### Install opuslib-next

Source: https://github.com/kalicyh/opuslib-next/blob/master/README.md

Install the library using pip. This is the primary method for end-users.

```bash
pip install opuslib-next
```

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

### Encoder CTL Usage Example

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Demonstrates how to use the encoder CTL interface to get and set the bitrate of an Opus encoder. Ensure opuslib_next.api.encoder and opuslib_next.api.ctl are imported.

```python
import opuslib_next.api.encoder
import opuslib_next.api.ctl

encoder_state = opuslib_next.api.encoder.create_state(48000, 2, 2049)

# Get current bitrate
bitrate = opuslib_next.api.encoder.encoder_ctl(
    encoder_state, 
    opuslib_next.api.ctl.get_bitrate
)

# Set new bitrate
opuslib_next.api.encoder.encoder_ctl(
    encoder_state,
    opuslib_next.api.ctl.set_bitrate,
    128000
)
```

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

### application

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Gets or sets the application type of the encoder after initialization. This can be used to switch the encoder's mode, for example, between voice and music.

```APIDOC
## application

### Description
Get or set the application type after initialization.

### Read/Write
Read/write

### Type
int
```

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

### application

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Get or set application type.

```APIDOC
## application

### Description
Get or set application type.

### Type
`int`

### Read/Write
Read/write
```

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

### application

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-encoder.md

Read/write. Get or set application type.

```APIDOC
## application

### Description
Get or set application type.

### Read/write
`application: int`
```

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

### Initialize ProjectionDecoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-decoder.md

Instantiate a ProjectionDecoder with sample rate, channel configuration, stream information, and the demixing matrix. Ensure the demixing matrix is correctly formatted for your spatial audio setup.

```python
import opuslib_next

demixing_matrix = bytes([...])  # Ambisonics or spatial audio matrix
decoder = opuslib_next.ProjectionDecoder(
    fs=48000,
    channels=4,
    streams=2,
    coupled_streams=1,
    demixing_matrix=demixing_matrix
)
```

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

### Get Opuslib-Next Version Information

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/QUICK_START.md

Use this function to retrieve the version string of the libopus library. Ensure Python 3.10+ is installed.

```python
import opuslib_next

print(opuslib_next.api.info.get_version_string())
```

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

### Multi-Channel (5.1) Encoder Setup

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/README.md

Set up an Opus multi-stream encoder for 5.1 surround sound, specifying the sample rate, channel count, and channel mapping.

```python
mapping = [0, 1, 2, 3, 4, 5]
encoder = opuslib_next.MultiStreamEncoder(
    48000, 6, 4, 2, mapping, 'audio'
)
```

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

### Real-Time VoIP Encoder and Decoder Setup

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/README.md

Configure an Opus encoder for real-time VoIP with specific sample rate, channels, and mode. Also, set up a decoder for the same configuration.

```python
encoder = opuslib_next.Encoder(16000, 1, 'voip')
encoder.bitrate = 32000
encoder.inband_fec = 1
encoder.dtx = 1

decoder = opuslib_next.Decoder(16000, 1)
```

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

### Music Streaming Encoder Setup

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/README.md

Configure an Opus encoder for music streaming with a higher sample rate, stereo channels, and optimized settings for audio quality.

```python
encoder = opuslib_next.Encoder(48000, 2, 'audio')
encoder.bitrate = 128000
encoder.complexity = 10
encoder.vbr = 1
```

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

### Spatial Audio (Ambisonics) Encoder Setup

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/README.md

Configure an Opus projection encoder for spatial audio, specifically for Order-1 Ambisonics, defining the sample rate and channel count.

```python
encoder = opuslib_next.ProjectionEncoder(
    48000, 4, 2, 'audio'  # Order-1 Ambisonics (4 channels)
)
```

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

### CTL Helper Objects (Python)

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/types.md

Callable objects that encapsulate CTL request logic for Opus library settings. These are created by `query()`, `get()`, and `ctl_set()` functions to abstract the underlying CTL mechanism.

```python
reset_state
get_final_range
get_bandwidth
get_pitch
set_lsb_depth
get_lsb_depth
set_gain
get_gain
set_complexity
get_complexity
set_bitrate
get_bitrate
set_vbr
get_vbr
set_vbr_constraint
get_vbr_constraint
set_force_channels
get_force_channels
set_max_bandwidth
get_max_bandwidth
set_bandwidth
set_signal
get_signal
set_application
get_application
get_sample_rate
get_lookahead
set_inband_fec
get_inband_fec
set_packet_loss_perc
get_packet_loss_perc
set_dtx
get_dtx
get_demixing_matrix_gain
get_demixing_matrix_size
get_demixing_matrix
```

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

### lsb_depth Property

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/decoder.md

Read/write. Get or set the configured signal depth (in bits). Higher values improve quality at the cost of bandwidth.

```APIDOC
## lsb_depth Property

### Description
Read/write. Get or set the configured signal depth (in bits). Higher values improve quality at the cost of bandwidth.

### Parameters
#### Set Value
- **lsb_depth** (int) - The signal depth in bits.

### Returns
- int: The current signal depth in bits.
```

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

### Get libopus Version String

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Retrieve the version string of the linked libopus library. This is useful for diagnostics and ensuring compatibility.

```python
version = opuslib_next.api.info.get_version_string()
print(f"Using {version}")
```

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

