Please note that this guide assumes you are working with an Impulse Tracker or OpenMPT module; if you are not, you will have a bit more work to do.

Ingredients

To build your performance, you will need the following items:

• The original module file (IT or MPTM format)
• The exported audio file (preferably in OGG, MP3, and M4A formats, for maximum cross-browser compatibility)
• A copy of the ModReader source (which you can download from GitHub)
• A copy of the TrackPerformer source (which you can also download from GitHub)
• A decent plain text editor (not Word) — I recommed Komodo IDE or Komodo Edit.
• A recent and decent web browser — Firefox, Chrome, or Opera work best.

With these in hand, you’re ready to get going!

Method

1. Set up

If you haven’t already, extract TrackPerformer to the folder of your choice. When you do so, you’ll notice that there are several sub-directories: “Examples”, “Source”, and “Utilities”. Create a new directory, called “Performances”.

Copy the file “template.html” from the “Examples” directory, renaming it to the name of your track.

Next, copy your exported audio files into the “Performances” directory; ensure that they all have the same file name (bar the extension).

Create a new, blank file, with a “.js” extension and named the same as your track. Load this file in your editor.

Finally, load the HTML file in your editor, and add a <script> tag just before the closing </head> tag that references your JS file. For example, if your JS file was named “purple.js”, you would type:

<script type="text/javascript" src="purple.js"></script>

 2. Conversion

The next step is to convert your file into a format that TrackPerformer understands. This means noting down when every note is played, and by which instrument. It also means extracting information such as the tempo, time signature, and song title.Fortunately, if you’re using an IT or MPTM module, the ModReader utility is able to perform this (rather tedious) step for you.

If you are not using a format that ModReader is able to convert, you will need to complete this step manually. If your file can be opened in OpenMPT, it is possible to use a JavaScript macro in Komodo IDE/Edit to facilitate this; otherwise, you will need to craft the entire lot by hand.

If you have not already done so, extract the ModReader zip file to a suitable location. Then, in your web browser, load the “index.html” file from that location.

Select the file you would like to convert. Note that ModReader does all of its processing on your computer — it doesn’t send your file anywhere, and won’t change its contents, either.

All going according to plan, there should now be a lot more text on-screen. Copy everything between the dashed lines (not including the lines), and paste it into your performance’s JS file. This is the TrackPerformer-compatible version of your module,in a format known as JSON.

3. Write some JavaScript

As I said earlier, ModReader gives you a JSON representation of your track, which is great. However, we need to now pass this representation through to TrackPerformer. To do this, we need to write some JavaScript to go around this JSON representation. Edit your JS file so that it looks something like this:

window.addEvent('domready', function() {
	var controller = window.controller = new barryvan.tp.Controller({
		background: 'rgba(230,230,230,0.5)',
		meta: {
			colour: 'rgba(0,0,0,0.5)',
			visible: false
		}
	}, $('container') || document.body);
	controller.perform({
		title: 'Foo bar baz'
		/* the rest of the track... */
	});
});

What we’re doing here is creating a new Controller, and telling it to perform the track.

4. Make some noise

The next step is to point TrackPerformer at the MP3, OGG, and M4A exports of the music. To do this, find the line in your JS file that reads

"audio": ""

. In the empty quotes, put in the filename of your audio (without any extension). If your audio is on the web, put in the full URL (again, without the extension). Your JS file will now look something like this:

{
	/* snip */
	"audio": "mice"
	/* snip */
}

Now, load up your HTML file in your web browser. You should be able to listen to your track. Next up, we’ll add a performer.

5. Add a performer

Each instrument in your piece can have zero or more performers assigned to it. There are a variety of performers that you can use, each of which offers a unique visual representation of your music. Each performer has a variety of options which affect its function and appearance. These include colour, size, position, vitality, and many others.

Each performer is defined in a code block that looks something like this:

{
	performer: barryvan.tp.performer.Oscillator,
	options: {
		colour: '#f00',
		stepSize: 10,
		sustain: true,
		middle: 58
	}
}

