Hacker Guide/Audio Output

Description

An audio output module is used to pass decoded audio frames to the audio output hardware. Normally, the audio frames contain an integral number of audio samples coded linearly, i.e. [1]. However, to address the need for digital audio pass-through, the audio output may also receive coded audio frames encapsulated as S/PDIF packets.

This describes the fourth version of the audio output layer, found in VLC version 1.2.0. Versions 0.5.0 to 1.1.x were based on a partly similar but nevertheless incompatible interface known as aout3.

Writing an audio output module

An audio output module should be declared with the correct capability and category as follows:

set_capability("audio output", 60)
set_category(CAT_AUDIO)
set_subcategory(SUBCAT_AUDIO_AOUT)

For more details on writing modules in general, see Documentation:Hacker's Guide/Module Writers Guide.

Priority

Unless a specific module has been provisioned in the VLC preferences, or specified through the --aout command line parameter, LibVLC will try to each audio output module in order of decreasing priority until one succeeds. As usual modules with a priority of zero will never be probed unless configured explicitly.

Thus, on Linux for instance, the PulseAudio module has a higher priority than the ALSA one, and the OSS module has the smallest (non-zero) priority. The file audio output has zero priority and will not be used normally. This is so that VLC uses PulseAudio if available, otherwise ALSA, otherwise OSS.

Initialization

The audio output will be probed and initialized with the typical Open() callback. The audio output should check the input audio format in audio_output_t.format:

static int Open (vlc_object_t *obj)
{
    audio_output_t *aout = (audio_output_t *)obj;

    vlc_fourcc_t format = aout->format.i_format;
    unsigned samplerate = aout->format.i_rate;
    unsigned channels = aout_FormatNbChannels(&aout->format);
    /* ... */
}

The format is usually VLC_CODEC_FL32 (float) on desktop systems, and either VLC_CODEC_FI32 (32-bits fixed point) or VLC_CODEC_S16N (int16_t) on FPU-less embedded architectures. However, it can also be VLC_CODEC_MPGA (MPEG 2 Audio), VLC_CODEC_A52 (AC-3) or VLC_CODEC_DTS (DTS) if the input uses a codec susceptible to S/PDIF encapsulation for digital pass-through.

The sample rate is the sample rate that comes from the decoder or the audio filters, so is the channel mapping.

If possible, it is recommended that the audio output uses a format as close to the input as possible. This is to conversion and loss of quality. Nevertheless, it is often necessary to use different a output format due to hardware limitation: - resample if the aout->format.i_rate is modified, - remix the channels if aout->format.i_physical_channels and/or aout->format.i_original_channels are modified, - convert the sample format is aout->format.i_format is modified.

Warning

Beware that the Open() callback must not change aout->format until it is absolutely certain to return VLC_SUCCESS (0). If it were to change the format and then return an initialization failure, subsequent modules would get corrupt informations about the input format!