API Reference

Encoder

class ruopus.OpusEncoder(channels, *, complexity=10, bitrate=None, dtx=False, bandwidth=Ellipsis, signal=Ellipsis, application=Ellipsis, max_bandwidth=Ellipsis, inband_fec=False, packet_loss_perc=0)

Bases: object

An Opus encoder for a single stream at 48 kHz.

Encodes one frame of interleaved 48 kHz float32 PCM (a 1-D interleaved array, or a 2-D (frames, channels) array) into an Opus packet returned as bytes. Configuration is exposed as properties (complexity, bitrate, dtx, bandwidth, signal, application, max_bandwidth); the encoder is stateful, so feed it consecutive frames from one stream.

Parameters:

channels (int) – 1 (mono) or 2 (stereo).
complexity (int, optional) – Encode complexity 0-10 (higher is better quality and slower). Defaults to 10.
bitrate (int or None, optional) – Target bitrate in bits/s, or None for the per-mode default (CBR filling max_bytes). Defaults to None.
dtx (bool, optional) – Enable discontinuous transmission. Defaults to False.
bandwidth (Bandwidth, optional) – Coded audio bandwidth. Defaults to Bandwidth.FullBand.

Examples

>>> import numpy as np, ruopus
>>> enc = ruopus.OpusEncoder(2, bitrate=64000)
>>> frame = np.zeros((960, 2), dtype=np.float32)   # 20 ms stereo at 48 kHz
>>> packet = enc.encode(frame)

application: Coding application / latency profile (OPUS_SET_APPLICATION). Application.RestrictedLowDelay forces CELT-only coding; Application.Voip biases toward speech; Application.Audio (default) is the balanced general profile.

bandwidth: Forced coded audio bandwidth (OPUS_SET_BANDWIDTH). Setting this pins the bandwidth so encode_auto() uses it instead of choosing one from the signal; call set_auto_bandwidth() to restore automatic selection.

bandwidth_forced: Whether a bandwidth has been forced (vs automatic selection).

bitrate: Target bitrate in bits/s, or None for the per-mode default (OPUS_SET_BITRATE). For CELT this selects VBR with max_bytes as a ceiling; None restores CBR.

channels: Number of channels (1 or 2).

complexity: Encode complexity 0-10 (OPUS_SET_COMPLEXITY); higher is better quality and slower. Values above 10 are clamped.

dtx: Whether discontinuous transmission is enabled (OPUS_SET_DTX).

encode(pcm, max_bytes=1275)

Encode one frame as CELT-only.

Parameters:

pcm (numpy.ndarray) – Interleaved 48 kHz float32 PCM; 120/240/480/960 samples per channel (2.5/5/10/20 ms).
max_bytes (int, optional) – Output budget in bytes, 3..=1275. Defaults to 1275.

Returns:

The encoded Opus packet.

Return type:

bytes

Raises:

EncodeError – For an unsupported frame size or an unusable budget.

encode_auto(pcm, max_bytes=1275)

Encode one frame, automatically choosing SILK, hybrid, or CELT.

The mode is chosen per frame from a signal analysis (speech-vs-music and spectral extent) together with the signal hint, the application profile and the target bitrate, with cross-frame hysteresis. When no bandwidth is forced, the coded bandwidth is selected automatically and capped by max_bandwidth.

Parameters:

pcm (numpy.ndarray) – Interleaved 48 kHz float32 PCM in [-1, 1]: a 1-D array or a 2-D (frames, channels) array. Frames per channel must be one of 120, 240, 480, 960, 1920, 2880 (2.5-60 ms).
max_bytes (int, optional) – Output budget in bytes, 3..=1275. Defaults to 1275.

Returns:

The encoded Opus packet (including its TOC byte).

Return type:

bytes

Raises:

EncodeError – For an unsupported frame size or an unusable budget.

encode_hybrid(pcm, max_bytes=1275)

Encode one frame as hybrid (SILK low band + CELT high band).

Parameters:

pcm (numpy.ndarray) – Interleaved 48 kHz float32 PCM; 480/960 samples per channel (10/20 ms).
max_bytes (int, optional) – Output budget in bytes, 3..=1275. Defaults to 1275.

Returns:

