Sfront is written in ANSI C and uses only ANSI C libraries. When executed, sfront creates ANSI C files that only use ANSI C libraries.These attributes make sfront portable over a wide number of platforms, with ancillary files (makefiles, project files, etc.) and real-time support being the primary portability issues.
The S, M, and P columns indicate support for audio output and input to soundcards, MIDI control input from an external controller, and plug-in support.
Sfront compiles MPEG 4 Structured Audio (MP4-SA) bitstreams into efficient C programs that generate audio when executed. It supports real-time, low-latency audio input/output, MIDI input from soundcards, and Network Musical Performance.
MP4-SA is a standard for normative algorithmic sound, that combines an audio signal processing language (SAOL) with score languages (SASL, and the legacy MIDI File Format).
This package includes the sfront application, the sfront manual and "The MPEG-4 Structured Audio Book", a book on sound modeling and sequencing using MP4-SA.
We develop sfront under Mac OS X; the sfront user community is instrumental in porting and testing to other platforms.
Thanks to Ross Bencina, Richard Dobson, Michael Gogins, Peter Maas, Kees van Prooijen, and Tim Thompson for Microsoft support. Thanks to Bertrand Petit for FreeBSD support. Thanks to the coreaudio-api and darwin list members, and Manfred Brockhaus, BUYO-BUYO-IGOR, Phil Burk, Richard Dobson, Dominic Mazzoni, and Juno for Mac OS support. Thanks to Michael Pruett for IRIX support. Thanks to Jeremy Voorhis and Christian Haines for testing AudioUnit plug-in support.
Download Source Package:
Downloading Sfront.
Sfront is free software, distributed under the terms of the BSD license (without advertising clause). See the right panel to learn how to download the source distribution.
Unpacking wxyz.tar.gz files
The source distributions intended for Mac OS X, Linux, and generic UNIX systems are in the form of a UNIX tar file, compressed with the gzip utility (i.e. wxyz.tar.gz, or perhaps wxyz.tar if your browser automatically uncompresses files). The commands:
gunzip sfront.tar.gz
tar -xf sfront.tar
tar -xf sfront.tar
should unpack this file and create the directory sfront. If the download generates the file sfront.tar, only execute the second command.
Unpacking wxyz.zip files
The distributions intended for Windows systems are in the form of a ZIP archive. Use a tool such as Pkunzip or WINzip to unpack this file and create the directory sfront.
The sfront directory tree
If you downloaded a tar.gz or zip file, unpacking the file will create a set of subdirectories under the sfront directory:
% cd sfront
% ls
examples/ sfman/ src/ bin/ lib/
The examples directories holds set of MP4-SA files to test sfront.
The src directory holds the source code to sfront.
After compilation, the bin directory holds sfront binaries.
The lib directory holds SAOL programming libraries, including the Slib library of low-level utilities.
The sfman directory holds a copy of the HTML manual you're reading right now, which starts at
sfman/index.html
Other files and directories may also be present.
Compiling sfront.
To compile sfront under UNIX, begin by cd'ing to the sfront/src directory. Edit the Makefile in this directory, making the changes suggested on the right panel.
Once these changes are made, simply type
make install
If all goes well, this command will trigger the compilation of all the C source files that make up sfront, then link the object files to create the sfront binary, and finally copy the binary to the bin directory specified by the Makefile.
If all doesn't go well, please let us know so we can do our best to fix the problem. See these instructions for sending a bug report.
Testing sfront.
The sfront distribution includes a set of example files, to test different aspects of the program. The example files are located in subdirectories that are in sfront/examples. If you installed a packaged version of sfront, copy /usr/doc/sfront/examples to your home directory). Not all sfront distributions contain the same examples, due to file size and legal issues.
Each of the example directories share a common structure. The directories include a Makefile, a SAOL file, and any other files needed in the example. See the right panel for a description of the examples.
Entering any of these directories and typing make results in the generation of an output.wav audio performance (an exception is the example in, which cannot be made until example beat is made). Mac OS X users may need to change the CC in each Makefile, from "gcc" to "cc".
The simplest example is examples/min, which should exist in all sfront distributions. Enter this directory, type make, and the command should finish a few seconds later, after running
- sfront, which produces the file sa.c.
- The C compiler, which compiles sa.c to produce sa.
- The object file sa, which creates the file output.wav.
For your convenience, the top-level examples directory contains a Makefile that generates the output.wav file for all of the examples at once. Typing make at this level runs all of the examples in order. Depending on your machine, this may take a good fraction of an hour to run.
SAOL development using sfront is easiest to do using make. You may wish to copy the Makefile from one of the examples for your own development work. The right panel shows the list of commands recognized by each Makefile.
The rtime directory contains several examples of audio playback, real-time interactive, and AudioUnit plug-in uses of sfront. These examples generate real-time low-latency audio output, in response to MIDI and audio input.
The right panel describes these examples. All of the examples run under Mac OS X, and all non-plug-in examples will run under Linux. Some of the examples should run in other environments with real-time sfront support, including SGI Irix and Microsoft Windows.
We have tested these examples on an x86 Linux (32-bit, gcc -m32) machine using the standard Linux OSS drivers and a PCI 128 soundcard, and on an Apple Powerbook G4 550 Mhz with an Edirol UM-1S USB MIDI interface.
To run an example under Linux, cd into its directory and type make. To run a (non-plugin) example under Mac OS X, copy Makefile.osx to Makefile and type make. Examine the README file in each directory to learn how to modify the example for other environments.
To build an AudioUnit example under Mac OS X, cd into its directory and type make install (for the plug-in examples, the default Makefile in the directory is the OS X Makefile).
Interactivity and Plug-Ins.
Examples in the examples/rtime/ directory are real-time applications, that generate audio output in response to audio and MIDI input signals.
name test coverage
------------------------
aatest the simplest audio
test -- streams a
MIDI file to audio out.
ascii monophonic sine-wave
instrument, played via
the ASCII keyboard.
linain simple reverb unit, that
processes audio input
and generates audio out.
linmidi polyphonic sine-wave
instrument, triggered by
signals on the MIDI In
port on the soundcard.
linbuzz a real-time instrument
like linmidi, that uses
Slib to add pitch wheel,
mod wheel, and channel
volume controls.
linvoc envelope follower patch,
that uses MIDI In and
audio in signals together
and generates audio out.
au/hiss an AudioUnit Effect plug-in
that adds random noise to
the audio input.
au/sin an AudioUnit MusicDevice
plug-in that is a simple
sine-wave virtual instrument.
au/lpf an AudioUnit Effect plug-in
that is a low-pass filter.
Lpf includes a Cocoa UI
view, and is based on the
FilterDemo example in Apple's
AudioUnit Programming Guide.
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.
- -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.
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 aucontrol. An AudioUnit control driver, that must be used for the Effect AU type. AudioUnits are the standard plugin format for Mac OS X.
- -cin aucontrolm. An AudioUnit control driver, that must be used for the MusicDevice and MusicEffect AU types. AudioUnits are the standard plugin format for Mac OS X.
- -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".
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.
- -null-program. When enabled, if the program number of a MIDI Program Change command on a channel does not map to the preset tag of any SAOL instr in the program, subsequent MIDI NoteOn commands on the MIDI channel are ignored. Note that by default (no -null-program flag), a Program Change command selecting a non-existent SAOL instr would be ignored, and subsequent MIDI NoteOn commands on the MIDI channel would create new instances of the SAOL instr that was previously bound to the MIDI channel.
Incompatibilities.
Sfront translates MPEG4 Structured Audio Object 3 bitstreams (plus MIDI functionality from Object 4).
It does not handle Object 1 (equivalent to MIDI files), Object 2 (sasbf synthesis driven by MIDI files), or Object 4 bitstreams (Objects 1-3, plus sasbf and MIDI file integration into SAOL).
In addition, sfront is currently non-compliant in the following major ways:
- If the SAOL global parameter interp set to 1, sfront implements band-limited interpolation for most core opcodes that use interpolation. However, the grain() opcode uses linear interpolation for envelope and wave tables.
- AudioFX-related core opcodes are implemented, since sfront isn't integrated into an MPEG 4 system. However, AudioFX related standard names are available to the control driver interface for reading and writing, and SAOL programs can see these changes.
- Array, oparray, and tablemap indexes are not checked for illegal array index values.
Custom Search
If you liked this article, subscribe to the feed by clicking the image below to keep informed about new contents of the blog:
0 commenti:
Post a Comment