opus-rs

https://docs.rs/opus-rs/0.1.17
Admin
opus-rs is a Rust implementation of the Opus audio codec, providing encoding and decoding...
Tokens:408,560
Snippets:1,913
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### 5-Point Butterfly Setup (Partial)

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/kiss_fft.rs.html

Initializes constants and pointers for a 5-point FFT butterfly operation using NEON intrinsics. This snippet shows the setup before the main processing loop.

```rust
#[cfg(target_arch = "aarch64")]
#[inline(always)]
unsafe fn kf_bfly5_neon_inner(
    fout: &mut [KissCpx],
    fstride: usize,
    twiddles: &[KissCpx],
    m: usize,
    n: usize,
    mm: usize,
) {
    use std::arch::aarch64::*

    let m2 = 2 * m;
    let m3 = 3 * m;
    let m4 = 4 * m;
    let stride2 = fstride * 2;
    let stride3 = fstride * 3;
    let stride4 = fstride * 4;

    let ya_r: f32 = 0.309_017;
    let ya_i: f32 = -0.95105652;
    let yb_r: f32 = -0.809_017;
    let yb_i: f32 = -0.58778525;

    let fout_ptr = fout.as_mut_ptr() as *mut f32;
    let tw_ptr = twiddles.as_ptr() as *const f32;

    for i in 0..n {
        let base = i * mm;

```

--------------------------------

### Silk Encoder Initialization and Setup

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/silk/enc_api.rs.html

Sets up the Silk encoder for processing a packet, calculating bit rates, and determining LBRR symbol usage.

```rust
    let n_frames_per_packet = ps_enc.s_cmn.n_frames_per_packet;
    let frame_length = ps_enc.s_cmn.frame_length as usize;
    let packet_size_ms = ps_enc.s_cmn.packet_size_ms;

    ps_enc.s_cmn.n_frames_encoded = 0;

    let n_blocks_of_10ms = (100 * n_samples_in as i32) / (ps_enc.s_cmn.fs_khz * 1000);
    let _tot_blocks = if n_blocks_of_10ms > 1 {
        n_blocks_of_10ms >> 1
    } else {
        1
    };

    let n_bits_total = target_rate_bps * packet_size_ms / 1000;
    let n_bits_per_frame = n_bits_total / n_frames_per_packet;
    let frame_rate_bps = if packet_size_ms == 10 {
        n_bits_per_frame * 100
    } else {
        n_bits_per_frame * 50
    };

    let lbrr_possible = ps_enc.s_cmn.use_in_band_fec != 0
        && ps_enc.s_cmn.packet_loss_perc > 0
        && ps_enc.s_cmn.lbrr_enabled != 0;

    let mut lbrr_symbol: i32 = 0;
    if lbrr_possible {
        for i in 0..n_frames_per_packet as usize {
            if ps_enc.s_cmn.indices_lbrr[i].signal_type >= TYPE_UNVOICED as i8 {
                lbrr_symbol |= 1 << i;
            }
        }
    }
    let use_lbrr = lbrr_symbol > 0;

    ps_enc.s_cmn.lbrr_flag = if lbrr_symbol > 0 { 1 } else { 0 };

    for i in 0..n_frames_per_packet as usize {
        ps_enc.s_cmn.lbrr_flags[i] = (lbrr_symbol >> i) & 1;
    }
```

--------------------------------

### KissFFT Butterfly Operations (Example)

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/kiss_fft.rs.html

Illustrates the complex arithmetic and assignments within a butterfly operation, a fundamental step in FFT algorithms. This snippet shows calculations for specific indices within the output array.

```rust
fout[idx + m] = c_sub(&scratch5, &scratch6);
            fout[idx + m4] = c_add(&scratch5, &scratch6);
            let scratch11 = KissCpx::new(
                scratch0.r + scratch7.r * yb_r + scratch8.r * ya_r,
                scratch0.i + scratch7.i * yb_r + scratch8.i * ya_r,
            );
            let scratch12 = KissCpx::new(
                scratch9.i * ya_i - scratch10.i * yb_i,
                scratch10.r * yb_i - scratch9.r * ya_i,
            );
            fout[idx + m2] = c_add(&scratch11, &scratch12);
            fout[idx + m3] = c_sub(&scratch11, &scratch12);
```

--------------------------------

### Initialize Silk Decoder

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/init_decoder/fn.silk_create_decoder.html

Call this function to create a new SilkDecoderState. No setup or imports are required beyond the function itself.

```rust
pub fn silk_create_decoder() -> SilkDecoderState
```

--------------------------------

### Setup Encoding Sample Rate and Packet Size

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/silk/control_codec.rs.html

Configures Silk encoder state based on the desired sample rate and packet size. Adjusts frame lengths, pitch window lengths, and other parameters accordingly.

