path: root/contrib/pianobar.1

.TH pianobar 1

.SH NAME
pianobar \- console pandora.com music player

.SH SYNOPSIS
.B pianobar

.SH DESCRIPTION
.B pianobar
is a lightweight console music player for the personalized online radio
pandora.com.

.SH FILES
.I $XDG_CONFIG_HOME/pianobar/config
or
.I ~/.config/pianobar/config
.RS
Per-user configuration file. See
.B CONFIGURATION.
.RE

.I /etc/libao.conf
or
.I ~/.libao
.RS
Global/per-user audio output configuration. See libao documentation at
http://xiph.org/ao/doc/config.html
.RE

.SH CONFIGURATION
The configuration file consists of simple
.B key = value
lines. Each terminated with a newline (\\n) character. Keys and values are both
case sensitive.

act_* keys control 
.B pianobar's
key-bindings. Every one-byte character except for \\x00 and the
special value
.B disabled
are allowed here.

.TP
.B act_help = ?
Show keybindings.

.TP
.B act_songlove = +
Love currently played song.

.TP
.B act_songban = -
Ban current track. It will not be played again and can only removed using the
pandora.com web interface.

.TP
.B act_stationaddmusic = a
Add more music to current station. You will be asked for a search string. Just
follow the instructions. If you're clueless try '?' (without quotes).

.TP
.B act_bookmark = b
Bookmark current song or artist.

.TP
.B act_stationcreate = c
Create new station. You have to enter a search string and select the song or
artist of your choice.

.TP
.B act_stationdelete = d
Delete current station.

.TP
.B act_songexplain = e
Explain why this song is played.

.TP
.B act_stationaddbygenre = g
Add genre station provided by pandora.

.TP
.B act_history = h
Show history.

.TP
.B act_songinfo = i
Print information about currently played song/station.

.TP
.B act_addshared = j
Add shared station by id. id is a very long integer without "sh" at the
beginning.

.TP
.B act_managestation = =
Delete artist/song seeds or feedback.

.TP
.B act_songmove = m
Move current song to another station

.TP
.B act_songnext = n
Skip current song.

.TP
.B act_songpause = p
Pause/Continue

.TP
.B act_quit = q
Quit
.B pianobar.

.TP
.B act_stationrename = r
Rename currently played station.

.TP
.B act_stationchange = s
Select another station. The station list can be filtered like most lists by
entering a search string instead of a station number.

.TP
.B act_songtired = t
Ban song for one month.

.TP
.B act_upcoming = u
Show next songs in playlist.

.TP
.B act_stationselectquickmix = x
Select quickmix stations. You can toggle the selection with 't', select all
with 'a' or select none with 'n'.

.TP
.B act_voldown = (
Decrease volume.

.TP
.B act_volup = )
Increase volume.

.TP
.B at_icon =  @ 
Replacement for %@ in station format string. It's " @ " by default.

.TP
.B audio_format = {aacplus,mp3,mp3-hifi}
Select audio format. aacplus is default if both libraries (faad, mad) are
available. mp3-hifi is available for Pandora One customers only.

.TP
.B autostart_station = stationid
Play this station when starting up. You can get the
.B stationid
by pressing
.B i
or the key you defined in
.B act_songinfo.

.TP
.B ban_icon = </3
Icon for banned songs.

.TP
.B control_proxy = http://user:password@host:port/
Non-american users need a proxy to use pandora.com. Only the xmlrpc interface
will use this proxy. The music is streamed directly.

.TP
.B event_command = path
File that is executed when event occurs. See section
.B EVENTCMD

.TP
.B fifo = /home/user/.config/pianobar/ctl
Location of control fifo. Defaults to $XDG_CONFIG_HOME/pianobar/ctl (which is
usually the value above). See section
.B REMOTE CONTROL

.TP
.B format_list_song = %i) %a - %t%r
Available format characters:

.B %i
Song number

.B %a
Song artist

.B %t
Song title

.B %r
Rating icon

.TP
.B format_msg_none = %s
.TQ
.B format_msg_info = (i) %s
.TQ
.B format_msg_nowplaying = |>  %s
.TQ
.B format_msg_time = #   %s
.TQ
.B format_msg_err = /!\\\\ %s
.TQ
.B format_msg_question = [?] %s
.TQ
.B format_msg_list = \\t%s
Message format strings.
.B %s
is replaced with the actual message.

.TP
.B format_nowplaying_song = \[dq]%t\[dq] by \[dq]%a\[dq] on \[dq]%l\[dq]%r%@%s
Now playing song message format. Available format characters are:

.B %t
Song title

.B %a
Song artist

.B %l
Album name

.B %r
Rating icon (only love icon)

.B %@
.B at_icon
if station is quickmix, empty otherwise.

.B %s
Real station name if quickmix

.B %u
Song detail url

.TP
.B format_nowplaying_station = Station \[dq]%n\[dq] (%i)
Now playing station format. Available format characters are:

.B %n
Station name

.B %i
Station id

.TP
.B history = 5
Keep a history of the last n songs (5, by default). You can rate these songs.

.TP
.B love_icon = <3
Icon for loved songs.

.TP
.B password = plaintext_password
Your pandora.com password. Plain-text.

.TP
.B proxy = http://user:password@host:port/
Use a http proxy. Note that this setting overrides the http_proxy environment
variable. Only "Basic" http authentication is supported.

.TP
.B sort = {name_az, name_za, quickmix_01_name_az, quickmix_01_name_za, quickmix_10_name_az, quickmix_10_name_za}
Sort station list by name or type (is quickmix) and name. name_az for example
sorts by name from a to z, quickmix_01_name_za by type (quickmix at the
bottom) and name from z to a.

.TP
.B user = your@user.name
Your pandora.com username.

.TP
.B volume = 0
Initial volume correction in dB. Usually between -30 and +5.

.SH REMOTE CONTROL
.B pianobar
can be controlled through a fifo. You have to create it yourself by executing

 mkfifo ~/.config/pianobar/ctl

Adjust the path if you set up a $XDG_CONFIG_HOME or changed the fifo setting.
Afterwards you can write commands directly into the fifo. Example (next song):

 echo -n 'n' > ~/.config/pianobar/ctl

.B n
is the keybinding for "next song". If you customized your keybindings you have to use these characters to control
.B pianobar.
.I This behaviour may change in the future!

Another example:

 while true; do;
    nc -l -p 12345 -s localhost localhost > ~/.config/pianobar/ctl;
    sleep 1;
 done

 echo -ne 'n\\x1a' | nc -q 0 127.0.0.1 12345

.SH EVENTCMD

.B pianobar
can report certain "events" to an external application (see
.B CONFIGURATION
). This application is started with the event name as it's first argument. More
information like error code and description, was well as song information
related to the current event, is supplied through stdin.

Currently supported events are: artistbookmark, songban, songbookmark,
songexplain, songfinish, songlove, songmove, songshelf, songstart,
stationaddmusic, stationaddshared, stationcreate, stationdelete,
stationdeleteartistseed, stationdeletefeedback, stationdeletesongseed,
stationfetchinfo, stationfetchplaylist, stationquickmixtoggle, stationrename,
userlogin, usergetstations

An example script can be found in the contrib/ directory of
.B pianobar's
source distribution.

.SH AUTHOR
Lars-Dominik Braun <lars@6xq.net>