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 N columns indicate support for audio output and input to soundcards, MIDI control input from an external controller, and sfront networking 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. The Debian project offers a binary distribution of sfront, which is maintained by Enrique Robledo Arnuncio. We develop sfront under Mac OS X and Linux; 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. |
Platform StatusOS Type | R | S | M | N | ---------------------------------- Linux 2.4 | x | x | x | x | Mac OS X 10.3 | x | x | x | x | MS Windows | x | x | ? | | IRIX 6.5 | x | x | | ? | Solaris 2.6 | x | | | x | FreeBSD 3.4 | x | x | ? | ? | BeOS 4.5 | x | | | | HPUX 9.x | 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. N: Sfront networking 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 10.3, compiles (slowly!) 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 GNU Public License. See the right panel to learn how to download the source distribution. An official Debian package for sfront also exists. 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.88, 12/26/04A 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. Sfront also has an official Debian package maintained by Enrique Robledo Arnuncio. Enrique's package may contain a slightly older sfront version than the source distribution above. 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 Mac OS X pre-10.2, the Developer Tools installs gcc as cc, and so "gcc" above 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 runs well on 10.3, using the gcc compiler that ships with OS X Developer Tools (see right panel). Sfront supports the low-latency audio I/O under OS X using the CoreAudio framework. 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 XThe boxed Mac OS X set includes a developer CD, that contains the Apple cc compiler and many other development tools. Some new Macs have these developer tools installed at the factory. You can 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 ExamplesThe 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 that the Makefiles recognize. |
Makefile Usageinvocation 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 networking uses of sfront. These examples generate real-time low-latency audio output, in response to MIDI and audio input; several examples use the Internet to connect several sfront clients interactively. The right panel describes these examples. All of the examples run under Linux and Max OS X, and 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 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 an 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. |
Interactivity and NetworkingExamples 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. mirror tests sfront networking, using a Berkeley-based testing service. nmp_audio a client for network musical performance. nmp_null a network testing utility for use with nmp_audio nmp_stream a client for streaming MIDI files with low latency over a network. |
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 |