Back to main page.

Usage of the saugns program

Usage examples for the saugns program, and some further notes. For the script language SAU, see the language page, or the doc/README.SAU file (GitHub view).

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.

Playing scripts or strings

To simply play a script with the default sample rate:

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 "Osin f20 f{v20000 cexp} 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)

Changing audio device

The audio device used for playback can be changed using the AUDIODEV environment variable, similarly to in other software supporting it:

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.

Checking scripts

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.)

Writing audio files

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 for sounds with too-wide frequency spectrums, it's best to instead write a WAV file with a higher sample rate and then use a separate tool to downsample with quality if you want a lower final sample rate.

saugns -r 44100 -o a.wav script(s)

If you need further format conversion or editing of WAV files, other tools will be needed. For example, SoX and Ecasound are capable command-line tools (unrelated to this project).