Software

Updated 27-May-08Includes Open Sound Control

WinZip

Windows users will need a way to uncompress .zip files. Try www.winzip.com. Linux and Mac users can use zip.

PortMidi

You will need the PortMidi library to compile Serpent. You will need to compile Serpent for Linux. You do not need PortMidi if you get binaries for OS X or Windows -- PortMidi is built in.

If the PortMidi migration to SourceForge and associated documentation is not complete and you need help, please contact rbd at cs.cmu.edu.

Windows users should note that there is or was a bug in the Windows MIDI drivers such that if a MIDI input port is left open when your application exits, Windows will crash. This is an obvious security hole that allows even unpriviledged applications to bring down the system (although I suppose Windows is full of such holes). PortMidi for Windows includes a DLL, pm_dll.dll, which is the best known (to us) means, short of running a secure MIDI server, to detect when an application exits and safely shutting down. This works, for example, when the user types control-C to a command-line application. The DLL is small, so I recommend that you just copy it to the same directory as any application you build. This dll is included with the Windows version of Serpent, below.

Serpent

Serpent Runtime for Windows, 10-Jul-07 Version

Serpent Runtime for Mac OS X, 10-Jul-07 Version

Serpent Source for Linux, Win32, 27-May-08 Version, 10-Jul-07 Version

Serpent is currently released in three zip files, one each for Win32, Linux, Mac OS X systems. This may change from time to time.

Each zip file contains two versions of serpent.

serpent -- command line version
wxserpent -- serpent with wxWidgets linked in to provide a graphical interface

The Win32 and Mac OS X zip files contain compiled executables. For Linux, download and compile the Source version.

The source files have been built on the following systems:

Windows (Visual C++, linked with wxWidgets 2.2.6), use the serpent.sln and wxs/wxserpent.sln "solutions". For wxserpent, edit the include paths and libraries according to your installation of wxWidgets (not included here). You will need the PortMidi library. The .sln files are set up assuming the portmidi and serpent directories share the same parent directory, e.g. mine are in e:/rbd/portmidi and e:/rbd/serpent.
Linux (Fedora Core 2, linked with wxWidgets 2.4), use Makefile and wxs/Makefile. You will need the PortMidi library and your system will have to have ALSA if you build Serpent with the default midi support.
Mac OS X (Version 10.4.2, gcc 4.0, wxWidgets 2.6.3)

You must install the Apple Developer tools.
install PortMidi.
You may have to use the command "sudo gcc_select 4.0" to switch to the version 4.0 GCC compiler, but probably installing xcode 2.3 will do this for you.
Build PortMidi (see documentation in PortMidi).
The Serpent code assumes the portmidi directory is at the same level, e.g. /home/rbd/portmidi and /home/rbd/serpent.
Use "make -f Makefile.osx" from the serpent directory to build serpent from the sources.
For wxWindows, install wxWindows 2.6.3. If you want a universal binary for wxSerpent, do not build wxWindows (see the next step).
Modify wxs/Makefile.osx if your paths do not match my paths. Use "make -f Makefile.osx" in serpent/wxs to build wxserpent from the sources. Alternatively, use "make -f wxWindows" followed by "make -f Makefile.univ", both in serpent/wxs, to make a universal binary version -- see the comments in the Makefiles.

Serpent Documentation

See the doc folder in your source or binary installation. There is a copy of the serpent documentation online.

Important: Serpent Environment

Serpent uses the environment to figure out where to search for files.

