Provided by: shell-fm_0.7+git20100414-2_amd64 bug

NAME

       Shell.FM - Lightweight, console-based player for Last.FM radio streams.

SYNOPSIS

       shell-fm [-d] [-i address] [-p port] [-b] [-D device] [-y proxy] [-h] lastfm://...

DESCRIPTION

       Shell.FM is a lightweight, console-based player for radio streams provided by Last.FM.

OPTIONS

       -d     Fork  to  background  (requires  a socket interface to be set up so it can still be
              controlled somehow).

       -i <address>
              Enable the socket interface and bind it to the given host address  (should  be  the
              host name or IP address of the host shell-fm is running on).

       -p <port>
              Make  the  socket  interface  listen  for  incoming  connections on the given port.
              Default is 54311.

       -b     Enable batch mode (some freaky mode that  makes  shell-fm  easier  to  handle  from
              inside emacs). This was not my idea.

       -D <device>
              Use  the  given  device file as audio device. This is only used if libao support is
              disabled. Default is /dev/audio.

       -y <proxy>
              Make shell-fm use the given host as proxy server for HTTP requests.

       -h     Print help text and exit.

       lastfm://...
              URI of a Last.FM radio stream to play after startup.   For  example:  `shell-fm  -d
              lastfm://artist/The%20Beatles/similarartists'

USAGE

       On  startup, shell-fm will ask you for your Last.FM login and password (if not provided in
       your ~/.shell-fm/shell-fm.rc). If you've given a stream URI on the command line  or  there
       is  a  default  radio defined in the configuration file, shell-fm will now try to play it.
       When the startup is done,  there  are  lots  of  keys  to  control  shell-fm.  Here  is  a
       alphabetically sorted list.

       a      Add the currently played track to your Last.FM playlist.

       A      Ban  the  artist  of the currently played track. Whenever a track of that artist is
              played from now on, it is automatically banned.

       B      Ban the currently played track.

       d      Enabled/disable discovery mode. I'm not sure if this has any effect, and  it  looks
              like  even the Last.FM guys don't really know what it does, but I think it is meant
              to ensure that you get only tracks that you don't know yet.

       f      Jump to the fan radio station of the artist of the currently played track.

       h      List bookmarks.

       H      Bookmark the currently played radio station. You'll be asked to hit  a  digit  key.
              Whenever  you  hit  that  key  again  from now on, shell-fm will jump to that radio
              station.

       i      Print some more information about the currently played track.

       l      Love the currently played track.

       n      Skip the currently played track.

       p      Pause. If you pause too long, the stream will break, which has the same  effect  as
              stopping the stream (see below).

       P      Enable/disable reporting played tracks to your Last.FM profile. Enabled by default.

       Q      Quit.

       r      Change  radio  station. This will prompt you for an Last.FM radio station URI.  The
              tabulator key helps if you don't know what to type. Arrow-Up and  Arrow-Down  allow
              you to browse your radio history. Enter these without the "lastfm://" prefix.

              For example: `radio url> globaltags/world'

       R      Recommend the currently played track/artist/album to another Last.FM user.

       S      Stop playing.

       s      Jump to the similar artists radio stream of the currently played tracks artist.

       T      Tag the currently played track/artist/album. Tabulator key completes known tags.

       U      Unlove the currently played track.

       u      Print upcoming tracks in playlist.

       +      Increase volume.

       -      Decrease volume.

SETUP

       Before  you  start,  you  should  have  created  the directories ~/.shell-fm and ~/.shell-
       fm/cache or you will get a lot of warnings, the tab-completion will be extremely slow  and
       you  can't  make use of some features (auto-ban, history, bookmarks).  You might also want
       to place a configuration file in ~/.shell-fm for a faster startup.

