PerlJammer, a SQL-backed MP3 Jukebox

PerlJammer - a SQL-backed Perl/Tk MP3 Jukebox

About PerlJammer

PerlJammer is a SQL-backed Perl/Tk music player based on Mike Oliphant's abandoned DigitalDJ. It is free software; you may do whatever you want with it, so long as you credit the author.

PerlJammer generates random MP3 playlists from a modified DDJ-compatible MySQL database, and plays them using a user-selected external command-line MP3 player, which defaults to madplay (because of its superior audio quality). It is highly configurable, and can be remote-controlled via a network socket using either of two companion remote-control programs: RemoteJammer, a skinnable graphical desktop remote (see below), or pjam-remote, a command-line console remote program intended for scripting use. The playlist can be reordered by drag-and-drop, and songs can be dynamically dropped from the playlist or inserted into it before, after, or in place of the current playing selection. You can jump directly to any song in the playlist at any time by double-clicking it, and can replace any selection in the playlist with the entire disc it came from, in track order, simply by clicking the track-to-disc button (fifth from right).

The screenshot above shows PerlJammer v1.6.1 in the middle of playing a song. (Window decorations are not included in the box; they are provided in this case by the F Virtual Window Manager.) PerlJammer's button bar can be configured to appear either at the top or bottom of the window. Some controls change their appearance depending on the state of the program. In general, buttons that start or change something have deep blue icons that highlight green; buttons that stop, close, or delete something have black icons that highlight red; and buttons that are waiting for a user action or a state change have red icons. In this example, with a selection playing, the Play button has changed to a Pause button. PerlJammer has been started with the gainctl option enabled, and the persistent gain adjustment control is visible between the two main control groups.

Here is the initial state of the main button bar with nothing playing. All buttons are in their default states.

Here, a selection has been paused mid-play, and PerlJammer is waiting for further action by the user. (The elapsed-time display also changes from blue to red when paused.)

And here, PerlJammer is doing a "delayed stop", in which it allows the current selection to finish, then stops playback with the selection set to the next unplayed track in the playlist. (The delayed-stop feature is, to the best of my knowledge, unique to PerlJammer.)

RemoteJammer

RemoteJammer is PerlJammer's skinnable graphical remote control. It provides a duplicate set of controls matching those on PerlJammer's control bar, with the exception of persistent gain control (which is not supported remotely at this time), and monitors PerlJammer's currently playing selection. The controls are rearranged into logical groups and laid out to give a "look and feel" suggestive of a hand-held remote control or a portable music player.

RemoteJammer can be reskinned by simply setting the remoteskin configuration option to point to a 162 x 302 pixels (width x height) or larger image in PNG, JPEG, GIF or XPM format. If the skin image is larger than 162 x 302, then the top left 162 x 302 pixels will be used. Reskinning does not (yet) include the ability to rearrange or redesign controls, but this capability may be added later.

A selection of sample skins is included.

pjam-import

You can now use the new pjam-import tool to populate a new database with an existing music collection. You can pass it anything from a single file, to the top level directory of your music collection, to your entire disk on the commandline, and it will search all paths passed to it for MP3 files. (It can also be told to find Ogg Vorbis files, but this isn't very useful yet, because the rest of the PerlJammer suite doesn't really know what to do with them yet.) You can use pjam-import -find to just search for audio files that aren't already in the database and report what it finds, or pjam-import -show to find files and show the metadata which it would insert into the database about each file so that you can verify the metadata before you actually perform the import.

pjam-import is a command-line-only tool for now. Later on, if there is a demand for it, I will add a GUI interface to allow you to select which files to import out of the audio files found by pjam-import, and possibly to make minor edits to MP3 metadata before inserting.

IMPORTANT NOTE:

pjam-import relies on MP3 tags containing correct metadata in order to insert correct metadata into the database. It is YOUR RESPONSIBILITY to make sure that MP3 tag information is correct to your satisfaction before importing music. The long delay before releasing pjam-import is because I kept thinking up different approaches to automatically derive and verify correct metadata, none of which worked reliably in all cases, and eventually concluded that the problem is intractable. MP3 metadata, particularly on downloaded files, is so frequently either incomplete, wrong, or both, that verifying it is a task which can be accomplished only by a human. (I've seen audio files that were tagged by people who didn't know either the correct name of the song or the correct artist, so instead of trying to look it up they apparently just guessed.)

If you need to correct MP3 tag data or fill in missing data on files with inaccurate or fragmentary MP3 tags (as is, sadly, the case for far too many MP3s obtained online), I recommend trying the Picard tool published by MusicBrainz. Even Picard won't get you all the way there 100% of the time, but it should get you close enough in almost all cases to be able to identify the correct metadata.

