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

Class 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

    • Constructor Summary

      Constructors 
      Constructor Description
      Opus()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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​(long encoder)
      Wrapper around the native opus_encoder_ctl function.
      static int encoder_get_vbr_constraint​(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​(long encoder, int vbr)
      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 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.

    • 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.