README.experimental
1This xaac codec (external/xaac) is experimental; it is not yet intended
2to be used on production devices.
3
4This codec should not be configured into any production Android device
5that is intended to be shipped.
6
README.md
1# Introduction of the Ex-HEAAC Decoder
2
3
4Ex-HEAAC (Extended HE AAC), the latest upgrade to the MPEG AAC codec family,
5is the audio codec of choice for digital radio and low bit rate
6streaming applications. Selected as the mandatory audio codec for DRM
7(Digital Radio Mondiale), Ex-HEAAC bridges the gap between speech and
8audio coding, and provides consistent high quality audio for all signal
9types, such as speech, music or mixed content.
10
11Another important feature is the codec’s coding efficiency. The audio
12codec produces excellent sound for both music and speech, delivering
13high quality performance at bit rates starting as low as 6 kbit/s for
14mono and 12 kbit/s for stereo services. Thus Ex-HEAAC streaming apps and
15streaming radio players may switch to very low bit rate streams and
16offer a continuous playback even while the network is congested. Once
17more bandwidth becomes available on the network again, the Ex-HEAAC
18client can request a higher bitrate version and seamless switch over
19the full range of bitrates. Audio bitrate that’s being saved due to the
20improved coding efficiency can be used to improve video quality. Ex-HEAAC
21supports AAC and HEAAC v2 as well.
22
23AAC is a popular audio coding technique recommended by MPEG committee.
24The codec handles audio signals sampled in the range of 8 kHz to 96
25kHz. It operates on a frame of 1024 samples. The bit-rates supported
26are in the range of 8 kbps to 576 kbps per channel.
27
28SBR and PS are the tools used in combination with the AAC general audio
29codec resulting in HEAAC v2 (also known as Enhanced AAC Plus). It
30provides significant increase in coding gain. In SBR, the high-band,
31i.e. the high frequency part of the spectrum is replicated using the
32low-band. In PS, channel redundancy is exploited and parameters are
33extracted from a down-mixed channel.The bit-rate is by far below the
34bit-rate required when using conventional AAC coding. This translates
35into better quality at lower bit-rates.
36
37
38# Introduction to Ex-HEAAC Decoder APIs
39
40## Files to be included are
41* [`ixheaacd_apicmd_standards.h`](decoder/ixheaacd_apicmd_standards.h)
42* [`ixheaacd_type_def.h`](decoder/ixheaacd_type_def.h)
43* [`ixheaacd_memory_standards.h`](decoder/ixheaacd_memory_standards.h)
44* [`ixheaacd_error_standards.h`](decoder/ixheaacd_error_standards.h)
45* [`ixheaacd_error_handler.h`](decoder/ixheaacd_error_handler.h)
46* [`ixheaacd_aac_config.h`](decoder/ixheaacd_aac_config.h)
47
48## Decoder APIs
49
50A single API is used to get and set configurations and execute the decode thread, based on command index passed.
51* ia_xheaacd_dec_api
52
53| **API Command** | **API Sub Command** | **Description** |
54|------|------|------|
55|IA_API_CMD_GET_LIB_ID_STRINGS | IA_CMD_TYPE_LIB_NAME | Gets the decoder library name |
56|IA_API_CMD_GET_LIB_ID_STRINGS | IA_CMD_TYPE_LIB_VERSION | Gets the decoder version |
57|IA_API_CMD_GET_API_SIZE | 0 | Gets the memory requirements size of the API |
58|IA_API_CMD_INIT | IA_CMD_TYPE_INIT_API_PRE_CONFIG_PARAMS | Sets the configuration parameters of the Ex-HEAAC v2 Decoder to default values |
59|IA_API_CMD_INIT | IA_CMD_TYPE_INIT_API_POST_CONFIG_PARAMS | Sets the attributes(size, priority, alignment) of all memory types required by the application onto the memory structure |
60|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_SAMP_FREQ | Sets the core AAC sampling frequency for RAW header decoding |
61|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PCM_WDSZ | Sets the bit width of the output pcm samples.The value has to be 16 |
62|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_DOWNMIX | Sets the parameter whether the output needs to be down-mix to mono(1) or not(0) |
63|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_TOSTEREO | Sets the flag to disable interleave mono to stereo |
64|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_DSAMPLE | Sets the parameter whether the output needs to be downsampled(1) or not(0).This is valid only for Ex-HEAAC v2 build |
65|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_FRAMEOK | Sets the flag to 0 or 1 to indicate whether the current frame is valid(1) or not(0) |
66|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_ISMP4 | Sets the flag to 0 or 1 to indicate whether given test vector is an mp4 file or not |
67|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_DISABLE_SYNC | Sets the flag of ADTS syncing or not ADTS syncing as 0 or 1 |
68|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_AUTO_SBR_UPSAMPLE | Sets the parameter auto SBR upsample to 0 or 1.Used in case of stream changing from SBR present to SBR not present.This is valid only for Ex-HEAAC v2 build |
69|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_MAX_CHANNEL | Sets the maximum number of channels present.Its maximum value is 2 for stereo library and 8 for multichannel library |
70|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_COUP_CHANNEL | Sets the number of coupling channels to be used for coupling.It can take values from 0 to 16.This command is supported only if the library has multichannel support |
71|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_DOWNMIX_STEREO | Sets the flag of downmixing n number of channels to stereo.Can be 0 or 1. This command is supported only if the library has multichannel support |
72|IA_API_CMD_SET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_ISLOAS | Sets the flag indicating that the input file is a .loas file.Can be 0 or 1 |
73|IA_API_CMD_GET_N_MEMTABS | 0 | Gets the number of memory types |
74|IA_API_CMD_GET_N_TABLES | 0 | Gets the number of tables |
75|IA_API_CMD_GET_MEM_INFO_SIZE | 0 | Gets the size of the memory type being referred to by the index |
76|IA_API_CMD_GET_MEM_INFO_ALIGNMENT | 0 | Gets the alignment information of the memory-type being referred to by the index |
77|IA_API_CMD_GET_MEM_INFO_TYPE | 0 | Gets the type of memory being referred to by the index |
78|IA_API_CMD_SET_MEM_PTR | 0 | Sets the pointer to the memory being referred to by the index to the input value |
79|IA_API_CMD_GET_TABLE_INFO_SIZE | 0 | Gets the size of the memory type being referred to by the index |
80|IA_API_CMD_GET_TABLE_INFO_ALIGNMENT | 0 | Gets the alignment information of the memory-type being referred to by the index |
81|IA_API_CMD_GET_TABLE_PTR | 0 | Gets the address of the current location of the table |
82|IA_API_CMD_SET_TABLE_PTR | 0 | Sets the relocated table address |
83|IA_API_CMD_INPUT_OVER | 0 | Signals the end of bit-stream to the library |
84|IA_API_CMD_SET_INPUT_BYTES | 0 | Sets the number of bytes available in the input buffer for initialization |
85|IA_API_CMD_INIT | IA_CMD_TYPE_INIT_PROCESS | Search for the valid header, does header decode to get the parameters and initializes state and configuration structure |
86|IA_API_CMD_INIT | IA_CMD_TYPE_INIT_DONE_QUERY | Checks if the initialization process has completed |
87|IA_API_CMD_GET_CURIDX_INPUT_BUF | 0 | Gets the number of input buffer bytes consumed by the last initialization |
88|IA_API_CMD_GET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_SAMP_FREQ | Gets the sampling frequency |
89|IA_API_CMD_GET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_NUM_CHANNELS | Gets the output number of channels |
90|IA_API_CMD_GET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_PCM_WDSZ | Gets the output PCM word size |
91|IA_API_CMD_GET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_CHANNEL_MODE | Gets the channel mode. (Mono or PS/Stereo/Dual-mono) |
92|IA_API_CMD_GET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_CHANNEL_MASK | Gets the channel mask |
93|IA_API_CMD_GET_CONFIG_PARAM | IA_ENHAACPLUS_DEC_CONFIG_PARAM_SBR_MODE | Gets the SBR mode (Present/ Not Present).This is valid only for Ex-HEAAC v2 build |
94|IA_API_CMD_EXECUTE | IA_CMD_TYPE_DO_EXECUTE | Executes the decode thread |
95|IA_API_CMD_EXECUTE | IA_CMD_TYPE_DONE_QUERY | Checks if the end of decode has been reached |
96|IA_API_CMD_GET_OUTPUT_BYTES | 0 | Gets the number of bytes output by the decoder in the last frame |
97
98## Flowchart of calling sequence
99
100
101
102# Building the Ex-HEAAC Decoder
103
104## Building for AOSP
105* Makefiles for building the Ex-HEAAC decoder library is provided in root(`libxaac/`) folder.
106* Makefiles for building the Ex-HEAAC decoder testbench is provided in `test` folder.
107* Build the library followed by the application using the below commands:
108Go to root directory
109```
110$ mm
111```
112
113## Using CMake
114Users can also use cmake to build for `x86`, `x86_64`, and Windows (MSVS project) platforms.
115
116### Creating MSVS project files
117To create MSVS project files for the Ex-HEAAC decoder from cmake, run the following commands:
118```
119Go to the root directory(libxaac/) of the Ex-HEAAC Decoder.
120Create a new folder in the project root directory and move to the newly created folder.
121
122$ cd <path to libxaac>
123$ mkdir bin
124$ cd bin
125$ cmake -G "Visual Studio 15 2017" ..
126```
127
128The above command creates MSVS 2017 project files. If the version is different, modify the generator name accordingly.
129The Ex-HEAAC decoder can be built using these project files.
130
131### Building for native platforms
132Run the following commands to build the Ex-HEAAC Decoder for native platform:
133```
134Go to the root directory(libxaac/) of the Ex-HEAAC Decoder.
135Create a new folder in the project root directory and move to the newly created folder.
136
137$ cd <path to libxaac>
138$ mkdir bin
139$ cd bin
140$ cmake ..
141$ cmake --build .
142```
143
144### Cross-compiler based builds
145### Building for x86_32 on a x86_64 Linux machine
146```
147$ cd <path to libxaac>
148$ mkdir build
149$ cd build
150$ CFLAGS="-m32" CXXFLAGS="-m32" LDFLAGS="-m32" cmake ..
151$ make
152```
153
154### Building for aarch32/aarch64
155Update 'CMAKE_C_COMPILER', 'CMAKE_CXX_COMPILER', 'CMAKE_C_COMPILER_AR', and 'CMAKE_CXX_COMPILER_AR' in CMAKE_TOOLCHAIN_FILE passed below
156```
157$ cd <path to libxaac>
158$ mkdir build
159$ cd build
160```
161
162### For aarch64
163```
164$ cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/aarch64_toolchain.cmake
165$ make
166```
167
168### For aarch32
169```
170$ cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/aarch32_toolchain.cmake
171$ make
172```
173
174# Running the Ex-HEAAC Decoder
175
176The Ex-HEAAC Decoder can be run by providing command-line parameters(CLI options) directly or by providing a parameter file as a command line argument.
177
178Command line usage :
179```
180<executable> -ifile:<input_file> -imeta:<meta_data_file> -ofile:<output_file> [options]
181
182[options] can be,
183[-mp4:<mp4_flag>]
184[-pcmsz:<pcmwordsize>]
185[-dmix:<down_mix>]
186[-esbr_hq:<esbr_hq_flag>]
187[-esbr_ps:<esbr_ps_flag>]
188[-tostereo:<interleave_to_stereo>]
189[-dsample:<down_sample_sbr>]
190[-drc_cut_fac:<drc_cut_factor>]
191[-drc_boost_fac:<drc_boost_factor>]
192[-drc_target_level:<drc_target_level>]
193[-drc_heavy_comp:<drc_heavy_compression>]
194[-effect:<effect_type>]
195[-target_loudness:<target_loudness>]
196[-nosync:<disable_sync>]
197[-sbrup:<auto_sbr_upsample>]
198[-flflag:<framelength_flag>}
199[-fs:<RAW_sample_rate>]
200[-maxchannel:<maximum_num_channels>]
201[-coupchannel:<coupling_channel>]
202[-downmix:<down_mix_stereo>]
203[-fs480:<ld_frame_size>]
204[-ld_testing:<ld_testing_flag>]
205[-peak_limiter_off:<peak_limiter_off_flag>]
206[-err_conceal:<error_concealment_flag>]
207
208where,
209 <input_file> is the input AAC/HEAACv1/HEAACv2/USAC file name.
210 <meta_data_file> is a text file which contains metadata. To be given when -mp4:1 is enabled.
211 <output_file> is the output file name.
212 <mp4_flag> is a flag that should be set to 1 when passing raw stream along with meta data text file.
213 <pcmwordsize> is the bits per sample info. value can be 16 or 24.
214 <down_mix> is to enable/disable always mono output. Default 1.
215 <esbr_hq_flag> is to enable/disable high quality eSBR. Default 0.
216 <esbr_ps_flag> is to indicate eSBR with PS. Default 0.
217 <interleave_to_stereo> is to enable/disable always interleaved to stereo output. Default 1.
218 <down_sample_sbr> is to enable/disable down-sampled SBR output. Default auto identification from header.
219 <drc_cut_factor> is to set DRC cut factor value. Default value is 0.
220 <drc_boost_factor> is to set DRC boost factor. Default value is 0.
221 <drc_target_level> is to set DRC target reference level. Default value is 108.
222 <drc_heavy_compression> is to enable/disable DRC heavy compression. Default value is 0.
223 <effect_type> is to set DRC effect type. Default value is 0.
224 <target_loudness> is to set target loudness level. Default value is -24.
225 <disable_sync> is to disable the ADTS/ADIF sync search i.e when enabled the decoder expects the header to be at the start of input buffer. Default 0.
226 <auto_sbr_upsample> is to enable(1) or disable(0) auto SBR upsample in case of stream changing from SBR present to SBR not present. Default 1.
227 <framelength_flag> is flag for decoding framelength of 1024 or 960. 1 to decode 960 frame length, 0 to decode 1024 frame length.
228 Frame length value in the GA header will override this option. Default 0.
229 <RAW_sample_rate> is to indicate the core AAC sample rate for a RAW stream. If this is specified no other file format headers are searched for.
230 <maximum_num_channels> is the number of maxiumum channels the input may have. Default is 6 for multichannel libraries and 2 for stereo libraries.
231 <coupling_channel> is element instance tag of independent coupling channel to be mixed. Default is 0.
232 <down_mix_stereo> is flag for Downmix. Give 1 to get stereo (downmix) output. Default is 0.
233 <ld_frame_size> is to indicate ld frame size. 0 is for 512 frame length, 1 is for 480 frame length. Default value is 512 (0).
234 <ld_testing_flag> is to enable/disable ld decoder testing. Default value is 0.
235 <peak_limiter_off_flag> is to enable/disable peak limiter. Default value is 0.
236 <error_concealment_flag> is to enable/disable error concealment. Default value is 0.
237
238```
239Sample CLI:
240```
241<xaac_dec_exe> -ifile:in_file.aac -ofile:out_file.wav -pcmsz:16
242```
243
244# Validating the Ex-HEAAC Decoder
245
246Conformance testing for AAC/HEAAC v1/HEAAC v2 mainly involves comparing
247decoder under test output with the ISO and 3GPP reference decoded output.
248
249Testing for USAC is done using encoded streams generated using ISO USAC
250reference encoder. The output generated by ITTIAM USAC decoder is
251compared against the output generated by ISO USAC decoder for 16-bit
252conformance on the respective(ARMv7, ARMv8, X86_32, X86_64) platforms.
253