The encoded Opus packet.

Return type:

bytes

Raises:

EncodeError – For an unsupported frame size or an unusable budget.

encode_silk(pcm, max_bytes=1275)

Encode one frame as SILK-only (speech).

Parameters:

pcm (numpy.ndarray) – Interleaved 48 kHz float32 PCM; 480/960/1920/2880 samples per channel (10/20/40/60 ms).
max_bytes (int, optional) – Output budget in bytes, 3..=1275. Defaults to 1275.

Returns:

The encoded Opus packet.

Return type:

bytes

Raises:

EncodeError – For an unsupported frame size or an unusable budget.

final_range

The range coder state after the last packet (OPUS_GET_FINAL_RANGE).

A conformant decoder finishes the same packet with this exact value.

force_channels

Force the coded channel count (OPUS_SET_FORCE_CHANNELS).

None (OPUS_AUTO, the default) codes the configured channels. 1 on a stereo encoder downmixes the stereo input to mono (the (l + r) / 2 average) and codes mono packets; the configured channel count and the input layout are unchanged. 2 on a mono encoder is a no-op. Switching the coded count rebuilds the coders.

Raises:: ValueError – If set to a value other than None, 1, or 2.

inband_fec: In-band forward error correction (OPUS_SET_INBAND_FEC). When enabled, SILK-mode packets carry a redundant LBRR copy of the previous packet’s frame(s), so a lost packet can be recovered from its successor via OpusDecoder.decode_fec().

lookahead

The encoder’s algorithmic delay in samples at 48 kHz (OPUS_GET_LOOKAHEAD).

The number of leading output samples to skip (pre_skip) to align the decoded output with the input. 120 for the default fullband CELT mode (the MDCT overlap), measured from a unit-impulse round trip.

max_bandwidth: Ceiling on automatic bandwidth selection (OPUS_SET_MAX_BANDWIDTH). Has no effect while a bandwidth is forced via bandwidth.

packet_loss_perc: Expected packet-loss percentage 0-100 (OPUS_SET_PACKET_LOSS_PERC), clamped. Biases the encoder toward loss-robust coding.

reset()

Reset the encoder to its freshly-created state (OPUS_RESET_STATE).

Keeps the configuration (channels, complexity, bitrate, bandwidth, DTX) but drops all cross-frame history, so the next packet is coded as if it were the first.

set_auto_bandwidth(): Restore automatic bandwidth selection (OPUS_SET_BANDWIDTH with OPUS_AUTO): encode_auto() picks the bandwidth from the signal’s spectral content and the bitrate, capped by max_bandwidth.

signal

Signal.Voice biases the automatic mode decision toward SILK / hybrid, Signal.Music toward CELT, and Signal.Auto (default) lets the analysis decide.

Type:: Signal-content hint (OPUS_SET_SIGNAL)

vbr: Variable bitrate (OPUS_SET_VBR). True (default) makes a set bitrate a VBR target; False codes constant bitrate (a fixed byte count per CELT frame at the target rate).

Decoder

class ruopus.OpusDecoder(channels, *, sample_rate=48000)

Bases: object

An Opus decoder for a single stream.

Decodes Opus packets to interleaved PCM as a NumPy array shaped (frames, channels) (mono is (frames, 1)). The decoder is stateful: feed it consecutive packets from one stream so inter-frame state (overlap, concealment, mode transitions) stays continuous.

Parameters:

channels (int) – Output channel count, 1 (mono) or 2 (stereo).
sample_rate (int, optional) – Output sample rate in Hz; one of 48000, 24000, 16000, 12000, 8000. Defaults to 48000.

Examples

>>> import ruopus
>>> dec = ruopus.OpusDecoder(2, sample_rate=48000)
>>> pcm = dec.decode_packet(packet)        # (frames, 2) float32 in [-1, 1]

channels: Output channel count (1 or 2).

decode_fec(data, frame_size)

Decode the in-band FEC (LBRR) data of data to recover a lost packet.

Like opus_decode(..., decode_fec=1): everything except the FEC’d duration is concealed, then the recovered low-bitrate redundancy frame completes it. Falls back to plain concealment when the packet carries no usable FEC (CELT-only modes, or a shorter request).

