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.
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 ();
});
</script>
Step 4: Copy the build/settings.js and
build/story.js files into your site and follow the instructions
found in each.
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 diveintohtml5.org 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 (
'video/my_video.mp4',
'video/my_video.webm',
'video/my_video.ogv'
);
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 (
'pix/one.png',
'pix/two.png',
'pix/three.png'
);
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 (
'example.rss',
'example.json'
);
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:
<?php
$url = 'http://www.example.com/feed.rss';
$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;
exit;
?>
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] = [
{a:'bg_fade_in'}
];
_s[1] = [
{a:'bg_colour', d:{colour:'#900'}}
];
_s[2] = [
{a:'bg_fade_out'}
];
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.
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>
<div id="cacophony-video-wrapper">
<video id="cacophony-video"></video>
</div>
<div id="cacophony-canvas1">
<canvas></canvas>
</div>
<div id="cacophony-canvas2">
<canvas></canvas>
</div>
<div id="cacophony-canvas3">
<canvas></canvas>
</div>
<div id="cacophony-canvas4">
<canvas></canvas>
</div>
</div>
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 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 ();
}
}
ended()Triggered when the video has ended. Example:
cacophony.callback.ended = function () {
window.location = 'http://www.example.com/next-video.html';
}
loading(percent)Triggered while the video is loading. Example:
cacophony.callback.loading = function (percent) {
// show the percent loaded
$('#percent').html (percent + '%');
}
play()Triggered when the video has begun or resumed playing. Example:
cacophony.callback.play = function () {
alert ('Playing!');
}
pause()Triggered when the video has been paused. Example:
cacophony.callback.play = function () {
alert ('Paused!');
}
ready()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 ();
}
timeupdate(time)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);
}
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:
cacophony.beatThe current beat of the song.
cacophony.canvasThe Cake.js canvas object for the first canvas layer.
cacophony.durationDuration of the video. Available after loading is complete.
cacophony.endedHas the video ended.
cacophony.heightHeight of the video (use cacophony.setSize(w, h) to modify).
cacophony.inputSet to true when an effect is accepting input, so Cacophony can stop listening for keyboard input while someone is typing, for example.
cacophony.playingWhether the video is currently playing or not.
cacophony.widthWidth of the video (use cacophony.setSize(w, h) to modify).
cacophony.wrapperThe jQuery object for the wrapper div.
Here are some other useful methods of the cacophony object
that you can use in customizing the player:
cacophony.beatLength()Returns the length of a single beat in seconds.
cacophony.getVolume()Returns the current volume, from 0 to 1.
cacophony.jumpTo(beat)Jumps the player to the specified beat number in the song.
cacophony.jumpToTime(seconds)Jumps the player to the specified point in the video in seconds.
cacophony.play()Starts or resumes playback.
cacophony.playPause()Toggles play/pause state.
cacophony.pause()Pauses video playback.
cacophony.setSize(w, h)Sets the size of the video player.
cacophony.setVolume(v)Sets the volume, from 0 to 1.
cacophony.timeToBeat(seconds)Returns the beat number for the specified time in the song.
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