### max_bandwidth

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Gets or sets the maximum allowed bandwidth for the encoder. Possible values include BANDWIDTH_NARROWBAND, BANDWIDTH_MEDIUMBAND, BANDWIDTH_WIDEBAND, BANDWIDTH_SUPERWIDEBAND, and BANDWIDTH_FULLBAND.

```APIDOC
## max_bandwidth

### Description
Maximum allowed bandwidth. Values: BANDWIDTH_NARROWBAND, BANDWIDTH_MEDIUMBAND, BANDWIDTH_WIDEBAND, BANDWIDTH_SUPERWIDEBAND, BANDWIDTH_FULLBAND.

### Read/Write
Read/write

### Type
int
```

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

### Get Packet Samples Per Frame

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Calculates the number of samples per channel for frames within an Opus packet, given the sample rate.

```python
packet_get_samples_per_frame(data: bytes, fs: int) -> int
```

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

### CTL Interface Helper Functions

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Helper functions to create CTL request objects for various Opus decoder operations. These include query, get, and set operations for parameters like bitrate, bandwidth, and complexity.

```python
# Query operations (no return value)
reset_state = query(RESET_STATE)

# Get operations (return value)
get_final_range = get(GET_FINAL_RANGE_REQUEST, ctypes.c_uint)
get_bandwidth = get(GET_BANDWIDTH_REQUEST, ctypes.c_int)
get_bitrate = get(GET_BITRATE_REQUEST, ctypes.c_int)

# Set operations (no return value)
set_bitrate = ctl_set(SET_BITRATE_REQUEST)
set_complexity = ctl_set(SET_COMPLEXITY_REQUEST)
set_gain = ctl_set(SET_GAIN_REQUEST)

# Special function for matrix retrieval
def get_demixing_matrix(func, obj, size) -> bytes
```

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

### Check Library Status and Version

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/errors.md

Use this snippet to get the libopus version string and check if an operation succeeded by comparing the result code to opuslib_next.OK. Ensure opuslib_next is imported.

```python
import opuslib_next
import opuslib_next.api.info

# Get libopus version
version = opuslib_next.api.info.get_version_string()
print(f"libopus version: {version}")

# Check if error code is OK
if result_code == opuslib_next.OK:
    print("Operation succeeded")
```

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

### Get/Set LSB Depth

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/decoder.md

Read/write. Get or set the configured signal depth in bits. Higher values generally improve audio quality but may increase bandwidth usage.

```python
lsb_depth: int
```

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

### vbr

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Gets or sets the variable bitrate (VBR) mode. A value of 0 indicates Constant Bitrate (CBR), while a value of 1 enables VBR. VBR typically offers superior audio quality at reduced average bitrates.

```APIDOC
## vbr

### Description
Variable bitrate mode (0 for CBR, 1 for VBR). VBR provides better quality at lower average bitrates.

### Read/Write
Read/write

### Type
int
```

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

### Development Workflow with uv

Source: https://github.com/kalicyh/opuslib-next/blob/master/README.md

Manage development dependencies, run tests, benchmarks, and build the project using uv.

```bash
uv sync --dev
```

```bash
uv run pytest
```

```bash
uv run python benchmarks/compare_versions.py --baseline-version 1.1.5
```

```bash
uv build
```

```bash
uv publish
```

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

### Handle Opus Decoding Errors

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/QUICK_START.md

Safely decodes Opus data by wrapping the decode operation in a try-except block to catch potential `OpusError` exceptions. This example specifically checks for and handles invalid packet errors.

```python
try:
    pcm = decoder.decode(opus_data, 960)
except opuslib_next.OpusError as e:
    if e.code == opuslib_next.INVALID_PACKET:
        print(f"Corrupted packet: {e}")
    else:
        raise
```

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

### Opuslib-Next Initialization Flow

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/QUICK_START.md

Illustrates the initialization process for opuslib-next, showing how the library finds the Opus library and creates encoder states.

```python
import opuslib_next
  └─> opuslib_next/api/__init__.py
      └─> find_library('opus') or platform-specific paths
      └─> ctypes.CDLL(lib_location) → libopus

Encoder.__init__()
  └─> opuslib_next.api.encoder.create_state()
      └─> libopus.opus_encoder_create()
      └─> checks result_code == OK
```

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

### Get/Set Gain

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/decoder.md

Read/write. Get or set the decoder gain adjustment in centibels (dB/100). The range is typically -32768 to 32767. Example shows reducing gain by 15 dB.

```python
gain: int
```

```python
decoder.gain = -1500  # Reduce gain by 15 dB
print(decoder.gain)
```

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

### Basic Audio Encoding and Decoding with opuslib-next

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/QUICK_START.md

This snippet demonstrates the fundamental usage of opuslib-next for encoding PCM audio data into Opus packets and then decoding those packets back into PCM. It covers the creation of encoder and decoder instances, setting the bitrate, and performing the encode/decode operations. Ensure you have PCM data ready for encoding and understand the frame size requirements.

```python
import opuslib_next

# Create encoder
encoder = opuslib_next.Encoder(fs=48000, channels=2, application='audio')
encoder.bitrate = 128000  # 128 kbps

# Encode 16-bit PCM to Opus
pcm_data = b'...'  # 16-bit signed audio samples
opus_packet = encoder.encode(pcm_data, frame_size=960)

# Create decoder
decoder = opuslib_next.Decoder(fs=48000, channels=2)

# Decode Opus back to PCM
decoded_pcm = decoder.decode(opus_packet, frame_size=960)
```

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

### Configure Publish Credentials

