Class Opus


  • public class Opus
    extends java.lang.Object
    Native bindings to the Opus library.

    The Opus codec is designed for interactive speech and audio transmission over the Internet. It is designed by the IETF Codec Working Group and incorporates technology from Skype's SILK codec and Xiph.Org's CELT codec.

    The Opus codec is designed to handle a wide range of interactive audio applications, including Voice over IP, videoconferencing, in-game chat, and even remote live music performances. It can scale from low bit-rate narrowband speech to very high quality stereo music. Its main features are:

    • Sampling rates from 8 to 48 kHz
    • Bit-rates from 6 kb/s to 510 kb/s
    • Support for both constant bit-rate (CBR) and variable bit-rate (VBR)
    • Audio bandwidth from narrowband to full-band
    • Support for speech and music
    • Support for mono and stereo
    • Support for multichannel (up to 255 channels)
    • Frame sizes from 2.5 ms to 60 ms
    • Good loss robustness and packet loss concealment (PLC)
    • Floating point and fixed-point implementation

    Opus Encoder

    This section describes the process and functions used to encode Opus.

    Since Opus is a stateful codec, the encoding process starts with creating an encoder state. This can be done with:

    
     int error;
     OpusEncoder *enc;
     enc = opus_encoder_create(Fs, channels, application, &error);

    From this point, enc can be used for encoding an audio stream. An encoder state must not be used for more than one stream at the same time. Similarly, the encoder state must not be re-initialized for each frame.

    While encoder_create allocates memory for the state, it's also possible to initialize pre-allocated memory:

    
             int size;
     int error;
     OpusEncoder *enc;
     size = opus_encoder_get_size(channels);
     enc = malloc(size);
     error = opus_encoder_init(enc, Fs, channels, application);

    where encoder_get_size returns the required size for the encoder state. Note that future versions of this code may change the size, so no assuptions should be made about it.

    The encoder state is always continuous in memory and only a shallow copy is sufficient to copy it (e.g. memcpy()).

    It is possible to change some of the encoder's settings using the encoder_ctl interface. All these settings already default to the recommended value, so they should only be changed when necessary. The most common settings one may want to change are:

    
     opus_encoder_ctl(enc, OPUS_SET_BITRATE(bitrate));
     opus_encoder_ctl(enc, OPUS_SET_COMPLEXITY(complexity));
     opus_encoder_ctl(enc, OPUS_SET_SIGNAL(signal_type));

    where

    • bitrate is in bits per second (b/s),
    • complexity is a value from 1 to 10, where 1 is the lowest complexity and 10 is the highest, and
    • signal_type is either AUTO (default), SIGNAL_VOICE, or SIGNAL_MUSIC.

    See Encoder related CTLs and Generic CTLs for a complete list of parameters that can be set or queried. Most parameters can be set or changed at any time during a stream.

    To encode a frame, encode or encode_float must be called with exactly one frame (2.5, 5, 10, 20, 40 or 60 ms) of audio data:

    
     len = opus_encode(enc, audio_frame, frame_size, packet, max_packet);

    where

    • audio_frame is the audio data in short (or float for encode_float),
    • frame_size is the duration of the frame in samples (per channel),
    • packet is the byte array to which the compressed data is written, and
    • max_packet is the maximum number of bytes that can be written in the packet (4000 bytes is recommended). Do not use max_packet to control VBR target bitrate, instead use the SET_BITRATE_REQUEST CTL.

    encode and encode_float return the number of bytes actually written to the packet. The return value can be negative, which indicates that an error has occurred. If the return value is 2 bytes or less, then the packet does not need to be transmitted (DTX).

    Once the encoder state if no longer needed, it can be destroyed with

    
     opus_encoder_destroy(enc);

    If the encoder was created with encoder_init rather than encoder_create, then no action is required aside from potentially freeing the memory that was manually allocated for it (calling free(enc) for the example above).

    Opus Decoder

    This page describes the process and functions used to decode Opus.

    The decoding process also starts with creating a decoder state. This can be done with:

    
     int error;
     OpusDecoder *dec;
     dec = opus_decoder_create(Fs, channels, &error);

    where

    • Fs is the sampling rate and must be 8000, 12000, 16000, 24000, or 48000
    • channels is the number of channels (1 or 2)
    • error will hold the error code in case of failure (or OK on success), and
    • the return value is a newly created decoder state to be used for decoding.

    While decoder_create allocates memory for the state, it's also possible to initialize pre-allocated memory:

    
     int size;
     int error;
     OpusDecoder *dec;
     size = opus_decoder_get_size(channels);
     dec = malloc(size);
     error = opus_decoder_init(dec, Fs, channels);

    where decoder_get_size returns the required size for the decoder state. Note that future versions of this code may change the size, so no assuptions should be made about it.

    The decoder state is always continuous in memory and only a shallow copy is sufficient to copy it (e.g. memcpy()).

    To decode a frame, decode or decode_float must be called with a packet of compressed audio data:

    
     frame_size = opus_decode(dec, packet, len, decoded, max_size, 0);

    where

    • packet is the byte array containing the compressed data
    • len is the exact number of bytes contained in the packet
    • decoded is the decoded audio data in opus_int16 (or float for decode_float), and
    • max_size is the max duration of the frame in samples (per channel) that can fit into the decoded_frame array.

    decode and decode_float return the number of samples (per channel) decoded from the packet. If that value is negative, then an error has occurred. This can occur if the packet is corrupted or if the audio buffer is too small to hold the decoded audio.

    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 pointer 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 unless the library was compiled with NONTHREADSAFE_PSEUDOSTACK defined.

    Repacketizer

    The repacketizer can be used to merge multiple Opus packets into a single packet or alternatively to split Opus packets that have previously been merged. Splitting valid Opus packets is always guaranteed to succeed, whereas merging valid packets only succeeds if all frames have the same mode, bandwidth, and frame size, and when the total duration of the merged packet is no more than 120 ms. The 120 ms limit comes from the specification and limits decoder memory requirements at a point where framing overhead becomes negligible.

    The repacketizer currently only operates on elementary Opus streams. It will not manipualte multistream packets successfully, except in the degenerate case where they consist of data from a single stream.

    The repacketizing process starts with creating a repacketizer state, either by calling repacketizer_create or by allocating the memory yourself, e.g.,

    
     OpusRepacketizer *rp;
     rp = (OpusRepacketizer*)malloc(opus_repacketizer_get_size());
     if (rp != NULL)
         opus_repacketizer_init(rp);

    Then the application should submit packets with repacketizer_cat, extract new packets with repacketizer_out or repacketizer_out_range, and then reset the state for the next set of input packets via repacketizer_init.

    For example, to split a sequence of packets into individual frames:

    
     unsigned char *data;
     int len;
     while (get_next_packet(&data, &len))
     {
       unsigned char out[1276];
       opus_int32 out_len;
       int nb_frames;
       int err;
       int i;
       err = opus_repacketizer_cat(rp, data, len);
       if (err != OPUS_OK)
       {
         release_packet(data);
         return err;
       }
       nb_frames = opus_repacketizer_get_nb_frames(rp);
       for (i = 0; i < nb_frames; i++)
       {
         out_len = opus_repacketizer_out_range(rp, i, i+1, out, sizeof(out));
         if (out_len < 0)
         {
            release_packet(data);
            return (int)out_len;
         }
         output_next_packet(out, out_len);
       }
       opus_repacketizer_init(rp);
       release_packet(data);
     }

    Alternatively, to combine a sequence of frames into packets that each contain up to TARGET_DURATION_MS milliseconds of data:

    
     // The maximum number of packets with duration TARGET_DURATION_MS occurs
     // when the frame size is 2.5 ms, for a total of (TARGET_DURATION_MS*2/5)
     // packets.
     unsigned char *data[(TARGET_DURATION_MS*2/5)+1];
     opus_int32 len[(TARGET_DURATION_MS*2/5)+1];
     int nb_packets;
     unsigned char out[1277*(TARGET_DURATION_MS*2/2)];
     opus_int32 out_len;
     int prev_toc;
     nb_packets = 0;
     while (get_next_packet(data+nb_packets, len+nb_packets))
     {
       int nb_frames;
       int err;
       nb_frames = opus_packet_get_nb_frames(data[nb_packets], len[nb_packets]);
       if (nb_frames < 1)
       {
         release_packets(data, nb_packets+1);
         return nb_frames;
       }
       nb_frames += opus_repacketizer_get_nb_frames(rp);
       // If adding the next packet would exceed our target, or it has an
       // incompatible TOC sequence, output the packets we already have before
       // submitting it.
       // N.B., The nb_packets > 0 check ensures we've submitted at least one
       // packet since the last call to opus_repacketizer_init(). Otherwise a
       // single packet longer than TARGET_DURATION_MS would cause us to try to
       // output an (invalid) empty packet. It also ensures that prev_toc has
       // been set to a valid value. Additionally, len[nb_packets] > 0 is
       // guaranteed by the call to opus_packet_get_nb_frames() above, so the
       // reference to data[nb_packets][0] should be valid.
       if (nb_packets > 0 && (
           ((prev_toc & 0xFC) != (data[nb_packets][0] & 0xFC)) ||
           opus_packet_get_samples_per_frame(data[nb_packets], 48000)*nb_frames >
           TARGET_DURATION_MS*48))
       {
         out_len = opus_repacketizer_out(rp, out, sizeof(out));
         if (out_len < 0)
         {
            release_packets(data, nb_packets+1);
            return (int)out_len;
         }
         output_next_packet(out, out_len);
         opus_repacketizer_init(rp);
         release_packets(data, nb_packets);
         data[0] = data[nb_packets];
         len[0] = len[nb_packets];
         nb_packets = 0;
       }
       err = opus_repacketizer_cat(rp, data[nb_packets], len[nb_packets]);
       if (err != OPUS_OK)
       {
         release_packets(data, nb_packets+1);
         return err;
       }
       prev_toc = data[nb_packets][0];
       nb_packets++;
     }
     // Output the final, partial packet.
     if (nb_packets > 0)
     {
       out_len = opus_repacketizer_out(rp, out, sizeof(out));
       release_packets(data, nb_packets);
       if (out_len < 0)
         return (int)out_len;
       output_next_packet(out, out_len);
     }

    An alternate way of merging packets is to simply call repacketizer_cat unconditionally until it fails. At that point, the merged packet can be obtained with opus_repacketizer_out() and the input packet for which opus_repacketizer_cat() needs to be re-added to a newly reinitialized repacketizer state.

    • Method Detail

      • opus_encoder_get_size

        public static int opus_encoder_get_size​(int channels)
        Gets the size of an OpusEncoder structure.
        Parameters:
        channels - number of channels. One of:
        12
        Returns:
        the size in bytes
      • nopus_encoder_create

        public static long nopus_encoder_create​(int Fs,
                                                int channels,
                                                int application,
                                                long error)
        Unsafe version of: encoder_create
      • opus_encoder_create

        public static long opus_encoder_create​(int Fs,
                                               int channels,
                                               int application,
                                               @Nullable
                                               java.nio.IntBuffer error)
        Allocates and initializes an encoder state.

        There are three coding modes:

        • APPLICATION_VOIP: gives best quality at a given bitrate for voice signals.

          It enhances the input signal by high-pass filtering and emphasizing formants and harmonics. Optionally it includes in-band forward error correction to protect against packet loss. Use this mode for typical VoIP applications. Because of the enhancement, even at high bitrates the output may sound different from the input.

        • APPLICATION_AUDIO: gives best quality at a given bitrate for most non-voice signals like music.

          Use this mode for music and mixed (music/voice) content, broadcast, and applications requiring less than 15 ms of coding delay.

        • APPLICATION_RESTRICTED_LOWDELAY: configures low-delay mode that disables the speech-optimized mode in exchange for slightly reduced delay.

          This mode can only be set on an newly initialized or freshly reset encoder because it changes the codec delay.

        This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution).

        Note

        Regardless of the sampling rate and number channels selected, the Opus encoder can switch to a lower audio bandwidth or number of channels if the bitrate selected is too low. This also means that it is safe to always use 48 kHz stereo input and let the encoder optimize the encoding.

        Parameters:
        Fs - sampling rate of input signal (Hz). One of:
        800012000160002400048000
        channels - number of channels in input signal. One of:
        12
        application - coding mode. One of:
        APPLICATION_VOIPAPPLICATION_AUDIOAPPLICATION_RESTRICTED_LOWDELAY
        error - one of:
        OKBAD_ARGBUFFER_TOO_SMALLINTERNAL_ERRORINVALID_PACKETUNIMPLEMENTEDINVALID_STATE
        ALLOC_FAIL
      • opus_encoder_init

        public static int opus_encoder_init​(long st,
                                            int Fs,
                                            int channels,
                                            int application)
        Initializes a previously allocated encoder state.

        The memory pointed to by st must be at least the size returned by 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 - encoder state
        Fs - sampling rate of input signal (Hz). One of:
        800012000160002400048000
        channels - number of channels in input signal. One of:
        12
        application - coding mode. One of:
        APPLICATION_VOIPAPPLICATION_AUDIOAPPLICATION_RESTRICTED_LOWDELAY
        Returns:
        OK on success or a negative error code on error
      • nopus_encode

        public static int nopus_encode​(long st,
                                       long pcm,
                                       int frame_size,
                                       long data,
                                       int max_data_bytes)
        Unsafe version of: encode
        Parameters:
        max_data_bytes - size of the allocated memory for the output payload. This may be used to impose an upper limit on the instant bitrate, but should not be used as the only bitrate control. Use SET_BITRATE_REQUEST to control the bitrate.
      • opus_encode

        public static int opus_encode​(long st,
                                      java.nio.ShortBuffer pcm,
                                      int frame_size,
                                      java.nio.ByteBuffer data)
        Encodes an Opus frame.
        Parameters:
        st - encoder state
        pcm - input signal (interleaved if 2 channels) (length is frame_size*channels*sizeof(opus_int16))
        frame_size - number of samples per channel in the input signal. This must be an Opus frame size for the encoder's sampling rate. For example, at 48 kHz the permitted values are 120, 240, 480, 960, 1920, and 2880. Passing in a duration of less than 10 ms (480 samples at 48 kHz) will prevent the encoder from using the LPC or hybrid modes.
        data - output payload
        Returns:
        the length of the encoded packet (in bytes) on success or a negative error code on error
      • nopus_encode_float

        public static int nopus_encode_float​(long st,
                                             long pcm,
                                             int frame_size,
                                             long data,
                                             int max_data_bytes)
        Unsafe version of: encode_float
        Parameters:
        max_data_bytes - size of the allocated memory for the output payload. This may be used to impose an upper limit on the instant bitrate, but should not be used as the only bitrate control. Use SET_BITRATE_REQUEST to control the bitrate.
      • opus_encode_float

        public static int opus_encode_float​(long st,
                                            java.nio.FloatBuffer pcm,
                                            int frame_size,
                                            java.nio.ByteBuffer data)
        Encodes an Opus frame from floating point input.
        Parameters:
        st - encoder state
        pcm - input signal (interleaved if 2 channels) 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. (length is frame_size*channels*sizeof(float))
        frame_size - number of samples per channel in the input signal. This must be an Opus frame size for the encoder's sampling rate. For example, at 48 kHz the permitted values are 120, 240, 480, 960, 1920, and 2880. Passing in a duration of less than 10 ms (480 samples at 48 kHz) will prevent the encoder from using the LPC or hybrid modes.
        data - output payload
        Returns:
        the length of the encoded packet (in bytes) on success or a negative error code on error
      • opus_encoder_destroy

        public static void opus_encoder_destroy​(long st)
        Frees an OpusEncoder allocated by encoder_create.
        Parameters:
        st - state to be freed
      • opus_decoder_get_size

        public static int opus_decoder_get_size​(int channels)
        Gets the size of an OpusDecoder structure.
        Parameters:
        channels - number of channels. One of:
        12
        Returns:
        the size in bytes
      • nopus_decoder_create

        public static long nopus_decoder_create​(int Fs,
                                                int channels,
                                                long error)
        Unsafe version of: decoder_create
      • opus_decoder_create

        public static long opus_decoder_create​(int Fs,
                                               int channels,
                                               @Nullable
                                               java.nio.IntBuffer error)
        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 - sampling rate of input signal (Hz). One of:
        800012000160002400048000
        channels - number of channels to decode. One of:
        12
        error - one of:
        OKBAD_ARGBUFFER_TOO_SMALLINTERNAL_ERRORINVALID_PACKETUNIMPLEMENTEDINVALID_STATE
        ALLOC_FAIL
      • opus_decoder_init

        public static int opus_decoder_init​(long st,
                                            int Fs,
                                            int channels)
        Initializes a previously allocated decoder state.

        The state must be at least the size returned by 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 - decoder state
        Fs - sampling rate of input signal (Hz). One of:
        800012000160002400048000
        channels - number of channels to decode. One of:
        12
        Returns:
        OK on success or a negative error code on error
      • nopus_decode

        public static int nopus_decode​(long st,
                                       long data,
                                       int len,
                                       long pcm,
                                       int frame_size,
                                       int decode_fec)
        Unsafe version of: decode
        Parameters:
        len - number of bytes in payload
      • opus_decode

        public static int opus_decode​(long st,
                                      @Nullable
                                      java.nio.ByteBuffer data,
                                      java.nio.ShortBuffer pcm,
                                      int frame_size,
                                      int decode_fec)
        Decodes an Opus packet.
        Parameters:
        st - decoder state
        data - input payload (Use a NULL pointer to indicate packet loss)
        pcm - output signal (interleaved if 2 channels) (length is frame_size*channels*sizeof(opus_int16)
        frame_size - number of samples per channel of available space in pcm.

        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=1), then frame_size needs to be exactly the duration of audio that is missing, otherwise the decoder will not be in the 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 - flag (0 or 1) to request that any in-band forward error correction data be decoded. If no such data is available, the frame is decoded as if it were lost.
        Returns:
        number of decoded samples or a negative error code
      • nopus_decode_float

        public static int nopus_decode_float​(long st,
                                             long data,
                                             int len,
                                             long pcm,
                                             int frame_size,
                                             int decode_fec)
        Unsafe version of: decode_float
        Parameters:
        len - number of bytes in payload
      • opus_decode_float

        public static int opus_decode_float​(long st,
                                            @Nullable
                                            java.nio.ByteBuffer data,
                                            java.nio.ShortBuffer pcm,
                                            int frame_size,
                                            int decode_fec)
        Decodes an Opus packet with floating point output.
        Parameters:
        st - decoder state
        data - input payload (Use a NULL pointer to indicate packet loss)
        pcm - output signal (interleaved if 2 channels) (length is frame_size*channels*sizeof(opus_int16)
        frame_size - number of samples per channel of available space in pcm.

        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=1), then frame_size needs to be exactly the duration of audio that is missing, otherwise the decoder will not be in the 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 - flag (0 or 1) to request that any in-band forward error correction data be decoded. If no such data is available, the frame is decoded as if it were lost.
        Returns:
        number of decoded samples or a negative error code
      • opus_decoder_destroy

        public static void opus_decoder_destroy​(long st)
        Frees an OpusDecoder allocated by decoder_create.
        Parameters:
        st - decoder state
      • nopus_packet_parse

        public static int nopus_packet_parse​(long data,
                                             int len,
                                             long out_toc,
                                             long frames,
                                             long size,
                                             long payload_offset)
        Unsafe version of: packet_parse
        Parameters:
        len - size of data
      • opus_packet_parse

        public static int opus_packet_parse​(java.nio.ByteBuffer data,
                                            @Nullable
                                            java.nio.ByteBuffer out_toc,
                                            @Nullable
                                            PointerBuffer frames,
                                            java.nio.ShortBuffer size,
                                            @Nullable
                                            java.nio.IntBuffer payload_offset)
        Parses an opus packet into one or more frames.

        decode will perform this operation internally so most applications do not need to use this function.

        This function does not copy the frames, the returned pointers are pointers into the input packet.

        Parameters:
        data - Opus packet to be parsed
        out_toc - TOC pointer
        frames - encapsulated frames
        size - sizes of the encapsulated frames
        payload_offset - returns the position of the payload within the packet (in bytes)
      • nopus_packet_get_bandwidth

        public static int nopus_packet_get_bandwidth​(long data)
        Unsafe version of: packet_get_bandwidth
      • opus_packet_get_bandwidth

        public static int opus_packet_get_bandwidth​(java.nio.ByteBuffer data)
        Gets the bandwidth of an Opus packet.
        Parameters:
        data - Opus packet
        Returns:
        the bandwidth of the packer on success, or INVALID_PACKET if the compressed data passed is corrupted or of an unsupported type
      • nopus_packet_get_samples_per_frame

        public static int nopus_packet_get_samples_per_frame​(long data,
                                                             int Fs)
        Unsafe version of: packet_get_samples_per_frame
      • opus_packet_get_samples_per_frame

        public static int opus_packet_get_samples_per_frame​(java.nio.ByteBuffer data,
                                                            int Fs)
        Gets the number of samples per frame from an Opus packet.
        Parameters:
        data - Opus packet. This must contain at least one byte of data.
        Fs - sampling rate in Hz. This must be a multiple of 400, or inaccurate results will be returned.
        Returns:
        number of samples per frame
      • nopus_packet_get_nb_channels

        public static int nopus_packet_get_nb_channels​(long data)
        Unsafe version of: packet_get_nb_channels
      • opus_packet_get_nb_channels

        public static int opus_packet_get_nb_channels​(java.nio.ByteBuffer data)
        Gets the number of channels from an Opus packet.
        Parameters:
        data - Opus packet
        Returns:
        number of channels, or INVALID_PACKET if the compressed data passed is corrupted or of an unsupported type
      • nopus_packet_get_nb_frames

        public static int nopus_packet_get_nb_frames​(long packet,
                                                     int len)
        Unsafe version of: packet_get_nb_frames
        Parameters:
        len - length of packet
      • opus_packet_get_nb_frames

        public static int opus_packet_get_nb_frames​(java.nio.ByteBuffer packet)
        Gets the number of frames in an Opus packet.
        Parameters:
        packet - Opus packet
        Returns:
        number of frames, BAD_ARG if insufficient data was passed to the function, or INVALID_PACKET if the compressed data passed is corrupted or of an unsupported type
      • nopus_packet_get_nb_samples

        public static int nopus_packet_get_nb_samples​(long packet,
                                                      int len,
                                                      int Fs)
        Unsafe version of: packet_get_nb_samples
        Parameters:
        len - length of packet
      • opus_packet_get_nb_samples

        public static int opus_packet_get_nb_samples​(java.nio.ByteBuffer packet,
                                                     int Fs)
        Gets the number of samples of an Opus packet.
        Parameters:
        packet - Opus packet
        Fs - sampling rate in Hz. This must be a multiple of 400, or inaccurate results will be returned.
        Returns:
        number of samples, BAD_ARG if insufficient data was passed to the function, or INVALID_PACKET if the compressed data passed is corrupted or of an unsupported type
      • nopus_decoder_get_nb_samples

        public static int nopus_decoder_get_nb_samples​(long dec,
                                                       long packet,
                                                       int len)
        Unsafe version of: decoder_get_nb_samples
        Parameters:
        len - length of packet
      • opus_decoder_get_nb_samples

        public static int opus_decoder_get_nb_samples​(long dec,
                                                      java.nio.ByteBuffer packet)
        Gets the number of samples of an Opus packet.
        Parameters:
        dec - decoder state
        packet - Opus packet
        Returns:
        number of samples, BAD_ARG if insufficient data was passed to the function, or INVALID_PACKET if the compressed data passed is corrupted or of an unsupported type
      • nopus_pcm_soft_clip

        public static void nopus_pcm_soft_clip​(long pcm,
                                               int frame_size,
                                               int channels,
                                               long softclip_mem)
        Unsafe version of: pcm_soft_clip
        Parameters:
        channels - number of channels
      • opus_pcm_soft_clip

        public static void opus_pcm_soft_clip​(java.nio.FloatBuffer pcm,
                                              int frame_size,
                                              java.nio.FloatBuffer softclip_mem)
        Applies soft-clipping to bring a float signal within the [-1,1] range. If the signal is already in that range, nothing is done. If there are values outside of [-1,1], then the signal is clipped as smoothly as possible to both fit in the range and avoid creating excessive distortion in the process.
        Parameters:
        pcm - input PCM and modified PCM
        frame_size - number of samples per channel to process
        softclip_mem - state memory for the soft clipping process (one float per channel, initialized to zero)
      • opus_repacketizer_get_size

        public static int opus_repacketizer_get_size()
        Gets the size of an OpusRepacketizer structure.
        Returns:
        the size in bytes
      • opus_repacketizer_init

        public static long opus_repacketizer_init​(long rp)
        (Re)initializes a previously allocated repacketizer state.

        The state must be at least the size returned by repacketizer_get_size. This can be used for applications which use their own allocator instead of malloc().

        It must also be called to reset the queue of packets waiting to be repacketized, which is necessary if the maximum packet duration of 120 ms is reached or if you wish to submit packets with a different Opus configuration (coding mode, audio bandwidth, frame size, or channel count). Failure to do so will prevent a new packet from being added with repacketizer_cat.

        Parameters:
        rp - the repacketizer state to (re)initialize
      • opus_repacketizer_create

        public static long opus_repacketizer_create()
        Allocates memory and initializes the new repacketizer with repacketizer_init.
      • opus_repacketizer_destroy

        public static void opus_repacketizer_destroy​(long rp)
        Frees an OpusRepacketizer allocated by repacketizer_create.
        Parameters:
        rp - state to be freed
      • nopus_repacketizer_cat

        public static int nopus_repacketizer_cat​(long rp,
                                                 long data,
                                                 int len)
        Unsafe version of: repacketizer_cat
        Parameters:
        len - the number of bytes in the packet data
      • opus_repacketizer_cat

        public static int opus_repacketizer_cat​(long rp,
                                                java.nio.ByteBuffer data)
        Adds a packet to the current repacketizer state.

        This packet must match the configuration of any packets already submitted for repacketization since the last call to repacketizer_init. This means that it must have the same coding mode, audio bandwidth, frame size, and channel count. This can be checked in advance by examining the top 6 bits of the first byte of the packet, and ensuring they match the top 6 bits of the first byte of any previously submitted packet. The total duration of audio in the repacketizer state also must not exceed 120 ms, the maximum duration of a single packet, after adding this packet.

        The contents of the current repacketizer state can be extracted into new packets using repacketizer_out or repacketizer_out_range.

        In order to add a packet with a different configuration or to add more audio beyond 120 ms, you must clear the repacketizer state by calling repacketizer_init. If a packet is too large to add to the current repacketizer state, no part of it is added, even if it contains multiple frames, some of which might fit. If you wish to be able to add parts of such packets, you should first use another repacketizer to split the packet into pieces and add them individually.

        Parameters:
        rp - the repacketizer state to which to add the packet
        Returns:
        OK on success, or INVALID_PACKET if the packet did not have a valid TOC sequence, the packet's TOC sequence was not compatible with previously submitted packets (because the coding mode, audio bandwidth, frame size, or channel count did not match), or adding this packet would increase the total amount of audio stored in the repacketizer state to more than 120 ms.
      • nopus_repacketizer_out_range

        public static int nopus_repacketizer_out_range​(long rp,
                                                       int begin,
                                                       int end,
                                                       long data,
                                                       int maxlen)
        Unsafe version of: repacketizer_out_range
        Parameters:
        maxlen - the maximum number of bytes to store in the output buffer. In order to guarantee success, this should be at least 1276 for a single frame, or for multiple frames, 1277*(end-begin). However, 1*(end-begin) plus the size of all packet data submitted to the repacketizer since the last call to repacketizer_init or repacketizer_create is also sufficient, and possibly much smaller.
      • opus_repacketizer_out_range

        public static int opus_repacketizer_out_range​(long rp,
                                                      int begin,
                                                      int end,
                                                      java.nio.ByteBuffer data)
        Constructs a new packet from data previously submitted to the repacketizer state via repacketizer_cat.
        Parameters:
        rp - the repacketizer state from which to construct the new packet
        begin - the index of the first frame in the current repacketizer state to include in the output
        end - one past the index of the last frame in the current repacketizer state to include in the output
        data - the buffer in which to store the output packet
        Returns:
        the total size of the output packet on success, BAD_ARG if [begin,end) was an invalid range of frames (begin < 0, begin >= end, or end > opus_repacketizer_get_nb_frames()), or BUFFER_TOO_SMALL if maxlen was insufficient to contain the complete output packet.
      • opus_repacketizer_get_nb_frames

        public static int opus_repacketizer_get_nb_frames​(long rp)
        Returns the total number of frames contained in packet data submitted to the repacketizer state so far via repacketizer_cat since the last call to repacketizer_init or repacketizer_create.

        This defines the valid range of packets that can be extracted with repacketizer_out_range or repacketizer_out.

        Parameters:
        rp - the repacketizer state containing the frames
        Returns:
        the total number of frames contained in the packet data submitted to the repacketizer state
      • nopus_repacketizer_out

        public static int nopus_repacketizer_out​(long rp,
                                                 long data,
                                                 int maxlen)
        Unsafe version of: repacketizer_out
        Parameters:
        maxlen - the maximum number of bytes to store in the output buffer. In order to guarantee success, this should be at least 1277*opus_repacketizer_get_nb_frames(rp). However, 1*opus_repacketizer_get_nb_frames(rp) plus the size of all packet data submitted to the repacketizer since the last call to repacketizer_init or repacketizer_create is also sufficient, and possibly much smaller.
      • opus_repacketizer_out

        public static int opus_repacketizer_out​(long rp,
                                                java.nio.ByteBuffer data)
        Constructs a new packet from data previously submitted to the repacketizer state via repacketizer_cat.

        This is a convenience routine that returns all the data submitted so far in a single packet. It is equivalent to calling opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_nb_frames(rp), data, maxlen).

        Parameters:
        rp - the repacketizer state from which to construct the new packet
        data - the buffer in which to store the output packet
        Returns:
        the total size of the output packet on success, or BUFFER_TOO_SMALL if maxlen was insufficient to contain the complete output packet
      • nopus_packet_pad

        public static int nopus_packet_pad​(long data,
                                           int len,
                                           int new_len)
        Unsafe version of: packet_pad
      • opus_packet_pad

        public static int opus_packet_pad​(java.nio.ByteBuffer data,
                                          int len,
                                          int new_len)
        Pads a given Opus packet to a larger size (possibly changing the TOC sequence).
        Parameters:
        data - the buffer containing the packet to pad
        len - the size of the packet. This must be at least 1.
        new_len - the desired size of the packet after padding. This must be at least as large as len.
        Returns:
        the new size of the output packet on success, BAD_ARG if len was less than 1 or new_len was less than len, or INVALID_PACKET if data did not contain a valid Opus packet
      • nopus_packet_unpad

        public static int nopus_packet_unpad​(long data,
                                             int len)
        Unsafe version of: packet_unpad
      • opus_packet_unpad

        public static int opus_packet_unpad​(java.nio.ByteBuffer data,
                                            int len)
        Removes all padding from a given Opus packet and rewrite the TOC sequence to minimize space usage.
        Parameters:
        data - the buffer containing the packet to strip
        len - the size of the packet. This must be at least 1.
        Returns:
        the new size of the output packet on success, BAD_ARG if len was less than 1, or INVALID_PACKET if data did not contain a valid Opus packet
      • nopus_multistream_packet_pad

        public static int nopus_multistream_packet_pad​(long data,
                                                       int len,
                                                       int new_len,
                                                       int nb_streams)
        Unsafe version of: multistream_packet_pad
      • opus_multistream_packet_pad

        public static int opus_multistream_packet_pad​(java.nio.ByteBuffer data,
                                                      int len,
                                                      int new_len,
                                                      int nb_streams)
        Pads a given Opus multi-stream packet to a larger size (possibly changing the TOC sequence).
        Parameters:
        data - the buffer containing the packet to pad
        len - the size of the packet. This must be at least 1.
        new_len - the desired size of the packet after padding. This must be at least 1.
        nb_streams - the number of streams (not channels) in the packet. This must be at least as large as len.
        Returns:
        the new size of the output packet on success, BAD_ARG if len was less than 1 or new_len was less than len, or INVALID_PACKET if data did not contain a valid Opus packet
      • nopus_multistream_packet_unpad

        public static int nopus_multistream_packet_unpad​(long data,
                                                         int len,
                                                         int nb_streams)
        Unsafe version of: multistream_packet_unpad
      • opus_multistream_packet_unpad

        public static int opus_multistream_packet_unpad​(java.nio.ByteBuffer data,
                                                        int len,
                                                        int nb_streams)
        Removes all padding from a given Opus multi-stream packet and rewrite the TOC sequence to minimize space usage.
        Parameters:
        data - the buffer containing the packet to strip
        len - the size of the packet. This must be at least 1.
        nb_streams - the number of streams (not channels) in the packet. This must be at least 1.
        Returns:
        the new size of the output packet on success, BAD_ARG if len was less than 1, or INVALID_PACKET if data did not contain a valid Opus packet
      • nopus_strerror

        public static long nopus_strerror​(int error)
        Unsafe version of: strerror
      • opus_strerror

        @Nullable
        public static java.lang.String opus_strerror​(int error)
        Converts an opus error code into a human readable string.
        Parameters:
        error - error number
        Returns:
        error string
      • nopus_get_version_string

        public static long nopus_get_version_string()
        Unsafe version of: get_version_string
      • opus_get_version_string

        @Nullable
        public static java.lang.String opus_get_version_string()
        Gets the libopus version string.

        Applications may look for the substring "-fixed" in the version string to determine whether they have a fixed-point or floating-point build at runtime.

      • opus_encoder_ctl

        public static int opus_encoder_ctl​(long st,
                                           int request)
        
        public static int opus_encoder_ctl​(long st,
                                           Opus.CTLRequest request)
        
        Performs a CTL function on an Opus encoder.
        Parameters:
        st - encoder state
        request - CTL request
      • opus_decoder_ctl

        public static int opus_decoder_ctl​(long st,
                                           int request)
        
        public static int opus_decoder_ctl​(long st,
                                           Opus.CTLRequest request)
        
        Performs a CTL function on an Opus decoder.
        Parameters:
        st - decoder state
        request - CTL request
      • OPUS_SET_COMPLEXITY

        public static Opus.CTLRequest OPUS_SET_COMPLEXITY​(int value)
        Configures the encoder's computational complexity.

        The supported range is 0-10 inclusive with 10 representing the highest complexity.

        Parameters:
        value - 0-10, inclusive
      • OPUS_GET_COMPLEXITY

        public static Opus.CTLRequest OPUS_GET_COMPLEXITY​(java.nio.IntBuffer value)
        Gets the encoder's complexity configuration.
        Returns:
        a value in the range 0-10, inclusive
      • OPUS_SET_BITRATE

        public static Opus.CTLRequest OPUS_SET_BITRATE​(int value)
        Configures the bitrate in the encoder.

        Rates from 500 to 512000 bits per second are meaningful, as well as the special values OPUS_AUTO and OPUS_BITRATE_MAX. The value OPUS_BITRATE_MAX can be used to cause the codec to use as much rate as it can, which is useful for controlling the rate by adjusting the output buffer size.

        Parameters:
        value - bitrate in bits per second. The default is determined based on the number of channels and the input sampling rate.
      • OPUS_GET_BITRATE

        public static Opus.CTLRequest OPUS_GET_BITRATE​(java.nio.IntBuffer value)
        Gets the encoder's bitrate configuration.
        Returns:
        the bitrate in bits per second. The default is determined based on the number of channels and the input sampling rate.
      • OPUS_SET_VBR

        public static Opus.CTLRequest OPUS_SET_VBR​(int value)
        Enables or disables variable bitrate (VBR) in the encoder.

        The configured bitrate may not be met exactly because frames must be an integer number of bytes in length.

        Parameters:
        value - allowed values:
        0
        Hard CBR. For LPC/hybrid modes at very low bit-rate, this can cause noticeable quality degradation.
        1
        VBR (default). The exact type of VBR is controlled by #OPUS_SET_VBR_CONSTRAINT.
      • OPUS_GET_VBR

        public static Opus.CTLRequest OPUS_GET_VBR​(java.nio.IntBuffer value)
        Determines if variable bitrate (VBR) is enabled in the encoder.
        Returns:
        one of the following values:
        0
        Hard CBR.
        1
        VBR (default). The exact type of VBR may be retrieved via OPUS_GET_VBR_CONSTRAINT(java.nio.IntBuffer).
      • OPUS_SET_VBR_CONSTRAINT

        public static Opus.CTLRequest OPUS_SET_VBR_CONSTRAINT​(int value)
        Enables or disables constrained VBR in the encoder.

        This setting is ignored when the encoder is in CBR mode. Warning: Only the MDCT mode of Opus currently heeds the constraint. Speech mode ignores it completely, hybrid mode may fail to obey it if the LPC layer uses more bitrate than the constraint would have permitted.

        Parameters:
        value - allowed values:
        0
        Unconstrained VBR.
        1
        Constrained VBR (default). This creates a maximum of one frame of buffering delay assuming a transport with a serialization speed of the nominal bitrate.
      • OPUS_GET_VBR_CONSTRAINT

        public static Opus.CTLRequest OPUS_GET_VBR_CONSTRAINT​(java.nio.IntBuffer value)
        Determines if constrained VBR is enabled in the encoder.
        Returns:
        one of the following values:
        0
        Unconstrained VBR.
        1
        Constrained VBR (default).
      • OPUS_SET_FORCE_CHANNELS

        public static Opus.CTLRequest OPUS_SET_FORCE_CHANNELS​(int value)
        Configures mono/stereo forcing in the encoder.

        This can force the encoder to produce packets encoded as either mono or stereo, regardless of the format of the input audio. This is useful when the caller knows that the input signal is currently a mono source embedded in a stereo stream.

        Parameters:
        value - allowed values:
        OPUS_AUTO
        Not forced (default)
        1
        Forced mono
        2
        Forced stereo
      • OPUS_GET_FORCE_CHANNELS

        public static Opus.CTLRequest OPUS_GET_FORCE_CHANNELS​(java.nio.IntBuffer value)
        Gets the encoder's forced channel configuration.
        Returns:
        one of the following values:
        OPUS_AUTO
        Not forced (default)
        1
        Forced mono
        2
        Forced stereo
      • OPUS_SET_SIGNAL

        public static Opus.CTLRequest OPUS_SET_SIGNAL​(int value)
        Configures the type of signal being encoded.

        This is a hint which helps the encoder's mode selection.

        Parameters:
        value - allowed values:
        OPUS_AUTO
        (default)
        OPUS_SIGNAL_VOICE
        Bias thresholds towards choosing LPC or Hybrid modes.
        OPUS_SIGNAL_MUSIC
        Bias thresholds towards choosing MDCT modes.
      • OPUS_GET_SIGNAL

        public static Opus.CTLRequest OPUS_GET_SIGNAL​(java.nio.IntBuffer value)
        Gets the encoder's configured signal type.
        Returns:
        one of the following values:
        OPUS_AUTO
        (default)
        OPUS_SIGNAL_VOICE
        Bias thresholds towards choosing LPC or Hybrid modes.
        OPUS_SIGNAL_MUSIC
        Bias thresholds towards choosing MDCT modes.
      • OPUS_SET_APPLICATION

        public static Opus.CTLRequest OPUS_SET_APPLICATION​(int value)
        Configures the encoder's intended application.

        The initial value is a mandatory argument to the encoder_create function.

        Parameters:
        value - allowed values:
        OPUS_APPLICATION_VOIP
        Process signal for improved speech intelligibility.
        OPUS_APPLICATION_AUDIO
        Favor faithfulness to the original input.
        OPUS_APPLICATION_RESTRICTED_LOWDELAY
        Configure the minimum possible coding delay by disabling certain modes of operation.
      • OPUS_GET_LOOKAHEAD

        public static Opus.CTLRequest OPUS_GET_LOOKAHEAD​(java.nio.IntBuffer value)
        Gets the total samples of delay added by the entire codec.

        This can be queried by the encoder and then the provided number of samples can be skipped on from the start of the decoder's output to provide time aligned input and output. From the perspective of a decoding application the real data begins this many samples late.

        The decoder contribution to this delay is identical for all decoders, but the encoder portion of the delay may vary from implementation to implementation, version to version, or even depend on the encoder's initial configuration. Applications needing delay compensation should call this CTL rather than hard-coding a value.

        Returns:
        number of lookahead samples
      • OPUS_SET_INBAND_FEC

        public static Opus.CTLRequest OPUS_SET_INBAND_FEC​(int value)
        Configures the encoder's use of inband forward error correction (FEC).

        Note: This is only applicable to the LPC layer

        Parameters:
        value - allowed values:
        0
        Disable inband FEC (default).
        1
        Enable inband FEC.
      • OPUS_GET_INBAND_FEC

        public static Opus.CTLRequest OPUS_GET_INBAND_FEC​(java.nio.IntBuffer value)
        Gets encoder's configured use of inband forward error correction.
        Returns:
        one of the following values:
        0
        Inband FEC disabled (default).
        1
        Inband FEC enabled.
      • OPUS_SET_PACKET_LOSS_PERC

        public static Opus.CTLRequest OPUS_SET_PACKET_LOSS_PERC​(int value)
        Configures the encoder's expected packet loss percentage.

        Higher values trigger progressively more loss resistant behavior in the encoder at the expense of quality at a given bitrate in the absence of packet loss, but greater quality under loss.

        Parameters:
        value - loss percentage in the range 0-100, inclusive (default: 0)
      • OPUS_GET_PACKET_LOSS_PERC

        public static Opus.CTLRequest OPUS_GET_PACKET_LOSS_PERC​(java.nio.IntBuffer value)
        Gets the encoder's configured packet loss percentage.
        Returns:
        the configured loss percentage in the range 0-100, inclusive (default: 0)
      • OPUS_SET_DTX

        public static Opus.CTLRequest OPUS_SET_DTX​(int value)
        Configures the encoder's use of discontinuous transmission (DTX).

        Note: This is only applicable to the LPC layer

        Parameters:
        value - allowed valued:
        0
        Disable DTX (default).
        1
        Enabled DTX.
      • OPUS_GET_DTX

        public static Opus.CTLRequest OPUS_GET_DTX​(java.nio.IntBuffer value)
        Gets encoder's configured use of discontinuous transmission.
        Returns:
        one of the following values:
        0
        DTX disabled (default).
        1
        DTX enabled.
      • OPUS_SET_LSB_DEPTH

        public static Opus.CTLRequest OPUS_SET_LSB_DEPTH​(int value)
        Configures the depth of signal being encoded.

        This is a hint which helps the encoder identify silence and near-silence. It represents the number of significant bits of linear intensity below which the signal contains ignorable quantization or other noise.

        For example, OPUS_SET_LSB_DEPTH(14) would be an appropriate setting for G.711 u-law input. OPUS_SET_LSB_DEPTH(16) would be appropriate for 16-bit linear pcm input with opus_encode_float().

        When using opus_encode(long, java.nio.ShortBuffer, int, java.nio.ByteBuffer) instead of opus_encode_float(long, java.nio.FloatBuffer, int, java.nio.ByteBuffer), or when libopus is compiled for fixed-point, the encoder uses the minimum of the value set here and the value 16.

        Parameters:
        value - input precision in bits, between 8 and 24 (default: 24).
      • OPUS_GET_LSB_DEPTH

        public static Opus.CTLRequest OPUS_GET_LSB_DEPTH​(java.nio.IntBuffer value)
        Gets the encoder's configured signal depth.
        Returns:
        input precision in bits, between 8 and 24 (default: 24).
      • OPUS_SET_PREDICTION_DISABLED

        public static Opus.CTLRequest OPUS_SET_PREDICTION_DISABLED​(int value)
        If set to 1, disables almost all use of prediction, making frames almost completely independent. This reduces quality.
        Parameters:
        value - allowed valued:
        0
        Enable prediction (default).
        1
        Disable prediction.
      • OPUS_GET_PREDICTION_DISABLED

        public static Opus.CTLRequest OPUS_GET_PREDICTION_DISABLED​(java.nio.IntBuffer value)
        Gets the encoder's configured prediction status.
        Returns:
        one of the following values:
        0
        Prediction enabled (default).
        1
        Prediction disabled.
      • OPUS_GET_FINAL_RANGE

        public static Opus.CTLRequest OPUS_GET_FINAL_RANGE​(java.nio.IntBuffer value)
        Gets the final state of the codec's entropy coder.

        This is used for testing purposes. The encoder and decoder state should be identical after coding a payload (assuming no data corruption or software bugs).

        Returns:
        entropy coder state
      • OPUS_SET_PHASE_INVERSION_DISABLED

        public static Opus.CTLRequest OPUS_SET_PHASE_INVERSION_DISABLED​(int value)
        If set to 1, disables the use of phase inversion for intensity stereo, improving the quality of mono downmixes, but slightly reducing normal stereo quality.

        Disabling phase inversion in the decoder does not comply with RFC 6716, although it does not cause any interoperability issue and is expected to become part of the Opus standard once RFC 6716 is updated by draft-ietf-codec-opus-update.

        Parameters:
        value - allowed valued:
        0
        Enable phase inversion (default).
        1
        Disable phase inversion.
      • OPUS_GET_PHASE_INVERSION_DISABLED

        public static Opus.CTLRequest OPUS_GET_PHASE_INVERSION_DISABLED​(java.nio.IntBuffer value)
        Gets the encoder's configured phase inversion status.
        Returns:
        one of the following values:
        0
        Stereo phase inversion enabled (default).
        1
        Stereo phase inversion disabled.
      • OPUS_GET_IN_DTX

        public static Opus.CTLRequest OPUS_GET_IN_DTX​(java.nio.IntBuffer value)
        Gets the DTX state of the encoder.

        Returns whether the last encoded frame was either a comfort noise update during DTX or not encoded because of DTX.

        Returns:
        one of the following values:
        0
        The encoder is not in DTX.
        1
        The encoder is in DTX.
      • OPUS_SET_GAIN

        public static Opus.CTLRequest OPUS_SET_GAIN​(int value)
        Configures decoder gain adjustment.

        Scales the decoded output by a factor specified in Q8 dB units. This has a maximum range of -32768 to 32767 inclusive, and returns OPUS_BAD_ARG otherwise. The default is zero indicating no adjustment. This setting survives decoder reset.

        gain = pow(10, x/(20.0*256))

        Parameters:
        value - amount to scale PCM signal by in Q8 dB units.
      • OPUS_GET_GAIN

        public static Opus.CTLRequest OPUS_GET_GAIN​(java.nio.IntBuffer value)
        Gets the decoder's configured gain adjustment.
        Returns:
        amount to scale PCM signal by in Q8 dB units.
      • OPUS_GET_LAST_PACKET_DURATION

        public static Opus.CTLRequest OPUS_GET_LAST_PACKET_DURATION​(java.nio.IntBuffer value)
        Gets the duration (in samples) of the last packet successfully decoded or concealed.
        Returns:
        number of samples (at current sampling rate).
      • OPUS_GET_PITCH

        public static Opus.CTLRequest OPUS_GET_PITCH​(java.nio.IntBuffer value)
        Gets the pitch of the last decoded frame, if available.

        This can be used for any post-processing algorithm requiring the use of pitch, e.g. time stretching/shortening. If the last frame was not voiced, or if the pitch was not coded in the frame, then zero is returned.

        This CTL is only implemented for decoder instances.

        Returns:
        pitch period at 48 kHz (or 0 if not available)