org.jitsi.impl.neomedia.codec.audio.opus

Class Opus

java.lang.Object

org.jitsi.impl.neomedia.codec.audio.opus.Opus

public class Opus
extends Object

Defines the API of the native opus library to be utilized by the libjitsi library.

Author:

Boris Grozev, Lyubomir Marinov

Field Summary

Fields

Modifier and Type	Field and Description
static int	BANDWIDTH_FULLBAND Opus fullband constant
static int	BANDWIDTH_MEDIUMBAND Opus mediumband constant
static int	BANDWIDTH_NARROWBAND Opus narrowband constant
static int	BANDWIDTH_SUPERWIDEBAND Opus superwideband constant
static int	BANDWIDTH_WIDEBAND Opus wideband constant
static int	INVALID_PACKET Opus constant for an invalid packet
static int	MAX_PACKET The maximum size of a packet we can create.
static int	OPUS_AUTO Constant used to set various settings to "automatic"
static int	OPUS_OK Constant usually indicating that no error occurred

Constructor Summary

Constructors

Constructor and Description
Opus()

Method Summary

Modifier and Type	Method and Description
static void	assertOpusIsFunctional() Asserts that the Opus class and the JNI library which supports it are functional.
static int	decode(long decoder, byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset, int outputFrameSize, int decodeFEC) Decodes an opus packet from input into output.
static long	decoder_create(int Fs, int channels) Creates an OpusDecoder structure, returns a pointer to it or 0 on error.
static void	decoder_destroy(long decoder) Destroys an OpusDecoder, freeing it's resources.
static int	decoder_get_nb_samples(long decoder, byte[] packet, int offset, int length) Returns the number of samples in an opus packet
static int	decoder_get_size(int channels) Returns the size in bytes required for an OpusDecoder structure.
static int	encode(long encoder, byte[] input, int inputOffset, int inputFrameSize, byte[] output, int outputOffset, int outputLength) Encodes the input from input into an opus packet in output.
static long	encoder_create(int Fs, int channels) Creates an OpusEncoder structure, returns a pointer to it casted to long.
static void	encoder_destroy(long encoder) Destroys an OpusEncoder, freeing it's resources.
static int	encoder_get_bandwidth(long encoder) Wrapper around the native opus_encoder_ctl function.
static int	encoder_get_bitrate(long encoder) Wrapper around the native opus_encoder_ctl function.
static int	encoder_get_complexity(long encoder)
static int	encoder_get_dtx(long encoder) Wrapper around the native opus_encoder_ctl function.
static int	encoder_get_inband_fec(long encoder) Wrapper around the native opus_encoder_ctl function.
static int	encoder_get_size(int channels) Returns the size in bytes required for an OpusEncoder structure.
static int	encoder_get_vbr_constraint(long encoder) Wrapper around the native opus_encoder_ctl function.
static int	encoder_get_vbr(long encoder) Wrapper around the native opus_encoder_ctl function.
static int	encoder_set_bandwidth(long encoder, int bandwidth) Wrapper around the native opus_encoder_ctl function.
static int	encoder_set_bitrate(long encoder, int bitrate) Wrapper around the native opus_encoder_ctl function.
static int	encoder_set_complexity(long encoder, int complexity) Wrapper around the native opus_encoder_ctl function.
static int	encoder_set_dtx(long encoder, int dtx) Wrapper around the native opus_encoder_ctl function.
static int	encoder_set_force_channels(long encoder, int forcechannels) Wrapper around the native opus_encoder_ctl function.
static int	encoder_set_inband_fec(long encoder, int inbandFEC) Wrapper around the native opus_encoder_ctl function.
static int	encoder_set_max_bandwidth(long encoder, int maxBandwidth) Wrapper around the native opus_encoder_ctl function.
static int	encoder_set_packet_loss_perc(long encoder, int packetLossPerc) Wrapper around the native opus_encoder_ctl function.
static int	encoder_set_vbr_constraint(long encoder, int use_cvbr) Wrapper around the native opus_encoder_ctl function.
static int	encoder_set_vbr(long encoder, int vbr) Wrapper around the native opus_encoder_ctl function.
static int	packet_get_bandwidth(byte[] data, int offset) Returns the audio bandwidth of an Opus packet, one of BANDWIDTH_FULLBAND, BANDWIDTH_MEDIUMBAND, BANDWIDTH_NARROWBAND, BANDWIDTH_SUPERWIDEBAND or BANDWIDTH_WIDEBAND, or INVALID_PACKET on error.
static int	packet_get_nb_channels(byte[] data, int offset) Returns the number of channels encoded in an Opus packet.
static int	packet_get_nb_frames(byte[] packet, int offset, int length) Returns the number of frames in an Opus packet.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BANDWIDTH_FULLBAND

