Toby's Jukebox
==============

(c) 2010 Toby Dacre
toby.junk@gmail.com
GPL2
Python 2.x

About
-----

This is my personal jukebox program

The aim of this project is to simply manage a music library
that is arranged into directories that fit the general pattern
of ARTIST_NAME/ALBUM_NAME/album_files. The album files should
be of some variation of "TRACK_NUMBER TITLE.ext' . If an image
file is found in the directory it will be used as album art.
For albums with various artists they are expected to be in
Various/ALBUM_NAME/album_files where the tracks are named
'TRACK_NUMBER ARTIST_NAME TITLE.ext'.

The jukebox can run in both a graphical or text based mode.
The graphical mode version also contains a 'child lock' mode
which needs to be documented. It picks random songs if the
playlist is empty.

Required Python Modules
-----------------------

    sqlalchemy
    PIL (python image library)
    mutagen.flac
    mutagen.easyid3
    mutagen.id3
    mutagen.mp3
    gobject
    gst
    pygtk (graphical mode only)
    gtk (graphical mode only)
    pango (graphical mode only)

Other Requirements
------------------

    gstreamer
    gstreamer-plugins (for the audio files you wish to play)

General usage
-------------

    python jukebox.py --find DIRECTORY  # find files in the given directory
    python jukebox.py --text  # run in text mode
    python jukebox.py --graphical  # run in graphical mode
    python jukebox.py --clear  # clear database

Text Mode
---------

    Keys

    Tab - change selected panel
    1 - select playlist panel
    2 - select artists panel
    3 - select albums panel
    4 - select songs panel
    > - skip current song
    + - volume up
    - - volume down
    0 - toggle mute
    up/down/page up/page down/home/end - move between items
    Esc - quit

    Playlist panel
    d - delete track from playlist
    shift up - move track up the playlist
    shift down - move track down the playlist

    Artist / Albums / Songs panels
    a-z - move to items starting with that letter
    # - move to items starting with a number or special character
    / - enter leave search mode

    Tracks panel
    Return - add track to playlist

    Albums panel
    Return - add whole album


Graphical Mode
--------------

    In graphical mode most actions can be carried out with the mouse.

    left arrow - move backwards through albums
    right arrow - move forwards through albums

    Admin Mode
    ----------

    To enter admin mode you need to press and hold the Control Key
    whilst typing the password - default password fish

    Keys

    Control q - quit admin mode
    Control / - show if in admin mode
    Control b - bonus track can add even if the playlist is full
    Control s - skip track
    Control f - toggle full screen
    Control l - toggle playlist limit
    Control c - clear any songs past length of currently allowed playlist
    control n - before pressing type a number between 1 and 99 (holding control)
                to set this as the new playlist length
    control d - delete item from playlist give number first as for option n