Using the liba52 API--------------------liba52 provides a low-level interface to decoding audio frames encodedusing ATSC standard A/52 aka AC-3. liba52 provides downmixing anddynamic range compression for the following output configurations:A52_CHANNEL : Dual mono. Two independant mono channels.A52_CHANNEL1 : First of the two mono channels above.A52_CHANNEL2 : Second of the two mono channels above.A52_MONO : Mono.A52_STEREO : Stereo.A52_DOLBY : Dolby surround compatible stereo.A52_3F : 3 front channels (left, center, right)A52_2F1R : 2 front, 1 rear surround channel (L, R, S)A52_3F1R : 3 front, 1 rear surround channel (L, C, R, S)A52_2F2R : 2 front, 2 rear surround channels (L, R, LS, RS)A52_3F2R : 3 front, 2 rear surround channels (L, C, R, LS, RS)A52_LFE : Low frequency effects channel. Normally used to connect a subwoofer. Can be combined with any of the above channels. For example: A52_3F2R | A52_LFE -> 3 front, 2 rear, 1 LFE (5.1)Initialization--------------sample_t * a52_init (uint32_t mm_accel);Initializes the A/52 library. Takes as a parameter the acceptableoptimizations which may be used, such as MMX. These are found in theincluded header file 'mm_accel', along with an autodetection function(mm_accel()). Currently, the only accelleration implemented isMM_ACCEL_MLIB, which uses the 'mlib' library if installed. mlib isonly available on some Sun Microsystems platforms.The return value is a pointer to a properly-aligned sample buffer usedfor output samples.Probing the bitstream---------------------int a52_syncinfo (uint8_t * buf, int * flags, int * sample_rate, int * bit_rate);The A/52 bitstream is composed of several a52 frames concatenated oneafter each other. An a52 frame is the smallest independantly decodableunit in the stream.buf must contain at least 7 bytes from the input stream. If these looklike the start of a valid a52 frame, a52_syncinfo() returns the sizeof the coded frame in bytes, and fills flags, sample_rate and bit_ratewith the information encoded in the stream. The returned size isguaranteed to be an even number between 128 and 3840. sample_rate willbe the sampling frequency in Hz, bit_rate is for the compressed streamand is in bits per second, and flags is a description of the codedchannels: the A52_LFE bit is set if there is an LFE channel coded inthis stream, and by masking flags with A52_CHANNEL_MASK you will get avalue that describes the full-bandwidth channels, as one of theA52_CHANNEL...A52_3F2R flags.If this can not possibly be a valid frame, then the function returns0. You should then try to re-synchronize with the a52 stream - one wayto try this would be to advance buf by one byte until its contentslooks like a valid frame, but there might be betterapplication-specific ways to synchronize.It is recommended to call this function for each frame, for severalreasons: this function detects errors that the other functions willnot double-check, consecutive frames might have different lengths, andit helps you re-sync with the stream if you get de-synchronized.Starting to decode a frame--------------------------int a52_frame (a52_state_t * state, uint8_t * buf, int * flags, sample_t * level, sample_t bias);This starts the work of decoding the A/52 frame (to be completed usinga52_block()). buf should point to the beginning of the complete frameof the full size returned by a52_syncinfo().You should pass in the flags the speaker configuration that yousupport, and liba52 will return the speaker configuration it will usefor its output, based on what is coded in the stream and what youasked for. For example, if the stream contains 2+2 channels(a52_syncinfo() returned A52_2F2R in the flags), and you have 3+1speakers (you passed A52_3F1R), then liba52 will choose do downmix to2+1 speakers, since there is no center channel to send to your centerspeaker. So in that case the left and right channels will beessentially unmodified by the downmix, and the two surround channelswill be added together and sent to your surround speaker. liba52 willreturn A52_2F1R to indicate this.The good news is that when you downmix to stereo you dont have toworry about this, you will ALWAYS get a stereo output no matter whatwas coded in the stream. For more complex output configurations youwill have to handle the case where liba52 couldnt give you what youwanted because some of the channels were not encoded in the streamthough.Level, bias, and A52_ADJUST_LEVEL:Before downmixing, samples are floating point values with a range of[-1,1]. Most types of downmixing will combine channels together, whichwill potentially result in a larger range for the outputsamples. liba52 provides two methods of controlling the range of theoutput, either before or after the downmix stage.If you do not set A52_ADJUST_LEVEL, liba52 will multiply the samplesby your level value, so that they fit in the [-level,level]range. Then it will apply the standardized downmix equations,potentially making the samples go out of that interval again. Thelevel parameter is not modified.Setting the A52_ADJUST_LEVEL flag will instruct liba52 to treat yourlevel value as the intended range interval after downmixing. It willthen figure out what level to use before the downmix (what you shouldhave passed if you hadnt used the A52_ADJUST_LEVEL flag), andoverwrite the level value you gave it with that new level value.The bias represents a value which should be added to the resultregardless:output_sample = (input_sample * level) + bias;For example, a bias of 384 and a level of 1 tells liba52 you wantsamples between 383 and 385 instead of -1 and 1. This is what thesample program a52dec does, as it makes it faster to convert thesamples to integer format, using a trick based on the IEEEfloating-point format.This function also initialises the state for that frame, which will bereused next when decoding blocks.Dynamic range compression-------------------------void a52_dynrng (a52_state_t * state, sample_t (* call) (sample_t, void *), void * data);This function is purely optional. If you dont call it, liba52 willprovide the default behaviour, which is to apply the full dynamicrange compression as specified in the A/52 stream. This basicallymakes the loud sounds softer, and the soft sounds louder, so you canmore easily listen to the stream in a noisy environment withoutdisturbing anyone.If you do call this function and set a NULL callback, this willtotally disable the dynamic range compression and provide a playbackmore adapted to a movie theater or a listening room.If you call this function and specify a callback function, thiscallback might be called up to once for each block, with twoarguments: the compression factor 'c' recommended by the bitstream,and the private data pointer you specified in a52_dynrng(). Thecallback will then return the amount of compression to actually use -typically pow(c,x) where x is somewhere between 0 and 1. Moreelaborate compression functions might want to use a different valuefor 'x' depending wether c>1 or c<1 - or even something more complexif this is what you want.Decoding blocks---------------int a52_block (a52_state_t * state, sample_t * samples);Every A/52 frame is composed of 6 blocks, each with an output of 256samples for each channel. The a52_block() function decodes the nextblock in the frame, and should be called 6 times to decode all of theaudio in the frame. After each call, you should extract the audio datafrom the sample buffer.The sample pointer given should be the one a52_init() returned.After this function returns, the samples buuffer will contain 256samples for the first channel, followed by 256 samples for the secondchannel, etc... the channel order is LFE, left, center, right, leftsurround, right surround. If one of the channels is not present in theliba52 output, as indicated by the flags returned by a52_frame(), thenthis channel is skipped and the following channels are shifted soliba52 does not leave an empty space between channels.Pseudocode example------------------sample_t * samples = a52_init (mm_accel());loop on input bytes: if at least 7 bytes in the buffer: bytes_to_get = a52_syncinfo (...) if bytes_to_get == 0: goto loop to keep looking for sync point else get rest of bytes a52_frame (state, buf, ...) [a52_dynrng (state, ...); this is only optional] for i = 1 ... 6: a52_block (state, samples) convert samples to integer and queue to soundcard