CONFIGURATION

       This section describes the syntax and options for the  shell-fm  configuration  file.  The
       file  should be placed in ~/.shell-fm/shell-fm.rc and should consist of simple key = value
       assignments.  See (far) below for a sample configuration. These are the available options.

       username = your-login
              This is your login on Last.FM. If this is provided, shell-fm won't ask you  for  it
              on startup anymore.

       password = your-password
              This  is  your (clear text) Last.FM password. If this and your login is provided in
              the configuration, shell-fm won't ask you on startup.

       default-radio = lastfm://...
              If this is provided (and valid), shell-fm will play this station by  default  after
              startup. If there's another station URI given on the command line, it will override
              this setting.

       np-file = path-to-file
              If this is defined, shell-fm will print  information  about  the  currently  played
              track into the given file, whenever a new track is played.

       np-file-format = format-string
              This  defines  how the information written to your now-playing file will look like.
              There are several format flags available. Have a look at the

       preview-format = format-string
              Format of the track information in the playlist preview (key  'u').   FORMAT  FLAGS
              section for the details.

       np-cmd = shell command
              If  this is defined, the given command will be execute whenever a new track starts.
              The value may contain format flags.

       pp-cmd = shell command
              If this is defined, the given command will be execute whenever a downloading  track
              ends. The value will have the path to the file appended.

       ?-color = color
              This  allows  you  to color format elements. The ?  may be the letter of any format
              flag (without percent). The color is  just  a  normal  shell  color  code  matching
              "[01];3[0-7]".  Whenever the format element is printed to the console, it will have
              the given color. Have a look at the

       daemon = something
              If this is set to something,  shell-fm  will  start  in  daemon  mode  by  default.
              Starting with -d as command line option will disable daemon mode.

       COLORS section for a list.

       key0x?? = shell command
              This  allows  you  to  bind  shell commands to free keys (keys that are not used by
              shell-fm, check the USAGE section above for a list).  ??  should be the hex code of
              the  ASCII  code  of  the  key. The command you assign will be evaluated (check the
              FORMAT FLAGS section) and executed then. This "feature" allows you to implement own
              features, like fetching and printing the lyrics of the currently played track, etc.
              If you have a cool idea or even a working script, I'd be happy if you let me know.

       bind = host
              This specifies the network interface you want shell-fm to bind to.  host should  be
              the  host name or an IP address of host shell-fm is running on.  shell-fm will open
              a port (see the port option below) on the specified interface which you can connect
              to  to control shell-fm remotely (or from local scripts, see key0x??  above). Check
              the NETWORK INTERFACE COMMANDS section below for a list of known  commands.   NOTE:
              The  network  interface  has  no user authentication, so anyone with access to your
              network/host can control shell-fm. Use it only if you really need to control shell-
              fm over a network. Otherwise use the UNIX socket interface (see below).

       unix = path
              If  this  is  set  to a proper path, on that path a UNIX socket will be created for
              local "remote" control. This socket interface takes the same commands  as  the  TCP
              socket interface (see above).

       port = port-number
              With  this  option  you  can  change  the  port shell-fm will listen on (if bind is
              specified). Default is 54311.

       extern = shell command
              This allows you to specify an external program or script as player for the streams.
              If given, shell-fm will run the command and pipe the MP3 stream into it, instead of
              playing the stream itself. For example, extern = madplay -Q - works very fine. This
              option  is  meant  as  a  work-around  for architectures that shell-fm doesn't work
              completly profectly on.

       proxy = proxy server
              This allows you to specify a proxy server for the HTTP requests.

       expiry = some-number
              This defines the number of seconds until a cached  page  expires.  The  default  is
              86400  seconds  (24  hours).  You  shouldn't  set  a very low value here, since the
              Last.FM server often are very slow. This mostly affects the prompts (radio  prompt,
              tag  prompt,  ...),  since  shell-fm  fetches some feeds to get values for the tab-
              completion.

       device = path
              Path to the audio device to use (see -D command line option).

       title-format = format-string
              This is the format of the track string that is printed to  the  console  for  every
              track played. Default is 'Now playing "%t" by %a.'.

       minimum = percentage
              With  this option you can change the minimum duration a track must have been played
              to be scrobbled (in percent, but without the % sign). For example, if  this  option
              is  set  to  75,  the  track will not be scrobbled if it has not been played for at
              least 75% of its total duration. If you skip or stop the track before it  has  been
              played  for  75%,  it  will  not  be scrobbled. Default is 50%, as specified in the
              scrobbling protocol version 1.2.

       delay-change = something
              If this is set to anything, and you change the station with 'r', 's'  or  'f',  the
              station-change  will  be  delayed  until  the currently played track finishes or is
              skipped. Also they key 'q' will initialize a delayed quit, so after  the  currently
              played track shell-fm will exit. 'Q' (uppercase) still quits immediately.

       screen-format = format-string
              If  this  is  set,  shell-fm will check if the terminal it's running in is a screen
              session ($TERM is "screen") and set the  screen  windows  title  to  the  formatted
              string to be seen on $ESCAPE+w or $ESCAPE+".

       term-format = format-string
              Works like screen-format, but sets the x-terminals window title.

       download = format-string
              If  this is set to a valid path (may contain format flags), and the played track is
              free, it is saved at the given place.

       gap = seconds
              If this is set to a number, shell-fm will  wait  that  amount  of  seconds  between
              tracks.

       discovery = something
              Enable discovery mode by default.

       stream-timeout = seconds
              Users reported that in some regions in the world, Last.FM servers sometimes pretend
              to stream a track but then don't send anything, which makes shell-fm  hang  forever
              waiting  for  the track data. If you have that problem, use this option to define a
              stream timeout. When shell-fm is waiting for stream data, it will  wait  that  many
              seconds and then skip to the next track.

       no-rtp = something
              Start with RTP disabled.