Parameters:

data (bytes) – The next received packet, whose FEC data reconstructs the lost one.
frame_size (int) – Samples per channel of the lost frame to recover.

Returns:

Shape (frames, channels), dtype float32.

Return type:

numpy.ndarray

Raises:

PacketError – If the packet violates RFC 6716 framing.

decode_lost(frame_size)

Conceal one lost packet of frame_size samples per channel.

Like opus_decode(NULL): CELT concealment extrapolates the last pitch period; frames following SILK/hybrid packets fade to silence (SILK PLC is not yet ported). The final range of a concealed packet is 0.

Parameters:: frame_size (int) – Samples per channel to conceal, corresponding to 2.5-60 ms at the output sample rate.
Returns:: Shape (frames, channels), dtype float32.
Return type:: numpy.ndarray

decode_packet(data)

Decode one Opus packet to interleaved float32 PCM in [-1, 1].

A 0- or 1-byte payload (TOC only) is treated as DTX and concealed as one frame of the last good packet’s duration.

Parameters:: data (bytes) – One Opus packet (including its TOC byte).
Returns:: Shape (frames, channels), dtype float32.
Return type:: numpy.ndarray
Raises:: PacketError – If the packet violates RFC 6716 framing.

decode_packet_i16(data)

Decode one Opus packet to interleaved int16 PCM.

Converts exactly as opus_demo does: scale by 32768, saturate, round ties to even.

Parameters:: data (bytes) – One Opus packet (including its TOC byte).
Returns:: Shape (frames, channels), dtype int16.
Return type:: numpy.ndarray
Raises:: PacketError – If the packet violates RFC 6716 framing.

final_range

The range coder state after the last packet (OPUS_GET_FINAL_RANGE).

A conformant encoder finishes the same packet with this exact value; it is the bit-exactness oracle. Zero after a concealed packet.

sample_rate: Output sample rate in Hz.

Multistream Decoder

class ruopus.MultistreamDecoder(streams, coupled, mapping, *, sample_rate=48000)

Bases: object

A multistream Opus decoder (OpusMSDecoder, RFC 7845 §5.1.1).

Decodes streams elementary Opus streams per packet - the first coupled decoded as stereo, the rest mono - and routes their channels to the output layout through mapping. Output is interleaved PCM as a NumPy array shaped (frames, channels).

Parameters:

streams (int) – Number of elementary streams (>= 1).
coupled (int) – Number of those streams that are stereo-coupled (<= streams).
mapping (Sequence[int]) – Per-output-channel source index; 255 means a silent channel. The output channel count is len(mapping).
sample_rate (int, optional) – Output sample rate in Hz; one of 48000, 24000, 16000, 12000, 8000. Defaults to 48000.

channels: Output channel count (len(mapping)).

decode_packet(data)

Decode one multistream packet to interleaved float32 PCM.

Parameters:: data (bytes) – One multistream Opus packet (self-delimited streams followed by a standard final stream).
Returns:: Shape (frames, channels), dtype float32.
Return type:: numpy.ndarray
Raises:: PacketError – If any elementary stream is malformed or they disagree on duration.

sample_rate: Output sample rate in Hz.

Ogg Opus

ruopus.encode_ogg_opus(pcm, channels, bitrate)

Encode interleaved 48 kHz float32 PCM to a complete in-memory Ogg Opus file.

Parameters:

pcm (numpy.ndarray) – Interleaved 48 kHz float32 PCM (1-D, or 2-D (frames, channels)).
channels (int) – 1 (mono) or 2 (stereo).
bitrate (int) – Target bitrate in bits/s.

Returns:

A complete Ogg Opus file.

Return type:

bytes

ruopus.decode_ogg_opus(data)

Decode a complete in-memory Ogg Opus file (RFC 7845 §4): pre-skip removal, end trimming, and the OpusHead output gain applied.

Only channel mapping family 0 (mono/stereo) is supported until a multistream Ogg decoder exists.

Parameters:: data (bytes) – A complete Ogg Opus file.
Returns:: Interleaved 48 kHz float32 PCM shaped (frames, channels) and the parsed identification header.
Return type:: tuple[numpy.ndarray, OpusHead]
Raises:: OggError – For a malformed container, a bad packet, or an unsupported mapping.

