- Installing Twisted
- Creating a Twisted Webserver
- Starting the Twisted Webserver
- Installing MaxJax files
- Configuring MaxJax
- Editing index.html
An example of it in running.
To run the server, follow the directions below.
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:
Open a webbrowser to "localhost:8080", and you should see something like:
Directory listing for / Filename Content type Content encoding
Installing MaxJax files
Uncompress, and put the contents of the directory in ~/MaxJaxDocs.
% tar -xzvf maxjax.tar.gz % cp maxjax/* ~/MaxJaxDocs/
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.
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 should specify a refresh rate for updates.
Here is an example document:
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( 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(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( 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(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(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