FORMAT FLAGS

       There are several format flags allowed for some options. Here is the list.

       %a     Artist name.

       %t     Track title.

       %l     Album name.

       %d     Track duration in seconds.

       %s     Station name.

       %S     Station URL.

       %A     URL of the artists page on Last.FM.

       %L     URL of the albums page on Last.FM.

       %T     URL of the tracks page on Last.FM.

       %R     Remaining seconds of the played track.

       %%     A %.

COLORS

       0;30   Black (not very useful).

       1;30   Dark gray.

       0;31   Red.

       1;31   Light red.

       0;32   Green.

       1;32   Light green.

       0;33   Dark yellow/brown.

       1;33   Yellow.

       0;34   Blue.

       1;34   Light blue.

       0;35   Violet.

       1;35   Pink.

       0;36   Turquoise.

       1;36   Cyan.

       0;37   Gray.

       1;37   White.

NETWORK INTERFACE COMMANDS

       This  section  describes  the  commands  shell-fm's  network  interface  knows. To use the
       interface, you must provide a valid value to the bind option in your configuration or  use
       the  -i  option  on  the  command  line. Then you can connect the specified port (54311 by
       default) and send one command at a time. You also have to hurry, since  there  is  a  very
       short timeout. Best thing would be if you used a script for accessing this interface. (See
       shell-fm-*/scripts/ for examples) This is a list of the known commands.

       play lastfm://...
              Play the given stream.

       love   Love the currently played track.

       ban    Ban the currently played track.

       skip   Skip the currently played track.

       quit   Quit.

       info some-format-string
              Evaluate the given format string (check the FORMAT FLAGS section)  and  return  the
              formatted information.

       pause  Pause.

       discovery
              Toggle discovery mode on/off.

       tag-artist some-comma-separated-tags
              Tag the artist of the currently played track.

       tag-album some-comma-separated-tags
              Tag the album of the currently played track.

       tag-track some-comma-separated-tags
              Tag the currently played track.

       artist-tags
              Returns the tags of the currently played tracks artist.

       album-tags
              Returns the tags of the currently played tracks album.

       track-tags
              Returns the tags of the currently played track.

       stop   Stop stream.

FILES

       This  section  describes the meanings of the files in $HOME/.shell-fm/. The base directory
       can be overriden by setting the environment variable $SHELL_FM_HOME to another directory.

       autoban
              This file contains the auto-banned artists.

       bookmarks
              This file contains the bookmarked stations in the format "[digit] = [url]".

       cache/ This directory contains cached sites fetched from Last.FM for faster tab-completion
              etc.

       i-template
              If  this  file  exists, it will be used as a template for the output of 'i'. It may
              contain usual format flags.

       radio-history
              The radio stations you have listened to. The history is used for the radio prompt.

       scrobble-cache
              If Shell.FM can't scrobble the data of a track for any reason before you  quit,  it
              stores the track data in here and it will try to submit the tracks the next time it
              is run.

       shell-fm.rc
              Your configuration file as described above.

EXAMPLES

       Sample Configuration for shell-fm.rc

              # shell-fm.rc example
              username = shellfmlover
              password = CheckFileIsOnlyReadableByOwner
              default-radio = lastfm://user/shellfmlover/playlist
              np-file = /home/shellfmlover/.shell-fm/nowplaying
              np-file-format = %t:%a:%S:%A
              minimum = 80
              delay-change = true

       shell-fm-*.*/scripts/
              Includes examples of using the network interface plus a color  printing  script  to
              help with choosing colors.

       URL FORMAT

              lastfm://user/$USER/loved
              lastfm://user/$USER/personal
              lastfm://usertags/$USER/$TAG
              lastfm://artist/$ARTIST/similarartists
              lastfm://globaltags/$TAG
              lastfm://user/$USER/recommended
              lastfm://user/$USER/playlist
              lastfm://tag/$TAG1*$TAG2*$TAG3

BUGS

       Please send bug reports to <shell-fm@nex.scrapping.cc>.

COPYRIGHT

       Copyright  (C)  2006-2010  by  Jonas Kramer.  Published under the terms of the GNU General
       Public License.

                                                                                      shell-fm(1)