Class OpusCustom
In addition to the interoperability limitations the use of Opus custom disables a substantial chunk of the codec and generally lowers the quality available at a given bitrate. Normally when an application needs a different frame size from the codec it should buffer to match the sizes but this adds a small amount of delay which may be important in some very low latency applications. Some transports (especially constant rate RF transports) may also work best with frames of particular durations.
Libopus only supports custom modes if they are enabled at compile time.
The Opus Custom API is similar to the regular API but the custom_encoder_create
and custom_decoder_create
calls take an additional mode parameter
which is a structure produced by a call to custom_mode_create
. Both the encoder and decoder must create a mode using the same sample rate (fs) and
frame size (frame size) so these parameters must either be signaled out of band or fixed in a particular implementation.
Similar to regular Opus the custom modes support on the fly frame size switching, but the sizes available depend on the particular frame size in use. For some initial frame sizes on a single on the fly size is available.
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic final class
Contains the function pointers loaded fromOpus.getLibrary()
. -
Method Summary
Modifier and TypeMethodDescriptionstatic int
nopus_custom_decode
(long st, long data, int len, long pcm, int frame_size) Unsafe version of:custom_decode
static int
nopus_custom_decode_float
(long st, long data, int len, long pcm, int frame_size) Unsafe version of:custom_decode_float
static long
nopus_custom_decoder_create
(long mode, int channels, long error) Unsafe version of:custom_decoder_create
static int
nopus_custom_encode
(long st, long pcm, int frame_size, long compressed, int maxCompressedBytes) Unsafe version of:custom_encode
static int
nopus_custom_encode_float
(long st, long pcm, int frame_size, long compressed, int maxCompressedBytes) Unsafe version of:custom_encode_float
static long
nopus_custom_encoder_create
(long mode, int channels, long error) Unsafe version of:custom_encoder_create
static long
nopus_custom_mode_create
(int Fs, int frame_size, long error) Unsafe version of:custom_mode_create
static int
opus_custom_decode
(long st, ByteBuffer data, ShortBuffer pcm, int frame_size) Decode an opus custom frame.static int
opus_custom_decode_float
(long st, ByteBuffer data, FloatBuffer pcm, int frame_size) Decode an opus custom frame with floating point output.static long
opus_custom_decoder_create
(long mode, int channels, IntBuffer error) Creates a new decoder state.static int
opus_custom_decoder_ctl
(long st, int request) Performs a CTL function on an Opus custom decoder.static int
opus_custom_decoder_ctl
(long st, Opus.CTLRequest request) Performs a CTL function on an Opus custom decoder.static void
opus_custom_decoder_destroy
(long st) Destroys a decoder state.static int
opus_custom_decoder_get_size
(long mode, int channels) Gets the size of anOpusCustomDecoder
structure.static int
opus_custom_decoder_init
(long st, long mode, int channels) Initializes a previously allocated decoder state.static int
opus_custom_encode
(long st, ShortBuffer pcm, int frame_size, ByteBuffer compressed) Encodes a frame of audio.static int
opus_custom_encode_float
(long st, FloatBuffer pcm, int frame_size, ByteBuffer compressed) Encodes a frame of audio.static long
opus_custom_encoder_create
(long mode, int channels, IntBuffer error) Creates a new encoder state.static int
opus_custom_encoder_ctl
(long st, int request) Performs a CTL function on an Opus custom encoder.static int
opus_custom_encoder_ctl
(long st, Opus.CTLRequest request) Performs a CTL function on an Opus custom encoder.static void
opus_custom_encoder_destroy
(long st) Destroys an encoder state.static int
opus_custom_encoder_get_size
(long mode, int channels) Gets the size of anOpusCustomEncoder
structure.static int
opus_custom_encoder_init
(long st, long mode, int channels) Initializes a previously allocated encoder state.static long
opus_custom_mode_create
(int Fs, int frame_size, IntBuffer error) Creates a new mode struct.static void
opus_custom_mode_destroy
(long mode) Destroys a mode struct.
-
Method Details
-
nopus_custom_mode_create
public static long nopus_custom_mode_create(int Fs, int frame_size, long error) Unsafe version of:custom_mode_create
-
opus_custom_mode_create
Creates a new mode struct. This will be passed to an encoder or decoder. The mode MUST NOT BE DESTROYED until the encoders and decoders that use it are destroyed as well.- Parameters:
Fs
- sampling rate (8000 to 96000 Hz)frame_size
- number of samples (per channel) to encode in each packet (64 - 1024, prime factorization must contain zero or more 2s, 3s, or 5s and no other primeserror
- returned error code (ifNULL
, no error will be returned)
-
opus_custom_mode_destroy
public static void opus_custom_mode_destroy(long mode) Destroys a mode struct. Only call this after all encoders and decoders using this mode are destroyed as well.- Parameters:
mode
- mode to be freed
-
opus_custom_encoder_get_size
public static int opus_custom_encoder_get_size(long mode, int channels) Gets the size of anOpusCustomEncoder
structure.- Parameters:
mode
- mode configurationchannels
- number of channels- Returns:
- size
-
opus_custom_encoder_init
public static int opus_custom_encoder_init(long st, long mode, int channels) Initializes a previously allocated encoder state.The memory pointed to by
st
must be the size returned bycustom_encoder_get_size
. This is intended for applications which use their own allocator instead ofmalloc
.To reset a previously initialized state use the
RESET_STATE
CTL.- Parameters:
st
- encoder statemode
- contains all the information about the characteristics of the stream (must be the same characteristics as used for the decoder)channels
- number of channels- Returns:
OK
Success or a negative error code
-
nopus_custom_encoder_create
public static long nopus_custom_encoder_create(long mode, int channels, long error) Unsafe version of:custom_encoder_create
-
opus_custom_encoder_create
Creates a new encoder state.Each stream needs its own encoder state (can't be shared across simultaneous streams).
- Parameters:
mode
- contains all the information about the characteristics of the stream (must be the same characteristics as used for the decoder)channels
- number of channelserror
- returns an error code- Returns:
- newly created encoder state
-
opus_custom_encoder_destroy
public static void opus_custom_encoder_destroy(long st) Destroys an encoder state.- Parameters:
st
- state to be freed
-
nopus_custom_encode_float
public static int nopus_custom_encode_float(long st, long pcm, int frame_size, long compressed, int maxCompressedBytes) Unsafe version of:custom_encode_float
- Parameters:
maxCompressedBytes
- maximum number of bytes to use for compressing the frame (can change from one frame to another)
-
opus_custom_encode_float
public static int opus_custom_encode_float(long st, FloatBuffer pcm, int frame_size, ByteBuffer compressed) Encodes a frame of audio.- Parameters:
st
- encoder statepcm
- PCM audio in float format, with a normal range of+/-1.0
. Samples with a range beyond+/-1.0
are supported but will be clipped by decoders using the integer API and should only be used if it is known that the far end supports extended dynamic range. There must be exactlyframe_size
samples per channel.frame_size
- number of samples per frame of input signalcompressed
- the compressed data is written here. This may not aliaspcm
and must be at leastmaxCompressedBytes
long.- Returns:
- the number of bytes written to
compress
on success, or a negative error code
-
nopus_custom_encode
public static int nopus_custom_encode(long st, long pcm, int frame_size, long compressed, int maxCompressedBytes) Unsafe version of:custom_encode
- Parameters:
maxCompressedBytes
- maximum number of bytes to use for compressing the frame (can change from one frame to another)
-
opus_custom_encode
public static int opus_custom_encode(long st, ShortBuffer pcm, int frame_size, ByteBuffer compressed) Encodes a frame of audio.- Parameters:
st
- encoder statepcm
- PCM audio in signed 16-bit format (native endian). (There must be exactlyframe_size
samples per channel.)frame_size
- number of samples per frame of input signalcompressed
- the compressed data is written here. This may not aliaspcm
and must be at leastmaxCompressedBytes
long.- Returns:
- the number of bytes written to
compress
on success, or a negative error code
-
opus_custom_decoder_get_size
public static int opus_custom_decoder_get_size(long mode, int channels) Gets the size of anOpusCustomDecoder
structure.- Parameters:
mode
- mode configurationchannels
- number of channels- Returns:
- size
-
opus_custom_decoder_init
public static int opus_custom_decoder_init(long st, long mode, int channels) Initializes a previously allocated decoder state.The memory pointed to by
st
must be the size returned bycustom_decoder_get_size
. This is intended for applications which use their own allocator instead ofmalloc
.To reset a previously initialized state use the
RESET_STATE
CTL.- Parameters:
st
- decoder statemode
- contains all the information about the characteristics of the stream (must be the same characteristics as used for the encoder)channels
- number of channels- Returns:
OK
Success or a negative error code
-
nopus_custom_decoder_create
public static long nopus_custom_decoder_create(long mode, int channels, long error) Unsafe version of:custom_decoder_create
-
opus_custom_decoder_create
Creates a new decoder state.Each stream needs its own decoder state (can't be shared across simultaneous streams).
- Parameters:
mode
- contains all the information about the characteristics of the stream (must be the same characteristics as used for the encoder)channels
- number of channelserror
- returns an error code- Returns:
- newly created decoder state
-
opus_custom_decoder_destroy
public static void opus_custom_decoder_destroy(long st) Destroys a decoder state.- Parameters:
st
- state to be freed
-
nopus_custom_decode_float
public static int nopus_custom_decode_float(long st, long data, int len, long pcm, int frame_size) Unsafe version of:custom_decode_float
- Parameters:
len
- number of bytes in payload
-
opus_custom_decode_float
public static int opus_custom_decode_float(long st, @Nullable ByteBuffer data, FloatBuffer pcm, int frame_size) Decode an opus custom frame with floating point output.- Parameters:
st
- decoder statedata
- input payload. Use aNULL
pointer to indicate packet loss.pcm
- output signal (interleaved if 2 channels) (length isframe_size*channels*sizeof(float)
frame_size
- number of samples per channel of available space inpcm
- Returns:
- number of decoded samples, or a negative error code
-
nopus_custom_decode
public static int nopus_custom_decode(long st, long data, int len, long pcm, int frame_size) Unsafe version of:custom_decode
- Parameters:
len
- number of bytes in payload
-
opus_custom_decode
public static int opus_custom_decode(long st, @Nullable ByteBuffer data, ShortBuffer pcm, int frame_size) Decode an opus custom frame.- Parameters:
st
- decoder statedata
- input payload. Use aNULL
pointer to indicate packet loss.pcm
- output signal (interleaved if 2 channels) (length isframe_size*channels*sizeof(opus_int16)
frame_size
- number of samples per channel of available space inpcm
- Returns:
- number of decoded samples, or a negative error code
-
opus_custom_encoder_ctl
public static int opus_custom_encoder_ctl(long st, int request) Performs a CTL function on an Opus custom encoder.- Parameters:
st
- encoder staterequest
- CTL request
-
opus_custom_encoder_ctl
Performs a CTL function on an Opus custom encoder.- Parameters:
st
- encoder staterequest
- CTL request
-
opus_custom_decoder_ctl
public static int opus_custom_decoder_ctl(long st, int request) Performs a CTL function on an Opus custom decoder.- Parameters:
st
- decoder staterequest
- CTL request
-
opus_custom_decoder_ctl
Performs a CTL function on an Opus custom decoder.- Parameters:
st
- decoder staterequest
- CTL request
-