Downloading

This is release 1.6.9 of the entire PerlJammer suite. Grab the tarball here. This release contains PerlJammer v1.6.9, pjam-remote v1.0.5, mp3insert v1.0.2, pjam-dbtool v1.1.0, RemoteJammer v0.9, and pjam-import v1.1.0, plus a new link to pjam-remote as pjam-insert with specific altered behavior. Also included is a new skin, Raindrops.

Recent Significant Changes

UI hot keys expanded and revised for version 1.7.0.
New feature: The playlist now includes a hidden column for song year, and STATUS output now includes the song year as well as play time, in the format (yyyy, mm:ss).
IMPORTANT BUG FIX: Fixed a somehow-overlooked design bug in which a 'Stop' command while PerlJammer is not playing causes abnormal termination. Added similar checks to the Pause and Resume commands as a precaution.
New feature: pjam-remote can now also be invoked as pjam-insert, in which case it assumes that the host is the default remotehost from .pjam/config and that the command is 'insert'. Thus, pjam-insert is basically a shorthand for 'pjam-remote <default_host> insert'.
New feature: pjam-dbtool now recognizes a special "meta-disc" named (single), for use when entering singles into the database. The (single) meta-disc has no associated artist, genre, or year. It is created automatically on first use, and used for any song with (single) as the DISC TITLE tag.
New feature: The new action_at_end directive allows you to choose from four actions when PerlJammer reaches the end of a playlist: loop back to the beginning of the current playlist and repeat (equivalent to autorepeat: yes), seamlessly generate a new playlist and keep going, just stop and wait (equivalent to autorepeat: no), or stop and exit.

(This directive replaces and obsoletes the autorepeat directive.)
New feature: PerlJammer can now track your play stats for music in your database. This information is not used at this time, but may be used in the future to offer optional least-often-played or least-recently-played priority schemes for tuning playlist generation.
pjam-import is ready for production! Now you can import an existing music collection into your PerlJammer database.
Various improvements to RemoteJammer, including a new feature to display the next ten upcoming tracks in the playlist, and a rearrangement of the controls (making the control arrangement a little more like PerlJammer's main control bar) to make room for the new .
Minor bug fixes in mp3insert, including properly escaping quotation marks in song and CD titles (rare, but it previously caused SQL errors when attempting to insert data).
New 'Insert Next' function automatically inserts the next track from the disc containing the selected song into the playlist after the selected song, if the current selection is not the last song on its disc.
The 'New Playlist' function no longer interrupts a currently playing song. If PerlJammer is playing when you generate a new playlist, the playing song is now kept as the first song in the new playlist, and play continues seamlessly. 'Insert Disc' is now also seamless, as long as the track being replaced by its source disc — if playing — is the first track of the disc. (Replacing any but the first track of a disc with the entire disc still restarts playback of the disc if the track replaced is currently playing.)
Networking code revised for better performance to support more remotes
Icon files and skins now stored in /usr/local/share/perljammer
Database character-set encoding problem fixed.
Drag-and-drop code fixed; drag-and-drop now updates the song list in real time as you drag songs.
Improved play/pause logic eliminates player deadlocks. (Previously, certain actions while playback was paused could create a deadlock that required manually killing the player. This bug was inherited from DigitalDJ.)
New persistent per-track gain adjustment feature. Gain adjustments are stored in the database. This IS NOT A VOLUME CONTROL; it is for normalizing playback volume between tracks.
Track disable is now a bitfield, allowing a single PerlJammer music database to hold disable flags for up to 64 distinct users.
Disable bitmasks allow you to choose to honor any combination of other users' disable flags.
The new disable control drops a song from your playlist and flags it as disabled with a single button click.
The new pjam-dbtool can update an existing DigitalDJ version 2 database to PerlJammer's version 3, or create a new version 3 database.
The new mp3insert tool replaces DigitalDJ's mp3insert, allowing Grip to automatically populate PerlJammer's database as you rip.

Installation

You can now either use an existing DigitalDJ database with PerlJammer or create a new one using pjam-dbtool. To install PerlJammer, extract the tarball, then copy perljammer, pjam-remote and mp3insert to a suitable location such as /usr/local/bin. Run perljammer once to create your config directory and a template config file (~/.pjam/config), edit the config file to set the preferences including the sqlcfg, sqlgroup and sqldb options, then run pjam-dbtool with the appropriate command-line settings to create the database if you do not already have an existing database created by DigitalDJ, then use pjam-import to populate it.

For more details and usage of each tool, see the 00.README file and the built-in help for each program (accessible via programname -man).