| mp4-sa-> sfront reference manual-> installing sfront |
Sections
|
IntroductionIn this chapter, we describe how set up sfront to work on your machine, and how to test sfront to make sure it works properly. |
|
Supported PlatformsSfront 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 right panel shows the platforms sfront is currently known to work. A checkbox in the R column indicates basic file rendering functionality. 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. We currently provide a generic source distribution, suitable for use on most UNIX variants (including Linux and Mac OS X) as well as Microsoft Windows. 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. |
Platform Status
OS Type | R | S | M | P |
----------------------------------
OS X 10.7 -m32 | x | x | x | x |
Linux 2.4 -m32 | x | x | x | |
Linux 2.6 -m64 | x | ? | ? | |
MS Windows | x | x | ? | |
IRIX 6.5 | x | x | | |
Solaris 2.6 | x | | | |
FreeBSD 3.4 | x | x | ? | |
BeOS 4.5 | x | | | |
HPUX 9.x | x | x | | |
----------------------------------
Key:
R: sfront can create a C file,
that when compiled and executed,
generates a WAV file containing
the performance.
S: C files that can handle
real-time audio output and input
from attached soundcards.
M: Real-time MIDI control input
from an attached MIDI controller.
P: Plug-in support.
x --> known to work
? --> untested drivers, please
report test results.
Compiler SupportSfront, and the C code sfront generates, compiles under gcc on all platforms. Under Windows, compiles using Microsoft Visual C++ compiler and Borland C++. Under Mac OS X, compiles with cc/gcc. Under Mac OS 9, sfront compiles, but the C code sfront creates is not completely stable (the sample wavetable generator and MIDI file input are the major issues). |
Downloading SfrontSfront 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:
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 filesThe 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:
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
Other files and directories may also be present. |
Download sfront 0.99, 8/31/11A source distribution is available, which works well on Mac OS X, Linux, MS Windows, and generic UNIX platforms. To read about changes since the last distribution, read this change log. Click on [sfront.tar.gz : 4.73 MB] or [sfront.zip : 4.92 MB] to download the full source distribution for sfront, which includes a large set of examples. Click on [sfrontlite.tar.gz : 1.03 MB] or [sfrontlite.zip : 1.23 MB] to download a minimal source distribution for sfront, which includes a smaller set of examples. An ANSI C compiler is needed to create the sfront binary and to compile sfront's output, and a version of make is needed to try the examples. If you are a DOS/Windows user and don't have these tools, click on [win_gnu.zip : 1.8 MB] to download a Windows port of the GNU gcc and make. Thanks to Ross Bencina for this package. |
Compiling sfrontTo 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
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. |
Makefile optionsBefore starting compilation, edit the Makefile and read the comments for suggestions on how to customize sfront for your environment. In particular: BINDIR = ../bin/ BINDIR is where the binary of sfront is copied. BINDIR defaults to the sfront/bin directory, but you may wish to put the binary somewhere else. The complete path for BINDIR must be in your shell path in order to use sfront on the command line. CC = gcc CC specifies the the C compiler. On early versions of Mac OS X, the Developer Tools installs gcc as cc, and so "gcc" must be changed to "cc". LINKLIB = -lm In some systems, LINKLIB will need extra options -- if you find that compilation works but linking fails, change this line. |
If you use Windows ...If you own the Microsoft Visual C++ or Borland C++ compiler, you can use it to compile sfront and the C files it creates, by following the directions above. Microsoft users will need to use the project files locating in the win/ directory to make sfront. These files were supplied by Richard Dobson. If you don't own a C compiler, you can download the Windows port of the GNU development tools, using the link on the right panel. Thanks to Ross Bencina for putting this download together. To fully use real-time audio support under Windows, you should download and install the latest version of Developer Microsoft DirectSound. |
GNU Tools for WindowsClick here to download a ZIP file (1.8 MB) that contains the Windows version of the GNU C compiler and GNU make. |
If you own a Mac ...We recommend Mac OS X for Macintosh users; sfront compiles and has been well tested on 10.7 (Lion) and 10.4 (Tiger). We do not have access to 10.5/10.6 machines, and so compatability reports would be appreciated. For stand-alone programs, sfront supports low-latency audio I/O under OS X using the CoreAudio framework. Sfront also supports the AudioUnit plug-in format. Sfront also compiles on Mac OS 9, using the the free MPW system to compile sfront and the C files it creates. Build sfront as an MPW tool and add it to your path, so that it can be used as a command-line tool in the MPW shell. Also build sa.c files as MPW-tools. MIDI file and sample file reading is unstable under MPW, and so several of the examples shipped with sfront will not work under OS 9. |
Developer Tools for Mac OS XFor 10.7/10.6 users, the Xcode developer tools are available as a free download via the Mac App Store application. Otherwise, the boxed Mac OS X set includes a developer CD, that contains the Apple cc compiler and many other development tools. Some Macs have these developer tools installed at the factory. Pre 10.6 userscan also obtain these tools for free, by becoming an ADC Online member, and downloading the tools from the ADC website. MPW for the Mac (Mac OS 9 only)Click here to download a free compiler and development environment for the Macintosh. |
Testing sfrontThe 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
If these commands execute, and if the output.wav file sounds like a short synthetic melody, then sfront works on your system. |
Sfront Examples
The number of examples in
your sfront distribution
depends on the type of
distribution you have.
Listed below are examples
which may included in your
version of sfront. ES
indicates the example was
written by Eric Scheirer.
name test coverage
------------------------
bach MIDI files
beat SASL table lines (ES).
claps AIF soundfile (ES).
elpelele MIDI files (ES)
gliss sfront control port.
in input_bus
min general-purpose
pc general-purpose (ES)
perc spatialize, reverb.
scr1 MIDI files (ES)
speedt WAV soundfile,
speedt core opcodes.
torvalds input_bus, soundfiles
vowels parametric filters (ES)
|
|
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. |
Makefile Usage
invocation function
------------------------
make create output.wav
make clean delete all created
files, including ~'s.
make mp4test tests binary encoding
make safe cp output.wav safe
make compare cmp safe and output.wav
make timing times ./sa execution
|
|
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.
|
BugsIf you use sfront extensively, or if you try to use sfront on a new platform, you will probably uncover bugs in the program. By sending a bug report along to us, you can help make sfront a better program. The right panel explains what makes a good bug report, and where to send the bug report. Next section: Part I/2: File Rendering |
Bug ReportsSend bug reports to: lazzaro@cs.berkeley.edu Ideally, include: -- ASCII versions of the SAOL and SASL files. -- The C file sfront produced, or the error message sfront produced. -- If the C file sfront produced didn't compile, the compiler error messages. -- If the file produced by sfront crashed while running, any ASCII messages printed by sfront or the OS. -- Information on the platform you're running on, including type of OS (including version number) and type of compiler (including version number). -- The version number of sfront. -- A short note explaining the problem, including what you heard. -- DON'T send any binary files (.mp4, output.wav, ect) at first -- I'll let you know if I need them later. |
| mp4-sa-> sfront reference manual-> installing sfront |