Source: https://github.com/kalicyh/opuslib-next/blob/master/README.md

Configure PyPI publish credentials using environment variables like UV_PUBLISH_TOKEN or uv auth.

```bash
uv auth
```

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

### Get Pitch

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/decoder.md

Read-only. Get the pitch of the last decoded frame, if available. Returns 0 if pitch information is not present in the frame.

```python
pitch: int
```

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

### Get Bandwidth

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/decoder.md

Read-only. Get the bandwidth of the last decoded frame. Returns one of the predefined bandwidth constants like BANDWIDTH_NARROWBAND, BANDWIDTH_FULLBAND, etc.

```python
bandwidth: int
```

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

### Configure Decoder Post-Initialization Properties

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Adjust decoder settings like gain, LSB depth, and observe properties such as bandwidth and pitch after initialization. Gain is set in centibels, and LSB depth ranges from 1 to 24.

```python
decoder = opuslib_next.Decoder(fs=48000, channels=2)
decoder.gain = -1500  # Reduce output by 15 dB
print(f"Last frame bandwidth: {decoder.bandwidth}")
print(f"Detected pitch: {decoder.pitch}")
```

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

### Initialize ProjectionEncoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-encoder.md

Instantiate a ProjectionEncoder with sample rate, channel count, mapping family, and application type. Ensure the application type is valid to avoid errors.

```python
import opuslib_next

encoder = opuslib_next.ProjectionEncoder(
    fs=48000,
    channels=4,
    mapping_family=2,  # Example Ambisonics order-1
    application='audio'
)
```

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

### Get Final Range

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/decoder.md

Read-only. Get the final state of the decoder's entropy coder. This property provides insight into the entropy coding process of the last decoded frame.

```python
final_range: int
```

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

### Initialize Opus Decoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Instantiate an Opus decoder with the specified sample rate and number of channels. Ensure the sample rate is one of the supported values (8000, 12000, 16000, 24000, 48000) and channels are 1 (mono) or 2 (stereo).

```python
decoder = opuslib_next.Decoder(fs=48000, channels=2)
```

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

### Initialize Encoder Instance

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Instantiate an Encoder object with the desired sampling rate, number of channels, and application type. Ensure the application type is valid to avoid errors.

```python
import opuslib_next

encoder = opuslib_next.Encoder(fs=48000, channels=2, application='audio')
```

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

### Initialize MultiStreamEncoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Instantiate a MultiStreamEncoder for multistream audio encoding. Ensure the channel mapping and application type are correctly specified. The application can be 'voip', 'audio', or 'restricted_lowdelay'.

```python
import opuslib_next

# 5.1 surround: 2 coupled streams for L/R, 4 more streams for C/LFE/SL/SR
mapping = [0, 1, 2, 3, 4, 5]
encoder = opuslib_next.MultiStreamEncoder(
    fs=48000,
    channels=6,
    streams=4,
    coupled_streams=2,
    mapping=mapping,
    application='audio'
)
```

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

### pitch

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Gets the detected pitch of the last encoded frame. This is a read-only property.

```APIDOC
## pitch

### Description
Detected pitch of the last encoded frame.

### Read-only
Read-only

### Type
int
```

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

### lsb_depth Property

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-decoder.md

Property to get or set the signal depth in bits. This is a read/write property.

```APIDOC
## lsb_depth

### Description
Read/write. Signal depth in bits.

### Returns
- int
```

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

### Initialize MultiStream Opus Encoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Set up a multi-stream Opus encoder with detailed configuration including sample rate, total channels, number of streams, coupled streams, channel mapping, and application type. The mapping array defines how channels are assigned to streams.

```python
# 5.1 configuration:
# - Streams 0-1: Coupled (stereo L/R)
# - Streams 2-3: Mono (Center, LFE)
# - Streams 4-5: Mono (Surround L/R) or another coupled pair
mapping = [0, 1, 2, 3, 4, 5]

encoder = opuslib_next.MultiStreamEncoder(
    fs=48000,
    channels=6,
    streams=4,
    coupled_streams=2,
    mapping=mapping,
    application='audio'
)
```

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

### Get Packet Frame Count

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Determines the number of frames contained within an Opus packet.

```python
packet_get_nb_frames(data: bytes, length: int | None = None) -> int
```

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

### Initialize MultiStreamDecoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-decoder.md

Initialize a multistream decoder with channel mapping configuration. Use this for setting up the decoder with specific audio parameters and stream layouts.

```python
import opuslib_next

# 5.1 surround example: 2 coupled streams + 1 stereo + 1 mono + 1 LFE
mapping = [0, 1, 2, 3, 4, 5]  # Stream layout
decoder = opuslib_next.MultiStreamDecoder(
    fs=48000,
    channels=6,
    streams=4,
    coupled_streams=2,
    mapping=mapping
)
```

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

### gain Property

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-decoder.md

Property to get or set the decoder gain adjustment in centibels. This is a read/write property.

```APIDOC
## gain

### Description
Read/write. Decoder gain adjustment in centibels.

### Returns
- int
```

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

### Dynamically Reconfigure Encoder Bitrate and Complexity

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Demonstrates how to dynamically adjust the encoder's bitrate and complexity based on available bandwidth. Includes logic to enable FEC when bandwidth is low.

