VLC  4.0.0-dev

Audio output object. More...

Collaboration diagram for audio_output:
[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 (can 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 asynchronously (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 (optional, 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 information 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

◆ 

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
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 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 vlc_aout_stream_Drain(), and vlc_aout_stream_IsDrained().

◆ events

◆ 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(), aout_PauseDefault(), vlc_aout_stream_ChangePause(), 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
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_OutputNew(), and 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
blockblock of audio samples
dateintended 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 *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
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 (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
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 stream_TimeGet(), vlc_aout_stream_ChangePause(), and vlc_aout_stream_Play().

◆ 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: