VLC  4.0.0-dev
Data Fields
audio_output Struct Reference

Audio output object. More...

Collaboration diagram for audio_output:
Collaboration graph
[legend]

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_eventsevents
 

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
idnul-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

◆ flush

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

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

Parameters
waittrue 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
mutetrue 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
pausepause if true, resume from pause if false
datetimestamp 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
blockblock of audio samples
dateintended 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
fmtinput 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
delaypointer 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_OutputNew(), and aout_TimeGet().

◆ volume_set

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

Changes playback volume (optional, may be NULL).

Parameters
volumerequested 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: