Documentation
Getting started
Being an overview of how to start and use Auditorium.
Getting and installing the programs
You can find source code, precompiled code and Java Web Start versions of Auditorium on the download page. Any one will do, although if you wish to use 3D video modules and are not running Mac OS X you may wish to download the source or precompiled versions.
If you choose Java Web Start, click the 'Video Processor' link on the download page and move to 'Setting up the video server'.
Otherwise we've got a bit more work to do. In order to run Auditorium from source or precompiled class files, you'll need to install a few other bits and pieces. These are:
Required:
Optional:
Java3D can be found at the Sun website, along with instructions of how to install. JavaOSC is a Java implementation by Chandrasekhar Ramakrishnan of the Open Sound Control protocol - a standardised way of sending audio data between applications. It can be found at the Illposed Software website.
ODE-Java is only required if you wish to run output modules that use it - currently the only one bundled with Auditorium is Bouncy Cubes 3D. It is available on the ODE-Java website. If you don't install ODE-Java, then this video module won't run, but you are free to run any other modules you wish.
Starting the programs
Java Web Starters can skip this section as all you need to do is click the links on the download page.
To start the video server, you can either download a helper script, or start it with the following command line argument:
java video.VideoProcessor
If using 3D modules, you may wish to increase the default stack size to something larger. Here I set it to 100MB:
java -Xss100M video.VideoProcessor
To start the audio processor, use a helper script or issue the following command:
java gui.Project
There shouldn't be a need for any special memory management with the audio processor.
Setting up the video server
After starting the video server, you will be presented with the following window (the exact apperance will depend on your operating system):
The port numbers specified for the OSC and control ports must be available on your machine - they cannot be used by other applications. If this is the only instance of the video server you are currently running, the default values should be fine. If you have problems, try different (higher) port numbers.
Full screen mode is supported on Windows and Mac OS X only.
After clicking Go, you should either be presented by a logging window, or a blank window displaying your chosen port numbers, depending on what logging options you chose.
Connecting to the video server
Now it's time to fire up the audio processor. The brains of the operation, if you will. Refer to the section Starting the programs for this.
When the program starts, you are presented with the following window:
Click the 'Add server' button in the top left of the window, and a large icon that looks like an overhead projector will appear. Click on the icon and the area below the 'Add server' will change. Enter the host name (a DNS name like 'localhost' or an IP address will do). Then enter the OSC and control ports chosen as part of the last step into the 'Remote OSC port' and 'Remote control port' fields. Finally, enter a local port to use as a control port and click 'Connect'. If all goes well the red 'Not connected' box should go green. You may have to wave your mouse over that portion of the window a bit to get this to happen.
If it does not work, have a look in the logging windows in both this and the video server.
Sending a video output module
Now that your audio processor is connected to a video processor, make sure that the video processor icon is selected (with a green box around it). Scroll the left hand pane down until you see a list of output modules.
Select the one you wish to send and hit the 'Send' button. After a short delay, the video server should open a new window displaying the output module. This may well just be a black window.
Adding a MIDI instrument
To add a MIDI instrument to the mix, first ensure that all the relevant hardware is attached to the computer and working.
When you click the 'Get interfaces' button, the empty list field beneath it should become populated with the available devices on your system. If your device does not appear, then the Java Virtual Machine cannot currently communicate with it. Please ensure that it is properly installed.
Select the interface you wish to add, and click the 'Add interface' button beneath it. A new icon should appear in the right hand panel.
It is worth noting at this point that the list of interfaces presented will most likely include items that cannot be used with Auditorium. For example on my laptop, it shows the modem. So if you try to add an interface and an icon doesn't appear or cannot be turned on (see the next step), it's possible that it does not support the kind of interactions we are attempting.
Linking instruments to video servers
Click the icon that represents the interface you want to connect to a video server. A green box should surround it. From the menu that appears in the far left pane, click the 'Link to output' button (you may have to scroll down), and the green box should turn blue.
Now, either click on the video server you want to connect it to, or click in some empty white space and drag to it, then release over icons where the box turns around them turns yellow. Note that you cannot attach one audio interface to another this way. You can however connect individual audio interfaces to multiple video servers, which can lead to some quite cool effects.
If you do not have any MIDI instruments to hand, one is provided for you in the shape of the last entry in the interfaces list - a 101 key keyboard. If you add this to your setup, you'll see it has a different icon to other devices.
Sending data
What you came here for. You should now have an audio interface or two connected to a video processor that's running a video output module and waiting for some input.
Select the audio interface icon you wish to use, and from the panel menu on the left, click the 'Turn on' button. If all goes according to plan, the little red 'Off' should turn to a green 'On'.
Play a few notes on your instrument and you should see some sort of output from the video processor.
Pausing and moving around your scene
Most of the video output modules bundled with Auditorium support some degree of interaction. Pausing can normally be done by hitting the space bar and you may be able to move around a 3D scene while paused or moving by either using the mouse or keyboard.
Fin
That's it! Check out the developer pages for information on how to write your own video output modules and even your own instruments.
