audio_output Struct Reference

Audio output object. More...

Collaboration diagram for audio_output:

Data Fields
struct vlc_object_t	obj
void *	sys
	Private data for callbacks. More...
int(*	start )(audio_output_t *, audio_sample_format_t *fmt)
	Starts a new stream (mandatory, cannot be NULL). More...
void(*	stop )(audio_output_t *)
	Stops the existing stream (mandatory, cannot be NULL). More...
int(*	time_get )(audio_output_t *, vlc_tick_t *delay)
	Estimates playback buffer latency (mandatory, cannot be NULL). More...
void(*	play )(audio_output_t *, block_t *block, vlc_tick_t date)
	Queues a block of samples for playback (mandatory, cannot be NULL). More...
void(*	pause )(audio_output_t *, bool pause, vlc_tick_t date)
	Pauses or resumes playback (mandatory, cannot be NULL). More...
void(*	flush )(audio_output_t *)
	Flushes the playback buffers (mandatory, cannot be NULL). More...
void(*	drain )(audio_output_t *)
	Drain the playback buffers (can be NULL). More...
int(*	volume_set )(audio_output_t *, float volume)
	Changes playback volume (optional, may be NULL). More...
int(*	mute_set )(audio_output_t *, bool mute)
	Changes muting (optinal, may be NULL). More...
int(*	device_select )(audio_output_t *, const char *id)
	Selects an audio output device (optional, may be NULL). More...
struct {
bool   headphones
	Default to false, set it to true if the current sink is using headphones. More...
}	current_sink_info
	Current sink informations set by the module from the start() function. More...
const struct vlc_audio_output_events *	events

Detailed Description

Audio output object.

The audio output object is the abstraction for rendering decoded (or pass-through) audio samples. In addition to playing samples, the abstraction exposes controls for pause/resume, flush/drain, changing the volume or mut flag, and listing and changing output device.

An audio output can be in one of three different states: stopped, playing or paused. The audio output is always created in stopped state and is always destroyed in that state also. It is moved from stopped to playing state by start(), and from playing or paused states back to stopped state by stop().

Field Documentation

current_sink_info

struct { ... } audio_output::current_sink_info

Current sink informations set by the module from the start() function.

Referenced by aout_OutputNew(), and aout_PrepareStereoMode().

device_select

int(* audio_output::device_select) (audio_output_t *, const char *id)

Selects an audio output device (optional, may be NULL).

Parameters

id	nul-terminated device unique identifier.

Returns

0 on success, non-zero on failure.

Warning

The same constraints apply as with volume_set().

Referenced by aout_Destroy(), aout_DeviceSet(), and aout_New().

drain

void(* audio_output::drain) (audio_output_t *)

Drain the playback buffers (can be NULL).

If NULL, the caller will wait for the delay returned by time_get before calling stop().

Referenced by aout_Drain().

events

const struct vlc_audio_output_events* audio_output::events

Referenced by aout_DeviceReport(), aout_GainRequest(), aout_HotplugReport(), aout_MuteReport(), aout_New(), aout_PolicyReport(), aout_RestartRequest(), and aout_VolumeReport().

flush

void(* audio_output::flush) (audio_output_t *)

Flushes the playback buffers (mandatory, cannot be NULL).

Parameters

wait	true to wait for playback of pending buffers (drain), false to discard pending buffers (flush)

Note

This callback cannot be called in stopped state.

Referenced by aout_DecChangePause(), aout_DecFlush(), aout_OutputNew(), and aout_PauseDefault().

headphones

bool audio_output::headphones

Default to false, set it to true if the current sink is using headphones.

Referenced by aout_OutputNew(), and aout_PrepareStereoMode().

mute_set

int(* audio_output::mute_set) (audio_output_t *, bool mute)

Changes muting (optinal, may be NULL).

Parameters

mute	true to mute, false to unmute

Warning

The same constraints apply as with volume_set().

Referenced by aout_Destroy(), aout_MuteSet(), and aout_New().

