Part I/5: Command-Line Options

Sections

• Command-line Options. Listed by function and alphabetically.

Command-Line Options

Usage: sfront [options]

Input Options

Only one of the following two options may be used:

• -bit mp4file. Specifies an MP4 Structured Audio bitstream as input. Only one bitstream may be specified. Both configuration and streaming blocks of the MP4 are read. Any samples in the bitstream are written out as WAV files using the names a#.wav, where # is an MP4 file symbol number. Any pre-existing files using these names will be deleted.
• -bitc mp4file. Like the -bit option, but reads the configuration block data while ignoring the streaming block data. Use the -bitc option, in conjunction with the file streaming control driver, for bitstreams with large streaming sections (like those created by sdif2mp4).
• -orc f1 [f2 f3 ...].Specifies one or more SAOL ASCII files. File order on the command line determines the position of each file's global block statements in the merged global block.

If the -orc option is used, the following options may also be used.

• -sco scorefile. Specifies a SASL file. Only one SASL file may be specified. To process multiple SASL files, concatenate them into one file first. Note that the timestamps need not be in temporal order. When creating an MP4 file, sfront places the SASL lines in the configuration section.
• -sstr scorefile. Specifies a SASL file. Behaves like the -sco option, except that when creating an MP4 file, sfront places the SASL lines in the streaming section.
• -midi midifile. Specifies a Format 0 or Format 1 MIDI file. Only one MIDI file may be specified. When creating an MP4 file, sfront places the MIDI events in the configuration section.
• -mstr scorefile. Specifies a MIDI file. Behaves like the -midi option, except that when creating an MP4 file, sfront places the MIDI events in the streaming section.
• -mv. Generates a verbose output when reading MIDI files, directly or via an MP4 file. Useful for orchestrating MIDI files created by someone else, to read the text comments for each channel, and to see which bank and patch change goes with each channel.

In addition to the static control input options above, dynamic input can drive the C file sfront generates, via the control driver interface. Only one control driver may be specified on the sfront command line, using the -cin option.

The following control drivers are available:

• -cin ascii. Simple real-time MIDI input from an ASCII keyboard. Each row of letter keys maps to a 2-octave pentatonic scale, notes have fixed duration. 0-9 select MIDI preset number, +/- change MIDI channel volume. See examples/rtime/ascii.
• -cin linmidi. Real-time input from the MIDI In jack of a soundcard under Linux, using the OSS API.
• -cin alsamidi. Real-time input from the MIDI In jack of a soundcard under Linux, using the ALSA API (ALSA's OSS-compatible mode may not work with the linmidi driver). Thanks to Steven Pickles.
• -cin alsaseq. Real-time MIDI input from the ALSA sequencer under Linux, a more sophisticated alternative to alsamidi. See this documentation for more details. Contributed by Enrique Robledo Arnuncio.
• -cin coremidi. Real-time input from external MIDI sources under Mac OS X. Be sure to connect the MIDI interface or device before starting the sa.c program. Up to 4 external MIDI inputs are supported. Virtual sources are currently ignored (with a warning message), but may be supported in a future release.
• -cin freebsdmidi. Read-time input from the MIDI In jack of a soundcard under FreeBSD, using the pcm API. This code has not been tested.
• -cin win32. Real-time input from the MIDI In jack of a soundcard under Windows. Should work with both pa_win_wmme and pa_win_ds audio drivers, but has not yet been tested.
• -cin gliss. Used by the examples/gliss example: produces piano glissando control input, with forward sweeps generating MIDI control, and reverse sweeps generation SASL control.
• -cin fstr. Reads streaming data from an MP4 file during the execution of the sa.c file. See this example for proper usage, or run the examples/claps example invoked with "make stream".

Streaming audio control drivers should be used with the -playback time management option. Interactive control drivers may be used with the -playback or -timesync time management options, depending on the audio driver in use.

See Part II/2 for information on adding your own control drivers to sfront.

Options By Category

Audio I/O Options
Code Output Options
Conformance Options
Debugging Options
Legal Options
Network Options
Pre-processor Options
Real-Time Options
Source Input Options

Alphabetical List

Code output options

These options specify output files written by sfront, or are flags that influence output file creation.

• -o cfile. Specifies the C file sfront writes out. If not specified, the file sa.c is used.
• -bitout. Creates a MP4 file output in addition to a C file. The files specified by the -orc, -sco, and and -midi commands are packed into the configuration part of the MP4 file, along with any samples specified in the -sco files. The files specified by the -mstr and -sstr commands are packed into the streaming section of the MP4 file, along with any samples used by SASL table lines in the -sstr file. Sfront cannot regenerate a -bit file into a -bitout file.
• -symtab. Includes a symbol table in the MP4 file created with -bitout. This makes the file longer, but allows decoders to create ASCII SAOL and SASL files with user-friendly variable names.
• -orcout. Generate an ASCII SAOL file. Useful when reverse engineering an MP4 bitstream.
• -scoout. Generate an ASCII SASL file. Useful when reverse engineering an MP4 bitstream.
• -midout. Generates a binary MIDI file. Useful when reverse engineering an MP4 bitstream.
• -except. When this option is enabled, the C file includes extra code that runs when the program ends prematurely (for example, due to a division by zero in the SAOL program), and gracefully shuts down audio input and output. Code produced by this option may not work correctly on non-POSIX systems. Thanks to Bertrand Petit.
• -fixedseed. When this option is enabled, the C file seeds the random number generator with the same value each time, ensuring the opcode calls that generate random numbers produce a deterministic number stream on each run of a sa.c program. If this flag is not specified, the random number generator seed is based on the current time of day, and so each program run produces a different result. This flag is primarily useful for testing. Thanks to Martin Marier and Michael McGonagle.
• -hexdata. When this option is enabled, the C file may encode arrays of numbers as hexadecimal strings to speed up the C compilation process, a platform-dependent technique that is not strict ANSI C. This technique is known to produce functional code that provides a significant speedup under gcc on Linux/x86; it is also known to produce buggy code under Solaris using the cc compiler.
• -pporc. When this option is enabled, -orcout produces parse tree for SAOL code that has been optimized by sfront in preparation for code generation.
• -interp [linear | sinc]. Instructs sfront to ignore the SAOL global interp parameter, and to instead perform linear interpolation (-interp linear) or band-limited sinc-function interpolation (-interp sinc). See this article for a description of the band-limited interpolation algorithm sfront implements. The tableread core opcode has special interpolation issues, as described in this part of the MP4-SA book).
• -sinc_zcross n. If band-limited interpolation is in use, set the windowed sinc interpolation function to have n zero-crossing for each lobe. The default value is 3. Higher values decrease aliasing but require more computation per sample.
• -sinc_pilen n. If band-limited interpolation is in use, set the table lookup approximation for the windowed sinc function to have n entries (n=128 by default). Note the sinc-function implementation does not linearly interpolate between loop-up entries. To avoid rounding artifacts, the table size should be increased if -sinc_zcross increases the number of zero crossings in the sinc function.

