--- name: "shell-fm" section: "1" platform: "linux" package: "shell-fm" version: "0.7+git20100414-2" release: "Debian 8 (Jessie)" platforms: ["linux"] url: "https://new.carta.tech/shell-fm" --- # shell-fm(1) Lightweight, console-based player for Last.FM radio streams. ## 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 \** 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 \** 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 \** Use the given device file as audio device. This is only used if libao support is disabled. Default is /dev/audio. - **-y \** 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 \. ## COPYRIGHT Copyright (C) 2006-2010 by Jonas Kramer. Published under the terms of the GNU General Public License.