public static final int BANDWIDTH_FULLBAND

Opus fullband constant

See Also:

Constant Field Values

BANDWIDTH_MEDIUMBAND

public static final int BANDWIDTH_MEDIUMBAND

Opus mediumband constant

See Also:

Constant Field Values

BANDWIDTH_NARROWBAND

public static final int BANDWIDTH_NARROWBAND

Opus narrowband constant

See Also:

Constant Field Values

BANDWIDTH_SUPERWIDEBAND

public static final int BANDWIDTH_SUPERWIDEBAND

Opus superwideband constant

See Also:

Constant Field Values

BANDWIDTH_WIDEBAND

public static final int BANDWIDTH_WIDEBAND

Opus wideband constant

See Also:

Constant Field Values

INVALID_PACKET

public static final int INVALID_PACKET

Opus constant for an invalid packet

See Also:

Constant Field Values

MAX_PACKET

public static final int MAX_PACKET

The maximum size of a packet we can create. Since we're only creating packets with a single frame, that's a 1 byte TOC + the maximum frame size. See http://tools.ietf.org/html/rfc6716#section-3.2

See Also:

Constant Field Values

OPUS_AUTO

public static final int OPUS_AUTO

Constant used to set various settings to "automatic"

See Also:

Constant Field Values

OPUS_OK

public static final int OPUS_OK

Constant usually indicating that no error occurred

See Also:

Constant Field Values

Constructor Detail

Opus

public Opus()

Method Detail

assertOpusIsFunctional

public static void assertOpusIsFunctional()

Asserts that the Opus class and the JNI library which supports it are functional. The method is to be invoked early (e.g. static/class initializers) by classes which require it (i.e. they depend on it and they cannot function without it).

decode

public static int decode(long decoder,
                         byte[] input,
                         int inputOffset,
                         int inputLength,
                         byte[] output,
                         int outputOffset,
                         int outputFrameSize,
                         int decodeFEC)

Decodes an opus packet from input into output.

Parameters:

decoder - the OpusDecoder state to perform the decoding

input - an array of bytes which represents the input payload to decode. If null, indicates packet loss.

inputOffset - the offset in input at which the payload to be decoded begins

inputLength - the length in bytes in input beginning at inputOffset of the payload to be decoded

output - an array of bytes into which the decoded signal is to be output

outputOffset - the offset in output at which the output of the decoded signal is to begin

outputFrameSize - the number of samples per channel output beginning at outputOffset of the maximum space available for output of the decoded signal

decodeFEC - 0 to decode the packet normally, 1 to decode the FEC data in the packet

Returns:

the number of decoded samples written into output (beginning at outputOffset)

decoder_create

public static long decoder_create(int Fs,
                                  int channels)

Creates an OpusDecoder structure, returns a pointer to it or 0 on error.

Parameters:

Fs - Sample rate to decode to

channels - number of channels to decode to(1/2)

Returns:

A pointer to the OpusDecoder structure created, 0 on error.

decoder_destroy

public static void decoder_destroy(long decoder)

Destroys an OpusDecoder, freeing it's resources.

Parameters:

decoder - Address of the structure (as returned from decoder_create)

decoder_get_nb_samples

public static int decoder_get_nb_samples(long decoder,
                                         byte[] packet,
                                         int offset,
                                         int length)

Returns the number of samples in an opus packet

Parameters:

decoder - The decoder to use.

packet - Array holding the packet.

offset - Offset into packet where the actual packet begins.

length - Length of the packet.

Returns:

the number of samples in packet .

decoder_get_size

public static int decoder_get_size(int channels)

