djcev.com

Intro & Problem

Stanton QuickGrid is an audio file analysis program for Mac OS X and Windows distributed with the Stanton SCS.4DJ. It creates metadata files that contain things like the waveform graphic and beat grid indicators for use with the SCS.4DJ device. It's a program in two parts: djanalyze.exe which does the work of generating metadata for one audio file, and the graphical frontend (pictured above) which automates the process for many audio files. QuickGrid performs a similar function to, say, Rekordbox's analysis and export to USB.

It works in two stages. First you "analyze tracks" which creates and stores analysis metadata files for audio in a location you specify. Then you "prepare USB device" which crawls a USB drive looking for audio and copies over the relevant analysis metadata files, and also creates a file called hashes.dat on the USB drive which the SCS.4DJ reads to discover new data.

I have a problem with QuickGrid: I don't run either OS X or Windows. So I worked out what the graphical frontend is doing and how to drive djanalyze.exe using Wine. Then I wrote a shell script to automate the process. Some notes on what I found:

djanalyze.exe

Let's take a look at djanalyze.exe's help output:

$ wine "C:\Program Files\Stanton\djanalyze.exe" "--help"

usage: djanalyze audioFileName rootFolder songId
             or
       djanalyze --version
             or
       djanalyze --error-code
             or
       djanalyze --help


example: djanalyze "e:\audio.mp3" "e:" "FE66E7B1E7D1C4B8AAA2FD5BB8B71A39"

audioFileName is the full path to one audio file. rootFolder is the path where you want djanalyze to write its metadata files. songId is the md5 hash of the audio file, and will be used as the filename of the resulting metadata files. All paths are in DOS format. Wine provides a __ Z:\ __ drive that maps to the Unix root directory, so we can access any path we want that way. It's easy to get the md5 hash of a file when running any modern Unix-like operating system; I used FreeBSD's md5(1).

File Structure

Another piece of the puzzle is the file structure the SCS.4DJ expects on USB drives:

$ ls /USB_Drive
SCS.4DJ_Database
SCS.4DJ_Playlists
SCS.4DJ_Sessions
$ ls /USB_Drive/SCS.4DJ_Database
analysis
db_reserved_space
hashes.dat
Stanton_DJ_DB.db
uuid.txt
$ ls /USB_Drive/SCS.4DJ_Database/analysis
00
01
02
... 256 two-character directories, 00 thru ff, named for the first
... two hex digits of the MD5 hash of the audio file the analysis
... files within relate to.
ff

SCS.4DJ_Database is what we're interested in. hashes.dat is found here, as well as Stanton_DJ_DB.db (an SQLite database we won't be getting into today). SCS.4DJ_Database/analysis is where the device looks for metadata files (in subdirectories named after the first two characters of the md5 hash of the audio file).

djanalyze.exe will create some of this tree itself, however for me it creates a directory called SCS.8DJ_Database rather than the expected SCS.4DJ_Database, something to remember when we script this process. (Perhaps it's creating .8 instead of .4 because it couldn't find an existing .4 directory?)

hashes.dat

hashes.dat is a plaintext file that the SCS.4DJ device reads when a USB drive is inserted into the device. It contains data on new tracks that the device should import. The first line of hashes.dat must be "Hash Helper v1". Subsequent lines each represent one audio file and are split into five tab-separated fields; here's the field order and contents:

1. Filename (no escape characters, regular Unix path, from the USB drive root).
2. MD5 Hash of file at Filename.
3. st_atime (time when Filename was last accessed).
4. st_size (Filename's size in bytes).
5. 0 (the character "0"; I don't know what this field is used for).

st_atime and st_size can both be easily retrieved in a shell script using for example FreeBSD's stat(1).

Script Outline & Closing

I wrote a script that copies both the audio files and metadata files to the USB drive at the same time instead of duplicating QuickGrid's two-stage approach. (My script "adds" music to a USB drive with the necessary additional files; you use it instead of your file manager to copy music over).

The order of operations is, roughly: call djanalyze.exe to generate metadata files in a temporary location for audio file X, then copy audio file X to the USB drive, then move the new metadata files to the USB drive, then add an entry to hashes.dat describing the new audio file (creating hashes.dat if necessary).

The information above should be enough for a savvy reader to script their own replacement for QuickGrid, I hope. I have another post on this topic in the works, Stanton QuickGrid (Part 2), where I'll show and explain a simplified version of my own script.