Opus-Related API

The following classes depend on the availability of libraries.

If the required libraries are available then the classes can be imported directly from the pyogg module, for example using the statement from pyogg import OpusFile. Or you may import the package using import pyogg and reference the classes explicitly, such as pyogg.OpusFile.

If the required libraries are not available then instantiating a class will raise a PyOggError exception.

OpusFile

To read an entire OggOpus-encoded audio file into memory, use the OpusFile class. For a basic example of its use see Getting Started. For a more elaborate example see Play an OggOpus file.

This class requires the shared libraries Ogg, Opus, and Opusfile.

class pyogg.opus_file.OpusFile(path: str)

bytes_per_sample = None

Bytes per sample

channels = None

Number of channels in audio file.

frequency = None

Number of samples per second (per channel). Always 48,000.

OpusFileStream

Often, reading an entire file into memory is not desirable. Rather, we prefer to stream the file by reading small chunks at a time, processing the small section of the PCM and then moving on to the next section. This can be achieved with the OpusFileStream class. For an example of its use see Stream an OggOpus file.

This class requires the shared libraries Ogg, Opus, and Opusfile.

class pyogg.opus_file_stream.OpusFileStream(path)

bytes_per_sample = None

Bytes per sample

channels = None

Number of channels in audio file

frequency = None

Number of samples per second (per channel)

get_buffer()

Obtains the next frame of PCM samples.

Returns an array of signed 16-bit integers. If the file is in stereo, the left and right channels are interleaved.

Returns None when all data has been read.

The array that is returned should be either processed or copied before the next call to get_buffer() or get_buffer_as_array() as the array’s memory is reused for each call.

get_buffer_as_array()

Provides the buffer as a NumPy array.

Note that the underlying data type is 16-bit signed integers.

Does not copy the underlying data, so the returned array should either be processed or copied before the next call to get_buffer() or get_buffer_as_array().

pcm_size = None

Total PCM Length

OggOpusWriter

To write OggOpus encoded files, use the OggOpusWriter class.

This class requires the shared libraries Ogg and Opus.

OpusEncoder

class pyogg.opus_encoder.OpusEncoder

Encodes PCM data into Opus frames.

encode(pcm: Union[bytes, bytearray, memoryview]) → memoryview

Encodes PCM data into an Opus frame.

pcm must be formatted as bytes-like, with each sample taking two bytes (signed 16-bit integers; interleaved left, then right channels if in stereo).

If pcm is not writeable, a copy of the array will be made.

get_algorithmic_delay()

Gets the total samples of delay added by the entire codec.

This can be queried by the encoder and then the provided number of samples can be skipped on from the start of the decoder’s output to provide time aligned input and output. From the perspective of a decoding application the real data begins this many samples late.

The decoder contribution to this delay is identical for all decoders, but the encoder portion of the delay may vary from implementation to implementation, version to version, or even depend on the encoder’s initial configuration. Applications needing delay compensation should call this method rather than hard-coding a value.

set_application(application: str) → None

Set the encoding mode.

This must be one of ‘voip’, ‘audio’, or ‘restricted_lowdelay’.

‘voip’: Gives best quality at a given bitrate for voice signals. It enhances the input signal by high-pass filtering and emphasizing formants and harmonics. Optionally it includes in-band forward error correction to protect against packet loss. Use this mode for typical VoIP applications. Because of the enhancement, even at high bitrates the output may sound different from the input.

‘audio’: Gives best quality at a given bitrate for most non-voice signals like music. Use this mode for music and mixed (music/voice) content, broadcast, and applications requiring less than 15 ms of coding delay.

‘restricted_lowdelay’: configures low-delay mode that disables the speech-optimized mode in exchange for slightly reduced delay. This mode can only be set on an newly initialized encoder because it changes the codec delay.

set_channels(n: int) → None

Set the number of channels.

n must be either 1 or 2.

set_max_bytes_per_frame(max_bytes: int) → None

Set the maximum number of bytes in an encoded frame.

Size of the output payload. This may be used to impose an upper limit on the instant bitrate, but should not be used as the only bitrate control.

TODO: Use OPUS_SET_BITRATE to control the bitrate.

set_sampling_frequency(samples_per_second: int) → None

Set the number of samples (per channel) per second.

This must be one of 8000, 12000, 16000, 24000, or 48000.

Regardless of the sampling rate and number of channels selected, the Opus encoder can switch to a lower audio bandwidth or number of channels if the bitrate selected is too low. This also means that it is safe to always use 48 kHz stereo input and let the encoder optimize the encoding.

