Sfront Reference Manual: Part I/5: Command-Line Options
Description: A part of the Sfront reference manual, that is a collection of reference materials. Sfront is a program that translates MP4-SA files into C programs.
Keywords: MP4-SA, SASL, SAOL, MP4, sfront, command line options.

### From The `sfront` Reference Manual by John Lazzaro and John Wawrzynek.

# 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 ignorned (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 `
-ain [name or fname.ext] | Audio input file/device
-aout [name or fname.ext] | Audio output file/device
-bandsize num | Player count
-bit fname | MP4 input file
-bitc fname | MP4 input file
-bitout fname | MP4 output file
-cin name | Control driver
-cpp | Use pre-processor
-except | Exception handling
-fec mode | Network algorithm.
-fixedseed | Random number seeds.
-gcc | System compiler
-hexdata | Encode data in hex strings
-Is | Preprocessor library
-isocheck | Debug option
-isosyntax | Strict SAOL syntax
-latency time | Playback latency
-lateplay | Network tolerance
-latetime t | Network tolerance
-license | Print license flag
-midi fname | MIDI input file
-midout fname | MIDI output file
-m_semitones num | Mirror transpose
-mstr fname | MIDI input file
-mv | MIDI verbose flag
-no-constopt | Optimizer flag
-no-inline | Optimizer flag
-no-rateopt | Optimizer flag
-o fname | C output file
-orc f1[,f2,...] | SAOL input file
-orcout fname | SAOL output file
-O0 | Optimizer flag
-passphrase | Network secret
-playback | Mode flag
-pporc | SAOL writing flag
-render | Mode flag
-sco fname | SASL input file
-scoout fname | SASL output file
-session name | Activate network
-sip_ip dotquad | SIP server
-sip_port num | SIP port
-sstr fname | SASL input file
-symtab | Symbol table flag
-timesync | Mode flag
`

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

#### Audio I/O Options Only one of the following output options may be used: `-aout fname.wav.` Writes fname.raw, a Microsoft WAV file. Note the .wav extension triggers this option -- fname can be any name. `-aout fname.aif.` Writes fname.aif, an AIFF file (Apple, SGI). `-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 configurations. These parameters may be set explicitly using the following option: `-latency time.` Sets the playback latency, in units of seconds. Try increasing the latency if playback clicks or stutters. Sfront chooses a default latency, based on the type of SAOL program (interactive or streaming) and the audio hardware type. The default interactive latency is usually a few milliseconds; the default streaming latency may be a few tens or a few hundreds of milliseconds. | #### `Windows DLL Issues` `
    To link sa.c files created with
    -aout pa_win_wmme ...

    Under gcc:

     gcc -O3 sa.c -lm -lwinmm -o sa.exe

    Under MS VC++:

     cl sa.c winmm.lib -o sa.exe

    To link sa.c files created with
    -aout pa_win_ds ...

    Under MS VC++:

      cl sa.c dsound.lib dxguid.lib
         winmm.lib -o sa.exe

    If complilation fails, see this
    FAQ for help
    with include path issues.

    Directsound programs may not link
    correctly with gcc, to try:

      gcc -O3 sa.c -ldsound -ldxguid
                   -lwinmm -o sa.exe
` #### `Windows Device Selection` `
    Multiple audio input or output
    sources may be available on
    your Windows machine. The
    pa_win_wmme and pa_win_ds
    drivers are set up with
    default sources. Environment
    variables select alternative
    sources. For example:

    set PA_RECOMMENDED_OUTPUT_DEVICE=1
    set PA_RECOMMENDED_INPUT_DEVICE=1

    uses an alternative source for both
    input and output (0 codes the
    default). Cycle through small
    integer values to find the
    source you want.