Returns the size in bytes required for an OpusDecoder structure.

Parameters:

channels - number of channels (1/2)

Returns:

the size in bytes required for an OpusDecoder structure.

encode

public static int encode(long encoder,
                         byte[] input,
                         int inputOffset,
                         int inputFrameSize,
                         byte[] output,
                         int outputOffset,
                         int outputLength)

Encodes the input from input into an opus packet in output.

Parameters:

encoder - The encoder to use.

input - Array containing PCM encoded input.

inputOffset - Offset to use into the input array

inputFrameSize - The number of samples per channel in input.

output - Array where the encoded packet will be stored.

outputOffset - Offset to use into the output array

outputLength - The number of available bytes in output.

Returns:

The number of bytes written in output, or a negative on error.

encoder_create

public static long encoder_create(int Fs,
                                  int channels)

Creates an OpusEncoder structure, returns a pointer to it casted to long. The native function's application parameter is always set to OPUS_APPLICATION_VOIP.

Parameters:

Fs - Sample rate of the input PCM

channels - number of channels in the input (1/2)

Returns:

A pointer to the OpusEncoder structure created, 0 on error

encoder_destroy

public static void encoder_destroy(long encoder)

Destroys an OpusEncoder, freeing it's resources.

Parameters:

encoder - Address of the structure (as returned from encoder_create)

encoder_get_bandwidth

public static int encoder_get_bandwidth(long encoder)

Wrapper around the native opus_encoder_ctl function. Returns the current encoder audio bandwidth .

Parameters:

encoder - The encoder to use

Returns:

the current encoder audio bandwidth

encoder_get_bitrate

public static int encoder_get_bitrate(long encoder)

Wrapper around the native opus_encoder_ctl function. Returns the current encoder bitrate.

Parameters:

encoder - The encoder to use

Returns:

The current encoder bitrate.

encoder_get_complexity

public static int encoder_get_complexity(long encoder)

encoder_get_dtx

public static int encoder_get_dtx(long encoder)

Wrapper around the native opus_encoder_ctl function. Returns the current DTX setting of the encoder.

Parameters:

encoder - The encoder to use

Returns:

the current DTX setting of the encoder.

encoder_get_inband_fec

public static int encoder_get_inband_fec(long encoder)

Wrapper around the native opus_encoder_ctl function. Returns the current inband FEC encoder setting.

Parameters:

encoder - The encoder to use

Returns:

the current inband FEC encoder setting.

encoder_get_size

public static int encoder_get_size(int channels)

Returns the size in bytes required for an OpusEncoder structure.

Parameters:

channels - number of channels (1/2)

Returns:

the size in bytes required for an OpusEncoder structure.

encoder_get_vbr

public static int encoder_get_vbr(long encoder)

Wrapper around the native opus_encoder_ctl function. Returns the current encoder VBR setting

Parameters:

encoder - The encoder to use

Returns:

The current encoder VBR setting.

encoder_get_vbr_constraint

public static int encoder_get_vbr_constraint(long encoder)

Wrapper around the native opus_encoder_ctl function. Returns the current VBR constraint encoder setting.

Parameters:

encoder - The encoder to use

Returns:

the current VBR constraint encoder setting.

encoder_set_bandwidth

public static int encoder_set_bandwidth(long encoder,
                                        int bandwidth)

Wrapper around the native opus_encoder_ctl function. Sets the encoder audio bandwidth.

Parameters:

encoder - The encoder to use

bandwidth - The bandwidth to set, should be one of BANDWIDTH_FULLBAND, BANDWIDTH_MEDIUMBAND, BANDWIDTH_NARROWBAND, BANDWIDTH_SUPERWIDEBAND or BANDWIDTH_WIDEBAND.

Returns:

OPUS_OK on success

encoder_set_bitrate

public static int encoder_set_bitrate(long encoder,
                                      int bitrate)

Wrapper around the native opus_encoder_ctl function. Sets the encoder bitrate

Parameters:

encoder - The encoder to use

bitrate - The bitrate to set

Returns:

OPUS_OK on success

encoder_set_complexity

public static int encoder_set_complexity(long encoder,
                                         int complexity)