class ruopus.OpusHead

Bases: object

The identification header of an Ogg Opus stream (RFC 7845 §5.1).

The channel-mapping table is flattened onto this object: family-0 streams report mapping_family 0 with the optional fields None; other families expose their stream/coupled counts and per-channel table.

channel_count: Output channel count (never zero).

channel_mapping: The per-channel mapping table (None for family 0).

coupled_count: Number of coupled (stereo) streams (None for family 0).

input_sample_rate: Sample rate of the original input in Hz (metadata only; 0 = unspecified).

mapping_family

0 for mono/stereo, otherwise the table family.

Type:: Channel-mapping family

output_gain_q8: Output gain in Q7.8 dB, applied by players on top of decoder output.

pre_skip: Samples at 48 kHz to discard from the start of decoder output.

stream_count: Number of encoded streams (None for family 0).

to_bytes(): Serialise this header to an OpusHead packet.

version: Encapsulation version (1 for this specification).

Packet Introspection

class ruopus.Packet(data)

Bases: object

A parsed Opus packet: its TOC plus the compressed frames (RFC 6716 §3).

Behaves as a read-only sequence of frames: len(packet) is the frame count and packet[i] is frame i as bytes (a frame may be empty, signalling DTX). Construct with Packet(data) to parse a standard packet, or parse_self_delimited() for the self-delimiting framing used by multistream payloads.

duration: Total audio duration of the packet, as a datetime.timedelta.

frames: The compressed frames, in order, as bytes (some may be empty).

padding: Bytes of Opus padding the packet carried (code 3 only).

static parse_self_delimited(data)

Parse one self-delimited Opus packet (RFC 6716 Appendix B).

Returns the packet and the number of bytes it consumed, so the caller can continue parsing the next stream in a multistream payload.

Raises:: PacketError – If the packet is malformed.

toc: The table-of-contents byte.

class ruopus.Toc(byte)

Bases: object

The table-of-contents byte heading every Opus packet (RFC 6716 §3.1).

A value type wrapping the raw byte; all 256 values are valid TOCs.

bandwidth: The audio bandwidth for this configuration.

byte: The raw TOC byte.

channels: The number of channels (1 or 2).

config

the top five bits.

Type:: The configuration number (0..=31)

frame_count_code

the bottom two bits.

Type:: The frame-count code (0..=3)

frame_size: The frame size for this configuration.

static from_parts(config, stereo, frame_count_code)

Build a TOC byte from its three fields.

Raises:: ValueError – If config > 31 or frame_count_code > 3.

mode: The operating mode for this configuration.

stereo: True for stereo, False for mono.

Enumerations

class ruopus.Mode

Bases: object

Operating mode of an Opus frame (RFC 6716 §3.1).

CeltOnly = Mode.CeltOnly

Hybrid = Mode.Hybrid

SilkOnly = Mode.SilkOnly

class ruopus.Bandwidth

Bases: object

Audio bandwidth of an Opus frame (RFC 6716 §2.1.3, §3.1).

FullBand = Bandwidth.FullBand

MediumBand = Bandwidth.MediumBand

NarrowBand = Bandwidth.NarrowBand

SuperWideBand = Bandwidth.SuperWideBand

WideBand = Bandwidth.WideBand

audio_bandwidth_hz: The audio bandwidth in Hz (the highest frequency reproduced).

sample_rate_hz: The effective sample rate in Hz for this bandwidth.

class ruopus.FrameSize

Bases: object

Duration of one Opus frame (RFC 6716 §3.1, Table 2).

Ms10 = FrameSize.Ms10

Ms20 = FrameSize.Ms20

Ms2_5 = FrameSize.Ms2_5

Ms40 = FrameSize.Ms40

Ms5 = FrameSize.Ms5

Ms60 = FrameSize.Ms60

duration: Frame duration as a datetime.timedelta.

samples_per_channel_48k: Number of samples per channel in one frame at 48 kHz.

tenth_ms: Frame duration in tenths of a millisecond (exact for 2.5 ms).

class ruopus.Signal

Bases: object

Signal-content hint for the automatic mode decision (OPUS_SET_SIGNAL).

