| blob | 714c4a86f5e30a3c4d3a93df3f0ab780503a39cb |
1 .TH "shell-fm" 1
2 .SH NAME
3 Shell.FM \- Lightweight, console-based player for Last.FM radio streams.
4 .SH SYNOPSIS
5 .B shell-fm
6 [-d] [-i address] [-p port] [-b] [-D device] [-y proxy] [-h] lastfm://...
7 .SH DESCRIPTION
8 Shell.FM is a lightweight, console-based player for radio streams provided by
9 Last.FM.
10 .SH OPTIONS
11 .TP
12 .B \-d
13 Fork to background (requires a socket interface to be set up so it can still be
14 controlled somehow).
15 .TP
16 .B \-i <address>
17 Enable the socket interface and bind it to the given host address (should be
18 the host name or IP address of the host shell-fm is running on).
19 .TP
20 .B \-p <port>
21 Make the socket interface listen for incoming connections on the given port.
22 Default is 54311.
23 .TP
24 .B \-b
25 Enable batch mode (some freaky mode that makes shell-fm easier to handle from
26 inside emacs). This was not my idea.
27 .TP
28 .B \-D <device>
29 Use the given device file as audio device. This is only used if libao support
30 is disabled. Default is /dev/audio.
31 .TP
32 .B \-y <proxy>
33 Make shell-fm use the given host as proxy server for HTTP requests.
34 .TP
35 .B \-h
36 Print help text and exit.
37 .TP
38 .B lastfm://...
39 URI of a Last.FM radio stream to play after startup.
40 For example: `shell-fm -d lastfm://artist/The%20Beatles/similarartists'
41 .SH USAGE
42 On startup, shell-fm will ask you for your Last.FM login and password
43 (if not
44 provided in your ~/.shell-fm/shell-fm.rc). If you've given a stream URI on the
45 command line or there is a default radio defined in the configuration file,
46 shell-fm will now try to play it. When the startup is done, there are lots of
47 keys to control shell-fm. Here is a alphabetically sorted list.
48 .TP
49 .B a
50 Add the currently played track to your Last.FM playlist.
51 .TP
52 .B A
53 Ban the artist of the currently played track. Whenever a track of that artist
54 is played from now on, it is automatically banned.
55 .TP
56 .B B
57 Ban the currently played track.
58 .TP
59 .B d
60 Enabled/disable discovery mode. I'm not sure if this has any effect, and it
61 looks like even the Last.FM guys don't really know what it does, but I think it
62 is meant to ensure that you get only tracks that you don't know yet.
63 .TP
64 .B f
65 Jump to the fan radio station of the artist of the currently played track.
66 .TP
67 .B h
68 List bookmarks.
69 .TP
70 .B H
71 Bookmark the currently played radio station. You'll be asked to hit a digit
72 key. Whenever you hit that key again from now on, shell-fm will jump to that
73 radio station.
74 .TP
75 .B i
76 Print some more information about the currently played track.
77 .TP
78 .B l
79 Love the currently played track.
80 .TP
81 .B n
82 Skip the currently played track.
83 .TP
84 .B p
85 Pause. If you pause too long, the stream will break, which has the same effect
86 as stopping the stream (see below).
87 .TP
88 .B P
89 Enable/disable reporting played tracks to your Last.FM profile. Enabled by default.
90 .TP
91 .B Q
92 Quit.
93 .TP
94 .B r
95 Change radio station. This will prompt you for an Last.FM radio station URI.
96 The tabulator key helps if you don't know what to type. Arrow-Up and Arrow-Down
97 allow you to browse your radio history. Enter these without the
98 "lastfm://" prefix.
99 .RS
100 .PP
101 For example: `radio url> globaltags/world'
102 .RE
103 .TP
104 .B R
105 Recommend the currently played track/artist/album to another Last.FM user.
106 .TP
107 .B S
108 Stop playing.
109 .TP
110 .B s
111 Jump to the similar artists radio stream of the currently played tracks artist.
112 .TP
113 .B T
114 Tag the currently played track/artist/album. Tabulator key completes known
115 tags.
116 .TP
117 .B +
118 Increase volume.
119 .TP
120 .B -
121 Decrease volume.
122 .PP
123 .SH SETUP
124 Before you start, you should have created the directories
125 .B ~/.shell-fm
126 and
127 .B ~/.shell-fm/cache
128 or you will get a lot of warnings, the tab-completion will be extremely
129 slow and you can't make use of some features (auto-ban, history, bookmarks).
130 You might also want to place a configuration file in
131 .B ~/.shell-fm
132 for a faster startup.
133 .SH CONFIGURATION
134 This section describes the syntax and options for the shell-fm configuration
135 file. The file should be placed in
136 .B ~/.shell-fm/shell-fm.rc
137 and should consist of simple
138 .B key = value
139 assignments.
140 See (far) below for a sample configuration. These are the available options.
141 .TP
142 .B username = your-login
143 This is your login on Last.FM. If this is provided, shell-fm won't ask you for
144 it on startup anymore.
145 .TP
146 .B password = your-password
147 This is your (clear text) Last.FM password. If this and your login is provided
148 in the configuration, shell-fm won't ask you on startup.
149 .TP
150 .B default-radio = lastfm://...
151 If this is provided (and valid), shell-fm will play this station by default
152 after startup. If there's another station URI given on the command line, it
153 will override this setting.
154 .TP
155 .B np-file = path-to-file
156 If this is defined, shell-fm will print information about the currently played
157 track into the given file, whenever a new track is played.
158 .TP
159 .B np-file-format = format-string
160 This defines how the information written to your now-playing file will look
161 like. There are several format flags available. Have a look at the
162 .B FORMAT FLAGS
163 section for the details.
164 .TP
165 .B np-cmd = shell command
166 If this is defined, the given command will be execute whenever a new track
167 starts. The value may contain format flags.
168 .TP
169 .B pp-cmd = shell command
170 If this is defined, the given command will be execute whenever a downloading
171 track ends. The value will have the path to the file appended.
172 .TP
173 .B ?-color = color
174 This allows you to color format elements. The
175 .B ?
176 may be the letter of any format flag (without percent). The color is just a
177 normal shell color code matching "[01];3[0-7]". Whenever the format element is
178 printed to the console, it will have the given color. Have a look at the
179 .TP
180 .B daemon = something
181 If this is set to something, shell-fm will start in daemon mode by default.
182 Starting with -d as command line option will disable daemon mode.
183 .TP
184 .B COLORS
185 section for a list.
186 .TP
187 .B key0x?? = shell command
188 This allows you to bind shell commands to free keys (keys that are not used by
189 shell-fm, check the
190 .B USAGE
191 section above for a list).
192 .B ??
193 should be the hex code of the ASCII code of the key. The command you assign
194 will be evaluated (check the
195 .B FORMAT FLAGS
196 section) and executed then. This "feature" allows you to implement own
197 features, like fetching and printing the lyrics of the currently played track,
198 etc. If you have a cool idea or even a working script, I'd be happy if you let
199 me know.
200 .TP
201 .B bind = host
202 This specifies the network interface you want shell-fm to bind to.
203 .B host
204 should be the host name or an IP address of host shell-fm is running on.
205 shell-fm will open a port (see the
206 .B port
207 option below) on the specified interface which you can connect to to control
208 shell-fm remotely (or from local scripts, see
209 .B key0x??
210 above). Check the
211 .B NETWORK INTERFACE COMMANDS
212 section below for a list of known commands.
213 .TP
214 .B port = port-number
215 With this option you can change the port shell-fm will listen on (if
216 .B bind
217 is specified). Default is 54311.
218 .TP
219 .B extern = shell command
220 This allows you to specify an external program or script as player for the
221 streams. If given, shell-fm will run the command and pipe the MP3 stream into
222 it, instead of playing the stream itself. For example,
223 .B extern = madplay -Q -
224 works very fine. This option is meant as a work-around for architectures that
225 shell-fm doesn't work completly profectly on.
226 .TP
227 .B proxy = proxy server
228 This allows you to specify a proxy server for the HTTP requests.
229 .TP
230 .B expiry = some-number
231 This defines the number of seconds until a cached page expires. The default is
232 86400 seconds (24 hours). You shouldn't set a very low value here, since the
233 Last.FM server often are very slow. This mostly affects the prompts (radio
234 prompt, tag prompt, ...), since shell-fm fetches some feeds to get values for
235 the tab-completion.
236 .TP
237 .B device = path
238 Path to the audio device to use (see
239 .B -D
240 command line option).
241 .TP
242 .B title-format = format-string
243 This is the format of the track string that is printed to the console for every
244 track played. Default is 'Now playing "%t" by %a.'.
245 .TP
246 .B minimum = percentage
247 With this option you can change the minimum duration a track must have been
248 played to be scrobbled (in percent, but without the % sign). For example, if
249 this option is set to 75, the track will not be scrobbled if it has not been
250 played for at least 75% of its total duration. If you skip or stop the track
251 before it has been played for 75%, it will not be scrobbled. Default is 50%, as
252 specified in the scrobbling protocol version 1.2.
253 .TP
254 .B delay-change = something
255 If this is set to anything, and you change the station with 'r', 's' or 'f',
256 the station-change will be delayed until the currently played track finishes or
257 is skipped. Also they key 'q' will initialize a delayed quit, so after the
258 currently played track shell-fm will exit. 'Q' (uppercase) still quits
259 immediately.
260 .TP
261 .B screen-format = format-string
262 If this is set, shell-fm will check if the terminal it's running in is a screen
263 session ($TERM is "screen") and set the screen windows title to the formatted
264 string to be seen on $ESCAPE+w or $ESCAPE+".
265 .TP
266 .B term-format = format-string
267 Works like screen-format, but sets the x-terminals window title.
268 .TP
269 .B download = format-string
270 If this is set to a valid path (may contain format flags), and the played track
271 is free, it is saved at the given place.
272 .TP
273 .B gap = seconds
274 If this is set to a number, shell-fm will wait that amount of seconds between
275 tracks.
276 .TP
277 .B discovery = something
278 Enable discovery mode by default.
279 .SH FORMAT FLAGS
280 There are several format flags allowed for some options. Here is the list.
281 .TP
282 .B %a
283 Artist name.
284 .TP
285 .B %t
286 Track title.
287 .TP
288 .B %l
289 Album name.
290 .TP
291 .B %d
292 Track duration in seconds.
293 .TP
294 .B %s
295 Station name.
296 .TP
297 .B %S
298 Station URL.
299 .TP
300 .B %A
301 URL of the artists page on Last.FM.
302 .TP
303 .B %L
304 URL of the albums page on Last.FM.
305 .TP
306 .B %T
307 URL of the tracks page on Last.FM.
308 .TP
309 .B %R
310 Remaining seconds of the played track.
311 .TP
312 .B %%
313 A %.
314 .SH COLORS
315 .TP
316 .B 0;30
317 Black (not very useful).
318 .TP
319 .B 1;30
320 Dark gray.
321 .TP
322 .B 0;31
323 Red.
324 .TP
325 .B 1;31
326 Light red.
327 .TP
328 .B 0;32
329 Green.
330 .TP
331 .B 1;32
332 Light green.
333 .TP
334 .B 0;33
335 Dark yellow/brown.
336 .TP
337 .B 1;33
338 Yellow.
339 .TP
340 .B 0;34
341 Blue.
342 .TP
343 .B 1;34
344 Light blue.
345 .TP
346 .B 0;35
347 Violet.
348 .TP
349 .B 1;35
350 Pink.
351 .TP
352 .B 0;36
353 Turquoise.
354 .TP
355 .B 1;36
356 Cyan.
357 .TP
358 .B 0;37
359 Gray.
360 .TP
361 .B 1;37
362 White.
363 .SH NETWORK INTERFACE COMMANDS
364 This section describes the commands shell-fm's network interface knows. To use
365 the interface, you must provide a valid value to the
366 .B bind
367 option in your configuration or use the
368 .B -i
369 option on the command line. Then you can connect the specified port (54311 by
370 default) and send one command at a time. You also have to hurry,
371 since there is a very short timeout. Best thing would be if you used a script
372 for accessing this interface. (See
373 .B shell-fm-*/scripts/
374 for examples) This is a list of the known commands.
375 .TP
376 .B play lastfm://...
377 Play the given stream.
378 .TP
379 .B love
380 Love the currently played track.
381 .TP
382 .B ban
383 Ban the currently played track.
384 .TP
385 .B skip
386 Skip the currently played track.
387 .TP
388 .B quit
389 Quit.
390 .TP
391 .B info some-format-string
392 Evaluate the given format string (check the
393 .B FORMAT FLAGS
394 section) and return the formatted information.
395 .TP
396 .B pause
397 Pause.
398 .TP
399 .B discovery
400 Toggle discovery mode on/off.
401 .TP
402 .B tag-artist some-comma-separated-tags
403 Tag the artist of the currently played track.
404 .TP
405 .B tag-album some-comma-separated-tags
406 Tag the album of the currently played track.
407 .TP
408 .B tag-track some-comma-separated-tags
409 Tag the currently played track.
410 .TP
411 .B artist-tags
412 Returns the tags of the currently played tracks artist.
413 .TP
414 .B album-tags
415 Returns the tags of the currently played tracks album.
416 .TP
417 .B track-tags
418 Returns the tags of the currently played track.
419 .TP
420 .B stop
421 Stop stream.
422 .SH FILES
423 This section describes the meanings of the files in $HOME/.shell-fm/. The base
424 directory can be overriden by setting the environment variable $SHELL_FM_HOME
425 to another directory.
426 .TP
427 .B autoban
428 This file contains the auto-banned artists.
429 .TP
430 .B bookmarks
431 This file contains the bookmarked stations in the format "[digit] = [url]".
432 .TP
433 .B cache/
434 This directory contains cached sites fetched from Last.FM for faster tab-completion etc.
435 .TP
436 .B i-template
437 If this file exists, it will be used as a template for the output of 'i'. It
438 may contain usual format flags.
439 .TP
440 .B radio-history
441 The radio stations you have listened to. The history is used for the radio prompt.
442 .TP
443 .B scrobble-cache
444 If Shell.FM can't scrobble the data of a track for any reason before you quit,
445 it stores the track data in here and it will try to submit the tracks the next
446 time it is run.
447 .TP
448 .B shell-fm.rc
449 Your configuration file as described above.
450 .SH EXAMPLES
451 .TP
452 .B Sample Configuration for shell-fm.rc
453 .PP
454 .RS
455 .nf
456 # shell-fm.rc example
457 username = shellfmlover
458 password = CheckFileIsOnlyReadableByOwner
459 default-radio = lastfm://user/shellfmlover/playlist
460 np-file = /home/shellfmlover/.shell-fm/nowplaying
461 np-file-format = %t:%a:%S:%A
462 minimum = 80
463 delay-change = true
464 .fi
465 .RE
466 .TP
467 .B shell-fm-*.*/scripts/
468 Includes examples of using the network interface plus a color printing script to help with choosing colors.
469 .TP
470 .B URL FORMAT
471 .PP
472 .RS
473 .nf
474 lastfm://user/$USER/loved
475 lastfm://user/$USER/personal
476 lastfm://usertags/$USER/$TAG
477 lastfm://artist/$ARTIST/similarartists
478 lastfm://artist/$ARTIST/fans
479 lastfm://globaltags/$TAG
480 lastfm://user/$USER/recommended
481 lastfm://user/$USER/playlist
482 .fi
483 .SH BUGS
484 No bugs known at the moment. Please send bug reports to <shell-fm@nex.scrapping.cc>.
485 .SH COPYRIGHT
486 Copyright (C) 2006-2009 by Jonas Kramer.
487 Published under the terms of the GNU General Public License.