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.

Contents

Playing scripts or strings

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 "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 system audio device

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.

Stereo or mono downmix?

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.

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)

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

Other file formats

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, SoX and Ecasound are both 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. For example, SoX 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. It's easy to use to e.g. write to a flac: (SoX supports many formats and can pick one to use by the filename entered.)

saugns -o - script(s) | sox - a.flac

Piping raw audio to stdout

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.

Files with shebangs

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.