.\" .\" $Id$ .\" .Dd December 15, 2006 .Dt SHELL-FM 1 .Os .Sh NAME .Nm shell-fm .Nd command-line Last.FM client .Sh SYNOPSIS .Nm shell-fm .Op Fl d .Op Fl i Ar address to listen on .Op Fl p Ar port to listen on .Op Fl D Ar device to play on .Op Fl y Ar http://proxy-server .Op Fl h .Op lastfm://... .Sh DESCRIPTION .Nm shell-fm is a console based player for the streams provided by Last.FM. It's lightweight, easy to use and under heavy development. New features might be added every day. .Nm shell-fm is Open Source and published under the terms of the GNU General Public License, so feel free to modify and/or redistribute it. .Sh RUNNINF SHELL-FM Usage of .Nm shell-fm is pretty simple. To tell .Nm shell-fm what to play, you simply give it the direct link to a Last.FM stream (a URL starting with lastfm://). The URLs are very clear and easy to understand. Here are some examples: .Pp .nf lastfm://user/shell-monkey/personal - my personal radio lastfm://user/shell-monkey/loved - my loved tracks radio lastfm://artist/Blood For Blood/similar - bands similar to Blood For Blood lastfm://artist/The Distillers/fans - The Distillers fan radio lastfm://globaltags/punk rock - songs that have been tagged as "punk rock" .fi .Pp Radios can be specified in three ways. First you can give a stream URL as command line argument to .Nm shell-fm : .Pp [~]$ shell-fm "lastfm://artist/The Distillers/fans" .Pp Note that you need to quote the URL, if it contains white spaces. .br Next you can enter a new URL while .Nm shell-fm is already running by pressing the r key. .Nm shell-fm then will prompt you for a new URL. Note that you don't need / may not quote the URL here like in the command line. .Nm shell-fm will take care of whitespaces for you. Finally, you can name a default stream in your configuration file, which is started by default if you run .Nm shell-fm without an URL as command line argument. .Sh CONFIGURATION Your configuration should be placed in the file ~/.shell-fm/shell-fm.rc. It consists of simple associations in the format key = value. Following keys are known at the moment (may/will be more in future). .br .nf username = YourLogin - your Last.FM username. password = YourPass - your Last.FM password. np-file = /path/to/np-file - the (absolute) path to a file in which you want shell-fm to save information about the currently played track in. np-file-format = format - the format in which shell-fm will write the song information to your np-file. Note that both, np-file and np-file-format need to be specified to make shell-fm write to the np-file. The format may contain any character plus some placeholders shell-fm will replace. They are: %a - artist %t - track %A - album %d - track duration %s - station name %u - station URL %U - artist URL %X - album URL %T - track URL %R - remaining seconds of the played track np-cmd = command - if defined, this command will be executed every time a new track is played. Accepts the sape format flast as np-file-format. default-radio = lastfm://.. - the default radio which shell-fm will play on startup if you called it without an command line argument. key0x?? = command - bind an external command to the key with the hexadecimal, UPPERCASE (!), zero-padded ASCII code "??". Keys that are already bound to an action (as listed here) can't be overwritten. Again, you can use all the variables as in "np-file-format" and "np-cmp". Please note that future versions may use further keys, so you might need to change your configuration then. ?-color = color-code - (where ? is one of the meta tag variables (see list above). This allows you to color every kind of tag with a different color (e.g. paint track titles red, artists green and so on). This is the list of valid color codes: 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 bind = ip/host - binds a socket to the given host so you can send simple commands to Shell.FM over a network to control it. For now, only the most common commands are supported: "skip", "love", "ban", "quit", "play" and "info". "play" takes a radio statio URI as paramater. "info" takes a format string as parameter (same as for np-file-format) and returns the string (formatted). port = 123 - if defined, the socket interface will be bound to this port instead of the default, 54311. extern = command - on some platforms, Shell.FM is still unable to play streams properly. This option enables you to use Shell.FM for stream control, but use another player for the playback. The stream will be written to STDIN of the external player. For example, extern = /usr/bin/madplay -Q - should work find on Mac OS X (if you have madplay installed). extern-restart = anything - if defined (no matter what value), Shell.FM will stop and restart the external player whenever the track changes. proxy = http://proxy-server - use proxy server for HTTP requests. expiry = 86400 - TTL of cached files in seconds. .fi .Pp This is what your configuration file for .Nm shell-fm could look like: .nf [~]$ cat ~/.shell-fm/shell-fm.rc username = shell-monkey password = secret default-radio = lastfm://user/shell-monkey/loved np-file = /tmp/np.txt np-file-format = %a - %t key0x6F = /usr/bin/elinks "%u" t-color = 1;32 a-color = 0;32 s-color = 1;37 [~]$ .fi .Sh CONTROLS These keys are available from within .Nm shell-fm to control it's behaviour: .br .nf l - love the currently played track. B - (uppercase!) ban the currently played track. n - skip the currently played track. Q - (uppercase!) quit. r - prompt for a new station URL. i - display some information about the currently played track. d - enable/disable discovery mode. A - ban the artist of the currently played track (whenever another track of this artist is streamed again, it will be banned automatically). R - recommend currently played track/artist/album to someone. f - jump to the currently played tracks artists fan radio. s - jump to the currently played tracks artists similar artists radio. H - bookmark the currently played stream. h - list bookmarks. [0-9] - jump to a previously bookmarked stream. p - pause (experimental - after a while the stream will be closed) S - stop playing T - tag the currently played track/artist/album. ? - show a list of available keys. .fi .br Note that the radio URL prompt provides a simple history (use up/down arrow keys to browse it). By default, .Nm Shell.FM will remember only the URLs you entered in the current session. If you want the history to survive, you need to create an empty file name ~/.shell-fm/radio-history. Simply touch(1) it and you're done. .Sh SEE ALSO http://nex.scrapping.cc/shell-fm/ .Sh CREDITS Read the AUTHORS file in the port's doc directory. .Sh AUTHOR Nikos Ntarmos