TrackPerformer step-by-step

I’ve had a request to put together a guide explaining exactly how to build a performance using TrackPerformer. This post will walk you through the process, from preparation to presentation.

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.

TrackPerformer update

I’ve added in some really exciting new features to my TrackPerformer project, as well as three new performances: We Three Kings, Carol of the Bells, and Joy to the World.

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?

CSSMin updated

I’ve updated my CSSMin project with a couple of new features and bugfixes. Download or fork it on GitHub!

What is it?

CSSMin takes your CSS file and strips out everything that’s not needed — spaces, extra semicolons, redundant units, and so on. That’s great, but there are loads of programs that do that. A shell script could do that! So what makes CSSMin different?

When you deliver content over the web, best practice is to deliver it gzipped. CSSMin takes your CSS file, and optimises it for gzip compression. This means that there’s a smaller payload delivered over the wire, which results in a faster experience for your users. It does this optimisation by ensuring that the properties inside your selectors are ordered consistently (alphabetically) and in lower case. That way, the gzip algorithm can work at its best.

What this means in practice is that your gzipped CSSMin-ed files are significantly smaller than plain gzipped CSS, and noticeably smaller than files that have been compressed by other means (say, YUI).

In this update:

Nested properties are now fully supported.

This means that the following CSS:

@-webkit-keyframes 'fadeUp' {
  from { opacity: 0; }
  to { opacity: 1; }
}

is compressed down to

@-webkit-keyframes 'fadeUp'{from{opacity:0}to{opacity:1}}

Your nested properties will have their contents compressed with all of the other tricks in system, but their order will be retained.

Thanks to bloveridge for reporting this bug and verifying the fix.

Font weights are replaced by their numeric counterparts.

.alpha {
  font-weight: bold;
}
.beta {
  font-weight: normal;
}

becomes

.alpha{font-weight:700}.beta{font-weight:400}

Values supported are “lighter”, “normal”, “bold”, and “bolder”.

Quotes are stripped where possible.

.alpha {
  background: url('ponies.png');
  font-family: 'Times New Roman', 'Arial';
}

becomes

.alpha{background:url(ponies.png);font-family:'Times New Roman',arial}

As much text as possible is changed to lower-case.

Only selectors, quoted strings (such as ‘Times New Roman’) and url() values are left intact.

Note that this means that if you mix the case of your selectors (for example, SPAN and span), your compression will be sub-optimal.

Thanks

Some of the ideas for this update were inspired by Lottery Post’s CSS Compressor.

Start using it!

Requirements

You will need a recent version of Java and the Java compiler.

Download

Download or fork it on GitHub.

Usage

  1. Compile the Java:
    # javac CSSMin.java
  2. Run your CSS through it:
    # java CSSMin [input] [output]

If you don’t specify an output file, the result will be dumped to stdout. Warnings and errors are written to stderr.

Results

These are the results of compressing the main CSS file for one of the webapps I develop at work. Note that many of these compressors only offer an online service, which means that they can’t easily be used as part of your general build process.

  Original size (bytes) Gzipped size (bytes)
Plain 81938 12291
YUI 64434 10198
LotteryPost 63609 10165
CSS Drive 69275 10795
CSSMin 63791 9896

Feedback

Let me know how you go with it — bug reports and feature requests are always welcome!

Emmanuel: God with us

My wife and I have just finished our Christmas carols album, “Emmanuel: God with us”. On it, you’ll find brand new orchestral arrangements of ten great carols.

It’s available for digital download now at bandcamp. You can listen to each of the tracks in full above, and decide whether or not you want to help support poor starving musicians like ourselves. 🙂

Each track is going for around $1 (or more, if you’re so inclined!), and you can pick up the whole album for $5 or more. You can also get your hands on a physical CD if you like — just let me know!

Generative Music

Continuing my HTML5 and canvas experiments, I’ve put together a generative music system. Essentially, a series of particles move across a field, occasionally triggering sounds — the sound triggered depends on their location in the field.

There is, of course, a little bit more to it than that. Under the hood, I’ve got a series of HTML5 Audio objects that are used to provide polyphonic audio using a simple round-robin algorithm (I encoded the audio in OGG, so you’ll need to use an OGG-friendly browser, like Firefox). The particles are much simpler than those in my previous canvas dalliance, in that they don’t swarm, and their motion is more linear.

New theme!

Well, I spent the weekend quickly working up a new theme for my site. I wanted something was a) a lot simpler, and b) showed off some of the cool new CSS 3 features available.

Cool CSS features used:

  • Columns (Gecko, Webkit, Presto)
  • Web fonts (Gecko, Webkit, Presto, Trident)
  • CSS gradients (Webkit)
  • CSS transforms (Gecko, Webkit)
  • Text shadow (Gecko, Webkit, Presto)
  • Assorted CSS3 selectors and pseudo-selectors (Gecko, Webkit, Presto)

