CAPI_AudioOutput.h

Overview

User-defined audio output interface.

#include <Ultralight/CAPI/CAPI_AudioOutput.h>

The library uses this to play the sound of <video> and <audio> elements. It decodes the audio and pushes the samples to your callbacks, which play them on a device.

A platform-specific implementation is provided for you when you call ulCreateApp(). If you are using ulCreateRenderer() and don't provide one, media plays without sound.

Each callback matches the method of the same name in <Ultralight/platform/AudioOutput.h>, and the rules documented there apply here too. Read that header before implementing this one.

Warning

The library calls these callbacks from several of its own threads. push_samples can still be running when flush or stop is called for the same stream, so protect each stream's state.

Warning

When your buffer is full, push_samples should wait for room instead of dropping samples. A waiting push_samples must return as soon as flush or stop is called for its stream, or the library can hang.

Note

get_playback_position is optional. Implement it for the most accurate audio-video sync.

Precondition

Requires the Pro edition or higher.

See also

ulPlatformSetAudioOutput()

Classes
struct	ULAudioFormat
	An audio sample format (channel count and sample rate). More...
struct	ULAudioOutput
	User-defined audio output interface. More...

Typedefs
typedef void(*)	ULAudioOutputCreateStreamCallback(void *user_data, unsigned int stream_id, ULAudioFormat format)
	The callback invoked to create a new audio stream (before its first samples are pushed).
typedef void(*)	ULAudioOutputPushSamplesCallback(void *user_data, unsigned int stream_id, const float *samples, unsigned int num_frames)
	The callback invoked to push decoded PCM samples into a stream (num_frames * channels interleaved floats).
typedef void(*)	ULAudioOutputSetVolumeCallback(void *user_data, unsigned int stream_id, float volume)
	The callback invoked to set a stream's volume, from 0.0 (silent) to 1.0 (full volume).
typedef void(*)	ULAudioOutputSetPausedCallback(void *user_data, unsigned int stream_id, bool paused)
	The callback invoked to pause or resume a stream.
typedef void(*)	ULAudioOutputFlushCallback(void *user_data, unsigned int stream_id)
	The callback invoked when the media seeks, to discard a stream's buffered audio.
typedef void(*)	ULAudioOutputStopCallback(void *user_data, unsigned int stream_id)
	The callback invoked when no more samples are coming for a stream.
typedef void(*)	ULAudioOutputDestroyStreamCallback(void *user_data, unsigned int stream_id)
	The callback invoked to destroy a stream and free its resources.
typedef unsigned long long(*)	ULAudioOutputGetPlaybackPositionCallback(void *user_data, unsigned int stream_id)
	The callback invoked to get the number of frames of a stream the device has played since the last flush (or since the stream was created).
typedef ULAudioFormat(*)	ULAudioOutputGetPreferredOutputFormatCallback(void *user_data)
	The callback invoked to get the device's preferred audio format.

Typedef Documentation

ULAudioOutputCreateStreamCallback

typedef void(*) ULAudioOutputCreateStreamCallback(void *user_data, unsigned int stream_id, ULAudioFormat format)

The callback invoked to create a new audio stream (before its first samples are pushed).

Samples will arrive in format. If you can't create the stream, ignore later calls with its id.

ULAudioOutputDestroyStreamCallback

typedef void(*) ULAudioOutputDestroyStreamCallback(void *user_data, unsigned int stream_id)

The callback invoked to destroy a stream and free its resources.

ULAudioOutputFlushCallback

typedef void(*) ULAudioOutputFlushCallback(void *user_data, unsigned int stream_id)

The callback invoked when the media seeks, to discard a stream's buffered audio.

Leave a paused stream paused.

ULAudioOutputGetPlaybackPositionCallback

typedef unsigned long long(*) ULAudioOutputGetPlaybackPositionCallback(void *user_data, unsigned int stream_id)

The callback invoked to get the number of frames of a stream the device has played since the last flush (or since the stream was created).

The count must not advance while the stream is paused. Return 0 if your backend can't report this.

ULAudioOutputGetPreferredOutputFormatCallback

typedef ULAudioFormat(*) ULAudioOutputGetPreferredOutputFormatCallback(void *user_data)

The callback invoked to get the device's preferred audio format.

ULAudioOutputPushSamplesCallback

typedef void(*) ULAudioOutputPushSamplesCallback(void *user_data, unsigned int stream_id, const float *samples, unsigned int num_frames)

The callback invoked to push decoded PCM samples into a stream (num_frames * channels interleaved floats).

When your buffer is full, wait for room instead of dropping samples.

ULAudioOutputSetPausedCallback

typedef void(*) ULAudioOutputSetPausedCallback(void *user_data, unsigned int stream_id, bool paused)

The callback invoked to pause or resume a stream.

Keep the buffered samples while paused.

ULAudioOutputSetVolumeCallback

typedef void(*) ULAudioOutputSetVolumeCallback(void *user_data, unsigned int stream_id, float volume)

The callback invoked to set a stream's volume, from 0.0 (silent) to 1.0 (full volume).

ULAudioOutputStopCallback

typedef void(*) ULAudioOutputStopCallback(void *user_data, unsigned int stream_id)

The callback invoked when no more samples are coming for a stream.

The stream stays valid, and a push_samples call waiting for room must return.

Go to the source code of this file.