Audio Initialization Usage

Table of Contents

• Default initialization
  • Setting the client callback
• Custom Settings
• Choosing the audio backend
• Automatic play/stop of audio samples playback
• Manual play/stop of audio samples playback
• Notes

Default initialization

To initialize audio playback with default settings, you have to include the fplInitFlags_Audio flag in the fplPlatformInit() call and ensure that audio is not disabled by a preprocessor directive FPL_NO_AUDIO.

 settings;
(&settings);

if ((, &settings)) {
    // ... your code here
}

Setting the client callback

Next is to specify the client user callback which gets invoked regularly when the audio device requires new samples to play.

This client callback can be set up in the fplAudioSettings::clientReadCallback field from the fplSettings::audio or changed by calling fplSetAudioClientReadCallback() :

static uint32_t MyAudioPlaybackCallback(const  *nativeFormat, const uint32_t frameCount, void *outputSamples, void *userData) {
    // ... Fill audio frames here
}

 settings;
(&settings);
 *audioSettings = &settings->;
audioSettings. = MyAudioPlaybackCallback;
audioSettings. = // ... pointer to some user data
if ((, &settings)) {
    // ... your code here
}

Note: This step must be done before you can start playing the audio!

You can specify a user data pointer that gets passed to the client callback as well.

Custom Settings

You can change several audio settings (Sample rate, Number of Channels, Format, Channel layout, etc.) before initializing the audio playback like this:

 settings;
(&settings);
 &audioSettings = settings.;
audioSettings. = MyAudioPlaybackCallback;
audioSettings.userData = // ... pointer to some user data
 &audioDeviceFormat = audioSettings.deviceFormat;
audioDeviceFormat. = 48000;
audioDeviceFormat. = 2;
audioDeviceFormat.layout = ;
audioDeviceFormat. = ;
if ((, &settings)) {
    // ... your code here
}

Note: Please see the

Notes for possible limitations!

If the

fplAudioChannelLayout does not match the number of channels, the layout are automatically detected by the number of channels.

Choosing the audio backend

By default, FPL uses the first available audio backend which is supported on your platform.

If you want to force FPL to use a certain audio backend, you can do this by changing the fplAudioSettings::backend field in the fplAudioSettings structure:

 settings;
(&settings);
 &audioSettings = settings.;

// Forcing to use the DirectSound audio backend
audioSettings. = ;

if ((, &settings)) {
    // ... your code here
}

It is recommended to use the default fplAudioBackendType_Auto which tries all audio backends until a suitable is found.

Warning: If your platform/system does not support the desired backend, the audio and platform initialization will fail!

Automatic play/stop of audio samples playback

By default, FPL starts the playback of audio samples automatically, but only when fplAudioSettings::clientReadCallback was set!

Also audio playback will be stopped when fplPlatformRelease() is called as well.

You can disable this behavior by changing the fields fplAudioSettings::startAuto and fplAudioSettings.stopAuto in the fplAudioSettings configuration respectively.

Manual play/stop of audio samples playback

For manual control of start/stop playback of audio samples use the following functions:

• fplPlayAudio() to start requesting and play audio samples.
• fplStopAudio() to stop the audio playback.

Warning: Please ensure that

fplStopAudio() is called before

fplPlatformRelease() always!

Notes

There is no guarantee that you get the desired audio format you specified back!

You should always check the nativeAudioFormat in your client callback and convert/write the correct samples the audio device expects!

For more details see the page: Audio Samples Writing

If needed you can use fplSetDefaultAudioSettings() to fill in just the default video settings inside the fplAudioSettings structure.