Skip to main content

threers_codec/aac/
encoder.rs

1//! AAC-LC encoding: planar `f32` PCM to raw access units, ADTS, or the
2//! `AudioSpecificConfig` an MP4 needs. Mono or stereo, any of the standard
3//! sample rates, at a target bitrate.
4//!
5//! What it does, per 1024-sample frame and channel:
6//!
7//! 1. A sine-windowed MDCT over 2048 samples (the previous frame and this
8//!    one), computed through a DCT-IV on a half-size complex FFT.
9//! 2. A low-pass at a cutoff that follows the bitrate, so no bits go to
10//!    frequencies the rate cannot afford.
11//! 3. For stereo, a per-band choice of left/right or mid/side, by which one
12//!    needs fewer bits at the same noise.
13//! 4. Power-law quantization (`|x|^(3/4)`, rounding offset 0.4054) with one
14//!    step for the frame, found by bisection so the frame fits its share of
15//!    the bit budget. A reservoir lets quiet frames lend bits to loud ones.
16//! 5. Huffman coding with the best of the eleven spectral codebooks per band,
17//!    grouped into sections.
18//!
19//! What it leaves out: window switching (transients can pre-echo), TNS,
20//! perceptual noise substitution, intensity stereo, prediction and a
21//! psychoacoustic model. The quantization noise is the same everywhere in a
22//! frame (apart from mid/side), which minimises the error for the bits spent
23//! but does not hide it. Output decodes with any AAC-LC decoder.
24//!
25//! ```
26//! use threers_codec::aac::encoder::{encode_adts, EncoderConfig};
27//! let tone: Vec<f32> = (0..44_100).map(|i| (i as f32 * 0.05).sin() * 0.5).collect();
28//! let adts = encode_adts(&[tone], &EncoderConfig::new(44_100, 1, 64_000)).unwrap();
29//! assert_eq!(&adts[..2], &[0xFF, 0xF1]);
30//! ```
31
32use super::tables::{BITS, CODES, NUM_SWB_1024, SF_BITS, SF_CODE, SWB_OFFSET_1024};
33use crate::bitstream::BitWriter;
34
35/// Samples per frame and channel.
36pub const FRAME: usize = 1024;
37
38/// Samples of delay the encoder adds: the first frame's overlap. A decoder's
39/// output starts with this much that is not in the input (MP4 files say so
40/// with an edit list).
41pub const DELAY: usize = FRAME;
42
43/// The sample rates AAC has an index for.
44pub const SAMPLE_RATES: [u32; 13] = [
45    96_000, 88_200, 64_000, 48_000, 44_100, 32_000, 24_000, 22_050, 16_000, 12_000, 11_025, 8_000,
46    7_350,
47];
48
49/// What to encode.
50#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51pub struct EncoderConfig {
52    pub sample_rate: u32,
53    /// 1 or 2.
54    pub channels: usize,
55    /// Target, in bits per second, for all channels together.
56    pub bitrate: u32,
57}
58
59impl EncoderConfig {
60    pub fn new(sample_rate: u32, channels: usize, bitrate: u32) -> Self {
61        Self {
62            sample_rate,
63            channels,
64            bitrate,
65        }
66    }
67}
68
69/// Why encoding was refused.
70#[derive(Clone, Debug, PartialEq, Eq)]
71pub enum EncodeError {
72    /// AAC has no code for this sample rate.
73    SampleRate(u32),
74    /// Only mono and stereo are supported.
75    Channels(usize),
76    /// The bitrate is under 8 kbit/s per channel or over 320 kbit/s.
77    Bitrate(u32),
78    /// The channels differ in length, or there are none.
79    Input(String),
80}
81
82impl std::fmt::Display for EncodeError {
83    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
84        match self {
85            Self::SampleRate(r) => write!(f, "AAC has no sample-rate code for {r} Hz"),
86            Self::Channels(c) => write!(f, "{c} channels: only mono and stereo are supported"),
87            Self::Bitrate(b) => {
88                write!(f, "{b} bit/s is outside 8 kbit/s per channel to 320 kbit/s")
89            }
90            Self::Input(why) => write!(f, "bad input: {why}"),
91        }
92    }
93}
94
95impl std::error::Error for EncodeError {}
96
97// ------------------------------------------------------------------ MDCT
98
99/// A power-of-two complex FFT, forward.
100struct Fft {
101    n: usize,
102    twiddle: Vec<(f64, f64)>,
103    reversed: Vec<usize>,
104}
105
106impl Fft {
107    fn new(n: usize) -> Self {
108        let bits = n.trailing_zeros();
109        Self {
110            n,
111            twiddle: (0..n / 2)
112                .map(|k| {
113                    let a = -2.0 * std::f64::consts::PI * k as f64 / n as f64;
114                    (a.cos(), a.sin())
115                })
116                .collect(),
117            reversed: (0..n)
118                .map(|i| {
119                    if bits == 0 {
120                        0
121                    } else {
122                        i.reverse_bits() >> (usize::BITS - bits)
123                    }
124                })
125                .collect(),
126        }
127    }
128
129    fn run(&self, re: &mut [f64], im: &mut [f64]) {
130        let n = self.n;
131        for i in 0..n {
132            let j = self.reversed[i];
133            if j > i {
134                re.swap(i, j);
135                im.swap(i, j);
136            }
137        }
138        let mut len = 2;
139        while len <= n {
140            let (half, step) = (len / 2, n / len);
141            for start in (0..n).step_by(len) {
142                for k in 0..half {
143                    let (wr, wi) = self.twiddle[k * step];
144                    let (a, b) = (start + k, start + k + half);
145                    let (tr, ti) = (re[b] * wr - im[b] * wi, re[b] * wi + im[b] * wr);
146                    re[b] = re[a] - tr;
147                    im[b] = im[a] - ti;
148                    re[a] += tr;
149                    im[a] += ti;
150                }
151            }
152            len *= 2;
153        }
154    }
155}
156
157/// The MDCT of `2m` samples to `m` coefficients, through a DCT-IV of the
158/// folded block and an `m/2`-point FFT.
159///
160/// `X[k] = sum x[n] cos(pi/m (n + 1/2 + m/2)(k + 1/2))`, the transform AAC
161/// defines (up to the factor 2 the encoder applies).
162pub struct Mdct {
163    m: usize,
164    fft: Fft,
165    /// `exp(-i pi n / m)` for the pre-twiddle and `exp(-i pi (k + 1/4) / m)` after.
166    pre: Vec<(f64, f64)>,
167    post: Vec<(f64, f64)>,
168}
169
170impl Mdct {
171    pub fn new(m: usize) -> Self {
172        assert!(m.is_power_of_two() && m >= 4);
173        let angle = |x: f64| -std::f64::consts::PI * x / m as f64;
174        Self {
175            m,
176            fft: Fft::new(m / 2),
177            pre: (0..m / 2)
178                .map(|n| (angle(n as f64).cos(), angle(n as f64).sin()))
179                .collect(),
180            post: (0..m / 2)
181                .map(|k| (angle(k as f64 + 0.25).cos(), angle(k as f64 + 0.25).sin()))
182                .collect(),
183        }
184    }
185
186    /// DCT-IV: `X[k] = sum u[n] cos(pi/m (n + 1/2)(k + 1/2))`.
187    pub fn dct4(&self, u: &[f64], out: &mut [f64]) {
188        let (m, h) = (self.m, self.m / 2);
189        let (mut re, mut im) = (vec![0.0; h], vec![0.0; h]);
190        for n in 0..h {
191            let (a, b) = (u[2 * n], u[m - 1 - 2 * n]);
192            let (c, s) = self.pre[n];
193            re[n] = a * c - b * s;
194            im[n] = a * s + b * c;
195        }
196        self.fft.run(&mut re, &mut im);
197        for k in 0..h {
198            let (c, s) = self.post[k];
199            let (yr, yi) = (re[k] * c - im[k] * s, re[k] * s + im[k] * c);
200            out[2 * k] = yr;
201            out[m - 1 - 2 * k] = -yi;
202        }
203    }
204
205    /// `x` has `2m` samples (already windowed); `out` gets `m` coefficients.
206    pub fn forward(&self, x: &[f64], out: &mut [f64]) {
207        let (m, h) = (self.m, self.m / 2);
208        let mut u = vec![0.0; m];
209        for n in 0..h {
210            u[n] = -x[3 * h - 1 - n] - x[3 * h + n];
211            u[h + n] = x[n] - x[m - 1 - n];
212        }
213        self.dct4(&u, out);
214    }
215}
216
217// ----------------------------------------------------------- bit counting
218
219/// Collects the bits of a unit while counting them.
220struct Sink {
221    writer: Option<BitWriter>,
222    bits: usize,
223}
224
225impl Sink {
226    fn writing() -> Self {
227        Self {
228            writer: Some(BitWriter::new()),
229            bits: 0,
230        }
231    }
232
233    fn put(&mut self, value: u32, n: u32) {
234        self.bits += n as usize;
235        if let Some(w) = &mut self.writer
236            && n > 0
237        {
238            w.write_bits(value, n);
239        }
240    }
241}
242
243// ------------------------------------------------------------ codebooks
244
245/// Largest magnitude each spectral codebook (1 to 11) can carry; 11 escapes.
246const CB_MAX: [i32; 11] = [1, 1, 2, 2, 4, 4, 7, 7, 12, 12, 8191];
247/// Values per codeword.
248const CB_DIM: [usize; 11] = [4, 4, 4, 4, 2, 2, 2, 2, 2, 2, 2];
249/// Signed codebooks carry the sign in the codeword; the others after it.
250const CB_SIGNED: [bool; 11] = [
251    true, true, false, false, true, true, false, false, false, false, false,
252];
253
254/// The codeword index of a tuple in codebook `cb` (1-based).
255fn tuple_index(cb: usize, v: &[i32]) -> usize {
256    match cb {
257        1 | 2 => v.iter().fold(0, |a, &x| a * 3 + (x + 1) as usize),
258        3 | 4 => v.iter().fold(0, |a, &x| a * 3 + x.unsigned_abs() as usize),
259        5 | 6 => v.iter().fold(0, |a, &x| a * 9 + (x + 4) as usize),
260        7 | 8 => v.iter().fold(0, |a, &x| a * 8 + x.unsigned_abs() as usize),
261        9 | 10 => v.iter().fold(0, |a, &x| a * 13 + x.unsigned_abs() as usize),
262        _ => v
263            .iter()
264            .fold(0, |a, &x| a * 17 + x.unsigned_abs().min(16) as usize),
265    }
266}
267
268/// Bits for the escape sequence after a value of 16 or more.
269fn escape_bits(magnitude: i32) -> u32 {
270    let n = 31 - (magnitude as u32).leading_zeros(); // floor(log2), at least 4
271    (n - 4) + 1 + n
272}
273
274/// Bits a tuple costs in a codebook.
275fn tuple_bits(cb: usize, v: &[i32]) -> u32 {
276    let mut bits = u32::from(BITS[cb - 1][tuple_index(cb, v)]);
277    if !CB_SIGNED[cb - 1] {
278        bits += v.iter().filter(|&&x| x != 0).count() as u32;
279    }
280    if cb == 11 {
281        bits += v
282            .iter()
283            .filter(|&&x| x.abs() >= 16)
284            .map(|&x| escape_bits(x.abs()))
285            .sum::<u32>();
286    }
287    bits
288}
289
290fn put_tuple(out: &mut Sink, cb: usize, v: &[i32]) {
291    let idx = tuple_index(cb, v);
292    out.put(u32::from(CODES[cb - 1][idx]), u32::from(BITS[cb - 1][idx]));
293    if !CB_SIGNED[cb - 1] {
294        for &x in v {
295            if x != 0 {
296                out.put(u32::from(x < 0), 1);
297            }
298        }
299    }
300    if cb == 11 {
301        for &x in v {
302            if x.abs() >= 16 {
303                let m = x.unsigned_abs();
304                let n = 31 - m.leading_zeros();
305                // n - 4 ones, a zero, then the n low bits.
306                for _ in 0..n - 4 {
307                    out.put(1, 1);
308                }
309                out.put(0, 1);
310                out.put(m & ((1 << n) - 1), n);
311            }
312        }
313    }
314}
315
316/// Bits to code the coefficients `q[start..end]` in codebook `cb`; `None` if
317/// a value does not fit.
318fn band_bits(cb: usize, q: &[i32]) -> Option<u32> {
319    let dim = CB_DIM[cb - 1];
320    if q.iter().any(|&x| x.abs() > CB_MAX[cb - 1]) {
321        return None;
322    }
323    Some(q.chunks(dim).map(|c| tuple_bits(cb, c)).sum())
324}
325
326/// A run of bands sharing a codebook.
327#[derive(Clone, Copy, Debug)]
328struct Section {
329    cb: usize,
330    first: usize,
331    end: usize,
332}
333
334/// How a channel's quantized spectrum is coded.
335struct Plan {
336    sections: Vec<Section>,
337    /// Bits in the section data, the scalefactors and the spectrum.
338    bits: u32,
339}
340
341/// Picks the cheapest codebook for each band, merges runs into sections and
342/// totals the bits (everything after `global_gain`, before the spectrum's
343/// own flags).
344fn plan(q: &[i32], offsets: &[u16], sf: &[i32], max_sfb: usize) -> Plan {
345    let mut cbs = Vec::with_capacity(max_sfb);
346    let mut spectral = 0u32;
347    for b in 0..max_sfb {
348        let band = &q[usize::from(offsets[b])..usize::from(offsets[b + 1])];
349        if band.iter().all(|&x| x == 0) {
350            cbs.push(0);
351            continue;
352        }
353        let (cb, bits) = (1..=11)
354            .filter_map(|cb| band_bits(cb, band).map(|bits| (cb, bits)))
355            .min_by_key(|&(_, bits)| bits)
356            .expect("book 11 takes any value");
357        cbs.push(cb);
358        spectral += bits;
359    }
360    // Sections: equal neighbours merge.
361    let mut sections: Vec<Section> = Vec::new();
362    for (b, &cb) in cbs.iter().enumerate() {
363        match sections.last_mut() {
364            Some(s) if s.cb == cb => s.end = b + 1,
365            _ => sections.push(Section {
366                cb,
367                first: b,
368                end: b + 1,
369            }),
370        }
371    }
372    let mut bits = spectral;
373    for s in &sections {
374        bits += 4 + 5 * ((s.end - s.first) as u32 / 31 + 1);
375    }
376    let mut prev = None;
377    for (b, &cb) in cbs.iter().enumerate() {
378        if cb != 0 {
379            let delta = sf[b] - prev.unwrap_or(sf[b]);
380            bits += u32::from(SF_BITS[(delta + 60) as usize]);
381            prev = Some(sf[b]);
382        }
383    }
384    Plan { sections, bits }
385}
386
387/// Writes section data, scalefactors and spectrum for one channel.
388fn write_channel_body(out: &mut Sink, q: &[i32], offsets: &[u16], sf: &[i32], plan: &Plan) {
389    for s in &plan.sections {
390        out.put(s.cb as u32, 4);
391        let mut len = s.end - s.first;
392        while len >= 31 {
393            out.put(31, 5);
394            len -= 31;
395        }
396        out.put(len as u32, 5);
397    }
398    let mut prev = None;
399    for s in &plan.sections {
400        if s.cb == 0 {
401            continue;
402        }
403        for b in s.first..s.end {
404            let delta = sf[b] - prev.unwrap_or(sf[b]);
405            let i = (delta + 60) as usize;
406            out.put(SF_CODE[i], u32::from(SF_BITS[i]));
407            prev = Some(sf[b]);
408        }
409    }
410    // pulse_data_present, tns_data_present, gain_control_data_present.
411    out.put(0, 3);
412    for s in &plan.sections {
413        if s.cb == 0 {
414            continue;
415        }
416        let dim = CB_DIM[s.cb - 1];
417        for b in s.first..s.end {
418            for c in q[usize::from(offsets[b])..usize::from(offsets[b + 1])].chunks(dim) {
419                put_tuple(out, s.cb, c);
420            }
421        }
422    }
423}
424
425// -------------------------------------------------------------- quantizer
426
427/// The rounding offset the AAC reference encoders use.
428const ROUNDING: f64 = 0.4054;
429
430/// `2^(3 (sf - 100) / 16)`: the step to the 3/4 power.
431fn step34(sf: i32) -> f64 {
432    (3.0 * f64::from(sf - 100) / 16.0).exp2()
433}
434
435/// The largest quantized magnitude AAC can code: the escape sequence tops out here.
436const MAX_QUANTIZED: f64 = 8191.0;
437
438/// Quantizes the bands below `max_sfb`. Returns false if any value is too big
439/// to code (the step is too fine), in which case `q` is not usable.
440fn quantize(companded: &[f64], offsets: &[u16], sf: &[i32], max_sfb: usize, q: &mut [i32]) -> bool {
441    let mut fits = true;
442    for b in 0..max_sfb {
443        let inv = 1.0 / step34(sf[b]);
444        for k in usize::from(offsets[b])..usize::from(offsets[b + 1]) {
445            let v = (companded[k] * inv + ROUNDING).floor();
446            fits &= v <= MAX_QUANTIZED;
447            q[k] = v.min(MAX_QUANTIZED) as i32;
448        }
449    }
450    fits
451}
452
453// ---------------------------------------------------------------- encoder
454
455/// Encodes a stream frame by frame.
456pub struct AacEncoder {
457    cfg: EncoderConfig,
458    sf_index: usize,
459    offsets: &'static [u16],
460    num_swb: usize,
461    window: Vec<f64>,
462    mdct: Mdct,
463    /// The previous frame's samples, per channel, for the overlap.
464    previous: Vec<Vec<f64>>,
465    /// Samples pushed but not yet in a frame, per channel.
466    pending: Vec<Vec<f32>>,
467    /// Bands at or above this are never coded (the low-pass).
468    cutoff_bands: usize,
469    /// Bits saved (or owed) against the average, for the reservoir.
470    bank: i64,
471    average_bits: i64,
472    frames: u64,
473    /// Samples pushed in total, for the flush.
474    pushed: u64,
475}
476
477/// The MDCT scale: the transform's factor 2, and 32768 for the 16-bit range
478/// AAC's scalefactors are defined against.
479const SCALE: f64 = 2.0 * 32_768.0;
480
481impl AacEncoder {
482    pub fn new(cfg: EncoderConfig) -> Result<Self, EncodeError> {
483        let sf_index = SAMPLE_RATES
484            .iter()
485            .position(|&r| r == cfg.sample_rate)
486            .ok_or(EncodeError::SampleRate(cfg.sample_rate))?;
487        if !(1..=2).contains(&cfg.channels) {
488            return Err(EncodeError::Channels(cfg.channels));
489        }
490        if cfg.bitrate < 8_000 * cfg.channels as u32 || cfg.bitrate > 320_000 {
491            return Err(EncodeError::Bitrate(cfg.bitrate));
492        }
493        let offsets = SWB_OFFSET_1024[sf_index];
494        let num_swb = usize::from(NUM_SWB_1024[sf_index]);
495        // About a quarter of the per-channel bitrate in Hz: 64 kbit/s a
496        // channel keeps 16 kHz, 32 kbit/s keeps 8 kHz.
497        let cutoff_hz = (f64::from(cfg.bitrate) / cfg.channels as f64 * 0.25)
498            .clamp(4_000.0, f64::from(cfg.sample_rate) / 2.0);
499        let cutoff_bin = (cutoff_hz / (f64::from(cfg.sample_rate) / 2.0) * FRAME as f64) as usize;
500        let cutoff_bands = (0..num_swb)
501            .take_while(|&b| usize::from(offsets[b + 1]) <= cutoff_bin.max(usize::from(offsets[1])))
502            .count()
503            .max(1);
504        Ok(Self {
505            cfg,
506            sf_index,
507            offsets,
508            num_swb,
509            window: (0..2 * FRAME)
510                .map(|n| (std::f64::consts::PI * (n as f64 + 0.5) / (2 * FRAME) as f64).sin())
511                .collect(),
512            mdct: Mdct::new(FRAME),
513            previous: vec![vec![0.0; FRAME]; cfg.channels],
514            pending: vec![Vec::new(); cfg.channels],
515            cutoff_bands,
516            bank: 0,
517            average_bits: (f64::from(cfg.bitrate) * FRAME as f64 / f64::from(cfg.sample_rate))
518                as i64,
519            frames: 0,
520            pushed: 0,
521        })
522    }
523
524    /// The two-byte `AudioSpecificConfig` for an MP4 `esds`.
525    pub fn audio_specific_config(&self) -> [u8; 2] {
526        // objectType 2 (5 bits), frequency index (4), channels (4), 3 zero bits.
527        let v = (2u16 << 11) | ((self.sf_index as u16) << 7) | ((self.cfg.channels as u16) << 3);
528        v.to_be_bytes()
529    }
530
531    pub fn config(&self) -> &EncoderConfig {
532        &self.cfg
533    }
534
535    /// Adds samples (one slice per channel, equal lengths) and returns the
536    /// raw access units for every frame that is now complete.
537    pub fn push(&mut self, planar: &[&[f32]]) -> Result<Vec<Vec<u8>>, EncodeError> {
538        if planar.len() != self.cfg.channels {
539            return Err(EncodeError::Input(format!(
540                "{} channels given, {} expected",
541                planar.len(),
542                self.cfg.channels
543            )));
544        }
545        if planar.iter().any(|c| c.len() != planar[0].len()) {
546            return Err(EncodeError::Input("the channels differ in length".into()));
547        }
548        for (p, c) in self.pending.iter_mut().zip(planar) {
549            p.extend_from_slice(c);
550        }
551        self.pushed += planar[0].len() as u64;
552        let mut units = Vec::new();
553        while self.pending[0].len() >= FRAME {
554            let frame: Vec<Vec<f32>> = self
555                .pending
556                .iter_mut()
557                .map(|p| p.drain(..FRAME).collect())
558                .collect();
559            units.push(self.encode_frame(&frame));
560        }
561        Ok(units)
562    }
563
564    /// Ends the stream: pads with silence so the last samples (and the
565    /// overlap that carries them) come out, and returns those frames.
566    pub fn finish(&mut self) -> Vec<Vec<u8>> {
567        let mut units = Vec::new();
568        let owed = self.pending[0].len();
569        // The remainder, padded to a frame, then one frame of silence to
570        // flush the overlap.
571        let extra = if owed > 0 { 2 } else { 1 };
572        for round in 0..extra {
573            let frame: Vec<Vec<f32>> = self
574                .pending
575                .iter_mut()
576                .map(|p| {
577                    let mut f: Vec<f32> = if round == 0 {
578                        std::mem::take(p)
579                    } else {
580                        Vec::new()
581                    };
582                    f.resize(FRAME, 0.0);
583                    f
584                })
585                .collect();
586            units.push(self.encode_frame(&frame));
587        }
588        units
589    }
590
591    fn encode_frame(&mut self, frame: &[Vec<f32>]) -> Vec<u8> {
592        let channels = self.cfg.channels;
593        // MDCT of each channel.
594        let mut spectra: Vec<Vec<f64>> = Vec::with_capacity(channels);
595        for (ch, new) in frame.iter().enumerate() {
596            let mut block = Vec::with_capacity(2 * FRAME);
597            block.extend_from_slice(&self.previous[ch]);
598            block.extend(new.iter().map(|&s| f64::from(s)));
599            self.previous[ch] = block[FRAME..].to_vec();
600            for (s, w) in block.iter_mut().zip(&self.window) {
601                *s *= w;
602            }
603            let mut spec = vec![0.0; FRAME];
604            self.mdct.forward(&block, &mut spec);
605            for s in &mut spec {
606                *s *= SCALE;
607            }
608            // The low-pass.
609            for s in &mut spec[usize::from(self.offsets[self.cutoff_bands])..] {
610                *s = 0.0;
611            }
612            spectra.push(spec);
613        }
614
615        // Mid/side per band, where it needs fewer bits.
616        let mut ms = vec![false; self.num_swb];
617        if channels == 2 {
618            for b in 0..self.cutoff_bands {
619                let (lo, hi) = (
620                    usize::from(self.offsets[b]),
621                    usize::from(self.offsets[b + 1]),
622                );
623                let (mut lr, mut msc) = (0.0, 0.0);
624                for k in lo..hi {
625                    let (l, r) = (spectra[0][k], spectra[1][k]);
626                    lr += l.abs().powf(0.75) + r.abs().powf(0.75);
627                    msc += ((l + r) * 0.5).abs().powf(0.75) + ((l - r) * 0.5).abs().powf(0.75);
628                }
629                // Mid/side spends a finer step on the same noise: it has to
630                // win by more than that costs.
631                ms[b] = msc * 1.25 < lr;
632            }
633            for (b, &on) in ms.iter().enumerate() {
634                if on {
635                    for k in usize::from(self.offsets[b])..usize::from(self.offsets[b + 1]) {
636                        let (l, r) = (spectra[0][k], spectra[1][k]);
637                        spectra[0][k] = (l + r) * 0.5;
638                        spectra[1][k] = (l - r) * 0.5;
639                    }
640                }
641            }
642        }
643
644        let companded: Vec<Vec<f64>> = spectra
645            .iter()
646            .map(|s| s.iter().map(|x| x.abs().powf(0.75)).collect())
647            .collect();
648        let signs: Vec<Vec<bool>> = spectra
649            .iter()
650            .map(|s| s.iter().map(|&x| x < 0.0).collect())
651            .collect();
652
653        // The bit budget: the average plus half of whatever is banked.
654        // A frame cannot hold more than 6144 bits a channel, whatever was
655        // asked for: at a low sample rate a high bitrate asks for more.
656        let most = 6144 * channels as i64 - 100;
657        let budget =
658            (self.average_bits + self.bank / 2).clamp(self.average_bits.min(most) / 2, most) as u32;
659
660        // The finest step (lowest scalefactor) that fits.
661        let (mut lo, mut hi) = (0i32, 255i32);
662        let mut best: Option<Encoded> = None;
663        while lo <= hi {
664            let mid = (lo + hi) / 2;
665            let e = self.try_step(mid, &companded, &signs, &ms);
666            if e.bits <= budget {
667                best = Some(e);
668                hi = mid - 1;
669            } else {
670                lo = mid + 1;
671            }
672        }
673        let e = best.unwrap_or_else(|| self.try_step(255, &companded, &signs, &ms));
674        let bytes = self.write_unit(&e, &ms);
675        self.bank = (self.bank + self.average_bits - (bytes.len() as i64) * 8)
676            .clamp(-self.average_bits * 4, self.average_bits * 4);
677        self.frames += 1;
678        bytes
679    }
680
681    /// Quantizes everything at scalefactor `g` (mid/side bands a little finer)
682    /// and plans the coding.
683    fn try_step(
684        &self,
685        g: i32,
686        companded: &[Vec<f64>],
687        signs: &[Vec<bool>],
688        ms: &[bool],
689    ) -> Encoded {
690        let mut channels = Vec::new();
691        let mut total = 0;
692        let mut max_sfb_all = 0;
693        let mut qs = Vec::new();
694        for ch in 0..self.cfg.channels {
695            let sf: Vec<i32> = (0..self.num_swb)
696                .map(|b| if ms[b] { (g - 2).max(0) } else { g })
697                .collect();
698            let mut q = vec![0i32; FRAME];
699            if !quantize(&companded[ch], self.offsets, &sf, self.cutoff_bands, &mut q) {
700                // Too fine a step for the loudest coefficient: not codable.
701                return Encoded {
702                    channels: Vec::new(),
703                    max_sfb: 0,
704                    bits: u32::MAX,
705                };
706            }
707            let top = (0..self.cutoff_bands)
708                .rev()
709                .find(|&b| {
710                    q[usize::from(self.offsets[b])..usize::from(self.offsets[b + 1])]
711                        .iter()
712                        .any(|&x| x != 0)
713                })
714                .map_or(0, |b| b + 1);
715            max_sfb_all = max_sfb_all.max(top);
716            qs.push((q, sf));
717        }
718        for (ch, (q, sf)) in qs.into_iter().enumerate() {
719            let mut q = q;
720            for (v, &neg) in q.iter_mut().zip(&signs[ch]) {
721                if neg {
722                    *v = -*v;
723                }
724            }
725            channels.push(ChannelData { q, sf, plan: None });
726        }
727        for c in &mut channels {
728            let p = plan(&c.q, self.offsets, &c.sf, max_sfb_all);
729            // global_gain, and the three "present" flags the body ends with.
730            total += p.bits + 8 + 3;
731            c.plan = Some(p);
732        }
733        // The element header, its window info, the mid/side flags, the END
734        // marker, and on average half a byte of alignment.
735        total += if self.cfg.channels == 1 {
736            3 + 4 + 11
737        } else {
738            3 + 4
739                + 1
740                + 11
741                + 2
742                + if ms.iter().take(max_sfb_all).any(|&m| m) {
743                    max_sfb_all as u32
744                } else {
745                    0
746                }
747        };
748        total += 3 + 4;
749        Encoded {
750            channels,
751            max_sfb: max_sfb_all,
752            bits: total,
753        }
754    }
755
756    fn write_unit(&self, e: &Encoded, ms: &[bool]) -> Vec<u8> {
757        let mut out = Sink::writing();
758        let ics_info = |out: &mut Sink| {
759            out.put(0, 1); // reserved
760            out.put(0, 2); // ONLY_LONG_SEQUENCE
761            out.put(0, 1); // sine window
762            out.put(e.max_sfb as u32, 6);
763            out.put(0, 1); // no prediction
764        };
765        // The first coded band's scalefactor is the starting point for the
766        // differences.
767        let global = |c: &ChannelData| -> u32 {
768            let p = c.plan.as_ref().expect("planned");
769            p.sections
770                .iter()
771                .find(|s| s.cb != 0)
772                .map_or(100, |s| c.sf[s.first]) as u32
773        };
774        if self.cfg.channels == 1 {
775            out.put(0, 3); // SCE
776            out.put(0, 4);
777            let c = &e.channels[0];
778            out.put(global(c), 8);
779            ics_info(&mut out);
780            write_channel_body(
781                &mut out,
782                &c.q,
783                self.offsets,
784                &c.sf,
785                c.plan.as_ref().expect("planned"),
786            );
787        } else {
788            out.put(1, 3); // CPE
789            out.put(0, 4);
790            out.put(1, 1); // common window
791            ics_info(&mut out);
792            let any = ms.iter().take(e.max_sfb).any(|&m| m);
793            out.put(if any { 1 } else { 0 }, 2);
794            if any {
795                for &m in ms.iter().take(e.max_sfb) {
796                    out.put(u32::from(m), 1);
797                }
798            }
799            for c in &e.channels {
800                out.put(global(c), 8);
801                write_channel_body(
802                    &mut out,
803                    &c.q,
804                    self.offsets,
805                    &c.sf,
806                    c.plan.as_ref().expect("planned"),
807                );
808            }
809        }
810        out.put(7, 3); // END
811        let mut w = out.writer.expect("writing");
812        w.align_zero();
813        w.finish()
814    }
815
816    /// Wraps a raw access unit in an ADTS header.
817    pub fn adts(&self, unit: &[u8]) -> Vec<u8> {
818        adts_frame(unit, self.sf_index, self.cfg.channels)
819    }
820}
821
822struct ChannelData {
823    q: Vec<i32>,
824    sf: Vec<i32>,
825    plan: Option<Plan>,
826}
827
828struct Encoded {
829    channels: Vec<ChannelData>,
830    max_sfb: usize,
831    bits: u32,
832}
833
834/// An ADTS header (MPEG-4, LC, no CRC, variable-rate buffer fullness) and
835/// the access unit.
836pub fn adts_frame(unit: &[u8], sf_index: usize, channels: usize) -> Vec<u8> {
837    let len = unit.len() + 7;
838    let mut h = [0u8; 7];
839    h[0] = 0xFF;
840    h[1] = 0xF1; // MPEG-4, layer 0, no CRC
841    h[2] = (1 << 6) | ((sf_index as u8) << 2) | ((channels as u8 >> 2) & 1); // profile 1 = LC
842    h[3] = (((channels as u8) & 3) << 6) | ((len >> 11) as u8 & 3);
843    h[4] = (len >> 3) as u8;
844    h[5] = (((len & 7) as u8) << 5) | 0x1F;
845    h[6] = 0xFC;
846    let mut out = h.to_vec();
847    out.extend_from_slice(unit);
848    out
849}
850
851/// Encodes whole channels to an ADTS stream.
852pub fn encode_adts(planar: &[Vec<f32>], cfg: &EncoderConfig) -> Result<Vec<u8>, EncodeError> {
853    let mut enc = AacEncoder::new(*cfg)?;
854    let views: Vec<&[f32]> = planar.iter().map(Vec::as_slice).collect();
855    let mut out = Vec::new();
856    for u in enc.push(&views)?.into_iter().chain(enc.finish()) {
857        out.extend(enc.adts(&u));
858    }
859    Ok(out)
860}
861
862#[cfg(test)]
863mod tests {
864    use super::*;
865
866    #[test]
867    fn mdct_matches_its_definition() {
868        let m = 16;
869        let x: Vec<f64> = (0..2 * m)
870            .map(|i| ((i * 7 + 3) % 11) as f64 - 5.0)
871            .collect();
872        let mut fast = vec![0.0; m];
873        Mdct::new(m).forward(&x, &mut fast);
874        for k in 0..m {
875            let direct: f64 = (0..2 * m)
876                .map(|n| {
877                    x[n] * (std::f64::consts::PI / m as f64
878                        * (n as f64 + 0.5 + m as f64 / 2.0)
879                        * (k as f64 + 0.5))
880                        .cos()
881                })
882                .sum();
883            assert!(
884                (fast[k] - direct).abs() < 1e-9,
885                "bin {k}: {} vs {direct}",
886                fast[k]
887            );
888        }
889    }
890
891    #[test]
892    fn the_dct4_matches_its_definition() {
893        let m = 32;
894        let u: Vec<f64> = (0..m).map(|i| ((i * 5 + 1) % 9) as f64 - 4.0).collect();
895        let mut fast = vec![0.0; m];
896        Mdct::new(m).dct4(&u, &mut fast);
897        for k in 0..m {
898            let direct: f64 = (0..m)
899                .map(|n| {
900                    u[n] * (std::f64::consts::PI / m as f64 * (n as f64 + 0.5) * (k as f64 + 0.5))
901                        .cos()
902                })
903                .sum();
904            assert!((fast[k] - direct).abs() < 1e-9, "bin {k}");
905        }
906    }
907
908    #[test]
909    fn the_asc_and_adts_header_are_right() {
910        let enc = AacEncoder::new(EncoderConfig::new(44_100, 2, 128_000)).unwrap();
911        // AOT 2, index 4, 2 channels: 00010 0100 0010 000.
912        assert_eq!(enc.audio_specific_config(), [0x12, 0x10]);
913        let f = adts_frame(&[1, 2, 3], 4, 2);
914        assert_eq!(&f[..2], &[0xFF, 0xF1]);
915        assert_eq!(f.len(), 10);
916        let len = (usize::from(f[3] & 3) << 11) | (usize::from(f[4]) << 3) | usize::from(f[5] >> 5);
917        assert_eq!(len, 10);
918        assert_eq!(f[2] >> 6, 1, "LC");
919        assert_eq!((f[2] >> 2) & 15, 4);
920        assert_eq!(((f[2] & 1) << 2) | (f[3] >> 6), 2);
921    }
922
923    #[test]
924    fn bad_settings_are_refused() {
925        assert_eq!(
926            AacEncoder::new(EncoderConfig::new(12_345, 2, 128_000)).err(),
927            Some(EncodeError::SampleRate(12_345))
928        );
929        assert_eq!(
930            AacEncoder::new(EncoderConfig::new(44_100, 3, 128_000)).err(),
931            Some(EncodeError::Channels(3))
932        );
933        assert_eq!(
934            AacEncoder::new(EncoderConfig::new(44_100, 2, 8_000)).err(),
935            Some(EncodeError::Bitrate(8_000))
936        );
937        let mut enc = AacEncoder::new(EncoderConfig::new(44_100, 2, 128_000)).unwrap();
938        assert!(matches!(
939            enc.push(&[&[0.0; 10][..]]),
940            Err(EncodeError::Input(_))
941        ));
942        assert!(matches!(
943            enc.push(&[&[0.0; 10][..], &[0.0; 9][..]]),
944            Err(EncodeError::Input(_))
945        ));
946    }
947
948    #[test]
949    fn escape_sequences_have_the_right_length() {
950        // 16 = 2^4: no ones, a zero, four bits.
951        assert_eq!(escape_bits(16), 5);
952        assert_eq!(escape_bits(31), 5);
953        assert_eq!(escape_bits(32), 7);
954        assert_eq!(escape_bits(8191), 8 + 1 + 12);
955    }
956}