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
- Firefox 4+ Mobile for Android
- Firefox 4+ Desktop (Windows, Mac OSX, Linux)
Presto
- Opera Mobile 11+ for Android
- Opera 11+ (Windows, Mac OSX, Linux)
Trident
- Internet Explorer 9+ (Windows)
WebKit Mobile
- Native Android Browser 2.3.2+ (Nexus S, HTC Desire HD, Samsung Galaxy S, Samsung Galaxy S2)
- iOS 4.3+ (iPad, iPad2, iPod 3G, iPod 3GS, iPhone 4)
- Palm WebOS 2.0+ (Palm Pre, Palm Pre 2)
WebKit Desktop
- Safari 4+ (Windows, Mac OSX)
- Safari 5.0.4+ (Windows, Mac OSX)
- Google Chrome 4+ (Windows, Mac OSX)
- Google Chrome Dev Channel (10,11,12,13,14) (Linux, Windows, Mac OSX)
- Chromium Nightly 12.0+ (Windows, Mac OSX, Linux)
- WebKit nightly rev83010(+) (Windows, Mac OSX, Linux)
Flash Support (Fallback)
sorted by Browser's Engine
Trident
- Internet Explorer 6, 7, 8 (Windows)
WebKit Mobile
- Native Android Browser 1.6+ (all devices of all manufacturers)
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:
- background music (fade-in / fade-out)
- 1.00 second silence
- sound effect #1
- 1.00 second silence
- sound effect #2
- 1.00 second silence
- sound effect #3
- 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:
- resources: (Array) array of urls to your sound files
- spritemap: (Object) spritemap settings
Optional:
- autoplay: (String) id of sprite entry (that is defined in spritemap)
- timeout: (Number) timeout in milliseconds if the EventListener fails on "canplaythrough" event. Defaulted by 1000.
- flashMediaElement: (String) url to the FlashMediaElement.swf (optional, required for flash fallback)
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:
- useFlash: (Boolean) True will enforce flash fallback, so html5 audio is ignored.
- useGameLoop: (Boolean) True will let you use your own game loop.
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
}
}
});