io.github.jaredmdobson.concentus

Class OpusDecoder

java.lang.Object

io.github.jaredmdobson.concentus.OpusDecoder

public class OpusDecoder
extends Object

The Opus decoder structure. Opus is a stateful codec with overlapping blocks and as a result Opus packets are not coded independently of each other. Packets must be passed into the decoder serially and in the correct order for a correct decode. Lost packets can be replaced with loss concealment by calling the decoder with a null reference and zero length for the missing packet. A single codec state may only be accessed from a single thread at a time and any required locking must be performed by the caller. Separate streams must be decoded with separate decoder states and can be decoded in parallel.

Version:

$Id: $Id

Constructor Summary

Constructors

Constructor and Description
OpusDecoder(int Fs, int channels) Allocates and initializes a decoder state.

Method Summary

Modifier and Type	Method and Description
int	decode(byte[] in_data, int in_data_offset, int len, byte[] out_pcm, int out_pcm_offset, int frame_size, boolean decode_fec) Decodes an Opus packet.
int	decode(byte[] in_data, int in_data_offset, int len, short[] out_pcm, int out_pcm_offset, int frame_size, boolean decode_fec) Decodes an Opus packet.
OpusBandwidth	getBandwidth() Getter for the field bandwidth.
int	getFinalRange() getFinalRange.
int	getGain() getGain.
int	getLastPacketDuration() getLastPacketDuration.
int	getPitch() getPitch.
int	getSampleRate() getSampleRate.
void	resetState() resetState.
void	setGain(int value) setGain.

Methods inherited from class java.lang.Object

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

Constructor Detail

OpusDecoder

public OpusDecoder(int Fs,
                   int channels)
            throws OpusException

Allocates and initializes a decoder state. 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. Likewise, the decoder is capable of filling in either mono or interleaved stereo pcm buffers, at the caller's request.

Parameters:

Fs - Sample rate to decode at (Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.

channels - Number of channels (1 or 2) to decode.

Throws:

OpusException

Method Detail

decode

public int decode(byte[] in_data,
                  int in_data_offset,
                  int len,
                  short[] out_pcm,
                  int out_pcm_offset,
                  int frame_size,
                  boolean decode_fec)
           throws OpusException

Decodes an Opus packet.

Parameters:

in_data - The input payload. This may be NULL if that previous packet was lost in transit (when PLC is enabled)

in_data_offset - The offset to use when reading the input payload. Usually 0

len - The number of bytes in the payload (the packet size)

out_pcm - A buffer to put the output PCM, in a short array. The output size is (# of samples) * (# of channels). You can use the OpusPacketInfo helpers to get a hint of the frame size before you decode the packet if you need exact sizing.

out_pcm_offset - The offset to use when writing to the output buffer

frame_size - The number of samples (per channel) of available space in the output PCM buf. If this is less than the maximum packet duration (120ms; 5760 for 48khz), this function will not be capable of decoding some packets. In the case of PLC (data == NULL) or FEC (decode_fec == true), then frame_size needs to be exactly the duration of the audio that is missing, otherwise the decoder will not be in an optimal state to decode the next incoming packet. For the PLC and FEC cases, frame_size *must* be a multiple of 2.5 ms.

decode_fec - Indicates that we want to recreate the PREVIOUS (lost) packet using FEC data from THIS packet. Using this packet recovery scheme, you will actually decode this packet twice, first with decode_fec TRUE and then again with FALSE. If FEC data is not available in this packet, the decoder will simply generate a best-effort recreation of the lost packet. In that case, the length of frame_size must be EXACTLY the length of the audio that was lost, or else the decoder will be in an inconsistent state.

Returns:

The number of decoded samples (per channel)

Throws:

OpusException

decode

public int decode(byte[] in_data,
                  int in_data_offset,
                  int len,
                  byte[] out_pcm,
                  int out_pcm_offset,
                  int frame_size,
                  boolean decode_fec)
           throws OpusException

Decodes an Opus packet.

Parameters:

in_data - The input payload. This may be NULL if that previous packet was lost in transit (when PLC is enabled)

in_data_offset - The offset to use when reading the input payload. Usually 0

len - The number of bytes in the payload (the packet size)

out_pcm - A buffer to put the output PCM, in a byte array. The output size is (# of samples) * (# of channels) * 2. You can use the OpusPacketInfo helpers to get a hint of the frame size before you decode the packet if you need exact sizing.

out_pcm_offset - The offset to use when writing to the output buffer

frame_size - The number of samples (per channel) of available space in the output PCM buf. If this is less than the maximum packet duration (120ms; 5760 for 48khz), this function will not be capable of decoding some packets. In the case of PLC (data == NULL) or FEC (decode_fec == true), then frame_size needs to be exactly the duration of the audio that is missing, otherwise the decoder will not be in an optimal state to decode the next incoming packet. For the PLC and FEC cases, frame_size *must* be a multiple of 2.5 ms.

decode_fec - Indicates that we want to recreate the PREVIOUS (lost) packet using FEC data from THIS packet. Using this packet recovery scheme, you will actually decode this packet twice, first with decode_fec TRUE and then again with FALSE. If FEC data is not available in this packet, the decoder will simply generate a best-effort recreation of the lost packet. In that case, the length of frame_size must be EXACTLY the length of the audio that was lost, or else the decoder will be in an inconsistent state.

Returns:

The number of decoded samples (per channel)

Throws:

OpusException

getBandwidth

public OpusBandwidth getBandwidth()

Getter for the field bandwidth.

Returns:

a OpusBandwidth object

getFinalRange

public int getFinalRange()

getFinalRange.

Returns:

a int

getSampleRate

public int getSampleRate()

getSampleRate.

Returns:

a int

getPitch

public int getPitch()

getPitch.

Returns:

a int

getGain

public int getGain()

getGain.

Returns:

a int

setGain

public void setGain(int value)

setGain.

Parameters:

value - a int

getLastPacketDuration

public int getLastPacketDuration()

getLastPacketDuration.

Returns:

a int

resetState

public void resetState()

resetState.