Wrapper around the native opus_encoder_ctl function. Sets the encoder complexity setting.

Parameters:

encoder - The encoder to use

complexity - The complexity level, from 1 to 10

Returns:

OPUS_OK on success

encoder_set_dtx

public static int encoder_set_dtx(long encoder,
                                  int dtx)

Wrapper around the native opus_encoder_ctl function. Sets the DTX setting of the encoder.

Parameters:

encoder - The encoder to use

dtx - 0 to turn DTX off, non-zero to turn it on

Returns:

OPUS_OK on success

encoder_set_force_channels

public static int encoder_set_force_channels(long encoder,
                                             int forcechannels)

Wrapper around the native opus_encoder_ctl function. Sets the force channels setting of the encoder.

Parameters:

encoder - The encoder to use

forcechannels - Number of channels

Returns:

OPUS_OK on success

encoder_set_inband_fec

public static int encoder_set_inband_fec(long encoder,
                                         int inbandFEC)

Wrapper around the native opus_encoder_ctl function. Sets the encoder FEC setting.

Parameters:

encoder - The encoder to use

inbandFEC - 0 to turn FEC off, non-zero to turn it on.

Returns:

OPUS_OK on success

encoder_set_max_bandwidth

public static int encoder_set_max_bandwidth(long encoder,
                                            int maxBandwidth)

Wrapper around the native opus_encoder_ctl function. Sets the maximum audio bandwidth to be used by the encoder.

Parameters:

encoder - The encoder to use

maxBandwidth - The maximum bandwidth to use, should be one of BANDWIDTH_FULLBAND, BANDWIDTH_MEDIUMBAND, BANDWIDTH_NARROWBAND, BANDWIDTH_SUPERWIDEBAND or BANDWIDTH_WIDEBAND

Returns:

OPUS_OK on success.

encoder_set_packet_loss_perc

public static int encoder_set_packet_loss_perc(long encoder,
                                               int packetLossPerc)

Wrapper around the native opus_encoder_ctl function. Sets the encoder's expected packet loss percentage.

Parameters:

encoder - The encoder to use

Returns:

OPUS_OK on success.

encoder_set_vbr

public static int encoder_set_vbr(long encoder,
                                  int vbr)

Wrapper around the native opus_encoder_ctl function. Sets the encoder VBR setting

Parameters:

encoder - The encoder to use

vbr - 0 to turn VBR off, non-zero to turn it on.

Returns:

OPUS_OK on success

encoder_set_vbr_constraint

public static int encoder_set_vbr_constraint(long encoder,
                                             int use_cvbr)

Wrapper around the native opus_encoder_ctl function. Sets the encoder VBR constraint setting

Parameters:

encoder - The encoder to use

use_cvbr - 0 to turn VBR constraint off, non-zero to turn it on.

Returns:

OPUS_OK on success

packet_get_bandwidth

public static int packet_get_bandwidth(byte[] data,
                                       int offset)

Returns the audio bandwidth of an Opus packet, one of BANDWIDTH_FULLBAND, BANDWIDTH_MEDIUMBAND, BANDWIDTH_NARROWBAND, BANDWIDTH_SUPERWIDEBAND or BANDWIDTH_WIDEBAND, or INVALID_PACKET on error.

Parameters:

data - Array holding the packet.

offset - Offset into packet where the actual packet begins.

Returns:

one of BANDWIDTH_FULLBAND, BANDWIDTH_MEDIUMBAND, BANDWIDTH_NARROWBAND, BANDWIDTH_SUPERWIDEBAND, BANDWIDTH_WIDEBAND, or INVALID_PACKET on error.

packet_get_nb_channels

public static int packet_get_nb_channels(byte[] data,
                                         int offset)

Returns the number of channels encoded in an Opus packet.

Parameters:

data - Array holding the packet.

offset - Offset into packet where the actual packet begins.

Returns:

the number of channels encoded in data.

packet_get_nb_frames

public static int packet_get_nb_frames(byte[] packet,
                                       int offset,
                                       int length)

Returns the number of frames in an Opus packet.

Parameters:

packet - Array holding the packet.

offset - Offset into packet where the actual packet begins.

length - Length of the packet.

Returns:

the number of frames in packet.