Audio I/O Options

Only one of the following output options may be used:

• -aout fname.wav. Writes fname.wav, a Microsoft WAV file. Note the .wav extension triggers this option -- fname can be any name. By default, fname.wav uses 16-bit samples. The names fname.wav-24 and fname.wav-8 specify the creation of a file fname.wav that uses 24-bit or 8-bit samples, respectively.
• -aout fname.aif. Writes fname.aif, an AIFF file (EA, Apple, SGI). Note the .aif extension triggers this option -- fname can be any name. By default, fname.aif uses 16-bit samples. The names fname.aif-24 and fname.aif-8 specify the creation of a file fname.aif that uses 24-bit or 8-bit samples, respectively.
• -aout fname.dat. Writes the ASCII file format of the view curve viewing tool, (a part of the Chipmunk tools). For single-channel output, writes the file fname.dat. For multi-channel output, writes the files fname1.dat, fname2.dat, ...
• -aout fname.raw. Writes fname.raw, a raw binary file. This file will contain channel-interleaved, 16-bit signed integers, in the native byte order of the machine. Note the .raw extension triggers this behavior -- fname can be any name. A companion ASCII, fname.raw.info, is also written, which has three lines: line one is the sampling rate, line two is the number of channels, line three is the total number of samples in the file.
• -aout linux. Send audio output to the audio hardware under Linux. Uses the OSS sound drivers (which also work under ALSA using OSS compatibility mode). Use a mixer application to set audio output source. When run as root, driver uses POSIX real-time features to improve audio quality. While we have carefully tested these root features, bugs in programs run as root can cause file-system damage: use at your own risk.
• -aout coreaudio. Send audio output to the audio hardware under Macintosh OS X, using the CoreAudio framework. To compile the sa.c file, add the -framework CoreAudio option on the cc command line. If your system does not have cc installed, join ADC Online and download the Apple Development Tools for free. Thanks to members of Apple's coreaudio-api and darwin mailing lists for help with the CoreAudio driver. Thanks to Phil Burk, Richard Dobson, and Dominic Mazzoni for help with an earlier Carbon-based version of this driver.
• -aout pa_win_wmme. Send audio output to the audio hardware under Microsoft windows, using the Windows MultiMedia Extension library. See right panel for linking instructions for sa.c files created with this audio driver, and for hardware selection details. Thanks to PortAudio, Phil Burk, Ross Bencina, Richard Dobson, Peter Maas, Kees van Prooijen, and Tim Thompson for help with this driver.
• -aout pa_win_ds. Send audio output to the audio hardware under Microsoft windows, using the Windows Directsound library. Users should install a recent copy of Developers DirectSound for best results. See right panel for linking instructions for sa.c files created with this audio driver, and for hardware selection details. Thanks to PortAudio, Phil Burk, Ross Bencina, Richard Dobson, Peter Maas, Kees van Prooijen, and Tim Thompson for help with this driver. Also thanks to Vincent Siliakus and Thomas Jongepier for work on an earlier DirectSound driver.
• -aout freebsd. Send audio output to the audio hardware under FreeBSD (pcm). Thanks to Bertrand Petit.
• -aout irix. Send audio output to the audio hardware of an SGI workstation running IRIX 6.2 or later. Output C file needs to be linked with -laudio. Thanks to Michael Pruett.
• -aout std. Send channel-interleaved, 16-bit signed integers, in the native byte order of the machine, to stdout.
• -aout null. Do not send audio output anywhere.
• -aout hpux. Send audio output to the audio hardware of a HP700 workstation running HPUX. Output C file needs to be linked with -lAlib. By default, sound is sent to the internal speaker; set the shell environment variable SPEAKER to EXTERNAL to drive the line out jack in the back of the machine.

