Getting started with esound


These are notes to myself. It's a work in process. esound is not yet ready for public distribution. This is only a crude outline, to help jog my memory and to provide a seed from which more useful documentation may eventually emerge. I've left out many crucial details.

esound is a MacOS-based software suite that generates audio from low-frequency seismic or other geophysical data, sends the audio to a SHOUTcast server, and periodically delivers files containing audio, spectrograms, state-of-health, and other data to a website.

First, some definitions. The name esound usually refers to the entire software suite. It consists of an interlinked ecosystem of Bash shell scripts and binary executables that support the heart of it all: a command-line executable program also named esound. The executable esound, which I wrote in C/C++, reads a bunch of data files in various formats, resamples the data to "speed it up", and converts the data to audio. It intelligently handles any gaps in the original time series data, resulting in a continuous audio file of the appropriate duration. A single run of the executable esound generates an audio file of a particular window of time. (Typically, the time window extends backward from the present moment by a few hours or days.) The associated shell scripts and ancillary programs actually play the audio file, generate spectrograms, upload files, and then supply esound with the appropriate command-line parameters to generate the next audio file. The entire esound suite produces a continuous forward-moving audio program of successive backward-looking windows of audified and accelerated geophysical data.

A "program" is a stream of audified data from a particular recording instrument (seismometer, infrasound sensor, etc.) coming from a particular station somewhere in the world, that has been speeded up a certain amount to make the low-frequency signals audible. For example, one program might consist of broadband seismic data from IRIS/IDA station NNA in Peru, speeded up 3600-fold; another might be infrasound data from a local infrasound sensor, speeded up 60 times. Each program is defined by the settings in its config file ( Up to four programs can run simultaneously on a Mac mini (probably more, but 4 seems to be a reasonable limit for now). Each program collects data from a predetermined directory on the network, converts the given data type (miniseed, RefTek, etc.) to audio, and optionally feeds the audio up to a SHOUTcast server. There are many settings in the config file: station info, speedup factor, time window duration, audio filters, audio compressors, SHOUTcast upload credentials, etc., etc. Config settings may be changed on-the-fly, while a program is playing. Programs are started and stopped via commands typed into the Terminal command line. Once the program is launched, it can run unattended for long periods of time.

A "pod" is a set of one or more programs running concurrently on a single Mac. Only one pod should be running at a time. Like programs, pods are configured by editing a config file. The config file includes the list of programs that are "bound" to the pod, plus settings for uploading files via sftp to a website. Like programs, pods are controlled from the command line. For example, the command pod/start starts the pod, and all the programs that are bound to it. The command pod/stop stops all the programs.

A "cluster" is a networked group of pods.

Hardware required: (1) A standalone Mac for each pod. A "headless" Mac Mini works great. (2) A multichannel audio interface. I use the Behringer U-Phoria 1820, which provides 8-channels of audio via a USB 2.0 connector. This is sufficient for a single pod running 4 stereo Earthsound channels.

Software required: (1) esound, a self-contained bundle of executables, libraries, shell scripts, and other resources that enable a Mac Mini to run unattended as a "pod" that generates up to four simultaneous Earthsound programs. (2) LoopBack, with which you configure "virtual audio devices" through which esound will send its audio output. Loopback is the only commercial piece of software required. (3) B.U.T.T. (Broadcast Using This Tool), an app for streaming audio to a SHOUTcast server; it's included in the esound bundle.

Optional: (1) a website to which the audio files, spectrograms, and other data will be delivered; (2) a SHOUTcast server to receive the audio feeds from your pod and deliver them to listeners on the Internet.

Step by step:

Set up the hardware.
Set up a headless Mac Mini. Attach the external multichannel audio interface.
Set up the virtual audio devices.
Download and install LoopBack. Use LoopBack to create 4 new virtual audio devices named "Device1", "Device2", "Device3", and "Device4". To each device add 8 additional channels (for a total of 10 channels). Choose the outboard interface as the "monitor". You should only need to run LoopBack this one time; it's not needed for routine operation.
Install esound.
Get a copy of the software bundle and place it in a convenient directory — say, ~/earthsound. Unzip the file. It will create a new directory, esound, within which all the components reside.
Install BUTT.
B.U.T.T. (Broadcast Using This Tool) is a shareware app that sends audio from the Mac to a SHOUTcast server. The installer is in the directory esound/resources. Double-click the installer and drag the app into your Applications folder.
Set up SSH on the pod.
See this tutorial. Once the pod has a public-key, add it to the list of "Access Keys" at my Bitbucket git repo for espsh (Earth Sound Project SHell). Without this step, the update commands (see below) will fail.
Create the first program.
Each Earthsound program is identified by a unique alphanumeric string. To create a program named 'myProgram1', open a Terminal window and type:

% cd ~/earthsound % ./esound/espsh/scripts/ myProgram1

In addition to creating the new program, this command places some useful (and much shorter) commands into a directory named pod.
Edit the config file.
Open a text editor and customize the program parameters:

% vim myProgram1/

Test the program.
Launch esound:

% myProgram1/start

To stop the program, either type CTRL-C or do this in another terminal window:

% ~/earthsound/myProgram1/stop

Control the program.

% myProgram1/start # start the program % myProgram1/stop # stop the program % myProgram1/restart # stop, then start, the program % myProgram1/clean # clean out the tmp files generate by the program

Control BUTT.
You can control the state of the SHOUTcast feed while the program is running:

% myProgram1/buttctl start # start the SHOUTcast feed % myProgram1/buttctl stop # stop the SHOUTcast feed % myProgram1/buttctl restart # stop, then start, the SHOUTcast feed

(This does not affect the state of the SHOUTcast server itself; it merely controls the audio feed from the pod to that server.)

Create more programs.

% pod/new program2 % vim program2/ ... % pod/new program3 % vim program3/ ... % pod/new program4 % vim program4/ ...

Test each program one by one, as described above. Edit the pod config file to bind these new programs to the pod:

% vim pod/

Launch the pod.

% pod/start

This launches each program, each in its own new terminal tab.
Other commands available.

To control the pod:

% pod/stop # stop all the programs % pod/restart # restart all the programs % pod/update # update the espsh shell scripts to the latest version % pod/clean # clean out the tmp files generate by each program

To control the upload manager:

% pod/umctl stop # stop the Upload Manager % pod/umctl start # start the Upload Manager % pod/umctl restart # start the Upload Manager % pod/umctl purge # delete all previously queued files from the Upload Manager % pod/umctl log # view the Upload Manager log file % pod/umctl tail # view the most recent entries in the Upload Manager log file