git.sesse.net Git - vlc/blob - doc/developer/audio_output.xml

   1 <chapter> <title> The audio output layer </title>
   2
   3   <sect1> <title> Audio output overview </title>
   4
   5     <para>
   6 This chapter documents the audio output layer known under the "audio output 3" codename. It has first been released with VLC version 0.5.0. Previous versions use an antic API, which is no longer documented nor supported. You definitely should write new code only for aout3 and later.
   7     </para>
   8
   9     <para>
  10 The audio output's main purpose is to take sound samples from one or several decoders (called "input streams" in this chapter), to mix them and write them to an output device (called "output stream"). During this process, transformations may be needed or asked by the user, and they will be performed by audio filters.
  11     </para>
  12
  13     <para>
  14 (insert here a schematic of the data flow in aout3)
  15     </para>
  16
  17     <sect2> <title> Typical runcourse </title>
  18
  19       <para>
  20 The input spawns a new decoder audio decoder, say for instance an A/52 decoder. The A/52 decoder parses the sync info for format information, and creates a new aout "input stream" whith aout_InputNew().
  21       </para>
  22
  23     </sect2>
  24
  25   </sect1>
  26
  27   <sect1> <title> API for the decoders </title>
  28
  29   </sect1>
  30
  31   <sect1> <title> API for the output module </title>
  32
  33   </sect1>
  34
  35   <sect1> <title> Writing an audio filter </title>
  36
  37   </sect1>
  38
  39   <sect1> <title> Writing an audio mixer </title>
  40
  41   </sect1>
  42
  43   <sect1> <title> Data exchanges between a decoder and the audio output
  44   </title>
  45
  46     <para>
  47 The audio output basically takes audio samples from one or several
  48 FIFOs, mixes and resamples them, and plays them through the audio
  49 chip. Data exchanges are simple and described in <filename>
  50 src/audio_output/audio_output.c.</filename> A decoder needs to open
  51 a channel FIFO with <function> aout_CreateFifo </function>, and
  52 then write the data to the buffer. The buffer is in <parameter>
  53 p_aout_fifo-&gt;buffer + p_aout_fifo-&gt;l_end_frame </parameter>
  54 * <constant> ADEC_FRAME_SIZE</constant>.
  55     </para>
  56
  57   </sect1>
  58
  59   <sect1> <title> How to write an audio output plugin </title>
  60
  61     <para>
  62 [This API is subject to change in the very near future.] Have a look at
  63 <filename> plugins/dsp/aout_dsp.c</filename>. You need to write six
  64 functions :
  65     </para>
  66
  67     <itemizedlist>
  68
  69       <listitem> <para> <type> int </type> <function> aout_Probe </function>
  70       <parameter> ( probedata_t *p_data ) </parameter> :
  71       Returns a score between 0 and 999 to tell whether the plugin
  72       can be used. <parameter> p_data </parameter> is currently
  73       unused.
  74       </para> </listitem>
  75
  76       <listitem> <para> <type> int </type> <function> aout_Open </function>
  77       <parameter> ( aout_thread_t *p_aout ) </parameter> :
  78       Opens the audio device.
  79       </para> </listitem>
  80
  81       <listitem> <para> <type> int </type> <function> aout_SetFormat
  82       </function> <parameter> ( aout_thread_t *p_aout ) </parameter> :
  83       Sets the output format, the number of channels, and the output
  84       rate.
  85       </para> </listitem>
  86
  87       <listitem> <para> <type> long </type> <function> aout_GetBufInfo
  88       </function> <parameter> ( aout_thread_t *p_aout,
  89       long l_buffer_limit ) </parameter> :
  90       Gets the status of the audio buffer.
  91       </para> </listitem>
  92
  93       <listitem> <para> <function> aout_Play </function> <parameter>
  94       ( aout_thread_t *p_aout, byte_t *buffer, int i_size )
  95       </parameter> :
  96       Writes the audio output buffer to the audio device.
  97       </para> </listitem>
  98
  99       <listitem> <para> <function> aout_Close </function> <parameter>
 100       ( aout_thread_t *p_aout ) </parameter> :
 101       Closes the audio device.
 102       </para> </listitem>
 103
 104     </itemizedlist>
 105
 106   </sect1>
 107
 108 </chapter>