audio_output Struct Reference

Audio output object. More...

#include <vlc_aout.h>

Collaboration diagram for audio_output:

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

[struct]

struct { ... } audio_output::current_sink_info

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

Referenced by aout_OutputNew().

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 asynchronously (can be NULL).

A drain operation can be cancelled by aout->flush() or aout->stop().

It is legal to continue playback after a drain_async, if flush() is called before the next play().

Call aout_DrainedReport() to notify that the stream is drained.

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

Referenced by stream_IsDrained(), and vlc_aout_stream_Drain().

events

const struct vlc_audio_output_events* audio_output::events

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

flush

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

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

Note

This callback cannot be called in stopped state.

Referenced by aout_OutputNew(), and vlc_aout_stream_Flush().

headphones

bool audio_output::headphones

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

Referenced by aout_OutputNew().

mute_set

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

Changes muting (optional, 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 (can 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, the core will flush the module.

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 vlc_aout_stream_ChangePause().

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_OutputNew(), stream_Silence(), vlc_aout_stream_Drain(), and vlc_aout_stream_Play().

start

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

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

This callback changes the audio output from stopped to playing state (if successful). 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 *restrict delay)

Estimates playback buffer latency (can 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 this callback is not mandatory. 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.

Warning

It is recommended to report the audio delay via aout_TimingReport(). In that case, time_get should not be implemented.

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 stream_GetDelay(), stream_Synchronize(), and vlc_aout_stream_ChangePause().

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