sdk-playback-tutorial-digital-audio-pass-through.md

   1 # Playback tutorial 9: Digital audio pass-through
   2
   3 ## Goal
   4
   5 This tutorial shows how GStreamer handles digital audio pass-through.
   6
   7 ## Introduction
   8
   9 Besides the common analog format, high-end audio systems usually also
  10 accept data in digital form, either compressed or uncompressed. This is
  11 convenient because the audio signal then travels from the computer to
  12 the speakers in a form that is more resilient to interference and noise,
  13 resulting higher quality.
  14
  15 The connection is typically made through an
  16 [S/PDIF](http://en.wikipedia.org/wiki/SPDIF) cable which can either be
  17 optical (with [TOSLINK](http://en.wikipedia.org/wiki/TOSLINK)
  18 connectors) or coaxial (with [RCA](http://en.wikipedia.org/wiki/RCA)
  19 connectors). S/PDIF is also known as IEC 60958 type II (IEC 958 before
  20 1998).
  21
  22 In this scenario, GStreamer does not need to perform audio decoding; it
  23 can simply output the encoded data, acting in *pass-through* mode, and
  24 let the external audio system perform the decoding.
  25
  26 ## Inner workings of GStreamer audio sinks
  27
  28 First off, digital audio output must be enabled at the system level. The
  29 method to achieve this depend on the operating system, but it generally
  30 involves going to the audio control panel and activating a checkbox
  31 reading “Digital Audio Output” or similar.
  32
  33 The main GStreamer audio sinks for each platform, Pulse Audio
  34 (`pulsesink`) for Linux, `osxaudiosink` for OS X and Direct Sound
  35 (`directsoundsink`) for Windows, detect when digital audio output is
  36 available and change their input caps accordingly to accept encoded
  37 data. For example, these elements typically accept `audio/x-raw` data:
  38 when digital audio output is enabled in the system, they may also
  39 accept `audio/mpeg`, `audio/x-ac3`, `audio/x-eac3` or `audio/x-dts`.
  40
  41 Then, when `playbin` builds the decoding pipeline, it realizes that the
  42 audio sink can be directly connected to the encoded data (typically
  43 coming out of a demuxer), so there is no need for a decoder. This
  44 process is automatic and does not need any action from the application.
  45
  46 On Linux, there exist other audio sinks, like Alsa (`alsasink`) which
  47 work differently (a “digital device” needs to be manually selected
  48 through the `device` property of the sink). Pulse Audio, though, is the
  49 commonly preferred audio sink on Linux.
  50
  51 ## Precautions with digital formats
  52
  53 When Digital Audio Output is enabled at the system level, the GStreamer
  54 audio sinks automatically expose all possible digital audio caps,
  55 regardless of whether the actual audio decoder at the end of the S/PDIF
  56 cable is able to decode all those formats. This is so because there is
  57 no mechanism to query an external audio decoder which formats are
  58 supported, and, in fact, the cable can even be disconnected during this
  59 process.
  60
  61 For example, after enabling Digital Audio Output in the system’s Control
  62 Panel,  `directsoundsink`  will automatically expose `audio/x-ac3`,
  63 `audio/x-eac3` and `audio/x-dts` caps in addition to `audio/x-raw`.
  64 However, one particular external decoder might only understand raw
  65 integer streams and would try to play the compressed data as such (a
  66 painful experience for your ears, rest assured).
  67
  68 Solving this issue requires user intervention, since only the user knows
  69 the formats supported by the external decoder.
  70
  71 On some systems, the simplest solution is to inform the operating system
  72 of the formats that the external audio decoder can accept. In this way,
  73 the GStreamer audio sinks will only offer these formats. The acceptable
  74 audio formats are commonly selected from the operating system’s audio
  75 configuration panel, from the same place where Digital Audio Output is
  76 enabled, but, unfortunately, this option is not available in all audio
  77 drivers.
  78
  79 Another solution involves, using a custom sinkbin (see
  80 [](sdk-playback-tutorial-custom-playbin-sinks.md)) which includes a
  81 `capsfilter` element (see [](sdk-basic-tutorial-handy-elements.md))
  82 and an audio sink. The caps that the external decoder supports are
  83 then set in the capsfiler so the wrong format is not output. This
  84 allows the application to enforce the appropriate format instead of
  85 relying on the user to have the system correctly configured. Still
  86 requires user intervention, but can be used regardless of the options
  87 the audio driver offers.
  88
  89 Please do not use `autoaudiosink` as the audio sink, as it currently
  90 only supports raw audio, and will ignore any compressed format.
  91
  92 ## Conclusion
  93
  94 This tutorial has shown a bit of how GStreamer deals with digital audio.
  95 In particular, it has shown that:
  96
  97   - Applications using `playbin` do not need to do anything special to
  98     enable digital audio output: it is managed from the audio control
  99     panel of the operating system.
 100
 101 It has been a pleasure having you here, and see you soon!