Top Description Inners Constructors Methods
org.lwjgl.util.opus

public Class OpusCustom

extends Object
Class Inheritance
Imports
javax.annotation.*, java.nio.*, org.lwjgl.system.*
Opus 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_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 and Inner Type Summary

Modifier and TypeClass and Description
public static class
OpusCustom.Functions

Contains the function pointers loaded from Opus.getLibrary().

Constructor Summary

AccessConstructor and Description
protected
OpusCustom()

Method Summary

Modifier and TypeMethod and Description
public static int
nopus_custom_decode(long st, long data, int
number of bytes in payload
len, long pcm, int frame_size)

Unsafe version of: custom_decode

public static int
nopus_custom_decode_float(long st, long data, int
number of bytes in payload
len, long pcm, int frame_size)

Unsafe version of: custom_decode_float

public static long
nopus_custom_decoder_create(long mode, int channels, long error)

Unsafe version of: custom_decoder_create

public static int
nopus_custom_encode(long st, long pcm, int frame_size, long compressed, int
maximum number of bytes to use for compressing the frame (can change from one frame to another)
maxCompressedBytes)

Unsafe version of: custom_encode

public static int
nopus_custom_encode_float(long st, long pcm, int frame_size, long compressed, int
maximum number of bytes to use for compressing the frame (can change from one frame to another)
maxCompressedBytes)

Unsafe version of: custom_encode_float

public static long
nopus_custom_encoder_create(long mode, int channels, long error)

Unsafe version of: custom_encoder_create

public static long
nopus_custom_mode_create(int Fs, int frame_size, long error)

Unsafe version of: custom_mode_create

public static int

Returns:

number of decoded samples, or a negative error code
opus_custom_decode(long
decoder state
st, ByteBuffer
input payload. Use a NULL pointer to indicate packet loss.
data, ShortBuffer
output signal (interleaved if 2 channels) (length is frame_size*channels*sizeof(opus_int16)
pcm, int
number of samples per channel of available space in pcm
frame_size)

Decode an opus custom frame.

public static int

Returns:

number of decoded samples, or a negative error code
opus_custom_decode_float(long
decoder state
st, ByteBuffer
input payload. Use a NULL pointer to indicate packet loss.
data, FloatBuffer
output signal (interleaved if 2 channels) (length is frame_size*channels*sizeof(float)
pcm, int
number of samples per channel of available space in pcm
frame_size)

Decode an opus custom frame with floating point output.

public static long

Returns:

newly created decoder state
opus_custom_decoder_create(long
contains all the information about the characteristics of the stream (must be the same characteristics as used for the encoder)
mode, int
number of channels
channels, IntBuffer
returns an error code
error)

Creates a new decoder state.

private static int
opus_custom_decoder_ctl(long
decoder state
st)

Performs a CTL function on an Opus custom decoder.

public static int
opus_custom_decoder_ctl(long
decoder state
st, int
CTL request
request)

Performs a CTL function on an Opus custom decoder.

public static int
opus_custom_decoder_ctl(long
decoder state
st, Opus.CTLRequest
CTL request
request)

Performs a CTL function on an Opus custom decoder.

public static void
opus_custom_decoder_destroy(long
state to be freed
st)

Destroys a decoder state.

public static int

Returns:

size
opus_custom_decoder_get_size(long
mode configuration
mode, int
number of channels
channels)

Gets the size of an OpusCustomDecoder structure.

public static int

Returns:

OK Success or a negative error code
opus_custom_decoder_init(long
decoder state
st, long
contains all the information about the characteristics of the stream (must be the same characteristics as used for the encoder)
mode, int
number of channels
channels)

Initializes a previously allocated decoder state.

public static int

Returns:

the number of bytes written to compress on success, or a negative error code
opus_custom_encode(long
encoder state
st, ShortBuffer
PCM audio in signed 16-bit format (native endian). (There must be exactly frame_size samples per channel.)
pcm, int
number of samples per frame of input signal
frame_size, ByteBuffer
the compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
compressed)

Encodes a frame of audio.

public static int

Returns:

the number of bytes written to compress on success, or a negative error code
opus_custom_encode_float(long
encoder state
st, FloatBuffer
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 exactly frame_size samples per channel.
pcm, int
number of samples per frame of input signal
frame_size, ByteBuffer
the compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
compressed)

Encodes a frame of audio.

public static long

Returns:

newly created encoder state
opus_custom_encoder_create(long
contains all the information about the characteristics of the stream (must be the same characteristics as used for the decoder)
mode, int
number of channels
channels, IntBuffer
returns an error code
error)

Creates a new encoder state.

private static int
opus_custom_encoder_ctl(long
encoder state
st)

Performs a CTL function on an Opus custom encoder.

public static int
opus_custom_encoder_ctl(long
encoder state
st, int
CTL request
request)

Performs a CTL function on an Opus custom encoder.

public static int
opus_custom_encoder_ctl(long
encoder state
st, Opus.CTLRequest
CTL request
request)

Performs a CTL function on an Opus custom encoder.

public static void
opus_custom_encoder_destroy(long
state to be freed
st)

Destroys an encoder state.

public static int

Returns:

size
opus_custom_encoder_get_size(long
mode configuration
mode, int
number of channels
channels)

Gets the size of an OpusCustomEncoder structure.

public static int

Returns:

OK Success or a negative error code
opus_custom_encoder_init(long
encoder state
st, long
contains all the information about the characteristics of the stream (must be the same characteristics as used for the decoder)
mode, int
number of channels
channels)

Initializes a previously allocated encoder state.

public static long
opus_custom_mode_create(int
sampling rate (8000 to 96000 Hz)
Fs, int
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 primes
frame_size, IntBuffer
returned error code (if NULL, no error will be returned)
error)

Creates a new mode struct.

public static void
opus_custom_mode_destroy(long
mode to be freed
mode)

Destroys a mode struct.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

OpusCustomback to summary
protected OpusCustom()

Method Detail

nopus_custom_decodeback to summary
public static int nopus_custom_decode(long st, long data, int len, long pcm, int frame_size)

Unsafe version of: custom_decode

Parameters
len:int

number of bytes in payload

nopus_custom_decode_floatback to summary
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:int

number of bytes in payload

nopus_custom_decoder_createback to summary
public static long nopus_custom_decoder_create(long mode, int channels, long error)

Unsafe version of: custom_decoder_create

nopus_custom_encodeback to summary
public static int nopus_custom_encode(long st, long pcm, int frame_size, long compressed, int maxCompressedBytes)

Unsafe version of: custom_encode

Parameters
maxCompressedBytes:int

maximum number of bytes to use for compressing the frame (can change from one frame to another)

nopus_custom_encode_floatback to summary
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:int

maximum number of bytes to use for compressing the frame (can change from one frame to another)

nopus_custom_encoder_createback to summary
public static long nopus_custom_encoder_create(long mode, int channels, long error)

Unsafe version of: custom_encoder_create

nopus_custom_mode_createback to summary
public static long nopus_custom_mode_create(int Fs, int frame_size, long error)

Unsafe version of: custom_mode_create

opus_custom_decodeback to summary
public static int opus_custom_decode(long st, ByteBuffer data, ShortBuffer pcm, int frame_size)

Decode an opus custom frame.

Parameters
st:long

decoder state

data:ByteBuffer

input payload. Use a NULL pointer to indicate packet loss.

pcm:ShortBuffer

output signal (interleaved if 2 channels) (length is frame_size*channels*sizeof(opus_int16)

frame_size:int

number of samples per channel of available space in pcm

Returns:int

number of decoded samples, or a negative error code

opus_custom_decode_floatback to summary
public static int opus_custom_decode_float(long st, ByteBuffer data, FloatBuffer pcm, int frame_size)

Decode an opus custom frame with floating point output.

Parameters
st:long

decoder state

data:ByteBuffer

input payload. Use a NULL pointer to indicate packet loss.

pcm:FloatBuffer

output signal (interleaved if 2 channels) (length is frame_size*channels*sizeof(float)

frame_size:int

number of samples per channel of available space in pcm

Returns:int

number of decoded samples, or a negative error code

opus_custom_decoder_createback to summary
public static long opus_custom_decoder_create(long mode, int channels, IntBuffer error)

Creates a new decoder state.

Each stream needs its own decoder state (can't be shared across simultaneous streams).

Parameters
mode:long

contains all the information about the characteristics of the stream (must be the same characteristics as used for the encoder)

channels:int

number of channels

error:IntBuffer

returns an error code

Returns:long

newly created decoder state

Annotations
@NativeType:OpusCustomDecoder *
opus_custom_decoder_ctlback to summary
private static int opus_custom_decoder_ctl(long st)

Performs a CTL function on an Opus custom decoder.

Parameters
st:long

decoder state

opus_custom_decoder_ctlback to summary
public static int opus_custom_decoder_ctl(long st, int request)

Performs a CTL function on an Opus custom decoder.

Parameters
st:long

decoder state

request:int

CTL request

opus_custom_decoder_ctlback to summary
public static int opus_custom_decoder_ctl(long st, Opus.CTLRequest request)

Performs a CTL function on an Opus custom decoder.

Parameters
st:long

decoder state

request:Opus.CTLRequest

CTL request

opus_custom_decoder_destroyback to summary
public static void opus_custom_decoder_destroy(long st)

Destroys a decoder state.

Parameters
st:long

state to be freed

opus_custom_decoder_get_sizeback to summary
public static int opus_custom_decoder_get_size(long mode, int channels)

Gets the size of an OpusCustomDecoder structure.

Parameters
mode:long

mode configuration

channels:int

number of channels

Returns:int

size

opus_custom_decoder_initback to summary
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 by custom_decoder_get_size. This is intended for applications which use their own allocator instead of malloc.

To reset a previously initialized state use the RESET_STATE CTL.

Parameters
st:long

decoder state

mode:long

contains all the information about the characteristics of the stream (must be the same characteristics as used for the encoder)

channels:int

number of channels

Returns:int

OK Success or a negative error code

opus_custom_encodeback to summary
public static int opus_custom_encode(long st, ShortBuffer pcm, int frame_size, ByteBuffer compressed)

Encodes a frame of audio.

Parameters
st:long

encoder state

pcm:ShortBuffer

PCM audio in signed 16-bit format (native endian). (There must be exactly frame_size samples per channel.)

frame_size:int

number of samples per frame of input signal

compressed:ByteBuffer

the compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.

Returns:int

the number of bytes written to compress on success, or a negative error code

opus_custom_encode_floatback to summary
public static int opus_custom_encode_float(long st, FloatBuffer pcm, int frame_size, ByteBuffer compressed)

Encodes a frame of audio.

Parameters
st:long

encoder state

pcm:FloatBuffer

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 exactly frame_size samples per channel.

frame_size:int

number of samples per frame of input signal

compressed:ByteBuffer

the compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.

Returns:int

the number of bytes written to compress on success, or a negative error code

opus_custom_encoder_createback to summary
public static long opus_custom_encoder_create(long mode, int channels, IntBuffer error)

Creates a new encoder state.

Each stream needs its own encoder state (can't be shared across simultaneous streams).

Parameters
mode:long

contains all the information about the characteristics of the stream (must be the same characteristics as used for the decoder)

channels:int

number of channels

error:IntBuffer

returns an error code

Returns:long

newly created encoder state

Annotations
@NativeType:OpusCustomEncoder *
opus_custom_encoder_ctlback to summary
private static int opus_custom_encoder_ctl(long st)

Performs a CTL function on an Opus custom encoder.

Parameters
st:long

encoder state

opus_custom_encoder_ctlback to summary
public static int opus_custom_encoder_ctl(long st, int request)

Performs a CTL function on an Opus custom encoder.

Parameters
st:long

encoder state

request:int

CTL request

opus_custom_encoder_ctlback to summary
public static int opus_custom_encoder_ctl(long st, Opus.CTLRequest request)

Performs a CTL function on an Opus custom encoder.

Parameters
st:long

encoder state

request:Opus.CTLRequest

CTL request

opus_custom_encoder_destroyback to summary
public static void opus_custom_encoder_destroy(long st)

Destroys an encoder state.

Parameters
st:long

state to be freed

opus_custom_encoder_get_sizeback to summary
public static int opus_custom_encoder_get_size(long mode, int channels)

Gets the size of an OpusCustomEncoder structure.

Parameters
mode:long

mode configuration

channels:int

number of channels

Returns:int

size

opus_custom_encoder_initback to summary
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 by custom_encoder_get_size. This is intended for applications which use their own allocator instead of malloc.

To reset a previously initialized state use the RESET_STATE CTL.

Parameters
st:long

encoder state

mode:long

contains all the information about the characteristics of the stream (must be the same characteristics as used for the decoder)

channels:int

number of channels

Returns:int

OK Success or a negative error code

opus_custom_mode_createback to summary
public static long opus_custom_mode_create(int Fs, int frame_size, 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:int

sampling rate (8000 to 96000 Hz)

frame_size:int

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 primes

error:IntBuffer

returned error code (if NULL, no error will be returned)

Annotations
@NativeType:OpusCustomMode *
opus_custom_mode_destroyback to summary
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:long

mode to be freed

org.lwjgl.util.opus back to summary

public final Class OpusCustom.Functions

extends Object
Class Inheritance
Contains the function pointers loaded from Opus.getLibrary().

Field Summary

Modifier and TypeField and Description
public static final long
custom_decode

Function address.

public static final long
custom_decode_float

Function address.

public static final long
custom_decoder_create

Function address.

public static final long
custom_decoder_ctl

Function address.

public static final long
custom_decoder_destroy

Function address.

public static final long
custom_decoder_get_size

Function address.

public static final long
custom_decoder_init

Function address.

public static final long
custom_encode

Function address.

public static final long
custom_encode_float

Function address.

public static final long
custom_encoder_create

Function address.

public static final long
custom_encoder_ctl

Function address.

public static final long
custom_encoder_destroy

Function address.

public static final long
custom_encoder_get_size

Function address.

public static final long
custom_encoder_init

Function address.

public static final long
custom_mode_create

Function address.

public static final long
custom_mode_destroy

Function address.

Constructor Summary

AccessConstructor and Description
private
Functions()

Method Summary

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

custom_decodeback to summary
public static final long custom_decode

Function address.

custom_decode_floatback to summary
public static final long custom_decode_float

Function address.

custom_decoder_createback to summary
public static final long custom_decoder_create

Function address.

custom_decoder_ctlback to summary
public static final long custom_decoder_ctl

Function address.

custom_decoder_destroyback to summary
public static final long custom_decoder_destroy

Function address.

custom_decoder_get_sizeback to summary
public static final long custom_decoder_get_size

Function address.

custom_decoder_initback to summary
public static final long custom_decoder_init

Function address.

custom_encodeback to summary
public static final long custom_encode

Function address.

custom_encode_floatback to summary
public static final long custom_encode_float

Function address.

custom_encoder_createback to summary
public static final long custom_encoder_create

Function address.

custom_encoder_ctlback to summary
public static final long custom_encoder_ctl

Function address.

custom_encoder_destroyback to summary
public static final long custom_encoder_destroy

Function address.

custom_encoder_get_sizeback to summary
public static final long custom_encoder_get_size

Function address.

custom_encoder_initback to summary
public static final long custom_encoder_init

Function address.

custom_mode_createback to summary
public static final long custom_mode_create

Function address.

custom_mode_destroyback to summary
public static final long custom_mode_destroy

Function address.

Constructor Detail

Functionsback to summary
private Functions()