```python
encoder = opuslib_next.Encoder(fs=48000, channels=2, application='audio')

# Dynamically adjust bitrate based on network conditions
def adjust_for_bandwidth(bandwidth_kbps):
    encoder.bitrate = bandwidth_kbps * 1000
    if bandwidth_kbps < 50:
        encoder.complexity = 5  # Reduce complexity for bandwidth
        encoder.inband_fec = 1
    else:
        encoder.complexity = 10
        encoder.inband_fec = 0
```

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

### Get Packet Channel Count

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Extracts the number of channels (1 or 2) from an Opus packet header.

```python
packet_get_nb_channels(data: bytes) -> int
```

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

### Basic Opus Encoding and Decoding

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/QUICK_START.md

Demonstrates the fundamental process of encoding PCM data into Opus format and decoding Opus data back into PCM. Ensure you have PCM data and Opus data to use.

```python
encoder = opuslib_next.Encoder(48000, 2, 'audio')
opus = encoder.encode(pcm_data, 960)

decoder = opuslib_next.Decoder(48000, 2)
pcm = decoder.decode(opus, 960)
```

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

### Initialize Opuslib-next Encoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Instantiate the Encoder class with essential parameters like sample rate, channels, and application type.

```python
import opuslib_next

encoder = opuslib_next.Encoder(
    fs=48000,      # 48 kHz sample rate
    channels=2,    # Stereo
    application='audio'  # General audio encoding
)
```

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

### Encoder Lookahead Property

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Read-only property to get the number of samples of lookahead delay introduced by the encoder.

```python
lookahead: int
```

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

### Encoder Sample Rate Property

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Read-only property to get the encoder's initialized sample rate.

```python
sample_rate: int
```

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

### bandwidth

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Set the bandwidth.

```APIDOC
## bandwidth

### Description
Set the bandwidth.

### Type
`int`

### Read/Write
Write-only
```

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

### Get Packet Bandwidth

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Retrieves the bandwidth information from an Opus packet header without decoding the packet. Raises OpusError if the packet is invalid.

```python
packet_get_bandwidth(data: bytes) -> int
```

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

### Get Multistream Encoder Size

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Retrieves the memory size required for a multistream encoder structure. Specify the number of independent streams and coupled streams.

```python
get_size(streams: int, coupled_streams: int) -> int
```

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

### Initialize Decoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/decoder.md

Initialize a decoder instance for a specific sampling rate and channel configuration. Supported values for fs are 8000, 12000, 16000, 24000, 48000 Hz. Channels must be 1 (mono) or 2 (stereo).

```python
Decoder(fs: int, channels: int)
```

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

### Create Opus Decoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/README.md

Instantiate a Decoder object with the desired sample rate and number of channels.

```python
decoder = opuslib_next.Decoder(
    fs=48000,
    channels=2
)
```

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

### vbr_constraint

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Gets or sets the constrained VBR mode. A value of 0 disables constraints, while 1 enables them, limiting bitrate variations when VBR is active.

```APIDOC
## vbr_constraint

### Description
Constrained VBR (0 or 1). Limits the variation in bitrate when VBR is enabled.

### Read/Write
Read/write

### Type
int
```

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

### Initialize MultiStream Opus Decoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Configure a multi-stream Opus decoder by specifying the sample rate, total output channels, number of input streams, coupled streams, and the channel mapping array.

```python
decoder = opuslib_next.MultiStreamDecoder(fs=48000, channels=2, streams=1, coupled_streams=1, mapping=[0, 1])
```

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

### Reset MultiStreamEncoder State

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Resets the internal state of the MultiStreamEncoder to its initial configuration. This is useful for starting a new encoding session without re-initializing the encoder.

```python
encoder.reset_state()
```

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

### Decoder Constructor

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/decoder.md

Initializes a decoder instance for a specific sampling rate and channel configuration.

```APIDOC
## Decoder Constructor

### Description
Initialize a decoder instance for a specific sampling rate and channel configuration.

### Parameters
#### Path Parameters
- **fs** (int) - Required - Sample rate in Hz. Supported values: 8000, 12000, 16000, 24000, 48000
- **channels** (int) - Required - Number of channels. Must be 1 (mono) or 2 (stereo)

### Raises
- OpusError: If decoder state initialization fails
```

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

### Get Demixing Matrix

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-encoder.md

Retrieve the demixing matrix used by the ProjectionEncoder. The matrix size can be optionally specified, otherwise, the encoder's default size is used.

```python
matrix = encoder.get_demixing_matrix()
matrix_size = encoder.demixing_matrix_size
print(f"Matrix size: {matrix_size} bytes")
```

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

### ProjectionEncoder Constructor

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-encoder.md

Initializes a ProjectionEncoder instance with specific audio and projection mapping configurations.

```APIDOC
## ProjectionEncoder Constructor

### Description
Initializes a projection encoder with projection mapping configuration.

### Parameters
#### Path Parameters
- **fs** (int) - Required - Sample rate in Hz
- **channels** (int) - Required - Number of input channels
- **mapping_family** (int) - Required - Projection/channel mapping family identifier
- **application** (str or int) - Required - Application: 'voip' (2048), 'audio' (2049), 'restricted_lowdelay' (2051)

### Raises
- `ValueError`: If application is invalid
- `OpusError`: If encoder initialization fails

### Example
```python
import opuslib_next

encoder = opuslib_next.ProjectionEncoder(
    fs=48000,
    channels=4,
    mapping_family=2,  # Example Ambisonics order-1
    application='audio'
)
```
```

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

### MultiStreamDecoder Constructor

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-decoder.md

Initializes a multistream decoder with channel mapping configuration. It requires sample rate, number of channels, independent streams, coupled streams, and a channel mapping array.

