Opus from Beginner to Master (II): Codec usage

Opus official encoder implementation, including:

• Opus Encoder
• Opus Decoder
• Repacketizer
• Opus Multistream API
• Opus library information functions
• Opus Custom codec example file :github.com/xiph/opus/b… Document address :www.opus-codec.org/docs/opus_a…

The encoder

The type definition

Typedef struct OpusEncoder OpusEncoder //Opus encoder state.

function

Function	instructions
int opus_encoder_get_size (int channels)	Get the size of OpusEncoder structure –
OpusEncoder * opus_encoder_create (opus_int32 Fs, int channels, int application, int *error)	Allocates and initializes encoder state.
int opus_encoder_init (OpusEncoder *st, opus_int32 Fs, int channels, int application)	Initialize a previously allocated encoder state. The memory saint referred to must be at least the size returned by opus_encoder_get_size().
opus_int32 opus_encode (OpusEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)	Encode an Opus frame
opus_int32 opus_encode_float (OpusEncoder *st, const float *pcm, int frame_size, unsigned char *data, opus_int32 max_data_bytes)	Encodes an Opus frame based on floating point input
void opus_encoder_destroy (OpusEncoder *st)	Releases an OpusEncoder object allocated according to opus_encoder_create()
int opus_encoder_ctl (OpusEncoder *st, int request,...)	Execute a CTL function to an Opus encoder.

A detailed description

This section describes the procedures and functions used to encode Opus. Since Opus is a stateful codec, the encoding process begins by creating an encoder state, which is done as follows:

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

From this point, ENC can be used to encode audio streams. One encoder state may not be used for more than one audio stream at a time. Similarly, the encoder state cannot be reinitialized for each frame. When opus_encoder_create() allocates memory for state, it can also initialize preallocated memory:

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

Opus_encoder_get_size () returns the size required by the encoder state. Note that future versions of this code may change size, so no Assuptions should be made to it. Encoder state is always continuous in memory and a shallow copy of it is sufficient. Some encoder parameter Settings can be changed using the opus_encoder_ctl() interface. All of these parameters have default values, so change them only if necessary. The most common parameter setting changes 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));
Copy the code

Here:

• The unit is bits per second (b/s).
• The complexity is a scale of 1 to 10 with 1 being the lowest and 10 the highest, with the higher the complexity
• Signal_type (signal type) includes OPUS_AUTO (default), OPUS_SIGNAL_VOICE, or OPUS_SIGNAL_MUSIC.

See Encoder Related CTLs and Generic CTLs for a detailed list of parameters that can be set and queried. Most parameters can be set or modified during the processing of an audio stream. To encode a frame, the opus_encode() or opus_encode_float() functions must be called correctly with frames of audio data (2.5, 5, 10, 20, 40, or 60 milliseconds).

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

Here:

• Audio_frame (audio frame) is audio data in opus_INT16 (or floating point for opus_encode_float()) format
• Frame_size is the maximum number of frames in the sample (per channel)
• A packet is an array of bytes written as compressed data,
• Max_packet is the recommended maximum number of bytes that can be written to a packet (4000 bytes). Do not use max_packet to control the target bit rate of the VBR. Instead, use OPUS_SET_BITRATE CTL. Opus_encode () and opus_encode_float() return the number of bytes actually written to the package. The return value can be negative, indicating that an error has occurred. If the return value is 1 byte, the packet does not need to be propagated (DTX). Once an encoder state is no longer needed, it can be deconstructed as follows:

opus_encoder_destroy(enc);
Copy the code

If the encoder is created with opus_encoder_init() instead of using the opus_encoder_create() function, no action is required to detach from the potential release of the memory that was manually allocated for it(the above example is a call to free(enc)).

Type definition document

Typedef struct OpusEncoder OpusEncoder //Opus encoder status.Copy the code

This contains the complete state of an Opus encoder. It is position-independent and can be copied freely.

Function of the document

opus_int32 opus_encode (OpusEncoder *       st,
        const opus_int16 *  pcm,
        int                 frame_size,
        unsigned char *     data,
        opus_int32          max_data_bytes 
)   
Copy the code

Encode an Opus frame.

parameter
[in]	st	OpusEncoder*: Encoder status
[in]	pcm	Opus_int16 *: Input signal (if 2 channels are crossed). Length frame_size* Channels *sizeof(opus_int16)
[in]	frame_size	Int: number of input signal samples per channel.
[out]	data	Unsigned char*: output load. Must contain at least max_datA_bytes of capacity.
[in]	max_data_bytes	opus_int32: The amount of memory allocated for the output load. Can be used to limit the maximum fixed bit rate limit, but not as a unique bit rate limit. You can use OPUS_SET_BITRATE to control the bit rate.

Return value: success, is the length of the encoded packet (in bytes); Failure, a negative error code.

opus_int32 opus_encode_float (  OpusEncoder *   st,
        const float *   pcm,
        int             frame_size,
        unsigned char * data,
        opus_int32      max_data_bytes
) 
Copy the code

Encodes an Opus frame based on floating point input.

parameter
[in]	st	OpusEncoder*: Encoder status
[in]	pcm	float*: Input in floating-point format (if 2 channels are crossed) in the normal range of +/-1.0. Sampling beyond this range is also supported, but it will be intercepted by the decoder using an integer API and can only be used if the remote side is known to support extended dynamic range. Length isframe_size* channels*sizeof(float)
[in]	frame_size	Int: number of input signal samples per channel. This must be the Opus frame size of the encoder sampling rate. For example, the allowable values at 48 kHz are 120, 240, 480, 960, 1920, and 2880. Samples of less than 10 ms (480 samples at 48 kHz) will prevent the encoder from using LPC or mixed mode.
[out]	data	unsigned char*: Output load. Must contain at least max_datA_bytes of capacity.
[in]	max_data_bytes	Opus_int32: Size of memory allocated for output load. Can be used to limit the maximum fixed bit rate limit, but not as a unique bit rate limit. You can use OPUS_SET_BITRATE to control the bit rate.

Return values: success, which is the length of the encoded package (in bytes), failure, a negative error code.

OpusEncoder* opus_encoder_create ( opus_int32   Fs,
        int     channels,
        int     application,
        int *   error 
    ) 
Copy the code

Allocates and initializes an encoder state. Including three coding modes:

• OPUS_APPLICATION_VOIP: Provides the highest quality for sound signals at a given bit rate. It enhances the input signal by high-pass filtering and emphasizing formants and harmonics. It includes in-band forward error checking to prevent packet loss. Typical VOIP applications use this pattern. Because of the enhancements, the output may sound different from the input, even at high bit rates.
• OPUS_APPLICATION_AUDIO: Provides the highest quality for most non-speech signals, such as music, at a given bit rate. Applications for this mode include music, mixing (music/sound), broadcasting, and other applications that require signal delays of less than 15 milliseconds.
• OPUS_APPLICATION_RESTRICTED_LOWDELAY: Configuring low-latency mode disables voice optimization mode to reduce latency. This mode can only be used when the encoder is just initialized or reset, because the codec delay is modified in these cases.

(Look out!) It is useful to configure low latency mode when the caller knows that voice optimization mode is no longer needed.

parameter
[in]	Fs	Opus_int32: Indicates the sampling rate (Hz) of the input signal. The value must be 8000, 12000, 16000, 24000, or 48000.
[in]	channels	Int: number of channels for input signals (1 or 2).
[in]	application	Int: encoding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)
[out]	error	int*: Error code

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

int opus_encoder_ctl ( OpusEncoder *    st,
        int     request,
        ... 
    )
Copy the code

Execute a CTL function to an Opus encoder. Typically its request and subsequent parameters are generated by a convenience macro.

parameter
[in]	st	OpusEncoder*: Encoder status
[in]	request	Int: This and all other parameters should be replaced by a macro that is convenient in Generic CTLs or Encoder Related CTLs

See also: – Generic CTLs – Encoder related CTLs

void opus_encoder_destroy ( OpusEncoder *   st  )   
Copy the code

Frees an OpusEncoder allocated by opus_encoder_create(). Releases an OpusEncoder object allocated according to opus_encoder_create().

parameter
[in]	st	OpusEncoder*: The encoder state used to release.

int opus_encoder_get_size ( int     channels    )   
Copy the code

Gets the size of the OpusEncoder structure.

parameter
[in]	channels	Int: number of channels. The value must be 1 or 2.

Returns: the size of the number of bytes.

int opus_encoder_init   (   OpusEncoder *   st,
        opus_int32      Fs,
        int     channels,
        int     application 
    )   
Copy the code

Initialize a previously allocated encoder state. The memory that the state points to must be at least the size returned by opus_encoder_get_size(). Instead of using the system to automatically allocate memory, the application is prepared to use its own allocator. See also: opus_encoder_create(),opus_encoder_get_size(). To reset a previously initialized state, use OPUS_RESET_STATE CTL.

parameter
[in]	st	OpusEncoder*: Encoder status
[in]	Fs	Opus_int32: Indicates the sampling rate (Hz) of the input signal. The value must be 8000, 12000, 16000, 24000, or 48000.
[in]	channels	Int: number of channels for input signal (1 or 2)
[in]	application	Int: encoding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO/OPUS_APPLICATION_RESTRICTED_LOWDELAY)

Return values: success, OPUS_OK, failure, error code.

Opus Decoder

The type definition

Typedef struct OpusDecoder OpusDecoder //Opus decoder state.Copy the code

function

functon
int opus_decoder_get_size (int channels)	Gets the size of the OpusDecoder structure.
|OpusDecoder * opus_decoder_create (opus_int32 Fs, int channels, int *error)

