Class OpusCustom
- java.lang.Object
-
- org.lwjgl.util.opus.OpusCustom
-
public class OpusCustom extends java.lang.ObjectOpus Custom is an optional part of the Opus specification and reference implementation which uses a distinct API from the regular API and supports frame sizes that are not normally supported. Use of Opus Custom is discouraged for all but very special applications for which a frame size different from 2.5, 5, 10, or 20 ms is needed (for either complexity or latency reasons) and where interoperability is less important.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_createandcustom_decoder_createcalls take an additional mode parameter which is a structure produced by a call tocustom_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
Nested Classes Modifier and Type Class Description static classOpusCustom.FunctionsContains the function pointers loaded fromOpus.getLibrary().
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static intnopus_custom_decode(long st, long data, int len, long pcm, int frame_size)Unsafe version of:custom_decodestatic intnopus_custom_decode_float(long st, long data, int len, long pcm, int frame_size)Unsafe version of:custom_decode_floatstatic longnopus_custom_decoder_create(long mode, int channels, long error)Unsafe version of:custom_decoder_createstatic intnopus_custom_encode(long st, long pcm, int frame_size, long compressed, int maxCompressedBytes)Unsafe version of:custom_encodestatic intnopus_custom_encode_float(long st, long pcm, int frame_size, long compressed, int maxCompressedBytes)Unsafe version of:custom_encode_floatstatic longnopus_custom_encoder_create(long mode, int channels, long error)Unsafe version of:custom_encoder_createstatic longnopus_custom_mode_create(int Fs, int frame_size, long error)Unsafe version of:custom_mode_createstatic intopus_custom_decode(long st, java.nio.ByteBuffer data, java.nio.ShortBuffer pcm, int frame_size)Decode an opus custom frame.static intopus_custom_decode_float(long st, java.nio.ByteBuffer data, java.nio.FloatBuffer pcm, int frame_size)Decode an opus custom frame with floating point output.static longopus_custom_decoder_create(long mode, int channels, java.nio.IntBuffer error)Creates a new decoder state.static intopus_custom_decoder_ctl(long st, int request)Performs a CTL function on an Opus custom decoder.static intopus_custom_decoder_ctl(long st, Opus.CTLRequest request)Performs a CTL function on an Opus custom decoder.static voidopus_custom_decoder_destroy(long st)Destroys a decoder state.static intopus_custom_decoder_get_size(long mode, int channels)Gets the size of anOpusCustomDecoderstructure.static intopus_custom_decoder_init(long st, long mode, int channels)Initializes a previously allocated decoder state.static intopus_custom_encode(long st, java.nio.ShortBuffer pcm, int frame_size, java.nio.ByteBuffer compressed)Encodes a frame of audio.static intopus_custom_encode_float(long st, java.nio.FloatBuffer pcm, int frame_size, java.nio.ByteBuffer compressed)Encodes a frame of audio.static longopus_custom_encoder_create(long mode, int channels, java.nio.IntBuffer error)Creates a new encoder state.static intopus_custom_encoder_ctl(long st, int request)Performs a CTL function on an Opus custom encoder.static intopus_custom_encoder_ctl(long st, Opus.CTLRequest request)Performs a CTL function on an Opus custom encoder.static voidopus_custom_encoder_destroy(long st)Destroys an encoder state.static intopus_custom_encoder_get_size(long mode, int channels)Gets the size of anOpusCustomEncoderstructure.static intopus_custom_encoder_init(long st, long mode, int channels)Initializes a previously allocated encoder state.static longopus_custom_mode_create(int Fs, int frame_size, java.nio.IntBuffer error)Creates a new mode struct.static voidopus_custom_mode_destroy(long mode)Destroys a mode struct.
-
-
-
Method Detail
-
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
public static long opus_custom_mode_create(int Fs, int frame_size, @Nullable java.nio.IntBuffer error)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 anOpusCustomEncoderstructure.- 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
stmust 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_STATECTL.- 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:
OKSuccess 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
public static long opus_custom_encoder_create(long mode, int channels, @Nullable java.nio.IntBuffer error)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, java.nio.FloatBuffer pcm, int frame_size, java.nio.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.0are 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_sizesamples per channel.frame_size- number of samples per frame of input signalcompressed- the compressed data is written here. This may not aliaspcmand must be at leastmaxCompressedByteslong.- Returns:
- the number of bytes written to
compresson 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, java.nio.ShortBuffer pcm, int frame_size, java.nio.ByteBuffer compressed)Encodes a frame of audio.- Parameters:
st- encoder statepcm- PCM audio in signed 16-bit format (native endian). (There must be exactlyframe_sizesamples per channel.)frame_size- number of samples per frame of input signalcompressed- the compressed data is written here. This may not aliaspcmand must be at leastmaxCompressedByteslong.- Returns:
- the number of bytes written to
compresson 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 anOpusCustomDecoderstructure.- 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
stmust 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_STATECTL.- 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:
OKSuccess 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
public static long opus_custom_decoder_create(long mode, int channels, @Nullable java.nio.IntBuffer error)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 java.nio.ByteBuffer data, java.nio.FloatBuffer pcm, int frame_size)Decode an opus custom frame with floating point output.- Parameters:
st- decoder statedata- input payload. Use aNULLpointer 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 java.nio.ByteBuffer data, java.nio.ShortBuffer pcm, int frame_size)Decode an opus custom frame.- Parameters:
st- decoder statedata- input payload. Use aNULLpointer 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) public static int opus_custom_encoder_ctl(long st, Opus.CTLRequest request)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) public static int opus_custom_decoder_ctl(long st, Opus.CTLRequest request)Performs a CTL function on an Opus custom decoder.- Parameters:
st- decoder staterequest- CTL request
-
-