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)