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.

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.

Mixers #

Every sound belongs to a mixer group (0 by default). The group's AudioMixer lets you control many sounds at once, which is perfect for separate "music" and "sfx" volume settings, or a global mute:

var mixer = audio.mixer(0);
mixer.volume = 0.5;
mixer.mute = true;

Procedural audio #

Sounds don't have to come from files: you can generate raw PCM samples in Haxe and turn them into a regular Sound with Sound.fromSamplesBuffer():

var sampleRate = 44100;
var duration = 0.2;
var count = Math.round(sampleRate * duration);

var buffer = new Float32Array(count);
for (i in 0...count) {
    var t = i / sampleRate;
    buffer[i] = 0.5 * Math.sin(2 * Math.PI * 440 * t); // A 440Hz sine
}

// buffer, frame count, channels, sample rate, interleaved
var beep = Sound.fromSamplesBuffer(buffer, count, 1, sampleRate, true);
beep.play();

The audio example pushes this further: all of its sound effects and even its music loop are synthesized this way, without a single audio file.

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