obj

struct vlc_object_t audio_output::obj

pause

void(* audio_output::pause) (audio_output_t *, bool pause, vlc_tick_t date)

Pauses or resumes playback (mandatory, cannot be NULL).

This callback pauses or resumes audio playback as quickly as possible. When pausing, it is desirable to stop producing sound immediately, but retain already queued audio samples in the buffer to play when later when resuming.

If pausing is impossible, then aout_PauseDefault() can provide a fallback implementation of this callback.

Parameters

pause	pause if true, resume from pause if false
date	timestamp when the pause or resume was requested

Note

This callback cannot be called in stopped state.

Referenced by aout_DecChangePause(), and aout_OutputNew().

play

void(* audio_output::play) (audio_output_t *, block_t *block, vlc_tick_t date)

Queues a block of samples for playback (mandatory, cannot be NULL).

The first play() date (after a flush()/start()) will be most likely in the future. Modules that don't know the hw latency before a first play (when they return -1 from the first time_get()) will need to handle this. They can play a silence buffer with 'length = date - now()', or configure their render callback to start at the given date.

Parameters

block	block of audio samples
date	intended system time to render the first sample

Note

This callback cannot be called in stopped state.

Referenced by aout_DecDrain(), aout_DecPlay(), aout_DecSilence(), and aout_OutputNew().

start

int(* audio_output::start) (audio_output_t *, audio_sample_format_t *fmt)

Starts a new stream (mandatory, cannot be NULL).

This callback changes the audio output from stopped to playing state (if succesful). After the callback returns, time_get(), play(), pause(), flush() and eventually stop() callbacks may be called.

Parameters

fmt	input stream sample format upon entry, output stream sample format upon return [IN/OUT]

Returns

VLC_SUCCESS on success, non-zero on failure

Note

This callback can only be called while the audio output is in stopped state. There can be only one stream per audio output at a time.

This callbacks needs not be reentrant.

Referenced by aout_New(), and aout_OutputNew().

stop

void(* audio_output::stop) (audio_output_t *)

Stops the existing stream (mandatory, cannot be NULL).

This callback terminates the current audio stream, and returns the audio output to stopped state.

Note

This callback needs not be reentrant.

Referenced by aout_New(), and aout_OutputDelete().

sys

void* audio_output::sys

Private data for callbacks.

time_get

int(* audio_output::time_get) (audio_output_t *, vlc_tick_t *delay)

Estimates playback buffer latency (mandatory, cannot be NULL).

This callback computes an estimation of the delay until the current tail of the audio output buffer would be rendered. This is essential for (lip) synchronization and long term drift between the audio output clock and the media upstream clock (if any).

If the audio output clock is exactly synchronized with the system monotonic clock (i.e. vlc_tick_now()), then aout_TimeGetDefault() can implement this callback. In that case, drain must be implemented (since the default implementation uses the delay to wait for the end of the stream).

This callback is called before the first play() in order to get the initial delay (the hw latency). Most modules won't be able to know this latency before the first play. In that case, they should return -1 and handle the first play() date, cf. play() documentation.

Parameters

delay

pointer to the delay until the next sample to be written to the playback buffer is rendered [OUT]

Returns

0 on success, non-zero on failure or lack of data

Note

This callback cannot be called in stopped state.

Referenced by aout_DecSynchronize(), aout_Drain(), and aout_OutputNew().

volume_set

int(* audio_output::volume_set) (audio_output_t *, float volume)

Changes playback volume (optional, may be NULL).

Parameters

volume

requested volume (0. = mute, 1. = nominal)

Note

The volume is always a positive number.

Warning

A stream may or may not have been started when called.

This callback may be called concurrently with time_get(), play(), pause() or flush(). It will however be protected against concurrent calls to start(), stop(), volume_set(), mute_set() or device_select().

Referenced by aout_Destroy(), aout_New(), and aout_VolumeSet().

---

The documentation for this struct was generated from the following file:

• include/vlc_aout.h