Skip to main content

threers_codec/opus/
mod.rs

1//! Opus, decoded as ffmpeg n7.1's native decoder does (`libavcodec/opus`,
2//! the decoder the ffmpeg CLI picks: "opus (native)"), bit for bit on
3//! aarch64: SILK (resampled to 48 kHz by its own libswresample context,
4//! `filter_size 16`), CELT (av_tx's PFA inverse MDCT over the NEON
5//! power-of-two codelets), hybrid mode with the CELT delay FIFO,
6//! redundancy frames, multistream channel mapping (families 0, 1, 2, 255)
7//! and the OpusHead output gain. [`decode_webm`] drives it the way the CLI
8//! does for a WebM/Matroska file: pre-skip from the header, `DiscardPadding`
9//! trimmed off the end, and the decoder drained at EOF.
10
11pub mod celt;
12pub mod mdct15;
13pub mod rc;
14pub mod silk;
15#[rustfmt::skip]
16/// SILK and CELT tables, generated from ffmpeg n7.1 `opus/tab.c`.
17pub mod tab;
18
19use crate::swr::SwrStream;
20use celt::Celt;
21use rc::Rc;
22use silk::Silk;
23use tab::{CELT_BAND_END, CELT_WINDOW2};
24
25const MODE_SILK: u8 = 0;
26const MODE_HYBRID: u8 = 1;
27const MODE_CELT: u8 = 2;
28
29const SILK_FRAME_DURATION_MS: [usize; 16] = [
30    10, 20, 40, 60, 10, 20, 40, 60, 10, 20, 40, 60, 10, 20, 10, 20,
31];
32const SILK_RESAMPLE_DELAY: [usize; 5] = [4, 8, 11, 11, 11];
33const FRAME_DURATION: [usize; 32] = [
34    480, 960, 1920, 2880, 480, 960, 1920, 2880, 480, 960, 1920, 2880, 480, 960, 480, 960, 120, 240,
35    480, 960, 120, 240, 480, 960, 120, 240, 480, 960, 120, 240, 480, 960,
36];
37const MAX_FRAME_SIZE: usize = 1275;
38
39/// `OpusPacket`.
40#[derive(Clone, Debug, Default)]
41pub struct Packet {
42    /// Bytes in the packet, padding included.
43    pub packet_size: usize,
44    /// Bytes of frame data, padding excluded.
45    pub data_size: usize,
46    /// The TOC's frame-count code, 0 to 3 (RFC 6716 §3.2).
47    pub code: u8,
48    /// Whether the TOC's stereo bit is set.
49    pub stereo: bool,
50    /// Whether a code-3 packet's frames have their own sizes.
51    pub vbr: bool,
52    /// The TOC configuration number, 0 to 31.
53    pub config: usize,
54    /// Frames in the packet.
55    pub frame_count: usize,
56    /// Where each frame starts, in bytes from the start of the packet.
57    pub frame_offset: Vec<usize>,
58    /// Each frame's size in bytes.
59    pub frame_size: Vec<usize>,
60    /// Samples per frame at 48 kHz.
61    pub frame_duration: usize,
62    /// 0 for SILK, 1 for hybrid, 2 for CELT.
63    pub mode: u8,
64    /// Audio bandwidth: 0 narrowband to 4 fullband.
65    pub bandwidth: usize,
66}
67
68fn lacing16(b: &[u8], p: &mut usize, end: usize) -> Option<usize> {
69    if *p >= end {
70        return None;
71    }
72    let mut v = b[*p] as usize;
73    *p += 1;
74    if v >= 252 {
75        if *p >= end {
76            return None;
77        }
78        v += 4 * b[*p] as usize;
79        *p += 1;
80    }
81    Some(v)
82}
83
84fn lacing_full(b: &[u8], p: &mut usize, end: usize) -> Option<usize> {
85    let mut v = 0usize;
86    loop {
87        if *p >= end {
88            return None;
89        }
90        let next = b[*p] as usize;
91        *p += 1;
92        v += next;
93        if next < 255 {
94            break;
95        }
96        v -= 1;
97    }
98    Some(v)
99}
100
101/// `ff_opus_parse_packet`.
102pub fn parse_packet(buf: &[u8], self_delimiting: bool) -> Result<Packet, String> {
103    let fail = || Err::<Packet, String>("Error parsing the packet header.".into());
104    let mut pkt = Packet::default();
105    let mut end = buf.len();
106    let mut buf_size = buf.len();
107    if buf_size < 1 {
108        return fail();
109    }
110    let mut p = 0usize;
111    let toc = buf[p];
112    p += 1;
113    pkt.code = toc & 3;
114    pkt.stereo = (toc >> 2) & 1 == 1;
115    pkt.config = (toc >> 3) as usize;
116    if pkt.code >= 2 && buf_size < 2 {
117        return fail();
118    }
119    let mut padding = 0usize;
120    match pkt.code {
121        0 => {
122            pkt.frame_count = 1;
123            if self_delimiting {
124                let Some(len) = lacing16(buf, &mut p, end) else {
125                    return fail();
126                };
127                if len > end - p {
128                    return fail();
129                }
130                end = p + len;
131                buf_size = end;
132            }
133            let fb = end - p;
134            if fb > MAX_FRAME_SIZE {
135                return fail();
136            }
137            pkt.frame_offset = vec![p];
138            pkt.frame_size = vec![fb];
139        }
140        1 => {
141            pkt.frame_count = 2;
142            if self_delimiting {
143                let Some(len) = lacing16(buf, &mut p, end) else {
144                    return fail();
145                };
146                if 2 * len > end - p {
147                    return fail();
148                }
149                end = p + 2 * len;
150                buf_size = end;
151            }
152            let fb = end - p;
153            if fb & 1 == 1 || fb >> 1 > MAX_FRAME_SIZE {
154                return fail();
155            }
156            pkt.frame_offset = vec![p, p + fb / 2];
157            pkt.frame_size = vec![fb / 2, fb / 2];
158        }
159        2 => {
160            pkt.frame_count = 2;
161            pkt.vbr = true;
162            let Some(fb0) = lacing16(buf, &mut p, end) else {
163                return fail();
164            };
165            if self_delimiting {
166                let Some(len) = lacing16(buf, &mut p, end) else {
167                    return fail();
168                };
169                if len + fb0 > end - p {
170                    return fail();
171                }
172                end = p + fb0 + len;
173                buf_size = end;
174            }
175            if fb0 > end - p {
176                return fail();
177            }
178            let fb1 = end - p - fb0;
179            if fb1 > MAX_FRAME_SIZE {
180                return fail();
181            }
182            pkt.frame_offset = vec![p, p + fb0];
183            pkt.frame_size = vec![fb0, fb1];
184        }
185        _ => {
186            let i = buf[p];
187            p += 1;
188            pkt.frame_count = (i & 0x3f) as usize;
189            let has_padding = (i >> 6) & 1 == 1;
190            pkt.vbr = i >> 7 == 1;
191            if pkt.frame_count == 0 || pkt.frame_count > 48 {
192                return fail();
193            }
194            if has_padding {
195                let Some(v) = lacing_full(buf, &mut p, end) else {
196                    return fail();
197                };
198                padding = v;
199            }
200            pkt.frame_size = vec![0; pkt.frame_count];
201            pkt.frame_offset = vec![0; pkt.frame_count];
202            if pkt.vbr {
203                let mut total = 0;
204                for i in 0..pkt.frame_count - 1 {
205                    let Some(fb) = lacing16(buf, &mut p, end) else {
206                        return fail();
207                    };
208                    pkt.frame_size[i] = fb;
209                    total += fb;
210                }
211                if self_delimiting {
212                    let Some(len) = lacing16(buf, &mut p, end) else {
213                        return fail();
214                    };
215                    if len + total + padding > end - p {
216                        return fail();
217                    }
218                    end = p + total + len + padding;
219                    buf_size = end;
220                }
221                if end < p + padding {
222                    return fail();
223                }
224                let fb = end - p - padding;
225                if total > fb {
226                    return fail();
227                }
228                pkt.frame_offset[0] = p;
229                for i in 1..pkt.frame_count {
230                    pkt.frame_offset[i] = pkt.frame_offset[i - 1] + pkt.frame_size[i - 1];
231                }
232                pkt.frame_size[pkt.frame_count - 1] = fb - total;
233            } else {
234                let fb;
235                if self_delimiting {
236                    let Some(v) = lacing16(buf, &mut p, end) else {
237                        return fail();
238                    };
239                    if pkt.frame_count * v + padding > end - p {
240                        return fail();
241                    }
242                    end = p + pkt.frame_count * v + padding;
243                    buf_size = end;
244                    fb = v;
245                } else {
246                    if end < p + padding {
247                        return fail();
248                    }
249                    let t = end - p - padding;
250                    if !t.is_multiple_of(pkt.frame_count) || t / pkt.frame_count > MAX_FRAME_SIZE {
251                        return fail();
252                    }
253                    fb = t / pkt.frame_count;
254                }
255                pkt.frame_offset[0] = p;
256                pkt.frame_size[0] = fb;
257                for i in 1..pkt.frame_count {
258                    pkt.frame_offset[i] = pkt.frame_offset[i - 1] + pkt.frame_size[i - 1];
259                    pkt.frame_size[i] = fb;
260                }
261            }
262        }
263    }
264    pkt.packet_size = buf_size;
265    pkt.data_size = buf_size - padding;
266    pkt.frame_duration = FRAME_DURATION[pkt.config];
267    if pkt.frame_duration * pkt.frame_count > 5760 {
268        return fail();
269    }
270    if pkt.config < 12 {
271        pkt.mode = MODE_SILK;
272        pkt.bandwidth = pkt.config >> 2;
273    } else if pkt.config < 16 {
274        pkt.mode = MODE_HYBRID;
275        pkt.bandwidth = 3 + (pkt.config >= 14) as usize;
276    } else {
277        pkt.mode = MODE_CELT;
278        pkt.bandwidth = (pkt.config - 16) >> 2;
279        if pkt.bandwidth != 0 {
280            pkt.bandwidth += 1;
281        }
282    }
283    Ok(pkt)
284}
285
286/// One output channel's source (`ChannelMap`).
287#[derive(Clone, Copy, Debug, Default)]
288struct ChannelMap {
289    stream_idx: usize,
290    channel_idx: usize,
291    copy: Option<usize>,
292    silence: bool,
293}
294
295/// `ff_vorbis_channel_layout_offsets`.
296const VORBIS_OFFSETS: [[usize; 8]; 8] = [
297    [0, 0, 0, 0, 0, 0, 0, 0],
298    [0, 1, 0, 0, 0, 0, 0, 0],
299    [0, 2, 1, 0, 0, 0, 0, 0],
300    [0, 1, 2, 3, 0, 0, 0, 0],
301    [0, 2, 1, 3, 4, 0, 0, 0],
302    [0, 2, 1, 4, 5, 3, 0, 0],
303    [0, 2, 1, 5, 6, 4, 3, 0],
304    [0, 2, 1, 6, 7, 4, 5, 3],
305];
306
307/// The parsed `OpusHead` (`ff_opus_parse_extradata`).
308#[derive(Clone, Debug)]
309pub struct Head {
310    /// Output channels.
311    pub channels: usize,
312    /// Samples at 48 kHz to drop from the start of the decode.
313    pub pre_skip: usize,
314    /// Output gain, Q7.8 dB.
315    pub gain_i: i16,
316    /// Elementary streams in the multistream packet.
317    pub nb_streams: usize,
318    /// How many of them are coupled stereo streams.
319    pub nb_stereo_streams: usize,
320    maps: Vec<ChannelMap>,
321}
322
323/// Parse an `OpusHead` (the Matroska `CodecPrivate`, or the first Ogg packet).
324pub fn parse_head(extradata: &[u8]) -> Result<Head, String> {
325    if extradata.len() < 19 {
326        return Err(format!("Invalid extradata size: {}", extradata.len()));
327    }
328    if extradata[8] > 15 {
329        return Err(format!("Extradata version {}", extradata[8]));
330    }
331    let pre_skip = u16::from_le_bytes([extradata[10], extradata[11]]) as usize;
332    let channels = extradata[9] as usize;
333    if channels == 0 {
334        return Err("Zero channel count specified in the extradata".into());
335    }
336    let gain_i = i16::from_le_bytes([extradata[16], extradata[17]]);
337    let map_type = extradata[18];
338    let (streams, stereo_streams, channel_map, vorbis): (usize, usize, Vec<u8>, bool) =
339        match map_type {
340            0 => {
341                if channels > 2 {
342                    return Err("Channel mapping 0 is only specified for up to 2 channels".into());
343                }
344                (1, channels - 1, vec![0, 1], false)
345            }
346            1 | 2 | 255 => {
347                if extradata.len() < 21 + channels {
348                    return Err(format!("Invalid extradata size: {}", extradata.len()));
349                }
350                let (s, ss) = (extradata[19] as usize, extradata[20] as usize);
351                if s == 0 || ss > s || s + ss > 255 {
352                    return Err(format!("Invalid stream/stereo stream count: {s}/{ss}"));
353                }
354                if map_type == 1 && channels > 8 {
355                    return Err("Channel mapping 1 is only specified for up to 8 channels".into());
356                }
357                (s, ss, extradata[21..21 + channels].to_vec(), map_type == 1)
358            }
359            t => return Err(format!("Mapping type {t}")),
360        };
361    let reorder = |i: usize| {
362        if vorbis {
363            VORBIS_OFFSETS[channels - 1][i]
364        } else {
365            i
366        }
367    };
368    let mut maps = vec![ChannelMap::default(); channels];
369    for i in 0..channels {
370        let idx = channel_map[reorder(i)] as usize;
371        if idx == 255 {
372            maps[i].silence = true;
373            continue;
374        }
375        if idx >= streams + stereo_streams {
376            return Err(format!("Invalid channel map for output channel {i}: {idx}"));
377        }
378        maps[i].copy = (0..i).find(|&j| channel_map[reorder(j)] as usize == idx);
379        if idx < 2 * stereo_streams {
380            maps[i].stream_idx = idx / 2;
381            maps[i].channel_idx = idx & 1;
382        } else {
383            maps[i].stream_idx = idx - stereo_streams;
384            maps[i].channel_idx = 0;
385        }
386    }
387    Ok(Head {
388        channels,
389        pre_skip,
390        gain_i,
391        nb_streams: streams,
392        nb_stereo_streams: stereo_streams,
393        maps,
394    })
395}
396
397/// `opus_fade(out, in1, in2, window, len)`: `in2*w + in1*(1.0 - w)`, the
398/// second product in double.
399#[inline]
400fn fade1(in1: f32, in2: f32, w: f32) -> f32 {
401    ((in2 * w) as f64 + in1 as f64 * (1.0 - w as f64)) as f32
402}
403
404/// `OpusStreamContext`.
405struct Stream {
406    output_channels: usize,
407    silk: Silk,
408    celt: Celt,
409    swr: Option<SwrStream>,
410    silk_samplerate: u32,
411    delayed_samples: usize,
412    celt_delay: [Vec<f32>; 2],
413    sync_buffer: [Vec<f32>; 2],
414    redundancy_idx: usize,
415    packet: Packet,
416    decoded_samples: usize,
417    silk_out: [Vec<f32>; 2],
418    celt_out: [Vec<f32>; 2],
419    red_out: [Vec<f32>; 2],
420    /// The stream's output planes for the current packet and the write cursor.
421    out: [Vec<f32>; 2],
422    cur: usize,
423}
424
425impl Stream {
426    fn new(output_channels: usize, apply_phase_inv: bool) -> Self {
427        Stream {
428            output_channels,
429            silk: Silk::new(output_channels),
430            celt: Celt::new(output_channels, apply_phase_inv),
431            swr: None,
432            silk_samplerate: 0,
433            delayed_samples: 0,
434            celt_delay: [Vec::new(), Vec::new()],
435            sync_buffer: [Vec::new(), Vec::new()],
436            redundancy_idx: 0,
437            packet: Packet::default(),
438            decoded_samples: 0,
439            silk_out: [vec![0.0; 960], vec![0.0; 960]],
440            celt_out: [vec![0.0; 960], vec![0.0; 960]],
441            red_out: [vec![0.0; 960], vec![0.0; 960]],
442            out: [Vec::new(), Vec::new()],
443            cur: 0,
444        }
445    }
446
447    fn redundancy_fade(&mut self) {
448        let idx = self.redundancy_idx;
449        if idx != 0 {
450            for c in 0..self.output_channels {
451                for i in 0..120 - idx {
452                    let o = &mut self.out[c][self.cur + i];
453                    *o = fade1(*o, self.red_out[c][120 + idx + i], CELT_WINDOW2[idx + i]);
454                }
455            }
456            self.redundancy_idx = 0;
457        }
458    }
459
460    /// `opus_flush_resample`.
461    fn flush_resample(&mut self, nb_samples: usize) -> Result<(), String> {
462        let swr = self.swr.as_mut().unwrap();
463        let mut ys = vec![Vec::new(); self.output_channels];
464        let got = swr.flush(&mut ys, nb_samples);
465        if got != nb_samples {
466            return Err(format!("Wrong number of flushed samples: {got}"));
467        }
468        for c in 0..self.output_channels {
469            self.out[c][self.cur..self.cur + got].copy_from_slice(&ys[c]);
470        }
471        let celt_size = self.celt_delay[0].len();
472        if celt_size != 0 {
473            if celt_size != nb_samples {
474                return Err("Wrong number of CELT delay samples.".into());
475            }
476            for c in 0..self.output_channels {
477                let d = std::mem::take(&mut self.celt_delay[c]);
478                for (o, &v) in self.out[c][self.cur..self.cur + nb_samples]
479                    .iter_mut()
480                    .zip(&d)
481                {
482                    *o = v.mul_add(1.0, *o);
483                }
484            }
485        }
486        self.redundancy_fade();
487        self.cur += nb_samples;
488        Ok(())
489    }
490
491    /// `opus_decode_redundancy`.
492    fn decode_redundancy(&mut self, data: &[u8], size: usize) -> Result<(), String> {
493        let mut rc = Rc::new(data, size);
494        rc.raw_init(size, size as u32);
495        let n = self.output_channels;
496        let (a, b) = self.red_out.split_at_mut(1);
497        let mut outs: Vec<&mut [f32]> = vec![&mut a[0][..], &mut b[0][..]];
498        outs.truncate(n);
499        self.celt
500            .decode_frame(
501                &mut rc,
502                &mut outs,
503                self.packet.stereo as usize + 1,
504                240,
505                0,
506                CELT_BAND_END[self.packet.bandwidth] as usize,
507            )
508            .map_err(|e| format!("Error decoding the redundancy frame: {e}"))
509    }
510
511    /// `opus_decode_frame`: `data` runs from the frame start to the end of
512    /// the packet (the range decoder may read past `size`).
513    fn decode_frame(&mut self, data: &[u8], size: usize) -> Result<usize, String> {
514        let fd = self.packet.frame_duration;
515        let mut samples = fd;
516        let delayed_samples = self.delayed_samples;
517        let mut size = size;
518        let mut rc = Rc::new(data, size);
519        let mode = self.packet.mode;
520        let nch = self.output_channels;
521
522        if mode == MODE_SILK || mode == MODE_HYBRID {
523            if self.swr.is_none() {
524                let mut swr = SwrStream::new(self.silk_samplerate, 48000, nch, 16)?;
525                let z = vec![0f32; SILK_RESAMPLE_DELAY[self.packet.bandwidth]];
526                let zs: Vec<&[f32]> = (0..nch).map(|_| z.as_slice()).collect();
527                swr.push(&zs);
528                self.swr = Some(swr);
529            }
530            let n = self.silk.decode_superframe(
531                &mut rc,
532                &mut self.silk_out,
533                self.packet.bandwidth.min(2),
534                self.packet.stereo as usize + 1,
535                SILK_FRAME_DURATION_MS[self.packet.config],
536            )?;
537            let ins: Vec<&[f32]> = (0..nch).map(|c| &self.silk_out[c][..n]).collect();
538            let mut ys = vec![Vec::new(); nch];
539            samples = self.swr.as_mut().unwrap().convert(&mut ys, fd, &ins);
540            for c in 0..nch {
541                self.out[c][self.cur..self.cur + samples].copy_from_slice(&ys[c]);
542            }
543            self.delayed_samples += fd - samples;
544        } else {
545            self.silk.flush();
546        }
547
548        let consumed = rc.tell() as usize;
549        let mut redundancy = false;
550        if mode == MODE_HYBRID && consumed + 37 <= size * 8 {
551            redundancy = rc.dec_log(12) != 0;
552        } else if mode == MODE_SILK && consumed + 17 <= size * 8 {
553            redundancy = true;
554        }
555        let (mut redundancy_pos, mut redundancy_size) = (false, 0usize);
556        if redundancy {
557            redundancy_pos = rc.dec_log(1) != 0;
558            redundancy_size = if mode == MODE_HYBRID {
559                rc.dec_uint(256) as usize + 2
560            } else {
561                size - consumed.div_ceil(8)
562            };
563            if redundancy_size > size {
564                return Err("Invalid redundancy frame size.".into());
565            }
566            size -= redundancy_size;
567            celt::stat(if redundancy_pos { 10 } else { 11 });
568            if redundancy_pos {
569                self.decode_redundancy(&data[size..], redundancy_size)?;
570                self.celt.flush();
571            }
572        }
573
574        if mode == MODE_CELT || mode == MODE_HYBRID {
575            let mut out_off = self.cur;
576            let mut celt_output_samples = samples;
577            let delay = self.celt_delay[0].len();
578            if delay != 0 {
579                if mode == MODE_HYBRID {
580                    for c in 0..nch {
581                        let d = std::mem::take(&mut self.celt_delay[c]);
582                        for (o, &v) in self.out[c][out_off..out_off + delay].iter_mut().zip(&d) {
583                            *o = v.mul_add(1.0, *o);
584                        }
585                    }
586                    out_off += delay;
587                    celt_output_samples -= delay;
588                } else {
589                    for c in 0..2 {
590                        self.celt_delay[c].clear();
591                    }
592                }
593            }
594            rc.raw_init(size, size as u32);
595            let start = if mode == MODE_HYBRID { 17 } else { 0 };
596            let end = CELT_BAND_END[self.packet.bandwidth] as usize;
597            let channels = self.packet.stereo as usize + 1;
598            if mode == MODE_CELT {
599                let cur = self.cur;
600                let (a, b) = self.out.split_at_mut(1);
601                let mut outs: Vec<&mut [f32]> = vec![&mut a[0][cur..], &mut b[0][cur..]];
602                outs.truncate(nch);
603                self.celt
604                    .decode_frame(&mut rc, &mut outs, channels, fd, start, end)?;
605            } else {
606                let (a, b) = self.celt_out.split_at_mut(1);
607                let mut outs: Vec<&mut [f32]> = vec![&mut a[0][..], &mut b[0][..]];
608                outs.truncate(nch);
609                self.celt
610                    .decode_frame(&mut rc, &mut outs, channels, fd, start, end)?;
611                for c in 0..nch {
612                    for k in 0..celt_output_samples {
613                        let o = &mut self.out[c][out_off + k];
614                        *o = self.celt_out[c][k].mul_add(1.0, *o);
615                    }
616                    let (celt_out, delay) = (&self.celt_out[c], &mut self.celt_delay[c]);
617                    delay.extend_from_slice(&celt_out[celt_output_samples..fd]);
618                }
619            }
620        } else {
621            self.celt.flush();
622        }
623
624        self.redundancy_fade();
625        if redundancy {
626            if !redundancy_pos {
627                self.celt.flush();
628                self.decode_redundancy(&data[size..], redundancy_size)?;
629                let at = self.cur + samples - 120 + delayed_samples;
630                for c in 0..nch {
631                    for i in 0..120 - delayed_samples {
632                        let o = &mut self.out[c][at + i];
633                        *o = fade1(*o, self.red_out[c][120 + i], CELT_WINDOW2[i]);
634                    }
635                    if delayed_samples != 0 {
636                        self.redundancy_idx = 120 - delayed_samples;
637                    }
638                }
639            } else {
640                let at = self.cur + delayed_samples;
641                for c in 0..nch {
642                    self.out[c][at..at + 120].copy_from_slice(&self.red_out[c][..120]);
643                    for i in 0..120 {
644                        let o = &mut self.out[c][at + 120 + i];
645                        *o = fade1(self.red_out[c][120 + i], *o, CELT_WINDOW2[i]);
646                    }
647                }
648            }
649        }
650        Ok(samples)
651    }
652
653    /// `opus_decode_subpacket`. `buf` starts at the sub-packet and runs to
654    /// the end of the packet (`None` drains).
655    fn decode_subpacket(&mut self, buf: Option<&[u8]>) -> Result<usize, String> {
656        let mut output_samples = 0;
657        let mut flush_needed = false;
658        if let Some(swr) = &self.swr {
659            flush_needed = if buf.is_some() {
660                self.packet.mode == MODE_CELT || swr.in_rate != self.silk_samplerate
661            } else {
662                self.delayed_samples != 0
663            };
664        }
665        if buf.is_none() && !flush_needed {
666            return Ok(0);
667        }
668        if flush_needed {
669            self.flush_resample(self.delayed_samples)
670                .map_err(|e| format!("Error flushing the resampler: {e}"))?;
671            self.swr = None;
672            output_samples += self.delayed_samples;
673            self.delayed_samples = 0;
674            if buf.is_none() {
675                return Ok(output_samples);
676            }
677        }
678        let buf = buf.unwrap();
679        for i in 0..self.packet.frame_count {
680            let (off, size) = (self.packet.frame_offset[i], self.packet.frame_size[i]);
681            let samples = match self.decode_frame(&buf[off..], size) {
682                Ok(s) => s,
683                Err(_) => {
684                    let fd = self.packet.frame_duration;
685                    for c in 0..self.output_channels {
686                        self.out[c][self.cur..self.cur + fd]
687                            .iter_mut()
688                            .for_each(|v| *v = 0.0);
689                    }
690                    fd
691                }
692            };
693            output_samples += samples;
694            self.cur += samples;
695        }
696        Ok(output_samples)
697    }
698}
699
700/// ffmpeg's native Opus decoder.
701pub struct Decoder {
702    /// The `OpusHead` the decoder was opened with.
703    pub head: Head,
704    streams: Vec<Stream>,
705    gain: f32,
706}
707
708impl Decoder {
709    /// `opus_decode_init` from the `OpusHead` (Matroska `CodecPrivate`).
710    pub fn new(extradata: &[u8]) -> Result<Self, String> {
711        let head = parse_head(extradata)?;
712        let gain = if head.gain_i != 0 {
713            10f64.powf(head.gain_i as f64 / (20.0 * 256.0)) as f32
714        } else {
715            0.0
716        };
717        let streams = (0..head.nb_streams)
718            .map(|i| Stream::new(if i < head.nb_stereo_streams { 2 } else { 1 }, true))
719            .collect();
720        Ok(Decoder {
721            head,
722            streams,
723            gain,
724        })
725    }
726
727    /// `opus_decode_packet`: planar output, one Vec per channel (empty when
728    /// nothing came out). `None` drains.
729    pub fn decode(&mut self, pkt: Option<&[u8]>) -> Result<Vec<Vec<f32>>, String> {
730        let nb = self.streams.len();
731        let mut delayed = 0;
732        for s in &self.streams {
733            delayed = delayed.max(s.delayed_samples + s.sync_buffer[0].len());
734        }
735        let mut coded_samples = 0;
736        if let Some(buf) = pkt {
737            let p = parse_packet(buf, nb > 1)?;
738            coded_samples = p.frame_count * p.frame_duration;
739            self.streams[0].silk_samplerate = silk_samplerate(p.config);
740            self.streams[0].packet = p;
741        }
742        let nb_samples = coded_samples + delayed;
743        let channels = self.head.channels;
744        if nb_samples == 0 {
745            return Ok(vec![Vec::new(); channels]);
746        }
747        for s in self.streams.iter_mut() {
748            let n = s.sync_buffer[0].len();
749            for c in 0..2 {
750                s.out[c].clear();
751                s.out[c].resize(nb_samples + 960, 0.0);
752                let sb = std::mem::take(&mut s.sync_buffer[c]);
753                s.out[c][..sb.len()].copy_from_slice(&sb);
754            }
755            s.cur = n;
756        }
757        let mut decoded_samples = usize::MAX;
758        let mut at = 0usize;
759        for i in 0..nb {
760            if let Some(buf) = pkt
761                && i > 0
762            {
763                let p = parse_packet(&buf[at..], i != nb - 1)?;
764                if coded_samples != p.frame_count * p.frame_duration {
765                    return Err(format!("Mismatching coded sample count in substream {i}."));
766                }
767                self.streams[i].silk_samplerate = silk_samplerate(p.config);
768                self.streams[i].packet = p;
769            }
770            let s = &mut self.streams[i];
771            let ret = s.decode_subpacket(pkt.map(|b| &b[at..]))?;
772            s.decoded_samples = ret;
773            decoded_samples = decoded_samples.min(ret);
774            if pkt.is_some() {
775                at += s.packet.packet_size;
776            }
777        }
778        for s in self.streams.iter_mut() {
779            let extra = s.decoded_samples - decoded_samples;
780            if extra != 0 {
781                let base = s.cur - s.decoded_samples + decoded_samples;
782                for c in 0..2 {
783                    s.sync_buffer[c] = s.out[c][base..base + extra].to_vec();
784                }
785            }
786        }
787        let mut out: Vec<Vec<f32>> = vec![Vec::new(); channels];
788        for (i, m) in self.head.maps.iter().enumerate() {
789            out[i] = if let Some(j) = m.copy {
790                out[j].clone()
791            } else if m.silence {
792                vec![0.0; decoded_samples]
793            } else {
794                self.streams[m.stream_idx].out[m.channel_idx][..decoded_samples].to_vec()
795            };
796            if self.head.gain_i != 0 && decoded_samples > 0 {
797                for v in out[i].iter_mut() {
798                    *v *= self.gain;
799                }
800            }
801        }
802        Ok(out)
803    }
804}
805
806fn silk_samplerate(config: usize) -> u32 {
807    if config < 4 {
808        8000
809    } else if config < 8 {
810        12000
811    } else {
812        16000
813    }
814}
815
816/// A decoded Opus track: planar 48 kHz float and the per-frame sample counts
817/// the CLI saw (after pre-skip and discard padding).
818pub struct Decoded {
819    /// Always 48000.
820    pub sample_rate: u32,
821    /// One `Vec` per channel.
822    pub planes: Vec<Vec<f32>>,
823    /// Samples in each decoded frame, in order.
824    pub frame_lens: Vec<usize>,
825}
826
827/// Collects decoded frames through `decode.c`'s `discard_samples`.
828struct Sink {
829    skip: usize,
830    planes: Vec<Vec<f32>>,
831    frame_lens: Vec<usize>,
832}
833
834impl Sink {
835    fn push(&mut self, frame: Vec<Vec<f32>>, discard: usize) {
836        let n = frame.first().map_or(0, |p| p.len());
837        if n == 0 {
838            return;
839        }
840        let mut lo = 0;
841        if self.skip > 0 {
842            if n <= self.skip {
843                self.skip -= n;
844                return;
845            }
846            lo = self.skip;
847            self.skip = 0;
848        }
849        let mut hi = n;
850        if discard > 0 && discard <= n - lo {
851            if discard == n - lo {
852                return;
853            }
854            hi = n - discard;
855        }
856        for (p, f) in self.planes.iter_mut().zip(&frame) {
857            p.extend_from_slice(&f[lo..hi]);
858        }
859        self.frame_lens.push(hi - lo);
860    }
861}
862
863/// Decode a WebM/Matroska file's first Opus track as
864/// `ffmpeg -i IN -f f32le -` does (ffmpeg n7.1, native decoder).
865pub fn decode_webm(data: &[u8]) -> Result<Decoded, String> {
866    decode_matroska(data)?.ok_or_else(|| "no audio track".to_string())
867}
868
869/// The audio of a WebM/Matroska file as the ffmpeg CLI decodes its default
870/// audio stream: `Ok(None)` without an audio track; an error for codecs
871/// other than Opus (ffmpeg's native Vorbis decoder is not ported — the
872/// `vorbis` module is libvorbis, which `soundfile` uses).
873pub fn decode_matroska(data: &[u8]) -> Result<Option<Decoded>, String> {
874    use crate::mkv_demux::{Mkv, TrackKind};
875    let mkv = Mkv::parse(data)?;
876    let audio: Vec<_> = mkv
877        .tracks
878        .iter()
879        .filter(|t| t.kind == TrackKind::Audio)
880        .collect();
881    let Some(track) = audio
882        .iter()
883        .find(|t| t.flag_default)
884        .or(audio.first())
885        .copied()
886    else {
887        return Ok(None);
888    };
889    if !track.codec_id.starts_with("A_OPUS") {
890        return Err(format!(
891            "{}: only Opus audio is decoded from Matroska/WebM",
892            track.codec_id
893        ));
894    }
895    let mut dec = Decoder::new(&track.codec_private)?;
896    // matroskadec rescales DiscardPadding by `codecpar->sample_rate`, which
897    // avformat_find_stream_info has replaced with the decoder's 48 kHz by the
898    // time the (final) padded packets are read.
899    let rate = 48000i128;
900    let mut sink = Sink {
901        skip: dec.head.pre_skip,
902        planes: vec![Vec::new(); dec.head.channels],
903        frame_lens: Vec::new(),
904    };
905    for f in mkv.frames_of(track.number) {
906        let mut discard = 0usize;
907        if f.discard_padding != 0 {
908            // av_rescale_q(ns, 1/1e9, 1/rate), to nearest; the side data
909            // also replaces skip_samples with its first field.
910            let num = f.discard_padding as i128 * rate;
911            let v = if num >= 0 {
912                (num + 500_000_000) / 1_000_000_000
913            } else {
914                -((-num + 500_000_000) / 1_000_000_000)
915            } as i64;
916            if v > 0 {
917                discard = v as usize;
918                sink.skip = 0;
919            } else {
920                sink.skip = (-v) as usize;
921            }
922        }
923        let frame = dec.decode(Some(&f.data))?;
924        sink.push(frame, discard);
925    }
926    loop {
927        let frame = dec.decode(None)?;
928        if frame.first().map_or(0, |p| p.len()) == 0 {
929            break;
930        }
931        sink.push(frame, 0);
932    }
933    Ok(Some(Decoded {
934        sample_rate: 48000,
935        planes: sink.planes,
936        frame_lens: sink.frame_lens,
937    }))
938}