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 binary distributions for Linux, and a generic source distribution for other platforms (Microsoft Windows, Mac OS, and many UNIX variants). We develop sfront under 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, Bertrand Petit for FreeBSD support, Manfred Brockhaus, BUYO-BUYO-IGOR, Phil Burk, Richard Dobson and Dominic Mazzoni for Mac OS support, and Michael Pruett for IRIX support.
|
Platform StatusOS Type | R | S | M | N | ---------------------------------- BeOS 4.5 | x | | | | FreeBSD 3.4 | x | x | ? | ? | HPUX 9.x | x | x | | x | IRIX 6.5 | x | x | | ? | Linux 2.2 | x | x | x | x | Mac OS X 10.1 | x | ? | | x | Solaris 2.6 | x | | | x | MS Windows | 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.1, compiles with cc. 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 files. Below, we describe how to unpack or install the different types of files you may download. Installing wxyz.rpm files
If your Linux system is set up to use the Red Hat package
manager, you can install sfront on your system by becoming
root and executing:
This command installs the sfront executable as
/usr/bin/sfront, a copy of this manual and a set of examples
in /usr/doc/sfront, a set of SAOL libraries in
/usr/lib/sfront, and a simple man page (type "man sfront")
to read it. Use the URL:
to read the local copy of the manual. Note that installing a new version of sfront deletes all files from the older version, so personal files should not be stored in the /usr/doc/sfront and /usr/lib/sfront directories. Installing wxyz.deb filesThe directions below are correct for the Debian packages found on the Berkeley website. Other Debian packages for sfront may exist: note that the description below might not accurately describe these packages. If your Linux system is set up to use the Debian package manager, and is running Debian 2.2 (potato) or later, you can use dpkg or delect to install the wxyz.deb. If you are running Debian 2.1 system (slink), you will need to download an sfront source distribution and compile it yourself. (wxyz.deb installation on a slink system will appear to go correctly, but sfront will crash when executed).
After installation of the wxyz.deb package, the sfront
executable as /usr/bin/sfront, a copy of this manual and a
set of examples in /usr/doc/sfront, a set of SAOL libraries
in /usr/lib/sfront, and a simple man page (type "man sfront")
to read it. Use the URL:
to read the local copy of the manual. Note that some Debian documentation about the sfront installation will reside in /usr/share/doc/sfront. Installing a new version of sfront deletes all files from the older version, so personal files should not be stored in the /usr/doc/sfront and /usr/lib/sfront directories. Thanks to Enrique Arnuncio and Joey Hess for help with the Debian package. Unpacking wxyz.tar.gz files
The source distributions intended for UNIX and Macintosh OS X 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. If you downloaded one of the tar.gz files that included pre-compiled Linux binaries, simply put sfront/bin/ in your path to access the binary file sfront. This file may also be moved to other locations without problems. 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. The bin directory holds precompiled binaries, if any. 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. If you downloaded a Redhat or Debian package, these subdirectories are located under /usr in your system, as described earlier (rpm deb) in this section. If you downloaded an executable ...If you downloaded a distribution that included an sfront executable, click here to skip past next section of the manual (the section you skip describes how to compile the sfront sources). |
Download sfront 0.79, 11/04/01A Linux distribution is available, that includes binaries. A source distribution is available, which works well on generic UNIX platforms and for DOS/Windows platforms. To read about changes since the last distribution, read this change log. For Linux:Click on [sfrontlinlite.tar.gz : 0.77 MB] or [sfrontlin.tar.gz : 4.85 MB] to download the minimal (sfrontlinlite) or complete (sfrontlin) version of sfront for Linux. The minimal version includes an executable, a small set of examples, and no sources. The complete version adds more examples and a full source tree. Click on [sfrontlinlite.i386.rpm : 0.78 MB] or [sfrontlin.i386.rpm : 4.4 MB] to download an RPM package for the the minimal or full version (except for source) of sfront. Click on [sfrontlinlite_i386.deb : 0.77 MB] or [sfrontlin_i386.deb : 4.4 MB] to download the Debian package for the minimal or full version (except for source) of sfront. Only for Debian 2.2 (potato) and later, not for Debian 2.1 (slink). For Other Platforms:Click on [sfront.tar.gz : 4.2 MB] or [sfront.zip : 4.4 MB] to download the full source distribution for sfront, which includes a large set of examples. Click on [sfrontlite.tar.gz : 0.64 MB] or [sfrontlite.zip : 0.78 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. 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.1, using the cc compiler that ships with OS X. Audio I/O is supported via the Carbon API. 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. |
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 the Linux Debian or Redhat packages, 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). 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 some of the examples should run in other environments with real-time sfront support, including Macintosh OS X and Microsoft Windows. We have tested these examples on an x86 Linux machine using the standard Linux OSS drivers and a PCI 128 soundcard. To run an example under Linux, cd into its directory 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 |