```APIDOC
## MultiStreamDecoder Constructor

### Description
Initialize a multistream decoder with channel mapping configuration.

### Parameters
#### Path Parameters
- **fs** (int) - Required - Sample rate in Hz (8000, 12000, 16000, 24000, 48000)
- **channels** (int) - Required - Total number of output channels
- **streams** (int) - Required - Number of independent streams in the input
- **coupled_streams** (int) - Required - Number of coupled streams (stereo pairs). Must be ≤ streams
- **mapping** (Sequence[int]) - Required - Channel mapping array defining how input streams map to output channels

### Raises
- OpusError: If decoder state initialization fails

### Example
```python
import opuslib_next

# 5.1 surround example: 2 coupled streams + 1 stereo + 1 mono + 1 LFE
mapping = [0, 1, 2, 3, 4, 5]  # Stream layout
decoder = opuslib_next.MultiStreamDecoder(
    fs=48000,
    channels=6,
    streams=4,
    coupled_streams=2,
    mapping=mapping
)
```
```

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

### Create Opus Encoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/README.md

Instantiate an Encoder object with specified sample rate, channels, and application type. The bitrate can be configured after creation.

```python
encoder = opuslib_next.Encoder(
    fs=48000,                    # Sample rate
    channels=2,                  # Mono or stereo
    application='audio'          # voip, audio, or restricted_lowdelay
)
encoder.bitrate = 128000        # Configure bitrate
```

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

### dtx

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Gets or sets the discontinuous transmission (DTX) mode. A value of 0 disables DTX, while 1 enables it. DTX conserves bandwidth by disabling transmission during periods of silence.

```APIDOC
## dtx

### Description
Discontinuous transmission (0 or 1). Saves bandwidth during silence.

### Read/Write
Read/write

### Type
int
```

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

### Create and Initialize Opus Encoder State

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Allocate and initialize an Opus encoder state. Requires specifying the sample rate, number of channels, and application type (e.g., audio, voice). Raises OpusError if initialization fails.

```python
opuslib_next.api.encoder.create_state(fs=48000, channels=2, application=opuslib_next.APPLICATION_AUDIO)
```

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

### Import opuslib_next

Source: https://github.com/kalicyh/opuslib-next/blob/master/README.md

Import the library in your Python project. The package name is opuslib_next.

```python
import opuslib_next
```

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

### Get Opus Encoder State Size

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Determine the memory size required for an Opus encoder state structure. This function takes the number of audio channels (1 or 2) as input.

```python
opuslib_next.api.encoder.get_size(channels=1)
```

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

### Configure ProjectionEncoder for Ambisonics

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Instantiate a ProjectionEncoder for first-order Ambisonics (B-format). This configuration is suitable for spatial audio processing. Accesses projection-specific properties like demixing matrix gain and size.

```python
encoder = opuslib_next.ProjectionEncoder(
    fs=48000,
    channels=4,  # Ambisonics B-format (W, X, Y, Z)
    mapping_family=2,  # First-order Ambisonics
    application='audio'
)

# Access projection-specific properties
matrix_gain = encoder.demixing_matrix_gain
matrix_size = encoder.demixing_matrix_size
matrix_data = encoder.get_demixing_matrix()
```

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

### Configure VoIP Optimized Encoder and Decoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Set up an Opus encoder for VoIP with specific bitrate, FEC, DTX, and complexity. A corresponding decoder is also initialized.

```python
import opuslib_next

encoder = opuslib_next.Encoder(fs=16000, channels=1, application='voip')
encoder.bitrate = 32000  # 32 kbps for narrowband speech
encoder.inband_fec = 1   # Enable FEC
encoder.dtx = 1          # Save bandwidth during silence
encoder.complexity = 9   # Good quality/CPU balance

decoder = opuslib_next.Decoder(fs=16000, channels=1)
```

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

### Configure Encoder Properties

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Adjust various encoder properties after initialization to fine-tune performance and quality for specific use cases, such as low-bandwidth scenarios or high packet loss.

```python
encoder = opuslib_next.Encoder(fs=48000, channels=2, application='voip')

# Configure for low-bandwidth scenarios
encoder.bitrate = 32000  # 32 kbps
encoder.complexity = 10  # Maximum quality
encoder.vbr = 1  # Variable bitrate
encoder.inband_fec = 1  # Enable FEC for packet loss
encoder.packet_loss_perc = 15  # Expect 15% packet loss
encoder.dtx = 1  # Save bandwidth during silence
```

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

### MultiStreamEncoder Constructor

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Initializes a multistream encoder with channel mapping and application type. It requires sample rate, channel count, stream counts, and a channel mapping table.

```APIDOC
## MultiStreamEncoder Constructor

### Description
Initializes a multistream encoder with channel mapping and application type.

### Parameters
#### Path Parameters
- **fs** (int) - Required - Sample rate in Hz
- **channels** (int) - Required - Total number of input channels
- **streams** (int) - Required - Number of independent output streams
- **coupled_streams** (int) - Required - Number of coupled streams (stereo pairs)
- **mapping** (Sequence[int]) - Required - Channel mapping table
- **application** (str or int) - Required - Application: 'voip' (2048), 'audio' (2049), 'restricted_lowdelay' (2051)

### Example
```python
import opuslib_next

# 5.1 surround: 2 coupled streams for L/R, 4 more streams for C/LFE/SL/SR
mapping = [0, 1, 2, 3, 4, 5]
encoder = opuslib_next.MultiStreamEncoder(
    fs=48000,
    channels=6,
    streams=4,
    coupled_streams=2,
    mapping=mapping,
    application='audio'
)
```
```

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

