diff -urNbB src/shell-fm.1.orig shell-fm/src/shell-fm.1 --- src/shell-fm.1.orig Thu Jan 1 02:00:00 1970 +++ src/shell-fm.1 Sat Dec 16 00:59:11 2006 @@ -0,0 +1,179 @@ +.\" +.\" $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 Ar daemon mode +.Op Fl i Ar address to listen on +.Op Fl W Ar port to listen on +.Op Fl D Ar device to play on +.Op Fl h +.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 - your Last.FM nick + password - your Last.FM password; if password and username or + only the password are missing here, shell-fm will + prompt you for it on startup. + default-radio - the default radio which shell-fm will play on startup + if you called it without an command line argument. + 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 - 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 - title + %A - album + %d - duration in seconds + %s - station name + %u - station URL + %U - artist URL + %T - track URL +.fi +.Pp +There may and will be more placeholders available in future releases. +.br +.nf + np-cmd - command that's executed whenever the track changes. Allows + the same format placeholders as the "np-file-format" + option. + key0x?? - 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 - (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 +.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 + r - prompt for a new station URL. + l - love the currently played track. + B - (uppercase!) ban the currently played track. + n - skip the currently played track. + Q - (uppercase!) quit. + 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 - toggle RTP on/off (RTP = record tracks to profile) + f - listen to the fan radio of the currently played tracks artist + s - listen to the similar-artists radio of the currently played + tracks artist +.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 +Jonas Kramer wrote the actual code. +.Sh AUTHOR +Nikos Ntarmos --- src/Makefile.am.orig Sat Dec 16 04:37:00 2006 +++ src/Makefile.am Sat Dec 16 04:37:59 2006 @@ -26,5 +26,7 @@ tag.c \ utility.c +man_MANS = shell-fm.1 +EXTRA_DIST = ${man_MANS} ## vim: noet ts=8 sw=8