ANSI Jukebox for Sony s-link CD changers

I. Warranty

1) There is no warranty. This source code, binaries, data records and instructions are provided as is. No warranty of any kind is expressed or implied. You are free to use the source code in whole or in part according to the terms of the GNU general public license, but do so at your own risk. The authors provide no statements of suitability for any purpose whatsoever.

II. Prerequisites

1) Sony CD changers supporting the slink command protocol

2) Parallel port slink interface adapter designed by Mike Muise and detailed at http://www.undeadscientist.com/slink.html

3) Linux Kernel from 2.0.x, 2.2.x or 2.4.x series.

4) Slink device driver appropriate for your kernel release. Refer to http://www.undeadscientist.com/slink.html for details of the device drivers and various kernal implementations.

5) Interconnect cables (stereo 1/8 inch) for slink.

6) gcc or other suitable compiler correctly installed.

III. Installation

1) Unpack the archive. You obviously have already figured that part out since you are reading these instructions.

2) Change to the ./src directory.

3) make

4) make install

5) ./jukebox

6) It should work as described in section IV.

Important Note: If you are using a version the version 2.0 slink parallel port device driver, you must create a symlink /dev/slink0 pointing to /dev/slink. The jukebox is setup to work with the 3.x drivers and uses the newer name convention for the device.

IV. Using the Jukebox

The ANSI jukebox uses the ANSI terminal cursor command codes to create and manipulate a GUI type environment that can be easily navigated using only the keyboard (in fact there is no mouse support at all) either at a console or over a telnet/ssh connection with proper emulation. This semi-graphical environment is driven by the member functions of the Graphical Ansi Library (GAL). The behavior of components in the GAL is as consistent with common windowed behavior as could be reasonably managed. The hope was to provide a fairly easy to navigate environment all on the keyboard. The following command keys are common within the GAL.

( TAB ) --- Next Window

( ~ ) --- Previous Window

( + ) --- Expand Drop Down List Box

( - ) --- Collapse Drop Down List Box

( ENTER ) --- Action / Select Hilited Item / Collapse List Box if Open / User Defined

( UPARW ) --- Scroll Up

( DNARW ) --- Scroll Down

( PGUP ) --- Page Up

( PGDN ) --- Page Down

( DEL ) --- Delete Item From List Box

Other keys will perform functions based on the definitions of the specific component as used within the Jukebox. The function keys swap interfaces between the playback console and the database build console. ESC exits the program, rather abruptly and with no "Are you sure?" type warnings.

Important Note: The ANSI jukebox was written and tested as a console application. It DOES NOT FUNCTION CORRECTLY when run in an X-Session terminal window. Primarily the function keys map incorrectly so it becomes difficult to move over and rebuild the database. If anyone finds a work around to get the keys mapped, please feed this fix back so it can be included in these instructions.

Pressing a letter while in the track list window will jump to the first track starting with that letter. This is a good way to overcome the redraw latency which the large list boxes have over non-local telnet/ssh connections. The keyboard buffer is quite large, so we recommend against holding down the up or down arrow in the track list window. It might scroll longer than you think.

There is presently no popup windowing support in the GAL. It never got written, and is perhaps one of the greatest short comings of this code.

Before you can use the Jukebox you need to create a database of tracks which are available. The Jukebox will generate the track list by loading each CD in the changer (or a range you specify), collecting the lengths and numbers of tracks, and then making a best guess at a CDDB key for the disc. I say best guess because the decks do not return enough information to make a 100% reliable key creation possible. The Jukebox gets it right about 90% of the time. The other 10% you can work around. Refer to section V for more information on CDDB record creation for the database.

Once you have a database of clean CDDB records (I have included a few hundred of my own to get you started with good examples), you need to start the Jukebox and press F3 to go to the database building console.

Select rebuild for one deck from the drop down menu and enter a range of discs. !!! IMPORTANT BUG NOTE: REBUILDING BOTH DECKS AT ONE TIME MAY CORRUPT THE COMPLETED DATABASE. WE STRONGLY RECOMMEND BUILDING ONLY ONE DECK AT A TIME !!!