Biases OpusEncoder.encode_auto()’s speech-vs-music classification.

Auto = Signal.Auto

Music = Signal.Music

Voice = Signal.Voice

class ruopus.Application

Bases: object

Coding application / latency profile (OPUS_SET_APPLICATION).

Audio = Application.Audio

RestrictedLowDelay = Application.RestrictedLowDelay

Voip = Application.Voip

Exceptions

class ruopus.OpusError

Bases: Exception

Base class for every error raised by ruopus.

Catch this to handle any codec failure regardless of its specific kind.

class ruopus.EncodeError

Bases: OpusError

Raised when encoding fails: an unsupported frame size, or an output budget outside 3..=1275 bytes that the packet could not be made to fit.

Corresponds to the Rust ruopus::EncodeError.

class ruopus.PacketError

Bases: OpusError

Raised when an Opus packet is malformed (RFC 6716 §3.4 rules R1-R7).

Corresponds to the Rust ruopus::PacketError.

class ruopus.OggError

Bases: OpusError

Raised when decoding an Ogg Opus stream fails (bad container, bad packet, or an unsupported channel-mapping family).

Corresponds to the Rust ruopus::OggDecodeError.

Low-Level Module

Direct access to the SILK, LPC, and CELT layers beneath the Opus packet codec. Advanced building blocks; ordinary use should prefer the top-level OpusEncoder / OpusDecoder.

class ruopus.lowlevel.CeltDecoder(channels, *, sample_rate=48000)

Bases: object

The CELT decoder (celt_decoder).

Parameters:

channels (int) – 1 (mono) or 2 (stereo).
sample_rate (int, optional) – Output sample rate in Hz; one of 48000, 24000, 16000, 12000, 8000. Defaults to 48000.

channels: Number of channels (1 or 2).

decode_lost(frame_size, start, end)

Conceal one lost CELT frame of frame_size samples per channel.

Parameters:

frame_size (int) – Samples per channel to conceal (at 48 kHz).
start (int) – First coded band.
end (int) – One past the last coded band.

Returns:

Shape (frames, channels), dtype float32.

Return type:

numpy.ndarray

final_range: The range coder state after the last decode (OPUS_GET_FINAL_RANGE).

sample_rate: Output sample rate in Hz.

class ruopus.lowlevel.CeltEncoder(channels=1, *, complexity=10, bitrate=None)

Bases: object

The CELT encoder (celt_encoder).

Parameters:

channels (int, optional) – 1 (mono) or 2 (stereo). Defaults to 1.
complexity (int, optional) – Encode complexity 0-10. Defaults to 10.
bitrate (int or None, optional) – Target VBR bitrate in bits/s, or None for CBR. Defaults to None.

bitrate: Target VBR bitrate in bits/s, or None for CBR.

channels: Number of channels (1 or 2).

complexity: Encode complexity 0-10.

encode_frame(pcm, nb_bytes)

Encode one CELT frame to a raw frame body (no Opus TOC).

Parameters:

pcm (numpy.ndarray) – Interleaved 48 kHz float32 PCM (1-D, or 2-D (frames, channels)); 120/240/480/960 samples per channel.
nb_bytes (int) – Output budget in bytes.

Returns:

The coded CELT frame body.

Return type:

bytes

encode_frame_bw(pcm, nb_bytes, end)

Encode one CELT frame, coding only the first end bands.

Parameters:

pcm (numpy.ndarray) – Interleaved 48 kHz float32 PCM (1-D, or 2-D (frames, channels)).
nb_bytes (int) – Output budget in bytes.
end (int) – Number of coded CELT bands.

Returns:

The coded CELT frame body.

Return type:

bytes

final_range: The range coder state after the last encode (OPUS_GET_FINAL_RANGE).

class ruopus.lowlevel.LpcCoefficients

Bases: object

LPC prediction coefficients returned by lpc_analysis() or levinson_durbin().

coeffs: Prediction coefficients a[0..order] such that e[n] = x[n] - a[0]*x[n-1] - ... - a[order-1]*x[n-order].

order: Number of prediction coefficients.

ruopus.lowlevel.compute_autocorrelation(sig, order)

Compute the biased autocorrelation sequence R[0..=order] of sig.

