jukebox - play selected music continuously in random order


  jukebox [options] [--] [selector...]
    -h, --help            - Show the help message then exit
    -V, --version         - Show the version message then exit
    -d, --debug           - Print debug messages
    -a, --all             - Select everything (not just your favourites)
    -j, --strict          - Search for selectors only in "Jukebox" tags
    -m, --mandatory       - Search treating all selectors as mandatory
    -n, --list            - Just list matching tracks (don't play them)
    -x, --extra           - Show artist/album/title as well (implies -n)
    -e, --elide           - Suppress duplicate artist/albums (implies -x)
    -v, --withtags        - Include tags when listing tracks (implies -x)
    -s, --sequential      - Play tracks sequentially, then stop
    -c, --continuous      - Play continuously (even if -s)
    -i, --nouser          - No user interaction between tracks
    -g, --gap seconds     - Inter track gap (in seconds)
    -f, --playlist file   - Play tracks from a playlist file
    -r, --root dir[:dir]* - Override default music directory (/mnt/music:/mnt/spare)
    -t, --tocglob tocglob - Override default tocfile glob (00*.toc)
    -p, --player player   - Override default music players (wav=play,mp3=mpg321 -q,ogg=ogg123 -q,flac=flac -sdc % | play -t wav -)
    -u, --unlink          - Unlink playlist (see -f) after reading it
    -T, --tagstats        - List known selectors/categories/tags
    -P, --perl            - Perl junkie (perl re in search criteria)


jukebox plays selected music continuously in a random order. By default, jukebox only plays your favourite tracks (see below). If the -a option is supplied, any tracks might be played.

If selectors are supplied, jukebox plays matching tracks. For a track to match, it must:

  - match all of the selectors that start with '+',
  - match none of the selectors that start with '-', and
  - match at least one of the ordinary selectors.

Searches are case and accent insensitive. Phrases can be quoted with single or double quotes (courtesy of the shell).

jukebox searches tocfiles for selectors in:

  - "Artist:", "Title:" and "Jukebox:" (and any other) headers,
  - track titles, and
  - track specific "[Jukebox: ...]" tags.

Your favourite tracks are defined to be those that are tagged with your login name. The default selector is your login name.

The -j option causes jukebox to ignore artist names and album and track titles. The search for selectors only looks at ``Jukebox:'' headers and track specific ``Jukebox:'' tags. This searches for tracks by category rather than by name.

The -m option causes all selectors to be treated as mandatory. This has the same effect as adding a '+' character to the start of every selector that does not already start with a '+' or '-' character.

The -f option plays tracks listed in a playlist file rather than using selectors to search for tracks. The format of the playlist is one filename per line (just like the output of the -n option). The -u option causes this file to be deleted after it is read.

The -s option plays the selected tracks in order, and then stops. This can be used to play a single album. If only a single track is selected, then the -s option is assumed. Adding the -c option repeats the in order selection continuously rather than stopping. This can be used to drive the neighbours mad while you're on holiday.

After each track is played, the user is asked whether or not they wish to continue. If there is no answer within two seconds, jukebox continues with the next track. If the user enters 'n' quickly enough, jukebox will terminate. The -i option causes this interaction to be suppressed, so jukebox will continue until it is killed by external means. The -g option causes a pause between tracks.

The -n option just prints the selected tracks without playing them. The -x option adds the artist, album and track titles to this output. The -e option suppresses duplicate artists and album titles from this output (the fields are present but empty). This reduces network traffic. The -v option adds a field containing each track's jukebox tags. This is to aid remote robot clients that need more information for compiling playlists. The -e and -v options imply the -x option and the -x option implies the -n option.

The -t, -r and -p options override various default values. The argument to the -r option can contain a colon separated list of directories to select tracks from multiple places.

The -P option allows perl ``regular expressions'' in the search criteria.

The -T option lists all categories used in all tocfiles (after the ``Jukebox:'' header or in track specific ``[Jukebox: ...]'' tags). After each category there are four numbers:

  - the number of albums that match the category,
  - the number of individual tracks that explicitly match the category,
  - the total number of tracks that match (inherited or explicit), and
  - the number of selected tracks that match the criteria.

Here's an example set of jukebox tags but feel free to classify tracks however you see fit.

  rock rockabilly glam punk black metal thrash surf garage pub grunge seattle
  jazz ragtime bebop bigband swing boogiewoogie dixieland free acid funk jive
  blues delta stlouis louisiana chicago downhome gutbucket stomp prewar dirty
  reggae ska dub ragamuffin rap gansta pranks
  techno rave hiphop triphop trance club house dance eurotechno eurohouse
  eurodance tribal urban gogo gabber hi-nrg newbeat freestyle anime gfunk
  industrial breakbeat hardcore drill grindcore ghettotech biphop idm
  country western bluegrass americana texmex christian rodeo yodeling square
  honkytonk bakersfield outlaw queercore riotgrrl doowop
  pop britpop boyband girlband rnb bubblegum jpop synthpop skiffle anti twee
  alternative indie newage newwave darkwave fusion crossover nova gothic
  classical symphonies operas operettas arias cantatas fugues canons
  concertos chamber sonatas musique-concrete divas counter tenors oratorios
  madrigals motets serenades preludes waltzes ballet suites
  folk shanties filk ballad torchsong gospel ccm
  avantgarde primus booty chanson jam terror negerpunk polskpunk
  space cult psychedelic madchester shoegazing
  disco soul motown muzak crooners lounge barbershop karaoke
  childrens nursery rhymes lullabies holiday
  military march tattoo ballroom

  world european african asian indian australian pacific american
  usa english british canadian oz aboriginal celtic irish welsh
  french spanish portuguese italian german tibetan chinese japanese
  hawaiian cajun latin carribean andean brazillian cuban arabic
  egyptian pakistani hindustani continental goa algerian tuvan gypsy
  armenian azerbaijani greek iranian iraqi israeli kurdistani kyrgyztani
  lebanese turkish

  bossanova calypso candombe carnatic chacha conjunto corrido fado
  flamenco junkanoo mariachi merengue norteno ranchero rhumba salsa
  samba tango tejano vallenato zydeco taiko afrobeat afropop hi-life
  mquanga juju soukous township qawwali rai polka rebetiko gamelan
  zarzeula klezmer chazzanut

  male female vocal instrumental spoken poetry acappella chant choral
  acoustic electric electronic power ambient microtonal noise fractal

  tv radio movie theatre showtunes dancehall musical cabaret
  vaudeville broadway soundtracks themes

  string guitar piano brass woodwind drum bass percussion

  gregorian medieval romantic renaissance baroque contemporary
  traditional modern early late recent new progressive
  neo mod post retro revival

  solo duet trio quartet band choir orchestra

  north south east west central

  live studio

  20s 30s 40s 50s 60s 70s 80s 90s 00s

  awesome excellent good fair bad crap weird

  comedy novelty happy depressing disturbing death relaxing

  political protest class gender race war peace

  hard soft easy loud quiet fast slow hot cool smooth explicit

  driving cooking gardening meditating housework washingup party


When jukebox receives a SIGTERM signal, it sends a SIGTERM signal to any player processes and then exits. This stops the jukebox.

When jukebox receives a SIGUSR1 signal, it sends a SIGSTOP or SIGCONT signal to any player processes. This pauses and continues the current track.

When jukebox receives a SIGUSR2 signal, it sends a SIGTERM signal to any player processes. This skips to the next track.


Play your favourite tracks


List your favourite tracks

  jukebox -n

Create a playlist file of Eric Clapton tracks

  jukebox -n 'eric clapton' >

Play tracks from a playlist file

  jukebox -f - <

List all known tags and a histogram of their use

  jukebox -T -a

Play a single album in order, then stop

  jukebox -s +"janis joplin" +'cheap thrills'

Play a single song over and over and over again

  jukebox -c 'night and day'

Play female jazz singers of the 1940's (two versions)

  jukebox -j +female +vocal +jazz +40s
  jukebox -jm female vocal jazz 40s

Play anything but the Wiggles

  jukebox -- -wiggles


If there is a jukebox network server running, then it is impolite to use jukebox directly. Use jukeboxc (in command line or graphical mode) instead.


The long options are only available if the value of the juke_opts variable in /etc/jukebox.conf is ``long''. This is because the standard perl module, Getopt::Long, requires the presence of a ``--'' argument before any arguments that begin with ``+'' because it thinks they are options (unless $POSIXLY_CORRECT is set in the environment). Since it is expected that this program will receive many command line arguments that begin with ``+'', the default is to only handle single letter options via the Getopt::Std module. Note that, with either short or long options, ``--'' must be used whenever there are search terms that begin with ``-'' because these really do look like options.


  /etc/jukebox.conf - System wide configuration file
  ~/.jukeboxrc      - User specific configuration file


  rip(1), riptrack(1), mktoc(1), toc2names(1), toc2tags(1),
  cdr(1), cdrw(1), burn(1), burnw(1), cdbackup(1), mp3backup(1),
  jukebox(1), jukeboxc(1), jukeboxc.jar(1), jukeboxd(8),
  jukeboxd-init.d(8), jukebox.conf(5),


raf <>