As discs are loaded, the key generated by the Jukebox for each disc is displayed and the status of the rebuild is displayed graphically.

  • White indicates the status of the database when the Jukebox started. This is based on faith that nothing has changed.
  • If you perform a SCAN, the Jukebox does its best to rotate the carosel 360 degrees and then asks the deck to report which slots have discs. This works ok if the deck is fairly full, not so well if it's fairly empty. Any slots that match what was expected before the scan will turn Yellow. Mismatches will turn Red and be removed from the database until rebuilt.
  • During a full rebuild you will see one of three results. Green indicates a record was verified and matched what was already in the database. Blue indicates the record didn't match the database, but was updated sucessfully. Red indicates it was impossible to match a record to the disc found in the indicated slot. Reds are caused by 3 things. (1) The disc is in the player backwards and was unreadable. (2) There is no CDDB record for the disc in the local database. (3) There is a record in the database, but it doesn't have the same CDDB key as the once generated by the deck. Refer to section V for more help on working with the local CDDB database.

    Take note of discs which fail to add correctly to the database to allow correction of the CDDB records later. The Jukebox will remember the database once built as long as the discs do not change positions.

    At this time there are no "self-healing" provisions in the code to detect when a disc is wrong until it's location is manually rebuilt. The Jukebox operates entirely on faith in the user. Several ideas have been proposed to try to mend the database while using the Jukebox, but none of them have been implemented in this code.

    As each disc is correctly identified, the first 13 characters of the disc artist are placed in the display memory of Sony changers that support text naming of discs. This is a big help later.

    After rebuilding the track index database return to the playback menu by pressing F1. Tracks may be selected out of the list on the bottom half of the screen. The list may be sorted by song title, artist or numerically by deck, disc and track. Selecting a track by pressing enter will put it in the queue for the corresponding deck. They are color coded red and green to make it easier to keep the two queues close to the same length since two decks will alternate back an forth when playing. !!! USABILITY NOTE: THERE IS NO PROTECTION CODE TO PREVENT ENTERING MULTIPLE COPIES OF A TRACK INTO THE PLAY QUE BY HOLDING DOWN THE ENTER KEY. IT WILL STACK UP 10 COPIES SURPRISINGLY FAST IF YOUR FINGER DAWDLES :) !!! You will notice that the decks will queue tracks as soon as one is available, but will not begin playback until you press the play button at the top of the screen.

    Once you have a few tracks in each queue, tab over to the Play button and press enter. The decks will being playback and alternate until the ques are empty. If the ques are uneven lengths they will still empty, but there will be a track queueing delay as discs are changed on the since active deck.

    The queues may be edited during playback. Expand the queued track list by tabbing into it and pressing +. Selecting a track with the arrows and pressing DEL will remove the track from the queue. Selecting a track from the list and pressing enter will move it to the top of the que. There were some issues with resoting the ques in the past that caused some strange effects (the same track being played twice, etc). I believe these have been resolved, but they might crop up and I thought I should include a warning so the cause would be easier to track down.

    The Pause button... doesn't work. The decks will pause, the timer will keep running, and there's no way to get them started again.

    The Stop button... also doesn't work like you'd expect.

    The Cut button will immediately change to the next song without waiting for it to play through, but it will only function when one deck is actively playing a song.

    Status of each deck is continuously displayed, including run and remain timers, artist, title and location of the current song loaded in each deck, as well as the model number and capacity of each deck as reported at startup.

    The timers will turn yellow at the 1 minute warning, and red at the 30 second warning. (Most of the Sony decks take 25 seconds to load and que a disc, so if you haven't got the next song picked at 30 seconds, you might not get it in the queue fast enough.)

    Some additional warnings...

  • If you press ESC at any time, the Jukebox will exit immediately... not warning, no muss no fuss, no saved play lists. Just gone.
  • If you change consoles using F1 or F3 during an operation the Jukebox will forget what it's doing. Once again, no warnings of any kind are given.
  • Occasionally you'll hear the first 1/2 second of a track start and get cutoff. This is an irritating but rare behavior. It is caused by poor length reporting on the part of the CD changer. We've attempted to cover it up, but once in a while one slips through and the Jukebox has to kill it just a hair too late. If someone fixes this, PLEASE PASS BACK THE MODIFIED CODE!
  • The Jukebox works best when launched from the console in 43 line mode. In fact, it isn't usable at all in anything but 43 line mode. It should work in a terminal window under X-Windows, but you may have to do some tweaking to get the function keys to pass correctly so you can swap between the building tool and the Jukebox playback console.

    Ok, I think that covers the functionality of the Jukebox. Now on to creating those necessary evil CDDB records.

    V. Local CDDB Database

    The local CDDB database is the solution used by this Jukebox for identification of the CDs in each deck. Why is it only local? Well, mostly because CDDB is a miserable thing for a machine to parse. It's irregularly formatted, inconsistent, full of extended character sets, and otherwise just a pain in the ass. Unfortunately when we started this project we didn't have an alternative. Subsequently we have created one called cd24, details of which can be found at http://www.cd24db.com, but this code still uses the CDDB records.

    The local CDDB records have to be cleaned up such that they can be parsed correctly by the Jukebox. That means each DTITLE or TTITLE line must be formatted as ARTIST / TITLE if artists are listed for each track. The Jukebox assumes the ARTIST found on DTITLE applies to all tracks if they do not have compound entries. The remaining fields in the CDDB record are totally ignored. If you get things backwards, you'll get strange entries in the track lists, so it's best to sort it out here.

    Unfortunately the records retrieved from the CDDB servers frequently are backwards, or bizzare in other ways. In addition, CDDB keys do not generate consistently across various hardware and software, so you'll find that small variations in the key values are common. Winamp may do a fairly good job of covering this up, but we can't because frame data is not available via the slink protocol. The end result is that if a disc you know you have a record for fails to id, check to see if the file name matches the key reported by the Jukebox during rebuild. If it doesn't match just rename it to whatever the Jukebox thinks it should be and use that. This is a bit of a hack, but it solves the problem and it's only a small local database anyway.

    VI. A Note On Permissions

    Nope, not more leagalese, file permissions. Right now the library files, database, and indexed lists will be created and maintained as mode 660 for the user that first runs the database. So, if I start the jukebox for the first time as jbehle, the databases will be owned by jbehle and in the group jbehle. This is just the way it is set up right now. No formal policy was ever established and you're free to tinker with it to suit your own operating environments.

    VII. Platform Compatability

    This software has only been tested on i386 systems running linux distributions from slackware, Mandrake, Debian and Red Hat. There are no obvious reasons why it shouldn't work on any platform where the device driver works, but we have not tested it.

    Brian Behlendorf < behlendo@attbi.com>
    Jeff Behlendorf < jbehle@earthling.net>