opus: the codec underneath most of the audio you stream

What the format is and what this repository is

Opus is a codec for interactive speech and audio transmission over the Internet, specified by IETF RFC 6716. The README describes the range it covers as everything from low bitrate narrowband speech to very high quality stereo music, and names the applications it targets: voice over IP, videoconferencing, in-game chat, and remote live music performances.

This repository is not the format specification and not a container. It is the reference implementation in C, built as a shared library for encoding and decoding raw Opus bitstreams. That distinction matters operationally, because raw bitstreams are meant to travel over RTP per RFC 7587, while Opus stored in files belongs in the Ogg encapsulation described in RFC 7845, which lives in a separate package called opus-tools.

The README is unusually clear that the test tools included here should not be used for distribution, because their bitstreams carry extra debugging data and cannot support seeking. That is a small sentence that prevents a real class of mistake.

The two containers are genuinely different products. If you are shipping audio in files, you want opus-tools. If you are building something that streams, this library plus your RTP layer is the piece you want.

Building from a tarball versus building from git

A distribution tarball needs two steps.

% ./configure
% make

The git tree needs a build environment first, and the README gives the package list per distribution family: `git autoconf automake libtool gcc make` on Debian and Ubuntu, the same set through `dnf` on Fedora and RHEL, `yum` on older CentOS releases, and `brew install autoconf automake libtool` on macOS after installing Xcode.

From there it is clone, configure, build.

% git clone https://gitlab.xiph.org/xiph/opus.git
% cd opus
% ./autogen.sh
% ./configure
% make

Note where that clone URL points. It is gitlab.xiph.org, not GitHub, which tells you that this GitHub repository is a mirror and that upstream development happens elsewhere. `sudo make install` is available if you want the libraries on the system path, and the build produces an `opus_demo` executable in the top directory.

The README also recommends passing a `-march=` option on x86 to allow AVX2 use. The 1.5.2 release notes explain why that is not merely a preference: they fix a misalignment issue in the AVX2 code that could cause crashes under Windows.

opus_demo, where the design becomes visible

The demo tool exposes the encoder's real decision points, and they are the same knobs a production integration needs. The usage line is positional, with application, sampling rate, channel count and bits per second, followed by options.

The `application` argument is the one that matters most, because it selects between `voip`, `audio` and `restricted-lowdelay`, and each maps to a different balance between the two codecs inside Opus. The `-bandwidth` flag narrows the audio bandwidth from narrowband through SWB to fullband, defaulting to the sampling rate. `-framesize` takes 2.5, 5, 10, 20, 40 or 60 milliseconds, defaulting to 20. `-complexity` runs from 0 to 10 and defaults to the maximum, so the encoder is tuned for quality unless you lower it.

Two flags are worth knowing by name because they map directly to the packet loss behaviour in the library. `-inbandfec` enables SILK inband FEC, and `-dtx` enables discontinuous transmission for speech, which stops sending during silence. `-loss` simulates packet loss in percent, defaulting to 0, which is a debugging tool rather than a production setting.

Reading the demo's option list is a reasonable way to understand Opus without reading the specification.

Fixed-point for embedded, floating point for everything else

The portability notes describe a build that changes shape depending on the target. The implementation uses floating point by default, but can be compiled for fixed-point-only arithmetic with `--enable-fixed-point` under autoconf, or by defining the `FIXED_POINT` macro when building manually. The README is direct about the cost: the fixed-point build has somewhat lower audio quality and is slower on platforms with fast FPUs, and is normally used only in embedded environments.

The library compiles as either C89 or C99. The README also documents its reliance on implementation-defined behaviour, specifically two's complement right shifts on negative values and modulo conversion to signed integers of N bits. Writing that down is useful, because it tells you the assumptions a port to an unusual architecture would need to check.

The repository tree shows how much of this is separate code: `silk/` and `celt/` are the two codec components with their own `_headers.mk` and `_sources.mk` files, `src/` holds the shared layer, `dnn/` holds the neural components added in 1.5, and `training/` sits alongside them. Windows and alternative build systems are documented in `cmake/README.md` and `meson/README.md`.