```rust
use crate::silk::define::*;
use crate::silk::structs::*;
use crate::silk::tables_nlsf::*;

pub const FIND_PITCH_LPC_WIN_MS: i32 = 20 + (LA_PITCH_MS as i32 * 2);
pub const FIND_PITCH_LPC_WIN_MS_2_SF: i32 = 10 + (LA_PITCH_MS as i32 * 2);
pub const MAX_DEL_DEC_STATES: i32 = 4;
pub const LA_SHAPE_MAX: i32 = LA_SHAPE_MS as i32 * MAX_FS_KHZ as i32;
pub const SHAPE_LPC_WIN_MAX: i32 = 15 * MAX_FS_KHZ as i32;

pub const WARPING_MULTIPLIER_Q16: i32 = 983;

pub fn silk_setup_fs(ps_enc: &mut SilkEncoderState, fs_khz: i32, packet_size_ms: i32) -> i32 {
    let cmn = &mut ps_enc.s_cmn;

    if packet_size_ms <= 10 {
        cmn.n_frames_per_packet = 1;
        cmn.nb_subfr = if packet_size_ms == 10 { 2 } else { 1 };
        cmn.frame_length = packet_size_ms * fs_khz;
        cmn.pitch_lpc_win_length = FIND_PITCH_LPC_WIN_MS_2_SF * fs_khz;
    } else {
        cmn.n_frames_per_packet = packet_size_ms / MAX_FRAME_LENGTH_MS as i32;
        cmn.nb_subfr = MAX_NB_SUBFR as i32;
        cmn.frame_length = 20 * fs_khz;
        cmn.pitch_lpc_win_length = FIND_PITCH_LPC_WIN_MS * fs_khz;
    }
    cmn.packet_size_ms = packet_size_ms;

    if cmn.fs_khz != fs_khz {
        ps_enc.s_nsq = SilkNSQState::default();
        cmn.prev_nlsf_q15 = [0; MAX_LPC_ORDER];

        cmn.prev_lag = 100;
        cmn.first_frame_after_reset = 1;
        ps_enc.s_shape.last_gain_index = 10;
        ps_enc.s_nsq.lag_prev = 100;
        ps_enc.s_nsq.prev_gain_q16 = 65536;
        cmn.prev_signal_type = TYPE_NO_VOICE_ACTIVITY;

        cmn.fs_khz = fs_khz;

        if fs_khz == 8 || fs_khz == 12 {
            cmn.predict_lpc_order = MIN_LPC_ORDER as i32;
            ps_enc.ps_nlsf_cb = Some(&SILK_NLSF_CB_NB_MB);
        } else {
            cmn.predict_lpc_order = MAX_LPC_ORDER as i32;
            ps_enc.ps_nlsf_cb = Some(&SILK_NLSF_CB_WB);
        }

        cmn.subfr_length = SUB_FRAME_LENGTH_MS as i32 * fs_khz;
        cmn.frame_length = cmn.subfr_length * cmn.nb_subfr;
        cmn.ltp_mem_length = LTP_MEM_LENGTH_MS as i32 * fs_khz;
        cmn.la_pitch = LA_PITCH_MS as i32 * fs_khz;

        if cmn.nb_subfr == MAX_NB_SUBFR as i32 {
            cmn.pitch_lpc_win_length = FIND_PITCH_LPC_WIN_MS * fs_khz;
        } else {
            cmn.pitch_lpc_win_length = FIND_PITCH_LPC_WIN_MS_2_SF * fs_khz;
        }
    }

    SILK_NO_ERROR
}
```

--------------------------------

### Control Silk Encoder Initialization

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/silk/control_codec.rs.html

Initializes and controls the Silk encoder with specified sample rate, packet size, target bitrate, and complexity. It calls setup functions for sample rate and complexity.

```rust
pub fn silk_control_encoder(
    ps_enc: &mut SilkEncoderState,
    fs_khz: i32,
    packet_size_ms: i32,
    target_rate_bps: i32,
    complexity: i32,
) -> i32 {
    let mut ret = silk_setup_fs(ps_enc, fs_khz, packet_size_ms);
    ret += silk_setup_complexity(ps_enc, complexity);

    ps_enc.s_cmn.target_rate_bps = target_rate_bps;

    ret
}

```

--------------------------------

### Setup Encoding Complexity Parameters

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/silk/control_codec.rs.html

Adjusts various Silk encoder parameters based on a complexity level. This affects pitch estimation, LPC order, and decision-making states.

```rust
pub fn silk_setup_complexity(ps_enc: &mut SilkEncoderState, complexity: i32) -> i32 {
    let cmn = &mut ps_enc.s_cmn;

    if complexity < 1 {
        cmn.pitch_estimation_complexity = SILK_PE_MIN_COMPLEX as i32;
        cmn.pitch_estimation_threshold_q16 = (0.8f32 * 65536.0) as i32;
        ps_enc.pitch_estimation_lpc_order = 6;
        cmn.shaping_lpc_order = 12;
        cmn.la_shape = 3 * cmn.fs_khz;
        cmn.n_states_delayed_decision = 1;
        cmn.use_interpolated_nlsfs = 0;
        cmn.n_nlsf_survivors = 2;
        cmn.warping_q16 = 0;
    } else if complexity < 2 {
        cmn.pitch_estimation_complexity = SILK_PE_MID_COMPLEX as i32;
        cmn.pitch_estimation_threshold_q16 = (0.76f32 * 65536.0) as i32;
        ps_enc.pitch_estimation_lpc_order = 8;
        cmn.shaping_lpc_order = 14;
        cmn.la_shape = 5 * cmn.fs_khz;
        cmn.n_states_delayed_decision = 1;
        cmn.use_interpolated_nlsfs = 0;
        cmn.n_nlsf_survivors = 3;
        cmn.warping_q16 = 0;
    } else if complexity < 3 {
        cmn.pitch_estimation_complexity = SILK_PE_MIN_COMPLEX as i32;
        cmn.pitch_estimation_threshold_q16 = (0.8f32 * 65536.0) as i32;
        ps_enc.pitch_estimation_lpc_order = 6;
        cmn.shaping_lpc_order = 12;
        cmn.la_shape = 3 * cmn.fs_khz;
        cmn.n_states_delayed_decision = 2;
        cmn.use_interpolated_nlsfs = 0;
        cmn.n_nlsf_survivors = 2;
        cmn.warping_q16 = 0;
    } else if complexity < 4 {
        cmn.pitch_estimation_complexity = SILK_PE_MID_COMPLEX as i32;
        cmn.pitch_estimation_threshold_q16 = (0.76f32 * 65536.0) as i32;
        ps_enc.pitch_estimation_lpc_order = 8;
        cmn.shaping_lpc_order = 14;
        cmn.la_shape = 5 * cmn.fs_khz;
        cmn.n_states_delayed_decision = 2;
        cmn.use_interpolated_nlsfs = 0;
        cmn.n_nlsf_survivors = 4;
        cmn.warping_q16 = 0;
    } else if complexity < 6 {
        cmn.pitch_estimation_complexity = SILK_PE_MID_COMPLEX as i32;
        cmn.pitch_estimation_threshold_q16 = (0.74f32 * 65536.0) as i32;
        ps_enc.pitch_estimation_lpc_order = 10;
        cmn.shaping_lpc_order = 16;
        cmn.la_shape = 5 * cmn.fs_khz;
        cmn.n_states_delayed_decision = 2;

```

