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).

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:

Load the 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
Audio format support table

Once your audio asset is loaded, you can play it:

Play the sound
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.

Play a sound and stop it after 10s
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:

Load the asset (streaming)
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 ➔ Inside a default project (Appendices)