MaxJax

Aug 01, 2006

MaxJax
Installing Twisted
Creating a Twisted Webserver
Starting the Twisted Webserver
Installing MaxJax files
Configuring MaxJax
Editing index.html
1. MaxJax.js api

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.

An example of it in running.

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:

Your html file should begin with an XHTML Strict doctype. This is necessary to ensure that browsers will render the positioning of elements properly.
MaxJax.js must be included in the head section of the document.
User interface elements must appear after the start of the body tag, as the script needs to be able to reference it.
You must define the scriptURL variable for the AJAX to work. This URL must have the same base address as the page you are viewing. For example, http://www.example.com and http://example.com is a different base address. This is a limitation of AJAX. The scriptURL points to the script on the server that will interpret HttpRequests from the javascript.
You should specify a refresh rate for updates.

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:

name: The name of the UI element, also the address of the OSC message this object will produce (beginning slashes (/) are added by the script, do not add them).
left: The distance in pixels from the left edge of the page.
top: the distance in pixels from the top of the page.

Below is the reference for argument orders and defaults.

Toggle

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

width: the width of the toggle (default 33)
height: the height of the toggle (default 34)
offimg: url for the image to display when off
onimg: url for the image to display when on

ToggleBank

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

numToggles: the number of toggles in this bank (default 1)
width: the width of the bank of toggles (defaults to the number of toggles * 33)
height: the height of the bank of toggles (default 34)
offimg: url for the image for an individual toggle when off
onimg: url for the image for an individual toggle when on

Bang

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

width: the width of the bang button (default 32)
height: the height of the bang button (default 32)
offimg: url for the image for a non-banged bang
onimg: url for the image for a banged bang

MultiSlider

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

width: the width of the multislider in pixels (default 100)
height: the height of the multislider in pixels (default 100)
numSliders: the number of sliders in the multislider (default 1)
range: the top end of the floating point range for the slider. (default 128)
background: url for the background image for the slider.
knob: url for the image for a single slider knob.
activeknob: url for the image for a single slider when being moved.
interpolate: true/false - whether or not to interpolate between mouse points while dragging. (default true)

PictSlider

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

width: the width of the pictslider in pixels (default 100)
height: the height of the pictslider in pixels (default 100)
rangeX: the x-coordinate range of the pictslider (default 128)
rangeY: the y-coordinate range of the pictslider (default 128)
background: url for the background image
knob: url for the slider knob
activeknob: url for the slider knob while being dragged