Skip to content

Playing sounds#

This page describes how to play sound files with aui::audio and control the playback. To play audio that is generated or decoded by your code, see Custom sound sources.

Playing a file#

Create an IAudioPlayer with IAudioPlayer::fromUrl and call play. The url can point to a file, to an AUI Assets resource (the : prefix) or to any other location AUrl can open. WAV and Ogg Vorbis are detected automatically.

1
2
mWavAudio = IAudioPlayer::fromUrl(":sound/sound1.wav");
mOggAudio = IAudioPlayer::fromUrl(":sound/sound1.ogg");

play returns immediately; the sound is mixed and sent to the audio device in the background. Keep the returned pointer alive as long as you want the sound to be played, or at least until it is finished.

Note

The sound is opened when the player is created, so a missing file or an unsupported format throws an exception right in fromUrl (aui::audio::ABadFormatException for the latter).

Pause, stop and resume#

play starts or resumes playback, pause stops it keeping the position, and stop stops it and discards the position, so the next play starts from the beginning. The current state is available as playbackStatus.

Since these are plain methods, they connect directly to signals:

1
2
3
4
5
6
Vertical {
  _new<ALabel>("Play music using AUI!"),
  _new<AButton>("Play .wav music").connect(&AButton::clicked, AUI_SLOT(mWavAudio)::play),
  _new<AButton>("Stop .wav music").connect(&AButton::clicked, AUI_SLOT(mWavAudio)::stop),
  _new<AButton>("Pause .wav music").connect(&AButton::clicked, AUI_SLOT(mWavAudio)::pause),
} AUI_OVERRIDE_STYLE { LayoutSpacing { 4_dp } },

Volume#

setVolume takes an integer from 0 (silence) to 256 (original volume); the scale is linear. It can be changed at any time, including while the sound is playing.

player->setVolume(128); // half of the original volume

Looping#

With setLoop(true) the sound starts over when it ends instead of finishing.

auto music = IAudioPlayer::fromUrl(":sound/music.ogg");
music->setLoop(true);
music->play();

Playing several sounds at once#

Create a player per sound and start them independently. Their output is mixed by AAudioMixer; each player has its own volume. Sounds with different sample rates, channel counts or formats can be mixed together, as everything is converted to the format of the audio device.

Note

At most AAudioMixer::MAX_PLAYER_COUNT (100) players can play simultaneously.

Knowing when the sound ends#

The finished signal is emitted on the thread which created the player when the sound ended (not looping) or when reading it failed.

auto player = IAudioPlayer::fromUrl(":sound/jingle.ogg");
connect(player->finished, [] {
    ALogger::info("Sound") << "done";
});
player->play();

Sound on UI events#

The ass::Sound style rule plays a sound when a style rule is applied, so a button click sound can be declared along with the rest of the style:

1
2
3
4
5
6
7
Vertical {
  _new<AButton>("Button produces sound when clicked") AUI_OVERRIDE_STYLE {
        ass::on_state::Activated {
          ass::Sound { IAudioPlayer::fromUrl(":sound/click.ogg") },
        },
      },
} AUI_OVERRIDE_STYLE { LayoutSpacing { 4_dp } },

See ass for details on styling.

Platforms#

Platform Backend
Linux PulseAudio
Windows DirectSound
macOS, iOS CoreAudio
Android Oboe
others stub (silent)

The player requests stereo 44100 Hz output from the backend.