Under Win32, this is the registry entry: "My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Serpent\SERPENTPATH", which on my machine has the value "d:\rbd\serpent\lib\;d:\rbd\serpent\programs\;d:\rbd\serpent\wxslib". To set this, go to the Start menu and select "Run...", then type in "regedit" and click "OK". Use this editor to create and set the path. The RegEdit program gives you access to all kinds of critical internal settings for your machine. Be careful.
Win32 users should also (probably) set their shell environment so they can run serpent from any command line. Otherwise you'll have to type in the full path name for serpent.exe. Environment variables are changed in the control panel with the System control, the Advanced tab, and the the Environment Variables button, e.g. on my machine, I clicked New under "User variables for rbd" and added the variable named PATH with the value d:/rbd/bin, which is where I copy serpent.exe and associated DLLs, especially pm_dll.dll.
Under Linux, set the environment variable SERPENTPATH to something like "/home/rbd/serpent/programs:/home/rbd/serpent/libs:/home/rbd/serpent/wxslib". I do this by creating a file serppath with the line:
```
setenv SERPENTPATH /home/rbd/serpent/programs:/home/rbd/serpent/lib:/home/rbd/serpent/wxslib
```
Then, from the shell, I type source serppath to set the environment. Note that you cannot simply execute serppath as a shell command: this will create a new shell and set the environment in that shell. When the new shell exits, the environment is destroyed, and the current environment is left unchanged. If you have a .login file or a .cshrc file, you can set the environment there so you do not have to set the environment manually. If you use bash instead of tcsh or csh, see the Mac instructions below.
Linux (and Mac) users may want to copy their executables to ~/bin. Then, if you set up your search path appropriately, you can run serpent or wxserpent from any command prompt and any current directory.
On the Mac, I run Serpent from the command line, and set the environment just like in Linux. Chances are good you will be using bash on OS X, 27-May-08 Version
Find the newly installed program: Applications > SimpleSynth and run it.
For the MIDI Source, select "IAC Driver Bus 1"
Do not exit SimpleSynth, but you can select the yellow button to minimise its window.

Now, when you run Serpent (initializing its embedded PortMidi library), PortMidi will look for MIDI devices. By default it searches the IAC Bus first, and so "IAC Driver Bus 1" will be the first output device. The first device found is the default output device, so this is probably where you will send MIDI. You have configured SimpleSynth to receive from "IAC Driver Bus 1."

Make sure your audio is enabled and volume is up.

Linux

MIDI support on Linux varies. I use a Planet CCRMA Linux installation that has been configured for music work. There is support for USB MIDI devices. I can also use a software synthesizer, Timidity++. Timidity was originally designed to convert standard MIDI files to audio files, but it can also be configured to listen for MIDI in real time and synthesize audio. Since this is probably the most generic way to get MIDI output using Linux, I will provide details for this method. The "Linux Audio Users Guide - TiMidity Howto" is very useful if you have problems.

Download Timidity++ sources from SourceForge (I already had a TiMidity, but it was not configured to receive real-time MIDI, so I built a new version from these sources.)
After expanding the source archive, go to the top-level TiMidity directory and type
./configure --enable-audio=alsa --enable-alsaseq --enable-gtk;make
If all goes well, install by becoming root (su) and running this:
make install
TiMidity will complain about a configuration file:
timidity: Can't read any configuration file. Please check /usr/local/share/timidity/timidity.cfg
Since I had a previous installation, I used locate timidity.cfg to find the file (in /usr/share/timidity/) and copy it to /usr/local/share/timidity. If you do not have timidity.cfg, see the "
Run TiMidity as follows:
timidity -iA -B2,8 -Os -EFreverb=0

Now, see if TiMidity is working by going to portmidi/pm_test and runing ./test (user input is bold).

> ./test Latency in ms: 1 begin portMidi test... enter your choice... 1: test input 2: test input (fail w/assert) 3: test input (fail w/NULL assign) 4: test output 5: test both 6: stream test 4 0: ALSA, Midi Through Port-0 (output) 2: ALSA, TiMidity port 0 (output) 3: ALSA, TiMidity port 1 (output) 4: ALSA, TiMidity port 2 (output) 5: ALSA, TiMidity port 3 (output) Type output number: 2 Midi Output opened with 1 ms latency. ready to send program 1 change... (type RETURN): ready to note-on... (type RETURN): ready to note-off... (type RETURN):

At this point you should have heard a note. Continue typing RETURNs to prompts until the test program quits.

Note in this example that the portmidi output device number was 2. The default output device number is 0 (the first output), so to send MIDI to TiMidity, you will have to open device number 2 rather than the default device.