{"id":8387,"library":"opuslib","title":"Opuslib Python Bindings (Original)","description":"Opuslib provides Python bindings to the `libopus` IETF low-delay audio codec. It allows Python applications to encode and decode Opus audio streams. The current version, 3.0.1, was released in January 2018. Note that this specific `opuslib` package is no longer actively maintained; users are encouraged to consider the `opuslib-next` fork for ongoing support and compatibility with newer Python versions.","status":"maintenance","version":"3.0.1","language":"en","source_language":"en","source_url":"https://github.com/onbeep/opuslib","tags":["audio","codec","opus","bindings"],"install":[{"cmd":"pip install opuslib","lang":"bash","label":"Install `opuslib`"}],"dependencies":[{"reason":"Opuslib is a binding to the C library `libopus`. This must be installed separately on your system.","package":"libopus","optional":false}],"imports":[{"symbol":"Encoder","correct":"from opuslib import Encoder"},{"symbol":"Decoder","correct":"from opuslib import Decoder"},{"note":"The Python package is `opuslib`, not `opus`.","wrong":"import opus","symbol":"opuslib","correct":"import opuslib"}],"quickstart":{"code":"import opuslib\n\n# Encoder parameters\nSAMPLE_RATE = 48000  # Hz\nCHANNELS = 1\nAPPLICATION = opuslib.APPLICATION_AUDIO\nFRAME_SIZE_MS = 20 # milliseconds\nFRAME_SIZE_SAMPLES = int(SAMPLE_RATE * FRAME_SIZE_MS / 1000)\n\n# Create an encoder instance\nencoder = opuslib.Encoder(SAMPLE_RATE, CHANNELS, APPLICATION)\n\n# Example PCM audio data (replace with actual audio)\npcm_data_in = b'\\x00' * FRAME_SIZE_SAMPLES * 2 * CHANNELS # 16-bit mono, silent\n\n# Encode the audio\nencoded_data = encoder.encode(pcm_data_in, FRAME_SIZE_SAMPLES)\nprint(f\"Encoded {len(pcm_data_in)} bytes of PCM into {len(encoded_data)} bytes of Opus.\")\n\n# Create a decoder instance\ndecoder = opuslib.Decoder(SAMPLE_RATE, CHANNELS)\n\n# Decode the audio\ndecoded_data = decoder.decode(encoded_data, FRAME_SIZE_SAMPLES)\nprint(f\"Decoded {len(encoded_data)} bytes of Opus into {len(decoded_data)} bytes of PCM.\")\n\n# It's good practice to free resources if not using context managers (though opuslib handles it)\ndel encoder\ndel decoder","lang":"python","description":"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."},"warnings":[{"fix":"Use `pip install opuslib-next` and `import opuslib_next as opuslib` or directly `import opuslib_next`.","message":"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.","severity":"breaking","affected_versions":"<=3.0.1"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `libopus` using your operating system's package manager (e.g., `sudo apt-get install libopus-dev` or `brew install opus`).","cause":"The Python `opuslib` package was installed, but the underlying C library `libopus` is missing from the system.","error":"Exception: Could not find opus library. Make sure it is installed."},{"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).","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.","error":"OSError: dlopen(opus, 6): image not found"},{"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.","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.","error":"opuslib.exceptions.OpusError: An audio packet failed to decode properly."}]}