--------------------------------

### Example Data Array

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/modes.rs.html

An example array representing data, possibly for a specific mode or configuration.

```rust
let data = [
    0, -2, 0, -3, 3, 0, 1, -1
];
```

--------------------------------

### silk_setup_fs

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/control_codec/fn.silk_setup_fs.html

Sets up the Silk encoder state. This function initializes the encoder with the provided sample rate and packet size.

```APIDOC
## Function silk_setup_fs

### Description
Sets up the Silk encoder state with the specified sample rate and packet size.

### Signature
```rust
pub fn silk_setup_fs(
    ps_enc: &mut SilkEncoderState,
    fs_khz: i32,
    packet_size_ms: i32,
) -> i32
```

### Parameters
* `ps_enc`: A mutable reference to the `SilkEncoderState` to be configured.
* `fs_khz`: The desired sample rate in kHz (e.g., 8, 16, 24, 48).
* `packet_size_ms`: The desired packet size in milliseconds.

### Returns
Returns an integer representing the result of the setup operation. A return value of 0 typically indicates success, while other values may indicate errors.
```

--------------------------------

### silk_setup_fs

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/control_codec/index.html

Configures the sample rate for the Silk encoder. This is crucial for ensuring proper audio processing and compatibility.

```APIDOC
## silk_setup_fs

### Description
Configures the sample rate for the Silk encoder. This is crucial for ensuring proper audio processing and compatibility.

### Functions
- `silk_setup_fs`
```

--------------------------------

### Decode with specified start band

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/celt.rs.html

Decodes a frame of compressed audio data, allowing specification of the starting frequency band for decoding. Useful for partial decoding or specific use cases.

```rust
pub fn decode_with_start_band(
        &mut self,
        compressed: &[u8],
        frame_size: usize,
        pcm: &mut [f32],
        start_band: usize,
    ) -> usize {
        self.decode_impl(compressed, frame_size, pcm, start_band, self.mode.nb_ebands)
    }
```

--------------------------------

### SilkDecoder::sample_rate

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/dec_api/struct.SilkDecoder.html

Gets the sample rate the decoder is configured for.

```APIDOC
## SilkDecoder::sample_rate

### Description
Returns the sample rate in Hz that the decoder is configured to process.

### Method
`sample_rate(&self) -> i32`

### Parameters
#### Path Parameters
- `self` (&SilkDecoder)

### Returns
- `i32`: The sample rate in Hz.
```

--------------------------------

### Scalar Initialization for PVQ Search (x86_64 fallback)

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/pvq.rs.html

Handles the initialization of PVQ search on x86_64 architectures when AVX2 is not available. It calculates the absolute values, sums them, and determines the signs of the input vector elements.

```rust
let mut s = 0.0f32;
for i in 0..n {
    let xi = x[i];
    let abs_xi = xi.abs();
    abs_x[i] = abs_xi;
    s += abs_xi;
    sign_x[i] = (xi < 0.0) as i32;
}
s
```

--------------------------------

### SilkDecoder::frame_length

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/dec_api/struct.SilkDecoder.html

Gets the current frame length of the decoder.

```APIDOC
## SilkDecoder::frame_length

### Description
Returns the current frame length in samples that the decoder is configured to process.

### Method
`frame_length(&self) -> i32`

### Parameters
#### Path Parameters
- `self` (&SilkDecoder)

### Returns
- `i32`: The frame length in samples.
```

--------------------------------

### silk_encode_prefill

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/enc_api/index.html

Prefills the Silk encoder with data, likely for initial buffering or setup.

```APIDOC
## Function silk_encode_prefill

### Description
Prefills the Silk encoder with data, likely for initial buffering or setup.

### Signature
`pub fn silk_encode_prefill(...)`

### Parameters
(Parameters not explicitly detailed in the source)

### Returns
(Return value not explicitly detailed in the source)
```

--------------------------------

### Initialize Stereo and Bit Allocation Buffers

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/celt.rs.html

Initializes buffers for intensity, dual stereo, balance, pulses, fine priority, and ebits. The size of stereo-related buffers depends on the channel count.