Parameters:

sig (numpy.ndarray) – 1-D float32 input signal.
order (int) – Maximum lag (output length is order + 1).

Returns:

1-D float64 array of shape (order + 1,).

Return type:

numpy.ndarray

ruopus.lowlevel.estimate_pitch(sig, min_lag=20, max_lag=200)

Estimate the fundamental pitch lag of sig by peak-picking the normalized autocorrelation in [min_lag, max_lag].

Parameters:

sig (numpy.ndarray) – 1-D float32 input signal.
min_lag (int, optional) – Minimum lag to consider (default 20).
max_lag (int, optional) – Maximum lag to consider (default 200).

Returns:

Estimated pitch lag in samples, or min_lag if the signal is silent.

Return type:

int

ruopus.lowlevel.levinson_durbin(ac, order)

Solve the Yule-Walker equations via the Levinson-Durbin recursion.

Parameters:

ac (numpy.ndarray) – 1-D float64 autocorrelation sequence of length >= order + 1 (as returned by compute_autocorrelation()).
order (int) – AR model order.

Returns:

None when the autocorrelation matrix is singular or the filter becomes unstable during the recursion.

Return type:

LpcCoefficients or None

ruopus.lowlevel.lpc_analysis(sig, order)

Estimate LPC coefficients of order order from signal sig.

Uses the autocorrelation method (Yule-Walker + Levinson-Durbin) with a small regularisation factor (1e-4 * R[0]) to ensure positive-definiteness in ill-conditioned cases (e.g. pure tones at high order).

Parameters:

sig (numpy.ndarray) – 1-D float32 input signal.
order (int) – AR model order.

Return type:

LpcCoefficients

Raises:

ValueError – If the autocorrelation matrix is singular even after regularisation.

ruopus.lowlevel.lpc_residual(sig, coeffs)

Apply the LPC analysis filter to sig, returning the prediction residual.

e[n] = sig[n] - coeffs[0]*sig[n-1] - ... - coeffs[p-1]*sig[n-p]

Samples before the start of sig are treated as zero.

ruopus.lowlevel.lpc_residual_stateful(sig, coeffs)

Stateful LPC analysis filter: returns (residual, state).

state is a Python list of the last order input samples, suitable for passing to a subsequent lpc_synthesis_stateful() call.

Parameters:

sig (numpy.ndarray) – 1-D float32 input signal.
coeffs (LpcCoefficients) – LPC coefficients.

Returns:

Residual array (float32) and filter state (list of float).

Return type:

tuple[numpy.ndarray, list[float]]

ruopus.lowlevel.lpc_synthesis(res, coeffs)

Apply the LPC synthesis filter to res, reconstructing the signal.

x[n] = res[n] + coeffs[0]*x[n-1] + ... + coeffs[p-1]*x[n-p]

Samples before the start of res are treated as zero.

ruopus.lowlevel.lpc_synthesis_stateful(res, coeffs, state=None)

Stateful LPC synthesis filter: returns (signal, state).

Parameters:

res (numpy.ndarray) – 1-D float32 residual.
coeffs (LpcCoefficients) – LPC coefficients.
state (list[float], optional) – Filter state from a previous call (length must equal coeffs.order).

Returns:

Reconstructed signal (float32) and updated filter state.

Return type:

tuple[numpy.ndarray, list[float]]

ruopus.lowlevel.ltp_residual(sig, lag, gain)

Long-term prediction residual: subtract a single-tap LTP predictor.

e[n] = sig[n] - gain * sig[n - lag]

Samples before the start of sig (index < lag) are treated as zero.

Parameters:

sig (numpy.ndarray) – 1-D float32 input signal.
lag (int) – Pitch lag in samples.
gain (float) – LTP gain coefficient.

Returns:

1-D float32 LTP residual, same shape as sig.

Return type:

numpy.ndarray

ruopus.lowlevel.ltp_synthesis(res, lag, gain)

Long-term prediction synthesis: reconstruct a signal from an LTP residual.

x[n] = res[n] + gain * x[n - lag]

Parameters:

res (numpy.ndarray) – 1-D float32 LTP residual.
lag (int) – Pitch lag in samples.
gain (float) – LTP gain coefficient.