To allocate and initialize the decoder state. | int opus_decoder_init (OpusDecoder * st, opus_int32 Fs, Int channel) | initialization before the distribution state of decoder. | | int opus_decode (OpusDecoder * st, const unsigned char * data, opus_int32 len, Opus_int16 * PCM, int frame_size, int decode_fec) | decoding a Opus bag. | | int opus_decode_float (OpusDecoder * st, Const unsigned char * data, opus_int32 len, float * PCM, int frame_size, int decode_fec) | decoding output a floating-point Opus package, .| |int opus_decoder_ctl (OpusDecoder *st, int request,…) | to a Opus decoder implementation CTL function. | | | void opus_decoder_destroy (OpusDecoder * st) released by opus_decoder_create (). OpusDecoder assigned. | |int opus_packet_parse (const unsigned char *data, opus_int32 len, unsigned char *out_toc, const unsigned char *frames[48], short size[48], Int * payload_offset) | an opus packet parsing into one or more frames. | | int opus_packet_get_bandwidth (const unsigned char * data) | get an opus packet bandwidth. | | int opus_packet_get_samples_per_frame (const unsigned char * data, opus_int32 Fs) | get Opus bag sample of each frame. | | int opus_packet_get_nb_channels (const unsigned char * data) | Opus package on the number of channels. | |int opus_packet_get_nb_frames (const unsigned char packet[], Opus_int32 len) | Opus package all the number of frames. | | int opus_packet_get_nb_samples (const unsigned char packet [], opus_int32 len, Opus_int32 Fs) | Opus package sample. | | int opus_decoder_get_nb_samples (const OpusDecoder * dec, const unsigned char packet [], opus_int32 len) | Opus package sample. |

A detailed description

Like encoding, the decoding process starts by creating a decoder state. Do this in the following ways:

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

Here: -fs is the sampling rate, It has to be 8000, 12000, 16000, 24000, Or 48000 -channels is the number of channels (1 or 2) – error will save the error code in the case of an error (or OPUS_OK in the success state) – the return value is a newly created decoder state for decoding

When opus_decoder_create() allocates memory for state, it can also initialize preallocated memory:

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

Opus_decoder_get_size () returns the size required by the decoder state. Note that future versions of this code may change size, so no Assuptions should be made to it. The decoder state is always continuous in memory, and a shallow copy of it is sufficient.

To decode a frame, opus_decode() or opus_decode_float() must be called with a package that compresses the audio data: frame_size = opus_decode(dec, packet, len, decoded, max_size, 0); Here – packet is the byte array containing compressed data – len is the exact number of bytes in the packet – decoded is decoded audio data in opus_INT16 (or floating point as defined by opus_decode_float()) format. Opus_decode () and opus_decode_float() return the number of samples per channel decoded from the packet. If this value is negative, an error has occurred. Errors can occur if the packet is corrupted or the audio buffer is too small to hold the decoded audio.

Opus is a stateful codec that contains overlapping blocks, with the result that Opus packages are not encoded independently of each other. Packets must be consecutively entered into the decoder for proper decoding in the correct order. Missing packets can be replaced with loss-hiding, which calls the decoder with an empty pointer and a packet of 0 length. A separate codec state can only be accessed by a separate thread at a time, with the caller performing any required locking. Separate audio streams can be decoded in parallel with separate decoder states, unless the API library uses the NONTHREADSAFE_PSEUDOSTACK definition at compile time.

Type definition document

Typedef struct OpusDecoder OpusDecoder //Opus decoder state.Copy the code

This contains the complete state of an Opus decoder. It is position-independent and can be copied freely. See also: opus_decoder_create opus_decoder_init

Function of the document

int opus_decode     (   OpusDecoder *   st,
        const unsigned char *   data,
        opus_int32      len,
        opus_int16 *    pcm,
        int     frame_size,
        int     decode_fec 
    )   
Copy the code

Decodes an Opus package.

parameter
[in]	st	OpusDecoder*: Decoder status
[in]	data	char*:Input load. packet loss is represented by a null pointer.
[in]	len	Opus_int32: number of bytes in the input load
[out]	pcm	opus_int16*: Output signal (if 2 channels are crossed). Length equal to frame_size* Channels *sizeof(opus_int16)
[in]	frame_size	Int: number of samples per channel in available PCM space. If less than the maximum packet length (120 ms, 4848kHz5760), this function will not decode some packets. In the case of PLC (data==NULL) or FEC (decoDE_FEC =1), frame_size must be exactly the length of time the audio was lost, otherwise the decoder cannot be optimized for decoding the next packet. For PLC and FEC cases, frame_size must be a multiple of 2.5 milliseconds.
[in]	decode_fec	Int: Status flag (0 or 1) that requests decoding of any in-band forward error correction data. If no such data is available, the frame is considered lost when decoded.

Return: Number of decoded samples, or error code.

int opus_decode_float   (   OpusDecoder *   st,
        const unsigned char *   data,
        opus_int32      len,
        float *     pcm,
        int     frame_size,
        int     decode_fec 
    )   
Copy the code

Decodes an Opus package in floating-point output format.

parameter
[in]	st	OpusDecoder*:Decoder state
[in]	data	char*:Input load. packet loss is represented by a null pointer.
[in]	len	Opus_int32: number of bytes in the input load
[out]	pcm	float*: Output signal (if 2 channels are crossed). Length equal to frame_size* Channels *sizeof(float)
[in]	frame_size	Int: number of samples per channel in available PCM space. If less than the maximum packet length (120 ms, 4848kHz5760), this function will not decode some packets. In the case of PLC (data==NULL) or FEC (decoDE_FEC =1), frame_size must be exactly the length of time the audio was lost, otherwise the decoder cannot be optimized for decoding the next packet. For PLC and FEC cases, frame_size must be a multiple of 2.5 milliseconds.
[in]	decode_fec	Int: Status flag (0 or 1) that requests decoding of any in-band forward error correction data. If no such data is available, the frame is considered lost when decoded.

Return: Number of decoded samples, or error code.

OpusDecoder* opus_decoder_create ( opus_int32   Fs,
        int     channels,
        int *   error 
    ) 
Copy the code

Allocates and initializes decoder state.

parameter
[in]	Fs	Opus_int32: Decode sampling rate (Hz). Must be 8000, 12000, 16000, 24000, or 48000.
[in]	channels	Int: Number of channels used to decode (1 or 2)
[out]	error	int*: OPUS_OK Success or error code on Success

int opus_decoder_ctl    (   OpusDecoder *   st,
        int     request,
            ... 
    ) 
Copy the code

Executes a CTL function to an Opus decoder. Typically its request and subsequent parameters are generated by a convenience macro.

parameter
st	OpusDecoder*: decoder status.
request	Int: This and all other remaining parameters should be replaced by a macro that is convenient in Generic CTLs or Encoder Related CTLs!

See: Generic CTLs Decoder Related CTLs

void opus_decoder_destroy   (   OpusDecoder *   st  )   
Copy the code

Releases an OpusDecoder object allocated according to opus_decoder_create().

parameter
[in]	st	OpusDecoder*: Decoder state used for release.

int opus_decoder_get_nb_samples     (   const OpusDecoder *     dec,
        const unsigned char     packet[],
        opus_int32      len 
    ) 
Copy the code

Get the number of samples of an Opus package

parameter
[in]	dec	OpusDecoder*: Decoder status
[in]	packet	char*: Opus
[in]	len	Opus_int32: indicates the packet length

Returned: Number of samples Returned value: OPUS_INVALID_PACKET: The passed compressed data is corrupted or its format is not supported.

int opus_decoder_get_size ( int     channels    )   
Copy the code

Gets the size of the OpusDecoder structure.

parameter
[in]	channels	Int: number of channels. The value must be 1 or 2.

Returns: the size of the number of bytes.

int opus_decoder_init   (   OpusDecoder *   st,
        opus_int32      Fs,
        int     channels 
    ) 
Copy the code

Initialize a previously allocated decoder state. – The state must be at least the size returned by opus_decoder_get_size(). – Here, the application does not automatically allocate memory with the system, but prepares to use its own allocator. See also: opus_decoder_create,opus_decoder_get_size, reset a previously initialized state using OPUS_RESET_STATE CTL

parameter
[in]	st	OpusDecoder*: Decoder status.
[in]	Fs	Opus_int32: Sampling rate to be decoded (Hz). The value must be 8000, 12000, 16000, 24000, or 48000.
[in]	channels	Int: number of channels decoded (1 or 2)

Return values: success, OPUS_OK, failure, error code.

int opus_packet_get_bandwidth   (   const unsigned char *   data    )
Copy the code

Get the bandwidth of an Opus packet.

parameter
[in]	data	char*: Opus

The return value:

• OPUS_BANDWIDTH_NARROWBAND (4kHz bandpass)
• OPUS_BANDWIDTH_MEDIUMBAND Medium bandwidth (6kHz bandpass)
• OPUS_BANDWIDTH_WIDEBAND (8kHz Bandpass)
• OPUS_BANDWIDTH_SUPERWIDEBAND (12kHz Bandpass)
• OPUS_BANDWIDTH_FULLBAND full bandwidth (20kHz bandpass)
• The compressed data passed by OPUS_INVALID_PACKET is corrupted or its format is not supported

int opus_packet_get_nb_channels ( const unsigned char *     data )  
Copy the code

Get the number of channels for the Opus package.

parameter
[int]	data	char*: Opus

Returned: Number of channels Returned value: OPUS_INVALID_PACKET The compressed data through the packet is damaged or its format is not supported

int opus_packet_get_nb_frames   (   const unsigned char     packet[],
        opus_int32      len 
    )       
Copy the code

Gets the number of all frames in the Opus package.

parameter
[in]	packet	char*: Opus
[in]	len	Opus_int32: indicates the packet length

Returned: Number of frames Returned value: OPUS_INVALID_PACKET The compressed data through the packet is corrupted or its format is not supported

int opus_packet_get_nb_samples  (   const unsigned char     packet[],
        opus_int32      len,
        opus_int32      Fs 
    )   
Copy the code

Get the number of Opus package samples.

