OPUS:IETF Low-Latency audio codec: API and Operating manual

https://www.zybuluo.com/khan-lau/note/383775
about Opus

The Opus codec is a specially designed interactive voice and audio transmission for the Internet. It was designed by the IETF's codec workgroup, merging Skype's silk and xiph. ORG's Celt technology.
The Opus codec is designed to handle a wide range of interactive audio applications, including voice over IP, video, in-game chats, and even remote live music performances. It can be applied from low-bitrate narrowband voice to very high-quality stereo music. Its main features are:
• Sample rate from 8 to + kHz
• Bit rates from 6kb/s to 510kb/s
• Support for fixed bit rate (CBR) and variable bitrate (VBR)
• Audio bandwidth from narrowband to broadband
• Support for voice and music
• Mono and stereo support
• Multi-channel support (up to 255 channels)
• Frame sizes from 2.5 ms to 60 MS
• Good loss robustness and packet loss concealment (PLC) (Note: It is not easy to find out if the packet is lost)
• Floating-point and fixed-point execution

Documentation includes:
opus Encoder
opus Decoder
Repacketizer
opus Multistream API
Opus Library information functions
opus Custom Opus Encoder

This section describes the process and functions of the Opus Encoder Opusencoder.
　　 type definition

   
   
    
    typedef struct OPUSENCODER Opusencoder//opus encoder state.
   
   

function

Functions
Int	Opus_encoder_get_size (int channels) Get the size of the opusencoder structure-
Opusencoder *	Opus_encoder_create (opus_int32 Fs, int channels, int application, int *error) Allocates and initializes the encoder state.
Int	Opus_encoder_init (Opusencoder *st, opus_int32 Fs, int channels, int application) Initializes a previously assigned encoder state. The memory that is pointing to Saint 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) Encodes 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 the floating point input.
void	Opus_encoder_destroy (Opusencoder *st) Releases a Opusencoder object that is assigned according to Opus_encoder_create ().
Int	Opus_encoder_ctl (opusencoder *st, int request,...) Executes a CTL function to an Opus encoder.

Detailed Description

This section describes the procedures and functions used to encode opus.
Since Opus is a stateful codec, the encoding process starts with creating an encoder state, which is done in the following ways:

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

From this point, the enc can be used to encode the audio stream. An encoder state must not be used at the same time for more than one audio stream. Similarly, the encoder state cannot be reinitialized for each frame.
When Opus_encoder_create () allocates memory for a state, it can also initialize pre-allocated memory:

   
   
    
    int size;
    
    int error;
    
    Opusencoder *enc;
    
    Size = opus_encoder_get_size (channels);
    
    ENC = malloc (size);
    
    Error = Opus_encoder_init (enc, Fs, channels, application);
   
   

Opus_encoder_get_size () returns the size of the encoder status requirement. Note that future versions of this code may change size, so no assuptions should be made for it.
The encoder state is always contiguous in memory, and copying it as long as a shallow copy is sufficient.
Use the Opus_encoder_ctl () interface to change some of the encoder's parameter settings. All of these parameters already have default values, so change them only when necessary. The most common parameter setting modifications 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));
   
   

Over here:
bitrate (bit rate) unit is bit/sec (b/s)
complexity (complexity) is a value from 1 to 10, 1 lowest, 10 highest, and the larger the value the more complex
Signal_type (type of signal) includes Opus_auto (default), Opus_signal_voice, or Opus_signal_music.

See Encoder related CTLs and Generic CTLs You can get a detailed list of parameters that can be set and queried. In an audio streaming process, most parameters can be set or modified.
In order to encode a frame, the Opus_encode () or opus_encode_float () function must be called correctly with the frame of the audio data (2.5, 5, 10, 20, 40, or 60 milliseconds).

   
   
    
    Len = Opus_encode (enc, audio_frame, frame_size, Packet, max_packet);
   
   

Over here:
Audio_frame (audio frame) is the audio data in opus_int16 (or floating point for opus_encode_float ()) format
frame_size (frame size) is the maximum number of frames in a sample (per channel)
Packet (package) is a byte array 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 bitrate of VBR, but should 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 a negative number, which indicates that an error has occurred. If the return value is 1 bytes, then the packet does not need to propagate (DTX).
Once an encoder state is no longer needed, it can be deconstructed in the following ways:

   
   
    
    Opus_encoder_destroy (ENC);
   
   

If the encoder is created with Opus_encoder_init () instead of using the opus_encoder_create () function, then there is no need to take action to require separation from the potential release of the memory allocated to it manually (the above example is called free (ENC)).
　　 type definition Document