Add documentation about missing E-AC-3 features.
[ffmpeg.git] / libavcodec / eac3dec.c
1 /*
2  * E-AC-3 decoder
3  * Copyright (c) 2007 Bartlomiej Wolowiec <bartek.wolowiec@gmail.com>
4  * Copyright (c) 2008 Justin Ruggles
5  *
6  * This file is part of FFmpeg.
7  *
8  * FFmpeg is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Lesser General Public
10  * License as published by the Free Software Foundation; either
11  * version 2.1 of the License, or (at your option) any later version.
12  *
13  * FFmpeg is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16  * Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public
19  * License along with FFmpeg; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
21  */
22
23 /*
24  * There are several features of E-AC-3 that this decoder does not yet support.
25  *
26  * Spectral Extension
27  *     There is a patch to get this working for the two samples we have that
28  *     use it, but it needs some minor changes in order to be accepted.
29  *
30  * Enhanced Coupling
31  *     No known samples exist.  If any ever surface, this feature should not be
32  *     too difficult to implement.
33  *
34  * Reduced Sample Rates
35  *     No known samples exist.  The spec also does not give clear information
36  *     on how this is to be implemented.
37  *
38  * Dependent Streams
39  *     Only the independent stream is currently decoded. Any dependent
40  *     streams are skipped.  We have only come across two examples of this, and
41  *     they are both just test streams, one for HD-DVD and the other for
42  *     Blu-ray.
43  *
44  * Transient Pre-noise Processing
45  *     This is side information which a decoder should use to reduce artifacts
46  *     caused by transients.  There are samples which are known to have this
47  *     information, but this decoder currently ignores it.
48  */
49
50
51 #include "avcodec.h"
52 #include "internal.h"
53 #include "aac_ac3_parser.h"
54 #include "ac3.h"
55 #include "ac3_parser.h"
56 #include "ac3dec.h"
57 #include "ac3dec_data.h"
58
59 /** gain adaptive quantization mode */
60 typedef enum {
61     EAC3_GAQ_NO =0,
62     EAC3_GAQ_12,
63     EAC3_GAQ_14,
64     EAC3_GAQ_124
65 } EAC3GaqMode;
66
67 #define EAC3_SR_CODE_REDUCED  3
68
69 /** lrint(M_SQRT2*cos(2*M_PI/12)*(1<<23)) */
70 #define COEFF_0 10273905LL
71
72 /** lrint(M_SQRT2*cos(0*M_PI/12)*(1<<23)) = lrint(M_SQRT2*(1<<23)) */
73 #define COEFF_1 11863283LL
74
75 /** lrint(M_SQRT2*cos(5*M_PI/12)*(1<<23)) */
76 #define COEFF_2  3070444LL
77
78 /**
79  * Calculate 6-point IDCT of the pre-mantissas.
80  * All calculations are 24-bit fixed-point.
81  */
82 static void idct6(int pre_mant[6])
83 {
84     int tmp;
85     int even0, even1, even2, odd0, odd1, odd2;
86
87     odd1 = pre_mant[1] - pre_mant[3] - pre_mant[5];
88
89     even2 = ( pre_mant[2]                * COEFF_0) >> 23;
90     tmp   = ( pre_mant[4]                * COEFF_1) >> 23;
91     odd0  = ((pre_mant[1] + pre_mant[5]) * COEFF_2) >> 23;
92
93     even0 = pre_mant[0] + (tmp >> 1);
94     even1 = pre_mant[0] - tmp;
95
96     tmp = even0;
97     even0 = tmp + even2;
98     even2 = tmp - even2;
99
100     tmp = odd0;
101     odd0 = tmp + pre_mant[1] + pre_mant[3];
102     odd2 = tmp + pre_mant[5] - pre_mant[3];
103
104     pre_mant[0] = even0 + odd0;
105     pre_mant[1] = even1 + odd1;
106     pre_mant[2] = even2 + odd2;
107     pre_mant[3] = even2 - odd2;
108     pre_mant[4] = even1 - odd1;
109     pre_mant[5] = even0 - odd0;
110 }
111
112 void ff_eac3_decode_transform_coeffs_aht_ch(AC3DecodeContext *s, int ch)
113 {
114     int bin, blk, gs;
115     int end_bap, gaq_mode;
116     GetBitContext *gbc = &s->gbc;
117     int gaq_gain[AC3_MAX_COEFS];
118
119     gaq_mode = get_bits(gbc, 2);
120     end_bap = (gaq_mode < 2) ? 12 : 17;
121
122     /* if GAQ gain is used, decode gain codes for bins with hebap between
123        8 and end_bap */
124     gs = 0;
125     if (gaq_mode == EAC3_GAQ_12 || gaq_mode == EAC3_GAQ_14) {
126         /* read 1-bit GAQ gain codes */
127         for (bin = s->start_freq[ch]; bin < s->end_freq[ch]; bin++) {
128             if (s->bap[ch][bin] > 7 && s->bap[ch][bin] < end_bap)
129                 gaq_gain[gs++] = get_bits1(gbc) << (gaq_mode-1);
130         }
131     } else if (gaq_mode == EAC3_GAQ_124) {
132         /* read 1.67-bit GAQ gain codes (3 codes in 5 bits) */
133         int gc = 2;
134         for (bin = s->start_freq[ch]; bin < s->end_freq[ch]; bin++) {
135             if (s->bap[ch][bin] > 7 && s->bap[ch][bin] < 17) {
136                 if (gc++ == 2) {
137                     int group_code = get_bits(gbc, 5);
138                     if (group_code > 26) {
139                         av_log(s->avctx, AV_LOG_WARNING, "GAQ gain group code out-of-range\n");
140                         group_code = 26;
141                     }
142                     gaq_gain[gs++] = ff_ac3_ungroup_3_in_5_bits_tab[group_code][0];
143                     gaq_gain[gs++] = ff_ac3_ungroup_3_in_5_bits_tab[group_code][1];
144                     gaq_gain[gs++] = ff_ac3_ungroup_3_in_5_bits_tab[group_code][2];
145                     gc = 0;
146                 }
147             }
148         }
149     }
150
151     gs=0;
152     for (bin = s->start_freq[ch]; bin < s->end_freq[ch]; bin++) {
153         int hebap = s->bap[ch][bin];
154         int bits = ff_eac3_bits_vs_hebap[hebap];
155         if (!hebap) {
156             /* zero-mantissa dithering */
157             for (blk = 0; blk < 6; blk++) {
158                 s->pre_mantissa[ch][bin][blk] = (av_lfg_get(&s->dith_state) & 0x7FFFFF) - 0x400000;
159             }
160         } else if (hebap < 8) {
161             /* Vector Quantization */
162             int v = get_bits(gbc, bits);
163             for (blk = 0; blk < 6; blk++) {
164                 s->pre_mantissa[ch][bin][blk] = ff_eac3_mantissa_vq[hebap][v][blk] << 8;
165             }
166         } else {
167             /* Gain Adaptive Quantization */
168             int gbits, log_gain;
169             if (gaq_mode != EAC3_GAQ_NO && hebap < end_bap) {
170                 log_gain = gaq_gain[gs++];
171             } else {
172                 log_gain = 0;
173             }
174             gbits = bits - log_gain;
175
176             for (blk = 0; blk < 6; blk++) {
177                 int mant = get_sbits(gbc, gbits);
178                 if (mant == -(1 << (gbits-1))) {
179                     /* large mantissa */
180                     int b;
181                     mant = get_sbits(gbc, bits-2+log_gain) << (26-log_gain-bits);
182                     /* remap mantissa value to correct for asymmetric quantization */
183                     if (mant >= 0)
184                         b = 32768 >> (log_gain+8);
185                     else
186                         b = ff_eac3_gaq_remap_2_4_b[hebap-8][log_gain-1];
187                     mant += (ff_eac3_gaq_remap_2_4_a[hebap-8][log_gain-1] * (mant>>8) + b) >> 7;
188                 } else {
189                     /* small mantissa, no GAQ, or Gk=1 */
190                     mant <<= 24 - bits;
191                     if (!log_gain) {
192                         /* remap mantissa value for no GAQ or Gk=1 */
193                         mant += (ff_eac3_gaq_remap_1[hebap-8] * (mant>>8)) >> 7;
194                     }
195                 }
196                 s->pre_mantissa[ch][bin][blk] = mant;
197             }
198         }
199         idct6(s->pre_mantissa[ch][bin]);
200     }
201 }
202
203 int ff_eac3_parse_header(AC3DecodeContext *s)
204 {
205     int i, blk, ch;
206     int ac3_exponent_strategy, parse_aht_info, parse_spx_atten_data;
207     int parse_transient_proc_info;
208     int num_cpl_blocks;
209     GetBitContext *gbc = &s->gbc;
210
211     /* An E-AC-3 stream can have multiple independent streams which the
212        application can select from. each independent stream can also contain
213        dependent streams which are used to add or replace channels. */
214     if (s->frame_type == EAC3_FRAME_TYPE_DEPENDENT) {
215         ff_log_missing_feature(s->avctx, "Dependent substream decoding", 1);
216         return AAC_AC3_PARSE_ERROR_FRAME_TYPE;
217     } else if (s->frame_type == EAC3_FRAME_TYPE_RESERVED) {
218         av_log(s->avctx, AV_LOG_ERROR, "Reserved frame type\n");
219         return AAC_AC3_PARSE_ERROR_FRAME_TYPE;
220     }
221
222     /* The substream id indicates which substream this frame belongs to. each
223        independent stream has its own substream id, and the dependent streams
224        associated to an independent stream have matching substream id's. */
225     if (s->substreamid) {
226         /* only decode substream with id=0. skip any additional substreams. */
227         ff_log_missing_feature(s->avctx, "Additional substreams", 1);
228         return AAC_AC3_PARSE_ERROR_FRAME_TYPE;
229     }
230
231     if (s->bit_alloc_params.sr_code == EAC3_SR_CODE_REDUCED) {
232         /* The E-AC-3 specification does not tell how to handle reduced sample
233            rates in bit allocation.  The best assumption would be that it is
234            handled like AC-3 DolbyNet, but we cannot be sure until we have a
235            sample which utilizes this feature. */
236         ff_log_missing_feature(s->avctx, "Reduced sampling rates", 1);
237         return -1;
238     }
239     skip_bits(gbc, 5); // skip bitstream id
240
241     /* volume control params */
242     for (i = 0; i < (s->channel_mode ? 1 : 2); i++) {
243         skip_bits(gbc, 5); // skip dialog normalization
244         if (get_bits1(gbc)) {
245             skip_bits(gbc, 8); // skip compression gain word
246         }
247     }
248
249     /* dependent stream channel map */
250     if (s->frame_type == EAC3_FRAME_TYPE_DEPENDENT) {
251         if (get_bits1(gbc)) {
252             skip_bits(gbc, 16); // skip custom channel map
253         }
254     }
255
256     /* mixing metadata */
257     if (get_bits1(gbc)) {
258         /* center and surround mix levels */
259         if (s->channel_mode > AC3_CHMODE_STEREO) {
260             skip_bits(gbc, 2);  // skip preferred stereo downmix mode
261             if (s->channel_mode & 1) {
262                 /* if three front channels exist */
263                 skip_bits(gbc, 3); //skip Lt/Rt center mix level
264                 s->center_mix_level = get_bits(gbc, 3);
265             }
266             if (s->channel_mode & 4) {
267                 /* if a surround channel exists */
268                 skip_bits(gbc, 3); //skip Lt/Rt surround mix level
269                 s->surround_mix_level = get_bits(gbc, 3);
270             }
271         }
272
273         /* lfe mix level */
274         if (s->lfe_on && get_bits1(gbc)) {
275             // TODO: use LFE mix level
276             skip_bits(gbc, 5); // skip LFE mix level code
277         }
278
279         /* info for mixing with other streams and substreams */
280         if (s->frame_type == EAC3_FRAME_TYPE_INDEPENDENT) {
281             for (i = 0; i < (s->channel_mode ? 1 : 2); i++) {
282                 // TODO: apply program scale factor
283                 if (get_bits1(gbc)) {
284                     skip_bits(gbc, 6);  // skip program scale factor
285                 }
286             }
287             if (get_bits1(gbc)) {
288                 skip_bits(gbc, 6);  // skip external program scale factor
289             }
290             /* skip mixing parameter data */
291             switch(get_bits(gbc, 2)) {
292                 case 1: skip_bits(gbc, 5);  break;
293                 case 2: skip_bits(gbc, 12); break;
294                 case 3: {
295                     int mix_data_size = (get_bits(gbc, 5) + 2) << 3;
296                     skip_bits_long(gbc, mix_data_size);
297                     break;
298                 }
299             }
300             /* skip pan information for mono or dual mono source */
301             if (s->channel_mode < AC3_CHMODE_STEREO) {
302                 for (i = 0; i < (s->channel_mode ? 1 : 2); i++) {
303                     if (get_bits1(gbc)) {
304                         /* note: this is not in the ATSC A/52B specification
305                            reference: ETSI TS 102 366 V1.1.1
306                                       section: E.1.3.1.25 */
307                         skip_bits(gbc, 8);  // skip pan mean direction index
308                         skip_bits(gbc, 6);  // skip reserved paninfo bits
309                     }
310                 }
311             }
312             /* skip mixing configuration information */
313             if (get_bits1(gbc)) {
314                 for (blk = 0; blk < s->num_blocks; blk++) {
315                     if (s->num_blocks == 1 || get_bits1(gbc)) {
316                         skip_bits(gbc, 5);
317                     }
318                 }
319             }
320         }
321     }
322
323     /* informational metadata */
324     if (get_bits1(gbc)) {
325         skip_bits(gbc, 3); // skip bit stream mode
326         skip_bits(gbc, 2); // skip copyright bit and original bitstream bit
327         if (s->channel_mode == AC3_CHMODE_STEREO) {
328             skip_bits(gbc, 4); // skip Dolby surround and headphone mode
329         }
330         if (s->channel_mode >= AC3_CHMODE_2F2R) {
331             skip_bits(gbc, 2); // skip Dolby surround EX mode
332         }
333         for (i = 0; i < (s->channel_mode ? 1 : 2); i++) {
334             if (get_bits1(gbc)) {
335                 skip_bits(gbc, 8); // skip mix level, room type, and A/D converter type
336             }
337         }
338         if (s->bit_alloc_params.sr_code != EAC3_SR_CODE_REDUCED) {
339             skip_bits1(gbc); // skip source sample rate code
340         }
341     }
342
343     /* converter synchronization flag
344        If frames are less than six blocks, this bit should be turned on
345        once every 6 blocks to indicate the start of a frame set.
346        reference: RFC 4598, Section 2.1.3  Frame Sets */
347     if (s->frame_type == EAC3_FRAME_TYPE_INDEPENDENT && s->num_blocks != 6) {
348         skip_bits1(gbc); // skip converter synchronization flag
349     }
350
351     /* original frame size code if this stream was converted from AC-3 */
352     if (s->frame_type == EAC3_FRAME_TYPE_AC3_CONVERT &&
353             (s->num_blocks == 6 || get_bits1(gbc))) {
354         skip_bits(gbc, 6); // skip frame size code
355     }
356
357     /* additional bitstream info */
358     if (get_bits1(gbc)) {
359         int addbsil = get_bits(gbc, 6);
360         for (i = 0; i < addbsil + 1; i++) {
361             skip_bits(gbc, 8); // skip additional bit stream info
362         }
363     }
364
365     /* audio frame syntax flags, strategy data, and per-frame data */
366
367     if (s->num_blocks == 6) {
368         ac3_exponent_strategy = get_bits1(gbc);
369         parse_aht_info        = get_bits1(gbc);
370     } else {
371         /* less than 6 blocks, so use AC-3-style exponent strategy syntax, and
372            do not use AHT */
373         ac3_exponent_strategy = 1;
374         parse_aht_info = 0;
375     }
376
377     s->snr_offset_strategy    = get_bits(gbc, 2);
378     parse_transient_proc_info = get_bits1(gbc);
379
380     s->block_switch_syntax = get_bits1(gbc);
381     if (!s->block_switch_syntax)
382         memset(s->block_switch, 0, sizeof(s->block_switch));
383
384     s->dither_flag_syntax = get_bits1(gbc);
385     if (!s->dither_flag_syntax) {
386         for (ch = 1; ch <= s->fbw_channels; ch++)
387             s->dither_flag[ch] = 1;
388     }
389     s->dither_flag[CPL_CH] = s->dither_flag[s->lfe_ch] = 0;
390
391     s->bit_allocation_syntax = get_bits1(gbc);
392     if (!s->bit_allocation_syntax) {
393         /* set default bit allocation parameters */
394         s->bit_alloc_params.slow_decay = ff_ac3_slow_decay_tab[2];
395         s->bit_alloc_params.fast_decay = ff_ac3_fast_decay_tab[1];
396         s->bit_alloc_params.slow_gain  = ff_ac3_slow_gain_tab [1];
397         s->bit_alloc_params.db_per_bit = ff_ac3_db_per_bit_tab[2];
398         s->bit_alloc_params.floor      = ff_ac3_floor_tab     [7];
399     }
400
401     s->fast_gain_syntax  = get_bits1(gbc);
402     s->dba_syntax        = get_bits1(gbc);
403     s->skip_syntax       = get_bits1(gbc);
404     parse_spx_atten_data = get_bits1(gbc);
405
406     /* coupling strategy occurance and coupling use per block */
407     num_cpl_blocks = 0;
408     if (s->channel_mode > 1) {
409         for (blk = 0; blk < s->num_blocks; blk++) {
410             s->cpl_strategy_exists[blk] = (!blk || get_bits1(gbc));
411             if (s->cpl_strategy_exists[blk]) {
412                 s->cpl_in_use[blk] = get_bits1(gbc);
413             } else {
414                 s->cpl_in_use[blk] = s->cpl_in_use[blk-1];
415             }
416             num_cpl_blocks += s->cpl_in_use[blk];
417         }
418     } else {
419         memset(s->cpl_in_use, 0, sizeof(s->cpl_in_use));
420     }
421
422     /* exponent strategy data */
423     if (ac3_exponent_strategy) {
424         /* AC-3-style exponent strategy syntax */
425         for (blk = 0; blk < s->num_blocks; blk++) {
426             for (ch = !s->cpl_in_use[blk]; ch <= s->fbw_channels; ch++) {
427                 s->exp_strategy[blk][ch] = get_bits(gbc, 2);
428             }
429         }
430     } else {
431         /* LUT-based exponent strategy syntax */
432         for (ch = !((s->channel_mode > 1) && num_cpl_blocks); ch <= s->fbw_channels; ch++) {
433             int frmchexpstr = get_bits(gbc, 5);
434             for (blk = 0; blk < 6; blk++) {
435                 s->exp_strategy[blk][ch] = ff_eac3_frm_expstr[frmchexpstr][blk];
436             }
437         }
438     }
439     /* LFE exponent strategy */
440     if (s->lfe_on) {
441         for (blk = 0; blk < s->num_blocks; blk++) {
442             s->exp_strategy[blk][s->lfe_ch] = get_bits1(gbc);
443         }
444     }
445     /* original exponent strategies if this stream was converted from AC-3 */
446     if (s->frame_type == EAC3_FRAME_TYPE_INDEPENDENT &&
447             (s->num_blocks == 6 || get_bits1(gbc))) {
448         skip_bits(gbc, 5 * s->fbw_channels); // skip converter channel exponent strategy
449     }
450
451     /* determine which channels use AHT */
452     if (parse_aht_info) {
453         /* For AHT to be used, all non-zero blocks must reuse exponents from
454            the first block.  Furthermore, for AHT to be used in the coupling
455            channel, all blocks must use coupling and use the same coupling
456            strategy. */
457         s->channel_uses_aht[CPL_CH]=0;
458         for (ch = (num_cpl_blocks != 6); ch <= s->channels; ch++) {
459             int use_aht = 1;
460             for (blk = 1; blk < 6; blk++) {
461                 if ((s->exp_strategy[blk][ch] != EXP_REUSE) ||
462                         (!ch && s->cpl_strategy_exists[blk])) {
463                     use_aht = 0;
464                     break;
465                 }
466             }
467             s->channel_uses_aht[ch] = use_aht && get_bits1(gbc);
468         }
469     } else {
470         memset(s->channel_uses_aht, 0, sizeof(s->channel_uses_aht));
471     }
472
473     /* per-frame SNR offset */
474     if (!s->snr_offset_strategy) {
475         int csnroffst = (get_bits(gbc, 6) - 15) << 4;
476         int snroffst = (csnroffst + get_bits(gbc, 4)) << 2;
477         for (ch = 0; ch <= s->channels; ch++)
478             s->snr_offset[ch] = snroffst;
479     }
480
481     /* transient pre-noise processing data */
482     if (parse_transient_proc_info) {
483         for (ch = 1; ch <= s->fbw_channels; ch++) {
484             if (get_bits1(gbc)) { // channel in transient processing
485                 skip_bits(gbc, 10); // skip transient processing location
486                 skip_bits(gbc, 8);  // skip transient processing length
487             }
488         }
489     }
490
491     /* spectral extension attenuation data */
492     if (parse_spx_atten_data) {
493         ff_log_missing_feature(s->avctx, "Spectral extension attenuation", 1);
494         for (ch = 1; ch <= s->fbw_channels; ch++) {
495             if (get_bits1(gbc)) { // channel has spx attenuation
496                 skip_bits(gbc, 5); // skip spx attenuation code
497             }
498         }
499     }
500
501     /* block start information */
502     if (s->num_blocks > 1 && get_bits1(gbc)) {
503         /* reference: Section E2.3.2.27
504            nblkstrtbits = (numblks - 1) * (4 + ceiling(log2(words_per_frame)))
505            The spec does not say what this data is or what it's used for.
506            It is likely the offset of each block within the frame. */
507         int block_start_bits = (s->num_blocks-1) * (4 + av_log2(s->frame_size-2));
508         skip_bits_long(gbc, block_start_bits);
509         ff_log_missing_feature(s->avctx, "Block start info", 1);
510     }
511
512     /* syntax state initialization */
513     for (ch = 1; ch <= s->fbw_channels; ch++) {
514         s->first_cpl_coords[ch] = 1;
515     }
516     s->first_cpl_leak = 1;
517
518     return 0;
519 }