Introduction

This is the documentation for the libopusfile C API.

The libopusfile package provides a convenient high-level API for decoding and basic manipulation of all Ogg Opus audio streams. libopusfile is implemented as a layer on top of Xiph.Org's reference libogg and libopus libraries.

libopusfile provides several sets of built-in routines for file/stream access, and may also use custom stream I/O routines provided by the embedded environment. There are built-in I/O routines provided for ANSI-compliant stdio (FILE *), memory buffers, and URLs (including <file:> URLs, plus optionally <http:> and <https:> URLs).

Organization

The main API is divided into several sections:

Several additional sections are not tied to the main API.

Overview

The libopusfile API always decodes files to 48 kHz. The original sample rate is not preserved by the lossy compression, though it is stored in the header to allow you to resample to it after decoding (the libopusfile API does not currently provide a resampler, but the the Speex resampler is a good choice if you need one). In general, if you are playing back the audio, you should leave it at 48 kHz, provided your audio hardware supports it. When decoding to a file, it may be worth resampling back to the original sample rate, so as not to surprise users who might not expect the sample rate to change after encoding to Opus and decoding.

Opus files can contain anywhere from 1 to 255 channels of audio. The channel mappings for up to 8 channels are the same as the Vorbis mappings. A special stereo API can convert everything to 2 channels, making it simple to support multichannel files in an application which only has stereo output. Although the libopusfile ABI provides support for the theoretical maximum number of channels, the current implementation does not support files with more than 8 channels, as they do not have well-defined channel mappings.

Like all Ogg files, Opus files may be "chained". That is, multiple Opus files may be combined into a single, longer file just by concatenating the original files. This is commonly done in internet radio streaming, as it allows the title and artist to be updated each time the song changes, since each link in the chain includes its own set of metadata.

libopusfile fully supports chained files. It will decode the first Opus stream found in each link of a chained file (ignoring any other streams that might be concurrently multiplexed with it, such as a video stream).

The channel count can also change between links. If your application is not prepared to deal with this, it can use the stereo API to ensure the audio from all links will always get decoded into a common format. Since libopusfile always decodes to 48 kHz, you do not have to worry about the sample rate changing between links (as was possible with Vorbis). This makes application support for chained files with libopusfile very easy.