Dali VM : MPEG Audio -- C API

Header Files

#include <dvmmpeg.h>

Type Definitions

MpegAudioHdr

MpegAudioHdr contains fields decoded from the bitstream. Only the important fields are described below. For the rest, please refer to the MPEG standard documentation.

	typedef struct MpegAudioHdr {
	    char  id;
	    char  layer;
	    char  bit_rate_index;
	    float bit_rate;
	    char  protection_bit;
	    char  sampling_rate_index;
	    float sampling_rate;
	    char  padding_bit;
	    char  extension;
	    char  mode;
	    char  mode_extension;
	    char  copyright;
	    char  original_or_copy;
	    char  emphasis_index;
	    short error_check;
	} MpegAudioHdr;

id

indicates id of the algorithm. 1 for ISO/IEC 11172-3 audio, 0 for extension to lower sampling rate frequencies per ISO/IEC 13818-3.

layer

can be either MPEG_AUDIO_LAYER_1, MPEG_AUDIO_LAYER_2, or MPEG_AUDIO_LAYER_3.

bit_rate_index

index into the bitrate table.

bit_rate

bitrates of the streams, regardless of the mode, in kbit/s.

protection_bit

1 if error detection is disable. 0 otherwise.

sampling_rate_index

index into the sampling rate table.

sampling_rate

sampling rate of the streams, in kHz.

padding_bit

1 to indicates that the frame has an additional slot to adjust the averate bit rate to the sampling frequency, otherwise this bit is 0. Padding is needed for sampling rates 22.05 and 44.1kHz (and maybe for free format also).

private_bit

for private used. not used by ISO/IEC.

mode

can be either MPEG_AUDIO_STEREO, MPEG_AUDIO_JOINT_STEREO, MPEG_AUDIO_DUAL_CHANNEL, MPEG_AUDIO_SINGLE_CHANNEL.

mode_extension

this is used in join stereo mode. For layer 1 and 2, they indicates which subbands are in intensity_stereo. All other subbands are in stereo. (00 : 4 - 31, 10 : 12 - 31, 01 : 8 - 31, 11 : 16 - 31). For layer 3, it indicates which type of joint stereo coding is applied. The first bit indicates that ms_stereo is on when set. The second bit indicates that intensity_stereo is on. (so 10 means ms_stereo on, intensity_stereo off).

copyright

1 if this file is copyright protected. 0 otherwise.

original_or_copy

1 if this file is original. 0 if this is a copy.

emphasis_index

type of de-emphasis to use. 00 for none, 01 for 50/15 ms, 10 is reserved, and 11 for CCITT J.17

error_check

16 bit CRC.

MpegAudioL1

This stores raw decoded audio data for a single channel from a MPEG-1 Layer 1 audio.

	typedef struct MpegAudioL1 {
	    char allocation[32];
	    char scalefactor[32];
	    unsigned int sample[12][32];
	} MpegAudioL1;

allocation[i]

bit allocation index into bit allocation table. indicates the number of bits used to decode the samples in subband[i].

scalefactor[i]

scale factor index into scale factor table. indicates the factor of subband[i] by which the requantized samples should be multiplied.

sample[j][i]

the j-th sample in subband[i].

MpegAudioL2

This stores raw decoded audio data for a single channel from a MPEG-1 Layer 2 audio.

	typedef struct MpegAudioL2 {
	    int sblimit;
	    char allocation[32];
	    char scalefactor[3][32];
	    unsigned int sample[12][3][32];
	} MpegAudioL2;

sblimit

highest subband encoded

table

a pointer to the allocation table to use.

allocation[i]

bit allocation index into bit allocation table. indicates the number of bits used to decode the samples in subband[i], and whether information on three consecutive samples have been grouped into one.

scalefactor[k][i]

scale factor index for scale factor table. indicates the factor of subband[i] granule[k] by which the requantized samples should be multiplied.

sample[j][k][i]

