{"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":"python","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,"search_vec":"'2018':37 '3.0.1':32 'activ':47 'allow':19 'applic':21 'audio':16,27,68 'bind':3,8,71 'codec':17,69 'compat':63 'consid':53 'current':30 'decod':25 'delay':15 'encod':23 'encourag':51 'fork':58 'ietf':12 'januari':36 'libopus':11 'longer':46 'low':14 'low-delay':13 'maintain':48 'newer':65 'next':57 'note':38 'ongo':60 'opus':26,70 'opuslib':1,5,42,56 'opuslib-next':55 'origin':4 'packag':43 'provid':6 'python':2,7,20,66 'releas':34 'specif':41 'stream':28 'support':61 'user':49 'version':31,67","created_at":"2026-04-16T17:01:55.844716+00:00","updated_at":"2026-04-16T17:01:55.844716+00:00","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."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.0.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/onbeep/opuslib","docs":null,"changelog":null,"pypi":"https://pypi.org/project/opuslib/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}