```rust
let mut intensity = 0;
        let mut dual_stereo_val = if channels == 2 { 1 } else { 0 };
        let mut balance = 0;
        self.w_pulses[..nb_ebands].fill(0);
        let pulses = &mut self.w_pulses[..nb_ebands];

        let ebands_stereo = if channels > 1 {
            nb_ebands * channels
        } else {
            nb_ebands
        };
        self.w_fine_priority[..ebands_stereo].fill(0);
        let fine_priority = &mut self.w_fine_priority[..ebands_stereo];
        self.w_ebits[..ebands_stereo].fill(0);
        let ebits = &mut self.w_ebits[..ebands_stereo];
```

--------------------------------

### Get FFT Size (nfft)

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/kiss_fft.rs.html

Returns the FFT size (nfft) of the KissFftState.

```rust
193    #[inline]
194    pub fn nfft(&self) -> usize {
195        self.nfft
196    }
```

--------------------------------

### NEON Optimized PVQ Search Initialization

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/pvq.rs.html

Initializes PVQ search using NEON intrinsics for ARM architectures. It processes input vectors in chunks of 4, calculating absolute values and signs efficiently.

```rust
use std::arch::aarch64::*;

let mut abs_x_arr = [0.0f32; 16];
let mut y2f_arr = [0.0f32; 16];
let mut sign_x_arr = [0i32; 16];

unsafe {
    let vzero = vdupq_n_f32(0.0);
    let n4 = n & !3;
    for i in (0..n4).step_by(4) {
        let vx = vld1q_f32(x.as_ptr().add(i));
        let vabs = vabsq_f32(vx);
        vst1q_f32(abs_x_arr.as_mut_ptr().add(i), vabs);
        let vneg = vcltq_f32(vx, vzero);
        let vsign = vandq_u32(vneg, vdupq_n_u32(1));
        vst1q_s32(sign_x_arr.as_mut_ptr().add(i), vreinterpretq_s32_u32(vsign));
    }
    for i in n4..n {
        let xi = x[i];
        abs_x_arr[i] = xi.abs();
        sign_x_arr[i] = (xi < 0.0) as i32;
    }
}

let mut yy_local = 0.0f32;
let mut xy_local = 0.0f32;

let abs_x_ptr = abs_x_arr.as_ptr();
```

--------------------------------

### Get Current Frame Length

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/silk/dec_api.rs.html

Returns the current frame length of the decoder.

```rust
pub fn frame_length(&self) -> i32 {
    self.channel_state[0].frame_length
}
```

--------------------------------

### Get SilkDecoder Sample Rate

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/dec_api/struct.SilkDecoder.html

Returns the sample rate of the SilkDecoder in Hz.

```rust
pub fn sample_rate(&self) -> i32
```

--------------------------------

### Bandwidth Expansion (Fixed-Point)

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/silk/sigproc_fix.rs.html

Applies bandwidth expansion to an array of coefficients using a chirp factor. This is a fixed-point implementation.

```rust
pub fn silk_bwexpander(ar: &mut [i16], d: usize, mut chirp_q16: i32) {
    let chirp_minus_one_q16 = chirp_q16 - 65536;

    for ar_val in ar[..d - 1].iter_mut() {
        *ar_val = silk_rshift_round((*ar_val as i32).wrapping_mul(chirp_q16), 16) as i16;
    }
}
```

--------------------------------

### Initialize Output Signal Buffer

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/celt.rs.html

Initializes the output signal buffer `w_x` with zeros, ensuring it's large enough to accommodate the frame size and channel count, with padding for stride access.

```rust
self.w_x[..frame_size * channels].fill(0.0);

        let x_pad_end = (frame_size * channels + STRIDE_ACCESS_PAD).min(self.w_x.len());
        let x = &mut self.w_x[..x_pad_end];
        self.w_collapse_masks[..nb_ebands * channels].fill(0);
        let collapse_masks = &mut self.w_collapse_masks[..nb_ebands * channels];
```

--------------------------------

### CeltDecoder::type_id

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/celt/struct.CeltDecoder.html

Gets the `TypeId` of the `CeltDecoder` instance. This is part of the `Any` trait implementation.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### KissFftState::new

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/kiss_fft/struct.KissFftState.html

Creates a new KissFftState with the specified FFT size. Returns None if the size is invalid.

```APIDOC
## pub fn new(nfft: usize) -> Option<Self>

### Description
Creates a new KissFftState with the specified FFT size.

### Parameters
* **nfft** (usize) - The desired size of the FFT.

### Returns
* `Option<Self>` - Returns `Some(KissFftState)` if the size is valid, otherwise `None`.
```

--------------------------------

### CeltDecoder::decode_with_start_band

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/celt/struct.CeltDecoder.html

Decodes a frame of compressed audio data, starting from a specified band.

```APIDOC
## CeltDecoder::decode_with_start_band

### Description
Decodes a frame of compressed audio data, starting from a specified band.

### Method
`decode_with_start_band`

### Parameters
* `compressed`: `&[u8]` - A slice containing the compressed audio data.
* `frame_size`: `usize` - The expected number of samples per channel in the decoded frame.
* `pcm`: `&mut [f32]` - A mutable slice to store the decoded PCM samples.
* `start_band`: `usize` - The first frequency band to decode.
```

--------------------------------

### Band Quantization with Bit Rebalancing

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/bands.rs.html

Demonstrates the process of quantizing audio bands, prioritizing either mid or side channels based on available bits. It includes logic for rebalancing bits between channels to optimize quantization.

