Opuslib Python Bindings (Original)

Common errors

• Exception: Could not find opus library. Make sure it is installed.

  cause The Python `opuslib` package was installed, but the underlying C library `libopus` is missing from the system.
  fix Install `libopus` using your operating system's package manager (e.g., `sudo apt-get install libopus-dev` or `brew install opus`).

• OSError: dlopen(opus, 6): image not found

  cause Similar to the 'Could not find opus library' error, this indicates that the Python bindings cannot locate the `libopus` shared library on your system's dynamic linker path.
  fix Ensure `libopus` is correctly installed (e.g., `sudo apt-get install libopus-dev`, `brew install opus`) and that its installation path is included in your system's library search paths (e.g., `LD_LIBRARY_PATH` on Linux, `DYLD_LIBRARY_PATH` on macOS, or proper system-wide installation).

• opuslib.exceptions.OpusError: An audio packet failed to decode properly.

  cause Often occurs when passing malformed data, non-Opus data, or Opus header packets to the decoder. It can also indicate incorrect decoder initialization parameters (sample rate, channels) that don't match the encoded stream.
  fix Verify that the input to `decoder.decode()` is a valid Opus audio data packet. Ensure the `Decoder` was initialized with the correct `fs` (sample rate) and `channels` matching the original encoding. Review data extraction from containers to ensure only audio data is passed.

Warnings

• breaking The original `opuslib` package (version 3.0.1 and prior) is no longer actively maintained. For ongoing development, bug fixes, and compatibility with newer Python versions (e.g., Python 3.10+), it is highly recommended to use the `opuslib-next` fork.
  Fix: Use `pip install opuslib-next` and `import opuslib_next as opuslib` or directly `import opuslib_next`.
• gotcha Opuslib is a Python binding to the `libopus` C library. Installing the Python package (`pip install opuslib`) is not sufficient; the underlying `libopus` shared library must be installed on your system.
  Fix: Install `libopus` via your system's package manager (e.g., `sudo apt-get install libopus-dev` on Debian/Ubuntu, `brew install opus` on macOS).
• gotcha When decoding Ogg Opus files, you should not pass the Ogg 'OpusHead' or 'OpusTags' header packets directly to the `opuslib.Decoder.decode` method. The decoder expects raw Opus audio data packets.
  Fix: Ensure you are extracting actual Opus data packets from the Ogg container and skipping initial header packets before feeding them to the `decode` method.

Install

• pip install opuslib Install `opuslib`

Imports

• Encoder

  from opuslib import Encoder

• Decoder

  from opuslib import Decoder

• opuslib
  wrong:

  import opus

  correct:

  import opuslib

  The Python package is `opuslib`, not `opus`.

Quickstart

Demonstrates initializing an Opus encoder and decoder, then encoding a block of dummy PCM audio data and decoding it back. Remember to adjust `pcm_data_in` with actual audio samples for real-world use cases.

import opuslib

# Encoder parameters
SAMPLE_RATE = 48000  # Hz
CHANNELS = 1
APPLICATION = opuslib.APPLICATION_AUDIO
FRAME_SIZE_MS = 20 # milliseconds
FRAME_SIZE_SAMPLES = int(SAMPLE_RATE * FRAME_SIZE_MS / 1000)

# Create an encoder instance
encoder = opuslib.Encoder(SAMPLE_RATE, CHANNELS, APPLICATION)

# Example PCM audio data (replace with actual audio)
pcm_data_in = b'\x00' * FRAME_SIZE_SAMPLES * 2 * CHANNELS # 16-bit mono, silent

# Encode the audio
encoded_data = encoder.encode(pcm_data_in, FRAME_SIZE_SAMPLES)
print(f"Encoded {len(pcm_data_in)} bytes of PCM into {len(encoded_data)} bytes of Opus.")

# Create a decoder instance
decoder = opuslib.Decoder(SAMPLE_RATE, CHANNELS)

# Decode the audio
decoded_data = decoder.decode(encoded_data, FRAME_SIZE_SAMPLES)
print(f"Decoded {len(encoded_data)} bytes of Opus into {len(decoded_data)} bytes of PCM.")

# It's good practice to free resources if not using context managers (though opuslib handles it)
del encoder
del decoder