the j-th sample in granule[k] in subband[i].

MpegAudioL3

This stores raw decoded audio data for both channels from a MPEG-1 Layer 3 audio.

	typedef struct MpegAudioL3 {
	    unsigned short main_data_end;
	    unsigned char  private_bits;
	    unsigned char  scfsi[4][2];
	    unsigned short part2_3_length[2][2];
	    unsigned short big_values[2][2];
	    unsigned char  global_gain[2][2];
	    unsigned char scalefac_compress[2][2];
	    unsigned char block_split_flag[2][2];
	    unsigned char block_type[2][2];
	    unsigned char switch_point[2][2];
	    unsigned char table_select[3][2][2];
	    unsigned char subblock_gain[3][2][2];
	    unsigned char region_address1[2][2];
	    unsigned char region_address2[2][2];
	    unsigned char preflag[2][2];
	    unsigned char scalefac_scale[2][2];
	    unsigned char countltable_table[2][2];
	    char scale_fac_s[2][2][13][3];
	    char scale_fac_l[2][2][23];
	    short zero_freq_start[2][2];
	    int  freq_lines[2][2][576];
	} MpegAudioL3;

main_data_end

Used to determine the location in bitstream of last bit of main_data. See MPEG standard for details.

private_bits

Bits for private use. These bits will not be used in the future by ISO.

scfsi

Scale factor selection information. See MPEG standard for details.

part2_3_length

Number of main_data bits used for scalefactors and Huffman code data. See MPEG standard for details.

big_values

Number of pairs of values in the spectrum. See MPEG standard for details.

global_gain

Quantizer step size information

scalefac_compress

Number of bits used for scalefactors transmission. See MPEG standard for details.

block_split_flag

Indicates whether block uses non-normal window

block_type

The window type. See MPEG standard for details.

switch_point

Split point of short/long transforms

table_select

Which Huffman code table to use

subblock_gain

Gain offset from global gain

region_address1

See MPEG standard for details.

region_address2

See MPEG standard for details.

preflag

Shortcut for additional high frequency amplification of quantized values

scalefac_scale

See MPEG standard for details.

countltable_table

Select one of two possible Huffman code tables

scalefac_s

Scale Factors for short transformation

scalefac_l

Scale Factors for long transformation

zero_freq_start

Where the zero frequency samples begin.

freq_lines

Huffman decoded frequencies.

MpegAudioSynData

This is an auxillary data structure that are needed during subband synthesis.

	typedef struct MpegAudioSynData {
	    int offset;
	    double syn[1024];
	} MpegAudioSynData;

offset

index to the elements in syn that are useful in current frame.

syn

auxillary data for subband synthesis.

MpegAudioGraData

This is an auxillary data structure that are needed during Layer 3 audio decoding.

	typedef double MpegAudioGraData[2][1024];

Constants

MPEG-1 Audio Layer

These values indicate which layer the current audio frame is encoded in.

	#define MPEG_AUDIO_LAYER_1 3
	#define MPEG_AUDIO_LAYER_2 2
	#define MPEG_AUDIO_LAYER_3 1

MPEG-1 Audio Mode

These constants indicate the number of channels the current audio frame has.

	#define MPEG_AUDIO_STEREO 0
	#define MPEG_AUDIO_JOINT_STEREO 1
	#define MPEG_AUDIO_DUAL_CHANNEL 2
	#define MPEG_AUDIO_SINGLE_CHANNEL 3

Return Code

These represent the possible return values from Dali MPEG functions. DVM_MPEG_OK is returned if all goes well. Error codes are: DVM_MPEG_NOT_FOUND, DVM_MPEG_INVALID_START_CODE.

	#define DVM_MPEG_OK 0
	#define DVM_MPEG_NOT_FOUND -1
	#define DVM_MPEG_INVALID_START_CODE -2

Operators

Allocation Primitives

MpegAudioHdr *MpegAudioHdrNew ()