```rust
    ctx.remaining_bits -= sctx.qalloc;
    let mut mbits = (0).max((b_mut - sctx.delta) / 2).min(b_mut);
    let mut sbits = b_mut - mbits;

    let mut rebalance = ctx.remaining_bits;
    let mut cm;

    if mbits >= sbits {
        cm = quant_band(
            ctx,
            x,
            n,
            mbits,
            b_blocks,
            lowband,
            lm,
            lowband_out,
            1.0,
            fill_mut,
        );
        rebalance = mbits - (rebalance - ctx.remaining_bits);
        if rebalance > (3 << 3) && sctx.itheta != 0 {
            sbits += rebalance - (3 << 3);
        }
        cm |= quant_band(
            ctx,
            y,
            n,
            sbits,
            b_blocks,
            None,
            lm,
            None,
            side_gain,
            fill_mut >> b_blocks,
        );
    } else {
        cm = quant_band(
            ctx,
            y,
            n,
            sbits,
            b_blocks,
            None,
            lm,
            None,
            side_gain,
            fill_mut >> b_blocks,
        );
        rebalance = sbits - (rebalance - ctx.remaining_bits);
        if rebalance > (3 << 3) && sctx.itheta != 16384 {
            mbits += rebalance - (3 << 3);
        }
        cm |= quant_band(
            ctx,
            x,
            n,
            mbits,
            b_blocks,
            lowband,
            lm,
            lowband_out,
            1.0,
            fill_mut,
        );
    }

    if ctx.resynth {
        stereo_merge(x, y, mid_gain, side_gain, n);
        if sctx.inv {
            for yv in y[..n].iter_mut() {
                *yv = -*yv;
            }
        }
    }
    cm
}
```

--------------------------------

### Get Default Audio Mode

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/modes.rs.html

Returns a reference to the default CeltMode configuration, which is MODE_48000_960_120.

```rust
pub fn default_mode() -> &'static CeltMode {
    &MODE_48000_960_120
}
```

--------------------------------

### Get Decoder Sample Rate

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/silk/dec_api.rs.html

Returns the current sample rate of the decoder in Hz.

```rust
pub fn sample_rate(&self) -> i32 {
    self.channel_state[0].fs_khz * 1000
}
```

--------------------------------

### Compute Quantization Parameter (qn)

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/bands.rs.html

Calculates the quantization parameter 'qn' based on input parameters like band count, bias, offset, and pulse capacity. Includes logic for stereo and bit resolution.

```rust
pub fn compute_qn(n: usize, b: i32, offset: i32, pulse_cap: i32, stereo: bool) -> i32 {
    static EXP2_TABLE8: [i16; 8] = [16384, 17866, 19483, 21247, 23170, 25267, 27554, 30048];
    let mut n2 = (2 * n as i32) - 1;
    if stereo && n == 2 {
        n2 -= 1;
    }
    let mut qb = celt_sudiv(b + n2 * offset, n2);
    qb = qb.min(b - pulse_cap - (4 << BITRES));
    qb = qb.min(8 << BITRES);
    if qb < (1i32 << BITRES >> 1) {
        1
    } else {
        // (qb + (1 << BITRES >> 1)) >> BITRES
        // This part is truncated in the source, but implies further calculation.
    }
}
```

--------------------------------

### Get SilkDecoder Frame Length

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/dec_api/struct.SilkDecoder.html

Returns the current frame length of the SilkDecoder in samples.

```rust
pub fn frame_length(&self) -> i32
```

--------------------------------

### SilkDecoder::init

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/dec_api/struct.SilkDecoder.html

Initializes the SilkDecoder with the specified sample rate and number of channels.

```APIDOC
## SilkDecoder::init

### Description
Initializes the SilkDecoder with the specified sample rate and number of channels.

### Method
`init(&mut self, sample_rate_hz: i32, channels: i32) -> i32`

### Parameters
#### Path Parameters
- `self` (*mut SilkDecoder)
- `sample_rate_hz` (i32)
- `channels` (i32)

### Returns
- `i32`: An integer representing the result of the initialization. (Specific meaning not detailed in source).
```

--------------------------------

### CeltEncoder::encode_with_start_band Function

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/celt/struct.CeltEncoder.html

Encodes PCM audio data, specifying a starting band for encoding.

```rust
pub fn encode_with_start_band( &mut self, pcm: &[f32], frame_size: usize, rc: &mut RangeCoder, start_band: usize, )
```

--------------------------------

### silk_init_decoder

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/init_decoder/index.html

Initializes an existing Silk decoder instance. This prepares the decoder for processing audio data.

```APIDOC
## silk_init_decoder

### Description
Initializes an existing Silk decoder instance.

### Method
(Not specified, likely a function call in Rust SDK)

### Endpoint
(Not applicable for SDK functions)

### Parameters
- **decoder** (Decoder Instance) - Required - The Silk decoder instance to initialize.
```

--------------------------------

### CeltDecoder::decode_from_range_coder

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/celt/struct.CeltDecoder.html

Decodes a frame of compressed audio data using a RangeCoder, starting from a specified band.

```APIDOC
## CeltDecoder::decode_from_range_coder

### Description
Decodes a frame of compressed audio data using a RangeCoder, starting from a specified band.

### Method
`decode_from_range_coder`

### Parameters
* `rc`: `&mut RangeCoder` - A mutable reference to the RangeCoder instance.
* `total_bits`: `i32` - The total number of bits available for decoding.
* `frame_size`: `usize` - The expected number of samples per channel in the decoded frame.
* `pcm`: `&mut [f32]` - A mutable slice to store the decoded PCM samples.
* `start_band`: `usize` - The first frequency band to decode.
```

--------------------------------

### PVQ Fast Select Initialization (Non-NEON)

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/pvq.rs.html