The block above means that we want an Oscillator (performer: barryvan.tp.performer.Oscillator). We have set some of its options (options: { … }) such that it is bright red (colour: ‘#f00′), that a semitone is 10 pixels in size (stepSize: 10), and that its middle note (vertically centred in the performance) is 58 (middle: 58), or A#4.

If you look at your JS file, you should see a section labelled “instruments”, which will look something like this:

"instruments": [
	{
		"name": "Melody",
		"performers": []
	}
]

Put the performer’s code block between the [], like so:

"instruments": [
	{
		"name": "Melody",
		"performers": [{
			performer: barryvan.tp.performer.Oscillator,
			options: {
				colour: '#f00',
				stepSize: 10,
				sustain: true,
				middle: 58
			}
		}]
	}
]

Now, if you reload your performance in your web browser, you should have something on-screen. You can add more performers to the other instruments in your piece in the same way. If you want more than one performer for the same instrument, you can simply place a comma after the closing brace of the performer block, and start the next one.

6. Add some filters (optional)

Filters can manipulate the entire presentation. They can, for example, shift pixels around, draw a grid, or simply calculate the framerate.

Filters are applied to each frame of the animation, and can be applied before or after the performers have been processed. Filters that are processed at the start of each frame go under “prefilters”; those processed at the end of each frame are entered under “postfilters”.

Let’s shift some pixels around using the “Pick” filter. Like performers, filters are defined in a block of code:

{
	filter: barryvan.tp.filter.Pick,
	options: {
		fuzz: 2
	}
}

We’ll add this into the “prefilters” section:

"prefilters": []

becomes

"prefilters": [{
	filter: barryvan.tp.filter.Pick,
	options: {
		fuzz: 2
	}
}]

If you reload your performance in your web browser, things should look a little more fuzzy.

Filters can have a huge impact on the overall “feel” of your performance. They can soften the performers’ hard edges, and give the entire performance a more natural appearance.

7. Present

Once you’ve added more performers, adjusted colours, and fiddled with the CSS on your HTML file, you’re ready to take to the stage. Simply upload the “Source” directory and your performance to your webserver (making sure to keep relative paths intact), and publish the URL. You don’t need to do anything on the server: TrackPerformer is entirely client-side.

8. Ask questions

If you run into problems, or have a question, don’t hesitate to leave a comment or raise an issue on GitHub. You’re also more than welcome to fork the project, and build your own performers and filters — if they’re pulled back into the main TrackPerformer tree, then everyone else can use them, too!

Appendix

A. Converting notes to numbers

Notes are in the range C-0 to B-9, and are numbered from 0 to 119. To find the number for a particular note, use this formula: x = note + (octave * 12). In this formula, the note C is 0, C# is 1, D is 2, and so on.

B. TrackPerformer Wiki: performers, formats, etc.

The TrackPerformer Wiki has details on all of the performers, the performance format, the filters that are available, and the controller options.

Filters

It’s now possible to add filters, or effects, into the processing chain. These filters can be applied before any performers (pre-filters) or after all performers (post-filters). At the moment, the included filters are:

• FPS: Calculates the average framerate across the performance, optionally displaying it in a DOM element.
• Grid: Draws a grid to the canvas. The grid may be a simple intersection grid (points), or lines. Both the X and Y axes may be independently configured.
• Pick: Probably the most interesting (and processor-intensive) part of TrackPerformer. The Pick filter will randomly swap a pixel with one of its neighbours. It’s used at full intensity on both We three Kings and Joy to the World, and, when toned down a little for Carol of the Bells, provides a softening, organic effect.

I’ve got some ideas for more filters down the track… The only difficulty is keeping performance acceptable: manipulation of the canvas pixel by pixel is quite slow in current browsers.

Performers

There are a couple of new performers, and some minor updates to some of the existing ones. The Oscillator performer, in particular, is rapidly becoming the most flexible and useful of the performers.

• There’s a new ShimmerGrid performer, which is great for adding texture and movement to the entire canvas. You can see it in action particularly well on Joy to the World.
• The Swarm performer can now draw its particles as knots (like the SignalTracker), as well as as dots.
• The Oscillator now has the ability to draw sustained notes, and to increase the longevity of notes. Take a look at Carol of the Bells to see these new options in use.
• Notes can now be filtered based not only on their pitch, but also their velocity (volume).

There are a couple of other changes here and there, but these are the main ones.

We Three Kings

The three new example tracks are all taken from We Three Kings, my new Christmas remix album. Why not go and have a listen?

Essentially, you take a piece of music, convert it into a format that TrackPerformer understands (JSON), describe how you want it to be performed, and then watch! You can, of course, write your own performers.

Note: You won’t be able to view the performance linked above in Internet Explorer, due to its over-aggressive script-blocking: the scripts served from GitHub have the wrong mime-type, so IE won’t let them run.

Take a look at the project on GitHub to see how it all fits together. TrackPerformer itself resides in the “Source” directory; in “Examples”, you’ll find the performance of Colony; in “Utilities”, there’s a JavaScript macro for Komodo IDE/Edit that will help you to translate copied-and-pasted OpenMPT pattern data into TrackPerformer’s JSON format.

You can find more information on the TrackPerformer wiki, including an outline of the format, and some basic instructions for getting started. I’ll be adding more information to the wiki over the next few days, and I’ll post updates here too.

Let me know what you think!

More of the usual Native Instruments suspects at play in this piece: Kontakt, Massive, FM8, and Battery. All of them driven by OpenMPT and Xlutop Chainer.

(Download)

Conflagration by Barry van Oudtshoorn is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.

Perhaps surprisingly, the sport has remained relatively unchanged from its Babylonian days, notwithstanding the French revolutionaries’ attempts to “simplify” and “democratise” it. Two teams attempt to remove the bristles from between five and six toothbrushes. Judges award points based on the number of bristles removed, their angular displacement, and the size of the bribe. Many have called for toothbrush depilation to be played at the Olympics, but unfortunately they had the wrong number, and so their calls could not be connected.

In Australia, the sport has had something of a checkered history. Forced underground by Hughes, it later experienced an upsurge in popularity under Menzies and Howard. Its detractors claim that it constitutes cruel and unusual punishment; its pundits counter this by pointing out that the detractors are all wimps.

With growing numbers of young Australians choosing toothbrush depilation over other, perhaps more conventional sports, it looks set to sweep the world in the new millenium. A bright future of bristles, bribes, and bloody murders beckons!

Barry van Oudtshoorn hails from the snow-clad plains of the Serengeti delta. Overcoming his debilitating muteness (Barry was born without a larynx), he has become an accomplished ventriloquist and master orator. He has presided over Presidential coming-of-age ceremonies and the marriages of seventeen Catholic priests, both in Uzbekistan and abroad.

The winner of the inaugural bi-annual toothbrush-depilation contest in 2010 (and a runner up the year before that), Barry leads a quiet life. Despite being married to Ariel, he has led a comfortable and well-cooked life. Barry enjoys making jellies wobble and cutting his toenails.

I’m not sure that this will be what goes up, though…

<p class=alpha>Lorem ipsum dolor sit amet etc.</p>

Indeed, Internet Explorer 7 and 8 favour this approach. Whereas Firefox, for example, would return the above as

<p class="alpha">Lorem ipsum dolor sit amet etc.</p>

when retrieving it using innerHTML, IE 7 & 8 only quotes attributes that satisfy certain criteria:

• Any attributes that contain spaces;
• Some magic set of standard attributes, such as href;
• Any custom attributes you may have specified.

Unfortunately, however, this doesn’t constitute well-formed XML. In the software I develop at work, we produce PDFs that can include user-generated HTML. To do this, we use XSL:FO — an XML-based system. You can see where this is going: the backend requires valid XML, but the frontend is sending through HTML. The simplest way to fix this is with a simple regex, like so:

var s = '<p class=alpha>Lorem ipsum dolor sit amet etc.</p>';
s = s.replace(/=([^"'`>\s]+)/g, '="$1"');
// s === '<p class="alpha">Lorem ipsum dolor sit amet etc.</p>'

Bear in mind that this regex is by no means perfect. It will, for example, convert this:

<p class=alpha>Lorem ipsum</p>
<p>dolor sit=amet</p>

into this:

<p class="alpha">Lorem ipsum</p>
<p>dolor sit="amet</p">.

…which is obviously not what we want. I spent a while trying to come up with a regex that would solve this problem, but I stopped pretty soon. What’s really needed here is a parser: something that can take in the tag soup that Internet Explorer produces, and produce valid XHTML (which is valid XML). A quick search reveals myriad implementations in various languages — Python, Java, even JavaScript.

So, after all that, what’s the take-away from this post? Just this: web browsers (slightly older versions of Internet Explorer in particular) are imperfect. XML was borne out of HTML, and is much less forgiving; whether or not its strictness is a good thing is up for debate. I guess that it’s a bit like reading Shakespeare nowadays: you can pretty much understand it, but every now and then you have to reach for a dictionary to make sense of what’s going on. Of course, when you don’t understand something in Shakespeare, you don’t fall over in a heap, but let’s not stretch the analogy too far.

In brief

When retrieving the innerHTML of an element (or using contenteditable), Internet Explorer doesn’t always wrap attribute values in quotes. The solution to this is not a magnificently obtuse regex, but a tag-soup parser that can return valid XML.

This piece is somewhat heavier than some of my other recent endeavours, but hopefully not too much so. In terms of VSTis, it makes use of the usual culprits: Reaktor, Massive, FM8, and Kontakt.

(Download)

Juggernaut by Barry van Oudtshoorn is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.

(Download)

Fluorescent by Barry van Oudtshoorn is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.

Let me know what you think!

(Download)

Frequency by Barry van Oudtshoorn is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License.