• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /* -----------------------------------------------------------------------------
2 Software License for The Fraunhofer FDK AAC Codec Library for Android
3 
4 © Copyright  1995 - 2018 Fraunhofer-Gesellschaft zur Förderung der angewandten
5 Forschung e.V. All rights reserved.
6 
7  1.    INTRODUCTION
8 The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software
9 that implements the MPEG Advanced Audio Coding ("AAC") encoding and decoding
10 scheme for digital audio. This FDK AAC Codec software is intended to be used on
11 a wide variety of Android devices.
12 
13 AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient
14 general perceptual audio codecs. AAC-ELD is considered the best-performing
15 full-bandwidth communications codec by independent studies and is widely
16 deployed. AAC has been standardized by ISO and IEC as part of the MPEG
17 specifications.
18 
19 Patent licenses for necessary patent claims for the FDK AAC Codec (including
20 those of Fraunhofer) may be obtained through Via Licensing
21 (www.vialicensing.com) or through the respective patent owners individually for
22 the purpose of encoding or decoding bit streams in products that are compliant
23 with the ISO/IEC MPEG audio standards. Please note that most manufacturers of
24 Android devices already license these patent claims through Via Licensing or
25 directly from the patent owners, and therefore FDK AAC Codec software may
26 already be covered under those patent licenses when it is used for those
27 licensed purposes only.
28 
29 Commercially-licensed AAC software libraries, including floating-point versions
30 with enhanced sound quality, are also available from Fraunhofer. Users are
31 encouraged to check the Fraunhofer website for additional applications
32 information and documentation.
33 
34 2.    COPYRIGHT LICENSE
35 
36 Redistribution and use in source and binary forms, with or without modification,
37 are permitted without payment of copyright license fees provided that you
38 satisfy the following conditions:
39 
40 You must retain the complete text of this software license in redistributions of
41 the FDK AAC Codec or your modifications thereto in source code form.
42 
43 You must retain the complete text of this software license in the documentation
44 and/or other materials provided with redistributions of the FDK AAC Codec or
45 your modifications thereto in binary form. You must make available free of
46 charge copies of the complete source code of the FDK AAC Codec and your
47 modifications thereto to recipients of copies in binary form.
48 
49 The name of Fraunhofer may not be used to endorse or promote products derived
50 from this library without prior written permission.
51 
52 You may not charge copyright license fees for anyone to use, copy or distribute
53 the FDK AAC Codec software or your modifications thereto.
54 
55 Your modified versions of the FDK AAC Codec must carry prominent notices stating
56 that you changed the software and the date of any change. For modified versions
57 of the FDK AAC Codec, the term "Fraunhofer FDK AAC Codec Library for Android"
58 must be replaced by the term "Third-Party Modified Version of the Fraunhofer FDK
59 AAC Codec Library for Android."
60 
61 3.    NO PATENT LICENSE
62 
63 NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without
64 limitation the patents of Fraunhofer, ARE GRANTED BY THIS SOFTWARE LICENSE.
65 Fraunhofer provides no warranty of patent non-infringement with respect to this
66 software.
67 
68 You may use this FDK AAC Codec software or modifications thereto only for
69 purposes that are authorized by appropriate patent licenses.
70 
71 4.    DISCLAIMER
72 
73 This FDK AAC Codec software is provided by Fraunhofer on behalf of the copyright
74 holders and contributors "AS IS" and WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
75 including but not limited to the implied warranties of merchantability and
76 fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
77 CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary,
78 or consequential damages, including but not limited to procurement of substitute
79 goods or services; loss of use, data, or profits, or business interruption,
80 however caused and on any theory of liability, whether in contract, strict
81 liability, or tort (including negligence), arising in any way out of the use of
82 this software, even if advised of the possibility of such damage.
83 
84 5.    CONTACT INFORMATION
85 
86 Fraunhofer Institute for Integrated Circuits IIS
87 Attention: Audio and Multimedia Departments - FDK AAC LL
88 Am Wolfsmantel 33
89 91058 Erlangen, Germany
90 
91 www.iis.fraunhofer.de/amm
92 amm-info@iis.fraunhofer.de
93 ----------------------------------------------------------------------------- */
94 
95 /**************************** SBR decoder library ******************************
96 
97    Author(s):
98 
99    Description:
100 
101 *******************************************************************************/
102 
103 /*!
104   \file
105   \brief  Envelope extraction prototypes
106 */
107 
108 #ifndef ENV_EXTR_H
109 #define ENV_EXTR_H
110 
111 #include "sbrdecoder.h"
112 
113 #include "FDK_bitstream.h"
114 #include "lpp_tran.h"
115 
116 #include "psdec.h"
117 #include "pvc_dec.h"
118 
119 #define ENV_EXP_FRACT 0
120 /*!< Shift raw envelope data to support fractional numbers.
121   Can be set to 8 instead of 0 to enhance accuracy during concealment.
122   This is not required for conformance and #requantizeEnvelopeData() will
123   become more expensive.
124 */
125 
126 #define EXP_BITS 6
127 /*!< Size of exponent-part of a pseudo float envelope value (should be at least
128   6). The remaining bits in each word are used for the mantissa (should be at
129   least 10). This format is used in the arrays iEnvelope[] and
130   sbrNoiseFloorLevel[] in the FRAME_DATA struct which must fit in a certain part
131   of the output buffer (See buffer management in sbr_dec.cpp). Exponents and
132   mantissas could also be stored in separate arrays. Accessing the exponent or
133   the mantissa would be simplified and the masks #MASK_E resp. #MASK_M would
134   no longer be required.
135 */
136 
137 #define MASK_M                                                          \
138   (((1 << (FRACT_BITS - EXP_BITS)) - 1)                                 \
139    << EXP_BITS) /*!< Mask for extracting the mantissa of a pseudo float \
140                    envelope value */
141 #define MASK_E                                                            \
142   ((1 << EXP_BITS) - 1) /*!< Mask for extracting the exponent of a pseudo \
143                            float envelope value */
144 
145 #define SIGN_EXT \
146   (((SCHAR)-1) ^ \
147    MASK_E) /*!< a CHAR-constant with all bits above our sign-bit set */
148 #define ROUNDING                                                           \
149   ((FIXP_SGL)(                                                             \
150       1 << (EXP_BITS - 1))) /*!< 0.5-offset for rounding the mantissa of a \
151                                pseudo-float envelope value */
152 #define NRG_EXP_OFFSET                                                         \
153   16 /*!< Will be added to the reference energy's exponent to prevent negative \
154         numbers */
155 #define NOISE_EXP_OFFSET                                                \
156   38 /*!< Will be added to the noise level exponent to prevent negative \
157         numbers */
158 
159 #define ADD_HARMONICS_FLAGS_SIZE 2 /* ceil(MAX_FREQ_COEFFS/32) */
160 
161 typedef enum {
162   HEADER_NOT_PRESENT,
163   HEADER_ERROR,
164   HEADER_OK,
165   HEADER_RESET
166 } SBR_HEADER_STATUS;
167 
168 typedef enum {
169   SBR_NOT_INITIALIZED = 0,
170   UPSAMPLING = 1,
171   SBR_HEADER = 2,
172   SBR_ACTIVE = 3
173 } SBR_SYNC_STATE;
174 
175 typedef enum { COUPLING_OFF = 0, COUPLING_LEVEL, COUPLING_BAL } COUPLING_MODE;
176 
177 typedef struct {
178   UCHAR nSfb[2]; /*!< Number of SBR-bands for low and high freq-resolution */
179   UCHAR nNfb;    /*!< Actual number of noise bands to read from the bitstream*/
180   UCHAR numMaster;      /*!< Number of SBR-bands in v_k_master */
181   UCHAR lowSubband;     /*!< QMF-band where SBR frequency range starts */
182   UCHAR highSubband;    /*!< QMF-band where SBR frequency range ends */
183   UCHAR ov_highSubband; /*!< if headerchange applies this value holds the old
184                            highband value -> highband value of overlap area;
185                              required for overlap in usac when headerchange
186                            occurs between XVAR and VARX frame */
187   UCHAR limiterBandTable[MAX_NUM_LIMITERS + 1]; /*!< Limiter band table. */
188   UCHAR noLimiterBands;                         /*!< Number of limiter bands. */
189   UCHAR nInvfBands; /*!< Number of bands for inverse filtering */
190   UCHAR
191   *freqBandTable[2]; /*!< Pointers to freqBandTableLo and freqBandTableHi */
192   UCHAR freqBandTableLo[MAX_FREQ_COEFFS / 2 + 1];
193   /*!< Mapping of SBR bands to QMF bands for low frequency resolution */
194   UCHAR freqBandTableHi[MAX_FREQ_COEFFS + 1];
195   /*!< Mapping of SBR bands to QMF bands for high frequency resolution */
196   UCHAR freqBandTableNoise[MAX_NOISE_COEFFS + 1];
197   /*!< Mapping of SBR noise bands to QMF bands */
198   UCHAR v_k_master[MAX_FREQ_COEFFS + 1];
199   /*!< Master BandTable which freqBandTable is derived from */
200 } FREQ_BAND_DATA;
201 
202 typedef FREQ_BAND_DATA *HANDLE_FREQ_BAND_DATA;
203 
204 #define SBRDEC_ELD_GRID 1
205 #define SBRDEC_SYNTAX_SCAL 2
206 #define SBRDEC_SYNTAX_USAC 4
207 #define SBRDEC_SYNTAX_RSVD50 8
208 #define SBRDEC_USAC_INDEP \
209   16 /* Flag indicating that USAC global independency flag is active. */
210 #define SBRDEC_LOW_POWER \
211   32 /* Flag indicating that Low Power QMF mode shall be used. */
212 #define SBRDEC_PS_DECODED \
213   64 /* Flag indicating that PS was decoded and rendered. */
214 #define SBRDEC_QUAD_RATE                              \
215   128 /* Flag indicating that USAC SBR 4:1 is active. \
216        */
217 #define SBRDEC_USAC_HARMONICSBR \
218   256 /* Flag indicating that USAC HBE tool is active. */
219 #define SBRDEC_LD_MPS_QMF \
220   512 /* Flag indicating that the LD-MPS QMF shall be used. */
221 #define SBRDEC_USAC_ITES \
222   1024 /* Flag indicating that USAC inter TES tool is active. */
223 #define SBRDEC_SYNTAX_DRM \
224   2048 /* Flag indicating that DRM30/DRM+ reverse syntax is being used. */
225 #define SBRDEC_ELD_DOWNSCALE \
226   4096 /* Flag indicating that ELD downscaled mode decoding is used */
227 #define SBRDEC_DOWNSAMPLE \
228   8192 /* Flag indicating that the downsampling mode is used. */
229 #define SBRDEC_FLUSH 16384 /* Flag is used to flush all elements in use. */
230 #define SBRDEC_FORCE_RESET \
231   32768 /* Flag is used to force a reset of all elements in use. */
232 #define SBRDEC_SKIP_QMF_ANA                                               \
233   (1 << 21) /* Flag indicating that the input data is provided in the QMF \
234                domain. */
235 #define SBRDEC_SKIP_QMF_SYN                                                \
236   (1 << 22) /* Flag indicating that the output data is exported in the QMF \
237                domain. */
238 
239 #define SBRDEC_HDR_STAT_RESET 1
240 #define SBRDEC_HDR_STAT_UPDATE 2
241 
242 typedef struct {
243   UCHAR ampResolution; /*!< Amplitude resolution of envelope values (0: 1.5dB,
244                           1: 3dB) */
245   UCHAR
246   xover_band; /*!< Start index in #v_k_master[] used for dynamic crossover
247                  frequency */
248   UCHAR sbr_preprocessing; /*!< SBR prewhitening flag. */
249   UCHAR pvc_mode;          /*!< Predictive vector coding mode */
250 } SBR_HEADER_DATA_BS_INFO;
251 
252 typedef struct {
253   /* Changes in these variables causes a reset of the decoder */
254   UCHAR startFreq;   /*!< Index for SBR start frequency */
255   UCHAR stopFreq;    /*!< Index for SBR highest frequency */
256   UCHAR freqScale;   /*!< 0: linear scale,  1-3 logarithmic scales */
257   UCHAR alterScale;  /*!< Flag for coarser frequency resolution */
258   UCHAR noise_bands; /*!< Noise bands per octave, read from bitstream*/
259 
260   /* don't require reset */
261   UCHAR limiterBands; /*!< Index for number of limiter bands per octave */
262   UCHAR limiterGains; /*!< Index to select gain limit */
263   UCHAR interpolFreq; /*!< Select gain calculation method (1: per QMF channel,
264                          0: per SBR band) */
265   UCHAR smoothingLength; /*!< Smoothing of gains over time (0: on  1: off) */
266 
267 } SBR_HEADER_DATA_BS;
268 
269 typedef struct {
270   SBR_SYNC_STATE
271   syncState; /*!< The current initialization status of the header */
272 
273   UCHAR status; /*!< Flags field used for signaling a reset right before the
274                    processing starts and an update from config (e.g. ASC). */
275   UCHAR
276   frameErrorFlag; /*!< Frame data valid flag. CAUTION: This variable will be
277                      overwritten by the flag stored in the element
278                      structure. This is necessary because of the frame
279                      delay. There it might happen that different slots use
280                      the same header. */
281   UCHAR numberTimeSlots;       /*!< AAC: 16,15 */
282   UCHAR numberOfAnalysisBands; /*!< Number of QMF analysis bands */
283   UCHAR timeStep;              /*!< Time resolution of SBR in QMF-slots */
284   UINT
285       sbrProcSmplRate; /*!< SBR processing sampling frequency (!=
286                           OutputSamplingRate)        (always: CoreSamplingRate *
287                           UpSamplingFactor; even in single rate mode) */
288 
289   SBR_HEADER_DATA_BS bs_data;      /*!< current SBR header. */
290   SBR_HEADER_DATA_BS bs_dflt;      /*!< Default sbr header. */
291   SBR_HEADER_DATA_BS_INFO bs_info; /*!< SBR info. */
292 
293   FREQ_BAND_DATA freqBandData; /*!< Pointer to struct #FREQ_BAND_DATA */
294   UCHAR pvcIDprev;
295 } SBR_HEADER_DATA;
296 
297 typedef SBR_HEADER_DATA *HANDLE_SBR_HEADER_DATA;
298 
299 typedef struct {
300   UCHAR frameClass;                 /*!< Select grid type */
301   UCHAR nEnvelopes;                 /*!< Number of envelopes */
302   UCHAR borders[MAX_ENVELOPES + 1]; /*!< Envelope borders (in SBR-timeslots,
303                                        e.g. mp3PRO: 0..11) */
304   UCHAR freqRes[MAX_ENVELOPES];     /*!< Frequency resolution for each envelope
305                                        (0=low, 1=high) */
306   SCHAR tranEnv;                    /*!< Transient envelope, -1 if none */
307   UCHAR nNoiseEnvelopes;            /*!< Number of noise envelopes */
308   UCHAR
309   bordersNoise[MAX_NOISE_ENVELOPES + 1]; /*!< borders of noise envelopes */
310   UCHAR pvcBorders[MAX_PVC_ENVELOPES + 1];
311   UCHAR noisePosition;
312   UCHAR varLength;
313 } FRAME_INFO;
314 
315 typedef struct {
316   FIXP_SGL sfb_nrg_prev[MAX_FREQ_COEFFS]; /*!< Previous envelope (required for
317                                              differential-coded values) */
318   FIXP_SGL
319   prevNoiseLevel[MAX_NOISE_COEFFS]; /*!< Previous noise envelope (required
320                                        for differential-coded values) */
321   COUPLING_MODE coupling;           /*!< Stereo-mode of previous frame */
322   INVF_MODE sbr_invf_mode[MAX_INVF_BANDS]; /*!< Previous strength of filtering
323                                               in transposer */
324   UCHAR ampRes;         /*!< Previous amplitude resolution (0: 1.5dB, 1: 3dB) */
325   UCHAR stopPos;        /*!< Position in time where last envelope ended */
326   UCHAR frameErrorFlag; /*!< Previous frame status */
327   UCHAR prevSbrPitchInBins; /*!< Previous frame pitchInBins */
328   FRAME_INFO prevFrameInfo;
329 } SBR_PREV_FRAME_DATA;
330 
331 typedef SBR_PREV_FRAME_DATA *HANDLE_SBR_PREV_FRAME_DATA;
332 
333 typedef struct {
334   int nScaleFactors; /*!< total number of scalefactors in frame */
335 
336   FRAME_INFO frameInfo;            /*!< time grid for current frame */
337   UCHAR domain_vec[MAX_ENVELOPES]; /*!< Bitfield containing direction of
338                                       delta-coding for each envelope
339                                       (0:frequency, 1:time) */
340   UCHAR domain_vec_noise
341       [MAX_NOISE_ENVELOPES]; /*!< Same as above, but for noise envelopes */
342 
343   INVF_MODE
344   sbr_invf_mode[MAX_INVF_BANDS]; /*!< Strength of filtering in transposer */
345   COUPLING_MODE coupling;        /*!< Stereo-mode */
346   int ampResolutionCurrentFrame; /*!< Amplitude resolution of envelope values
347                                     (0: 1.5dB, 1: 3dB) */
348 
349   ULONG addHarmonics[ADD_HARMONICS_FLAGS_SIZE]; /*!< Flags for synthetic sine
350                                                    addition (aligned to MSB) */
351 
352   FIXP_SGL iEnvelope[MAX_NUM_ENVELOPE_VALUES];       /*!< Envelope data */
353   FIXP_SGL sbrNoiseFloorLevel[MAX_NUM_NOISE_VALUES]; /*!< Noise envelope data */
354   UCHAR iTESactive; /*!< One flag for each envelope to enable USAC inter-TES */
355   UCHAR
356   interTempShapeMode[MAX_ENVELOPES]; /*!< USAC inter-TES:
357                                         bs_inter_temp_shape_mode[ch][env]
358                                         value */
359   UCHAR pvcID[PVC_NTIMESLOT];        /*!< One PVC ID value for each time slot */
360   UCHAR ns;
361   UCHAR sinusoidal_position;
362 
363   UCHAR sbrPatchingMode;
364   UCHAR sbrOversamplingFlag;
365   UCHAR sbrPitchInBins;
366 } SBR_FRAME_DATA;
367 
368 typedef SBR_FRAME_DATA *HANDLE_SBR_FRAME_DATA;
369 
370 /*!
371 \brief   Maps sampling frequencies to frequencies for which setup tables are
372 available
373 
374 Maps arbitary sampling frequency to nearest neighbors for which setup tables
375 are available (e.g. 25600 -> 24000).
376 Used for startFreq calculation.
377 The mapping is defined in 14496-3 (4.6.18.2.6), fs(SBR), and table 4.82
378 
379 \return  mapped sampling frequency
380 */
381 UINT sbrdec_mapToStdSampleRate(UINT fs,
382                                UINT isUsac); /*!< Output sampling frequency */
383 
384 void initSbrPrevFrameData(HANDLE_SBR_PREV_FRAME_DATA h_prev_data,
385                           int timeSlots);
386 
387 int sbrGetChannelElement(HANDLE_SBR_HEADER_DATA hHeaderData,
388                          HANDLE_SBR_FRAME_DATA hFrameDataLeft,
389                          HANDLE_SBR_FRAME_DATA hFrameDataRight,
390                          HANDLE_SBR_PREV_FRAME_DATA hFrameDataLeftPrev,
391                          UCHAR pvc_mode_last, HANDLE_FDK_BITSTREAM hBitBuf,
392                          HANDLE_PS_DEC hParametricStereoDec, const UINT flags,
393                          const int overlap);
394 
395 SBR_HEADER_STATUS
396 sbrGetHeaderData(HANDLE_SBR_HEADER_DATA headerData,
397                  HANDLE_FDK_BITSTREAM hBitBuf, const UINT flags,
398                  const int fIsSbrData, const UCHAR configMode);
399 
400 /*!
401   \brief     Initialize SBR header data
402 
403   Copy default values to the header data struct and patch some entries
404   depending on the core codec.
405 */
406 SBR_ERROR
407 initHeaderData(HANDLE_SBR_HEADER_DATA hHeaderData, const int sampleRateIn,
408                const int sampleRateOut, const INT downscaleFactor,
409                const int samplesPerFrame, const UINT flags,
410                const int setDefaultHdr);
411 #endif
412 
413 /* Convert headroom bits to exponent */
414 #define SCALE2EXP(s) (15 - (s))
415 #define EXP2SCALE(e) (15 - (e))
416