SoundSpigot HOWTO

Step by step instructions for setting up SoundSpigot.


  1. A computer running Linux, with a working sound card.
  2. If you want to trigger sounds, you also need a working parallel port and some switches connected to the parallel port.
  3. The sox tools (sound utilities); probably already installed.
  4. Enough RAM to store your sounds - only an issue with very long sounds. Add up the sizes of all the sound files you want to play; you must have more RAM than this.


Install from source:

Download the tarball (.tar.gz file).
$ tar xvzf soundspigot.tar.gz
$ cd soundspigot
$ make
$ make install

Prepare Your Sounds

Create a .wav file for each sound you want to play.
Prepare sound samples that:
  1. are all at the same bitrate - typically 44100 samples per second, which is CD quality;
  2. are single-track (mono)
  3. have no silent portion in the beginning;
  4. if meant to loop, have an end that matches the beginning;
  5. have no spaces in the filename;
  6. are preferably normalized; the loudest part of the sample should be full volume.
You can do this with cooledit on Windows, or audacity on Linux.
Convert each sound to a .sw file (raw PCM 16 bit signed format) using the sox tool:
$ sox myfile.wav myfile.sw

Set Up the Directory

Create a directory:
$ mkdir myshow
and move all the .sw sound files into it.

Create the Configuration File

Inside directory myshow, create a file called soundspigot.conf. Here's a short example:
samplerate 44100
port-poll-freq 20
buffer-size 8
channels 2
track {
    channel 1
    trigger 5
    attenuation -10.0
    file howl.sw
See the reference for details on the syntax of this file. Add a track section for each track you want to play. Set the attenuation to -10.0 decibels. This is a little below full volume, leaving headroom for mixing sounds. Later you can turn some tracks down if they're too loud. For each track, choose a triggering method: one of: If you don't set a triggering method, the track can only be triggered from the UDP interface. The reference describes how to set each of these methods.


Keep soundspigot.conf open in a text editor. In a separate terminal, launch the program:
$ soundspigot -d /path/to/myshow -f
The -f option tells the program not to daemonize. If all goes well, the program will print a table of tracks. If you specified some looping tracks, they should start playing. If you have triggered tracks, try triggering them from the parallel port.


If the program exited right after startup, read the error message carefully. Some common problems:
  1. Failure to open parallel port: May need to run as root. May need to unload the parport module (rmmod parport)
  2. Failure to open sound device: May need to run as root, or change permissions on sound device.
  3. Failure to open config file: Check path and permissions on file and directories.
  4. Error in config file: Check the line number provided. Make sure all integer values have no decimal point, and all real values have one.


Once you have the program working, try modifying a setting in soundspigot.conf. For example, change an attenuation from -10 to -20, and save. The program will react immediately, and print a new table of tracks.
You can rapidly evolve your show without needing to stop and restart the program.


When the program is running correctly, kill it with ^C and restart it without the -f option. It will daemonize, so it can keep running after the terminal is removed. This is the mode you want for actual operation. The program will still respond to changes in soundspigot.conf.

Starting at Boot

If you want soundspigot to start running when the computer boots up, one way is to add a line to /etc/rc.local, if your distro uses this file.
Add a line like this to rc.local:
/usr/local/bin/soundspigot -d /path/to/my/show

Soundspigot Home Page