Initializes absolute values and signs for PVQ search, calculating the initial sum. This is a fallback for non-aarch64 architectures.

```rust
let sum = {
        let mut s = 0.0f32;
        for i in 0..n {
            abs_x_mu[i].write(x[i].abs());
            signs_mu[i].write(if x[i] < 0.0 { -1i32 } else { 1i32 });
            s += unsafe { abs_x_mu[i].assume_init() };
        }
        s
    };
```

--------------------------------

### Get Scaling Factor

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/kiss_fft.rs.html

Returns the scaling factor applied to the FFT output. This is typically 1.0 / nfft.

```rust
197    #[inline]
198    pub fn scale(&self) -> f32 {
199        self.scale
200    }
```

--------------------------------

### Opus Encoder Initialization and Mode Selection

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/lib.rs.html

Demonstrates the logic for selecting the Opus encoding mode (SilkOnly, CeltOnly, Hybrid) based on application type, bitrate, channels, and other parameters. This logic mirrors the behavior of the C reference implementation.

```rust
        let mut mode = if self.application == Application::RestrictedLowDelay {
            OpusMode::CeltOnly
        } else {
            let equiv = compute_equiv_rate(
                self.bitrate_bps,
                self.channels,
                frame_rate,
                !self.use_cbr,
                self.complexity,
                self.packet_loss_perc,
            );
            let prev_was_celt = self.prev_enc_mode == Some(OpusMode::CeltOnly);
            let threshold = compute_mode_threshold(self.application, self.channels, prev_was_celt);
            if equiv >= threshold {
                OpusMode::CeltOnly
            } else {
                OpusMode::SilkOnly
            }
        };

        let curr_bw = self.bandwidth;
        if mode == OpusMode::SilkOnly
            && (curr_bw == Bandwidth::Superwideband || curr_bw == Bandwidth::Fullband)
        {
            mode = OpusMode::Hybrid;
        }
        if mode == OpusMode::Hybrid
            && (curr_bw == Bandwidth::Narrowband
                || curr_bw == Bandwidth::Mediumband
                || curr_bw == Bandwidth::Wideband)
        {
            mode = OpusMode::SilkOnly;
        }

        if mode == OpusMode::CeltOnly {
            match frame_rate {
                400 | 200 | 100 | 50 => {} // Supported frame rates for CELT-only
                _ => return Err("Unsupported frame size for CELT-only mode"),
            }
        }
```

--------------------------------

### SilkResampler Initialization

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/silk/resampler.rs.html

Initializes the `SilkResampler` with input and output sample rates. It determines the resampling mode, calculates internal parameters like batch size and inverse ratio, and returns 0 on success or -1 on invalid input rates.

```rust
pub fn init(&mut self, fs_hz_in: i32, fs_hz_out: i32) -> i32 {
    *self = Self::default();

    let in_id = rate_id(fs_hz_in);
    let out_id = rate_id(fs_hz_out);

    if in_id > 2 || out_id > 5 {
        return -1;
    }

    self.input_delay = DELAY_MATRIX_DEC[in_id][out_id] as i32;
    self.fs_in_khz = fs_hz_in / 1000;
    self.fs_out_khz = fs_hz_out / 1000;
    self.batch_size = self.fs_in_khz * RESAMPLER_MAX_BATCH_SIZE_MS;

    if fs_hz_out == fs_hz_in {
        self.mode = ResamplerMode::Copy;
    } else if fs_hz_out == fs_hz_in * 2 {
        self.mode = ResamplerMode::Up2HQ;
    } else {
        self.mode = ResamplerMode::IirFir;
    }

    let up2x = if self.mode == ResamplerMode::IirFir {
        1
    } else {
        0
    };
    self.inv_ratio_q16 = ((((fs_hz_in as i64) << (14 + up2x)) / fs_hz_out as i64) << 2) as i32;

    while silk_smulww(self.inv_ratio_q16, fs_hz_out) < (fs_hz_in << up2x) {
        self.inv_ratio_q16 += 1;
    }

    0
}
```

--------------------------------

### PVQ Pre-search and Initialization

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/pvq.rs.html

Initializes PVQ-related arrays and performs a pre-search step if conditions are met. This involves calculating sums and signs of input vector elements, potentially using NEON vector instructions.

```rust
        let y2f_ptr = y2f_arr.as_mut_ptr();
        let y_ptr = y.as_mut_ptr();
        unsafe {
            for _ in 0..k {
                yy_local += 1.0;
                let mut best_num = xy_local + *abs_x_ptr;
                let mut best_den = yy_local + *y2f_ptr;
                let mut best_id = 0;

                let mut j = 1;
                while j < n {
                    let rxy = xy_local + *abs_x_ptr.add(j);
                    let ryy = yy_local + *y2f_ptr.add(j);
                    if best_den * rxy > best_num * ryy {
                        best_den = ryy;
                        best_num = rxy;
                        best_id = j;
                    }
                    j += 1;
                }

                xy_local += *abs_x_ptr.add(best_id);
                yy_local += *y2f_ptr.add(best_id);
                *y2f_ptr.add(best_id) += 2.0;
                *y_ptr.add(best_id) += 1;
            }
        }

        unsafe {
            let sign_ptr = sign_x_arr.as_ptr();
            for i in 0..n {
                let s = *sign_ptr.add(i);
                *y_ptr.add(i) = (*y_ptr.add(i) ^ -s) + s;
            }
        }
        return;
    }
```

--------------------------------

### silk_reset_decoder

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/init_decoder/index.html

Resets the Silk decoder to its initial state. This is useful for starting new audio streams or recovering from errors.

