manual/shell-fm.1

   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 U
 118 Unlove the currently played track.
 119 .TP
 120 .B u
 121 Print upcoming tracks in playlist.
 122 .TP
 123 .B +
 124 Increase volume.
 125 .TP
 126 .B -
 127 Decrease volume.
 128 .TP
 129 .B m
 130 Mute/unmute.
 131 .PP
 132 .SH SETUP
 133 Before you start, you should have created the directories
 134 .B ~/.shell-fm
 135 and
 136 .B ~/.shell-fm/cache
 137 or you will get a lot of warnings, the tab-completion will be extremely
 138 slow and you can't make use of some features (auto-ban, history, bookmarks).
 139 You might also want to place a configuration file in
 140 .B ~/.shell-fm
 141 for a faster startup.
 142 .SH CONFIGURATION
 143 This section describes the syntax and options for the shell-fm configuration
 144 file. The file should be placed in
 145 .B ~/.shell-fm/shell-fm.rc
 146 and should consist of simple
 147 .B key = value
 148 assignments.
 149 See (far) below for a sample configuration. These are the available options.
 150 .TP
 151 .B username = your-login
 152 This is your login on Last.FM. If this is provided, shell-fm won't ask you for
 153 it on startup anymore.
 154 .TP
 155 .B password = your-password
 156 This is your (clear text) Last.FM password. If this and your login is provided
 157 in the configuration, shell-fm won't ask you on startup.
 158 .TP
 159 .B default-radio = lastfm://...
 160 If this is provided (and valid), shell-fm will play this station by default
 161 after startup. If there's another station URI given on the command line, it
 162 will override this setting.
 163 .TP
 164 .B np-file = path-to-file
 165 If this is defined, shell-fm will print information about the currently played
 166 track into the given file, whenever a new track is played.
 167 .TP
 168 .B np-file-format = format-string
 169 This defines how the information written to your now-playing file will look
 170 like. There are several format flags available. Have a look at the
 171 .B FORMAT FLAGS
 172 section for the details.
 173 .TP
 174 .B preview-format = format-string
 175 Format of the track information in the playlist preview (key 'u').
 176 .TP
 177 .B np-cmd = shell command
 178 If this is defined, the given command will be executed whenever a new track
 179 starts. The value may contain format flags.
 180 .TP
 181 .B pp-cmd = shell command
 182 If this is defined, the given command will be executed whenever a downloading
 183 track ends. The value will have the path to the file appended.
 184 .TP
 185 .B rate-cmd = shell command
 186 If this is defined, the given command will be executed whenever a track is rated.
 187 The value may contain format flags, especially %V to get the actual rating.
 188 .TP
 189 .B ?-color = color
 190 This allows you to color format elements. The
 191 .B ?
 192 may be the letter of any format flag (without percent). The color is just a
 193 normal shell color code matching "[01];3[0-7]". Whenever the format element is
 194 printed to the console, it will have the given color. Have a look at the
 195 .B COLORS
 196 section for a list.
 197 .TP
 198 .B daemon = something
 199 If this is set to something, shell-fm will start in daemon mode by default.
 200 Starting with -d as command line option will disable daemon mode.
 201 .TP
 202 .B key0x?? = shell command
 203 This allows you to bind shell commands to free keys (keys that are not used by
 204 shell-fm, check the
 205 .B USAGE
 206 section above for a list).
 207 .B ??
 208 should be the hex code of the ASCII code of the key. The command you assign
 209 will be evaluated (check the
 210 .B FORMAT FLAGS
 211 section) and executed then. This "feature" allows you to implement own
 212 features, like fetching and printing the lyrics of the currently played track,
 213 etc. If you have a cool idea or even a working script, I'd be happy if you let
 214 me know.
 215 .TP
 216 .B bind = host
 217 This specifies the network interface you want shell-fm to bind to.
 218 .B host
 219 should be the host name or an IP address of host shell-fm is running on.
 220 shell-fm will open a port (see the
 221 .B port
 222 option below) on the specified interface which you can connect to to control
 223 shell-fm remotely (or from local scripts, see
 224 .B key0x??
 225 above). Check the
 226 .B NETWORK INTERFACE COMMANDS
 227 section below for a list of known commands.
 228 .B NOTE:
 229 The network interface has no user authentication, so anyone with access to your
 230 network/host can control shell-fm. Use it only if you really need to control
 231 shell-fm over a network. Otherwise use the UNIX socket interface (see below).
 232 .TP
 233 .B unix = path
 234 If this is set to a proper path, on that path a UNIX socket will be created for
 235 local "remote" control. This socket interface takes the same commands as the
 236 TCP socket interface (see above).
 237 .TP
 238 .B port = port-number
 239 With this option you can change the port shell-fm will listen on (if
 240 .B bind
 241 is specified). Default is 54311.
 242 .TP
 243 .B extern = shell command
 244 This allows you to specify an external program or script as player for the
 245 streams. If given, shell-fm will run the command and pipe the MP3 stream into
 246 it, instead of playing the stream itself. For example,
 247 .B extern = madplay -Q -
 248 works very fine. This option is meant as a work-around for architectures that
 249 shell-fm doesn't work completly profectly on.
 250 .TP
 251 .B proxy = proxy server
 252 This allows you to specify a proxy server for the HTTP requests.
 253 .TP
 254 .B expiry = some-number
 255 This defines the number of seconds until a cached page expires. The default is
 256 86400 seconds (24 hours). You shouldn't set a very low value here, since the
 257 Last.FM server often are very slow. This mostly affects the prompts (radio
 258 prompt, tag prompt, ...), since shell-fm fetches some feeds to get values for
 259 the tab-completion.
 260 .TP
 261 .B device = path
 262 Path to the audio device to use (see
 263 .B -D
 264 command line option).
 265 .TP
 266 .B title-format = format-string
 267 This is the format of the track string that is printed to the console for every
 268 track played. Default is 'Now playing "%t" by %a.'.
 269 .TP
 270 .B minimum = percentage
 271 With this option you can change the minimum duration a track must have been
 272 played to be scrobbled (in percent, but without the % sign). For example, if
 273 this option is set to 75, the track will not be scrobbled if it has not been
 274 played for at least 75% of its total duration. If you skip or stop the track
 275 before it has been played for 75%, it will not be scrobbled. Default is 50%, as
 276 specified in the scrobbling protocol version 1.2.
 277 .TP
 278 .B delay-change = something
 279 If this is set to anything, and you change the station with 'r', 's' or 'f',
 280 the station-change will be delayed until the currently played track finishes or
 281 is skipped. Also they key 'q' will initialize a delayed quit, so after the
 282 currently played track shell-fm will exit. 'Q' (uppercase) still quits
 283 immediately.
 284 .TP
 285 .B screen-format = format-string
 286 If this is set, shell-fm will check if the terminal it's running in is a screen
 287 session ($TERM is "screen") and set the screen windows title to the formatted
 288 string to be seen on $ESCAPE+w or $ESCAPE+".
 289 .TP
 290 .B term-format = format-string
 291 Works like screen-format, but sets the x-terminals window title.
 292 .TP
 293 .B download = format-string
 294 If this is set to a valid path (may contain format flags), and the played track
 295 is free, it is saved at the given place.
 296 .TP
 297 .B gap = seconds
 298 If this is set to a number, shell-fm will wait that amount of seconds between
 299 tracks.
 300 .TP
 301 .B discovery = something
 302 Enable discovery mode by default.
 303 .TP
 304 .B stream-timeout = seconds
 305 Users reported that in some regions in the world, Last.FM servers sometimes
 306 pretend to stream a track but then don't send anything, which makes shell-fm
 307 hang forever waiting for the track data. If you have that problem, use this
 308 option to define a stream timeout. When shell-fm is waiting for stream data, it
 309 will wait that many seconds and then skip to the next track.
 310 .TP
 311 .B no-rtp = something
 312 Start with RTP disabled.
 313 .SH FORMAT FLAGS
 314 There are several format flags allowed for some options. Here is the list.
 315 .TP
 316 .B %a
 317 Artist name.
 318 .TP
 319 .B %t
 320 Track title.
 321 .TP
 322 .B %l
 323 Album name.
 324 .TP
 325 .B %I
 326 URL of the album image.
 327 .TP
 328 .B %d
 329 Track duration in seconds.
 330 .TP
 331 .B %f
 332 Track duration formatted as 'min:sec'.
 333 .TP
 334 .B %s
 335 Station name.
 336 .TP
 337 .B %S
 338 Station URL.
 339 .TP
 340 .B %A
 341 URL of the artists page on Last.FM.
 342 .TP
 343 .B %L
 344 URL of the albums page on Last.FM.
 345 .TP
 346 .B %T
 347 URL of the tracks page on Last.FM.
 348 .TP
 349 .B %R
 350 Remaining seconds of the played track.
 351 .TP
 352 .B %r
 353 Remaining time of the played track, formatted as 'min:sec'.
 354 .TP
 355 .B %v
 356 Volume level, formatted as 'xx%'.
 357 .TP
 358 .B %V
 359 Rating of the current track
 360 ('L' loved, 'B' banned, 'S' skipped or empty).
 361 .TP
 362 .B %~
 363 Environment variable $HOME.
 364 .TP
 365 .B %%
 366 A %.
 367 .SH COLORS
 368 .TP
 369 .B 0;30
 370 Black (not very useful).
 371 .TP
 372 .B 1;30
 373 Dark gray.
 374 .TP
 375 .B 0;31
 376 Red.
 377 .TP
 378 .B 1;31
 379 Light red.
 380 .TP
 381 .B 0;32
 382 Green.
 383 .TP
 384 .B 1;32
 385 Light green.
 386 .TP
 387 .B 0;33
 388 Dark yellow/brown.
 389 .TP
 390 .B 1;33
 391 Yellow.
 392 .TP
 393 .B 0;34
 394 Blue.
 395 .TP
 396 .B 1;34
 397 Light blue.
 398 .TP
 399 .B 0;35
 400 Violet.
 401 .TP
 402 .B 1;35
 403 Pink.
 404 .TP
 405 .B 0;36
 406 Turquoise.
 407 .TP
 408 .B 1;36
 409 Cyan.
 410 .TP
 411 .B 0;37
 412 Gray.
 413 .TP
 414 .B 1;37
 415 White.
 416 .SH NETWORK INTERFACE COMMANDS
 417 This section describes the commands shell-fm's network interface knows. To use
 418 the interface, you must provide a valid value to the
 419 .B bind
 420 option in your configuration or use the
 421 .B -i
 422 option on the command line. Then you can connect the specified port (54311 by
 423 default) and send one command at a time.  This is a list of the known commands.
 424 .TP
 425 .B play lastfm://...
 426 Play the given stream.
 427 .TP
 428 .B love
 429 Love the currently played track.
 430 .TP
 431 .B ban
 432 Ban the currently played track.
 433 .TP
 434 .B skip
 435 Skip the currently played track.
 436 .TP
 437 .B quit
 438 Quit.
 439 .TP
 440 .B info some-format-string
 441 Evaluate the given format string (check the
 442 .B FORMAT FLAGS
 443 section) and return the formatted information.
 444 .TP
 445 .B pause
 446 Pause.
 447 .TP
 448 .B discovery
 449 Toggle discovery mode on/off.
 450 .TP
 451 .B rtp
 452 Toggle RTP (scrobbling) on/off. Returns "RTP ON" or "RTP OFF" to indicate status.
 453 .TP
 454 .B tag-artist some-comma-separated-tags
 455 Tag the artist of the currently played track.
 456 .TP
 457 .B tag-album some-comma-separated-tags
 458 Tag the album of the currently played track.
 459 .TP
 460 .B tag-track some-comma-separated-tags
 461 Tag the currently played track.
 462 .TP
 463 .B artist-tags
 464 Returns the tags of the currently played tracks artist.
 465 .TP
 466 .B album-tags
 467 Returns the tags of the currently played tracks album.
 468 .TP
 469 .B track-tags
 470 Returns the tags of the currently played track.
 471 .TP
 472 .B stop
 473 Stop stream.
 474 .TP
 475 .B volume-up
 476 Increment volume by 1.
 477 .TP
 478 .B volume-down
 479 Decrement volume by 1.
 480 .TP
 481 .B volume 32
 482 Set volume. Volume may be a number between 0 and 64.
 483 .TP
 484 .B volume %50
 485 Set percental volume. %50 is 32, %100 is 64 and so on.
 486 .TP
 487 .B volume [+-]10
 488 Adjust absolute volume. "volume +1" is the same as "volume-up" and "volume -1"
 489 is the same as "volume-down".
 490 All volumes return the absolute volume (0-64).
 491 .TP
 492 .B detach
 493 Detaches from the network interface. Use this to cleanly close your session.
 494 .SH FILES
 495 This section describes the meanings of the files in $HOME/.shell-fm/. The base
 496 directory can be overriden by setting the environment variable $SHELL_FM_HOME
 497 to another directory.
 498 .TP
 499 .B autoban
 500 This file contains the auto-banned artists.
 501 .TP
 502 .B bookmarks
 503 This file contains the bookmarked stations in the format "[digit] = [url]".
 504 .TP
 505 .B cache/
 506 This directory contains cached sites fetched from Last.FM for faster tab-completion etc.
 507 .TP
 508 .B i-template
 509 If this file exists, it will be used as a template for the output of 'i'. It
 510 may contain usual format flags.
 511 .TP
 512 .B radio-history
 513 The radio stations you have listened to. The history is used for the radio prompt.
 514 .TP
 515 .B scrobble-cache
 516 If Shell.FM can't scrobble the data of a track for any reason before you quit,
 517 it stores the track data in here and it will try to submit the tracks the next
 518 time it is run.
 519 .TP
 520 .B shell-fm.rc
 521 Your configuration file as described above.
 522 .SH EXAMPLES
 523 .TP
 524 .B  Sample Configuration for shell-fm.rc
 525 .PP
 526 .RS
 527 .nf
 528 # shell-fm.rc example
 529 username = shellfmlover
 530 password = CheckFileIsOnlyReadableByOwner
 531 default-radio = lastfm://user/shellfmlover/playlist
 532 np-file = /home/shellfmlover/.shell-fm/nowplaying
 533 np-file-format = %t:%a:%S:%A
 534 minimum = 80
 535 delay-change = true
 536 .fi
 537 .RE
 538 .TP
 539 .B shell-fm-*.*/scripts/
 540 Includes examples of using the network interface plus a color printing script to help with choosing colors.
 541 .TP
 542 .B URL FORMAT
 543 .PP
 544 .RS
 545 .nf
 546 lastfm://user/$USER/personal
 547 lastfm://user/$USER/mix
 548 lastfm://user/$USER/recommended
 549 lastfm://user/$USER/neighbours
 550 lastfm://user/$USER/friends
 551 lastfm://artist/$ARTIST/similarartists
 552 lastfm://artist/$ARTIST/fans
 553 lastfm://tag/$TAG1*$TAG2*$TAG3
 554 .fi
 555 .SH BUGS
 556 Please send bug reports to <shell-fm@nex.scrapping.cc>.
 557 .SH COPYRIGHT
 558 Copyright (C) 2006-2010 by Jonas Kramer.
 559 Published under the terms of the GNU General Public License.
 560