Jukebox
Documentation API Demos

Overview

Important Issues and Hints

Chrome 16.0.912.* (Mac OSX) is a known for timing issues with the Audio Decoder. getCurrentTime() will return false values that are incorrect, because the internal used decoder is not behaving the same way as it should. Confirmed is that this could be a problem related to VBR encoded files.

iOS

iOS allows only playback of a single sound in parallel. It has also latencies up to 820ms (initial playback) due to the implementation of using iTunes as a low-priority thread and issues with encoded audio formats.

There's a further demo using an AIFF container and the IMA4 codec that allows instant playback there.

The iOS security model only allows playback of sound using the Audio API (and iTunes in the background) if the callstack was triggered by an event inside the UI layer. That means, you will have to use an element.onclick(), element.ontouchstart() or similar to initialize the Jukebox.

Take a look at the iOS demo that shows how to bypass the security model for having a background music.

Android

Jukebox should work with all third-party shipped web browsers that are known to support HTML5, as they ship their own codec implementations.

Native WebKit will also support HTML5 Audio, but it depends on if the manufacturer ships a codec implementation. Google's policies for the Android platform requires a Apache/BSD license based implementation of the codec. That's why Android 2.3.2+ devices may have an mp3 codec installed. Third-party Mods like Cyanogen also support mp3 and flac codec implementations.

Mobile Codec Mess (Fallback solution)

All mobiles support GSM, so they have the voice codec for GSM installed which is based on 3gp / amr. This codec supports bitrates up to 12.2kbit/s. While this is a pretty sub-par quality, it is a good fallback solution for slow internet connections.

The codec is known to work across all Android devices (even on those without any other supported codec) and known to work on iOS and WebOS.

HTML5 Audio Support

sorted by Browser's Engine

Gecko

Presto

Trident

WebKit Mobile

WebKit Desktop

Flash Support (Fallback)

sorted by Browser's Engine

Trident

WebKit Mobile

Getting Started

Jukebox makes usage of spritemap-based soundfiles. That means every soundfile consists of different sprite entries that can be played. We chose to use spritemaps, because every codec is more effective when encoding large files - and download speed is a huge plus when considering that music and sounds are by far the largest files in games.

Another reason for choosing a spritemap structure was the latency on mobile devices, especially on iOS where initial playback can take up to 820ms due to their implementation using iTunes for playback.

Create the Audio File

The sprite entries can be looped, such as a background music - or used as sound effects.

The structure of an audio sprite map should look like this, to avoid any issues with playback latency:

  1. background music (fade-in / fade-out)
  2. 1.00 second silence
  3. sound effect #1
  4. 1.00 second silence
  5. sound effect #2
  6. 1.00 second silence
  7. sound effect #3
  8. 1.00 second silence

Important: For easier playback, you should round up the silence. So it's much easier and more precise. The Audio API behind is in seconds - so if you choose to start a sprite entry at e.g. 3.075s you will have a delay of at least 0.005s (minimum, worst case plus loop interval timeout).

My recommendation is to round up to full seconds instead to avoid that problem. Place the sprite entry at 4.00 seconds.

jukebox.Player Settings

Required: Optional:

Spritemap Settings

The spritemap settings are the data representation of your audio file.
This is an example that gives you an idea of how to setup:

	var player = new jukebox.Player({

		// ... other settings

		spritemap: {
			bgmusic: {
				start: 0.00,
				end:  20.00,
				loop: true
			},
			shoot: {
				start: 21.00,
				end: 22.50
			},
			kaching: {
				start: 24.00,
				end: 24.75
			}
		}

	});
	

jukebox.Manager Settings

Optional:

useGameLoop is an important settings for usage with performance-critic game loop intervals. It allows you to call jukebox.Manager.loop() inside your game loop, so that you can avoid usage of multiple intervals.

Please take a look at the Game Integration demo for more details.

Initialization Example

This example uses the available resources from the demos folder. It automatically starts to play the bgmusic sprite entry.
Note that there's no play() call, so only the background music is repeating all the time due to it's loop flag.

	window.demo = new jukebox.Player({

		resources: [
			'../demo/media/spritemap-cajon.ac3',
			'../demo/media/spritemap-cajon.mp3',
			'../demo/media/spritemap-cajon.m4a',
			'../demo/media/spritemap-cajon.ogg',
			'../demo/media/spritemap-cajon.amr'
		],

		autoplay: 'bgmusic',

		spritemap: {
			bgmusic: {
				start: 0.00,
				end: 4.20,
				loop: true
			},
			effect: {
				start: 5.00,
				end: 9.30
			}
		}

	});