```APIDOC
## silk_reset_decoder

### Description
Resets the Silk decoder to its initial state.

### Method
(Not specified, likely a function call in Rust SDK)

### Endpoint
(Not applicable for SDK functions)

### Parameters
- **decoder** (Decoder Instance) - Required - The Silk decoder instance to reset.
```

--------------------------------

### SILK Mode Input Preparation (48kHz)

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/lib.rs.html

Prepares input for SILK mode when sampling rate is 48kHz. Involves downsampling by 2, then by 2/3.

```rust
                if self.sampling_rate == 48000 {
                    let stage1_size = frame_size / 2;
                    let mut stage1_buf = [0i16; 480];
                    silk_resampler_down2(
                        &mut self.down2_state_first,
                        &mut stage1_buf[..stage1_size],
                        input_i16,
                        frame_size as i32,
                    );
                    let silk_frame_size = stage1_size * 2 / 3;
                    self.buf_silk_input.resize(silk_frame_size, 0);
                    silk_resampler_down2_3(
                        &mut self.down2_3_state,
                        &mut self.buf_silk_input,
                        &stage1_buf[..stage1_size],
                        stage1_size as i32,
                    );
                    &self.buf_silk_input
                }
```

--------------------------------

### CeltEncoder::encode_with_budget Function

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/celt/struct.CeltEncoder.html

Encodes PCM audio data with a specified total bit budget and starting band.

```rust
pub fn encode_with_budget( &mut self, pcm: &[f32], frame_size: usize, rc: &mut RangeCoder, start_band: usize, total_bits: i32, )
```

--------------------------------

### silk_encode_prefill

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/enc_api/fn.silk_encode_prefill.html

Pre-fills the Silk encoder state with initial audio samples. This is useful for starting the encoding process with a buffer of audio data.

```APIDOC
## Function silk_encode_prefill

### Description
Pre-fills the Silk encoder state with initial audio samples. This function takes a mutable reference to the `SilkEncoderState`, a slice of `i16` audio samples, and an `_activity` integer.

### Signature
```rust
pub fn silk_encode_prefill(
    ps_enc: &mut SilkEncoderState,
    samples: &[i16],
    _activity: i32,
)
```

### Parameters
* `ps_enc`: A mutable reference to the `SilkEncoderState` structure, which holds the encoder's state.
* `samples`: A slice of `i16` representing the audio samples to pre-fill.
* `_activity`: An integer representing activity level, currently unused in this function signature (indicated by the underscore prefix).
```

--------------------------------

### Initialize Polynomials for LPC to NLSF

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/silk/nlsf.rs.html

Initializes two polynomials, 'p' and 'q', based on input LPC coefficients ('a_q16'). These polynomials are used in the subsequent NLSF root finding process.

```rust
use crate::silk::define::MAX_LPC_ORDER;

fn silk_a2nlsf_init(a_q16: &[i32], p: &mut [i32], q: &mut [i32], dd: usize) {
    p[dd] = 1 << 16;
    q[dd] = 1 << 16;
    for k in 0..dd {
        p[k] = -a_q16[dd - k - 1] - a_q16[dd + k];
        q[k] = -a_q16[dd - k - 1] + a_q16[dd + k];
    }

    for k in (1..=dd).rev() {
        p[k - 1] -= p[k];
        q[k - 1] += q[k];
    }

    silk_a2nlsf_trans_poly(p, dd);
    silk_a2nlsf_trans_poly(q, dd);
}
```

--------------------------------

### CeltEncoder::encode_with_start_band

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/celt/struct.CeltEncoder.html

Encodes a frame of PCM audio data, allowing specification of the starting band for encoding. The output is written to a RangeCoder.

```APIDOC
## CeltEncoder::encode_with_start_band

### Description
Encodes a frame of PCM audio data, allowing specification of the starting band for encoding. The output is written to a `RangeCoder`.

### Signature
`pub fn encode_with_start_band(&mut self, pcm: &[f32], frame_size: usize, rc: &mut RangeCoder, start_band: usize)`

### Parameters
* `pcm` (&[f32]) - A slice of floating-point audio samples (PCM).
* `frame_size` (usize) - The number of samples in the frame to encode.
* `rc` (&mut RangeCoder) - A mutable reference to a `RangeCoder` to write the encoded output.
* `start_band` (usize) - The frequency band to start encoding from.
```

--------------------------------

### Qext Quantization for 2 < n <= 32 Vectors

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/pvq.rs.html

Implements qext quantization for vectors where 2 < n <= 32. It uses PVQ search with refinement, encodes pulses, and includes conditional resynthesis.

```rust
let eb = extra_bits.unwrap();
let mut up_y = [0i32; 32];
let mut refine = [0i32; 32];
let _yy = pvq_search_qext(x, y, &mut up_y, &mut refine, k, eb, n);
let mask = extract_collapse_mask(&up_y, n, stride);
encode_pulses(y, n as u32, k as u32, rc);

let up = (1 << eb) - 1;
for i in 0..n - 1 {
    ec_enc_refine(rc, refine[i], up, eb);
}

if y[n - 1] == 0 {
    rc.enc_bits((up_y[n - 1] < 0) as u32, 1);
}

if resynth {
    #[cfg(target_arch = "aarch64")]
    unsafe {
        alg_quant_resynth_neon(&up_y, x, n, gain);
    }
    #[cfg(not(target_arch = "aarch64"))]
    alg_quant_resynth_scalar(&up_y, x, n, gain);
    exp_rotation(x, n, -1, stride, k, spread);
}
return mask
```