### Create Projection Decoder State

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Allocates a projection decoder with a specified demixing matrix. Requires parameters for sample rate, channels, streams, coupled streams, and the demixing matrix itself.

```python
create_state(fs: int, channels: int, streams: int, coupled_streams: int, demixing_matrix: Sequence[int]) -> ctypes.Structure
```

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

### Opuslib-Next Module Exports

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/types.md

Lists the classes, exceptions, and constants directly available for import from the main opuslib_next module. Ensure these are imported correctly for use in your application.

```python
# Classes
Decoder
Encoder
MultiStreamDecoder
MultiStreamEncoder
ProjectionDecoder
ProjectionEncoder

# Exception
OpusError

# Constants (via constants.py with wildcard import)
OK
BAD_ARG
BUFFER_TOO_SMALL
INTERNAL_ERROR
INVALID_PACKET
UNIMPLEMENTED
INVALID_STATE
ALLOC_FAIL
APPLICATION_VOIP
APPLICATION_AUDIO
APPLICATION_RESTRICTED_LOWDELAY
SIGNAL_VOICE
SIGNAL_MUSIC
BANDWIDTH_NARROWBAND
BANDWIDTH_MEDIUMBAND
BANDWIDTH_WIDEBAND
BANDWIDTH_SUPERWIDEBAND
BANDWIDTH_FULLBAND
AUTO
APPLICATION_TYPES_MAP
# ... plus all CTL request constants
```

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

### complexity

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Gets or sets the computational complexity of the encoder, ranging from 0 to 10. Higher complexity generally results in better audio quality at the expense of increased CPU usage. The default value may vary depending on the application.

```APIDOC
## complexity

### Description
Computational complexity (0-10). Higher values provide better quality at the cost of CPU. Default varies by application.

### Read/Write
Read/write

### Type
int
```

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

### Create Multistream Decoder State

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Allocates and initializes a multistream decoder state. Requires sample rate, channels, stream counts, and channel mapping.

```python
create_state(fs: int, channels: int, streams: int, coupled_streams: int, mapping: Sequence[int]) -> ctypes.Structure
```

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

### Handle Corrupted Opus Packets

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/errors.md

Corrupted or incomplete Opus packets can cause OpusError(-4) INVALID_PACKET during decoding. Implement a try-except block to catch this error and handle corrupt packets, for example, by skipping them or using packet loss concealment.

```python
decoder = opuslib_next.Decoder(fs=48000, channels=2)
corrupted_data = b'\x00\x01\x02'  # Invalid/truncated Opus packet
pcm = decoder.decode(corrupted_data, frame_size=960)
```

```python
try:
    pcm = decoder.decode(opus_data, frame_size=960)
except opuslib_next.OpusError as e:
    if e.code == opuslib_next.INVALID_PACKET:
        print(f"Skipping corrupt packet: {e}")
        # Use packet loss concealment or silence
    else:
        raise
```

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

### ProjectionDecoder Constructor

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-decoder.md

Initializes a projection decoder with the specified sample rate, channel configuration, stream information, and a demixing matrix for spatial reconstruction. It can raise an OpusError if initialization fails.

```APIDOC
## Constructor

### Description
Initialize a projection decoder with demixing matrix for spatial audio decoding.

### Parameters
#### Path Parameters
- **fs** (int) - Required - Sample rate in Hz (8000, 12000, 16000, 24000, 48000)
- **channels** (int) - Required - Number of output channels
- **streams** (int) - Required - Number of input streams in the projection
- **coupled_streams** (int) - Required - Number of coupled streams
- **demixing_matrix** (Sequence[int]) - Required - Projection demixing matrix for spatial reconstruction

### Raises
- OpusError: If decoder initialization fails

### Example
```python
import opuslib_next

demixing_matrix = bytes([...])  # Ambisonics or spatial audio matrix
decoder = opuslib_next.ProjectionDecoder(
    fs=48000,
    channels=4,
    streams=2,
    coupled_streams=1,
    demixing_matrix=demixing_matrix
)
```
```

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

### Opuslib-Next Signal Type Hints

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/types.md

Provides constants to hint the encoder about the type of audio signal being processed, such as voice or music. This allows the encoder to apply specific optimizations for better quality.

```python
SIGNAL_VOICE = 3001
SIGNAL_MUSIC = 3002
```

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

### Opuslib-Next Library Discovery

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

This code illustrates how opuslib_next discovers the underlying libopus library. It checks common locations on Linux and macOS, falling back to system-wide discovery if not found.

```python
# opuslib_next/api/__init__.py handles library discovery
# On Linux: checks /usr/lib/x86_64-linux-gnu/libopus.so.0
# On macOS: checks /opt/homebrew/lib/libopus.dylib and /usr/local/lib/libopus.dylib
# Falls back to system ctypes.find_library()
```

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

### Create Decoder State

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Allocates and initializes a decoder state. Requires specifying the sample rate and number of channels. Raises OpusError on failure.

```python
create_state(fs: int, channels: int) -> ctypes.Structure
```

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

### Query and Adjust Opus Encoder Properties

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/QUICK_START.md

Retrieves and displays various properties of an Opus encoder, such as bitrate, complexity, and lookahead. It also demonstrates how to dynamically adjust the bitrate after initialization.

