1. MaxJax
  2. Installing Twisted
  3. Creating a Twisted Webserver
  4. Starting the Twisted Webserver
  5. Installing MaxJax files
  6. Configuring MaxJax
  7. Editing index.html
    1. MaxJax.js api
      1. Toggle
      2. ToggleBank
      3. Bang
      4. MultiSlider
      5. PictSlider

MaxJax

MaxJax is a solution for real-time web based control of any open sound control enabled sound synthesis engine, using AJAX and the python Twisted Web framework. Several user interface elements are written in Javascript, which send data to the twisted server which then forwards the requests to the sound synthesis application over OSC. It is tested and fully functional in Firefox 1.5, Internet Explorer 6, Safari 1.3 and up, and Opera 8. Any computer running one of these browsers can control the sound synthesis in real time.

To run the server, follow the directions below.

Installing Twisted

First, download the latest complete twisted package from the twisted homepage. As of this writing, the latest is "TwistedSumo-2005-11-06.tar.bz2".

Expand the tar.bz2 archive. 

% tar -xjvf TwistedSumo-2005-11-06.tar.bz2

Next, we need to install the Zope interfaces on which twisted depends. Go into the twisted install directory, and into the Zope subdirectory, and then execute the install script. 

% cd TwistedSumo-2005-11-06/
% cd ZopeInterface-3.1.0c1
% python setup.py install

Next, we need to install the twisted core. Go back to the main twisted directory, and run the setup program for the two necessary components - core, and web. These must be installed as superuser on Mac OS X. 

% cd ..
% sudo python setup.py core install
% sudo python setup.py web install

Note: I had error messages complaining about an out-of-date quicktime SDK when I first tried to install these. Running Software Update fixed the problem, and then I was able to install.

Creating a Twisted Webserver

First, we must decide where to put the server files and logs, and the web documents (html files). I like to use folders called MaxJaxServer and MaxJaxDocs in my home directory: 

% mkdir ~/MaxJaxServer
% mkdir ~/MaxJaxDocs

Next, we need to create a webserver instance. Twisted hides its binaries deep under the python frameworks directory on Mac OS X, so it requires a bit of typing. 

% cd ~/MaxJaxServer
% /System/Library/Frameworks/Python.framework/Versions/Current/bin/mktap web --path ~/MaxJaxDocs
% ls
web.tap

Notice that the file "web.tap" has been created - this is the webserver.

Starting the Twisted Webserver

The twisted binaries are buried deep in the python frameworks folder on OS X. Since starting and stopping the webserver requires one of those binaries and it is something that one must do fairly often, it is useful to make the binaries more easily accessible. You could add the python frameworks binary folder to the $PATH variable, but I prefer to just create a simple shell script to start and stop the server for me.

This is what I will do here: First, create a shell script that simply calls the twistd -f ~/MaxJaxServer/web.tap (but using the full path to twistd), and another shell script to call kill `cat ~/MaxJaxServer/twistd.pid` (Note the use of the backticks `, which must be escaped when using echo). 

% cd ~/MaxJaxServer
% echo /System/Library/Frameworks/Python.framework/Versions/Current/bin/twistd -f ~/MaxJaxServer/web.tap > start.sh
% echo "kill \`cat ~/MaxJaxServer/twistd.pid\`" > stop.sh
% chmod a+x start.sh stop.sh
% ls
start.sh stop.sh web.tap

Now, to start the server, simply type: 

% ./start.sh

Open a webbrowser to "localhost:8080", and you should see something like: 

Directory listing for /

Filename        Content type    Content encoding

Installing MaxJax files

Download the MaxJax files here.

Uncompress, and put the contents of the directory in ~/MaxJaxDocs. 

% tar -xzvf maxjax.tar.gz
% cp maxjax/* ~/MaxJaxDocs/

Configuring MaxJax

In your favorite text editor, open the file ~/MaxJaxDocs/conf.py. This file contains the settings for the outgoing OSC port, the OSC host that will receive requests from the webserver, and also a list of legal OSC fields which will be forwarded. These should be the same names as those given to the javascript objects created in your index.html file.

For security, only the names in the element_names array will be accepted. Additionally, only numerical values, or lists of numbers up to 255 elements will be accepted, to prevent malicious data from being sent to MaxMSP or SuperCollider or whatever.

Editing index.html

Add user interface elements to index.html to construct your interface by simply creating javascript objects for the appropriate user interface elements.

The MaxJax user interface consists of javascript objects created in the html file that users will visit.

Important notes:

Here is an example document: 

<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
    <head>
        <script type="text/javascript" language="javascript" src="MaxJax.js"></script>
    </head>
    <body>
        <script type="text/javascript" language="javascript">
            var scriptURL = "http://www.example.com:8080/jaxin.rpy";
            var refreshRate = 200;

            new PictSlider("happy2d", 50, 100);
            new MultiSlider("multi", 231, 330, 180, 128, 4);
        </script>
    </body>
</html>

MaxJax.js api

The first three arguments of every user interface object are required. They are:

Below is the reference for argument orders and defaults.

Toggle

Toggle( name, left, top, width, height, offimg, onimg )

ToggleBank

ToggleBank(name, left, top, numToggles, width, height, offimg, onimg)

Bang

Bang( name, left, top, width, height, offimg, onimg )

MultiSlider

MultiSlider(name, left, top, width, height, numSliders, range, background, knob, activeknob, interpolate)

PictSlider

PictSlider(name, left, top, width, height, rangeX, rangeY, background, knob, activeknob)
© 2008