parameter
[in]		packet
[in]	len	Opus_int32: indicates the packet length
[in]		Fs

Returned: Number of samples Returned value: OPUS_INVALID_PACKET The compressed data passed through is corrupted or in an unsupported format

int opus_packet_get_samples_per_frame   (   const unsigned char *   data,
        opus_int32      Fs 
    )   
Copy the code

Get the number of samples per frame of the Opus package.

parameter
[in]	data	char*: Opus. Must contain at least one byte of data.
[in]	Fs	Opus_int32: sampling rate (Hz). The value must be a multiple of 400; otherwise, the result is inaccurate.

Returns: Number of samples per frame.

int opus_packet_parse   (   const unsigned char *   data,
        opus_int32      len,
        unsigned char *     out_toc,
        const unsigned char *   frames[48],
        short   size[48],
        int *   payload_offset 
    )   
Copy the code

Parse an OPUS package into one or more frames. Opus_decode does this internally, so most applications don’t need this function. This function does not copy each frame and returns a pointer inside the input package.

parameter
[in]	data	char*: Opus package to parse
[in]	len	Opus_int32: indicates the data size
[out]	out_toc	char*: the TOC pointer
[out]	frames	char*[48] Encapsulated frames
[out]	size	Short [48] The size of the encapsulated frame
[out]	payload_offset	int*: returns the position of the load in the packet (in bytes)

Returns: Number of frames

Repacketizer

Repacketizer combines multiple packages Opus into a single package or separates previously combined packages into multiple Opus packages.

The type definition

typedef struct OpusRepacketizer OpusRepacketizer
Copy the code

function

Int opus_repacketizer_get_size (void) // Get the size of OpusRepacketizer* opus_repacketizer_init (OpusRepacketizer * RP) //(re) initializes the previously allocated Repacketizer state. OpusRepacketizer* opus_repacketizer_Create (void) // Allocates memory and initializes the new Repacketizer generated with opus_repacketizer_init(). Void opus_repacketizer_Destroy (OpusRepacketizer * RP) // Frees the OpusRepacketizer Int allocated by opus_repacketizer_Create () Opus_repacketizer_cat (OpusRepacketizer * RP, const unsigned char *data, opus_int32 len) // Adds a packet to the current Repacketizer state. opus_int32 opus_repacketizer_out_range ( OpusRepacketizer *rp, int begin, int end, unsigned char *data, Opus_int32 maxlen) // Build a new package from the data previously given to the Repacketizer state by opus_repacketizer_cat(). Int opus_repacketizer_get_nb_frames (OpusRepacketizer * RP) // Returns the last call to opus_repacketizer_init() or Opus_repacketizer_create () The total number of frames contained in the package data submitted so far via opus_repacketizer_cat(). opus_int32 opus_repacketizer_out ( OpusRepacketizer *rp, unsigned char *data, Opus_int32 maxlen) // Build a new package from the data previously given to the Repacketizer state by opus_repacketizer_cat().Copy the code

A detailed description

Repacketizer combines multiple packages Opus into a single package or separates previously combined packages into multiple Opus packages. Separating valid packets is guaranteed to succeed, however, merging valid packets will only succeed if all frames have the same encoding pattern, bandwidth, frame size, and the combined packet length does not exceed 120 milliseconds. Operations on multiple stream packets will not succeed, except in degraded cases where the packets consist of data from the same audio stream. The process of refactoring a package begins by creating a Repacketizer state, which can be done either by calling the opus_repacketizer_create() function or by allocating its own memory, for example

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

The application should then submit the package via opus_repacketizer_cat(), extract the new package with opus_repacketizer_out() or opus_repacketizer_out_range(), It then resets the state for the next set of input packets with opus_repacketizer_init(). In the following example, a series of packets is separated into separate 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);
}
Copy the code

Optionally, a series of frames can be merged into packages, each containing 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); }Copy the code

An alternative to merging packages is to simply call opus_repacketizer_cat() unconditionally until it fails. Thus, the combined packages can be obtained with opus_repacketizer_out(), and the packages entered by opus_repacketizer_cat() need to be re-added to a new reinitialized Repacketizer state.

Type definition document

typedef struct OpusRepacketizer OpusRepacketizer
Copy the code

Function of the document

int opus_repacketizer_cat ( OpusRepacketizer * rp,
        const unsigned char *   data,
        opus_int32      len 
    ) 
Copy the code

Adds a package to the current Repacketizer state. This package must match the configuration of any packages that have been submitted to the Repacketizer state since the last call to opus_repacketizer_init(). This means that it must have the same encoding mode, bandwidth, frame size, and number of channels. You can check ahead of time by monitoring the first six bits of the first byte of the package to see if they match the first six bits of the first byte of any other package that has been committed. After adding this package, the total duration of the individual packages and the total duration of the audio at the Repacketizer state cannot exceed 120 milliseconds. This packet must match the configuration of any packets already submitted for repacketization since the last call to opus_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. With opus_repacketizer_out() or opus_repacketizer_out_range(), the contents of the current Repacketizer state can be extracted into a new packet. The contents of The current repacketizer state can be extracted into new packets using opus_repacketizer_out() or Opus_repacketizer_out_range (). If you want to add packets with different configurations, or more audio data that exceeds 120 milliseconds, you must call opus_Repacketizer_init () to clear the Repacketizer state. If a package is too large to be added in its entirety to the current Repacketizer state, no part of it can be added, even if the package contains multiple frames, some of which may be suitable for addition. If you want to add portions of such a packet, you should first use another Repacketizer to separate the packets into suitable pieces, and then add the pieces one by one to the target Repacketizer state. 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 opus_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.

See also: opus_repacketizer_out_range Opus_repacketizer_Out Opus_repacketizer_init Parameter: [in] RP OpusRepacketizer*: Repacketizer state for packets to be added. The repacketizer state to which to add The packet. [in] data const unsigned char* The application must ensure that this pointer is valid until the next call to opus_repacketizer_init() or opus_repacketizer_destroy(). The packet data. The application must ensure this pointer remains valid until the next call to opus_repacketizer_init() Or opus_repacketizer_destroy(). [in] len opus_int32: indicates the number of bytes in the packet data. The number of bytes in the packet data. Return: Error code indicating success of the operation. An error code indicating whether or not the operation succeeded. Return value: the contents of the OPUS_OK package have been added to the Repacketizer state. The Packet’s contents have been added to The repacketizer. The TOC series for the OPUS_INVALID_PACKET package is invalid, the series does not match the previously submitted package (encoding pattern, audio bandwidth, frame size, or number of channels does not match), or adding this package will result in sounds stored at the Repacketizer state lasting more than 120 milliseconds. 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 to more than 120 ms.

OpusRepacketizer* opus_repacketizer_create ( void )
Copy the code

Allocates memory and initializes the new Repacketizer generated with opus_repacketizer_init(). Allocates memory and initializes the new repacketizer with opus_repacketizer_init().

void opus_repacketizer_destroy ( OpusRepacketizer * rp )
Copy the code

Frees the OpusRepacketizer allocated via opus_repacketizer_Create (). Frees an OpusRepacketizer allocated by opus_repacketizer_create(). Parameter: [in] RP OpusRepacketizer*: Repacketizer state to be released. State to be freed.

int opus_repacketizer_get_nb_frames ( OpusRepacketizer * rp )
Copy the code

Returns the total number of frames contained in the package data submitted through opus_repacketizer_cat() so far since the last call to opus_repacketizer_init() or opus_repacketizer_create(). Return the total number of frames contained in packet data submitted to the repacketizer status so far via opus_repacketizer_cat() since the last call to opus_repacketizer_init() or opus_repacketizer_create(). This defines the range of valid packages that can be extracted by opus_repacketizer_out_range() or opus_repacketizer_out(). This defines the valid range of packets that can be extracted with opus_repacketizer_out_range() or opus_repacketizer_out(). Parameters: RP OpusRepacketizer*: Contains the repacketizer state for each frame. The repacketizer state containing The frames. Returns the total number of frames contained in a package submitted to the Repacketizer state. The total number of frames contained in The packet data submitted to The repacketizer status.

int opus_repacketizer_get_size ( void )
Copy the code

Gets the size of an OpusRepacketizer structure. Returns The size in bytes of The structure.

OpusRepacketizer* opus_repacketizer_init ( OpusRepacketizer * rp )
Copy the code

(reinitializes the previously allocated repacketizer state (Re) initializing a previously allocated repacketizer state. The Repacketizer state must have at least the size returned by opus_repackeTIZer_get_size (). This applies to applications that do not use malloc() but use their own allocator. It is also called to reset the queue of those packets that are awaiting reconstruction, which is necessary if the maximum packet length is 120ms or if you want to submit packets with a different Opus configuration (encoding mode, audio bandwidth, frame size, or number of channels). If this fails, the system will prevent you from adding new packages with opus_repacketizer_cat(). The state must be at least the size returned by opus_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 opus_repacketizer_cat(). See also: opus_repacketizer_create Opus_repacketizer_get_size Opus_repacketizer_cat parameter: Rp OpusRepacketizer*: Repacketizer state to be (re) initialized Returns: pointer to the same Repacketizer state to be entered. A pointer to the same repacketizer state that was passed in.

opus_int32 opus_repacketizer_out    (   OpusRepacketizer *      rp,
        unsigned char *     data,
        opus_int32      maxlen 
    ) 
Copy the code

Build a new package from the data previously given to the Repacketizer state with opus_repacketizer_cat(). Construct a new packet from data previously submitted to the Repacketizer state via opus_repacketizer_cat(). It is convenient to return all data submitted so far into a single package, Doing so is equivalent to calling opus_repacketizer_out_range(rp, 0, opus_repacketizer_get_NB_frames (rp),data, maxlen) 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) Rp OpusRepacketizer*: Repacketizer state ready to build new packages. The repacketizer state from which to construct The new packet. [out] data const unsigned char*: The buffer to store output packets. The buffer in which to store The output packet. Maxlen opus_int32: The maximum number of bytes to store in The output buffer. To ensure success, this value should be at least 1277OPus_repackeTIZer_GEt_NB_frames (RP). However, 1OPus_repacketizer_get_NB_frames (RP) plus the size of all submitted package data since the last call to opus_repacketizer_init() or opus_repacketizer_create() is also sufficient, Or (paradoxically) much smaller. The maximum number of bytes to store in the output buffer. In order to guarantee success, this should be at least 1277opus_repacketizer_get_nb_frames(rp). However, 1opus_repacketizer_get_nb_frames(rp) plus the size of all packet data submitted to the repacketizer since the last call to opus_repacketizer_init() or opus_repacketizer_create() is also sufficient, and possibly much smaller. Returns: success, total package size, failure, error code. The total size of the output packet on success, or an error code on failure. Returned value: OPUS_BUFFER_TOO_SMALL Maximum capacity maxlen is not sufficient to contain the entire output package. maxlen was insufficient to contain the complete output packet.