Allocate a new MpegAudioHdr, and return a handle to it. Return NULL if allocation fails.

void MpegAudioHdrFree (MpegAudioHdr *hdr)

Deallocate the MpegAudioHdr pointed to by hdr.

MpegAudioL1 *MpegAudioL1New ()

Allocate a new MpegAudioL1 structure and return a handle to it.

void MpegAudioL1Free (MpegAudioL1 *l1)

Deallocate the MpegAudioL1 structure pointed to by l1.

MpegAudioL2 *MpegAudioL2New ()

Allocate a new MpegAudioL2 structure and return a handle to it.

void MpegAudioL2Free (MpegAudioL2 *l2)

Deallocate the MpegAudioL2 structure pointed to by l2.

MpegAudioL3 *MpegAudioL3New ()

Allocate a new MpegAudioL3 structure and return a handle to it.

void MpegAudioL3Free (MpegAudioL3 *l3)

Deallocate the MpegAudioL3 structure pointed to by l3.

MpegAudioHdr Manipulation

int MpegAudioHdrFind (BitParser *bp)

Scan the bitstream attached to the BitParser bp, and advance the cursor to the beginning of an audio header. Return the number of bytes skipped.

int MpegAudioHdrParse (BitParser *bp, MpegAudioHdr *hdr)

Parse the bitstream attached to BitParser bp, assuming that the cursor is position at the beginning of audio header. The content of MpegAudioHdr is initialized by contents of the audio header from the bitstream. Return the number of bytes parsed.

int MpegAudioHdrDump (BitParser *inbp, BitParser *outbp)

Assuming the cursor of BitParser inbp is at the beginning of audio header, dump the header to the output bitstream attached to BitParser outbp, without parsing the whole header. Returns the number of bytes dumped.

int MpegAudioHdrSkip (BitParser *bp)

Assuming the cursor of BitParser bp is at the beginning of the audio header, skips the header and advance the cursor to the end of the header. Returns the number of bytes skipped.

int MpegAudioHdrEncode (MpegAudioHdr *hdr, BitParser *bp)

Encode the header hdr into output BitStream attached to the BitParser bp. Return the number of bytes encoded.

MpegAudioHdr Queries

int MpegAudioHdrGetLayer (MpegAudioHdr *hdr)

Return the layer of the audio header hdr

int MpegAudioHdrGetMode (MpegAudioHdr *hdr)

Return the mode of the audio header hdr.

double MpegAudioHdrGetBitRate (MpegAudioHdr *hdr)

Return the bit rate of the audio header hdr

double MpegAudioHdrGetSamplingRate (MpegAudioHdr *hdr)

Return the sampling rate of the audio header hdr

MpegAudioL1 Manipulation

void MpegAudioL1MonoParse (BitParser *bp, MpegAudioHdr *hdr, MpegAudioL1 *l1)

Assuming that the bitstream attached to BitParser bp contains data from a mono MPEG Layer 1 audio streams, parse a frame from the stream, and store the data in l1. After parsing, the cursor is at the end of compreseed audio data.

void MpegAudioL1MonoEncode (MpegAudioL1 *l1, MpegAudioHdr *hdr, BitParser *bp)

Encode the audio data in l1 into output bistream attached to BitParser bp.

void MpegAudioL1StereoParse (BitParser *bp, MpegAudioHdr *hdr, MpegAudioL1 *left, MpegAudioL1 *right)

Assuming that the bitstream attached to BitParser bp contains data from a stereo MPEG Layer 1 audio streams, parse a frame from the stream, and store the left and right channel data in left and right respectively. After parsing the cursor is at the end of compreseed audio data.

void MpegAudioL1StereoEncode (MpegAudioL1 *left, MpegAudioL1 *right, MpegAudioHdr *hdr, BitParser *bp)

Encode the left and right channel data in left and right into output bistream attached to BitParser bp.

