Understanding opus_packet_get_bandwidth in Libopus

This article explains the purpose, functionality, and return values of the opus_packet_get_bandwidth function in the libopus library. It covers how this method extracts audio bandwidth information directly from an Opus packet’s metadata, enabling efficient stream analysis without the need for full audio decoding.

The primary function of opus_packet_get_bandwidth is to determine the audio bandwidth of a given Opus packet. In digital audio, bandwidth refers to the range of frequencies contained within the audio signal. Because the Opus codec is highly adaptable, a single stream can dynamically switch between different bandwidths to optimize quality based on network conditions and bitrate. This function allows developers to inspect a packet and identify its bandwidth configuration instantly.

To achieve high efficiency, opus_packet_get_bandwidth does not decode the actual audio payload. Instead, it parses the Table of Contents (TOC) byte, which is the very first byte of any valid Opus packet. This byte contains encoded metadata detailing the frame duration, channel count, and bandwidth. By reading only this header information, the function executes almost instantaneously, making it ideal for real-time network monitoring, jitter buffer management, and packet filtering.

When called, the function returns an integer value representing one of five predefined bandwidth constants in libopus:

• OPUS_BANDWIDTH_NARROWBAND: Represents a 4 kHz audio bandpass (typically used for low-bitrate speech, equivalent to an 8 kHz sampling rate).
• OPUS_BANDWIDTH_MEDIUMBAND: Represents a 6 kHz audio bandpass (equivalent to a 12 kHz sampling rate).
• OPUS_BANDWIDTH_WIDEBAND: Represents an 8 kHz audio bandpass (equivalent to a 16 kHz sampling rate, standard for high-quality VoIP).
• OPUS_BANDWIDTH_SUPERWIDEBAND: Represents a 12 kHz audio bandpass (equivalent to a 24 kHz sampling rate).
• OPUS_BANDWIDTH_FULLBAND: Represents a 20 kHz audio bandpass (equivalent to a 48 kHz sampling rate, providing full-fidelity music and audio).

If the packet passed to the function is invalid, corrupted, or too short to contain a TOC byte, the function returns the error code OPUS_INVALID_PACKET. This error handling allows applications to detect and discard malformed data before passing it to the decoder.