Usage examples for the saugns program, and some further notes. For the script language SAU, see the language page, or the README.SAU file.
Running the program with no arguments, or with -h,
prints a concise list of arguments and invocation types supported.
The same information, and a bit more, is provided with the accompanying
saugns(1) man page.
To simply play a script, using the default sample rate (96000 Hz):
saugns script
(Several filenames can be listed, or a * glob pattern used,
to play several files one after the other.)
To play a one-liner (in this example, sweeping through the human hearing range in 10 seconds):
saugns -e "Wsin f[v20 g20000 lexp] t10 a0.25"
(Several string arguments can be listed when -e is used,
each of which plays as a separate script.)
Sample rate in Hz can be changed using the -r option:
saugns -r 48000 script(s)
The quality of the generated audio is currently always better with a higher sample rate. Using a higher rate means that less aliasing distortion will be in audible frequencies. For each specific script, this may or may not matter. (Note that a very few scripts are exceptions, and actually depend on aliasing distortion as part of the sound design.)
The examples page offers more sounds and musicality. The language page has more on how to generate audio.
Test tones and some other kinds of simple signals are very easy to make using saugns, usually with one-liner scripts. Here's a 100 Hz test tone, plain white noise, and stereo white noise, respectively, each 10 seconds long.
saugns -e "W f100 t10"
saugns -e "N t10"
saugns -e "N cL N cR t10"
In the case of the last example, time only needs to be set for one of the generator objects, because default time values grow from 1 second to match the longest play duration within the current scope. S options are another way to change parameters for several generators at once. As for the c parameter, it works like a balance knob.
The option of which system audio device name or path is used (for ALSA, OSS, etc.) by saugns can be changed by setting the AUDIODEV
environment variable, similarly to how other software supports this option:
export AUDIODEV=value
...where instead of value something is inserted to
replace e.g. default for ALSA or sndio, or /dev/dsp for OSS.
See the man page for notes on compatibility support for differently named environment variables specific to one or another system standard.
By default, both system audio output and any other output(s) are stereo, whether or not any sounds in a script differ between the channels. (See the SAU channel features for how to place things in stereo.) This can be changed by adding the --mono option, to downmix all outputs to mono.
To simply check if scripts parse cleanly (no errors or warnings),
use the -c option:
saugns -c examples/*.sau examples/*/*.sau
To print info for scripts based on a parse (duration, number of voices, and a partial debug info listing of what the script does):
saugns -cp script(s)
(The -c can be left out to also play.)
To write a 16-bit stereo PCM WAV file named "a.wav" containing all of the audio from script(s):
saugns -o a.wav script(s)
By default, writing a file makes the program run silent instead of playing scripts. This can be changed by adding the -a (audible) option, to also produce output for system audio.
Note that the default sample rate is 96000 Hz. It can be changed by using the -r option, as in the following example which uses CD quality sample rate. Note however that if you want to minimize aliasing distortion, it's best to instead produce audio with a higher sample rate, and then use an external resampler to reduce it.
saugns -r 44100 -o a.wav script(s)
If for example your script has a sawtooth wave which sounds too rough in the resulting file, the current recommended solution is to use SoX to resample, as in the below example which effectively does that for ~4x oversampling. This also uses the "AU over stdout" output file format described next, instead of a temporary file with the higher sample rate.
saugns -r 192000 -o - script(s) | sox - -r 44100 a.wav
The --mono option can be added to downmix to mono and write a mono file. For WAV files containing only mono sounds, this halves the space usage. (But external compression tools and formats, like FLAC, can losslessly compress away stereo duplication anyway.)
It's also possible to produce AU files by using -
(for stdout) as the filename, as a special case. When streaming a
file, only AU among the well-recognized simple formats allows the
length to be unspecified in the header – at least portably.
As WAV is more common, it remains the format used in other cases.
saugns -o - script(s) > a.au
If you need further format conversion or editing of WAV files, AU files or streams, or raw audio data, other tools will be needed. For example, FFmpeg, SoX, and Ecasound are more generally capable command-line tools (unrelated to this project). It's also possible to send audio data to those and other tools raw over stdout instead of with a format.
AU over stdout is the most convenient way to interface with some external programs without using temporary files. E.g. SoX, FFmpeg can recognize audio format settings (number of bits, channels, sample rate) using the AU header, instead of having to duplicate those as command-line arguments, as is needed when piping raw audio over stdout. Both SoX and FFmpeg support many formats, and can also pick the output format to use by the output filename extension.
With SoX it's easy to use to e.g. write to a FLAC file.
saugns -o - script(s) | sox - a.flac
With FFmpeg, the same thing is also simple.
saugns -o - script(s) | ffmpeg -i - a.flac
There's no built-in saugns command for producing several output files in one go, but this can be done with shell-scripting or a Makefile. Used with a format conversion program such as SoX, this can turn a collection of SAU scripts into MP3s, Ogg Vorbis files, etc., in one go. An optionally used Makefile for this is included with saugns example scripts, and can also be found in the extra-scripts collection where it is further described; it's tweakable and makes it easy to only (re)render files according to need, when one's scripts to render are changed.
For interfacing with other programs that accept raw 16-bit audio data,
the --stdout option can be added to copy audio to stdout. If
options for playing scripts are used, system audio
is still on by default. But if writing a WAV file,
running muted is still the default. This can as usual be changed with the
options to run audible (-a) and run muted (-m).
When system audio output is produced, the copying to stdout is done in parallel, at the same limited pace. This may be desirable for programs to visualize an audio stream, for example for a live spectrogram. But if the program running in parallel takes too much CPU time to do its work, there is the risk of stuttering. Experimenting to see how well it works for the system and configuration is best.
An alternative to raw data exists, for sending audio with an AU format
header over stdout. This uses the file output option -o with
- as the filename. Both cannot be
used at the same time.
Values can be passed to scripts using the saugns variable=value command-line option, which can be used any number of times to set some numerical variable. For this to do anything (unless the variable set has its own special behavior), the script needs to be written to make use of such $variable values within it.
Here's a trivial example of a script we'll call "beep.sau", which expects a named value "length" to be passed to it. If ran without setting length to some value, it will fail with a message that passing the value was expected. This behavior comes from the check for the variable inserted on the first line.
$?length W t$length
saugns length=10 beep.sau
The variable=value argument (here length=10) can also be placed after the filename. If several scripts are ran at once, every variable assignment applies to each script.
Alternatively, the script source could have had the ? after the variable name and provided a fallback value (as in $length ?= 1) to silently accept the lack of a passed value. Which to use depends on whether passing the value is meant to be required or optional, in the particular script. It's also possible to pick a middle option, by writing as above combined with providing a fallback value ($?length = 1), which makes the script warn that the value was expected but then go on to run anyway.
Note that the variable=value command-line option does not accept the full mathematical expressions of the SAU language for the value, only a plain number with or without a decimal point.
Most scripts produce an unvarying result (audio or -p printout) whenever ran with the same options. Scripts can however use the time() SAU language function to get a timestamp, used to seed randomness (as in $seed=time()) or otherwise behave differently at different times.
This variability can be controlled using the -d (deterministic mode) command-line option when handling a script. Using it forces the script to always do the same thing given the same options, which can be useful for testing. (Currently, this option only changes time() to make it return 0, but it could possibly do more in future versions.)
Randomness is in any case pseudo-random and its starting point set or reset via the magic variable called $seed. Strictly speaking, there is nothing nondeterministic ever going on, but for practical purposes, behavior varying with unvarying options can be called so.
As with shell scripts and various other types of scripts, a Unix shebang can be used for SAU scripts. Placing #! at the very beginning of a script, followed by the full path to the installed saugns binary, makes the file run using saugns when the file is used by itself as if it were a program. This also requires the script file to have the execute permission set (as in chmod +x filename).
This is generally most useful for creating sound-playing files – and saugns gets going producing audio very fast when such a file is launched. The shebang line on top can optionally include e.g. a specific playback sample rate to use for the script, as it does in the following example (where 48000 Hz is set).
#!/usr/local/bin/saugns -r48000
Of course, other arguments could be included after the path to saugns to instead make the script do something like (also) print info about itself, or write to some WAV file path included in the shebang line.
Passing variables to a script can be done when executing a script set up to run like this; variable assignments can be placed after the script file path, and not only before, which corresponds to the resulting invocation of saugns. (If the "beep.sau" example in that linked above section is changed to be executable, the corresponding way to run it would be ./beep.sau length=10.)