DRED hides recovery data in the padding

Opus 1.5 is the release that matters most for anything running over a lossy network, because it is the first to make extended use of machine learning in the encoder and decoder. The headline feature is the deep redundancy algorithm, called DRED.

The mechanism is elegant and worth understanding precisely. The encoder embeds one second of recovery data in the padding data of each packet. Because that padding is already part of the packet format, older decoders discard it and newer decoders use it, so Opus 1.5 remains backward compatible with prior revisions. An older receiver simply hears a slightly degraded version of the same audio; a 1.5 receiver can reconstruct more of a packet that never fully arrived.

The release notes also list improved packet loss concealment through Deep PLC, low bitrate speech quality improvements down to 6 kb/s wideband, AVX2 and Neon optimizations, and support for fourth and fifth order ambisonics.

Two caveats come straight from the README. DRED was developed by a team that Amazon Web Services initially sponsored and open sourced, and the standardization process is underway at the IETF as an Opus extension draft. The README also states that the license or intellectual property position of Opus does not change with 1.5, which is the sentence an integrator should notice.

Testing, and a command that needs a correction

The README asks that the integrated tests be run after compiling, especially on a new platform, and `make check` is the command.

% make check

It then points at the standard test vectors, which are not shipped in the package because of their size, and gives the download and run sequence.

% curl -OL https://opus-codec.org/docs/opus_testvectors-rfc8251.tar.gz
% tar -zxf opus_testvectors-rfc8251.tar.gz
% ./tests/run_vectors.sh ./ opus_newvectors 48000

That third line does not line up with the second. The archive is extracted as `opus_testvectors-rfc8251`, but the run command passes `opus_newvectors` as the vector directory and 48000 as the sample rate. The sample rate is correct for Opus, so the mismatch is in the directory name, and you should point the script at the directory the extraction actually produced. Both facts are in the README as printed, and the fix is the kind of thing you would rather find here than an hour into a build.

Beyond that, the test surface includes a fuzzing directory under `tests/`, a `tests/run_vectors.sh` script, and a `.gitlab-ci.yml`, so CI runs from the upstream GitLab instance.

Where this mirror and the upstream project disagree

GitHub reports the license as NOASSERTION for this repository. The README, meanwhile, states that the Opus format and this implementation are subject to the royalty-free patent and copyright licenses specified in the file `COPYING`, and the tree contains both `COPYING` and `LICENSE_PLEASE_READ.txt`. The NOASSERTION value reflects GitHub failing to map those files to a known SPDX identifier, not a claim that the code is unlicensed. For a codec whose patent situation is the whole point, read `COPYING` rather than the repository field.

The second discrepancy is about time. The newest tags here are v1.5.2, v1.5.1 and v1.5, all published on the same day, 2024-09-11. The repository itself was pushed to on 2026-09-11. Both are true: development has continued on the mirror for two years without a new release tag appearing here.

That combination tells you where to look for current state. The `NEWS` file, the `ChangeLog` and the commit history on gitlab.xiph.org are more informative than the tag list. GitHub shows 3,322 stars, 810 forks and 192 open issues, which is a lot of open issues on a mature reference implementation, and part of that is simply that this is where people land when they search for opus rather than where the maintainers work.

Editorial conclusion

opus is worth understanding at the implementation level rather than the format level, because the interesting decisions are all in this repository: the SILK and CELT split, the fixed-point fallback, the DRED recovery data hidden in packet padding, and the test vector harness. Two practical notes for anyone picking it up. First, this GitHub repository is a mirror of a project whose canonical home is gitlab.xiph.org, which is where the clone instructions point and where the COPYING terms live. Second, the newest tagged release here is 1.5.2 from September 2024 while the repository has been pushed to since, so check the NEWS file and the commit log rather than assuming the tag reflects current state. To evaluate it, build from the git tree, run `make check`, and then run the RFC 8251 vectors, correcting the extracted directory name in the documented command.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. xiph/opus on GitHub