opus_int32 opus_repacketizer_out_range  (   OpusRepacketizer *      rp,
        int     begin,
        int     end,
        unsigned char *     data,
        opus_int32      maxlen 
    )   
Copy the code

Build a new package from the data previously given to the Repacketizer state with opus_repacketizer_cat(). Construct a new packet from data previously submitted to the Repacketizer state via opus_repacketizer_cat(). Parameters: RP OpusRepacketizer*: Repacketizer state ready to build a new package. The Repacketizer State from which to construct The new packet. Begin int: The index of The first frame of The current Repacketizer state to be exported. The index of the first frame in the current repacketizer state to include in the output. end int: 1.One past the index of the last frame in the current repacketizer State to include in the Output. [out] data const unsigned char*: Prepares the buffer to store the output package. The buffer in which to store The output packet. Maxlen opus_int32: The maximum number of bytes to store in The output buffer. To ensure success, this value should be at least 1277OPus_repackeTIZer_GEt_NB_frames (RP). However, 1OPus_repacketizer_get_NB_frames (RP) plus the size of all submitted package data since the last call to opus_repacketizer_init() or opus_repacketizer_create() is also sufficient, Or (paradoxically) much smaller. 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 opus_repacketizer_init() or opus_repacketizer_create() is also sufficient, and possibly much smaller. Returns: success, total package size, failure, error code. The total size of the output packet on success, or an error code on failure. The return value: OPUS_BAD_ARG (begin,end) is the position where the frame is invalid (begin < 0, begin >= end, or end > opus_repacketizer_get_nb_frames()). [begin,end) was an invalid range of frames (begin < 0, begin >= end, Or end > opus_repacketizer_get_nb_frames()). OPUS_BUFFER_TOO_SMALL Maximum capacity maxlen is insufficient to contain the entire output package. maxlen was insufficient to contain the complete output packet.

Opus Multistream API

The Multistream API allows multiple Opus data streams to be combined into a package capable of supporting up to 255 channels. The multistream API allows individual Opus streams to be combined into a single packet, enabling support for up to 255 channels.

The type definition

typedef struct OpusMSEncoder
OpusMSEncoder
Copy the code

Opus Multi-stream encoder status.

typedef struct OpusMSDecoder
OpusMSDecoder
Copy the code

Opus leaves more decoder state.

Multistream encoder function

Opus_int32 opus_multistream_encoder_get_size (int streams, int coupled_streams) // Allocates and initializes the multistream encoder state.  OpusMSEncoder * opus_multistream_encoder_create (opus_int32 Fs, int channels, int streams, int coupled_streams, Const unsigned char *mapping, int application, int error) // Initializes the previously allocated multistream encoder state. int opus_multistream_encoder_init (OpusMSEncoder *st, opus_int32 Fs, int channels, int streams, int coupled_streams, Const unsigned char *mapping, int application) // Encode a multi-stream Opus frame. int opus_multistream_encode (OpusMSEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *data, Opus_int32 max_datA_bytes) // Encodes a multi-stream Opus frame from the floating point input. int opus_multistream_encode_float (OpusMSEncoder *st, constfloat*pcm, int frame_size, unsigned char *data, Opus_int32 max_datA_bytes) // Release the OpusMSEncoder allocated by opus_multistream_encoder_create (). Void opus_multistream_encoder_destroy (OpusMSEncoder *st) // Execute CTL to a multistream Opus encoder. int opus_multistream_encoder_ctl (OpusMSEncoder *st, int request,...)Copy the code

Multistream decoder function

Opus_int32 opus_multistream_decoder_get_size (int streams, int coupled_streams) // Allocates and initializes the multistream decoder state. OpusMSDecoder * opus_multistream_decoder_create (opus_int32 Fs, int channels, int streams, int coupled_streams, Const unsigned char *mapping, int *error) // Initializes the previously allocated multistream encoder state object. int opus_multistream_decoder_init (OpusMSDecoder *st, opus_int32 Fs, int channels, int streams, int coupled_streams, Const unsigned char *mapping) // Decodes a multistream Opus packet. int opus_multistream_decode (OpusMSDecoder *st, const unsigned char *data, opus_int32 len, opus_int16 *pcm, Int frame_size, int decode_fec) // Decodes a multistream Opus packet with floating-point output. int opus_multistream_decode_float (OpusMSDecoder *st, const unsigned char *data, opus_int32 len,float* PCM, int frame_size, int decode_fec) int opus_multistream_decoder_ctl (OpusMSDecoder *st, int request,...) // Release OpusMSDecoder allocated by opus_multiSTREAM_decoder_create (). void opus_multistream_decoder_destroy (OpusMSDecoder *st)Copy the code

A detailed description

The multi-stream API allows multiple Opus data streams to be combined into a package capable of supporting up to 255 channels. The multistream API allows individual Opus streams to be combined into a single packet, enabling support for up to 255 channels. Unlike a basic Opus stream, the encoder and decoder must agree on the channel configuration before the decoder can successfully interpret the data in the packet generated by the encoder. Some basic information, such as the duration of the package, can be calculated without special negotiation. Unlike an elementary Opus stream, the encoder and decoder must negotiate the channel configuration before the decoder can successfully interpret the data in the packets produced by the encoder. Some basic information, such as packet duration, can be computed without any special negotiation. The format of the multistream Opus package is defined in the Ogg package specification and is also based on the customized Opus framework as described in Appendix B of RFC 6716. The standard Opus package happens to be a degraded version of the multi-stream Opus package that can be encoded and decoded using the convection API, When initializing The encoder and decoder, set The number of streams to 1. The format for multistream Opus packets is defined in The Ogg Encapsulation Specification and is based on the self-delimited Opus framing described in Appendix B of RFC 6716. Normal Opus packets are just a degenerate case of multistream Opus packets, and can be encoded or decoded with the multistream API by setting streams to 1 when initializing the encoder or decoder. A multistream Opus data stream can contain up to 255 basic Opus streams, which can be either “queued” or “unqueued”, indicating that the decoder is configured to decode them with 1 or 2 channels respectively. These flows are ordered so that all the flows that are grouped can appear in the first place (which seems inappropriate). Multistream Opus streams can contain up to 255 elementary Opus streams. These may be either “uncoupled” or “coupled”, indicating that the decoder is configured to decode them to either 1 or 2 channels, respectively. The streams are ordered so that all coupled streams appear at the beginning. A mapping table is used to define which decoding channel I should be used for which input/output (I/O) channel J. This table is typically used as an array of unsigned characters. Let I = mapping[j] which is the index of I/O channel J. If I < 2coupled_streams, then if I is even, I/O channel J is encoded according to the left channel of the data stream; If I is odd, I/O channel J is encoded according to the right channel of the data stream. Otherwise, the I/O channel J is encoded according to the i-coupled_streams of the data stream, unless it has a special value of 255, in which case it will be removed from the encoding entirely (the decoder will rebuild it as a mute). Each value of I is either a special value 255 or less than streams + coupled_streams. A mapping table defines which decoded channel i should be used for each input/output (I/O) channel j. This table is typically provided as an unsigned char array. Let i = mapping[j] be the index for I/O channel j. If i < 2coupled_streams, then I/O channel j is encoded as the left channel of stream (i/2) if i is even, or as the right channel of stream (i/2) if i is odd. Otherwise, I/O channel j is encoded as mono in stream (i – coupled_streams), unless it has the special value 255, in which case it is omitted from the encoding entirely (the decoder will reproduce it as silence). Each value i must either be the special value 255 or be less than streams + coupled_streams. It must be noted that the output channel of the encoder should use the channel rules of Vorbis (free music format). The decoder may wish to apply an additional permutation to map encoders used to implement different output channel rules (for example, output for WAV rules). The output channels specified by the encoder should use the Vorbis channel ordering. A decoder may wish to apply an additional permutation to the mapping the encoder used to achieve a different output channel order (e.g. for outputing in WAV order). Multi-stream packets contain Opus packets corresponding to each stream, and all Opus packets within a single multi-stream packet must have the same duration. Thus, the duration of a multi-stream package can be extracted from the TOC sequence of the first stream at the start of the package, just like a basic Opus stream: Each multistream packet contains an Opus psacket for each stream, and all of the Opus packets in a single multistream packet must have the same duration. Therefore the duration of a multistream packet can be extracted from the TOC sequence of the first stream, which is located at the beginning of the packet, just like an elementary Opus stream:

int nb_samples;
int nb_frames;
nb_frames = opus_packet_get_nb_frames(data, len);
if (nb_frames < 1)
    return nb_frames;
nb_samples = opus_packet_get_samples_per_frame(data, 48000) * nb_frames;
Copy the code

The general encoding and decoding process executes exactly the same standard Opus Encoder and Opus Decoder apis. You can refer to their documentation on how to use the corresponding multistream functions. The general encoding and decoding process proceeds exactly the same as in the normal Opus Encoder and Opus Decoder APIs. See their documentation for an overview of how to use the corresponding multistream functions.

