Audio
An initial contribution from @thepercentageguy, edited by @jeremyfa.
This guide will show you how to load and play sounds and background music in Ceramic.
Loading a sound asset
Sounds can be played anywhere at any time. However first you need to load your asset (in your scene's preload()
method).
Learn more about assets loading in the Assets guide.
Let's say we want to play the sound from an audio file named mySound.ogg
. You'd have to load Sounds.MY_SOUND
asset:
override function preload() {
assets.add(Sounds.MY_SOUND);
}
Ceramic supports several audio formats (WAV
, OGG
, MP3
and FLAC
) but not all formats are supported on all targets. If you want your audio files to work on every browser and target, you should add several versions of your files in your assets. OGG
+ MP3
will cover all cases, so in the example above, you could have mySound.ogg
and mySound.mp3
and Ceramic will pick the right file at runtime.
clay native |
WAV , OGG , MP3 , FLAC |
clay web |
WAV , OGG , MP3 , FLAC (depending on the browser) |
unity |
WAV , OGG , MP3 |
Once your audio asset is loaded, you can play it:
override function create() {
var position = 0;
var looping = true;
assets.sound(Sounds.MY_SOUND).play(position, looping);
}
When playing a sound you can pass in from where you want the sound to play (position) and whether you want the sound to loop. In that example, the sound will be played and loop without ever stopping.
Using the SoundPlayer
instance
Everytime you play a sound, it returns a SoundPlayer
instance that you can use to keep track of the sound state or manipulate the sound while it is playing.
Here, we simply stop the sound after 10 seconds.
import ceramic.SoundPlayer;
import ceramic.Scene;
class PlayASound extends Scene {
var sound:SoundPlayer;
override function preload() {
// Load the sound
assets.add(Sounds.SOUND_NAME);
}
override function create() {
// Play the sound and keep the
// SoundPlayer instance around
sound = assets.sound(Sounds.SOUND_NAME).play(0, true);
}
override function update(delta:Float)
{
// Stop the sound if it's been going
// for more than 10 seconds.
if (sound.position > 10)
{
sound.stop();
}
}
}
Background music
If you play a looping background music, you might want to stream the audio instead of loading it entirely in memory as this can save a lot of memory. Ceramic supports that by adding the stream
option to your asset:
override function preload() {
assets.add(Sounds.MY_MUSIC, { stream: true });
}
Beware that when you use the stream
option on your background music, you won't be able to change the pitch
or the position
, because it is only supported on non streaming sounds. Also, you should use the stream
option only on audio like background music etc... not on short sounds that you'll play many times.
That's all for now
There's actually more about sounds than what is covered here, but these samples should be enough to cover most common use cases of playing audio!
Continue reading ➔ Assets