libopus_sys 0.3.3

FFI-Binding to Opus, dynamically or statically linked for Windows and UNIX.
Documentation

libopus_sys

libopus_sys is an FFI-Rust-binding to Opus version 1.5.

Originally, this sys-crate was made to empower the serenity-crate to build audio features on Windows, Linux, and macOS. However, it's not limited to that.

Everyone is welcome to contribute, check out the CONTRIBUTING.md for further guidance.

Building & Linking

This crate can either:

  • link against a system-installed libopus, or
  • build Opus from vendored sources (no system libopus required) via the bundled feature.

Features

  • bundled: build Opus from the vendored opus/ sources using CMake (does not require a system libopus)
  • static: prefer static linking
  • dynamic: prefer dynamic linking
  • generate_binding: regenerate src/lib.rs from src/wrapper.h (requires libclang)

Requirements

  • To build Opus from source (e.g. --features bundled): you need cmake.
  • To link a system libopus via pkg-config: you need pkg-config (Unix / GNU targets only).
  • This crate ships with pre-generated bindings. To regenerate bindings you need Clang and LIBCLANG_PATH.

Recommended: build from vendored sources (no system dependency)

If you want a build that does not depend on any system-installed libopus, enable bundled:

cargo build --features bundled

You can also force this via environment variables:

  • OPUS_BUNDLED=1
  • LIBOPUS_BUNDLED=1

When bundled is enabled, the build script uses CMake to compile the vendored opus/ sources and links the resulting library.

Linking

libopus_sys targets Opus 1.5 and supports Windows, Linux, and macOS.

Static vs dynamic

  • By default, we link statically on Windows, macOS, and musl targets.
  • By default, we link dynamically on Linux gnu targets.

You can override this with features:

  • --features static
  • --features dynamic

If both are enabled, we pick the default for your target (as described above).

Environment variables LIBOPUS_STATIC or OPUS_STATIC take precedence over features: if either is set, static linking is selected (the value does not matter).

How libopus is located (when bundled is not enabled)

On Unix / GNU targets, the build script will:

  • try pkg-config for opus (unless LIBOPUS_NO_PKG or OPUS_NO_PKG is set)
  • otherwise, if LIBOPUS_LIB_DIR or OPUS_LIB_DIR is set, link from that prefix
  • otherwise, if vendored sources (opus/) are present, build Opus via CMake

If none of these work, the build fails with instructions on how to proceed.

Pkg-Config

On Unix / GNU targets (and when bundled is not enabled), libopus_sys will try pkg-config first. Set LIBOPUS_NO_PKG=1 or OPUS_NO_PKG=1 to bypass it.

System libopus (pre-installed)

If you prefer to link an existing libopus installation (or you already ship one with your application), you can point the build script at it:

  • LIBOPUS_LIB_DIR=/path/to/prefix
  • OPUS_LIB_DIR=/path/to/prefix

Where /path/to/prefix contains lib/ (e.g. /usr/local, a Homebrew prefix, etc.).

Be aware that using an Opus other than version 1.5 may not work.

Generating The Binding

If you want to generate the binding yourself, you can use the generate_binding-feature.

Be aware, bindgen requires Clang and its LIBCLANG_PATH environment variable to be specified.

Installation

Add this to your Cargo.toml:

[dependencies]
libopus_sys = "0.3"