Only one of the following input options may be used:

• -ain fname.wav. Reads fname.raw, a Microsoft WAV file. Note the .wav extension triggers this option -- fname can be any name.
• -ain fname.aif. Reads fname.aif, an AIFF file (Apple, SGI).
• -ain fname.dat. Reads the ASCII file format of the view curve viewing tool, (a part of the Chipmunk tools). Reads the first curve in file fname.dat and sends its data to all input channels. Ignores the x parameter of the curve.
• -ain fname.raw. Reads the raw binary file fname.raw. This file should contain channel-interleaved, 16-bit signed integers, in the native byte order of the machine. Note the .raw extension triggers this behavior -- fname can be any name. An ASCII fname.raw.info, is also written, that contains information on how the file was read. This file has three lines: line one is the sampling rate, line two is the number of channels, line three is the total number of samples in the file.
• -ain linux. Read audio input from the audio hardware under Linux. Uses the OSS sound drivers. Use a mixer application to set audio input source.
• -ain coreaudio. Read audio input from the audio hardware under Mac OS X, using the CoreAudio framework. To compile the sa.c file, add the -framework CoreAudio option on the cc command line. If your system does not have cc installed, join ADC Online and download the Apple Development Tools for free. Thanks to members of Apple's coreaudio-api and darwin mailing lists for help with the CoreAudio driver. Thanks to Phil Burk, Richard Dobson, and Dominic Mazzoni for help with an earlier Carbon-based version of this driver.
• -ain pa_win_wmme. Read audio input from the audio hardware under Microsoft windows, using the Windows MultiMedia Extension library. See right panel for linking instructions for sa.c files created with this audio driver, and for hardware selection details. Thanks to PortAudio, Phil Burk, Ross Bencina, Richard Dobson, Peter Maas, Kees van Prooijen, and Tim Thompson for help with this driver.
• -ain pa_win_ds. Read audio input from the audio hardware under Microsoft windows, using the Windows Directsound library. Users should install a recent copy of Developers DirectSound for best results. See right panel for linking instructions for sa.c files created with this audio driver, and for hardware selection details.. Thanks to PortAudio, Phil Burk, Ross Bencina, Richard Dobson, Peter Maas, Kees van Prooijen, and Tim Thompson for help with this driver. Also thanks to Vincent Siliakus and Thomas Jongepier for work on an earlier DirectSound driver.
• -ain freebsd. Read audio input from the audio hardware under FreeBSD (pcm). Thanks to Bertrand Petit.
• -ain irix. Read audio output from the audio hardware of an SGI workstation running IRIX 6.2 or later. Output C file needs to be linked with -laudio. Thanks to Michael Pruett.
• -ain std. Read channel-interleaved, 16-bit signed integers, in the native byte order of the machine, from stdin. This is the default option.
• -ain null. Read silence (all channels set to zero).
• -ain hpux. Reads audio output to the audio hardware of a HP700 workstation running HPUX. Output C file needs to be linked with -lAlib. By default, sound is read from front-panel microphone input, and audio output is forced to be internal speaker by hardware constraints.

If an audio input or output is needed and -ain or -aout is not on the command line, the WAV files input.wav and output.wav are used as defaults.

If the srate or inchannels global parameters are not set in the SAOL global block, sfront queries the audio input source for the correct sampling rate and input width. Since sfront, and not the sa.c program, does the query, the file specified by the file-input -ain options must be available when sfront runs.

See Part II/3 for information on adding your own audio drivers to sfront.

Time-management options

Sfront programs run under one of three temporal modes: render, playback, or timesync. Each mode defines a set of real-time behaviors.

Sfront sets a default temporal mode to suit the requirements of the chosen audio drivers. The time-management command-line options described below override the default temporal mode. These options are mutually exclusive; if multiple options are given, the last one is used.

• -render. Execute the SAOL program as accurately as possible. Update the SAOL standard name cpuload if a real-time driver is in use; set cpuload to 0 if no real-time drivers are in use.
• -playback. Compute audio output with the goal of meeting real-time constraints. Compromise audio quality if necessary to prevent buffer overruns. Always update cpuload.
• -timesync. Follow the behavior described for playback mode, and also force the program to use at least 1 ms of real time to compute 1 ms of audio, by temporarily halting program execution if audio is computing too fast. This mode is rarely needed: real-time drivers usually default to playback mode, and use implicit techniques to handle compute-ahead issues.

The algorithm for real-time playback includes several parameters, which default to sensible values for typical hardware configurationn-basedof this driver.