Tutorial: Customizing the Player

« Home

This tutorial is mainly a reference for the different elements of the Cacophony player and how to use each of them to configure and customize the player to your needs.

Basic Setup

The initial steps to setting up a new Cacophony player go as follows:

Step 1: Include the scripts and stylesheet in your <head>:

<script type="text/javascript" src="js/jquery-1.4.2.min.js"></script>
<script type="text/javascript" src="js/cacophony.min.js"></script>
<script type="text/javascript" src="js/settings.js"></script>
<script type="text/javascript" src="js/story.js"></script>
<link rel="stylesheet" type="text/css" href="css/cacophony.min.css" />

Step 2: Create an element like this in your page, note the ID must be 'cacophony':

<div id="cacophony"></div>

Step 3: Add the following script to your web page:

<script type="text/javascript">
$(document).ready (function () {
    cacophony.init ();

Step 4: Copy the build/settings.js and build/story.js files into your site and follow the instructions found in each.

The Settings File

Here is where you configure the basic settings of the player. Each is commented so you can see what to enter for each value. Here is also where you'll need to add your videos and other files (images, data feeds).


HTML5 videos need to be provided in multiple formats in order to work in the various web browsers, since they haven't all agreed on a single common video format. For maximum compatibility, you'll need 3 formats: H.264, WebM, and Theora.

A more in-depth overview of the different formats and which browsers support them is available on here.

A tool that has worked well for me for converting between formats is the free Miro Video Converter.

Once you have converted your videos, add them to your site and refer to them like this:

cacophony.setVideo (

If you're using any static images in your video, you'll need to preload them so they're ready when they need to be called. To do this, add them to your site and refer to them in the cacophony.preloadImages() setting like this:

cacophony.preloadImages (

Data Feeds

Some Cacophony effects can take advantage of RSS or JSON data feeds, meaning data from external sources can be used in your videos. To add a feed, specify the file in the cacophony.preloadData() setting like this:

cacophony.preloadData (

Note that data feeds are retrieved via a jQuery.ajax() request, which means that for security reasons they cannot be retrieved from other domains than the one the video is hosted on. However, you can easily write a server-side script to retrieve external feeds, cache them locally to improve load times, and serve them to the video directly. An example of that in PHP, cached using the memcached extension, would be as simple as this:


$url = '';

$m = new Memcached ();
$m->addServer ('localhost', 11211);

if (! ($data = $m->get ($url))) {
	$data = file_get_contents ($url);
	$m->set ($url, $data, 3600);

header ('Content-Type: application/rss+xml');
echo $data;


The Story File

Like the settings file, the story file provides further info for the Cacophony player about your video. The file describes a series of effects that should be triggered in sequence to the specified beats of the song or video.

The format is a Javascript array of beats, each containing an array of objects describing the effect to be triggered and parameters to pass to it. For example:

_s[0] = [

_s[1] = [
	{a:'bg_colour', d:{colour:'#900'}}

_s[2] = [

The above story tells Cacophony to fade in on the first beat, change the background color to #900 on the second beat, and to fade out on the third beat.

_s[] is the story array, an alias for cacophony.story and the numbers are the beats, which depend on the beats-per-minute of the video. Note that this doesn't mean you have to make music videos with Cacophony, it's just a means of dividing the song into points where actions occur. So if you set the beats-per-minute to 60, actions will occur once every second. If you set it to 120, they will occur every half of a second, and if you set it to 600, they will occur every 100 milliseconds, and so on.

Each action is an object containing an a: property specifying the action (which effect to trigger), and usually also a d: property specifying some data to pass to the effect. For example, in the story above we passed d:{color:'#900'} to the bg_colour effect.

Examples of the data for each effect are listed in the default story file, and more documentation for each is available in the API documentation as well.

Styleable Elements

Cacophony generates the following HTML structure for the player, which you can use to style however you want.

<div id="cacophony">
	<div id="cacophony-duration">
		<div id="cacophony-play"></div>
		<span id="cacophony-time"></span>
	<div id="cacophony-video-wrapper">
		<video id="cacophony-video"></video>
	<div id="cacophony-canvas1">
	<div id="cacophony-canvas2">
	<div id="cacophony-canvas3">
	<div id="cacophony-canvas4">

In the default CSS file, the player is centered and set to a default size of 854x480, with an extra 20px on top for the div#cacophony-duration, but you can override any style or create your own, as well as additional elements in the page for custom player controls. You can also use jQuery to modify the CSS for any element on the fly during video playback.

Callback Functions

Callback functions make it possible for Cacophony to communicate with your page and notify it when certain actions have occurred, allowing you to create functionality triggered by those actions. This includes things like play/pause updates, customizing the loading process, and being notified of when the video has ended (useful, for example, in auto-playing the next video in a series).

Each available callback is listed below with an example of how you might use it.

browser_check(message, compatible)

Triggered during the initialization so you can handle browser incompatibility notices. Example:

cacophony.callback.browser_check = function (message, compatible) {
	if (! compatible) {
		// show an incompatible browser message
		$('#incompatible').html (message).show ();


Triggered when the video has ended. Example:

cacophony.callback.ended = function () {
	window.location = '';


Triggered while the video is loading. Example:

cacophony.callback.loading = function (percent) {
	// show the percent loaded
	$('#percent').html (percent + '%');


Triggered when the video has begun or resumed playing. Example: = function () {
	alert ('Playing!');


Triggered when the video has been paused. Example: = function () {
	alert ('Paused!');


Triggered when the video is loaded and ready to play. Example:

cacophony.callback.ready = function () {
	// show the play button once it's loaded
	$('#cacophony-duration').show ();


Triggered by the video's ontimeupdate event throughout playback. Example:

cacophony.callback.timeupdate = function (time) {
	// update a scrubber using a jQuery UI slider
	$('#scrubber').slider ('option', 'value', time);

Useful Properties

In addition to the callbacks, you may need info about the video itself and its current state, which you can get by accessing the following properties of the cacophony object:


The current beat of the song.


The Cake.js canvas object for the first canvas layer.


Duration of the video. Available after loading is complete.


Has the video ended.


Height of the video (use cacophony.setSize(w, h) to modify).


Set to true when an effect is accepting input, so Cacophony can stop listening for keyboard input while someone is typing, for example.


Whether the video is currently playing or not.


Width of the video (use cacophony.setSize(w, h) to modify).


The jQuery object for the wrapper div.

Useful Methods

Here are some other useful methods of the cacophony object that you can use in customizing the player:


Returns the length of a single beat in seconds.


Returns the current volume, from 0 to 1.


Jumps the player to the specified beat number in the song.


Jumps the player to the specified point in the video in seconds.

Starts or resumes playback.


Toggles play/pause state.


Pauses video playback.

cacophony.setSize(w, h)

Sets the size of the video player.


Sets the volume, from 0 to 1.


Returns the beat number for the specified time in the song.

Where to From Here

If you want to get into making custom effects, see the next tutorial here. You can also find additional info on all of the above in the API documentation.

If you have any questions, join our Google Group and get involved!

Brought to you by Johnny Broadway