OpusBufferedEncoder

class pyogg.opus_buffered_encoder.OpusBufferedEncoder

buffered_encode(pcm_bytes: memoryview, flush: bool = False, callback: Callable[[memoryview, int, bool], None] = None) → List[Tuple[memoryview, int, bool]]

Gets encoded packets and their number of samples.

This method returns a list, where each item in the list is a tuple. The first item in the tuple is an Opus-encoded frame stored as a bytes-object. The second item in the tuple is the number of samples encoded (excluding silence).

If callback is supplied then this method will instead return an empty list but call the callback for every Opus-encoded frame that would have been returned as a list. This option has the desireable property of eliminating the copying of the encoded packets, which is required in order to form a list. The callback should take two arguments, the encoded frame (a Python bytes object) and the number of samples encoded per channel (an int). The user must either process or copy the data as the data may be overwritten once the callback terminates.

encode(pcm: Union[bytes, bytearray, memoryview]) → memoryview

Encodes PCM data into an Opus frame.

pcm must be formatted as bytes-like, with each sample taking two bytes (signed 16-bit integers; interleaved left, then right channels if in stereo).

If pcm is not writeable, a copy of the array will be made.

get_algorithmic_delay()

Gets the total samples of delay added by the entire codec.

This can be queried by the encoder and then the provided number of samples can be skipped on from the start of the decoder’s output to provide time aligned input and output. From the perspective of a decoding application the real data begins this many samples late.

The decoder contribution to this delay is identical for all decoders, but the encoder portion of the delay may vary from implementation to implementation, version to version, or even depend on the encoder’s initial configuration. Applications needing delay compensation should call this method rather than hard-coding a value.

set_application(application: str) → None

Set the encoding mode.

This must be one of ‘voip’, ‘audio’, or ‘restricted_lowdelay’.

‘voip’: Gives best quality at a given bitrate for voice signals. It enhances the input signal by high-pass filtering and emphasizing formants and harmonics. Optionally it includes in-band forward error correction to protect against packet loss. Use this mode for typical VoIP applications. Because of the enhancement, even at high bitrates the output may sound different from the input.

‘audio’: Gives best quality at a given bitrate for most non-voice signals like music. Use this mode for music and mixed (music/voice) content, broadcast, and applications requiring less than 15 ms of coding delay.

‘restricted_lowdelay’: configures low-delay mode that disables the speech-optimized mode in exchange for slightly reduced delay. This mode can only be set on an newly initialized encoder because it changes the codec delay.

set_channels(n: int) → None

Set the number of channels.

n must be either 1 or 2.

set_frame_size(frame_size: float) → None

Set the desired frame duration (in milliseconds).

Valid options are 2.5, 5, 10, 20, 40, or 60ms.

set_max_bytes_per_frame(max_bytes: int) → None

Set the maximum number of bytes in an encoded frame.

Size of the output payload. This may be used to impose an upper limit on the instant bitrate, but should not be used as the only bitrate control.

TODO: Use OPUS_SET_BITRATE to control the bitrate.

set_sampling_frequency(samples_per_second: int) → None

Set the number of samples (per channel) per second.

This must be one of 8000, 12000, 16000, 24000, or 48000.

Regardless of the sampling rate and number of channels selected, the Opus encoder can switch to a lower audio bandwidth or number of channels if the bitrate selected is too low. This also means that it is safe to always use 48 kHz stereo input and let the encoder optimize the encoding.

OpusDecoder

class pyogg.opus_decoder.OpusDecoder

decode(encoded_bytes: memoryview)

Decodes an Opus-encoded packet into PCM.

decode_missing_packet(frame_duration)

Obtain PCM data despite missing a frame.

frame_duration is in milliseconds.

set_channels(n)

Set the number of channels.

n must be either 1 or 2.

The decoder is capable of filling in either mono or interleaved stereo pcm buffers.

set_sampling_frequency(samples_per_second)

Set the number of samples (per channel) per second.

samples_per_second must be one of 8000, 12000, 16000, 24000, or 48000.

Internally Opus stores data at 48000 Hz, so that should be the default value for Fs. However, the decoder can efficiently decode to buffers at 8, 12, 16, and 24 kHz so if for some reason the caller cannot use data at the full sample rate, or knows the compressed data doesn’t use the full frequency range, it can request decoding at a reduced rate.