djcev.com

Intro & Problem

For years I used a Stanton SCS.4DJ standalone player / mixer to play digital music in mixes. The SCS.4DJ comes with a program called QuickGrid that is used to generate metadata for music files you plan to play on the device. Notably QuickGrid takes care of calculating BPM, generating waveform displays, and so on.

Unfortunately QuickGrid is only publicly available for Windows and OS X, and I'm a BSD / Linux user. So, after a bit of investigation, I wrote a shell script wrapper around the djanalyze.exe program that comes with the QuickGrid software package. This script lets me do everything QuickGrid does from the comfort of my FreeBSD machine.

Here's a little about that shell script, scs4tool.sh:

Requirements & Script Arguments

scs4tool has only been tested on FreeBSD and it requires FreeBSD's md5 and stat utils. Additionally it requires working installations of the following programs: ffmpeg, FLAC, lame (for converting FLAC files to mp3), and SoX (to resample incompatible files). Some script features require other scripts from my library (in particular flac_to_mp3.sh).

Of course the program also requires a working copy of Wine with Stanton's QuickGrid software installed. You'll need to edit scs4tool.sh around line 48 to specify the Wine prefix you want to use & the path to djanalyze.exe.

Now let's take a look at the help output:

$ scs4tool.sh -h
Usage: scs4tool.sh [-3hHlv] [-a dir] [-d dir] [-r dir]

    Manage a file tree for use on the Stanton SCS.4DJ music player. Performs
    a function similar to Stanton's Quickgrid software.

    This script requires a working installation of wine and "djanalyze.exe",
    which can be found in the latest version of Stanton Quickgrid for
    Windows. This script also requires ffmpeg, flac/libFlac, and sox.

    Top level options:
      -3     Convert flac files to mp3 before copying.
      -a     Add a directory to the destination.
      -d     Destination directory.
      -h     Show help.
      -H     Print the "hashes.dat" hashtable.
      -l     View output log when finished.
      -r     Remove a directory at the destination.
      -V     Print version info.

There are two main modes: -a add and -r remove.

-a add takes as its argument one directory. Any music files in this source directory will be run through djanalyze.exe and the resulting metadata files will be copied to their appropriate places in the destination directory (default /y). Then the source directory and any music files it contains will be copied to the destination.

-r remove takes as its argument one directory name (which is assumed to be relative to the destination directory). This mode will remove the named directory and any metadata files associated with the music files contained in that directory. This is used, as the name suggests, to remove music from the USB thumb drive or other storage device used with the SCS.4DJ.

Several assumptions are made by the script. One: source directories do not have subdirectories. This script is not designed to recurse into and handle complex directory trees. Two: music files are FLACs or mp3s and the filenames end in ".flac" or ".mp3" (case sensitive). Three: the files are not corrupt or damaged in any way. In particular it must be possible to decode FLAC files with the reference library.

Some additional options: -d can be used to specify an alternate destination prefix (I don't think many people mount storage devices to /y), -3 instructs the script to convert any FLAC files it finds into mp3 as it copies them to the destination (hasn't been tested in a while), and -H is a simple shortcut to print the hashes.dat file present in the destination directory. Finally calling scs4tool.sh with no arguments will list the contents of the destination directory (equivalent to ls /y).

Typical Usage

Here's an example. I have a USB flash drive mounted at /y and I'm in the "Misc (demoscene, mods)" directory of my music library.

$ ls
...
[kfmf-egg1] various - exceedingly great grooves 1
[m5v] various - music contest 5 (veteran)
[mods001] rs3 - ray, beam, prism
[mods002] unknown artist - dirt
[mods003] necros - cloud city
...

Let's add the "[mods001] rs3 - ray, beam, prism" directory to my USB thumb drive for playback on my SCS.4DJ.

$ scs4tool.sh -a "[mods001] rs3 - ray, beam, prism"
scs4tool.sh: creating [mods001] rs3 - ray, beam, prism...
scs4tool.sh: adding 02 rs3 - beam.mp3...
scs4tool.sh: adding 01 rs3 - ray.mp3...
scs4tool.sh: adding 03 rs3 - prism.mp3...
$ ls -R1 /y
[mods001] rs3 - ray, beam, prism
SCS.4DJ_Database