Type definition document

typedef struct OpusMSDecoder OpusMSDecoder
Copy the code

Opus multistream decoder state. Opus multistream decoder state. This contains the complete state of an Opus multistream decoder. It is position-independent and can be copied freely. This contains the complete state of a multistream Opus decoder. It is position independent and can be freely copied. See: opus_multistream_decoder_create opus_multistream_decoder_init

typedef struct OpusMSEncoder OpusMSEncoder
Copy the code

Opus Multi-stream encoder status. Opus multistream encoder state. This contains the complete state of an Opus multistream encoder. It is position-independent and can be copied freely. This contains the complete state of a multistream Opus encoder. It is position independent and can be freely copied. See: opus_multistream_encoder_create opus_multistream_encoder_init

Function of the document

int opus_multistream_decode     (   OpusMSDecoder *     st,
        const unsigned char *   data,
        opus_int32      len,
        opus_int16 *    pcm,
        int     frame_size,
        int     decode_fec 
    )   
Copy the code

Decodes a multistream Opus packet. Decode a multistream Opus packet. Parameters:

• St OpusMSDecoder*: Opus multistream decoder status. Multistream decoder state.
• [in] data const unsigned char*: input load. Packet loss is represented by a null pointer. Input payload. Use a NULL pointer to indicate packet loss.
• Len opus_int32: Number of bytes in the input load. Number of bytes in payload.
• [out] PCM opus_INT16 *: Output signal using cross sample. Must contain frame_sizeSpace of sample number in Channels. Output signal, with interleaved samples. This must contain room for frame_sizechannels samples.
• Frame_size int: Number of samples per channel in available PCM space. If less than the maximum packet length (120 ms, 4848kHz5760), this function will not decode some packets. In the case of PLC (data==NULL) or FEC (decoDE_FEC =1), frame_size must be exactly the length of time the audio was lost, otherwise the decoder cannot be optimized for decoding the next packet. For PLC and FEC cases, frame_size must be a multiple of 2.5 milliseconds. The number of samples per channel of available space in pcm. If this is less than the maximum packet duration (120 ms; 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.5ms.
• Decode_fec int: status flag (0 or 1) for requesting any in-band forward error correction data to be decoded. If no such data is available, the frame is considered lost when decoded. 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: success, number of decoded samples, failure, negative error code. Number of samples decoded on success or a negative error code (see Error codes) on failure.

int opus_multistream_decode_float   (   OpusMSDecoder *     st,
        const unsigned char *   data,
        opus_int32      len,
        float *     pcm,
        int     frame_size,
        int     decode_fec 
    ) 
Copy the code

Decodes a multistream Opus package in floating-point output format. Decode a multistream Opus packet with floating point output. Parameters:

• St OpusMSDecoder*: Opus multistream decoder status. Multistream decoder state.
• [in] data const unsigned char*:: Input load. Packet loss is represented by a null pointer. Input payload. Use a NULL pointer to indicate packet loss.
• Len opus_int32: Number of bytes in the input load. Number of bytes in payload.
• [out] PCM opus_INT16 *: Output signal using cross sample. Must contain frame_sizeSpace of sample number in Channels. Output signal, with interleaved samples. This must contain room for frame_sizechannels samples.
• Frame_size int: Number of samples per channel in available PCM space. If less than the maximum packet length (120 ms, 4848kHz5760), this function will not decode some packets. In the case of PLC (data==NULL) or FEC (decoDE_FEC =1), frame_size must be exactly the length of time the audio was lost, otherwise the decoder cannot be optimized for decoding the next packet. For PLC and FEC cases, frame_size must be a multiple of 2.5 milliseconds. The number of samples per channel of available space in pcm. If this is less than the maximum packet duration (120 ms; 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.5ms.
• Decode_fec int: status flag (0 or 1) for requesting any in-band forward error correction data to be decoded. If no such data is available, the frame is considered lost when decoded. 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: success, number of decoded samples, failure, negative error code. Number of samples decoded on success or a negative error code (see Error codes) on failure.

OpusMSDecoder* opus_multistream_decoder_create  (   opus_int32      Fs,
        int     channels,
        int     streams,
        int     coupled_streams,
        const unsigned char *   mapping,
        int *   error 
    ) 
Copy the code

Allocates and initializes multistream decoder state. Allocates and initializes a multistream decoder state. When finished, opus_multistream_decoder_destroy() is called to release the object. Call opus_multistream_decoder_destroy() to release this object when finished. Parameters:

• Fs opus_int32: Sampling rate to decode at (in Hz). This must be one of 8000, 12000, 16000, 24000, or 48000. 12000, 16000, 24000, or 48000.
• Channels int: The number of channels used to decode, up to 255, which may differ from the number of streams + coupled_streams. Number of channels to output. This must be at most 255. It may be different from the number of coded channels (streams + coupled_streams).
• The total number of streams coded in The input must not exceed 255. This must be no more than 255.
• Coupled_streams INT: Number of data streams to be decoded as group streams (2 channels). Must not be greater than the total number of data streams. In addition, The Number of streams to decode as coupled (2 channels) streams must be no more than 255 larger than the total number of streams. Additionally, The total number of coded channels (streams + coupled_streams) must be no more than 255.
• [in] mapping const unsigned char[Channels]: Indicates the mapping between the encoded channels and the output channels. Mapping from coded channels to output channels, as described in Opus Multistream API.
• [out] error int *: OPUS_OK is returned on success, error code is returned on failure. Returns OPUS_OK on success, or an error code (see Error codes) on failure.

int opus_multistream_decoder_ctl    (   OpusMSDecoder *     st,
        int     request,
            ... 
    )      
Copy the code

Executes a CTL function to an Opus multistream decoder. Perform a CTL function on a multistream Opus decoder. Typically its request and subsequent parameters are generated by a convenience macro. Generally the request and subsequent arguments are generated by a convenience macro. Parameters:

• St OpusMSDecoder*: Multi-stream decoder state. Multistream decoder state.
• Request: This and all other remaining parameters should be replaced by a macro that facilitates CTLs in Generic CTLs, Decoder related CTLs, or Multistream specific encoder and Decoder CTLs. This and all remaining parameters should be replaced by one of the convenience macros in Generic CTLs, Decoder related CTLs, or Multistream specific encoder and decoder CTLs. See also: Generic CTLs Decoder Related CTLs Multistream Specific encoder and Decoder CTLs

void opus_multistream_decoder_destroy ( OpusMSDecoder * st ) 
Copy the code

Releases an OpusMSDecoder object allocated according to opus_multiSTREAM_decoder_create (). Frees an OpusMSDecoder allocated by opus_multistream_decoder_create(). Parameters:

• St OpusMSDecoder: Multistream decoder state for release. Multistream decoder state to be freed.

opus_int32 opus_multistream_decoder_get_size ( int streams,
int coupled_streams
)
Copy the code

Gets the size of the OpusMSDecoder structure. Gets the size of an OpusMSDecoder structure. Parameters:

• The total number of streams coded in The input must not exceed 255. This must be no more than 255.
• Coupled_streams INT: Number of data streams to be decoded as group streams (2 channels). Must not be greater than the total number of data streams. In addition, The Number of streams + coupled_streams must be no more than 255 larger than the total number of streams. Additionally, The total number of coded channels (streams + coupled_streams) must be no more than 255. Returns: success, number of bytes, failure, negative error code. The size in bytes on success, or a negative error code (see Error codes) on error.

int opus_multistream_decoder_init   (   OpusMSDecoder *     st,
        opus_int32      Fs,
        int     channels,
        int     streams,
        int     coupled_streams,
        const unsigned char *   mapping 
    ) 
Copy the code

Initialize a previously allocated decoder object. Intialize a previously allocated decoder state object. St must point to at least the size returned by opus_multistream_decoder_get_size(), For applications that do not automatically allocate memory to the system and need to prepare to use their own allocator. To reset the previously initialized state, use OPUS_RESET_STATE CTL. The memory pointed to by st must be at least the size returned by opus_multistream_decoder_get_size(). This is intended for applications which use their own allocator instead of malloc. To reset a previously initialized state, use the OPUS_RESET_STATE CTL. See also: opus_multistream_decoder_create Opus_multistream_deocder_get_size parameter:

• St OpusMSEncoder*: Multistream decoder state ready for initialization. Multistream encoder state to initialize.
• Fs opus_int32: Sampling rate to decode at (in Hz). This must be one of 8000, 12000, 16000, 24000, or 48000. 12000, 16000, 24000, or 48000.
• Channels int: The number of channels used for output, up to 255, which may be different from the number of streams + coupled_streams. Number of channels to output. This must be at most 255. It may be different from the number of coded channels (streams + coupled_streams).
• The total number of streams coded in The input must not exceed 255. This must be no more than 255.
• Coupled_streams INT: Number of data streams to be decoded as group streams (2 channels). Must not be greater than the total number of data streams. In addition, The Number of streams to decode as coupled (2 channels) streams must be no more than 255 larger than the total number of streams. Additionally, The total number of coded channels (streams + coupled_streams) must be no more than 255.
• [in] mapping const unsigned char[Channels]: Indicates the mapping between the encoded channels and the output channels. Mapping from coded channels to output channels, as described in Opus Multistream API.

Return: OPUS_OK on success, error code on failure. OPUS_OK on success, or an error code (see Error codes) on failure.

int opus_multistream_encode     (   OpusMSEncoder *     st,
        const opus_int16 *      pcm,
        int     frame_size,
        unsigned char *     data,
        opus_int32      max_data_bytes 
    )   
Copy the code

Encode a multistream Opus frame. Encodes a multistream Opus frame. Parameters:

• St OpusMSEncoder*: Multi-stream encoder status. Multistream encoder state.
• [in] PCM const opus_int16*: Input signal using cross sample. Must contain frame_sizeSpace of sample number in Channels. The input signal as interleaved samples. This must contain frame_sizechannels samples.
• Frame_size INT: Output signals using cross samples for each channel of the input signal. There must be room for the frame_size* Channels sample number. This must be the encoder sampling rate of the Opus frame size. For example, the allowable values at 48 kHz are 120, 240, 480, 960, 1920, and 2880. Samples of less than 10 ms (480 samples at 48 kHz) will prevent the encoder from using LPC or mixed mode. 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.
• [out] data unsigned char*: output load. Must contain at least max_datA_bytes of capacity. Output payload. This must contain storage for at least max_data_bytes.
• [in] max_DATA_bytes opus_INT32: Memory size allocated for output load. Can be used to limit the maximum fixed bit rate limit, but not as a unique bit rate limit. You can use OPUS_SET_BITRATE to control the bit rate. 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 OPUS_SET_BITRATE to control the bitrate. Returns: success, which is the length of the encoded package (in bytes), failure, a negative error code. The length of the encoded packet (in bytes) on success or a negative error code (see Error codes) on failure.

int opus_multistream_encode_float   (   OpusMSEncoder *     st,
        const float *   pcm,
        int     frame_size,
        unsigned char *     data,
        opus_int32      max_data_bytes 
    )   
Copy the code

Encodes an Opus frame based on floating point input. Encodes a multistream Opus frame from floating point input. Parameters:

• St OpusMSEncoder*: Multi-stream encoder status. Multistream encoder state.
• [in] PCM const float*: Input signal of cross sample, normal range between +/-1.0. Sampling beyond this range is also supported, but it will be intercepted by the decoder using an integer API and can only be used if the remote side is known to support extended dynamic range. Must contain frame_sizeSpace of sample number in Channels. The input signal as interleaved samples 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. This must contain frame_sizechannels samples.
• Frame_size INT: Output signals using cross samples for each channel of the input signal. There must be room for the frame_size* Channels sample number. This must be the encoder sampling rate of the Opus frame size. For example, the allowable values at 48 kHz are 120, 240, 480, 960, 1920, and 2880. Samples of less than 10 ms (480 samples at 48 kHz) will prevent the encoder from using LPC or mixed mode. 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.
• [out] data unsigned char*: output load. Must contain at least max_datA_bytes of capacity. Output payload. This must contain storage for at least max_data_bytes.
• [in] max_DATA_bytes opus_INT32: Memory size allocated for output load. Can be used to limit the maximum fixed bit rate limit, but not as a unique bit rate limit. You can use OPUS_SET_BITRATE to control the bit rate. 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 OPUS_SET_BITRATE to control the bitrate.

Returns: success, which is the length of the encoded package (in bytes), failure, a negative error code. The length of the encoded packet (in bytes) on success or a negative error code (see Error codes) on failure.

OpusMSEncoder* opus_multistream_encoder_create  (   opus_int32      Fs,
        int     channels,
        int     streams,
        int     coupled_streams,
        const unsigned char *   mapping,
        int     application,
        int *   error 
    )   
Copy the code

Allocates and initializes the multistream encoder state. Allocates and initializes a multistream encoder state. When finished, opus_multistream_encoder_destroy() is called to release the object. Call opus_multistream_encoder_destroy() to release this object when finished. Parameters:

• Fs opus_int32: Decoding sampling rate (Hz). Must be 8000, 12000, 16000, 24000, Sampling rate of the input signal (in Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.
• Channels int: The number of channels in the input signal, which is up to 255 and may be greater than the number of streams + coupled_streams. Number of channels in the input signal. This must be at most 255. It may be greater than the number of coded channels (streams + coupled_streams).
• Streams Int Specifies the total number of streams to be encoded, which must not exceed the number of channels. The total number of streams to encode from the input. This must be no more than the number of channels.
• Coupled_streams INT: The total number of pair (2-channel) data streams to encode must not be greater than the total number of data streams. In addition, the total number of encoded channels (Streams + Coupled_Streams) must not exceed the number of input channels. Number of coupled (2 channel) streams to encode. This must be no larger than the total number of streams. Additionally, The total number of encoded channels (streams + coupled_streams) must be no more than the number of input channels.
• [in] mapping const unsigned char[Channels]: Indicates the mapping between the encoded channels and the input channels. As an additional limitation, multistream encoders don’t allow you to encode a data stream for a group where the channel is not available, because that’s a bad idea. Mapping from encoded channels to input channels, as described in Opus Multistream API. As an extra constraint, the multistream encoder does not allow encoding coupled streams for which one channel is unused since this is never a good idea.
• Application int: target encoder application, must be one of The following:
  • OPUS_APPLICATION_VOIP Improves voice articulation processing signals. Process signal for improved speech intelligibility.
  • OPUS_APPLICATION_AUDIO preference versus the correctness of the original input. Favor faithfulness to the original input.
  • OPUS_APPLICATION_RESTRICTED_LOWDELAY keeps coding delays as small as possible by invalidating specific operation modes. Configure the minimum possible coding delay by disabling certain modes of operation.
• [out] error int *: OPUS_OK is returned on success, error code is returned on failure. Returns OPUS_OK on success, or an error code (see Error codes) on failure.

int opus_multistream_encoder_ctl    (   OpusMSEncoder *     st,
        int     request,
            ... 
    ) 
Copy the code

Execute a CTL function to an Opus multistream encoder. Perform a CTL function on a multistream Opus encoder. Typically its request and subsequent parameters are generated by a convenience macro. Generally the request and subsequent arguments are generated by a convenience macro. Parameters: ST OpusMSEncoder*: Multi-stream encoder status. Multistream encoder state. request: This and all other remaining parameters should be replaced by a macro that is convenient for Generic CTLs, encoder related CTLs, or multistream-specific encoder and decoder CTLs. This and all remaining parameters should be replaced by one of the convenience macros in Generic CTLs, Encoder related CTLs, or Multistream specific encoder and decoder CTLs. See also: Generic CTLs Encoder Related CTLs Multistream Specific Encoder and decoder CTLs

Void opus_multistream_encoder_destroy (OpusMSEncoder * st) Releases a destroy based on opus_ Multistream_encoder_create () The allocated OpusMSEncoder object. Frees an OpusMSEncoder allocated by opus_multistream_encoder_create(). Parameters:

• St OpusMSEncoder*: Multistream encoder state for release. Multistream encoder state to be freed.

opus_int32 opus_multistream_encoder_get_size    (   int     streams,
        int     coupled_streams 
    )   
Copy the code

Gets the size of the OpusMSEncoder structure. Gets the size of an OpusMSEncoder structure. Parameters:

• streams int: The total number of streams used for encoding from The input must not exceed 255.
• Coupled_streams Int: Number of group streams (2 channels) to encode. Must not be greater than the total number of data streams. In addition, The Number of streams + coupled_streams must not be larger than 255 the total number of streams. Additionally, The total number of encoded channels (streams + coupled_streams) must be no more than 255. Returns: success, number of bytes, failure, negative error code. The size in bytes on success, or a negative error code (see Error codes) on error.

int opus_multistream_encoder_init   (   OpusMSEncoder *     st,
        opus_int32      Fs,
        int     channels,
        int     streams,
        int     coupled_streams,
        const unsigned char *   mapping,
        int     application 
    )   
Copy the code

Initialize a previously allocated encoder object. Initialize a previously allocated multistream encoder state. st Must be at least the size returned by opus_multistream_encoder_get_size(), For applications that do not automatically allocate memory to the system and need to prepare to use their own allocator. To reset the previously initialized state, use OPUS_RESET_STATE CTL. The memory pointed to by st must be at least the size returned by opus_multistream_encoder_get_size(). This is intended for applications which use their own allocator instead of malloc. To reset a previously initialized state, use the OPUS_RESET_STATE CTL. See also: opus_multistream_encoder_create Opus_multistream_encoder_get_size parameter:

• St OpusMSEncoder*: Multistream encoder state ready for initialization. Multistream encoder state to initialize.
• Fs opus_int32: Input signal sampling rate (Hz). Must be 8000, 12000, 16000, 24000, Sampling rate of the input signal (in Hz). This must be one of 8000, 12000, 16000, 24000, or 48000.
• Channels int: The number of channels in the input signal, which can be up to 255 and may be greater than the number of streams + coupled_streams. Number of channels in the input signal. This must be at most 255. It may be greater than the number of coded channels (streams + coupled_streams).
• Streams Int: The total number of streams to encode from the input, which must not be greater than the number of channels. The total number of streams to encode from the input. This must be no more than the number of channels.
• Coupled_streams INT: The total number of pair (2-channel) data streams to encode must not be greater than the total number of data streams. In addition, the total number of encoded channels (Streams + Coupled_Streams) must not exceed the number of input channels. Number of coupled (2 channel) streams to encode. This must be no larger than the total number of streams. Additionally, The total number of encoded channels (streams + coupled_streams) must be no more than the number of input channels.
• [in] mapping const unsigned char[Channels]: Indicates the mapping between the encoded channels and the input channels. As an additional limitation, multistream encoders don’t allow you to encode a data stream for a group where the channel is not available, because that’s a bad idea. Mapping from encoded channels to input channels, as described in Opus Multistream API. As an extra constraint, the multistream encoder does not allow encoding coupled streams for which one channel is unused since this is never a good idea.
• Application int: target encoder application, must be one of The following: – OPUS_APPLICATION_VOIP Improves voice articulation processing signals. Process signal for improved speech intelligibility. – OPUS_APPLICATION_AUDIO preference and the correctness of the original input. Favor faithfulness to the original input. – OPUS_APPLICATION_RESTRICTED_LOWDELAY Invalidates specific operating modes to keep coding delays as small as possible. Configure the minimum possible coding delay by disabling certain modes of operation. Return: OPUS_OK on success, error code on failure. OPUS_OK on success, or an error code (see Error codes) on failure.

Opus library information functions

This section describes the Opus library information functions

function

Converts an opus error code into a human readable string.

const char * opus_strerror (int error)
Copy the code

Gets the libopus version string.

const char * opus_get_version_string (void)
Copy the code

Function of the document

const char* opus_get_version_string ( void )
Copy the code

Get libopus version information, expressed as a string. Gets the libopus version string. Returns: version string. Version string

const char* opus_strerror ( int error )
Copy the code

Convert the Opus error code to a human-readable string. Converts an opus error code into a human readable string. Parameters:

• [in] error int: indicates the error number. Error number: the Error string is returned. Error string

Opus Custom

Opus Custom is an optional part of the Opus specification and reference implementation and can be used to use a unique API that is different from the normal API and supports abnormal frame sizes. Opus Custom is only used for very specific applications that need to handle different frame specifications than 2.5, 5, 10, or 20 ms (due to complexity or other potential reasons), where interoperability is less important. Opus Custom is an optional part of the Opus specification and reference implementation which uses a distinct API from the regular API and supports frame sizes that are not normally supported. Use of Opus Custom is discouraged for all but Very special applications for which a frame size different from 2.5, 5, 10, or 20 ms is needed (for either complexity or latency reasons) and where interoperability is less important.

The type definition

The encoder state Contains the state of an encoder.

typedef struct OpusCustomEncoder
OpusCustomEncoder
Copy the code

Decoder State of the decoder.

typedef struct OpusCustomDecoder

Copy the code

The mode contains all The information necessary to create an encoder.

function

OpusCustomMode *
opus_custom_mode_create (opus_int32 Fs, int frame_size, int *error)
Copy the code

Create a new schema structure. Creates a new mode struct.

void opus_custom_mode_destroy (OpusCustomMode *mode)
Copy the code

Deconstruct a pattern structure. Destroys a mode struct.

int opus_custom_encoder_get_size (const OpusCustomMode *mode, int channels)
Copy the code

Gets the size of the OpusCustomEncoder structure. Gets the size of an OpusCustomEncoder structure.

OpusCustomEncoder * opus_custom_encoder_create (const OpusCustomMode *mode, int channels, int *error)
Copy the code

Create a new encoder state. Creates a new encoder state.

int opus_custom_encoder_init (OpusCustomEncoder *st, const OpusCustomMode *mode, int channels)
Copy the code

Initialize a previously allocated encoder state. The memory referred to by ST must be the size returned by opus_custom_encoder_get_size. Initializes a previously allocated encoder state The memory pointed to by st must be the size returned by opus_custom_encoder_get_size.

void opus_custom_encoder_destroy (OpusCustomEncoder *st)
Copy the code

Deconstruct an encoder state. Destroys a an encoder state.

int opus_custom_encode_float (OpusCustomEncoder *st, const float *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes)
Copy the code

Encode an audio frame. Encodes a frame of audio.

int opus_custom_encode (OpusCustomEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes)
Copy the code

Encode an audio frame. Encodes a frame of audio.

int opus_custom_encoder_ctl (OpusCustomEncoder *OPUS_RESTRICT st, int request,...)
Copy the code

Execute a CTL function for an Opus custom encoder. Perform a CTL function on an Opus custom encoder.

int opus_custom_decoder_get_size (const OpusCustomMode *mode, int channels)
Copy the code

Get the size of an OpusCustomDecoder structure. Gets the size of an OpusCustomDecoder structure.

OpusCustomDecoder * opus_custom_decoder_create (const OpusCustomMode *mode, int channels, int *error)
Copy the code

Create a new decoder state. Creates a new decoder state.

int opus_custom_decoder_init (OpusCustomDecoder *st, const OpusCustomMode *mode, int channels)
Copy the code

Initialize a previously allocated decoder state. The memory referred to by ST must be the size returned by opus_CUSTOM_decoder_get_size. Initializes a previously allocated decoder state The memory pointed to by st must be the size returned by opus_custom_decoder_get_size.

void opus_custom_decoder_destroy (OpusCustomDecoder *st)
Copy the code

Deconstruct a decoder state. Destroys a an decoder state.

int opus_custom_decode_float (OpusCustomDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size)
Copy the code

Decodes an Opus custom frame using floating point output. Decode an opus custom frame with floating point output.

int opus_custom_decode (OpusCustomDecoder *st, const unsigned char *data, int len, opus_int16 *pcm, int frame_size)
Copy the code

Decode an Opus custom frame. Decode an opus custom frame.

int opus_custom_decoder_ctl (OpusCustomDecoder *OPUS_RESTRICT st, int request,...)
Copy the code

Performs a CTL function for an Opus custom decoder. Perform a CTL function on an Opus custom decoder.

A detailed description

Opus Custom is an optional part of the Opus specification and reference implementation and can be used to use a unique API that is different from the normal API and supports abnormal frame sizes. Opus Custom is only used for very specific applications that need to handle different frame specifications than 2.5, 5, 10, or 20 ms (due to complexity or other potential reasons), where interoperability is less important. Opus Custom is an optional part of the Opus specification and reference implementation which uses a distinct API from the regular API and supports frame sizes that are not normally supported. Use of Opus Custom is discouraged for all but Very special applications for which a frame size different from 2.5, 5, 10, or 20 ms is needed (for either complexity or latency reasons) and where interoperability is less important. In addition to interoperability limitations, the use of Opus customization makes most of the codec functionality unusable and generally reduces the quality attainable at a given bit rate. Normally when an application needs to get a different frame size from the codec, it should create a buffer to accommodate the required frame space, but this adds a small amount of latency that is important for some very low-latency applications. Some transport protocols (especially RF transport with constant traffic) may also be able to handle special long frames best. In addition to the interoperiability limitations the use of Opus custom disables a substantial chunk of the codec and generally lowers the quality available at a given bitrate. Normally when an application needs a different frame size from the codec it should buffer to match the sizes but this adds a small amount of delay which may be important in some very low latency applications. Some transports (especially constant rate RF transports) may also work best with frames of particular durations. If activated at compile time, libopus only supports custom mode. Libopus only supports custom modes if they are enabled at compile time. Opus custom apis are similar to normal apis, But the calls to opus_encoder_CREATE and opus_decoder_CREATE have an additional schema parameter, which is the structure generated by calling opus_custom_mode_CREATE. The encoder and decoder must agree on a pattern using the same sampling rate (FS) and frame size (frame size), and these parameters must either be schemed out of band or fixed in a particular implementation. The Opus Custom API is similar to the regular API but the opus_encoder_create and opus_decoder_create calls take an additional mode parameter which is a structure produced by a call to opus_custom_mode_create. Both the encoder and decoder must create a mode using the same sample rate (fs) and frame size (frame size) so these parameters must either be signaled out of band or fixed in a particular implementation. Similar to normal, Opus custom mode supports flight frame size conversion, although these available sizes depend on the particular frame size in use. The flight frame size is available for some initial frame sizes of a single data stream. Similar to regular Opus the custom modes support on the fly frame size switching, but the sizes available depend on the particular frame size in use. For some initial frame sizes on a single on the fly size is available.

Type definition document

typedef struct OpusCustomDecoder OpusCustomDecoder
Copy the code

Decoder state. State of the decoder. For each data stream, a decoder State is required. The decoder state is initialized once at the beginning of the data stream. Do not innovate initialization for each frame. One decoder state is needed for each stream. It is initialized once at the beginning of the stream. Do not re-initialize the state for every frame. Decoder state

typedef struct OpusCustomEncoder OpusCustomEncoder
Copy the code

Encoder status. Contains the state of an encoder. For each data flow, an encoder state is required. The encoder state is initialized once at the beginning of the data flow. Do not innovate initialization for each frame. One encoder state is needed for each stream. It is initialized once at the beginning of the stream. Do not re-initialize the state for every frame. Encoder state

typedef struct OpusCustomMode OpusCustomMode
Copy the code

The mode contains all The information necessary to create an encoder. The encoder and decoder need to be initialized in exactly the same mode, otherwise the output will be corrupted. Both the encoder and decoder need to be initialized with exactly the same mode, otherwise the output will be corrupted. Mode configuration

Function of the document

int opus_custom_decode  (   OpusCustomDecoder *     st,
        const unsigned char *   data,
        int     len,
        opus_int16 *    pcm,
        int     frame_size 
    ) 
Copy the code

Decode an Opus custom frame. Decode an opus custom frame.

• [in] St OpusCustomDecoder*: Decoder state
• [in] data char*: indicates the input load. Packet loss is represented by a null pointer. Input payload. Use a NULL pointer to indicate packet loss
• [in] len int: Indicates the Number of bytes in the input payload
• [out] PCM opus_int16*: output signal (if 2 channels are crossed). Length equal to frame_sizechannelsSizeof (opus_int16). Output signal (interleaved if 2 channels). length is frame_sizechannelssizeof(opus_int16)
• [in] frame_size: Number of samples per channel in * PCM available space. Number of samples per channel of available space in *pcm. Return: Number of decoded samples, or error code. Number of decoded samples or Error codes

int opus_custom_decode_float    (   OpusCustomDecoder *     st,
        const unsigned char *   data,
        int     len,
        float *     pcm,
        int     frame_size 
    )
Copy the code

Decodes an Opus custom frame with floating point output. Decode an opus custom frame with floating point output. Parameters:

• [in] St OpusCustomDecoder*: Decoder status. Decoder state
• [in] data char*: indicates the input load. Packet loss is represented by a null pointer. Input payload. Use a NULL pointer to indicate packet loss
• [in] len int: Indicates the Number of bytes in the input payload
• [out] PCM float*: output signal (if 2 channels are crossed). Length equal to frame_sizechannelsSizeof (float). Output signal (interleaved if 2 channels). length is frame_sizechannelssizeof(float)
• [in] frame_size: Number of samples per channel in * PCM available space. Number of samples per channel of available space in *pcm. Return: Number of decoded samples, or error code. Number of decoded samples or Error codes

OpusCustomDecoder* opus_custom_decoder_create   (   const OpusCustomMode *      mode,
        int     channels,
        int *   error 
    )
Copy the code

Create a new decoder state. Creates a new decoder state. Each stream needs to have its own decoder state (which cannot be shared with simultaneous streams). Each stream needs its own decoder state (can’t be shared across simultaneous streams). Parameters:

• [in] mode OpusCustomMode: Contains all information about the characteristics of the data stream (must be the same as for the encoder). Contains all the information about the characteristics of the stream (must be the same characteristics as used for the encoder)
• [in] channels int Number of channels
• [out] error int*: Returns an error code. Returns an error code: The newly created decoder status. Newly created decoder state.

int opus_custom_decoder_ctl     (   OpusCustomDecoder *OPUS_RESTRICT    st,
        int     request,
            ... 
    )   
Copy the code

Execute a CTL function for the Opus custom decoder. Perform a CTL function on an Opus custom decoder. Typically its request and subsequent parameters are generated by a convenience macro. Generally the request and subsequent arguments are generated by a convenience macro. See also: Generic CTLs

Void opus_custom_decoder_destroy (OpusCustomDecoder * st) Deconstructs a decoder state. Destroys a an decoder state.Copy the code

Parameters:

• [in] St OpusCustomDecoder*: State to be released. State to be freed.

int opus_custom_decoder_get_size    (   const OpusCustomMode *      mode,
        int     channels 
    )   
Copy the code

Get the size of the OpusCustomDecoder structure. Gets the size of an OpusCustomDecoder structure. Parameters:

• [in] mode OpusCustomMode *: Mode configuration. Mode configuration
• [in] channels int Number of Channels Returns: size. size

int opus_custom_decoder_init    (   OpusCustomDecoder *     st,
        const OpusCustomMode *      mode,
        int     channels 
    )
Copy the code

Initialize a previously allocated decoder state. The memory referred to by st must be the size returned by opus_ CUSTOM_ decoder_get_size(). Instead of using the system to automatically allocate memory, the application is prepared to use its own allocator. Initializes a previously allocated decoder state The memory pointed to by st must be the size retured by opus_custom_decoder_get_size. This is intended for applications which use their own allocator instead of malloc. See also: Opus_custom_decoder_create (),opus_custom_decoder_get_size(), reset a previously initialized state, Use OPUS_RESET_STATE CTL.To reset a previously initialized state use the OPUS_RESET_STATE CTL. Parameters:

• [in] St OpusCustomDecoder*: Decoder status. Decoder state
• [in] mode OpusCustomMode *: Contains all information about the characteristics of the data stream (must be the same as for the encoder). Contains all the information about the characteristics of the stream (must be the same characteristics as used for the encoder)
• [in] channels int Number of channels returns: success, OPUS_OK, failure, error code. OPUS_OK Success or Error codes

int opus_custom_encode  (   OpusCustomEncoder *     st,
        const opus_int16 *      pcm,
        int     frame_size,
        unsigned char *     compressed,
        int     maxCompressedBytes 
    )
Copy the code

Encode an audio frame. Encodes a frame of audio.

• [in] st OpusCustomEncoder*: Encoder state
• [in] PCM opus_int16*: PCM audio of signals in 16-bit format (original byte storage order). Each channel must have exactly frame_size samples. PCM audio in signed 16-bit format (native endian). There must be exactly frame_size samples per channel.
• [in] frame_size int: Number of input signal samples per frame. Number of samples per frame of input signal
• [out] compressed char *: compressed data is written here. It may not be in PCM format and must have a length of maxCompressedBytes. The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
• [in] maxCompressedBytes int: The maximum number of bytes used to compress a frame (which can be changed from frame to frame). Maximum number of bytes to use for compressing the frame (can change from one frame to another) If it is negative, it is an error (see error code). It is important that this length be passed to the decoder in some way, otherwise it cannot be decoded. Number of bytes written to “compressed”. If negative, an error has occurred (see error codes). It is IMPORTANT that the length returned be somehow transmitted to the decoder. Otherwise, no decoding is possible.

int opus_custom_encode_float    (   OpusCustomEncoder *     st,
        const float *   pcm,
        int     frame_size,
        unsigned char *     compressed,
        int     maxCompressedBytes 
    )   
Copy the code

Encode an audio frame. Encodes a frame of audio.

• [in] st OpusCustomEncoder*: Encoder state
• [in] PCM float*: PCM audio data in floating point format, normally between +/-1.0. Sampling beyond this range is also supported, but it will be intercepted by the decoder using an integer API and can only be used if the remote side is known to support extended dynamic range. Each channel must have an accurate frame_size sample. PCM audio in float format, Samples with a normal range of +/-1.0. Samples with a range beyond +/-1.0 are supported but will be clipped by decoders using the integer API and should only be used if it is known that the far end supports extended dynamic range. There must be exactly frame_size samples per channel.
• [in] frame_size int: Number of input signal samples per frame. Number of samples per frame of input signal
• [out] compressed char *: compressed data is written here. It may not be in PCM format and must have a length of maxCompressedBytes. The compressed data is written here. This may not alias pcm and must be at least maxCompressedBytes long.
• [in] maxCompressedBytes int: The maximum number of bytes used to compress a frame (which can be changed from frame to frame). Maximum number of bytes to use for compressing the frame (can change from one frame to another) If it is negative, it is an error (see error code). It is important that this length be passed to the decoder in some way, otherwise it cannot be decoded. Number of bytes written to “compressed”. If negative, an error has occurred (see error codes). It is IMPORTANT that the length returned be somehow transmitted to the decoder. Otherwise, no decoding is possible.

OpusCustomEncoder* opus_custom_encoder_create   (   const OpusCustomMode *      mode,
        int     channels,
        int *   error 
    )
Copy the code

Create a new encoder state. Creates a new encoder state. Each data flow needs to have its own encoder state (which cannot be shared with simultaneous data flows). Each stream needs its own encoder state (can’t be shared across simultaneous streams). Parameters:

• [in] mode OpusCustomMode*: Contains all information about the characteristics of the data stream (must be the same as for the decoder). Contains all the information about the characteristics of the stream (must be the same characteristics as used for the decoder)
• [in] channels int Number of channels
• [out] error int*: Returns an error code. Returns an error code: The status of the newly created encoder is returned. Newly created encoder state.

int opus_custom_encoder_ctl     (   OpusCustomEncoder *OPUS_RESTRICT    st,
        int     request,
            ... 
    )
Copy the code

Execute a CTL function for the Opus custom encoder. Perform a CTL function on an Opus custom encoder. Typically its request and subsequent parameters are generated by a convenience macro. Generally the request and subsequent arguments are generated by a convenience macro.

See also: Encoder related CTLs

Void opus_custom_encoder_destroy (OpusCustomEncoder * st) Deconstructs an encoder state. Destroys a an encoder state.Copy the code

Parameters:

• [in] St OpusCustomEncoder*: State that needs to be freed. State to be freed.

int opus_custom_encoder_get_size    (   const OpusCustomMode *      mode,
        int     channels 
    )
Copy the code

Gets the size of the OpusCustomEncoder structure. Gets the size of an OpusCustomEncoder structure. Parameters:

• [in] mode OpusCustomMode *: Mode configuration. Mode configuration
• [in] channels int Number of Channels Returns: size. size

int opus_custom_encoder_init    (   OpusCustomEncoder *     st,
        const OpusCustomMode *      mode,
        int     channels 
    )
Copy the code

Initialize a previously allocated encoder state. The memory referred to by st must be the size returned by opus_ custom_encoder_get_size(). Instead of using the system to automatically allocate memory, the application is prepared to use its own allocator. Initializes a previously allocated encoder state The memory pointed to by st must be the size returned by opus_custom_encoder_get_size. This is intended for applications which use their own allocator instead of malloc. See also: Opus_custom_encoder_create (),opus_custom_encoder_get_size(), resets a previously initialized state, Use OPUS_RESET_STATE CTL. To reset a previously initialized state use the OPUS_RESET_STATE CTL. Parameters:

• [in] St OpusCustomEncoder*: Encoder status. Encoder state
• [in] mode OpusCustomMode *: Contains all information about the characteristics of the data stream (must be the same as for the decoder). Contains all the information about the characteristics of the stream (must be the same characteristics as used for the decoder)
• [in] channels int Number of channels returns: success, OPUS_OK, failure, error code. OPUS_OK Success or Error codes

OpusCustomMode* opus_custom_mode_create     (   opus_int32      Fs,
        int     frame_size,
        int *   error 
    )
Copy the code

Create a new schema structure. Creates a new mode struct. This pattern structure will be passed to the encoder and decoder. The schema structure must not be deconstructed until the encoder and decoder that uses it are deconstructed. This will be passed to an encoder or decoder. The mode MUST NOT BE DESTROYED until the encoders and decoders that use it are destroyed as well. Parameters:

• [IN] Fs int: Sampling rate (8000 to 96000Hz)
• [in] frame_size int: Number of samples encoded to each packet (per channel) (64-1024, factorization must include 0 or 2, 3, 5, not other prime numbers). Number of samples (per channel) to encode in each packet (64 – 1024, prime factorization must contain zero or more 2s, 3s, or 5s and no other primes)
• [out] error int*: error code returned (Null, indicating no error). Returned Error Code (if NULL, no error will be Returned) Returned: a newly created schema object. A newly created mode

void opus_custom_mode_destroy ( OpusCustomMode * mode )
Copy the code

Deconstruct a pattern structure. Destroys a mode struct this function must be called only after all encoders and decoders using this mode object have been destructed. Only call this after all encoders and decoders using this mode are destroyed as well. Parameters:

• [in] mode OpusCustomMode*: Mode structure to be released. Mode to be freed.