Skip to main content

opus_rs/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2#![allow(unsafe_op_in_unsafe_fn)]
3#![allow(clippy::too_many_arguments)]
4#![allow(clippy::needless_range_loop)]
5
6mod compat;
7mod fixedvec;
8
9pub mod bands;
10pub mod celt;
11pub mod celt_lpc;
12pub mod hp_cutoff;
13pub mod kiss_fft;
14pub mod mdct;
15pub mod modes;
16/// Multistream decode uses `Vec`-based plumbing, so it is only available
17/// with the `std` (default) feature set; the core codec stays `no_std`
18/// + no-`alloc` capable (see `split_self_delimited` docs).
19#[cfg(feature = "std")]
20pub mod multistream;
21pub mod pitch;
22pub mod pvq;
23pub mod quant_bands;
24pub mod range_coder;
25pub mod rate;
26pub mod silk;
27
28pub use silk::{SilkResampler, SilkResamplerDown1_3, SilkResamplerDown1_6};
29
30use crate::fixedvec::FixedVec;
31use core::mem::MaybeUninit;
32pub use celt::{CeltDecoder, CeltEncoder};
33use hp_cutoff::{dc_reject_float, hp_cutoff, hp_cutoff_float, hp_cutoff_i16};
34use range_coder::RangeCoder;
35use silk::control_codec::{silk_control_encoder, silk_setup_lbrr};
36use silk::enc_api::{
37    silk_encode, silk_encode_prefill, silk_encode_prefill_stereo, silk_encode_stereo_packet,
38};
39use silk::init_encoder::silk_init_encoder;
40use silk::lin2log::silk_lin2log;
41use silk::log2lin::silk_log2lin;
42use silk::macros::*;
43use silk::structs::SilkEncoderState;
44
45// --- Heap-free buffer capacity constants (worst case: 2 channels). ---
46const OPUS_MAX_CHANNELS: usize = 2;
47/// Largest API frame in samples/channel (120 ms @ 48 kHz = 5760). Used by the
48/// encoder's per-frame input buffers (sized `frame_size * channels`).
49const OPUS_MAX_FRAME: usize = 5760;
50/// Largest SILK packet at the internal rate: 60 ms at 16 kHz.
51const SILK_MAX_PACKET_SAMPLES: usize = 3 * silk::define::MAX_FRAME_LENGTH;
52/// Largest *single-frame* samples/channel (60 ms @ 48 kHz = 2880). The decoder's
53/// staging buffers hold one sub-frame at a time, so they're sized to this — not
54/// the full packet. (Halves the decoder footprint vs. a naive 5760/channel.)
55const OPUS_MAX_SUBFRAME: usize = 2880;
56/// Decoder per-sub-frame staging cap: `OPUS_MAX_SUBFRAME * max_channels`.
57const OPUS_SUBFRAME_SCRATCH: usize = OPUS_MAX_SUBFRAME * OPUS_MAX_CHANNELS;
58/// High-pass filter state memory (`channels * 2`).
59const OPUS_HP_MEM: usize = OPUS_MAX_CHANNELS * 2;
60/// Decoder `w_pcm_i16` cap (`960 * max_channels`).
61const OPUS_PCM_I16: usize = 960 * OPUS_MAX_CHANNELS;
62/// Decoder `prev_pcm_tail` cap (`240 * max_channels`).
63const OPUS_PCM_TAIL: usize = 240 * OPUS_MAX_CHANNELS;
64/// Max number of frames encoded in one Opus packet (RFC 6716 caps at 48 for
65/// 2.5 ms codes in a 120 ms packet).
66const OPUS_MAX_PACKET_FRAMES: usize = 48;
67/// RFC 6716 §3.1: a single Opus packet carries at most 1276 bytes of data.
68const OPUS_MAX_PACKET_BYTES: usize = 1276;
69/// C `OpusEncoder.delay_buffer[MAX_ENCODER_BUFFER*2]` (480 samples * 2 ch).
70/// Holds the delay-compensation ring feeding the CELT encoder.
71const OPUS_DELAY_BUF: usize = 480 * OPUS_MAX_CHANNELS;
72/// CELT/hybrid input staging cap: `(delay_compensation + frame)*channels`.
73/// Worst case 60 ms stereo @ 48 kHz: (192 + 2880) * 2 = 6144.
74const OPUS_PCM_BUF: usize = (192 + OPUS_MAX_SUBFRAME) * OPUS_MAX_CHANNELS;
75
76#[derive(Debug, Clone, Copy, PartialEq, Eq)]
77pub enum Application {
78    Voip = 2048,
79    Audio = 2049,
80    RestrictedLowDelay = 2051,
81}
82
83#[derive(Debug, Clone, Copy, PartialEq, Eq)]
84pub enum Bandwidth {
85    Auto = -1000,
86    Narrowband = 1101,
87    Mediumband = 1102,
88    Wideband = 1103,
89    Superwideband = 1104,
90    Fullband = 1105,
91}
92
93#[derive(Debug, Clone, Copy, PartialEq, Eq)]
94enum OpusMode {
95    SilkOnly,
96    Hybrid,
97    CeltOnly,
98}
99
100pub struct OpusEncoder {
101    #[cfg(not(feature = "heap"))]
102    celt_enc: CeltEncoder,
103    #[cfg(feature = "heap")]
104    celt_enc: Box<CeltEncoder>,
105    /// SILK encoder for mono input, or for the mid of stereo input (it also
106    /// holds the stereo state).
107    #[cfg(not(feature = "heap"))]
108    silk_enc: SilkEncoderState,
109    #[cfg(feature = "heap")]
110    silk_enc: Box<SilkEncoderState>,
111    /// SILK encoder for the side of stereo input (libopus `state_Fxx[1]`).
112    #[cfg(not(feature = "heap"))]
113    silk_enc_side: SilkEncoderState,
114    #[cfg(feature = "heap")]
115    silk_enc_side: Box<SilkEncoderState>,
116    application: Application,
117    sampling_rate: i32,
118    channels: usize,
119    bandwidth: Bandwidth,
120    pub bitrate_bps: i32,
121    pub complexity: i32,
122    pub use_cbr: bool,
123
124    pub use_inband_fec: bool,
125
126    pub packet_loss_perc: i32,
127    silk_initialized: bool,
128    mode: OpusMode,
129    prev_enc_mode: Option<OpusMode>,
130    /// When set, `encode_impl` uses this mode instead of running the
131    /// mode-selection heuristic. Used to keep all sub-frames of a multiframe
132    /// packet in the same mode (libopus `user_forced_mode`).
133    forced_mode: Option<OpusMode>,
134
135    variable_hp_smth2_q15: i32,
136    hp_mem: FixedVec<i32, OPUS_HP_MEM>,
137
138    #[cfg(not(feature = "heap"))]
139    buf_filtered: FixedVec<i16, OPUS_MAX_FRAME>,
140    #[cfg(feature = "heap")]
141    buf_filtered: Box<FixedVec<i16, OPUS_MAX_FRAME>>,
142    #[cfg(not(feature = "heap"))]
143    buf_silk_input: FixedVec<i16, OPUS_MAX_FRAME>,
144    #[cfg(feature = "heap")]
145    buf_silk_input: Box<FixedVec<i16, OPUS_MAX_FRAME>>,
146    /// Right channel of a stereo frame at the SILK internal rate, beside the
147    /// left in `buf_silk_input`.
148    #[cfg(not(feature = "heap"))]
149    buf_silk_input_right: FixedVec<i16, SILK_MAX_PACKET_SAMPLES>,
150    #[cfg(feature = "heap")]
151    buf_silk_input_right: Box<FixedVec<i16, SILK_MAX_PACKET_SAMPLES>>,
152    /// One channel of a stereo frame at the API rate, de-interleaved for its
153    /// SILK resampler.
154    #[cfg(not(feature = "heap"))]
155    buf_silk_api_channel: FixedVec<i16, OPUS_MAX_FRAME>,
156    #[cfg(feature = "heap")]
157    buf_silk_api_channel: Box<FixedVec<i16, OPUS_MAX_FRAME>>,
158    #[cfg(not(feature = "heap"))]
159    buf_celt_input: FixedVec<f32, OPUS_MAX_FRAME>,
160    #[cfg(feature = "heap")]
161    buf_celt_input: Box<FixedVec<f32, OPUS_MAX_FRAME>>,
162    /// C `delay_buffer[MAX_ENCODER_BUFFER*2]`: delay-compensation ring feeding
163    /// the CELT encoder (see `encoder_buffer` / `delay_compensation`).
164    #[cfg(not(feature = "heap"))]
165    delay_buffer: FixedVec<f32, OPUS_DELAY_BUF>,
166    #[cfg(feature = "heap")]
167    delay_buffer: Box<FixedVec<f32, OPUS_DELAY_BUF>>,
168    /// Interleaved `pcm_buf` staging: `delay prefix + filtered frame` exactly
169    /// like C `opus_encode_frame_native()` builds it before CELT encoding.
170    #[cfg(not(feature = "heap"))]
171    buf_celt_pcm: FixedVec<f32, OPUS_PCM_BUF>,
172    #[cfg(feature = "heap")]
173    buf_celt_pcm: Box<FixedVec<f32, OPUS_PCM_BUF>>,
174    /// f32 staging of the current frame for the CELT/Hybrid float pipeline
175    /// when the caller feeds `encode_i16()` (issue #28).
176    #[cfg(not(feature = "heap"))]
177    buf_f32_frame: FixedVec<f32, OPUS_MAX_FRAME>,
178    #[cfg(feature = "heap")]
179    buf_f32_frame: Box<FixedVec<f32, OPUS_MAX_FRAME>>,
180    /// C `encoder_buffer` (= Fs/100): samples of ring history kept between
181    /// frames (0 for restricted-latency applications).
182    encoder_buffer: usize,
183    /// C `delay_compensation` (= Fs/250): 4 ms lookahead prefix prepended to
184    /// each CELT frame (0 for restricted-latency applications).
185    delay_compensation: usize,
186    /// Float filter state for `dc_reject_float` / `hp_cutoff_float`
187    /// (C `st->hp_mem[4]`, opus_val32 in the float build).
188    hp_mem_float: [f32; 4],
189    /// Encoder-direction SILK input resampler (C `resampler_state` with
190    /// `forEnc = 1`): API rate -> SILK internal rate, carrying the
191    /// `delay_matrix_enc` input delay and the private down-FIR chain. It
192    /// resamples mono input, or the left channel of stereo input.
193    silk_resampler_enc: silk::resampler::SilkResampler,
194    /// The right channel's SILK input resampler: libopus resamples each
195    /// stereo channel separately and splits mid/side at the internal rate.
196    silk_resampler_enc_right: silk::resampler::SilkResampler,
197
198    rc: RangeCoder,
199}
200
201/// Format-agnostic PCM input for `encode_impl` (issue #28): `F32` is the
202/// classic float path; `I16` reaches the SILK integer pipeline directly
203/// and is converted to f32 only where the CELT pipeline requires it.
204#[derive(Clone, Copy)]
205enum PcmInput<'a> {
206    F32(&'a [f32]),
207    I16(&'a [i16]),
208}
209
210impl PcmInput<'_> {
211    fn len(&self) -> usize {
212        match self {
213            PcmInput::F32(s) => s.len(),
214            PcmInput::I16(s) => s.len(),
215        }
216    }
217}
218
219fn compute_equiv_rate(
220    bitrate: i32,
221    channels: usize,
222    frame_rate: i32,
223    vbr: bool,
224    complexity: i32,
225    loss: i32,
226) -> i32 {
227    let mut equiv = bitrate;
228    if frame_rate > 50 {
229        equiv -= (40 * channels as i32 + 20) * (frame_rate - 50);
230    }
231    if !vbr {
232        equiv -= equiv / 12;
233    }
234    equiv = equiv * (90 + complexity) / 100;
235    if loss > 0 {
236        equiv -= equiv * loss / (12 * loss + 20);
237    }
238    equiv
239}
240
241/// `fec_thresholds` (opus_encoder.c:160): LBRR rate threshold and hysteresis
242/// per bandwidth, starting at narrowband.
243const FEC_THRESHOLDS: [i32; 10] = [
244    12000, 1000, // NB
245    14000, 1000, // MB
246    16000, 1000, // WB
247    20000, 1000, // SWB
248    22000, 1000, // FB
249];
250
251fn bandwidth_fec_index(bw: Bandwidth) -> usize {
252    match bw {
253        Bandwidth::Narrowband => 0,
254        Bandwidth::Mediumband => 1,
255        Bandwidth::Wideband => 2,
256        Bandwidth::Superwideband => 3,
257        Bandwidth::Fullband | Bandwidth::Auto => 4,
258    }
259}
260
261fn bandwidth_from_fec_index(idx: usize) -> Bandwidth {
262    match idx {
263        0 => Bandwidth::Narrowband,
264        1 => Bandwidth::Mediumband,
265        2 => Bandwidth::Wideband,
266        3 => Bandwidth::Superwideband,
267        _ => Bandwidth::Fullband,
268    }
269}
270
271/// Port of opus_encoder.c `decide_fec()`: gate in-band FEC on the packet loss
272/// setting and on whether the equivalent rate can afford LBRR at the current
273/// bandwidth. With loss > 5%, the bandwidth is reduced until FEC fits; the
274/// caller's per-frame bandwidth is updated accordingly.
275fn decide_fec(
276    use_in_band_fec: i32,
277    packet_loss_perc: i32,
278    last_fec: i32,
279    mode: OpusMode,
280    bandwidth: &mut Bandwidth,
281    rate: i32,
282) -> i32 {
283    if use_in_band_fec == 0 || packet_loss_perc == 0 || mode == OpusMode::CeltOnly {
284        return 0;
285    }
286    let orig_bandwidth = *bandwidth;
287    loop {
288        let idx = bandwidth_fec_index(*bandwidth);
289        let mut lbrr_rate_thres_bps = FEC_THRESHOLDS[2 * idx];
290        let hysteresis = FEC_THRESHOLDS[2 * idx + 1];
291        if last_fec == 1 {
292            lbrr_rate_thres_bps -= hysteresis;
293        }
294        if last_fec == 0 {
295            lbrr_rate_thres_bps += hysteresis;
296        }
297        // silk_SMULWB(threshold * (125 - min(loss, 25)), 0.01 in Q16)
298        lbrr_rate_thres_bps = silk_smulwb(
299            lbrr_rate_thres_bps * (125 - packet_loss_perc.min(25)),
300            655,
301        );
302        // If loss <= 5%, we look at whether we have enough rate to enable FEC.
303        // If loss > 5%, we decrease the bandwidth until we can enable FEC.
304        if rate > lbrr_rate_thres_bps {
305            return 1;
306        } else if packet_loss_perc <= 5 {
307            return 0;
308        } else if bandwidth_fec_index(*bandwidth) > 0 {
309            let lower = bandwidth_fec_index(*bandwidth) - 1;
310            *bandwidth = bandwidth_from_fec_index(lower);
311        } else {
312            break;
313        }
314    }
315    // Couldn't find any bandwidth to enable FEC, keep original bandwidth.
316    *bandwidth = orig_bandwidth;
317    0
318}
319
320fn compute_mode_threshold(
321    application: Application,
322    channels: usize,
323    prev_was_celt: bool,
324    has_prev_mode: bool,
325    voice_est: i32,
326) -> i32 {
327    let mode_voice = if channels == 1 { 64000 } else { 44000 };
328    let mode_music = 10000;
329
330    let diff = mode_voice - mode_music;
331    let offset = (voice_est * voice_est * diff) >> 14;
332    let mut threshold = mode_music + offset;
333
334    if application == Application::Voip {
335        threshold += 8000;
336    }
337
338    if has_prev_mode {
339        if prev_was_celt {
340            threshold -= 4000;
341        } else {
342            threshold += 4000;
343        }
344    }
345
346    if application == Application::RestrictedLowDelay {
347        threshold = 0;
348    }
349
350    threshold
351}
352
353/// C `bits_to_bitrate` (opus_private.h, libopus 1.6): bits per frame to b/s,
354/// through the 6x frame rate so 60 ms frames (16.67 Hz) round like libopus.
355fn bits_to_bitrate(bits: i32, fs: i32, frame_size: usize) -> i32 {
356    (bits as i64 * (6 * fs as i64 / frame_size as i64) / 6) as i32
357}
358
359/// C `bitrate_to_bits` (opus_private.h, libopus 1.6): b/s to bits per frame.
360fn bitrate_to_bits(bitrate: i32, fs: i32, frame_size: usize) -> i32 {
361    (bitrate as i64 * 6 / (6 * fs as i64 / frame_size as i64)) as i32
362}
363
364/// SILK's share of a Hybrid packet's `rate_bps` (libopus
365/// `compute_silk_rate_for_hybrid`), allocated per channel: stereo codes the
366/// side with SILK too. Not ported: the FEC column, the CBR boost and the SWB
367/// boost.
368fn compute_silk_rate_for_hybrid(rate_bps: i32, frame20ms: bool, channels: usize) -> i32 {
369    let channels = channels as i32;
370    let rate_bps = rate_bps / channels;
371    let silk_rate = silk_rate_for_hybrid_per_channel(rate_bps, frame20ms) * channels;
372    // Small adjustment for stereo (libopus: "calibrated for 32 kb/s").
373    if channels == 2 && rate_bps >= 12000 {
374        silk_rate - 1000
375    } else {
376        silk_rate
377    }
378}
379
380fn silk_rate_for_hybrid_per_channel(rate_bps: i32, frame20ms: bool) -> i32 {
381    const RATE_TABLE: &[(i32, i32, i32)] = &[
382        (0, 0, 0),
383        (12000, 10000, 10000),
384        (16000, 13500, 13500),
385        (20000, 16000, 16000),
386        (24000, 18000, 18000),
387        (32000, 22000, 22000),
388        (64000, 38000, 38000),
389    ];
390    let n = RATE_TABLE.len();
391    let mut i = 1;
392    while i < n && RATE_TABLE[i].0 <= rate_bps {
393        i += 1;
394    }
395    if i == n {
396        let (x_last, r10_last, r20_last) = RATE_TABLE[n - 1];
397        let base = if frame20ms { r20_last } else { r10_last };
398        base + (rate_bps - x_last) / 2
399    } else {
400        let (x0, lo10, lo20) = RATE_TABLE[i - 1];
401        let (x1, hi10, hi20) = RATE_TABLE[i];
402        let (lo, hi) = if frame20ms {
403            (lo20, hi20)
404        } else {
405            (lo10, hi10)
406        };
407        (lo * (x1 - rate_bps) + hi * (rate_bps - x0)) / (x1 - x0)
408    }
409}
410
411#[cfg(all(test, feature = "std"))]
412mod silk_rate_tests {
413    use super::compute_silk_rate_for_hybrid;
414
415    #[test]
416    fn test_reference_table_exact_entries() {
417        assert_eq!(compute_silk_rate_for_hybrid(12000, true, 1), 10000);
418        assert_eq!(compute_silk_rate_for_hybrid(16000, true, 1), 13500);
419        assert_eq!(compute_silk_rate_for_hybrid(20000, true, 1), 16000);
420        assert_eq!(compute_silk_rate_for_hybrid(24000, true, 1), 18000);
421        assert_eq!(compute_silk_rate_for_hybrid(32000, true, 1), 22000);
422        assert_eq!(compute_silk_rate_for_hybrid(64000, true, 1), 38000);
423    }
424
425    #[test]
426    fn test_32kbps_gives_22kbps_silk() {
427        assert_eq!(compute_silk_rate_for_hybrid(32000, true, 1), 22000);
428    }
429
430    #[test]
431    fn test_interpolation_between_table_entries() {
432        let r = compute_silk_rate_for_hybrid(18000, true, 1);
433        assert_eq!(r, 14750);
434    }
435
436    #[test]
437    fn test_above_table_max_gives_half_extra() {
438        let r = compute_silk_rate_for_hybrid(72000, true, 1);
439        assert_eq!(r, 38000 + (72000 - 64000) / 2);
440    }
441
442    /// Stereo looks the rate up per channel, doubles it and, from 12 kb/s per
443    /// channel, takes 1 kb/s off (libopus opus_encoder.c).
444    #[test]
445    fn test_stereo_allocates_per_channel() {
446        let stereo = |rate| compute_silk_rate_for_hybrid(rate, true, 2);
447        assert_eq!(stereo(32000), 2 * 13500 - 1000);
448        assert_eq!(stereo(24000), 2 * 10000 - 1000);
449        assert_eq!(stereo(20000), 2 * 8333);
450        assert_eq!(stereo(64000), 2 * 22000 - 1000);
451    }
452}
453
454/// Uniformly borrow a codec-state field that is a `Box<T>` under the `heap`
455/// feature and a plain `T` otherwise, so call sites don't need `#[cfg]` on
456/// every `&self.field` / `&mut self.field`.
457///
458/// Under `heap` the field is a `Box<...>`, so `T: Deref(DerefMut)` resolves to
459/// the box itself and the `Target` is the inner type; without `heap` the field
460/// is the inner type directly (`?Sized` lets `&mut [i16]`-style coercion choose
461/// the slice target).
462#[cfg(feature = "heap")]
463#[inline(always)]
464fn state_ref<T: core::ops::Deref>(b: &T) -> &T::Target {
465    b
466}
467#[cfg(not(feature = "heap"))]
468#[inline(always)]
469fn state_ref<T: ?Sized>(b: &T) -> &T {
470    b
471}
472
473#[cfg(feature = "heap")]
474#[inline(always)]
475fn state_mut<T: core::ops::DerefMut>(b: &mut T) -> &mut T::Target {
476    b
477}
478#[cfg(not(feature = "heap"))]
479#[inline(always)]
480fn state_mut<T: ?Sized>(b: &mut T) -> &mut T {
481    b
482}
483
484impl OpusEncoder {
485    pub fn new(
486        sampling_rate: i32,
487        channels: usize,
488        application: Application,
489    ) -> Result<Self, &'static str> {
490        if ![8000, 12000, 16000, 24000, 48000].contains(&sampling_rate) {
491            return Err("Invalid sampling rate");
492        }
493        if ![1, 2].contains(&channels) {
494            return Err("Invalid number of channels");
495        }
496
497        let mode = modes::default_mode();
498        #[cfg(feature = "heap")]
499        let celt_enc = Box::new(CeltEncoder::with_sampling_rate(mode, channels, sampling_rate));
500        #[cfg(not(feature = "heap"))]
501        let celt_enc = CeltEncoder::with_sampling_rate(mode, channels, sampling_rate);
502
503        #[cfg(feature = "heap")]
504        let mut silk_enc = Box::new(SilkEncoderState::default());
505        #[cfg(not(feature = "heap"))]
506        let mut silk_enc = SilkEncoderState::default();
507        if silk_init_encoder(state_mut(&mut silk_enc), 0) != 0 {
508            return Err("SILK encoder initialization failed");
509        }
510        #[cfg(feature = "heap")]
511        let mut silk_enc_side = Box::new(SilkEncoderState::default());
512        #[cfg(not(feature = "heap"))]
513        let mut silk_enc_side = SilkEncoderState::default();
514        if silk_init_encoder(state_mut(&mut silk_enc_side), 0) != 0 {
515            return Err("SILK encoder initialization failed");
516        }
517
518        let (opus_mode, bw) = match application {
519            Application::Voip => {
520                let bw = match sampling_rate {
521                    8000 => Bandwidth::Narrowband,
522                    12000 => Bandwidth::Mediumband,
523                    16000 => Bandwidth::Wideband,
524                    24000 => Bandwidth::Superwideband,
525                    48000 => Bandwidth::Fullband,
526                    _ => Bandwidth::Narrowband,
527                };
528
529                let mode = if sampling_rate > 16000 {
530                    OpusMode::Hybrid
531                } else {
532                    OpusMode::SilkOnly
533                };
534                (mode, bw)
535            }
536            Application::RestrictedLowDelay => {
537                let bw = match sampling_rate {
538                    8000 => Bandwidth::Narrowband,
539                    12000 => Bandwidth::Mediumband,
540                    16000 => Bandwidth::Wideband,
541                    24000 => Bandwidth::Superwideband,
542                    _ => Bandwidth::Fullband,
543                };
544                (OpusMode::CeltOnly, bw)
545            }
546            Application::Audio => {
547                if sampling_rate <= 16000 {
548                    let bw = match sampling_rate {
549                        8000 => Bandwidth::Narrowband,
550                        12000 => Bandwidth::Mediumband,
551                        _ => Bandwidth::Wideband,
552                    };
553                    (OpusMode::SilkOnly, bw)
554                } else {
555                    let bw = match sampling_rate {
556                        24000 => Bandwidth::Superwideband,
557                        _ => Bandwidth::Fullband,
558                    };
559                    (OpusMode::Hybrid, bw)
560                }
561            }
562        };
563
564        use silk::lin2log::silk_lin2log;
565        let variable_hp_smth2_q15 = silk_lin2log(60) << 8;
566
567        Ok(Self {
568            celt_enc,
569            silk_enc,
570            silk_enc_side,
571            application,
572            sampling_rate,
573            channels,
574            bandwidth: bw,
575            bitrate_bps: 64000,
576            complexity: 9,
577            use_cbr: false,
578            use_inband_fec: false,
579            packet_loss_perc: 0,
580            silk_initialized: false,
581            prev_enc_mode: None,
582            forced_mode: None,
583            mode: opus_mode,
584            variable_hp_smth2_q15,
585            hp_mem: FixedVec::from_value(0, channels * 2),
586
587            #[cfg(not(feature = "heap"))]
588            buf_filtered: FixedVec::new(),
589            #[cfg(feature = "heap")]
590            buf_filtered: Box::new(FixedVec::new()),
591            #[cfg(not(feature = "heap"))]
592            buf_silk_input: FixedVec::new(),
593            #[cfg(feature = "heap")]
594            buf_silk_input: Box::new(FixedVec::new()),
595            #[cfg(not(feature = "heap"))]
596            buf_silk_input_right: FixedVec::new(),
597            #[cfg(feature = "heap")]
598            buf_silk_input_right: Box::new(FixedVec::new()),
599            #[cfg(not(feature = "heap"))]
600            buf_silk_api_channel: FixedVec::new(),
601            #[cfg(feature = "heap")]
602            buf_silk_api_channel: Box::new(FixedVec::new()),
603            #[cfg(not(feature = "heap"))]
604            buf_celt_input: FixedVec::new(),
605            #[cfg(feature = "heap")]
606            buf_celt_input: Box::new(FixedVec::new()),
607            #[cfg(not(feature = "heap"))]
608            delay_buffer: FixedVec::from_value(0.0, OPUS_DELAY_BUF),
609            #[cfg(feature = "heap")]
610            delay_buffer: Box::new(FixedVec::from_value(0.0, OPUS_DELAY_BUF)),
611            #[cfg(not(feature = "heap"))]
612            buf_celt_pcm: FixedVec::new(),
613            #[cfg(feature = "heap")]
614            buf_celt_pcm: Box::new(FixedVec::new()),
615            #[cfg(not(feature = "heap"))]
616            buf_f32_frame: FixedVec::new(),
617            #[cfg(feature = "heap")]
618            buf_f32_frame: Box::new(FixedVec::new()),
619            encoder_buffer: if matches!(application, Application::RestrictedLowDelay) {
620                0
621            } else {
622                (sampling_rate / 100) as usize
623            },
624            delay_compensation: if matches!(application, Application::RestrictedLowDelay) {
625                0
626            } else {
627                (sampling_rate / 250) as usize
628            },
629            hp_mem_float: [0.0; 4],
630            silk_resampler_enc: silk::resampler::SilkResampler::default(),
631            silk_resampler_enc_right: silk::resampler::SilkResampler::default(),
632            rc: RangeCoder::new_encoder(1),
633        })
634    }
635
636    /// The encoder's lookahead in samples at its sampling rate, like libopus
637    /// `OPUS_GET_LOOKAHEAD`: the pre-skip an Ogg Opus `OpusHead` needs.
638    /// `Fs/400 + Fs/250` (312 samples at 48 kHz), only `Fs/400` for
639    /// `RestrictedLowDelay`.
640    pub fn lookahead(&self) -> usize {
641        self.sampling_rate as usize / 400 + self.delay_compensation
642    }
643
644    pub fn enable_hybrid_mode(&mut self) -> Result<(), &'static str> {
645        if self.sampling_rate != 24000 && self.sampling_rate != 48000 {
646            return Err("Hybrid mode requires 24kHz or 48kHz sampling rate");
647        }
648        let bw = if self.sampling_rate == 48000 {
649            Bandwidth::Fullband
650        } else {
651            Bandwidth::Superwideband
652        };
653        self.mode = OpusMode::Hybrid;
654        self.bandwidth = bw;
655        self.silk_initialized = false;
656        Ok(())
657    }
658
659    /// Encode a frame of interleaved f32 PCM (scale ±1.0; C `opus_encode_float`
660    /// convention where 1.0 maps to PCM16 32768). Samples are consumed exactly
661    /// up to `frame_size * channels`.
662    pub fn encode(
663        &mut self,
664        input: &[f32],
665        frame_size: usize,
666        output: &mut [u8],
667    ) -> Result<usize, &'static str> {
668        self.encode_impl(PcmInput::F32(input), frame_size, output)
669    }
670
671    /// Encode a frame of interleaved PCM16 (`opus_int16` C `opus_encode()`
672    /// convention). Produces byte-for-byte identical packets to
673    /// `encode()` called with the same audio converted via
674    /// `sample as f32 / 32768.0`, while skipping the f32 round-trip in the
675    /// SILK/VoIP path: the integer high-pass biquad and SILK pipeline are fed
676    /// natively, with no temporary conversion buffer (issue #28).
677    pub fn encode_i16(
678        &mut self,
679        input: &[i16],
680        frame_size: usize,
681        output: &mut [u8],
682    ) -> Result<usize, &'static str> {
683        self.encode_impl(PcmInput::I16(input), frame_size, output)
684    }
685
686    fn encode_impl(
687        &mut self,
688        input: PcmInput<'_>,
689        frame_size: usize,
690        output: &mut [u8],
691    ) -> Result<usize, &'static str> {
692        if output.len() < 2 {
693            return Err("Output buffer too small");
694        }
695
696        let frame_rate = frame_rate_from_params(self.sampling_rate, frame_size)
697            .ok_or("Invalid frame size for sampling rate")?;
698
699        // Clamp caller-provided control fields the way libopus's ctl
700        // interface does (OPUS_SET_BITRATE clamps to [500, 3000000];
701        // complexity to [0, 10]). Unclamped extremes overflow the bitrate
702        // arithmetic downstream (bitrate*6 in celt, `equiv*(90+complexity)`
703        // in the mode selection) — issue #27 deep scan.
704        self.bitrate_bps = self.bitrate_bps.clamp(500, 3_000_000);
705        self.complexity = self.complexity.clamp(0, 10);
706        self.packet_loss_perc = self.packet_loss_perc.clamp(0, 100);
707
708        // The encoder consumes exactly frame_size * channels samples per call;
709        // reject short input up front instead of panicking inside the HP filter
710        // or the float→int conversion loops (issue #27 deep-scan).
711        if input.len() < frame_size * self.channels {
712            return Err("Input buffer too small for frame");
713        }
714
715        // Mode selection: match C's opus_encode_native() behavior.
716        // C reference auto-selects between SILK_ONLY and CELT_ONLY; Hybrid is
717        // produced afterwards by bandwidth overrides (SILK-only + FB/SWB → Hybrid).
718        let mut mode = if let Some(forced) = self.forced_mode {
719            forced
720        } else if self.application == Application::RestrictedLowDelay {
721            OpusMode::CeltOnly
722        } else {
723            let equiv = compute_equiv_rate(
724                self.bitrate_bps,
725                self.channels,
726                frame_rate,
727                !self.use_cbr,
728                self.complexity,
729                self.packet_loss_perc,
730            );
731            let prev_was_celt = self.prev_enc_mode == Some(OpusMode::CeltOnly);
732            let has_prev_mode = self.prev_enc_mode.is_some();
733            let voice_est = match self.application {
734                Application::Voip => 115,
735                Application::Audio => 48,
736                Application::RestrictedLowDelay => 0,
737            };
738            let threshold = compute_mode_threshold(
739                self.application,
740                self.channels,
741                prev_was_celt,
742                has_prev_mode,
743                voice_est,
744            );
745            if equiv >= threshold && self.sampling_rate >= 24000 {
746                OpusMode::CeltOnly
747            } else {
748                OpusMode::SilkOnly
749            }
750        };
751
752        if self.forced_mode.is_none() {
753            let curr_bw = self.bandwidth;
754            if mode == OpusMode::SilkOnly
755                && (curr_bw == Bandwidth::Superwideband || curr_bw == Bandwidth::Fullband)
756            {
757                mode = OpusMode::Hybrid;
758            }
759            if mode == OpusMode::Hybrid
760                && (curr_bw == Bandwidth::Narrowband
761                    || curr_bw == Bandwidth::Mediumband
762                    || curr_bw == Bandwidth::Wideband)
763            {
764                mode = OpusMode::SilkOnly;
765            }
766        }
767
768        // Per-frame packet budget (C computes this before the mode-dependent
769        // encode; the starved-budget rules below need it too).
770        let target_bits =
771            (self.bitrate_bps as i64 * frame_size as i64 / self.sampling_rate as i64) as i32;
772        let cbr_bytes = ((target_bits + 4) / 8) as usize;
773        let max_data_bytes = output.len();
774
775        // C parity (opus_encoder.c): the nominal-size cap applies in CBR mode
776        // only. In VBR mode the CELT-internal bound (vbr_rate/reservoir) decides
777        // the per-frame size, allowing overshoot (borrowing) and undershoot.
778        // Capping VBR at nominal defeats the reservoir and starves complex frames.
779        let mut n_bytes = if self.use_cbr {
780            cbr_bytes
781                .min(max_data_bytes)
782                .clamp(1, OPUS_MAX_PACKET_BYTES)
783        } else {
784            max_data_bytes.clamp(1, OPUS_MAX_PACKET_BYTES)
785        };
786
787        // C opus_encoder.c:1525-1527: a budget representing less than 6 kb/s
788        // (9 kb/s for frames longer than 20 ms) cannot carry SILK — libopus
789        // switches to CELT-only mode, which codes it as a small valid packet
790        // instead of a PLC placeholder (issue #46).
791        let tiny_budget_rate: i64 = if frame_rate > 50 { 9000 } else { 6000 };
792        if ((n_bytes as i64) * 8 * (self.sampling_rate as i64))
793            < (tiny_budget_rate * (frame_size as i64))
794        {
795            mode = OpusMode::CeltOnly;
796        }
797
798        // 40/60 ms frames are only legal as a single Opus frame in SILK-only
799        // mode. CELT and Hybrid cap a frame at 20 ms, so libopus encodes 20 ms
800        // sub-frames and repacketizes them into one code 1/2/3 packet
801        // (opus_encoder.c `encode_multiframe_packet`). (issue #35)
802        if self.forced_mode.is_none()
803            && mode != OpusMode::SilkOnly
804            && frame_size > self.sampling_rate as usize / 50
805        {
806            return self.encode_multiframe(input, frame_size, mode, output);
807        }
808
809        // C opus_encoder.c: with mode and bandwidth settled, decide whether
810        // this packet codes in-band FEC (decide_fec()); it can lower the
811        // frame's bandwidth when a high loss rate demands FEC at any cost.
812        // The reduction is per-frame: `self.bandwidth` (the user/auto state)
813        // is left untouched, matching C where the bandwidth is re-derived
814        // every frame.
815        let mut frame_bandwidth = self.bandwidth;
816        let equiv_rate = compute_equiv_rate(
817            self.bitrate_bps,
818            self.channels,
819            frame_rate,
820            !self.use_cbr,
821            self.complexity,
822            self.packet_loss_perc,
823        );
824        let lbrr_coded = decide_fec(
825            if self.use_inband_fec { 1 } else { 0 },
826            self.packet_loss_perc,
827            self.silk_enc.s_cmn.lbrr_enabled,
828            mode,
829            &mut frame_bandwidth,
830            equiv_rate,
831        );
832        if mode == OpusMode::CeltOnly {
833            // silk_mode.LBRR_coded persists across frames even while SILK is
834            // idle; it feeds decide_fec's hysteresis on the next SILK frame.
835            self.silk_enc.s_cmn.lbrr_enabled = 0;
836            self.silk_enc_side.s_cmn.lbrr_enabled = 0;
837        }
838
839        if mode == OpusMode::CeltOnly {
840            match frame_rate {
841                400 | 200 | 100 | 50 => {}
842                _ => return Err("Unsupported frame size for CELT-only mode"),
843            }
844        }
845
846        if mode == OpusMode::Hybrid {
847            match frame_rate {
848                100 | 50 => {}
849                _ => return Err("Unsupported frame size for Hybrid mode"),
850            }
851        }
852
853        if mode == OpusMode::SilkOnly {
854            match frame_rate {
855                100 | 50 | 25 | 16 => {}
856                // 2.5/5 ms are CELT-only durations: SILK frames are 10 ms or
857                // longer (libopus), and sub-10 ms frames break the SILK
858                // analysis geometry (e.g. the VAD band split at 12 kHz).
859                _ => return Err("Unsupported frame size for SILK-only mode"),
860            }
861        }
862
863        let toc = gen_toc(mode, frame_rate, frame_bandwidth, self.channels);
864        output[0] = toc;
865
866        // C opus_encoder.c:1226-1243: a budget too small to code anything
867        // useful produces a TOC-only "PLC" packet — decoders conceal it as a
868        // loss. Encoding into 0-2 bytes would otherwise overflow the range
869        // coder (issue #45). Under CBR the packet is padded to the nominal
870        // size, exactly like libopus's opus_packet_pad.
871        let sub_3_bytes_per_frame =
872            (self.bitrate_bps as i64) < 3 * frame_rate as i64 * 8;
873        let tiny_long_frame =
874            frame_rate < 50
875                && (n_bytes * (frame_rate as usize) < 300 || self.bitrate_bps < 2400);
876        if n_bytes < 3 || sub_3_bytes_per_frame || tiny_long_frame {
877            let mut toc_mode = mode;
878            let mut packet_code = 0u8;
879            let mut num_multiframes = 0u8;
880            let mut frame_rate_adj = frame_rate;
881            if frame_rate > 100 {
882                toc_mode = OpusMode::CeltOnly;
883            }
884            // 40 ms -> 2 x 20 ms in CELT/hybrid mode.
885            if frame_rate == 25 && toc_mode != OpusMode::SilkOnly {
886                frame_rate_adj = 50;
887                packet_code = 1;
888            }
889            // >= 60 ms frames: 1 x 60 ms, or 2 x 40 ms / 2 x 60 ms multiframes.
890            if frame_rate <= 16 {
891                if n_bytes == 1 || (toc_mode == OpusMode::SilkOnly && frame_rate != 10) {
892                    toc_mode = OpusMode::SilkOnly;
893                    packet_code = if frame_rate <= 12 { 1 } else { 0 };
894                    frame_rate_adj = if frame_rate == 12 { 25 } else { 16 };
895                } else {
896                    num_multiframes = (50 / frame_rate) as u8;
897                    frame_rate_adj = 50;
898                    packet_code = 3;
899                }
900            }
901            let mut plc_bw = frame_bandwidth;
902            if toc_mode == OpusMode::SilkOnly && bandwidth_fec_index(plc_bw) > 2 {
903                // SilkOnly is wideband at most (C: bw > OPUS_BANDWIDTH_WIDEBAND).
904                plc_bw = Bandwidth::Wideband;
905            }
906            output[0] = gen_toc(toc_mode, frame_rate_adj, plc_bw, self.channels) | packet_code;
907            let mut ret = if packet_code <= 1 { 1 } else { 2 };
908            if packet_code == 3 {
909                output[1] = num_multiframes;
910            }
911            if self.use_cbr {
912                let target_total = n_bytes.min(output.len());
913                if target_total >= 2 {
914                    // opus_packet_pad of the TOC-only packet: code 3 with
915                    // `m` empty frames and zero padding.
916                    let m: usize = if packet_code == 3 {
917                        num_multiframes as usize
918                    } else if packet_code == 1 {
919                        2
920                    } else {
921                        1
922                    };
923                    output[0] = (output[0] & 0xFC) | 0x03;
924                    output[1] = 0x40 | m as u8; // padding present, CBR, m frames
925                    if target_total > 2 {
926                        let pad_amount = target_total - 2;
927                        let nb_255s = (pad_amount - 1) / 255;
928                        let mut ptr = 2;
929                        for _ in 0..nb_255s {
930                            output[ptr] = 255;
931                            ptr += 1;
932                        }
933                        output[ptr] = (pad_amount - 255 * nb_255s - 1) as u8;
934                        ptr += 1;
935                        for b in &mut output[ptr..target_total] {
936                            *b = 0;
937                        }
938                    }
939                    ret = target_total;
940                }
941            }
942            // C leaves st->prev_mode untouched on this path.
943            return Ok(ret);
944        }
945
946        let init_rc_size = n_bytes - 1;
947        self.rc.reset_for_encode(init_rc_size as u32);
948
949        // C opus_encode_frame_native: high-pass cutoff state is updated for ALL
950        // modes (celt_encoder.c:1969-1977); the filtered signal is what feeds
951        // both SILK (hybrid) and CELT. Compute it here so CELT-only frames also
952        // keep `variable_hp_smth2_q15` in sync with libopus.
953        let hp_freq_smth1 = if mode == OpusMode::CeltOnly {
954            silk_lin2log(60) << 8
955        } else {
956            self.silk_enc.s_cmn.variable_hp_smth1_q15
957        };
958
959        const VARIABLE_HP_SMTH_COEF2_Q16: i32 = 984;
960        self.variable_hp_smth2_q15 = silk_smlawb(
961            self.variable_hp_smth2_q15,
962            hp_freq_smth1 - self.variable_hp_smth2_q15,
963            VARIABLE_HP_SMTH_COEF2_Q16,
964        );
965
966        let cutoff_hz = silk_log2lin(silk_rshift(self.variable_hp_smth2_q15, 8));
967
968        if mode == OpusMode::SilkOnly || mode == OpusMode::Hybrid {
969            let silk_fs_khz = if mode == OpusMode::Hybrid {
970                16
971            } else {
972                self.sampling_rate.min(16000) / 1000
973            };
974
975            let frame_ms = (frame_size as i32 * 1000) / self.sampling_rate;
976
977            // C opus_encoder.c `bits_target` / `total_bitRate` (1.6): SILK
978            // codes at the requested bitrate, capped by the packet budget,
979            // less the TOC byte. Under VBR the budget is the caller's output
980            // buffer, which must cap the rate, not set it (issue #43). CBR
981            // first re-quantizes the bitrate to the whole bytes it codes, as
982            // opus_encode_native does, so the cap is the packet itself.
983            let rate_bps = if self.use_cbr {
984                bits_to_bitrate(8 * n_bytes as i32, self.sampling_rate, frame_size)
985            } else {
986                self.bitrate_bps
987            };
988            let rate_bits = bitrate_to_bits(rate_bps, self.sampling_rate, frame_size);
989            let bits_target = (8 * n_bytes as i32).min(rate_bits) - 8;
990            let total_bitrate = bits_to_bitrate(bits_target, self.sampling_rate, frame_size);
991
992            // C opus_encoder.c:1448-1455: (re)entering SILK/hybrid from CELT
993            // resets the SILK encoder and prefills it with recent (ramped)
994            // audio, so the first SILK frame starts from valid history.
995            let silk_restart_after_celt =
996                self.prev_enc_mode == Some(OpusMode::CeltOnly);
997            if silk_restart_after_celt {
998                silk_init_encoder(state_mut(&mut self.silk_enc), 0);
999                // C silk_InitEncoder also clears the packet-level rate state.
1000                self.silk_enc.n_bits_used_lbrr = 0;
1001                self.silk_enc.n_bits_exceeded = 0;
1002                if self.channels == 2 {
1003                    // C silk_InitEncoder clears the side encoder and the
1004                    // stereo state too; the next stereo frame starts afresh.
1005                    *state_mut(&mut self.silk_enc_side) = SilkEncoderState::default();
1006                    silk_init_encoder(state_mut(&mut self.silk_enc_side), 0);
1007                    self.silk_enc.stereo.reset();
1008                }
1009                self.silk_initialized = false;
1010            }
1011            if !self.silk_initialized || self.silk_enc.s_cmn.fs_khz != silk_fs_khz {
1012                silk_control_encoder(
1013                    state_mut(&mut self.silk_enc),
1014                    silk_fs_khz,
1015                    frame_ms,
1016                    total_bitrate,
1017                    self.complexity,
1018                );
1019                self.silk_enc.s_cmn.use_cbr = if self.use_cbr { 1 } else { 0 };
1020
1021                self.silk_enc.s_cmn.n_channels = self.channels as i32;
1022                self.silk_initialized = true;
1023                // C silk_setup_resamplers: re-init the encoder-direction
1024                // resampler whenever the SILK rate changes; the input delay
1025                // comes from delay_matrix_enc.
1026                let ret = self
1027                    .silk_resampler_enc
1028                    .init_for_enc(self.sampling_rate as i32, silk_fs_khz * 1000);
1029                if ret != 0 {
1030                    return Err("Unsupported SILK resampling ratio");
1031                }
1032                if self.channels == 2 {
1033                    self.silk_resampler_enc_right = self.silk_resampler_enc.clone();
1034                    // The side runs at the mid's rate and frame size (C
1035                    // silk_control_encoder with force_fs_kHz).
1036                    let side = state_mut(&mut self.silk_enc_side);
1037                    silk_control_encoder(
1038                        side,
1039                        silk_fs_khz,
1040                        frame_ms,
1041                        total_bitrate,
1042                        self.complexity,
1043                    );
1044                    side.s_cmn.use_cbr = self.silk_enc.s_cmn.use_cbr;
1045                    side.s_cmn.n_channels = 2;
1046                }
1047            }
1048
1049            // C silk_setup_LBRR (control_codec.c): per-packet FEC state and
1050            // LBRR gain increase (7 on the first FEC packet, then
1051            // max(7 - 0.2*loss, 2)), for each coded channel.
1052            for enc in [&mut self.silk_enc, &mut self.silk_enc_side]
1053                .into_iter()
1054                .take(self.channels)
1055            {
1056                enc.s_cmn.use_in_band_fec = if self.use_inband_fec { 1 } else { 0 };
1057                enc.s_cmn.packet_loss_perc = self.packet_loss_perc.clamp(0, 100);
1058                silk_setup_lbrr(state_mut(enc), lbrr_coded);
1059            }
1060
1061            let silk_frame_len_samples =
1062                frame_size * silk_fs_khz as usize / (self.sampling_rate.max(1000) / 1000) as usize;
1063            let silk_bitrate = if mode == OpusMode::Hybrid {
1064                let frame_duration_ms = frame_size as i32 * 1000 / self.sampling_rate;
1065                let frame20ms = frame_duration_ms >= 20;
1066                compute_silk_rate_for_hybrid(self.bitrate_bps, frame20ms, self.channels)
1067            } else {
1068                // C: SILK gets all bits, at the requested rate (issue #43).
1069                total_bitrate
1070            };
1071
1072            // C opus_encoder.c:1806-1826: prefill the fresh SILK encoder with
1073            // the tail of the delay buffer, zeroed before a 2.5 ms fade-in,
1074            // resampled through the fresh encoder resampler so its delay
1075            // state also starts consistent.
1076            if silk_restart_after_celt && self.encoder_buffer > 0 && self.delay_compensation > 0
1077            {
1078                let ch = self.channels;
1079                let f2_5 = self.sampling_rate / 400;
1080                let eb = self.encoder_buffer;
1081                let offset = eb - self.delay_compensation.min(eb) - f2_5 as usize;
1082                let silk_rate = self.sampling_rate.min(16000);
1083                let pre_resampled_len = eb * silk_rate as usize / self.sampling_rate as usize;
1084                // Stack-fixed: encoder_buffer = Fs/100 <= 480, and the
1085                // resampled prefill is at most the same length (Copy at equal
1086                // rates). No allocation: this crate is heap-free without the
1087                // `heap` feature.
1088                if ch == 2 {
1089                    // Each channel through its own resampler, then mid/side
1090                    // at the internal rate, as C silk_Encode prefills two
1091                    // internal channels.
1092                    let (mut pre_l, mut pre_r) = ([0i16; 480], [0i16; 480]);
1093                    if offset < eb {
1094                        for i in offset..eb {
1095                            let fade = (((i - offset) as f32) / f2_5 as f32).min(1.0);
1096                            pre_l[i] = (self.delay_buffer[2 * i] * fade * 32768.0) as i16;
1097                            pre_r[i] = (self.delay_buffer[2 * i + 1] * fade * 32768.0) as i16;
1098                        }
1099                    }
1100                    let (mut int_l, mut int_r) = ([0i16; 480], [0i16; 480]);
1101                    let int_l = &mut int_l[..pre_resampled_len];
1102                    let int_r = &mut int_r[..pre_resampled_len];
1103                    self.silk_resampler_enc
1104                        .process(int_l, &pre_l[..eb], eb as i32);
1105                    self.silk_resampler_enc_right
1106                        .process(int_r, &pre_r[..eb], eb as i32);
1107                    silk_encode_prefill_stereo(
1108                        state_mut(&mut self.silk_enc),
1109                        state_mut(&mut self.silk_enc_side),
1110                        int_l,
1111                        int_r,
1112                        silk_bitrate,
1113                        1,
1114                    );
1115                } else {
1116                    let mut pre = [0i16; 480];
1117                    let pre = &mut pre[..eb];
1118                    if offset < eb {
1119                        for i in offset..eb {
1120                            let fade = (((i - offset) as f32) / f2_5 as f32).min(1.0);
1121                            pre[i] = (self.delay_buffer[i] * fade * 32768.0) as i16;
1122                        }
1123                    }
1124                    let mut pre_internal = [0i16; 480];
1125                    let pre_internal = &mut pre_internal[..pre_resampled_len];
1126                    self.silk_resampler_enc
1127                        .process(pre_internal, pre, eb as i32);
1128                    silk_encode_prefill(state_mut(&mut self.silk_enc), pre_internal, 1);
1129                }
1130            }
1131
1132            let required_size = frame_size * self.channels;
1133            self.buf_filtered.resize(required_size, 0);
1134            let voip = self.application == Application::Voip;
1135            match input {
1136                PcmInput::I16(samples) => {
1137                    if voip {
1138                        // Native i16 path: feed the integer HP biquad directly,
1139                        // skipping the f32 round-trip and its temporary
1140                        // conversion buffer (issue #28).
1141                        hp_cutoff_i16(
1142                            samples,
1143                            cutoff_hz,
1144                            state_mut(&mut self.buf_filtered),
1145                            &mut self.hp_mem,
1146                            frame_size,
1147                            self.channels,
1148                            self.sampling_rate,
1149                        );
1150                    } else {
1151                        let filtered = state_mut(&mut self.buf_filtered);
1152                        filtered[..required_size].copy_from_slice(&samples[..required_size]);
1153                    }
1154                }
1155                PcmInput::F32(samples) => {
1156                    if voip {
1157                        hp_cutoff(
1158                            samples,
1159                            cutoff_hz,
1160                            state_mut(&mut self.buf_filtered),
1161                            &mut self.hp_mem,
1162                            frame_size,
1163                            self.channels,
1164                            self.sampling_rate,
1165                        );
1166                    } else {
1167                        let filtered = state_mut(&mut self.buf_filtered);
1168                        for (i, &x) in samples.iter().enumerate().take(required_size) {
1169                            filtered[i] = (x * 32768.0).clamp(-32768.0, 32767.0) as i16;
1170                        }
1171                    }
1172                }
1173            }
1174
1175            let input_i16 = state_ref(&self.buf_filtered);
1176
1177            // SILK input resampling (C silk_Encode always runs silk_resampler
1178            // on the API-rate input; the Copy path still applies its
1179            // delay_matrix_enc input delay at equal rates). Stereo resamples
1180            // each channel on its own and splits mid/side at the internal
1181            // rate (enc_API.c, nChannelsInternal 2), in SILK-only and Hybrid
1182            // alike.
1183            self.buf_silk_input.resize(silk_frame_len_samples, 0);
1184            if self.channels == 2 {
1185                self.buf_silk_input_right.resize(silk_frame_len_samples, 0);
1186                for c in 0..2 {
1187                    self.buf_silk_api_channel.resize(frame_size, 0);
1188                    for (s, lr) in self
1189                        .buf_silk_api_channel
1190                        .iter_mut()
1191                        .zip(input_i16.chunks_exact(2))
1192                    {
1193                        *s = lr[c];
1194                    }
1195                    let (resampler, out) = if c == 0 {
1196                        (
1197                            &mut self.silk_resampler_enc,
1198                            state_mut(&mut self.buf_silk_input).as_mut_slice(),
1199                        )
1200                    } else {
1201                        (
1202                            &mut self.silk_resampler_enc_right,
1203                            state_mut(&mut self.buf_silk_input_right).as_mut_slice(),
1204                        )
1205                    };
1206                    if resampler.process(out, &self.buf_silk_api_channel, frame_size as i32) != 0 {
1207                        return Err("SILK input resampling failed");
1208                    }
1209                }
1210            } else {
1211                let got = self.silk_resampler_enc.process(
1212                    state_mut(&mut self.buf_silk_input),
1213                    input_i16,
1214                    frame_size as i32,
1215                );
1216                if got != 0 {
1217                    return Err("SILK input resampling failed");
1218                }
1219            }
1220            let silk_input: &[i16] = state_ref(&self.buf_silk_input);
1221
1222            let mut pn_bytes = 0;
1223
1224            let silk_max_bits = if mode == OpusMode::Hybrid {
1225                let total_max_bits = ((n_bytes - 1) * 8) as i32;
1226                if self.use_cbr {
1227                    let silk_bits = (silk_bitrate as i64 * frame_size as i64
1228                        / self.sampling_rate as i64) as i32;
1229                    let other_bits = 0i32.max(total_max_bits - silk_bits);
1230                    0i32.max(total_max_bits - other_bits * 3 / 4)
1231                } else {
1232                    let frame_duration_ms = frame_size as i32 * 1000 / self.sampling_rate;
1233                    let frame20ms = frame_duration_ms >= 20;
1234                    let max_bit_rate = compute_silk_rate_for_hybrid(
1235                        total_max_bits * self.sampling_rate / frame_size as i32,
1236                        frame20ms,
1237                        self.channels,
1238                    );
1239                    max_bit_rate * frame_size as i32 / self.sampling_rate
1240                }
1241            } else {
1242                ((n_bytes - 1) * 8) as i32
1243            };
1244            let silk_use_cbr = if mode == OpusMode::Hybrid && self.use_cbr {
1245                0
1246            } else if self.use_cbr {
1247                1
1248            } else {
1249                0
1250            };
1251            let ret = if self.channels == 2 {
1252                silk_encode_stereo_packet(
1253                    state_mut(&mut self.silk_enc),
1254                    state_mut(&mut self.silk_enc_side),
1255                    silk_input,
1256                    state_ref(&self.buf_silk_input_right),
1257                    silk_input.len(),
1258                    &mut self.rc,
1259                    &mut pn_bytes,
1260                    silk_bitrate,
1261                    silk_max_bits,
1262                    silk_use_cbr,
1263                    1,
1264                )
1265            } else {
1266                silk_encode(
1267                    state_mut(&mut self.silk_enc),
1268                    silk_input,
1269                    silk_input.len(),
1270                    &mut self.rc,
1271                    &mut pn_bytes,
1272                    silk_bitrate,
1273                    silk_max_bits,
1274                    silk_use_cbr,
1275                    1,
1276                )
1277            };
1278            if ret != 0 {
1279                return Err("SILK encoding failed");
1280            }
1281        }
1282
1283        if mode == OpusMode::Hybrid {
1284            self.rc.encode_bit_logp(false, 12); // redundancy = 0
1285        }
1286
1287        if mode == OpusMode::Hybrid {
1288            let nb_compr_bytes = (n_bytes - 1) as u32;
1289            self.rc.shrink(nb_compr_bytes);
1290        }
1291
1292        let silk_ret_bytes = if mode == OpusMode::SilkOnly {
1293            ((self.rc.tell() + 7) >> 3) as usize
1294        } else {
1295            0
1296        };
1297
1298        // libopus parity: adjust nbCompressedBytes for CELT/Hybrid based on tell (celt_encoder.c:1913-1921)
1299        // tmp = bitrate*frame_size + tell*Fs; nbCompressed = (tmp+4*Fs)/(8*Fs)
1300        // This is the CBR branch (vbr==0) in celt_encoder.c; for VBR the encoder
1301        // does *not* do this adjustment - it uses the vbr_bound logic instead.
1302        // Doing it for VBR would double-shrink and corrupt the budget.
1303        if mode != OpusMode::SilkOnly && self.use_cbr {
1304            let tell = self.rc.tell();
1305            if tell > 1 {
1306                let tmp = self.bitrate_bps as i64 * frame_size as i64
1307                    + tell as i64 * self.sampling_rate as i64;
1308                let adjusted = ((tmp + 4 * self.sampling_rate as i64)
1309                    / (8 * self.sampling_rate as i64)) as usize;
1310                let new_n = adjusted.clamp(1, OPUS_MAX_PACKET_BYTES).min(max_data_bytes);
1311                if new_n < n_bytes {
1312                    n_bytes = new_n;
1313                    // shrink range coder to new size (keep SILK bytes, trim tail)
1314                    let new_payload = n_bytes - 1;
1315                    self.rc.shrink(new_payload as u32);
1316                }
1317            }
1318        }
1319        if mode == OpusMode::CeltOnly || mode == OpusMode::Hybrid {
1320            self.celt_enc.complexity = self.complexity;
1321            let start_band = if mode == OpusMode::Hybrid { 17 } else { 0 };
1322            // libopus `CELT_SET_END_BAND`: match the TOC bandwidth so the
1323            // decoder reads the same number of coded bands (issue #37).
1324            let end_band = match frame_bandwidth {
1325                Bandwidth::Narrowband => 13,
1326                Bandwidth::Mediumband | Bandwidth::Wideband => 17,
1327                Bandwidth::Superwideband => 19,
1328                Bandwidth::Fullband | Bandwidth::Auto => 21,
1329            };
1330            self.celt_enc.set_end_band(end_band);
1331            let total_packet_bits = ((n_bytes - 1) * 8) as i32;
1332            // Propagate bitrate/VBR to CeltEncoder for accurate VBR handling (libopus parity)
1333            let celt_bitrate = if mode == OpusMode::Hybrid {
1334                let frame_ms = frame_size as i32 * 1000 / self.sampling_rate;
1335                let frame20ms = frame_ms >= 20;
1336                let silk_rate =
1337                    compute_silk_rate_for_hybrid(self.bitrate_bps, frame20ms, self.channels);
1338                (self.bitrate_bps - silk_rate).max(8000)
1339            } else {
1340                self.bitrate_bps
1341            };
1342            self.celt_enc.set_bitrate(celt_bitrate);
1343            self.celt_enc.set_vbr(!self.use_cbr);
1344            // libopus: Hybrid VBR is unconstrained (can steal from SILK), CELT-only constrained
1345            self.celt_enc
1346                .set_constrained_vbr(mode == OpusMode::CeltOnly);
1347
1348            // Float view of the current frame for the CELT pipeline. For the
1349            // i16 entry point this converts once into a scratch buffer with
1350            // the exact per-sample scaling a caller of `encode()` performs
1351            // (`s as f32 / 32768.0`), so packets stay byte-for-byte identical
1352            // across the two entry points (issue #28).
1353            let input_f32: &[f32] = match input {
1354                PcmInput::F32(samples) => samples,
1355                PcmInput::I16(samples) => {
1356                    let n = frame_size * self.channels;
1357                    self.buf_f32_frame.resize(n, 0.0);
1358                    let staging = state_mut(&mut self.buf_f32_frame);
1359                    for (dst, &src) in staging[..n].iter_mut().zip(samples[..n].iter()) {
1360                        *dst = src as f32 / 32768.0;
1361                    }
1362                    state_ref(&self.buf_f32_frame)
1363                }
1364            };
1365
1366            // Build the CELT input exactly like C `opus_encode_frame_native`:
1367            //   pcm_buf = [delay-compensation prefix from ring]
1368            //             [dc_reject / hp_cutoff'd current frame]
1369            // CELT then reads pcm_buf[0..frame_size*channels] (opus_encoder.c:
1370            // 1966-2010, 2493). This delay + filter step is what libopus feeds
1371            // its CELT encoder; passing the raw input diverges from 1.6.
1372            let celt_input: &[f32] = if self.delay_compensation > 0 {
1373                let delay = self.delay_compensation;
1374                let ebuf = self.encoder_buffer;
1375                let ch = self.channels;
1376                let total = (delay + frame_size) * ch;
1377                self.buf_celt_pcm.resize(total, 0.0);
1378                // 1. delay prefix from the ring (C: OPUS_COPY at 1967)
1379                let prefix = delay * ch;
1380                let src_start = (ebuf - delay) * ch;
1381                self.buf_celt_pcm[..prefix]
1382                    .copy_from_slice(&self.delay_buffer[src_start..src_start + prefix]);
1383                // 2. filter current frame into pcm_buf[delay..] (C: 2002-2010)
1384                let out = &mut self.buf_celt_pcm[prefix..];
1385                if self.application == Application::Voip {
1386                    hp_cutoff_float(
1387                        input_f32,
1388                        cutoff_hz,
1389                        out,
1390                        &mut self.hp_mem_float,
1391                        frame_size,
1392                        ch,
1393                        self.sampling_rate,
1394                    );
1395                } else {
1396                    dc_reject_float(
1397                        input_f32,
1398                        3,
1399                        out,
1400                        &mut self.hp_mem_float,
1401                        frame_size,
1402                        ch,
1403                        self.sampling_rate,
1404                    );
1405                }
1406                // 3. float NaN guard (C: 2016-2028)
1407                let mut sum = 0.0f32;
1408                for &v in &self.buf_celt_pcm[prefix..] {
1409                    sum += v * v;
1410                }
1411                // C shape kept verbatim (`!(sum < 1e9f) || celt_isnan(sum)`):
1412                // the negated comparison is deliberate NaN handling.
1413                #[allow(clippy::neg_cmp_op_on_partial_ord)]
1414                if !(sum < 1e9) || sum.is_nan() {
1415                    self.buf_celt_pcm[prefix..].fill(0.0);
1416                    self.hp_mem_float = [0.0; 4];
1417                }
1418                // 4. delay ring update (C: 2300-2312)
1419                let keep = ebuf as i64 - (frame_size as i64 + delay as i64);
1420                if keep > 0 {
1421                    let keep = keep as usize;
1422                    self.delay_buffer
1423                        .copy_within(ch * frame_size..ch * (frame_size + keep), 0);
1424                    let dst = ch * keep;
1425                    let n = (frame_size + delay) * ch;
1426                    self.delay_buffer[dst..dst + n].copy_from_slice(&self.buf_celt_pcm[..n]);
1427                } else {
1428                    let n = ebuf * ch;
1429                    let src = (frame_size + delay - ebuf) * ch;
1430                    self.delay_buffer[..n].copy_from_slice(&self.buf_celt_pcm[src..src + n]);
1431                }
1432                // 5. deinterleave pcm_buf[0..frame_size*ch] (interleaved) to
1433                //    channel-major for the Rust CELT encoder.
1434                let n = frame_size * ch;
1435                self.buf_celt_input.resize(n, 0.0);
1436                for i in 0..frame_size {
1437                    for c in 0..ch {
1438                        self.buf_celt_input[c * frame_size + i] = self.buf_celt_pcm[i * ch + c];
1439                    }
1440                }
1441                state_ref(&self.buf_celt_input)
1442            } else if self.channels == 1 {
1443                input_f32
1444            } else {
1445                let n = frame_size * self.channels;
1446                self.buf_celt_input.resize(n, 0.0);
1447                for i in 0..frame_size {
1448                    for ch in 0..self.channels {
1449                        self.buf_celt_input[ch * frame_size + i] =
1450                            input_f32[i * self.channels + ch];
1451                    }
1452                }
1453                state_ref(&self.buf_celt_input)
1454            };
1455
1456            if self.rc.tell() <= total_packet_bits {
1457                let is_vbr = !self.use_cbr;
1458                self.celt_enc.encode_with_budget_vbr(
1459                    celt_input,
1460                    frame_size,
1461                    &mut self.rc,
1462                    start_band,
1463                    total_packet_bits,
1464                    is_vbr,
1465                );
1466            }
1467        }
1468
1469        self.rc.done();
1470
1471        // C opus_encoder.c:2170-2179: "In the unlikely case that the SILK
1472        // encoder busted its target, tell the decoder to call the PLC" — emit
1473        // a minimal packet with an EMPTY frame instead of failing hard. The
1474        // zero-length frame makes the decoder conceal (libopus pads the same
1475        // 2-byte packet with opus_packet_pad under CBR). With FEC the LBRR
1476        // section can squeeze the main frame below what even the
1477        // damage-control re-encode fits, which is exactly the case this
1478        // fallback exists for.
1479        if self.rc.error != 0 || self.rc.tell() > (n_bytes as i32 - 1) * 8 {
1480            if output.len() < 2 {
1481                return Err("Output buffer too small");
1482            }
1483            let mut ret = 2usize;
1484            if self.use_cbr && n_bytes >= 2 {
1485                // CBR: pad to the nominal size as a code-3 packet holding a
1486                // single EMPTY frame (opus_packet_pad of the 2-byte packet).
1487                let target_total = n_bytes.min(output.len());
1488                if target_total > 2 {
1489                    output[0] = toc | 0x03;
1490                    output[1] = 0x41; // 1 frame, padding present, CBR
1491                    let pad_amount = target_total - 2;
1492                    let nb_255s = (pad_amount - 1) / 255;
1493                    let mut ptr = 2;
1494                    for _ in 0..nb_255s {
1495                        output[ptr] = 255;
1496                        ptr += 1;
1497                    }
1498                    output[ptr] = (pad_amount - 255 * nb_255s - 1) as u8;
1499                    ptr += 1;
1500                    for b in &mut output[ptr..target_total] {
1501                        *b = 0;
1502                    }
1503                    self.prev_enc_mode = Some(mode);
1504                    return Ok(target_total);
1505                }
1506                ret = target_total.max(1);
1507            }
1508            // VBR: a 2-byte code-0 packet whose frame length byte is 0.
1509            output[0] = toc;
1510            output[1] = 0;
1511            self.prev_enc_mode = Some(mode);
1512            return Ok(ret);
1513        }
1514
1515        if mode == OpusMode::SilkOnly {
1516            let mut ret = silk_ret_bytes.min(self.rc.storage as usize);
1517            while ret > 2 && self.rc.buf[ret - 1] == 0 {
1518                ret -= 1;
1519            }
1520
1521            let target_total = if self.use_cbr {
1522                n_bytes.min(output.len())
1523            } else {
1524                (ret + 1).min(output.len())
1525            };
1526
1527            let silk_len = ret;
1528
1529            if !self.use_cbr || silk_len + 1 >= target_total {
1530                // VBR or payload fills the target: simple code 0 packet
1531                output[0] = toc;
1532                let copy_len = silk_len.min(target_total - 1);
1533                output[1..1 + copy_len].copy_from_slice(&self.rc.buf[..copy_len]);
1534                return Ok((copy_len + 1).min(output.len()));
1535            }
1536
1537            output[0] = toc | 0x03;
1538
1539            if silk_len + 2 >= target_total {
1540                output[1] = 0x01;
1541                let copy_len = (target_total - 2).min(silk_len);
1542                output[2..2 + copy_len].copy_from_slice(&self.rc.buf[..copy_len]);
1543                self.prev_enc_mode = Some(mode);
1544                return Ok(target_total.min(output.len()));
1545            }
1546
1547            let pad_amount = target_total - silk_len - 2;
1548            output[1] = 0x41;
1549
1550            let nb_255s = (pad_amount - 1) / 255;
1551            let mut ptr = 2;
1552            for _ in 0..nb_255s {
1553                output[ptr] = 255;
1554                ptr += 1;
1555            }
1556            output[ptr] = (pad_amount - 255 * nb_255s - 1) as u8;
1557            ptr += 1;
1558
1559            output[ptr..ptr + silk_len].copy_from_slice(&self.rc.buf[..silk_len]);
1560            ptr += silk_len;
1561
1562            let fill_end = target_total.min(output.len());
1563            for byte in output[ptr..fill_end].iter_mut() {
1564                *byte = 0;
1565            }
1566
1567            self.prev_enc_mode = Some(mode);
1568            return Ok(target_total.min(output.len()));
1569        }
1570
1571        // For CELT/Hybrid, respect possible VBR shrink performed by CeltEncoder (e.g. silence)
1572        let payload_len = (self.rc.storage as usize).min(output.len() - 1);
1573        output[1..1 + payload_len].copy_from_slice(&self.rc.buf[..payload_len]);
1574        self.prev_enc_mode = Some(mode);
1575        Ok(payload_len + 1)
1576    }
1577
1578    /// Repacketize 40/60 ms CELT/Hybrid input as 20 ms sub-frames in one code
1579    /// 1/2/3 Opus packet (libopus `encode_multiframe_packet`). Every sub-frame
1580    /// is forced to `mode` so the packet carries a single config.
1581    fn encode_multiframe(
1582        &mut self,
1583        input: PcmInput<'_>,
1584        frame_size: usize,
1585        mode: OpusMode,
1586        output: &mut [u8],
1587    ) -> Result<usize, &'static str> {
1588        const MAX_SUB: usize = 3; // up to 60 ms of 20 ms frames
1589        let ch = self.channels;
1590        let enc_frame = (self.sampling_rate / 50) as usize; // 20 ms
1591        if enc_frame == 0 || !frame_size.is_multiple_of(enc_frame) {
1592            return Err("Invalid multi-frame size");
1593        }
1594        let nb = frame_size / enc_frame;
1595        if !(2..=MAX_SUB).contains(&nb) {
1596            return Err("Unsupported multi-frame size");
1597        }
1598
1599        // RFC 6716 size field: one byte below 252, else two.
1600        fn put_size(out: &mut [u8], pos: &mut usize, len: usize) -> Result<(), &'static str> {
1601            if len < 252 {
1602                if *pos >= out.len() {
1603                    return Err("Output buffer too small");
1604                }
1605                out[*pos] = len as u8;
1606                *pos += 1;
1607            } else {
1608                if *pos + 1 >= out.len() {
1609                    return Err("Output buffer too small");
1610                }
1611                let first = 252 + (len & 3);
1612                out[*pos] = first as u8;
1613                out[*pos + 1] = ((len - first) >> 2) as u8;
1614                *pos += 2;
1615            }
1616            Ok(())
1617        }
1618
1619        let mut sub = [[0u8; 1276]; MAX_SUB];
1620        let mut lens = [0usize; MAX_SUB];
1621        self.forced_mode = Some(mode);
1622        let enc_res = (|| -> Result<(), &'static str> {
1623            for i in 0..nb {
1624                let start = i * enc_frame * ch;
1625                let end = start + enc_frame * ch;
1626                let sub_input = match input {
1627                    PcmInput::F32(s) => PcmInput::F32(&s[start..end]),
1628                    PcmInput::I16(s) => PcmInput::I16(&s[start..end]),
1629                };
1630                let n = self.encode_impl(sub_input, enc_frame, &mut sub[i])?;
1631                if n == 0 {
1632                    return Err("Empty sub-frame");
1633                }
1634                lens[i] = n - 1;
1635            }
1636            Ok(())
1637        })();
1638        self.forced_mode = None;
1639        enc_res?;
1640
1641        let toc = sub[0][0] & 0xFC;
1642        let mut pos = 0usize;
1643        let push =
1644            |out: &mut [u8], pos: &mut usize, byte: u8| -> Result<(), &'static str> {
1645                if *pos >= out.len() {
1646                    return Err("Output buffer too small");
1647                }
1648                out[*pos] = byte;
1649                *pos += 1;
1650                Ok(())
1651            };
1652        // Use explicit per-frame lengths (code 2 / code 3 VBR) for every
1653        // sub-frame packet: it is always valid, and avoids the code-3 CBR
1654        // assumption that all frames are byte-identical in size.
1655        if nb == 2 {
1656            push(output, &mut pos, toc | 0x02)?;
1657            put_size(output, &mut pos, lens[0])?;
1658        } else {
1659            push(output, &mut pos, toc | 0x03)?;
1660            push(output, &mut pos, nb as u8 | 0x80)?;
1661            for i in 0..nb - 1 {
1662                put_size(output, &mut pos, lens[i])?;
1663            }
1664        }
1665
1666        for i in 0..nb {
1667            let payload = &sub[i][1..1 + lens[i]];
1668            if pos + payload.len() > output.len() {
1669                return Err("Output buffer too small");
1670            }
1671            output[pos..pos + payload.len()].copy_from_slice(payload);
1672            pos += payload.len();
1673        }
1674        self.prev_enc_mode = Some(mode);
1675        Ok(pos)
1676    }
1677}
1678
1679pub struct OpusDecoder {
1680    #[cfg(not(feature = "heap"))]
1681    celt_dec: CeltDecoder,
1682    #[cfg(feature = "heap")]
1683    celt_dec: Box<CeltDecoder>,
1684    #[cfg(not(feature = "heap"))]
1685    silk_dec: silk::dec_api::SilkDecoder,
1686    #[cfg(feature = "heap")]
1687    silk_dec: Box<silk::dec_api::SilkDecoder>,
1688    sampling_rate: i32,
1689    channels: usize,
1690
1691    prev_mode: Option<OpusMode>,
1692
1693    /// Whether the previous frame had redundancy (mode transition marker).
1694    prev_redundancy: bool,
1695    frame_size: usize,
1696
1697    bandwidth: Bandwidth,
1698
1699    stream_channels: usize,
1700
1701    silk_resampler: silk::resampler::SilkResampler,
1702
1703    /// Second resampler instance for stereo channel 1.
1704    silk_resampler_2: silk::resampler::SilkResampler,
1705
1706    prev_internal_rate: i32,
1707
1708    pub hybrid_skip_celt: bool,
1709
1710    #[cfg(not(feature = "heap"))]
1711    w_pcm_i16: FixedVec<i16, OPUS_PCM_I16>,
1712    #[cfg(feature = "heap")]
1713    w_pcm_i16: Box<FixedVec<i16, OPUS_PCM_I16>>,
1714    #[cfg(not(feature = "heap"))]
1715    w_silk_out: FixedVec<f32, OPUS_SUBFRAME_SCRATCH>,
1716    #[cfg(feature = "heap")]
1717    w_silk_out: Box<FixedVec<f32, OPUS_SUBFRAME_SCRATCH>>,
1718    #[cfg(not(feature = "heap"))]
1719    w_pcm_resampled: FixedVec<i16, OPUS_SUBFRAME_SCRATCH>,
1720    #[cfg(feature = "heap")]
1721    w_pcm_resampled: Box<FixedVec<i16, OPUS_SUBFRAME_SCRATCH>>,
1722    #[cfg(not(feature = "heap"))]
1723    w_celt_planar: FixedVec<f32, OPUS_SUBFRAME_SCRATCH>,
1724    #[cfg(feature = "heap")]
1725    w_celt_planar: Box<FixedVec<f32, OPUS_SUBFRAME_SCRATCH>>,
1726    #[cfg(not(feature = "heap"))]
1727    w_celt_out: FixedVec<f32, OPUS_SUBFRAME_SCRATCH>,
1728    #[cfg(feature = "heap")]
1729    w_celt_out: Box<FixedVec<f32, OPUS_SUBFRAME_SCRATCH>>,
1730
1731    /// Tail of the previous frame's output, used for smooth_fade at mode
1732    /// transitions (libopus pcm_transition + smooth_fade).
1733    #[cfg(not(feature = "heap"))]
1734    prev_pcm_tail: FixedVec<f32, OPUS_PCM_TAIL>,
1735    #[cfg(feature = "heap")]
1736    prev_pcm_tail: Box<FixedVec<f32, OPUS_PCM_TAIL>>,
1737}
1738
1739impl OpusDecoder {
1740    pub fn new(sampling_rate: i32, channels: usize) -> Result<Self, &'static str> {
1741        let mut decoder = MaybeUninit::uninit();
1742        Self::init(&mut decoder, sampling_rate, channels)?;
1743        Ok(unsafe { decoder.assume_init() })
1744    }
1745
1746    /// Builds a decoder in `slot` instead of returning it.
1747    ///
1748    /// Without the `heap` feature the decoder is about 175 KB, and `new` returns it
1749    /// through the stack. `init` writes it straight into memory you provide, such as
1750    /// a `static`, so it never has to fit on the stack.
1751    pub fn init(
1752        slot: &mut MaybeUninit<Self>,
1753        sampling_rate: i32,
1754        channels: usize,
1755    ) -> Result<&mut Self, &'static str> {
1756        if ![8000, 12000, 16000, 24000, 48000].contains(&sampling_rate) {
1757            return Err("Invalid sampling rate");
1758        }
1759        if ![1, 2].contains(&channels) {
1760            return Err("Invalid number of channels");
1761        }
1762
1763        let mode = modes::default_mode();
1764        let this = slot.as_mut_ptr();
1765        unsafe {
1766            #[cfg(feature = "heap")]
1767            {
1768                (&raw mut (*this).celt_dec).write(Box::new(CeltDecoder::new(mode, channels, sampling_rate)));
1769                (&raw mut (*this).silk_dec).write(Box::new(silk::dec_api::SilkDecoder::new()));
1770            }
1771            #[cfg(not(feature = "heap"))]
1772            {
1773                CeltDecoder::write_new(&raw mut (*this).celt_dec, mode, channels, sampling_rate);
1774                silk::dec_api::SilkDecoder::write_new(&raw mut (*this).silk_dec);
1775            }
1776            (&raw mut (*this).sampling_rate).write(sampling_rate);
1777            (&raw mut (*this).channels).write(channels);
1778            (&raw mut (*this).prev_mode).write(None);
1779            (&raw mut (*this).prev_redundancy).write(false);
1780            (&raw mut (*this).frame_size).write(0);
1781            (&raw mut (*this).bandwidth).write(Bandwidth::Auto);
1782            (&raw mut (*this).stream_channels).write(channels);
1783            (&raw mut (*this).silk_resampler).write(silk::resampler::SilkResampler::default());
1784            (&raw mut (*this).silk_resampler_2).write(silk::resampler::SilkResampler::default());
1785            (&raw mut (*this).prev_internal_rate).write(0);
1786            (&raw mut (*this).hybrid_skip_celt).write(false);
1787            #[cfg(feature = "heap")]
1788            {
1789                (&raw mut (*this).w_pcm_i16).write(Box::new(FixedVec::from_value(0i16, 960 * channels)));
1790                (&raw mut (*this).w_silk_out).write(Box::new(FixedVec::from_value(0.0f32, OPUS_MAX_SUBFRAME * channels)));
1791                (&raw mut (*this).w_pcm_resampled).write(Box::new(FixedVec::from_value(0i16, OPUS_MAX_SUBFRAME * channels)));
1792                (&raw mut (*this).w_celt_planar).write(Box::new(FixedVec::from_value(0.0f32, OPUS_MAX_SUBFRAME * channels)));
1793                (&raw mut (*this).w_celt_out).write(Box::new(FixedVec::from_value(0.0f32, OPUS_MAX_SUBFRAME * channels)));
1794                (&raw mut (*this).prev_pcm_tail).write(Box::new(FixedVec::from_value(0.0f32, 240 * channels)));
1795            }
1796            #[cfg(not(feature = "heap"))]
1797            {
1798                FixedVec::write_from_value(&raw mut (*this).w_pcm_i16, 0i16, 960 * channels);
1799                FixedVec::write_from_value(&raw mut (*this).w_silk_out, 0.0f32, OPUS_MAX_SUBFRAME * channels);
1800                FixedVec::write_from_value(&raw mut (*this).w_pcm_resampled, 0i16, OPUS_MAX_SUBFRAME * channels);
1801                FixedVec::write_from_value(&raw mut (*this).w_celt_planar, 0.0f32, OPUS_MAX_SUBFRAME * channels);
1802                FixedVec::write_from_value(&raw mut (*this).w_celt_out, 0.0f32, OPUS_MAX_SUBFRAME * channels);
1803                FixedVec::write_from_value(&raw mut (*this).prev_pcm_tail, 0.0f32, 240 * channels);
1804            }
1805        }
1806
1807        let decoder = unsafe { slot.assume_init_mut() };
1808        decoder.silk_dec.init(sampling_rate.min(16000), channels as i32);
1809        decoder.silk_dec.channel_state[0].fs_api_hz = sampling_rate;
1810        Ok(decoder)
1811    }
1812
1813    /// Decode one Opus packet into interleaved `f32` PCM, returning the
1814    /// number of samples per channel written.
1815    ///
1816    /// Packet loss follows libopus: pass an empty packet (`&[]`) to conceal
1817    /// `frame_size` samples (a multiple of 2.5 ms), or a ToC-only 1-byte
1818    /// packet to conceal the duration that ToC describes. Either way the
1819    /// frame is concealed in the previous packet's mode; the placeholder's
1820    /// mode, bandwidth and channel bits are ignored.
1821    ///
1822    /// A packet's channel count need not match the decoder's, as in libopus:
1823    /// a stereo decoder plays a mono packet on both channels, and a mono
1824    /// decoder downmixes a stereo packet (SILK plays the mid). libopus
1825    /// encoders send mono packets in stereo streams at low bitrates.
1826    pub fn decode(
1827        &mut self,
1828        input: &[u8],
1829        frame_size: usize,
1830        output: &mut [f32],
1831    ) -> Result<usize, &'static str> {
1832        // A packet of 0 or 1 bytes (ToC only) is a lost/DTX frame: conceal it
1833        // in the previous mode without touching the mode state (issue #15).
1834        if input.len() <= 1 {
1835            return self.decode_lost(input.first().copied(), frame_size, output);
1836        }
1837
1838        let toc = input[0];
1839        let mode = mode_from_toc(toc);
1840        let packet_channels = channels_from_toc(toc);
1841        let bandwidth = bandwidth_from_toc(toc);
1842        let frame_duration_ms = frame_duration_ms_from_toc(toc);
1843
1844        let frame_payloads = frame_payloads(input)?;
1845        let frame_count = frame_payloads.len();
1846
1847        self.frame_size = frame_size;
1848        self.bandwidth = bandwidth;
1849
1850        // Derive the actual per-frame sample count from the TOC, not from the
1851        // caller's frame_size. This prevents panics in bands.rs/celt.rs when
1852        // the caller passes a mismatched frame_size (issue #7 sub-item 1):
1853        // the internal decoders always get the correct geometry.
1854        let toc_frame_size = frame_samples_from_toc(toc, self.sampling_rate)
1855            .ok_or("Invalid TOC for sampling rate")?;
1856        let decoded_total = toc_frame_size * frame_count;
1857        if frame_size < decoded_total {
1858            return Err("frame_size too small for packet");
1859        }
1860        if output.len() < decoded_total * self.channels {
1861            return Err("Output buffer too small for packet");
1862        }
1863        // The packet's channel count steers both layers from here on.
1864        self.stream_channels = packet_channels;
1865        self.celt_dec.set_stream_channels(packet_channels);
1866        // Zero-fill any extra space the caller provided beyond what the packet
1867        // actually produces, so stale data is never left in the buffer.
1868        if output.len() > decoded_total * self.channels {
1869            for v in &mut output[decoded_total * self.channels..] {
1870                *v = 0.0;
1871            }
1872        }
1873        let sub_frame_size = toc_frame_size;
1874        let sub_output_len = sub_frame_size * self.channels;
1875
1876        // Detect mode transition and reset CELT decoder state to prevent
1877        // cross-mode artifacts (libopus opus_decoder.c:602-604).
1878        // This is the primary fix for issue #8/#9 alignment divergence:
1879        // stale CELT MDCT/prefilter state at SILK↔CELT boundaries causes
1880        // discontinuities that accumulate across transitions.
1881        let mode_transition = matches!(
1882            self.prev_mode,
1883            Some(prev) if prev != mode && !self.prev_redundancy
1884        );
1885        // The transitions libopus's opus_decode_frame bridges with 5 ms of the old mode concealed
1886        // forward: into CELT from SILK or Hybrid (unless that frame's redundancy did it), and out of CELT. A Hybrid
1887        // frame carrying redundancy clears it below (libopus: `if (redundancy) transition = 0`).
1888        let mut transition = match self.prev_mode {
1889            Some(prev) => {
1890                (mode == OpusMode::CeltOnly && prev != OpusMode::CeltOnly && !self.prev_redundancy)
1891                    || (mode != OpusMode::CeltOnly && prev == OpusMode::CeltOnly)
1892            }
1893            None => false,
1894        };
1895        let from_celt = self.prev_mode == Some(OpusMode::CeltOnly) && mode != OpusMode::CeltOnly;
1896        if from_celt {
1897            // SILK starts over, as libopus's silk_ResetDecoder on a switch from CELT (its resampler too: the reset
1898            // clears the SILK rate, so the next set_fs initialises it again).
1899            self.silk_dec.reset();
1900            self.prev_internal_rate = 0;
1901        }
1902        // A SILK-only frame decides its out-of-CELT bridge only after its SILK
1903        // layer runs: when the frame carries a redundancy tail there is nothing
1904        // to bridge (libopus: `if (redundancy) transition = 0`), and without one
1905        // the old CELT state conceals forward from inside the branch below.
1906        // Only a switch into CELT resets CELT here (libopus's reset at
1907        // opus_decode_frame 551-553 sits inside `mode != MODE_SILK_ONLY`): a
1908        // Hybrid frame resets it after its CELT-to-SILK redundant frame is
1909        // decoded from the old state, and a SILK-only frame resets it right
1910        // before its own redundant frame, if it carries one.
1911        if mode_transition && mode == OpusMode::CeltOnly {
1912            self.celt_dec.reset_state();
1913        }
1914
1915        // Generate SILK PLC audio for the mode-transition bridge. libopus
1916        // synthesizes 5ms (F5) of pitch-extrapolated audio in the OLD mode
1917        // (opus_decoder.c:387-391) and crossfades it with the new frame. We
1918        // reuse the F5-sized prev_pcm_tail buffer for this bridge.
1919        let f5_bridge = self.sampling_rate as usize / 200; // F5 = Fs/200
1920        if transition
1921            && mode == OpusMode::CeltOnly
1922            && f5_bridge > 0
1923            && matches!(
1924                self.prev_mode,
1925                Some(OpusMode::SilkOnly) | Some(OpusMode::Hybrid)
1926            )
1927            && self.prev_internal_rate > 0
1928        {
1929            let internal_rate = self.prev_internal_rate;
1930            let plc_internal_len = (10 * internal_rate / 1000) as usize;
1931            let mut plc_rc = RangeCoder::new_decoder(&[]);
1932            let mut plc_i16: FixedVec<i16, OPUS_PCM_I16> =
1933                FixedVec::from_value(0i16, plc_internal_len * self.channels);
1934            let n = self.silk_dec.decode(
1935                &mut plc_rc,
1936                &mut plc_i16,
1937                silk::decode_frame::FLAG_PACKET_LOST,
1938                true,
1939                10,
1940                internal_rate,
1941            );
1942            if n > 0 {
1943                let bridge_ch = f5_bridge * self.channels;
1944                let bridge_len = bridge_ch.min(self.prev_pcm_tail.len());
1945                if internal_rate == self.sampling_rate {
1946                    // No resampling: copy PLC samples directly (planar). A
1947                    // mono stream fills both channels of a stereo decoder.
1948                    let n_us = n as usize;
1949                    let silk_channels = self
1950                        .channels
1951                        .min(self.silk_dec.n_channels_internal as usize);
1952                    for ch in 0..self.channels {
1953                        let src_base = ch.min(silk_channels - 1) * n_us;
1954                        for i in 0..(bridge_len / self.channels).min(n_us) {
1955                            let dst = i * self.channels + ch;
1956                            if dst < bridge_len {
1957                                self.prev_pcm_tail[dst] = plc_i16[src_base + i] as f32 / 32768.0;
1958                            }
1959                        }
1960                    }
1961                } else if self.silk_resampler.is_initialized() {
1962                    // Resample channel 0 to the API rate for the bridge.
1963                    // The resampler must receive an output buffer sized for the
1964                    // FULL resampled length (issue #15): truncating the buffer to
1965                    // `f5_bridge` caused out-of-bounds writes in the Up2HQ/Copy
1966                    // paths. We size it fully, then copy only the bridge window.
1967                    let ratio = self.sampling_rate as f64 / internal_rate as f64;
1968                    let full_len = ((n as f64 * ratio) as usize).max(1);
1969                    let out_len = full_len.min(f5_bridge);
1970                    let n_us = n as usize;
1971                    let mut resampled: FixedVec<i16, OPUS_MAX_FRAME> =
1972                        FixedVec::from_value(0i16, full_len);
1973                    self.silk_resampler
1974                        .process(&mut resampled, &plc_i16[..n_us], n);
1975                    for i in 0..out_len {
1976                        if i < bridge_len / self.channels {
1977                            for ch in 0..self.channels {
1978                                self.prev_pcm_tail[i * self.channels + ch] =
1979                                    resampled[i] as f32 / 32768.0;
1980                            }
1981                        }
1982                    }
1983                }
1984            }
1985        }
1986
1987        // Track whether this packet uses Hybrid redundancy.
1988        let mut has_redundancy = false;
1989
1990        match mode {
1991            OpusMode::SilkOnly => {
1992                let internal_sample_rate = match bandwidth {
1993                    Bandwidth::Narrowband => 8000,
1994                    Bandwidth::Mediumband => 12000,
1995                    Bandwidth::Wideband => 16000,
1996                    _ => 16000,
1997                };
1998                if internal_sample_rate != self.prev_internal_rate
1999                    || !self.silk_resampler.is_initialized()
2000                {
2001                    self.silk_resampler
2002                        .init(internal_sample_rate, self.sampling_rate);
2003                    self.silk_resampler_2
2004                        .init(internal_sample_rate, self.sampling_rate);
2005                }
2006                // Always track the SILK internal rate so the mode-transition
2007                // PLC bridge can be generated (even when no resampling is
2008                // needed, e.g. 16kHz decoder + SILK WB).
2009                self.prev_internal_rate = internal_sample_rate;
2010
2011                // 5 ms redundant frames and their crossfade window, shared by
2012                // every frame of the packet. The redundant frame ends where
2013                // the packet's bandwidth does (libopus 499-524): narrowband
2014                // 13, mediumband and wideband 17.
2015                let f5 = self.sampling_rate as usize / 200;
2016                let f2_5 = f5 / 2;
2017                let redundant_end_band = match bandwidth {
2018                    Bandwidth::Narrowband => 13,
2019                    Bandwidth::Mediumband | Bandwidth::Wideband => 17,
2020                    _ => 21,
2021                };
2022                let window = modes::default_mode().window;
2023                let inc = (48000 / self.sampling_rate) as usize;
2024
2025                for (fi, payload) in frame_payloads.iter().enumerate() {
2026                    let out_start = fi * sub_output_len;
2027                    // C opus_decode_frame: a zero-length frame (e.g. the
2028                    // encoder's busted-budget fallback packet) is concealed,
2029                    // not decoded.
2030                    let flag = if payload.is_empty() {
2031                        silk::decode_frame::FLAG_PACKET_LOST
2032                    } else {
2033                        silk::decode_frame::FLAG_DECODE_NORMAL
2034                    };
2035                    let mut rc = RangeCoder::new_decoder(payload);
2036                    self.decode_silk_frames(
2037                        &mut rc,
2038                        flag,
2039                        frame_duration_ms,
2040                        internal_sample_rate,
2041                        sub_frame_size,
2042                    )?;
2043                    output[out_start..out_start + sub_output_len]
2044                        .copy_from_slice(&self.w_silk_out[..sub_output_len]);
2045
2046                    // A SILK-only frame's redundancy is implicit (libopus
2047                    // opus_decode_frame 452-479): no flag is coded — when bits
2048                    // are left for it, redundancy is on, `celt_to_silk` reads
2049                    // as one bit, and the frame's tail past the SILK layer is
2050                    // a 5 ms redundant CELT frame. Going to CELT it decodes
2051                    // from a reset CELT state — which the next CELT frame
2052                    // carries on — and its second half fades into the frame's
2053                    // last 2.5 ms (595-603). Coming from CELT it decodes from
2054                    // the old state, opens the frame and fades into its first
2055                    // 5 ms (608-617). Only the SILK-to-CELT direction counts
2056                    // as `prev_redundancy` (657), which spares the next frame
2057                    // its transition bridge and CELT reset (346-352, 551-553).
2058                    let len = payload.len();
2059                    let mut redundancy_bytes = 0usize;
2060                    let mut celt_to_silk = false;
2061                    let mut redundant = [0.0f32; REDUNDANT_MAX];
2062                    let has_tail = !payload.is_empty() && rc.tell() + 17 <= (8 * len) as i32;
2063                    if has_tail {
2064                        celt_to_silk = rc.decode_bit_logp(1);
2065                        // The tail is everything the SILK layer left:
2066                        // `redundancy_bytes = len - ceil(ec_tell/8)`.
2067                        redundancy_bytes = len - ((rc.tell() as usize + 7) >> 3);
2068                        // Keep the main range coder in sync, as libopus's
2069                        // `dec.storage -= redundancy_bytes`.
2070                        rc.storage -= redundancy_bytes as u32;
2071                        if celt_to_silk {
2072                            // From the old CELT state, before any reset — a
2073                            // CELT-to-SILK switch's bridge (532-541).
2074                            self.decode_redundant(
2075                                &payload[len - redundancy_bytes..],
2076                                redundant_end_band,
2077                                f5,
2078                                &mut redundant,
2079                            );
2080                        }
2081                    }
2082                    if fi == 0 {
2083                        if has_tail {
2084                            // libopus: `if (redundancy) transition = 0`.
2085                            transition = false;
2086                        } else if from_celt {
2087                            // Without a tail there is nothing to fade into:
2088                            // bridge out of CELT with 5 ms of the old CELT
2089                            // state concealed forward (libopus's
2090                            // `pcm_transition`), not the previous frame's last
2091                            // 5 ms, which already played.
2092                            self.conceal_celt_bridge()?;
2093                        }
2094                    }
2095                    let ch = self.channels;
2096                    if has_tail && !celt_to_silk && f5 > 0 && sub_output_len >= f5 * ch {
2097                        // SILK to CELT: reset CELT, decode the redundant frame
2098                        // with all bands from that fresh state — the next CELT
2099                        // frame carries it on — and fade its second half into
2100                        // the frame's last 2.5 ms (595-603).
2101                        self.celt_dec.reset_state();
2102                        self.decode_redundant(
2103                            &payload[len - redundancy_bytes..],
2104                            redundant_end_band,
2105                            f5,
2106                            &mut redundant,
2107                        );
2108                        let at = out_start + (sub_frame_size - f2_5) * ch;
2109                        let mut tail = [0.0f32; REDUNDANT_MAX];
2110                        tail[..f2_5 * ch].copy_from_slice(&output[at..at + f2_5 * ch]);
2111                        smooth_fade(
2112                            &tail[..f2_5 * ch],
2113                            &redundant[f2_5 * ch..f5 * ch],
2114                            &mut output[at..at + f2_5 * ch],
2115                            f2_5,
2116                            ch,
2117                            window,
2118                            inc,
2119                        );
2120                    } else if has_tail
2121                        && celt_to_silk
2122                        && (self.prev_mode != Some(OpusMode::SilkOnly) || self.prev_redundancy)
2123                        && f5 > 0
2124                        && sub_output_len >= f5 * ch
2125                    {
2126                        // CELT to SILK: the redundant frame opens this one and
2127                        // fades into its first 5 ms (608-617). It is ignored
2128                        // when the CELT state it came from is stale (606-608).
2129                        output[out_start..out_start + f2_5 * ch]
2130                            .copy_from_slice(&redundant[..f2_5 * ch]);
2131                        let at = out_start + f2_5 * ch;
2132                        let mut next = [0.0f32; REDUNDANT_MAX];
2133                        next[..f2_5 * ch].copy_from_slice(&output[at..at + f2_5 * ch]);
2134                        smooth_fade(
2135                            &redundant[f2_5 * ch..f5 * ch],
2136                            &next[..f2_5 * ch],
2137                            &mut output[at..at + f2_5 * ch],
2138                            f2_5,
2139                            ch,
2140                            window,
2141                            inc,
2142                        );
2143                    }
2144                    has_redundancy = has_tail && !celt_to_silk;
2145                }
2146                decoded_total
2147            }
2148
2149            OpusMode::CeltOnly => {
2150                let celt_end_band = self.celt_end_band_from_toc(toc);
2151
2152                for (fi, payload) in frame_payloads.iter().enumerate() {
2153                    let mut rc = RangeCoder::new_decoder(payload);
2154                    let total_bits = (payload.len() * 8) as i32;
2155                    let needed = sub_frame_size * self.channels;
2156                    let out_start = fi * needed;
2157                    let out_end = (out_start + needed).min(output.len());
2158
2159                    if output.len() < out_end {
2160                        return Err("Output buffer too small");
2161                    }
2162
2163                    if self.channels == 1 {
2164                        self.celt_dec.decode_from_range_coder_with_band_range(
2165                            &mut rc,
2166                            total_bits,
2167                            sub_frame_size,
2168                            &mut output[out_start..out_end],
2169                            0,
2170                            celt_end_band,
2171                        );
2172                        for sample in &mut output[out_start..out_end] {
2173                            *sample = sample.clamp(-1.0, 1.0);
2174                        }
2175                    } else {
2176                        self.celt_dec.decode_from_range_coder_with_band_range(
2177                            &mut rc,
2178                            total_bits,
2179                            sub_frame_size,
2180                            &mut self.w_celt_planar[..needed],
2181                            0,
2182                            celt_end_band,
2183                        );
2184                        for i in 0..sub_frame_size {
2185                            for ch in 0..self.channels {
2186                                let idx = out_start + i * self.channels + ch;
2187                                output[idx] =
2188                                    self.w_celt_planar[ch * sub_frame_size + i].clamp(-1.0, 1.0);
2189                            }
2190                        }
2191                    }
2192                }
2193                decoded_total
2194            }
2195
2196            OpusMode::Hybrid => {
2197                let internal_sample_rate = 16000;
2198                let celt_end_band = self.celt_end_band_from_toc(toc);
2199
2200                if internal_sample_rate != self.prev_internal_rate
2201                    || !self.silk_resampler.is_initialized()
2202                {
2203                    self.silk_resampler
2204                        .init(internal_sample_rate, self.sampling_rate);
2205                    self.silk_resampler_2
2206                        .init(internal_sample_rate, self.sampling_rate);
2207                }
2208                self.prev_internal_rate = internal_sample_rate;
2209
2210                for (fi, payload) in frame_payloads.iter().enumerate() {
2211                    let mut rc = RangeCoder::new_decoder(payload);
2212                    // SILK layer of this frame -> w_silk_out (interleaved, API rate).
2213                    // A zero-length frame is concealed, not decoded (C
2214                    // opus_decode_frame).
2215                    let flag = if payload.is_empty() {
2216                        silk::decode_frame::FLAG_PACKET_LOST
2217                    } else {
2218                        silk::decode_frame::FLAG_DECODE_NORMAL
2219                    };
2220                    self.decode_silk_frames(
2221                        &mut rc,
2222                        flag,
2223                        frame_duration_ms,
2224                        internal_sample_rate,
2225                        sub_frame_size,
2226                    )?;
2227                    let silk_out_len = sub_frame_size * self.channels;
2228
2229                    // A mode switch's redundancy (RFC 6716 §4.5.1; libopus
2230                    // opus_decode_frame): after the SILK layer, when enough bits
2231                    // are left, a flag; if set, which way the switch goes and the
2232                    // size of a 5 ms CELT frame carried at the packet's end. The
2233                    // main CELT layer reads only the bytes before it; the
2234                    // redundant frame is decoded on its own and crossfaded in
2235                    // below.
2236                    let mut len = payload.len();
2237                    let mut redundancy = false;
2238                    let mut celt_to_silk = false;
2239                    let mut redundancy_bytes = 0usize;
2240                    if !payload.is_empty() && rc.tell() + 17 + 20 <= (8 * len) as i32 {
2241                        redundancy = rc.decode_bit_logp(12);
2242                        if redundancy {
2243                            celt_to_silk = rc.decode_bit_logp(1);
2244                            redundancy_bytes = rc.dec_uint(256) as usize + 2;
2245                            if redundancy_bytes > len
2246                                || ((len - redundancy_bytes) * 8) < rc.tell() as usize
2247                            {
2248                                len = 0;
2249                                redundancy_bytes = 0;
2250                                redundancy = false;
2251                            } else {
2252                                len -= redundancy_bytes;
2253                                rc.storage -= redundancy_bytes as u32;
2254                            }
2255                        }
2256                    }
2257                    // libopus remembers only a SILK-to-CELT frame's redundancy (`prev_redundancy = redundancy &&
2258                    // !celt_to_silk`).
2259                    has_redundancy = redundancy && !celt_to_silk;
2260                    let f5 = self.sampling_rate as usize / 200;
2261                    let f2_5 = f5 / 2;
2262                    let mut redundant = [0.0f32; REDUNDANT_MAX];
2263                    if fi == 0 {
2264                        if redundancy {
2265                            transition = false;
2266                        } else if from_celt {
2267                            self.conceal_celt_bridge()?;
2268                        }
2269                    }
2270                    if redundancy && celt_to_silk {
2271                        self.decode_redundant(
2272                            &payload[len..len + redundancy_bytes],
2273                            celt_end_band,
2274                            f5,
2275                            &mut redundant,
2276                        );
2277                    }
2278                    if fi == 0 && mode_transition {
2279                        self.celt_dec.reset_state();
2280                    }
2281
2282                    let total_bits = (len * 8) as i32;
2283                    if len <= 1 {
2284                        self.w_celt_out[..silk_out_len].fill(0.0);
2285                    } else {
2286                        let (celt_dec, celt_planar) = (
2287                            state_mut(&mut self.celt_dec),
2288                            state_mut(&mut self.w_celt_planar),
2289                        );
2290                        celt_dec.decode_from_range_coder_with_band_range(
2291                            &mut rc,
2292                            total_bits,
2293                            sub_frame_size,
2294                            &mut celt_planar[..silk_out_len],
2295                            17,
2296                            celt_end_band,
2297                        );
2298
2299                        if self.channels == 1 {
2300                            self.w_celt_out[..silk_out_len]
2301                                .copy_from_slice(&self.w_celt_planar[..silk_out_len]);
2302                        } else {
2303                            for i in 0..sub_frame_size {
2304                                for ch in 0..self.channels {
2305                                    self.w_celt_out[i * self.channels + ch] =
2306                                        self.w_celt_planar[ch * sub_frame_size + i];
2307                                }
2308                            }
2309                        }
2310                    }
2311
2312                    let out_start = fi * silk_out_len;
2313                    let total = silk_out_len.min(output.len() - out_start);
2314                    for j in 0..total {
2315                        output[out_start + j] =
2316                            (self.w_silk_out[j] + self.w_celt_out[j]).clamp(-1.0, 1.0);
2317                    }
2318
2319                    // The redundant frame crossfaded in (libopus
2320                    // opus_decode_frame): going SILK to CELT, the frame's last
2321                    // 2.5 ms fade into its second half (decoded from a fresh CELT
2322                    // state, which the next CELT frame then carries on from);
2323                    // going CELT to SILK, its first half opens the frame and its
2324                    // second half fades into the frame's next 2.5 ms.
2325                    let ch = self.channels;
2326                    let use_redundant = !celt_to_silk
2327                        || self.prev_mode != Some(OpusMode::SilkOnly)
2328                        || self.prev_redundancy;
2329                    if redundancy && use_redundant && f5 > 0 && total >= f5 * ch {
2330                        let window = modes::default_mode().window;
2331                        let inc = (48000 / self.sampling_rate) as usize;
2332                        if !celt_to_silk {
2333                            self.celt_dec.reset_state();
2334                            self.decode_redundant(
2335                                &payload[len..len + redundancy_bytes],
2336                                celt_end_band,
2337                                f5,
2338                                &mut redundant,
2339                            );
2340                            let at = out_start + (sub_frame_size - f2_5) * ch;
2341                            let mut tail = [0.0f32; REDUNDANT_MAX];
2342                            tail[..f2_5 * ch].copy_from_slice(&output[at..at + f2_5 * ch]);
2343                            smooth_fade(
2344                                &tail[..f2_5 * ch],
2345                                &redundant[f2_5 * ch..f5 * ch],
2346                                &mut output[at..at + f2_5 * ch],
2347                                f2_5,
2348                                ch,
2349                                window,
2350                                inc,
2351                            );
2352                        } else {
2353                            output[out_start..out_start + f2_5 * ch]
2354                                .copy_from_slice(&redundant[..f2_5 * ch]);
2355                            let at = out_start + f2_5 * ch;
2356                            let mut next = [0.0f32; REDUNDANT_MAX];
2357                            next[..f2_5 * ch].copy_from_slice(&output[at..at + f2_5 * ch]);
2358                            smooth_fade(
2359                                &redundant[f2_5 * ch..f5 * ch],
2360                                &next[..f2_5 * ch],
2361                                &mut output[at..at + f2_5 * ch],
2362                                f2_5,
2363                                ch,
2364                                window,
2365                                inc,
2366                            );
2367                        }
2368                    }
2369                }
2370                decoded_total
2371            }
2372        };
2373
2374        // Apply PLC-style bridging at mode transitions (libopus
2375        // opus_decoder.c:660-679). The first F2_5 of the output is replaced
2376        // with the previous frame's tail (PLC bridge), and the next F2_5 is
2377        // crossfaded between the bridge and the new frame's CELT output.
2378        // F5 = Fs/200, F2_5 = Fs/400.
2379        let f2_5 = self.sampling_rate as usize / 400;
2380        let f5 = f2_5 * 2;
2381        if transition && f5 > 0 && decoded_total >= f5 {
2382            let window = modes::default_mode().window;
2383            let inc = (48000 / self.sampling_rate) as usize;
2384            let f2_5_ch = f2_5 * self.channels;
2385            let f5_ch = f5 * self.channels;
2386            // First F2_5: pure bridging audio from previous frame's tail.
2387            output[..f2_5_ch].copy_from_slice(&self.prev_pcm_tail[..f2_5_ch]);
2388            // Next F2_5: crossfade bridge → new CELT output.
2389            let new_mid: FixedVec<f32, OPUS_PCM_TAIL> =
2390                FixedVec::from_slice(&output[f2_5_ch..f5_ch]);
2391            smooth_fade(
2392                &self.prev_pcm_tail[f2_5_ch..f5_ch],
2393                &new_mid,
2394                &mut output[f2_5_ch..f5_ch],
2395                f2_5,
2396                self.channels,
2397                window,
2398                inc,
2399            );
2400        }
2401
2402        self.save_pcm_tail(output, decoded_total);
2403        self.prev_mode = Some(mode);
2404        self.prev_redundancy = has_redundancy;
2405        Ok(decoded_total)
2406    }
2407
2408    /// Rebuild a lost packet from the in-band FEC of the packet after it,
2409    /// into interleaved `f32` PCM, returning the number of samples per
2410    /// channel written (always `frame_size`). This is libopus's
2411    /// `opus_decode(..., decode_fec = 1)`.
2412    ///
2413    /// `input` is the packet that followed the loss. When it is SILK-only or
2414    /// Hybrid and its first frame carries LBRR (the encoder's
2415    /// `use_inband_fec`), the last frame's worth of `frame_size` (one frame
2416    /// of `input`, 10 to 60 ms) is rebuilt from that LBRR, and anything
2417    /// before it is concealed. A SILK frame without LBRR is concealed too,
2418    /// and all of `frame_size` is, as for `decode(&[], frame_size, ..)`, when
2419    /// `input` is CELT-only, follows a CELT packet, or has frames longer than
2420    /// `frame_size`. Hybrid uses only the SILK layer's LBRR, with the CELT
2421    /// layer concealed. `frame_size` is a multiple of 2.5 ms.
2422    ///
2423    /// `input` itself is not consumed: decode it with [`Self::decode`] next.
2424    pub fn decode_fec(
2425        &mut self,
2426        input: &[u8],
2427        frame_size: usize,
2428        output: &mut [f32],
2429    ) -> Result<usize, &'static str> {
2430        if input.len() <= 1 {
2431            return self.decode_lost(None, frame_size, output);
2432        }
2433        let toc = input[0];
2434        let mode = mode_from_toc(toc);
2435        let packet_frame = frame_samples_from_toc(toc, self.sampling_rate)
2436            .ok_or("Invalid TOC for sampling rate")?;
2437        let payloads = frame_payloads(input)?;
2438        // No FEC can be present: conceal it all (opus_decode_native).
2439        if frame_size < packet_frame
2440            || payloads[0].len() <= 1
2441            || mode == OpusMode::CeltOnly
2442            || self.prev_mode == Some(OpusMode::CeltOnly)
2443        {
2444            return self.decode_lost(None, frame_size, output);
2445        }
2446        let channels = self.channels;
2447        if output.len() < frame_size * channels {
2448            return Err("Output buffer too small for packet");
2449        }
2450        // Conceal everything but the duration the packet's FEC covers.
2451        let head = frame_size - packet_frame;
2452        if head > 0 {
2453            self.decode_lost(None, head, output)?;
2454        }
2455
2456        let bandwidth = bandwidth_from_toc(toc);
2457        let packet_channels = channels_from_toc(toc);
2458        self.frame_size = frame_size;
2459        self.bandwidth = bandwidth;
2460        self.stream_channels = packet_channels;
2461        self.celt_dec.set_stream_channels(packet_channels);
2462        let internal_rate = match (mode, bandwidth) {
2463            (OpusMode::SilkOnly, Bandwidth::Narrowband) => 8000,
2464            (OpusMode::SilkOnly, Bandwidth::Mediumband) => 12000,
2465            _ => 16000,
2466        };
2467        if internal_rate != self.prev_internal_rate || !self.silk_resampler.is_initialized() {
2468            self.silk_resampler.init(internal_rate, self.sampling_rate);
2469            self.silk_resampler_2
2470                .init(internal_rate, self.sampling_rate);
2471        }
2472        self.prev_internal_rate = internal_rate;
2473
2474        // The first frame's LBRR, frame by frame; a SILK frame without LBRR
2475        // is concealed (silk_decode_frame).
2476        let mut rc = RangeCoder::new_decoder(payloads[0]);
2477        self.decode_silk_frames(
2478            &mut rc,
2479            silk::decode_frame::FLAG_DECODE_LBRR,
2480            frame_duration_ms_from_toc(toc),
2481            internal_rate,
2482            packet_frame,
2483        )?;
2484        let len = packet_frame * channels;
2485        if mode == OpusMode::Hybrid {
2486            // FEC never reads the CELT layer: conceal it above SILK's band,
2487            // from a reset state unless the last packet was Hybrid too
2488            // (opus_decode_frame 551-553).
2489            if self.prev_mode.is_some_and(|m| m != OpusMode::Hybrid) && !self.prev_redundancy {
2490                self.celt_dec.reset_state();
2491            }
2492            self.conceal_celt(packet_frame, 17)?;
2493        } else {
2494            self.w_celt_out[..len].fill(0.0);
2495        }
2496        let tail = &mut output[head * channels..frame_size * channels];
2497        for (i, d) in tail.iter_mut().enumerate() {
2498            *d = (self.w_silk_out[i] + self.w_celt_out[i]).clamp(-1.0, 1.0);
2499        }
2500        output[frame_size * channels..].fill(0.0);
2501
2502        self.save_pcm_tail(output, frame_size);
2503        self.prev_mode = Some(mode);
2504        self.prev_redundancy = false;
2505        Ok(frame_size)
2506    }
2507
2508    /// Conceal a lost frame (libopus `opus_decode_frame` with `data == NULL`).
2509    ///
2510    /// Only the duration comes from the caller: the placeholder ToC of a
2511    /// 1-byte packet, or `frame_size` for an empty one. Mode, bandwidth, SILK
2512    /// rate and resamplers stay the previous packet's, so a placeholder such
2513    /// as `[0]` (SILK NB 10 ms) can no longer switch a CELT or wideband stream
2514    /// into another mode and fake two mode transitions (issue #15).
2515    fn decode_lost(
2516        &mut self,
2517        toc: Option<u8>,
2518        frame_size: usize,
2519        output: &mut [f32],
2520    ) -> Result<usize, &'static str> {
2521        let f2_5 = self.sampling_rate as usize / 400;
2522        let (f5, f10, f20) = (2 * f2_5, 4 * f2_5, 8 * f2_5);
2523
2524        let total = match toc {
2525            None => {
2526                if frame_size == 0 || !frame_size.is_multiple_of(f2_5) {
2527                    return Err("Lost frame: frame_size must be a multiple of 2.5 ms");
2528                }
2529                frame_size
2530            }
2531            Some(toc) => {
2532                // A ToC-only packet: code 0 is one empty frame, codes 1 and 2
2533                // are two; code 3 lacks its frame-count byte (libopus rejects).
2534                let count = match toc & 0x03 {
2535                    0 => 1,
2536                    1 | 2 => 2,
2537                    _ => return Err("Code 3 packet too short"),
2538                };
2539                let per_frame = frame_samples_from_toc(toc, self.sampling_rate)
2540                    .ok_or("Invalid TOC for sampling rate")?;
2541                let total = per_frame * count;
2542                if frame_size < total {
2543                    return Err("frame_size too small for packet");
2544                }
2545                total
2546            }
2547        };
2548        let channels = self.channels;
2549        if output.len() < total * channels {
2550            return Err("Output buffer too small for packet");
2551        }
2552        output[total * channels..].fill(0.0);
2553
2554        let mut pos = 0usize;
2555        while pos < total {
2556            let remaining = total - pos;
2557            let dst = &mut output[pos * channels..total * channels];
2558            let produced = match self.prev_mode {
2559                None => {
2560                    dst.fill(0.0);
2561                    remaining
2562                }
2563                Some(OpusMode::CeltOnly) => {
2564                    // Largest CELT frame that fits; `remaining` is a multiple
2565                    // of 2.5 ms, so one always does.
2566                    let n = [f20, f10, f5, f2_5]
2567                        .into_iter()
2568                        .find(|&c| c <= remaining)
2569                        .unwrap_or(f2_5);
2570                    self.conceal_celt(n, 0)?;
2571                    for (d, s) in dst.iter_mut().zip(&self.w_celt_out[..n * channels]) {
2572                        *d = s.clamp(-1.0, 1.0);
2573                    }
2574                    n
2575                }
2576                Some(prev @ (OpusMode::SilkOnly | OpusMode::Hybrid)) => {
2577                    // SILK conceals in 10/20 ms frames; a shorter request
2578                    // takes the head of a 10 ms frame, as libopus does.
2579                    let (ms, n) = if remaining >= f20 {
2580                        (20, f20)
2581                    } else {
2582                        (10, f10)
2583                    };
2584                    let hybrid = prev == OpusMode::Hybrid;
2585                    let rate = if hybrid {
2586                        16000
2587                    } else {
2588                        self.prev_internal_rate
2589                    };
2590                    let mut rc = RangeCoder::new_decoder(&[]);
2591                    self.decode_silk_frames(
2592                        &mut rc,
2593                        silk::decode_frame::FLAG_PACKET_LOST,
2594                        ms,
2595                        rate,
2596                        n,
2597                    )?;
2598                    if hybrid {
2599                        self.conceal_celt(n, 17)?;
2600                    } else {
2601                        self.w_celt_out[..n * channels].fill(0.0);
2602                    }
2603                    let take = n.min(remaining);
2604                    for (i, d) in dst[..take * channels].iter_mut().enumerate() {
2605                        *d = (self.w_silk_out[i] + self.w_celt_out[i]).clamp(-1.0, 1.0);
2606                    }
2607                    take
2608                }
2609            };
2610            pos += produced;
2611        }
2612
2613        self.save_pcm_tail(output, total);
2614        Ok(total)
2615    }
2616
2617    /// 5 ms of the old CELT state concealed forward, the bridge out of CELT (libopus
2618    /// opus_decode_frame's `pcm_transition`), into `prev_pcm_tail`.
2619    fn conceal_celt_bridge(&mut self) -> Result<(), &'static str> {
2620        let f5 = self.sampling_rate as usize / 200;
2621        if f5 == 0 {
2622            return Ok(());
2623        }
2624        self.conceal_celt(f5, 0)?;
2625        let n = (f5 * self.channels).min(self.prev_pcm_tail.len());
2626        for i in 0..n {
2627            self.prev_pcm_tail[i] = self.w_celt_out[i].clamp(-1.0, 1.0);
2628        }
2629        Ok(())
2630    }
2631
2632    /// CELT concealment for `n` samples from band `start_band` (libopus
2633    /// `celt_decode_lost`): pitch repetition or noise, decaying. Output lands
2634    /// interleaved in `w_celt_out[..n * channels]`.
2635    fn conceal_celt(&mut self, n: usize, start_band: usize) -> Result<(), &'static str> {
2636        let len = n * self.channels;
2637        let decoded = {
2638            let (celt_dec, planar) = (
2639                state_mut(&mut self.celt_dec),
2640                state_mut(&mut self.w_celt_planar),
2641            );
2642            celt_dec.decode_lost(n, &mut planar[..len], start_band)
2643        };
2644        if decoded != n {
2645            return Err("CELT concealment failed");
2646        }
2647        for i in 0..n {
2648            for ch in 0..self.channels {
2649                self.w_celt_out[i * self.channels + ch] = self.w_celt_planar[ch * n + i];
2650            }
2651        }
2652        Ok(())
2653    }
2654
2655    /// Keep the last F5 of output for the next mode-transition bridge.
2656    fn save_pcm_tail(&mut self, output: &[f32], decoded: usize) {
2657        let tail_len = (self.sampling_rate as usize / 200) * self.channels;
2658        let out_total = decoded * self.channels;
2659        if out_total >= tail_len && tail_len <= self.prev_pcm_tail.len() {
2660            self.prev_pcm_tail[..tail_len]
2661                .copy_from_slice(&output[out_total - tail_len..out_total]);
2662        }
2663    }
2664}
2665
2666impl OpusDecoder {
2667    /// Decode one Opus frame of SILK audio — `duration_ms` at `internal_rate`
2668    /// — into `w_silk_out[..api_len * channels]`, interleaved at the API rate.
2669    ///
2670    /// A 40/60 ms payload carries 2/3 internal SILK frames in one range-coded
2671    /// stream; libopus loops silk_Decode until the full duration is produced,
2672    /// with new_packet set only on the first call (issue #27). With
2673    /// `FLAG_PACKET_LOST` the same loop drives SILK packet-loss concealment.
2674    fn decode_silk_frames(
2675        &mut self,
2676        rc: &mut RangeCoder,
2677        lost_flag: i32,
2678        duration_ms: i32,
2679        internal_rate: i32,
2680        api_len: usize,
2681    ) -> Result<(), &'static str> {
2682        let internal_frame_size = (duration_ms * internal_rate / 1000) as usize;
2683        let pcm_i16_len = internal_frame_size * self.channels;
2684        debug_assert!(pcm_i16_len <= self.w_pcm_i16.len());
2685        let out_len = api_len * self.channels;
2686        self.w_silk_out[..out_len].fill(0.0);
2687
2688        let mut frame_pos = 0usize; // internal-rate samples decoded so far
2689        let mut new_packet = true;
2690        while frame_pos < internal_frame_size {
2691            // libopus takes the channel count from the packet only when there
2692            // is data; concealment keeps the last frame's.
2693            let prev_channels = self.silk_dec.n_channels_internal as usize;
2694            let stream_channels = if lost_flag == silk::decode_frame::FLAG_PACKET_LOST {
2695                prev_channels
2696            } else {
2697                self.stream_channels
2698            };
2699            // libopus keeps a resampler per SILK channel (dec_API.c). When a
2700            // stereo decoder's stream turns stereo, the right one starts from
2701            // the left's. The first mono frame after stereo, at an unchanged
2702            // rate, still resamples the right channel with its own; libopus
2703            // resets SILK after CELT, so that frame never follows CELT there.
2704            if self.channels == 2 && stream_channels == 2 && prev_channels == 1 {
2705                self.silk_resampler_2 = self.silk_resampler.clone();
2706            }
2707            let stereo_to_mono = stream_channels == 1
2708                && prev_channels == 2
2709                && internal_rate == self.silk_dec.sample_rate()
2710                && matches!(
2711                    self.prev_mode,
2712                    Some(OpusMode::SilkOnly) | Some(OpusMode::Hybrid)
2713                );
2714            let ret = {
2715                let (silk_dec, pcm_i16) = (
2716                    state_mut(&mut self.silk_dec),
2717                    state_mut(&mut self.w_pcm_i16),
2718                );
2719                silk_dec.decode_with_channels(
2720                    rc,
2721                    &mut pcm_i16[..pcm_i16_len],
2722                    lost_flag,
2723                    new_packet,
2724                    duration_ms,
2725                    internal_rate,
2726                    stream_channels as i32,
2727                )
2728            };
2729            new_packet = false;
2730
2731            if ret < 0 {
2732                return Err("SILK decoding failed");
2733            }
2734            let decoded_samples = ret as usize;
2735            if decoded_samples == 0 {
2736                break;
2737            }
2738
2739            // SILK decoder outputs planar for THIS frame:
2740            // ch0 at [0..fl], ch1 at [fl..2*fl].
2741            //
2742            // libopus always runs `silk_resampler`, even when the API and SILK
2743            // internal rates are equal: the Copy path still carries the
2744            // resampler's `inputDelay` (12 samples at 16k, 4 at 8k). Bypassing
2745            // it made equal-rate SILK output early versus libopus (and versus
2746            // opus-rs's own resampled paths).
2747            let resampled_len =
2748                decoded_samples * self.sampling_rate as usize / internal_rate as usize;
2749            let api_pos = frame_pos * self.sampling_rate as usize / internal_rate as usize;
2750            let copy_len = resampled_len.min(api_len - api_pos);
2751            debug_assert!(resampled_len * self.channels <= self.w_pcm_resampled.len());
2752            // Resample channel 0.
2753            {
2754                let (res, inp, out) = (
2755                    &mut self.silk_resampler,
2756                    state_ref(&self.w_pcm_i16),
2757                    state_mut(&mut self.w_pcm_resampled),
2758                );
2759                res.process(
2760                    &mut out[..resampled_len],
2761                    &inp[..decoded_samples],
2762                    decoded_samples as i32,
2763                );
2764            }
2765            // Channel 1 (stereo output only). A mono stream is copied from
2766            // channel 0, except on the frame that collapses stereo to mono.
2767            if self.channels == 2 {
2768                let (res, inp, out) = (
2769                    &mut self.silk_resampler_2,
2770                    state_ref(&self.w_pcm_i16),
2771                    state_mut(&mut self.w_pcm_resampled),
2772                );
2773                if stream_channels == 2 || stereo_to_mono {
2774                    let src = if stream_channels == 2 {
2775                        &inp[decoded_samples..2 * decoded_samples]
2776                    } else {
2777                        &inp[..decoded_samples]
2778                    };
2779                    res.process(
2780                        &mut out[resampled_len..2 * resampled_len],
2781                        src,
2782                        decoded_samples as i32,
2783                    );
2784                } else {
2785                    out.copy_within(..resampled_len, resampled_len);
2786                }
2787            }
2788            for i in 0..copy_len {
2789                for ch in 0..self.channels {
2790                    let v = self.w_pcm_resampled[ch * resampled_len + i] as f32 / 32768.0;
2791                    let idx = (api_pos + i) * self.channels + ch;
2792                    if idx < out_len {
2793                        self.w_silk_out[idx] = v;
2794                    }
2795                }
2796            }
2797            frame_pos += decoded_samples;
2798        }
2799        Ok(())
2800    }
2801
2802    #[inline(always)]
2803    fn celt_end_band_from_toc(&self, toc: u8) -> usize {
2804        let mode = modes::default_mode();
2805        let top = mode.eff_ebands;
2806        if mode_from_toc(toc) == OpusMode::CeltOnly && toc >= 0x80 {
2807            const FROM_OPUS_TABLE: [u8; 16] = [
2808                0x80, 0x88, 0x90, 0x98, 0x40, 0x48, 0x50, 0x58, 0x20, 0x28, 0x30, 0x38, 0x00, 0x08,
2809                0x10, 0x18,
2810            ];
2811            let idx = ((toc >> 3) - 16) as usize;
2812            let data0 = FROM_OPUS_TABLE[idx] | (toc & 0x7);
2813            let trim = (data0 >> 5) as usize;
2814            return top.saturating_sub(2 * trim).max(1);
2815        }
2816        // A Hybrid frame's CELT layer ends where its bandwidth does (libopus opus_decode_frame:
2817        // super-wideband 19 bands, fullband 21); it decoded to 21 at every bandwidth.
2818        if mode_from_toc(toc) == OpusMode::Hybrid && (toc >> 3) < 14 {
2819            return top.saturating_sub(2).max(1);
2820        }
2821        top
2822    }
2823}
2824
2825fn frame_rate_from_params(sampling_rate: i32, frame_size: usize) -> Option<i32> {
2826    let frame_size = frame_size as i32;
2827    if frame_size <= 0 {
2828        return None;
2829    }
2830    // libopus `frame_size_select`: a frame is 2.5, 5, 10, 20, 40 or 60 ms.
2831    // Validating by duration (not by `sampling_rate % frame_size == 0`) is what
2832    // lets 60 ms through: its rate is 16.67 frames/s, so the old divisibility
2833    // test rejected it before encoding could start (issue #35). Longer frames
2834    // (>60 ms) are handled by the caller's multiframe path.
2835    let fs = sampling_rate;
2836    let valid = frame_size == fs / 400
2837        || frame_size == fs / 200
2838        || frame_size == fs / 100
2839        || frame_size == fs / 50
2840        || frame_size == fs / 25
2841        || 50 * frame_size == 3 * fs;
2842    if !valid {
2843        return None;
2844    }
2845    Some(fs / frame_size)
2846}
2847
2848fn gen_toc(mode: OpusMode, frame_rate: i32, bandwidth: Bandwidth, channels: usize) -> u8 {
2849    let mut rate = frame_rate;
2850    let mut period = 0;
2851    while rate < 400 {
2852        rate <<= 1;
2853        period += 1;
2854    }
2855
2856    let mut toc = match mode {
2857        OpusMode::SilkOnly => {
2858            let bw = (bandwidth as i32 - Bandwidth::Narrowband as i32) << 5;
2859            let per = (period - 2) << 3;
2860            (bw | per) as u8
2861        }
2862        OpusMode::CeltOnly => {
2863            let mut tmp = bandwidth as i32 - Bandwidth::Mediumband as i32;
2864            if tmp < 0 {
2865                tmp = 0;
2866            }
2867            let per = period << 3;
2868            (0x80 | (tmp << 5) | per) as u8
2869        }
2870        OpusMode::Hybrid => {
2871            let base_config = if bandwidth == Bandwidth::Superwideband {
2872                12
2873            } else {
2874                14
2875            };
2876            let period_offset = if frame_rate >= 100 { 0 } else { 1 };
2877            ((base_config + period_offset) << 3) as u8
2878        }
2879    };
2880
2881    if channels == 2 {
2882        toc |= 0x04;
2883    }
2884    toc
2885}
2886
2887fn mode_from_toc(toc: u8) -> OpusMode {
2888    if toc & 0x80 != 0 {
2889        OpusMode::CeltOnly
2890    } else if toc & 0x60 == 0x60 {
2891        OpusMode::Hybrid
2892    } else {
2893        OpusMode::SilkOnly
2894    }
2895}
2896
2897fn bandwidth_from_toc(toc: u8) -> Bandwidth {
2898    let mode = mode_from_toc(toc);
2899    match mode {
2900        OpusMode::SilkOnly => {
2901            let bw_bits = (toc >> 5) & 0x03;
2902            match bw_bits {
2903                0 => Bandwidth::Narrowband,
2904                1 => Bandwidth::Mediumband,
2905                2 => Bandwidth::Wideband,
2906                _ => Bandwidth::Wideband,
2907            }
2908        }
2909        OpusMode::Hybrid => {
2910            let bw_bit = (toc >> 4) & 0x01;
2911            if bw_bit == 0 {
2912                Bandwidth::Superwideband
2913            } else {
2914                Bandwidth::Fullband
2915            }
2916        }
2917        OpusMode::CeltOnly => {
2918            let bw_bits = (toc >> 5) & 0x03;
2919            match bw_bits {
2920                0 => Bandwidth::Mediumband,
2921                1 => Bandwidth::Wideband,
2922                2 => Bandwidth::Superwideband,
2923                3 => Bandwidth::Fullband,
2924                _ => Bandwidth::Fullband,
2925            }
2926        }
2927    }
2928}
2929
2930fn frame_duration_ms_from_toc(toc: u8) -> i32 {
2931    let mode = mode_from_toc(toc);
2932    match mode {
2933        OpusMode::SilkOnly => {
2934            let config = (toc >> 3) & 0x03;
2935            match config {
2936                0 => 10,
2937                1 => 20,
2938                2 => 40,
2939                3 => 60,
2940                _ => 20,
2941            }
2942        }
2943        OpusMode::Hybrid => {
2944            let config = (toc >> 3) & 0x01;
2945            if config == 0 { 10 } else { 20 }
2946        }
2947        OpusMode::CeltOnly => {
2948            let config = (toc >> 3) & 0x03;
2949            match config {
2950                0 => 2,
2951                1 => 5,
2952                2 => 10,
2953                3 => 20,
2954                _ => 20,
2955            }
2956        }
2957    }
2958}
2959
2960/// Compute the per-frame sample count implied by the TOC byte at a given
2961/// sampling rate. For CELT this uses the frame-rate derivation (which handles
2962/// the 2.5 ms case correctly, unlike integer millisecond arithmetic).
2963fn frame_samples_from_toc(toc: u8, sampling_rate: i32) -> Option<usize> {
2964    let mode = mode_from_toc(toc);
2965    match mode {
2966        OpusMode::CeltOnly => {
2967            let period = ((toc >> 3) & 0x03) as i32;
2968            let frame_rate = 400 >> period;
2969            if frame_rate == 0 || sampling_rate % frame_rate != 0 {
2970                return None;
2971            }
2972            Some((sampling_rate / frame_rate) as usize)
2973        }
2974        OpusMode::SilkOnly | OpusMode::Hybrid => {
2975            let duration_ms = frame_duration_ms_from_toc(toc);
2976            Some((sampling_rate as i64 * duration_ms as i64 / 1000) as usize)
2977        }
2978    }
2979}
2980
2981fn channels_from_toc(toc: u8) -> usize {
2982    if toc & 0x04 != 0 { 2 } else { 1 }
2983}
2984
2985/// The frames of a packet of at least 2 bytes, split as its ToC's code says
2986/// (RFC 6716 §3.2; libopus `opus_packet_parse_impl`).
2987fn frame_payloads(input: &[u8]) -> Result<FixedVec<&[u8], OPUS_MAX_PACKET_FRAMES>, &'static str> {
2988    Ok(match input[0] & 0x03 {
2989        0 => FixedVec::from_slice(&[&input[1..]]),
2990        1 => {
2991            let data_len = input.len() - 1;
2992            // RFC 6716 §3.2.1: code 1 carries two equal-size (CBR) frames,
2993            // so the payload length must be even. libopus rejects odd lengths.
2994            if !data_len.is_multiple_of(2) {
2995                return Err("Code 1: payload length must be even");
2996            }
2997            let half = data_len / 2;
2998            if half == 0 {
2999                return Err("Code 1: empty frame");
3000            }
3001            FixedVec::from_slice(&[&input[1..1 + half], &input[1 + half..]])
3002        }
3003        2 => {
3004            let data = &input[1..];
3005            if data.is_empty() {
3006                return Err("Code 2 packet has no data");
3007            }
3008            let (first_len, header_size) = parse_frame_size(data)?;
3009            if header_size + first_len > data.len() {
3010                return Err("Code 2: first frame size exceeds packet");
3011            }
3012            FixedVec::from_slice(&[
3013                &data[header_size..header_size + first_len],
3014                &data[header_size + first_len..],
3015            ])
3016        }
3017        3 => {
3018            if input.len() < 2 {
3019                return Err("Code 3 packet too short");
3020            }
3021            let count_byte = input[1];
3022            let n_frames = (count_byte & 0x3F) as usize;
3023            if !(1..=48).contains(&n_frames) {
3024                return Err("Code 3: invalid frame count");
3025            }
3026            let frame_count = n_frames;
3027            // Bit 6 = padding flag, bit 7 = VBR flag (RFC 6716 §3.2.1).
3028            let padding_flag = (count_byte & 0x40) != 0;
3029            let vbr = (count_byte & 0x80) != 0;
3030
3031            // Parse the optional padding length bytes that follow the count
3032            // byte. The padding *content* (pad_len bytes) lives at the end of
3033            // the packet and is not part of any frame.
3034            let mut ptr = 2usize;
3035            let mut pad_len = 0usize;
3036            if padding_flag {
3037                loop {
3038                    if ptr >= input.len() {
3039                        return Err("Code 3: padding overflow");
3040                    }
3041                    let p = input[ptr] as usize;
3042                    ptr += 1;
3043                    if p == 255 {
3044                        pad_len += 254;
3045                    } else {
3046                        pad_len += p;
3047                        break;
3048                    }
3049                }
3050            }
3051            if ptr + pad_len > input.len() {
3052                return Err("Code 3: padding exceeds packet");
3053            }
3054            let payload_end = input.len() - pad_len;
3055            let payload = &input[ptr..payload_end];
3056
3057            let mut payloads: FixedVec<&[u8], OPUS_MAX_PACKET_FRAMES> = FixedVec::new();
3058            if frame_count == 1 {
3059                // Single frame: the entire payload region is the frame, both
3060                // for VBR and CBR (no length prefix is present).
3061                payloads.push(payload);
3062            } else if vbr {
3063                // VBR (V=1): the per-frame length fields for all frames
3064                // except the last come first, then all frame payloads
3065                // (RFC 6716 §3.2.1; libopus `opus_packet_parse_impl`).
3066                // Interleaving length and data — as this used to — parsed
3067                // any libopus code-3 VBR packet wrong.
3068                let mut cursor = 0usize;
3069                let mut frame_bytes = 0usize;
3070                let mut sizes = [0usize; OPUS_MAX_PACKET_FRAMES];
3071                for i in 0..frame_count - 1 {
3072                    if cursor >= payload.len() {
3073                        return Err("Code 3: unexpected end in VBR header");
3074                    }
3075                    let (frame_len, header_bytes) = parse_frame_size(&payload[cursor..])?;
3076                    cursor += header_bytes;
3077                    sizes[i] = frame_len;
3078                    frame_bytes += frame_len;
3079                }
3080                if frame_bytes > payload.len() - cursor {
3081                    return Err("Code 3: frame length exceeds packet");
3082                }
3083                sizes[frame_count - 1] = payload.len() - cursor - frame_bytes;
3084                let mut data_pos = cursor;
3085                for i in 0..frame_count {
3086                    payloads.push(&payload[data_pos..data_pos + sizes[i]]);
3087                    data_pos += sizes[i];
3088                }
3089            } else {
3090                // CBR (V=0): remaining bytes are split equally into M frames
3091                // (RFC 6716 §3.2.1: "the remaining bytes are split into M
3092                // equal chunks").
3093                if !payload.len().is_multiple_of(frame_count) {
3094                    return Err("Code 3 CBR: payload not divisible by frame count");
3095                }
3096                let frame_len = payload.len() / frame_count;
3097                for i in 0..frame_count {
3098                    payloads.push(&payload[i * frame_len..(i + 1) * frame_len]);
3099                }
3100            }
3101            payloads
3102        }
3103        _ => unreachable!(),
3104    })
3105}
3106
3107/// A 5 ms redundant CELT frame at 48 kHz in stereo, the most it holds.
3108const REDUNDANT_MAX: usize = 480;
3109
3110impl OpusDecoder {
3111    /// A mode switch's 5 ms redundant CELT frame (libopus opus_decode_frame:
3112    /// all bands from 0, its own range coder over its bytes), interleaved into
3113    /// `out`.
3114    fn decode_redundant(&mut self, data: &[u8], end_band: usize, f5: usize, out: &mut [f32]) {
3115        let n = f5 * self.channels;
3116        if data.is_empty() || n > REDUNDANT_MAX {
3117            return;
3118        }
3119        let mut planar = [0.0f32; REDUNDANT_MAX];
3120        let mut rrc = RangeCoder::new_decoder(data);
3121        self.celt_dec.decode_from_range_coder_with_band_range(
3122            &mut rrc,
3123            (data.len() * 8) as i32,
3124            f5,
3125            &mut planar[..n],
3126            0,
3127            end_band,
3128        );
3129        if self.channels == 1 {
3130            out[..n].copy_from_slice(&planar[..n]);
3131        } else {
3132            for i in 0..f5 {
3133                for c in 0..self.channels {
3134                    out[i * self.channels + c] = planar[c * f5 + i];
3135                }
3136            }
3137        }
3138    }
3139}
3140
3141/// Crossfade two signals using a squared-sine window (libopus smooth_fade).
3142/// `window` is the 120-sample CELT window at 48 kHz; `inc` = 48000/Fs strides it.
3143fn smooth_fade(
3144    in1: &[f32],
3145    in2: &[f32],
3146    out: &mut [f32],
3147    overlap: usize,
3148    channels: usize,
3149    window: &[f32],
3150    inc: usize,
3151) {
3152    for c in 0..channels {
3153        for i in 0..overlap {
3154            let wi = i * inc;
3155            if wi >= window.len() {
3156                break;
3157            }
3158            let w = window[wi] * window[wi];
3159            out[i * channels + c] = w * in2[i * channels + c] + (1.0 - w) * in1[i * channels + c];
3160        }
3161    }
3162}
3163
3164/// Parse an Opus frame length per RFC 6716 §3.2.1, identical to libopus
3165/// `parse_size()`:
3166///   - `0`: no frame (DTX / lost packet)
3167///   - `1..=251`: length of the frame in bytes (one byte consumed)
3168///   - `252..=255`: a second byte is read; length = `second*4 + first`
3169///
3170/// Returns `(length, bytes_consumed)`.
3171pub(crate) fn parse_frame_size(data: &[u8]) -> Result<(usize, usize), &'static str> {
3172    let first = *data.first().ok_or("truncated frame length")? as usize;
3173    if first < 252 {
3174        Ok((first, 1))
3175    } else {
3176        let second = *data.get(1).ok_or("truncated frame length")? as usize;
3177        Ok((second * 4 + first, 2))
3178    }
3179}
3180
3181#[cfg(all(test, feature = "std"))]
3182mod tests {
3183    use super::*;
3184
3185    fn frame_size_from_toc(toc: u8, sampling_rate: i32) -> Option<usize> {
3186        let mode = mode_from_toc(toc);
3187        match mode {
3188            OpusMode::CeltOnly => {
3189                let period = ((toc >> 3) & 0x03) as i32;
3190                let frame_rate = 400 >> period;
3191                if frame_rate == 0 || sampling_rate % frame_rate != 0 {
3192                    return None;
3193                }
3194                Some((sampling_rate / frame_rate) as usize)
3195            }
3196            OpusMode::SilkOnly => {
3197                let duration_ms = frame_duration_ms_from_toc(toc);
3198                Some((sampling_rate as i64 * duration_ms as i64 / 1000) as usize)
3199            }
3200            OpusMode::Hybrid => {
3201                let duration_ms = frame_duration_ms_from_toc(toc);
3202                Some((sampling_rate as i64 * duration_ms as i64 / 1000) as usize)
3203            }
3204        }
3205    }
3206
3207    #[test]
3208    fn gen_toc_matches_celt_reference_values() {
3209        let sampling_rate = 48_000;
3210        let cases = [
3211            (120usize, 0xE0u8),
3212            (240usize, 0xE8u8),
3213            (480usize, 0xF0u8),
3214            (960usize, 0xF8u8),
3215        ];
3216
3217        for (frame_size, expected_toc) in cases {
3218            let frame_rate = frame_rate_from_params(sampling_rate, frame_size).unwrap();
3219            let toc = gen_toc(OpusMode::CeltOnly, frame_rate, Bandwidth::Fullband, 1);
3220            assert_eq!(
3221                toc, expected_toc,
3222                "frame_size {} expected TOC {:02X} got {:02X}",
3223                frame_size, expected_toc, toc
3224            );
3225            let decoded_size = frame_size_from_toc(toc, sampling_rate).unwrap();
3226            assert_eq!(decoded_size, frame_size);
3227        }
3228
3229        let stereo_toc = gen_toc(
3230            OpusMode::CeltOnly,
3231            frame_rate_from_params(sampling_rate, 960).unwrap(),
3232            Bandwidth::Fullband,
3233            2,
3234        );
3235        assert_eq!(channels_from_toc(stereo_toc), 2);
3236    }
3237
3238    #[test]
3239    fn test_celt_decoder_large_frame_sizes() {
3240        let sampling_rate = 48000;
3241        let channels = 1;
3242
3243        let mut decoder = OpusDecoder::new(sampling_rate, channels).unwrap();
3244
3245        let frame_sizes = [120, 240, 480, 960];
3246
3247        for frame_size in frame_sizes {
3248            let toc = gen_toc(
3249                OpusMode::CeltOnly,
3250                frame_rate_from_params(sampling_rate, frame_size).unwrap(),
3251                Bandwidth::Fullband,
3252                channels,
3253            );
3254            let packet = [toc, 0, 0, 0, 0];
3255
3256            let mut output = vec![0.0f32; frame_size * channels];
3257
3258            let _ = decoder.decode(&packet, frame_size, &mut output);
3259        }
3260
3261        let channels = 2;
3262        let mut decoder = OpusDecoder::new(sampling_rate, channels).unwrap();
3263
3264        for frame_size in frame_sizes {
3265            let toc = gen_toc(
3266                OpusMode::CeltOnly,
3267                frame_rate_from_params(sampling_rate, frame_size).unwrap(),
3268                Bandwidth::Fullband,
3269                channels,
3270            );
3271            let packet = [toc, 0, 0, 0, 0];
3272
3273            let mut output = vec![0.0f32; frame_size * channels];
3274            let _ = decoder.decode(&packet, frame_size, &mut output);
3275        }
3276    }
3277
3278    #[test]
3279    fn test_celt_decoder_edge_case_frame_sizes() {
3280        let sampling_rate = 48000;
3281        let channels = 1;
3282        let mut decoder = OpusDecoder::new(sampling_rate, channels).unwrap();
3283
3284        let edge_sizes = [2048, 2167, 2168, 2169, 2880, 3072];
3285
3286        for frame_size in edge_sizes {
3287            let mut output = vec![0.0f32; frame_size * channels];
3288
3289            let _ = decoder.decode(&[0x80, 0, 0, 0], frame_size, &mut output);
3290        }
3291    }
3292
3293    // Regression test for: "index out of bounds: the len is 48 but the index is 119"
3294    // Root cause: frame_size=48 at 48kHz gives frame_rate=1000, which is not a valid
3295    // Hybrid-mode frame rate but was not validated.  CELT's lm-search then silently
3296    // fell back to lm=0, computed n2=120, and wrote output[119] into a 48-element
3297    // slice.  Triggered via G.729-decoded PCM (8kHz) passed to a 48kHz Opus encoder
3298    // without proper resampling, so the encoder received 48 samples instead of 480.
3299    #[test]
3300    fn test_invalid_small_frame_size_returns_error_not_panic() {
3301        let mut enc = OpusEncoder::new(48000, 2, Application::Voip).unwrap();
3302        enc.bitrate_bps = 64000;
3303        enc.complexity = 5;
3304        enc.use_cbr = true;
3305
3306        // 48 samples at 48kHz = 1ms → frame_rate=1000, invalid for Hybrid mode.
3307        let input = vec![0.0f32; 48 * 2]; // stereo interleaved
3308        let mut output = vec![0u8; 256];
3309
3310        let result = enc.encode(&input, 48, &mut output);
3311        assert!(
3312            result.is_err(),
3313            "encode with invalid frame_size=48 should return Err, not panic"
3314        );
3315    }
3316
3317    // Also verify that the Audio application path (always Hybrid at 48 kHz) rejects
3318    // the same bad frame size.
3319    #[test]
3320    fn test_invalid_small_frame_size_audio_application_returns_error() {
3321        let mut enc = OpusEncoder::new(48000, 1, Application::Audio).unwrap();
3322        let input = vec![0.0f32; 48];
3323        let mut output = vec![0u8; 256];
3324
3325        let result = enc.encode(&input, 48, &mut output);
3326        assert!(
3327            result.is_err(),
3328            "Audio/48kHz encoder with frame_size=48 should return Err"
3329        );
3330    }
3331}