ninjam plugin

A plug-in client for Ninjam. Visit the Ninjam website before reading on or it won't make much sense to you.

why do a plugin client for Ninjam?

As you'll know if you use Ninjam there are various client applications already in existence. Generally though these are designed around the assumption that you're just using the computer to send and receive audio, and that your instruments are just fed into your computer's audio interface.

If however your instrument is your computer, it's not really possible to get audio in and out of the Ninjam system in a convenient way.

By having the Ninjam client in a plug-in, it makes it very easy to combine Ninjam into your normal computer-based music setup. It also gives you many more creative options for routing signals in and out of Ninjam, even without multichannel audio hardware attached to your computer.

open source

The Ninjam client code is open sourced (GPL) and so is this. Please see the list of limitations below for things that I need help with developing.


Current version: 1.1.0

plugin (Universal Binary, Audio Unit)
source code (xcode project) - see notes on building below


As built, the plug-in is a 4-in 9-out effect. (Since you can build it from the source code, you are of course welcome to build any configuration you find useful.) All my tests were done in Ableton Live and the descriptions below apply to that package.

NB some hosts (e.g. Logic, Digital Performer) cannot handle 4-in 9-out plug-ins. You'll need to rebuild it as e.g. a basic stereo plug-in to use this with those hosts.

To connect to a server enter the connection details in the field to the left of the 'Connect' button. The syntax is
server ; username ; password
If you're connecting anonymously, the username should be in the format anonymous:name and the password should be blank.

simple stereo in/out usage

Simply adding the Ninjam plugin to an audio track will achieve much the same result as using the standard standalone Ninjam client (though embedded in your audio host). All the standard Ninjam monitor mixing controls (volume, pan, mute, solo) work as expected. The stereo channel that is the plugin's input will be broadcast by Ninjam, and all the remote channels, local channels and metronome can be mixed into the plugin's stereo output.
For a slightly more flexible routing, you could use separate input channels for your two inputs, mixing them in the host before sending to the Ninjam plugin. This lets you e.g. apply separate effects to the two inputs.

extra output channels

Since the plugin defines 9 output channels (intended as 4 stereo pairs plus a mono output for the metronome), you can make more use of the host's routing capabilities to separate remote channels and the metronome onto different channels. In the image oppposite, the metronome has been assigned to channel 9 in the plugin, and is being routed out into a separate channel in the host.

extra input channels

In a similar way, you can access the other plugin inputs.

current limitations

  • Currently only exists as an Audio Unit plug-in (not VST).
  • Working folder hardcoded to a folder called 'ninjamplugin' on your desktop.
  • No control over saving session files.
  • Server license is automatically accepted - someone please help me make a popup dialog which doesn't crash the client.
  • List of output channels doesn't scroll when it exceeds the size of the window - again, I need help from a GUI expert to help with this one.
  • The GUI appears in its own window rather than embedded in the host's AU editor window. Arguably this is useful - however I did have embedding working, but only fully for composited windows. This option is #ifdef'd in the code.

building from source code

Download the source code above. NB this is an Xcode 2 project, for building on OS X 10.4 (Tiger). An Xcode 3/Leopard version has not yet been created. However, building the plug-in on Tiger and running it on Leopard is known to work.

In addition to the source code, you'll need

You'll need to build and install libogg if you don't already have it on your system. I recommend the following config command, which makes Universal Binary versions, and only static libs:

env CFLAGS="-O -g -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc" LDFLAGS="-Wl,-syslibroot,/Developer/SDKs/MacOSX10.4u.sdk" ./configure --disable-dependency-tracking --enable-static --disable-shared --with-ogg=/usr/local

(The final --with-ogg=/usr/local is only required when building libvorbis.)

Also, you need to apply my patches to the Ninjam client source code. These are in the 'diffs' folder of the source code download and are in GNU diff -u (generated by Perforce), and should be automatically applicable using 'patch'.

support/feedback/developer discussion

Since this is a) free and b) open source, I probably won't be supporting it to the same level that I do my other plugins. However I'm always happy to hear from people - see the 'contact' and 'forums' links to the left. There are also the Ninjam forums.