In case you’re wondering, Gecko is Firefox’s rendering engine, Webkit is Chrome & Safari, Presto is Opera, and Trident is Internet Explorer. Now you know. Tell your friends!

All in all, lots of fun stuff to play with.

Rendering bugs

Of course, the fun thing about playing with cutting edge features is that you get to find all sorts of bizarre glitches and rendering issues. Here are a few that I’ve noticed during development.

Missing letters (Presto)

Letters just seem to go missing randomly from words — “you” becomes “yo”, for example. I think that this is caused either wholly by the downloaded font, the use of columns, or a combination of the two. Quite annoying.

Pixel creep in columns (Webkit)

Every now and then, pixels from a word in column B will find their way to the very bottom of column A. It’s even worse when you set a box-shadow on an element — the top of the shadow is rendered in the previous column. I’m guessing that Webkit’s column-rendering algorithm basically renders the entire area in a long strip, then cuts it into chunks and shoves them on the page. Annoying.

Disappearing column rules (Gecko)

Apparently, setting the “overflow” property (or “overflow-x” or “overflow-y”) on an element that is rendered in columns prevents the column rule from being rendered in Gecko. I really have no idea why this should be the case — it’s a very strange behaviour.

HTML 5 element styling (Trident)

Internet Explorer can’t style elements that aren’t bog-standard HTML. Unless you use “document.createElement(‘elemName’)” on them first. Ridiculous.

CSS minifier and alphabetiser

Update: This project is now hosted on GitHub: https://github.com/barryvan/CSSMin/

There are quite a few CSS minifiers out there, which can bring the raw size of your CSS files down substantially. There are, however, significant gains to be made if the CSS is minified so that it gzips better. To that end, I’ve written a small Java application that will read in a CSS file and output its contents to stdout or another file in a format that’s optimised for gzipping.

The problem

A gzipped file will be stored most efficiently when there are many recurring strings in the file. This means that when writing CSS files, this code:

.pony {
border: solid red 1px;
font-weight: bold;
}
.lemur {
border: solid red 1px;
font-weight: normal;
}

will be better-compressed than this:

.pony {
border: solid red 1px;
font-weight: bold;
}
.lemur {
font-weight: normal;
border: red solid 1px;
}

In the first sample, notice that we have a very long string that occurs twice:

 {
border-style: solid red 1px;
font-weight: 

In the second sample, there are strings that occur more than once, but they’re much shorter. The gzip algorithm can, in the first case, replace that entire long string with a much shorter placeholder.

What it does

So, how can we optimise CSS for gzipping, then? A file that’s minified using this CSS Minifier will have these operations applied:

  • All comments removed.
  • The properties within all selectors ordered alphabetically.
  • The values for all properties ordered alphabetically.
  • All unnecessary whitespace removed.
  • Font weights replaced by their numeric counterparts (which are shorter).
  • Quotes stripped wherever possible.
  • As much text as possible transformed to lowercase.
  • Prefixed properties (for example, -moz-box-sizing) placed before the unprefixed variant (box-sizing).
  • Colours simplified from rgb() to six- or three-digit hex values, or simple names.
  • Units on values of 0 stripped.
  • Multi-parameter items simplified to as few parameters as possible.
  • Various other small tweaks and adjustments made.

By way of example, the following CSS snippet:

body {
  padding: 8px;
  margin: 0;
  background-color: blue;
  color: white;
  font-family: "Trebuchet MS", sans-serif;
}

h1 {
  margin: 0;
  padding: 0;
  font-size: 200%;
  color: #0F0;
  font-weight: bold;
}

p {
  margin: 0 0 2em;
  line-height: 2em;
}

would be formatted to the following (note that line breaks have been added for legibility — no line breaks appear in the final output):

body{background-color:blue;color:#fff;font-family:"trebuchet ms",sans-serif;
margin:0;padding:8px}h1{color:#0f0;font-size:200%;font-weight:700;margin:0;
padding:0}p{line-height:2em;margin:0 0 2em}

Compression results

These are the results of compressing the main CSS file for one of the webapps I develop at work.

  Original size (bytes) Gzipped size (bytes)
Plain 81938 12291
YUI 64434 10198
LotteryPost 63609 10165
CSS Drive 69275 10795
CSSMin 63791 9896

Download

Head over to GitHub to download the source.

Usage

First, if you haven’t done so yet, compile the code:

# javac CSSMin.java

Then, you can call the minifier by running

# java CSSMin in.css [out.css]

If you do not specify an output file, the resultant CSS will be printed to stdout (and can then be redirected as you wish).

Contact

If you have any questions or comments about this app, or if you find a bug or some weird behaviour, just comment on this post, and I’ll see what I can do.

You can also raise issues on GitHub, fork the project, commit changes, and more.

If you find this utility useful, let me know!