```python
encoder = opuslib_next.Encoder(48000, 2, 'audio')
print(f"Bitrate: {encoder.bitrate}")
print(f"Complexity: {encoder.complexity}")
print(f"Lookahead: {encoder.lookahead}")
encoder.bitrate = 96000  # Adjust dynamically
```

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

### Configure Bidirectional Low Latency Encoder and Decoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Set up an Opus encoder for bidirectional communication with a focus on low latency, using a restricted low-delay application, moderate bitrate, and reduced complexity.

```python
encoder = opuslib_next.Encoder(
    fs=48000, 
    channels=2, 
    application='restricted_lowdelay'
)
encoder.bitrate = 64000   # Moderate bitrate
encoder.complexity = 5    # Reduce CPU for lower latency
encoder.inband_fec = 1    # Some packet loss protection

decoder = opuslib_next.Decoder(fs=48000, channels=2)
```

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

### bitrate

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-encoder.md

Read/write. Target bitrate in bits per second.

```APIDOC
## bitrate

### Description
Target bitrate in bits per second.

### Read/write
`bitrate: int`
```

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

### Encoder Constructor

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Initializes an encoder instance with specified sampling rate, channels, and application type. Raises ValueError for invalid application or OpusError for initialization failures.

```APIDOC
## Encoder Constructor

### Description
Initialize an encoder instance with specified sampling rate, channels, and application type.

### Parameters
#### Path Parameters
- **fs** (int) - Required - Sample rate in Hz (e.g., 8000, 16000, 48000)
- **channels** (int) - Required - Number of channels: 1 (mono) or 2 (stereo)
- **application** (str or int) - Required - Application type: 'voip' (2048), 'audio' (2049), or 'restricted_lowdelay' (2051). Can pass string name or numeric constant

### Raises
- `ValueError`: If application is not valid
- `OpusError`: If encoder state initialization fails

### Example
```python
import opuslib_next

encoder = opuslib_next.Encoder(fs=48000, channels=2, application='audio')
```
```

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

### force_channels

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Force mono (1) or stereo (2) encoding.

```APIDOC
## force_channels

### Description
Force mono (1) or stereo (2) encoding.

### Type
`int`

### Read/Write
Read/write
```

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

### create_state

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Allocates and initializes a decoder state with the specified sample rate and number of channels.

```APIDOC
## create_state

### Description
Allocate and initialize a decoder state.

### Parameters
#### Path Parameters
- **fs** (int) - Required - Sample rate (8000, 12000, 16000, 24000, 48000)
- **channels** (int) - Required - 1 or 2

### Returns
- **ctypes.Structure** - Decoder state

### Raises
- **OpusError** - if initialization fails
```

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

### Encoder Application Property

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Read or write the application type after initialization. This can be changed dynamically.

```python
application: int
```

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

### max_bandwidth

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Maximum allowed bandwidth.

```APIDOC
## max_bandwidth

### Description
Maximum allowed bandwidth.

### Type
`int`

### Read/Write
Read/write
```

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

### Parameters Table Format

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/INDEX.md

Defines the markdown table format for documenting function parameters, including their type, requirement status, default value, and a description.

```markdown
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
```

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

### bandwidth

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-encoder.md

Write-only. Set the bandwidth.

```APIDOC
## bandwidth

### Description
Set the bandwidth.

### Write-only
`bandwidth: int`
```

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

### Import Public API in Python

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/QUICK_START.md

Import all public API elements from the opuslib_next module. This includes access to Encoder, Decoder, MultiStreamEncoder, MultiStreamDecoder, ProjectionEncoder, ProjectionDecoder, OpusError, error codes, application types, signal types, bandwidth types, and CTL request constants.

```python
# Import all public API
import opuslib_next

# Available from top-level module:
# - Encoder, Decoder, MultiStreamEncoder, MultiStreamDecoder, ProjectionEncoder, ProjectionDecoder
# - OpusError
# - OK, BAD_ARG, BUFFER_TOO_SMALL, INTERNAL_ERROR, INVALID_PACKET, UNIMPLEMENTED, INVALID_STATE, ALLOC_FAIL
# - APPLICATION_VOIP, APPLICATION_AUDIO, APPLICATION_RESTRICTED_LOWDELAY
# - SIGNAL_VOICE, SIGNAL_MUSIC
# - BANDWIDTH_NARROWBAND, BANDWIDTH_MEDIUMBAND, BANDWIDTH_WIDEBAND, BANDWIDTH_SUPERWIDEBAND, BANDWIDTH_FULLBAND
# - AUTO, APPLICATION_TYPES_MAP
# - Plus all CTL request constants (SET_BITRATE_REQUEST, GET_BITRATE_REQUEST, etc.)
```

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

### Dynamic Encoder Configuration

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/README.md

Dynamically adjust encoder bitrate and complexity based on network conditions, such as available bandwidth, to optimize for quality or efficiency.

```python
encoder = opuslib_next.Encoder(48000, 2, 'audio')

# Adjust based on network conditions
if bandwidth_kbps < 50:
    encoder.bitrate = 32000
    encoder.complexity = 5
else:
    encoder.bitrate = 128000
    encoder.complexity = 10
```

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

### bitrate

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Target bitrate in bits per second. Set to -1 for automatic bitrate.

```APIDOC
## bitrate

### Description
Target bitrate in bits per second. Set to -1 for automatic bitrate.

### Type
`int`

### Read/Write
Read/write
```

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

### signal

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Signal type hint (SIGNAL_VOICE or SIGNAL_MUSIC).