/y/[mods001] rs3 - ray, beam, prism:
01 rs3 - ray.mp3
02 rs3 - beam.mp3
03 rs3 - prism.mp3

/y/SCS.4DJ_Database:
analysis
hashes.dat

/y/SCS.4DJ_Database/analysis:
08
63
f1

/y/SCS.4DJ_Database/analysis/08:
988ef313b6ffa7fe49df1702edc63e.sar
988ef313b6ffa7fe49df1702edc63e.sek
988ef313b6ffa7fe49df1702edc63e.wfv

/y/SCS.4DJ_Database/analysis/63:
e7bae6d3f0e7bfa6e003c63895b077.sar
e7bae6d3f0e7bfa6e003c63895b077.sek
e7bae6d3f0e7bfa6e003c63895b077.wfv

/y/SCS.4DJ_Database/analysis/f1:
d65a06ac0b401468e9e1a6a5a2033f.sar
d65a06ac0b401468e9e1a6a5a2033f.sek
d65a06ac0b401468e9e1a6a5a2033f.wfv
$ scs -H
Hash Helper v1
/[mods001] rs3 - ray, beam, prism/02 rs3 - beam.mp3     63e7bae6d3f0e7bfa6e003c63895b077 1681583184000   26364981        0
/[mods001] rs3 - ray, beam, prism/01 rs3 - ray.mp3      08988ef313b6ffa7fe49df1702edc63e 1681583228000   18419577        0
/[mods001] rs3 - ray, beam, prism/03 rs3 - prism.mp3    f1d65a06ac0b401468e9e1a6a5a2033f 1681583233000   17683969        0

Now I can unmount /y then take that USB flash drive and insert it into a port on my SCS.4DJ. The SCS will then find the three files I added above and the associated metadata files created by djanalyze.exe. That means that the track waveforms, track BPM, and beatgrid analysis for those files are all ready to go and the SCS won't have to calculate any of that itself.

Removing a directory is similarly easy:

$ scs -r "[mods001] rs3 - ray, beam, prism"
scs4tool.sh: removing [mods001] rs3 - ray, beam, prism/03 rs3 - prism.mp3...
scs4tool.sh: removing [mods001] rs3 - ray, beam, prism/01 rs3 - ray.mp3...
scs4tool.sh: removing [mods001] rs3 - ray, beam, prism/02 rs3 - beam.mp3...
scs4tool.sh: removing [mods001] rs3 - ray, beam, prism...
$ ls -R /y
SCS.4DJ_Database

/y/SCS.4DJ_Database:
analysis   hashes.dat

/y/SCS.4DJ_Database/analysis:
08 63 f1

/y/SCS.4DJ_Database/analysis/08:

/y/SCS.4DJ_Database/analysis/63:

/y/SCS.4DJ_Database/analysis/f1:

And that's basically all the script is designed to do: add and remove files. There's a little more going on under the hood (I added some replaygain mangling nonsense late in the script's life) but not much. The process and purpose of this thing is kind of complicated to describe but easy to use, as I hope the example above shows.

Conclusion

As of April 2023 the SCS.4DJ software package that includes QuickGrid for OS X & Windows is available from archive.org's copy of the SCS.4DJ page on Stanton's old website (filename "SC-IXV5.0.1.zip"). That same file comes with the latest software update for the SCS.4DJ device itself (filename "SCS.4DJ_SC-IX-5-0-1_RC1_2014-03-17.update"). That's everything someone would need to update & run one of these media players (and the source of djanalyze.exe). You can find the scs4tool.sh script in my dotfiles repo.

This'll probably be my final word on the SCS.4DJ. I moved on from it to an Xwax-based DVS system nearly a year ago. My SCS4 is beat-up but still mostly reliable; it's now my backup device (and so hopefully won't see much use).

I've been meaning to write this article for several years. I'm doing it today because I can tell I'm right on the edge of forgetting how this all works. Maybe it - this article or the script - will be useful to someone. If nothing else I can use it as a reference in the future if I need to use my SCS.4DJ again.