Using GJay

1. What it Does

GJay generates playlists across a body of music such that the playlists sound good but surprise you. It wanders your collection and gathers information about each song -- the frequency "fingerprint" and beats per minute. You describe your music collection by ranking songs and assigning them a color. The color is arbitrary, and only has meaning to you.

GJay builds intelligent playlists using these characteristics. You can set how it starts and moves between songs, as well as the relative importance of various features. For example, I may want to start a playlist with "dark blue" songs and specify that BPM matching is my highest priority.

1.1. Analysis

BPM and frequency analysis are CPU intensive. It takes about 30 seconds on my 1Ghz Athlon machine to analyze a 4-minute MP3. After introducing GJay to your collection, it will analyze songs in the background.

1.2 Data Files

GJay stores all its data in the ".gjay" directory in your home directory. Most files are stored in XML, which you can figure out just by reading it. Note that strings are UTF-8 encoded and "." is used to denote a decimal.

Song data is never discarded unless the song file cannot be found. If you change your song base directory, old song data will stay around in ~/.gjay/data.xml -- it just won't be displayed or used.

2. Usage

USAGE: gjay [--help] [-hdvpux] [-l length] [-f filename] [-c color]
        --help, -h  :  Display this help message
        -d          :  Run as daemon
        -v          :  Run in verbose mode. -vv for lots more info
        -p          :  Generate a playlist

Playlist options:
        -u          :  Display list in m3u format
        -x          :  Use XMMS to play generated playlist
        -l length   :  Length of playlist, in minutes
	-f filename :  Start playlist at a given file
	-c color    :  Start playlist at color, either a hex value or by name.
                       To see all color options, just call -c

For example:

To launch GJay as a stand-alone application, just run:
```
gjay
```
To run GJay as a background daemon to finish song analysis:
```
gjay -d
```
With more detail (e.g. to see which song is being analyzed now):
```
gjay -dv
```
To generate a playlist from the command line:
```
gjay -p
```
To generate a playlist and then play it in XMMS:
```
gjay -px 
```
(gjay -p -x is OK, too)
To generate a playlist which is 120 minutes long, starting at a blue song, with full m3u data, and saved to "list.m3u":
```
gjay -p -l 120 -c blue -u > list.m3u
```
To generate a playlist starting at the song file "/mp3/hop/lamb/fear_of_fours/soft_mistake.mp3", which is 120 minutes long, and is played in xmms:
```
gjay -px -l 120 -f /mp3/hop/lamb/fear_of_fours/soft_mistake.mp3  
```

3. Stand-alone application

3.1 Organization

GJay uses a tabbed interface. There are four screens:

Explore
Make Playlist
Prefs
About

The Explore screen lets you browse your music collection, set song attributes, and select songs. The Playlist screen lets you generate playlists from the songs in your collection. You can choose to make playlists using the currently selected file as starting point, or staying only within the currently selected directory.

3.2 Choose the Music Directory

GJay assumes that you have a single base music directory in which you have stored all your music files. The first time you start GJay, it will ask you to choose this base music directory. (You can change this later in the preferences).

3.3 Scan Music Directory

Whenever you set the base music directory or start GJay, it will pause for a moment as it scans all the files in the directory. It looks for new files to add, as well as old files which are no longer there.

3.4 Explore

Once the base music directory has been set, the explore tab lets you navigate your music directory tree. You can browse your collection, play songs in xmms, see how songs have been analyzed, and set song attributes.

You can rate and set the color of songs which haven't been analyzed yet.

The pane on the right shows what's selected in the explore tree. You cannot select multiple files from the tree by clicking on them. You can select every file within a directory, however, by clicking on the directory in the tree and then clicking the "select all" button.

When you have several files selected, you can pick their color or rate them as a group.

3.5 Playlist

The Playlist screen lets you generate playlists.

Note that only the left portion of the screen changes; whatever file, directory, or group of files was selected in the explore view is still selected. This lets you specify playlists based on the selection:

Start the playlist with the selected file
Only use the selected files in the playlist
Only use files within the selected directory

Clearly, you can tweak a lot of options in pursuit of the perfect playlist. These options address three questions:

What songs should be included?
How will the playlist start?
How will the next song be selected?

3.5.1 Eligibility

As mentioned above, if you have selected files within a directory or a directory, you can choose to make a playlist using only the selected songs.

If the "Rating cut-off" is selected, songs which have been rated below the rating threshold will not be used.

3.5.2 Starting the Playlist

If a file is selected, you can choose to start the playlist using that file. Alternately, you can choose to start a playlist by picking whatever song is closest to a particular song. If you opt for neither option, a random starting song will be selected.

3.5.3 Pick Next Song

If "Wander" is selected, GJay will pick each song by comparing it against the previous song. Otherwise, GJay will pick each song by comparing it against the first song.

Song comparison is based on picking the best song matching a particular song using a variety of criteria. The user picks the relative importance of the criterea; these include:

Frequency Fingerprint -- do two songs use the same kinds of sounds (e.g. are two songs bass-heavy in the same register?)
BPM -- do two songs have a similar beat?
Hue (Color) -- did you give two songs a similar color categorization?
Brightness (Color) -- did you give two songs a similiar color brightness?
File location -- how close are two songs in the directory tree? Two songs in the same directory are closer than two songs five directory steps apart.

There is another component to this: randomness. You can adjust how tightly these criterea are applied. The trade-off is that if you pick a low randomness, the same songs will tend to following one another, but if you pick too high a randomness, there won't be much coherence between tracks.

3.5.4 Time

You can specify how long the playlish should be, in minutes. Of course, the actual playlist will be a few minutes longer or shorter, depending on how the songs that are picked.

3.6 Prefs

4. Analysis

Song analysis takes place in the background. When you quit GJay, you can choose to continue this analysis in the background. You can also run GJay as a daemon, without displaying the application, to finish any pending analysis. (Run "gjay -d").

If GJay is running in daemon mode and you start GJay as an application, the daemon process will attach to the application.

The daemon process has been nice'd (to 19) so it will play nice on your system.

5. Playlist Mode

You can run GJay from the command-line to generate playlists (gjay -p). It uses your last stored preference values as the relative criteria weighting.

Passing "-x" will send the generated playlist to XMMS. Otherwise, the playlist will be written to standard out. In most cases, you'll want to direct this output to a file, e.g. "gjay -p > list.m3u".

You can specify how the playlist starts by passing a color (gjay -p -c color, where color is either "red", "green", etc., or a hex value 0xRRGGBB) or file (gjay -p -f filename).

The playlist length is given by "-l length".

Passing "-u" will include normal m3u playlist fields (e.g. artist and title information, length) in the playlist.