Returns:

1-D float32 reconstructed signal, same shape as res.

Return type:

numpy.ndarray

class ruopus.lowlevel.DecControl(channels_internal, channels_api, internal_sample_rate, api_sample_rate, payload_size_ms)

Bases: object

Decoder control parameters for the low-level SILK decoder (silk_DecControlStruct).

Parameters:

channels_internal (int) – Channels coded in the bitstream (1 or 2).
channels_api (int) – Channels to produce (1 or 2).
internal_sample_rate (int) – SILK internal rate in Hz (8000, 12000, or 16000).
api_sample_rate (int) – Output rate in Hz.
payload_size_ms (int) – Packet duration in ms (10, 20, 40, or 60).

api_sample_rate

channels_api

channels_internal

internal_sample_rate

payload_size_ms

class ruopus.lowlevel.SilkDecoder

Bases: object

The SILK decoder for one Opus stream (silk_decoder).

The range-coder plumbing is handled internally: decode() takes the raw payload bytes directly.

decode(data, ctl, new_packet=True)

Decode a SILK payload to int16 PCM shaped (frames, channels_api).

Parameters:

data (bytes) – The SILK payload.
ctl (DecControl) – Decoder control parameters.
new_packet (bool, optional) – Whether this begins a new packet. Defaults to True.

decode_fec(data, ctl, new_packet=True)

Decode in-band FEC (LBRR) from a SILK payload.

Parameters:

data (bytes) – The payload whose FEC data is decoded.
ctl (DecControl) – Decoder control parameters.
new_packet (bool, optional) – Whether this begins a new packet. Defaults to True.

decode_lost(ctl)

Conceal one lost SILK frame.

Parameters:: ctl (DecControl) – Decoder control parameters.

class ruopus.lowlevel.SilkEncoder(fs_khz, nb_subfr, *, bitrate=25000, complexity=10)

Bases: object

The SILK encoder for one mono stream (silk_encoder).

Parameters:

fs_khz (int) – Internal sample rate in kHz: 8, 12, or 16.
nb_subfr (int) – Subframes per frame: 4 for 20 ms, 2 for 10 ms.
bitrate (int, optional) – Target bitrate in bits/s. Defaults to 25000.
complexity (int, optional) – Encode complexity 0-10. Defaults to 10.

bitrate: Target bitrate in bits/s.

complexity: Encode complexity 0-10 (pitch-search depth).

encode(pcm)

Encode int16 PCM (a whole number of frames) into a SILK payload.

Parameters:: pcm (numpy.ndarray) – 1-D int16 PCM at the internal rate; length a multiple of one frame (nb_subfr * 5 * fs_khz samples).
Returns:: The SILK payload.
Return type:: bytes

encode_capped(pcm, max_payload)

Encode into at most max_payload bytes, lowering the rate to fit.

Parameters:

pcm (numpy.ndarray) – 1-D int16 PCM (a whole number of frames).
max_payload (int) – Byte ceiling for the payload.

Returns:

The payload, or None if even the minimum bitrate cannot fit.

Return type:

bytes or None

final_range: The range coder state after the last encode() (OPUS_GET_FINAL_RANGE).

class ruopus.lowlevel.SilkStereoEncoder(fs_khz, nb_subfr, *, bitrate=25000, complexity=10)

Bases: object

The SILK encoder for one stereo stream (silk stereo encoder).

Parameters:

fs_khz (int) – Internal sample rate in kHz: 8, 12, or 16.
nb_subfr (int) – Subframes per frame: 4 for 20 ms, 2 for 10 ms.
bitrate (int, optional) – Target bitrate in bits/s. Defaults to 25000.
complexity (int, optional) – Encode complexity 0-10. Defaults to 10.

bitrate: Target bitrate in bits/s.

complexity: Encode complexity 0-10.

encode(left, right)

Encode left/right int16 channels into a SILK stereo payload.

Parameters:

left (numpy.ndarray) – 1-D int16 PCM at the internal rate, equal length, a whole number of frames.
right (numpy.ndarray) – 1-D int16 PCM at the internal rate, equal length, a whole number of frames.

Returns:

The SILK stereo payload.

Return type:

bytes