`

#### Networking options The C program sfront creates can communicate with other clients in a network session. Note that using network features could result in a malicious attack on your machine. USE AT YOUR OWN RISK. Currently, network sessions only carry MIDI commands that originate from the the `-cin` control driver. MIDI commands are sent to all other session participants. The options below activate networking. `-session name.` The name of session, chosen by the session participants and treated as a secret. If the name contains space characters, it should be enclosed in double-quotes. The session name mirror has special semantics, described below. `-passphrase key.` A secret phrase, at least 20 characters long, shared among the session participants. If the passphrase contains space characters, it should be enclosed in double-quotes. May be omitted for the special mirror session; sfront generates a random passphrase in this case. Session participants should keep the session name and passphrase secret, because these items are used to cryptographically authenticate data arriving over the network. Without authentication, an attacker could play loud notes into your speakers and cause damage, or perhaps even take over your machine. The session name mirror has special semantics, and should not be used for regular session. The `-session mirror` option connects the client to a packet reflector client currently located in Berkeley California USA, that bounces back each RTP packet that contains MIDI data as soon as it arrives. The sonic effect is an echo note for each note played, whose echo time reflects the network delay. By default, this echo is also transposed up by 5 semitones. The following option changes this default. `-m_semitones num.` Number of semitones to transpose echo note, a positive number between 0 and 24. In theory, any number of clients may be in a session. In practice, more CPU and bandwidth is needed to sustain a session as the number of participants rise. By default, the client can only handle sessions with 2 other players. The following option changes this default. `-bandsize num.` Number of other clients in the session. Note that the SIP server can only currently handle 6-member sessions, and so num should never be more than 5. The Internet is an unreliable network; packets may be lost, delayed, or reordered in flight. Sfront uses algorithms to lessen the impact of lost and last packets on a performance. These algorithms may be tuned using the options below. `-latetime t.` If a MIDI NoteOn command arrives too late, the note is not played. The -latetime option sets how late is too late, and has units of seconds. If this value is set too small, practically all notes will be dropped; if it is set too large, very late notes will play. The default value of 0.04 works well on Internet 2. `-lateplay.` Sets the latetime to infinity. `-fec mode.` This flag sets the behavior of the forward-error correction system sfront uses to recover from lost packets. We describe each mode individually. `-fec standard.` The standard FEC algorithm. For vigorous MIDI keyboarding, this algorithm uses about 6 kilobits per second of network bandwidth. `-fec extra.` Adds extra protection for note initiation events, when compared with standard fec. Fewer notes will be dropped due to lost packets, at the expense of higher bandwidth. Note this does not help late packets. `-fec minimal.` Reduced protection relative to standard mode, but bandwidth uses decreases. Sonic effect is that sustained notes may play slightly past the time of release if packets are lost. `-fec noguard.` Reduces protection relative to minimal mode, but bandwidth decreases. Sonic effect is that a sustained note may play long past the time of release, until the musician generates a new MIDI event. Mostly used for testing. `-fec none.` No packet loss protection at all. Use for reliable networks, or for SAOL programs where all voices are percussive and execute SAOL `turnoff` commands after a fixed period of time. By default, the C program sfront creates tries to contact a SIP (session initiation protocol) server located in Berkeley California USA. This SIP server acts to coordinate the session. Someday, alternative SIP servers may exist. When that day arrives, the following options will become useful. `-sip_ip dotquad.` The IP number of the SIP server, expressed in dotted-quad format. For example, the dotted-quad 128.32.112.203 is the default SIP server at Berkeley (at the time of this writing). `-sip_port port.` The port number for the SIP server, expressed as an unsigned integer. For example, port number 5060 is the default SIP port. |

#### Pre-processor options SAOL and SASL files may be directed to a C pre-processor, by using the flags described below. `-cpp.` Process all files specified by `-orc`, `-sco`, and `-sstr` options using the C pre-processor available on the system. One of the system compiler options (described below) must be set to tell sfront how to run the pre-processor. `-gcc.` Use gcc as the system compiler. This option uses the ANSI C `system` function to invoke the pre-processor, and so should work on gcc-enabled UNIX and Windows systems. `-Is dirname.` Search directory dirname to locate files specified in `#include` lines. The environment variable `SFRONT_INCLUDE_PATH` is also checked for include search directories. Sfront expects this variable to hold one or more directory names, separated by colons. In addition, Sfront searches the /usr/lib/sfront directory. After pre-processing, extraneous semicolons (introduced by popular macro idioms) are stripped from the code to produce legal SAOL code. All semicolons which follow open or closed braces are deleted, and repeated semicolons are reduced to a single semicolon (except inside the send statement). This post-processing is needed because null statements are not legal in SAOL. #### Debugging options By default, sfront optimizes for speed, by implementing several code-generation techniques, and by not doing many run-time checks mandated by the MP4-SA standard. These flags change these defaults, and are useful during debugging. `-isocheck.` Turns on core opcode run-time checks mandated by MP4-SA standard. Once sfront implements run-time checks for arrays, oparrays, and tablemaps, this flag will also enable those checks. `-no-constopt.` Turns off the pre-computation of constant subexpressions. `-no-inline.` Turns off inlining of opcode calls into instrument body. `-no-rateopt.` Turns off rate optimizations. These optimizations find k-rate or i-rate subexpressions in a-rate expressions, and move the computation of these subexpressions to a slower rate. `-O0.` Equivalent to `-isocheck -no-constopt -no-rateopt -no-inline`. #### Conformance options By default, sfront deviates from the strict syntax and semantics of the MP4-SA standard. These flags make sfront more closely match the standard. `-isocheck.` Turns on core opcode run-time checks mandated by MP4-SA standard. Once sfront implements run-time checks for arrays, oparrays, and tablemaps, this flag will also enable those checks. `-isosyntax.` Disallow sfront SAOL syntax extensions. These currently include the `printf` statement, the ability to have more than one `global` statement in a program, and tolerance of stray semicolons as described in the pre-processor section. Note that the `-bitout` option always produces encoded SAOL and SASL in strict conformance with the MP4-SA standard. The extensions listed under the `-isosyntax` are converted into compliant SAOL during encoding. #### Legal options The `-license.`option prints out license info for Sfront. The message it prints is reproduced below: `` This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License (Version 2) as published by the Free Software Foundation. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA In sfront distribution, see file COPYING for the GNU General Public License, or see the next section of this chapter. |

Next section: Part I/6: Change Log and License | ##

Copyright 1999 John Lazzaro and John Wawrzynek.