liba52/liba52.txt

   1 Using the liba52 API
   2 --------------------
   3
   4 liba52 provides a low-level interface to decoding audio frames encoded
   5 using ATSC standard A/52 aka AC-3. liba52 provides downmixing and
   6 dynamic range compression for the following output configurations:
   7
   8 A52_CHANNEL  : Dual mono. Two independant mono channels.
   9 A52_CHANNEL1 : First of the two mono channels above.
  10 A52_CHANNEL2 : Second of the two mono channels above.
  11 A52_MONO     : Mono.
  12 A52_STEREO   : Stereo.
  13 A52_DOLBY    : Dolby surround compatible stereo.
  14 A52_3F       : 3 front channels (left, center, right)
  15 A52_2F1R     : 2 front, 1 rear surround channel (L, R, S)
  16 A52_3F1R     : 3 front, 1 rear surround channel (L, C, R, S)
  17 A52_2F2R     : 2 front, 2 rear surround channels (L, R, LS, RS)
  18 A52_3F2R     : 3 front, 2 rear surround channels (L, C, R, LS, RS)
  19
  20 A52_LFE      : Low frequency effects channel. Normally used to connect a
  21                subwoofer. Can be combined with any of the above channels.
  22                For example: A52_3F2R | A52_LFE -> 3 front, 2 rear, 1 LFE (5.1)
  23
  24
  25 Initialization
  26 --------------
  27
  28 sample_t * a52_init (uint32_t mm_accel);
  29
  30 Initializes the A/52 library. Takes as a parameter the acceptable
  31 optimizations which may be used, such as MMX. These are found in the
  32 included header file 'mm_accel', along with an autodetection function
  33 (mm_accel()). Currently, the only accelleration implemented is
  34 MM_ACCEL_MLIB, which uses the 'mlib' library if installed. mlib is
  35 only available on some Sun Microsystems platforms.
  36
  37 The return value is a pointer to a properly-aligned sample buffer used
  38 for output samples.
  39
  40
  41 Probing the bitstream
  42 ---------------------
  43
  44 int a52_syncinfo (uint8_t * buf, int * flags,
  45                   int * sample_rate, int * bit_rate);
  46
  47 The A/52 bitstream is composed of several a52 frames concatenated one
  48 after each other. An a52 frame is the smallest independantly decodable
  49 unit in the stream.
  50
  51 buf must contain at least 7 bytes from the input stream. If these look
  52 like the start of a valid a52 frame, a52_syncinfo() returns the size
  53 of the coded frame in bytes, and fills flags, sample_rate and bit_rate
  54 with the information encoded in the stream. The returned size is
  55 guaranteed to be an even number between 128 and 3840. sample_rate will
  56 be the sampling frequency in Hz, bit_rate is for the compressed stream
  57 and is in bits per second, and flags is a description of the coded
  58 channels: the A52_LFE bit is set if there is an LFE channel coded in
  59 this stream, and by masking flags with A52_CHANNEL_MASK you will get a
  60 value that describes the full-bandwidth channels, as one of the
  61 A52_CHANNEL...A52_3F2R flags.
  62
  63 If this can not possibly be a valid frame, then the function returns
  64 0. You should then try to re-synchronize with the a52 stream - one way
  65 to try this would be to advance buf by one byte until its contents
  66 looks like a valid frame, but there might be better
  67 application-specific ways to synchronize.
  68
  69 It is recommended to call this function for each frame, for several
  70 reasons: this function detects errors that the other functions will
  71 not double-check, consecutive frames might have different lengths, and
  72 it helps you re-sync with the stream if you get de-synchronized.
  73
  74
  75 Starting to decode a frame
  76 --------------------------
  77
  78 int a52_frame (a52_state_t * state, uint8_t * buf, int * flags,
  79                sample_t * level, sample_t bias);
  80
  81 This starts the work of decoding the A/52 frame (to be completed using
  82 a52_block()). buf should point to the beginning of the complete frame
  83 of the full size returned by a52_syncinfo().
  84
  85 You should pass in the flags the speaker configuration that you
  86 support, and liba52 will return the speaker configuration it will use
  87 for its output, based on what is coded in the stream and what you
  88 asked for. For example, if the stream contains 2+2 channels
  89 (a52_syncinfo() returned A52_2F2R in the flags), and you have 3+1
  90 speakers (you passed A52_3F1R), then liba52 will choose do downmix to
  91 2+1 speakers, since there is no center channel to send to your center
  92 speaker. So in that case the left and right channels will be
  93 essentially unmodified by the downmix, and the two surround channels
  94 will be added together and sent to your surround speaker. liba52 will
  95 return A52_2F1R to indicate this.
  96
  97 The good news is that when you downmix to stereo you dont have to
  98 worry about this, you will ALWAYS get a stereo output no matter what
  99 was coded in the stream. For more complex output configurations you
 100 will have to handle the case where liba52 couldnt give you what you
 101 wanted because some of the channels were not encoded in the stream
 102 though.
 103
 104 Level, bias, and A52_ADJUST_LEVEL:
 105
 106 Before downmixing, samples are floating point values with a range of
 107 [-1,1]. Most types of downmixing will combine channels together, which
 108 will potentially result in a larger range for the output
 109 samples. liba52 provides two methods of controlling the range of the
 110 output, either before or after the downmix stage.
 111
 112 If you do not set A52_ADJUST_LEVEL, liba52 will multiply the samples
 113 by your level value, so that they fit in the [-level,level]
 114 range. Then it will apply the standardized downmix equations,
 115 potentially making the samples go out of that interval again. The
 116 level parameter is not modified.
 117
 118 Setting the A52_ADJUST_LEVEL flag will instruct liba52 to treat your
 119 level value as the intended range interval after downmixing. It will
 120 then figure out what level to use before the downmix (what you should
 121 have passed if you hadnt used the A52_ADJUST_LEVEL flag), and
 122 overwrite the level value you gave it with that new level value.
 123
 124 The bias represents a value which should be added to the result
 125 regardless:
 126
 127 output_sample = (input_sample * level) + bias;
 128
 129 For example, a bias of 384 and a level of 1 tells liba52 you want
 130 samples between 383 and 385 instead of -1 and 1. This is what the
 131 sample program a52dec does, as it makes it faster to convert the
 132 samples to integer format, using a trick based on the IEEE
 133 floating-point format.
 134
 135 This function also initialises the state for that frame, which will be
 136 reused next when decoding blocks.
 137
 138
 139 Dynamic range compression
 140 -------------------------
 141
 142 void a52_dynrng (a52_state_t * state,
 143                  sample_t (* call) (sample_t, void *), void * data);
 144
 145 This function is purely optional. If you dont call it, liba52 will
 146 provide the default behaviour, which is to apply the full dynamic
 147 range compression as specified in the A/52 stream. This basically
 148 makes the loud sounds softer, and the soft sounds louder, so you can
 149 more easily listen to the stream in a noisy environment without
 150 disturbing anyone.
 151
 152 If you do call this function and set a NULL callback, this will
 153 totally disable the dynamic range compression and provide a playback
 154 more adapted to a movie theater or a listening room.
 155
 156 If you call this function and specify a callback function, this
 157 callback might be called up to once for each block, with two
 158 arguments: the compression factor 'c' recommended by the bitstream,
 159 and the private data pointer you specified in a52_dynrng(). The
 160 callback will then return the amount of compression to actually use -
 161 typically pow(c,x) where x is somewhere between 0 and 1. More
 162 elaborate compression functions might want to use a different value
 163 for 'x' depending wether c>1 or c<1 - or even something more complex
 164 if this is what you want.
 165
 166
 167 Decoding blocks
 168 ---------------
 169
 170 int a52_block (a52_state_t * state, sample_t * samples);
 171
 172 Every A/52 frame is composed of 6 blocks, each with an output of 256
 173 samples for each channel. The a52_block() function decodes the next
 174 block in the frame, and should be called 6 times to decode all of the
 175 audio in the frame. After each call, you should extract the audio data
 176 from the sample buffer.
 177
 178 The sample pointer given should be the one a52_init() returned.
 179
 180 After this function returns, the samples buuffer will contain 256
 181 samples for the first channel, followed by 256 samples for the second
 182 channel, etc... the channel order is LFE, left, center, right, left
 183 surround, right surround. If one of the channels is not present in the
 184 liba52 output, as indicated by the flags returned by a52_frame(), then
 185 this channel is skipped and the following channels are shifted so
 186 liba52 does not leave an empty space between channels.
 187
 188
 189 Pseudocode example
 190 ------------------
 191
 192 sample_t * samples = a52_init (mm_accel());
 193
 194 loop on input bytes:
 195   if at least 7 bytes in the buffer:
 196
 197     bytes_to_get = a52_syncinfo (...)
 198
 199     if bytes_to_get == 0:
 200       goto loop to keep looking for sync point
 201     else
 202       get rest of bytes
 203
 204       a52_frame (state, buf, ...)
 205       [a52_dynrng (state, ...); this is only optional]
 206       for i = 1 ... 6:
 207         a52_block (state, samples)
 208         convert samples to integer and queue to soundcard