--------------------------------

### Initialize SilkResampler

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/resampler/struct.SilkResampler.html

Initializes a SilkResampler instance with input and output sample rates.

```rust
pub fn init(&mut self, fs_hz_in: i32, fs_hz_out: i32) -> i32
```

--------------------------------

### CeltDecoder::decode_with_start_band

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/celt/struct.CeltDecoder.html

Decodes a frame of compressed audio data, starting decoding from a specified band. Returns the number of samples decoded.

```rust
pub fn decode_with_start_band( &mut self, compressed: &[u8], frame_size: usize, pcm: &mut [f32], start_band: usize, ) -> usize
```

--------------------------------

### Get Fast Tell (tell_fast)

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/range_coder.rs.html

Returns the total number of bits that have been encoded, providing a quick estimate of the coder's progress.

```rust
    #[inline(always)]
    pub fn tell_fast(&self) -> i32 {
        self.nbits_total
    }

```

--------------------------------

### silk_setup_fs Function Signature

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/silk/control_codec/fn.silk_setup_fs.html

This is the function signature for silk_setup_fs. It takes a mutable reference to SilkEncoderState, the sampling frequency in kHz, and the packet size in milliseconds. It returns an integer status code.

```rust
pub fn silk_setup_fs(
    ps_enc: &mut SilkEncoderState,
    fs_khz: i32,
    packet_size_ms: i32,
) -> i32
```

--------------------------------

### Quantization Partitioning Logic

Source: https://docs.rs/opus-rs/0.1.17/src/opus_rs/bands.rs.html

This snippet demonstrates the logic for partitioning and quantizing bits for mid and side channels. It handles cases where lowband data is present or absent, and rebalances bits between channels based on their characteristics and remaining bit budget. Use this when performing channel-specific quantization.

```rust
let mbits = (0).max((b_mut - delta) / 2).min(b_mut);
        let mut sbits = b_mut - mbits;
        let mut mbits = mbits;

        let mut rebalance = ctx.remaining_bits;
        let mut cm;

        if mbits >= sbits {
            if let Some(lb) = lowband {
                let (lb_mid, lb_side) = lb.split_at_mut(mid);
                cm = quant_partition(
                    ctx,
                    x_mid,
                    mid,
                    mbits,
                    b_blocks,
                    Some(lb_mid),
                    lm,
                    gain * (sctx.imid as f32 / 32768.0),
                    fill_mut,
                );
                rebalance = mbits - (rebalance - ctx.remaining_bits);
                if rebalance > (3 << 3) && sctx.itheta != 0 {
                    sbits += rebalance - (3 << 3);
                }
                cm |= quant_partition(
                    ctx,
                    x_side,
                    mid,
                    sbits,
                    b_blocks,
                    Some(lb_side),
                    lm,
                    gain * (sctx.iside as f32 / 32768.0),
                    fill_mut >> b_blocks,
                ) << (b0 >> 1);
            } else {
                cm = quant_partition(
                    ctx,
                    x_mid,
                    mid,
                    mbits,
                    b_blocks,
                    None,
                    lm,
                    gain * (sctx.imid as f32 / 32768.0),
                    fill_mut,
                );
                rebalance = mbits - (rebalance - ctx.remaining_bits);
                if rebalance > (3 << 3) && sctx.itheta != 0 {
                    sbits += rebalance - (3 << 3);
                }
                cm |= quant_partition(
                    ctx,
                    x_side,
                    mid,
                    sbits,
                    b_blocks,
                    None,
                    lm,
                    gain * (sctx.iside as f32 / 32768.0),
                    fill_mut >> b_blocks,
                ) << (b0 >> 1);
            }
        } else if let Some(lb) = lowband {
            let (lb_mid, lb_side) = lb.split_at_mut(mid);
            cm = quant_partition(
                ctx,
                x_side,
                mid,
                sbits,
                b_blocks,
                Some(lb_side),
                lm,
                gain * (sctx.iside as f32 / 32768.0),
                fill_mut >> b_blocks,
            ) << (b0 >> 1);
            rebalance = sbits - (rebalance - ctx.remaining_bits);
            if rebalance > (3 << 3) && sctx.itheta != 16384 {
                mbits += rebalance - (3 << 3);
            }
            cm |= quant_partition(
                ctx,
                x_mid,
                mid,
                mbits,
                b_blocks,
                Some(lb_mid),
                lm,
                gain * (sctx.imid as f32 / 32768.0),
                fill_mut,
            );
        } else {
            cm = quant_partition(
                ctx,
                x_side,
                mid,
                sbits,
                b_blocks,
                None,
                lm,
                gain * (sctx.iside as f32 / 32768.0),
                fill_mut >> b_blocks,
            ) << (b0 >> 1);
            rebalance = sbits - (rebalance - ctx.remaining_bits);
            if rebalance > (3 << 3) && sctx.itheta != 16384 {
                mbits += rebalance - (3 << 3);
            }
            cm |= quant_partition(
                ctx,
                x_mid,
                mid,
                mbits,
                b_blocks,
                None,
                lm,
                gain * (sctx.imid as f32 / 32768.0),
                fill_mut,
            );
        }
        cm
```

--------------------------------

### Get Default CeltMode

Source: https://docs.rs/opus-rs/0.1.17/opus_rs/modes/fn.default_mode.html

Returns a static reference to the default CeltMode configuration. This is useful for initializing Opus encoders or decoders with standard settings.

```rust
pub fn default_mode() -> &'static CeltMode
```
Tokens:
Raw