```APIDOC
## signal

### Description
Signal type hint (SIGNAL_VOICE or SIGNAL_MUSIC).

### Type
`int`

### Read/Write
Read/write
```

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

### Configure Music Streaming Encoder and Decoder

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Configure an Opus encoder for music streaming with higher sample rate, stereo channels, maximum bitrate, and VBR enabled. A decoder is also initialized.

```python
encoder = opuslib_next.Encoder(fs=48000, channels=2, application='audio')
encoder.bitrate = 128000  # 128 kbps
encoder.complexity = 10   # Maximum quality
encoder.vbr = 1           # Variable bitrate for efficiency
encoder.signal = opuslib_next.SIGNAL_MUSIC  # Optimize for music

decoder = opuslib_next.Decoder(fs=48000, channels=2)
```

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

### Basic Error Catching with OpusLib-Next

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/errors.md

Use a basic try-except block to catch generic Opus errors during decoding. This is useful for general error reporting.

```python
import opuslib_next

try:
    decoder = opuslib_next.Decoder(fs=48000, channels=2)
    pcm = decoder.decode(opus_data, frame_size=960)
except opuslib_next.OpusError as e:
    print(f"Opus error {e.code}: {e}")
```

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

### Discontinuous Transmission (DTX) Configuration

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/README.md

Enable Discontinuous Transmission (DTX) on the encoder to save bandwidth by not transmitting data during silence.

```python
encoder.dtx = 1  # Save bandwidth during silence
```

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

### vbr_constraint

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/projection-encoder.md

Read/write. Constrained VBR (0 or 1).

```APIDOC
## vbr_constraint

### Description
Constrained VBR (0 or 1).

### Read/write
`vbr_constraint: int`
```

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

### Encode PCM Data with Opuslib-Next

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/configuration.md

Use this snippet to encode raw PCM audio data into Opus format. Specify the sample rate, channels, application type, and frame size for optimal encoding.

```python
encoder = opuslib_next.Encoder(fs=48000, channels=2, application='audio')
frame_size = 960  # 20ms at 48 kHz
opus_data = encoder.encode(pcm_data, frame_size)
```

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

### Opuslib-Next Encoding Data Flow

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/QUICK_START.md

Details the data flow for encoding audio using opuslib-next, from PCM input to Opus bytes output.

```text
PCM bytes (16-bit signed)
  ↓
Encoder.encode(pcm_data, frame_size)
  ↓
opuslib_next.api.encoder.encode()
  ↓
ctypes cast to int16* pointer
  ↓
libopus.opus_encode(state, pcm_pointer, frame_size, output_buffer, max_size)
  ↓
Checks result >= 0
  ↓
Returns opus_data bytes (length = result)
```

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

### Set Encoder Bitrate

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Set the target bitrate in bits per second. Use -1 for automatic bitrate. Typical range: 500-512000.

```python
encoder.bitrate = 128000  # 128 kbps
print(encoder.bitrate)
```

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

### Create Multistream Encoder State

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/low-level-api.md

Allocates and initializes a multistream encoder state. Requires sample rate, channels, stream counts, channel mapping, and application type.

```python
create_state(fs: int, channels: int, streams: int, coupled_streams: int, mapping: Sequence[int], application: int) -> ctypes.Structure
```

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

### final_range

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Entropy coder final state.

```APIDOC
## final_range

### Description
Entropy coder final state.

### Type
`int`

### Read/Write
Read-only
```

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

### encode

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/encoder.md

Encodes raw PCM audio data (16-bit samples) into Opus format. Requires specifying the frame size. Raises OpusError if encoding fails.

```APIDOC
## encode

### Description
Encode PCM audio data to Opus format (16-bit samples).

### Parameters
#### Path Parameters
- **pcm_data** (bytes) - Required - Raw PCM audio data (16-bit signed samples, interleaved for stereo)
- **frame_size** (int) - Required - Number of samples per channel. Must be 120, 240, 480, 960, 1920, or 2880 at 48 kHz

### Returns
`bytes` - Opus-encoded audio packet

### Raises
- `OpusError`: If encoding fails

### Example
```python
encoder = opuslib_next.Encoder(fs=48000, channels=2, application='voip')
opus_packet = encoder.encode(pcm_data, frame_size=960)
```
```

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

### decode

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/decoder.md

Decode Opus-encoded data to 16-bit PCM audio.

```APIDOC
## decode

### Description
Decode Opus-encoded data to 16-bit PCM audio.

### Parameters
#### Path Parameters
- **opus_data** (bytes) - Required - Opus-encoded audio data
- **frame_size** (int) - Required - Number of samples per channel to decode. Common values: 120, 240, 480, 960, 1920, 2880
- **decode_fec** (bool) - Optional - Enable forward error correction decoding for lost packets (Default: False)

### Returns
- bytes - PCM audio data (16-bit signed samples, interleaved for stereo)

### Raises
- OpusError: If decoding fails or data is corrupted

### Example
```python
import opuslib_next

decoder = opuslib_next.Decoder(fs=48000, channels=2)
pcm_audio = decoder.decode(opus_data, frame_size=960)
```
```

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

### vbr_constraint

Source: https://github.com/kalicyh/opuslib-next/blob/master/_autodocs/api-reference/multistream-encoder.md

Constrained VBR (0 or 1).

```APIDOC
## vbr_constraint

### Description
Constrained VBR (0 or 1).

### Type
`int`

### Read/Write
Read/write
```