void MpegAudioL1ToAudio (MpegAudioHdr *hdr, MpegAudioL1 *audio, MpegAudioSynData *syn, Audio *pcm)

Decode the compressed layer 1 audio data in audio into uncompressed pcm audio and store the pcm samples in pcm. syn stores synthesis data that are initialized from decoding of previous frames, and is used in current decoding. syn will be updated for decoding of next frame.

MpegAudioL2 Manipulation

void MpegAudioL2MonoParse (BitParser *bp, MpegAudioHdr *hdr, MpegAudioL2 *l2)

Assuming that the bitstream attached to BitParser bp contains data from a mono MPEG Layer 2 audio streams, parse a frame from the stream, and store the data in l2. After parsing, the cursor is at the end of compreseed audio data.

void MpegAudioL2MonoEncode (MpegAudioL2 *l2, MpegAudioHdr *hdr, BitParser *bp)

Encode the audio data in l2 into output bistream attached to BitParser bp.

void MpegAudioL2StereoParse (BitParser *bp, MpegAudioHdr *hdr, MpegAudioL2 *left, MpegAudioL2 *right)

Assuming that the bitstream attached to BitParser bp contains data from a stereo MPEG Layer 2 audio streams, parse a frame from the stream, and store the left and right channel data in left and right respectively. After parsing, the cursor is at the end of compreseed audio data.

void MpegAudioL2StereoEncode (MpegAudioL2 *left, MpegAudioL2 *right, MpegAudioHdr *hdr, BitParser *bp)

Encode the left and right channel data in left and right into output bistream attached to BitParser bp.

void MpegAudioL2ToAudio (MpegAudioHdr *hdr, MpegAudioL2 *audio, MpegAudioSynData *syn, Audio *pcm)

Decode the compressed layer 2 audio data in audio into uncompressed pcm audio and store the pcm samples in pcm. syn stores synthesis data that are initialized from decoding of previous frames, and is used in current decoding. syn will be updated for decoding of next frame.

double MpegAudioL2ScaleFactorSum (MpegAudioHdr *hdr, MpegAudioL1 *audio)

It computes the sum of the scaling factors among the 1152 samples encoded in audio without actually decoding it and returns the sum.

MpegAudioL3 Manipulation

void MpegAudioL3Parse (BitParser *bp, BitParser *buffer, MpegAudioHdr *hdr, MpegAudioL3 *audio)

Parse the bitstream attached to bitparser bp and store the compressed audio information in audio. Some of the compressed audio may exists in previous frames in the bitstream. These should have been buffered in an auxillary bitstream attached to BitParser buffer, when we parsed the previous frame. Some data from the next frame may exists in current frame as well. In this case we update the auxillary bitstream with those data so that they can be used when parsing next frame. After parsing, the cursor is at the end of compressed audio data.

void MpegAudioL3ToAudio (MpegAudioHdr *hdr, MpegAudioL3 *audio, MpegAudioSynData *lsyn, MpegAudioSynData *rsyn, MpegAudioGraData *gra, Audio *left, Audio *right)

Decode the compressed layer 3 audio data in audio into two channels of uncompressed pcm audio and store the pcm samples in left and right respectively. rsyn and lsyn stores synthesis data that are initialized from decoding of previous frames, and is used in current decoding. Both lsyn and rsyn will be updated for the decoding of next frame. gra has similar usage to lsyn and rsyn.

Misc. Primitives

MpegSynData *MpegSynDataNew ()

Allocate a new MpegSynData, and return a pointer to it. Return NULL if allocation failed.

void MpegSynDataFree (MpegSynData *hdr)

Deallocate the MpegSynData pointed to by hdr

MpegGraData *MpegGraDataNew ()

Allocate a new MpegGraData, and return a pointer to it. Return NULL if allocation failed.

void MpegGraDataFree (MpegGraData *hdr)

Deallocate the MpegGraData pointed to by hdr