Google Git Google Git
Sign in
webrtc/src//dafde4b473e8625209a25705ece2dfd55863be7a/./modules/audio_coding/codecs/opus/opus_interface.h
blob: 4fb1dff233784bf4f8558b21b0631ad949ecc0ef [file]
/*
* Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
*
* Use of this source code is governed by a BSD-style license
* that can be found in the LICENSE file in the root of the source
* tree. An additional intellectual property rights grant can be found
* in the file PATENTS. All contributing project authors may
* be found in the AUTHORS file in the root of the source tree.
*/
#ifndef MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_
#define MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_
#include <stddef.h>
#include <stdint.h>
#include "modules/audio_coding/codecs/opus/opus_inst.h" // IWYU pragma: export
#ifdef __cplusplus
extern "C" {
#endif
// Opaque wrapper types for the codec state.
typedef struct WebRtcOpusEncInst OpusEncInst;
typedef struct WebRtcOpusDecInst OpusDecInst;
/****************************************************************************
* WebRtcOpus_EncoderCreate(...)
*
* This function creates an Opus encoder that encodes mono or stereo.
*
* Input:
* - channels : number of channels; 1 or 2.
* - application : 0 - VOIP applications.
* Favor speech intelligibility.
* 1 - Audio applications.
* Favor faithfulness to the original input.
* - sample_rate_hz : sample rate of input audio
*
* Output:
* - inst : a pointer to Encoder context that is created
* if success.
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_EncoderCreate(OpusEncInst** inst,
size_t channels,
int32_t application,
int sample_rate_hz);
/****************************************************************************
* WebRtcOpus_MultistreamEncoderCreate(...)
*
* This function creates an Opus encoder with any supported channel count.
*
* Input:
* - channels : number of channels in the input of the encoder.
* - application : 0 - VOIP applications.
* Favor speech intelligibility.
* 1 - Audio applications.
* Favor faithfulness to the original input.
* - streams : number of streams, as described in RFC 7845.
* - coupled_streams : number of coupled streams, as described in
* RFC 7845.
* - channel_mapping : the channel mapping; pointer to array of
* `channel` bytes, as described in RFC 7845.
*
* Output:
* - inst : a pointer to Encoder context that is created
* if success.
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_MultistreamEncoderCreate(
OpusEncInst** inst,
size_t channels,
int32_t application,
size_t streams,
size_t coupled_streams,
const unsigned char* channel_mapping);
int16_t WebRtcOpus_EncoderFree(OpusEncInst* inst);
/****************************************************************************
* WebRtcOpus_Encode(...)
*
* This function encodes audio as a series of Opus frames and inserts
* it into a packet. Input buffer can be any length.
*
* Input:
* - inst : Encoder context
* - audio_in : Input speech data buffer
* - samples : Samples per channel in audio_in
* - length_encoded_buffer : Output buffer size
*
* Output:
* - encoded : Output compressed data buffer
*
* Return value : >=0 - Length (in bytes) of coded data
* -1 - Error
*/
int WebRtcOpus_Encode(OpusEncInst* inst,
const int16_t* audio_in,
size_t samples,
size_t length_encoded_buffer,
uint8_t* encoded);
/****************************************************************************
* WebRtcOpus_SetBitRate(...)
*
* This function adjusts the target bitrate of the encoder.
*
* Input:
* - inst : Encoder context
* - rate : New target bitrate
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_SetBitRate(OpusEncInst* inst, int32_t rate);
/****************************************************************************
* WebRtcOpus_SetPacketLossRate(...)
*
* This function configures the encoder's expected packet loss percentage.
*
* Input:
* - inst : Encoder context
* - loss_rate : loss percentage in the range 0-100, inclusive.
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_SetPacketLossRate(OpusEncInst* inst, int32_t loss_rate);
/****************************************************************************
* WebRtcOpus_SetMaxPlaybackRate(...)
*
* Configures the maximum playback rate for encoding. Due to hardware
* limitations, the receiver may render audio up to a playback rate. Opus
* encoder can use this information to optimize for network usage and encoding
* complexity. This will affect the audio bandwidth in the coded audio. However,
* the input/output sample rate is not affected.
*
* Input:
* - inst : Encoder context
* - frequency_hz : Maximum playback rate in Hz.
* This parameter can take any value. The relation
* between the value and the Opus internal mode is
* as following:
* frequency_hz <= 8000 narrow band
* 8000 < frequency_hz <= 12000 medium band
* 12000 < frequency_hz <= 16000 wide band
* 16000 < frequency_hz <= 24000 super wide band
* frequency_hz > 24000 full band
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_SetMaxPlaybackRate(OpusEncInst* inst, int32_t frequency_hz);
/****************************************************************************
* WebRtcOpus_GetMaxPlaybackRate(...)
*
* Queries the maximum playback rate for encoding. If different single-stream
* encoders have different maximum playback rates, this function fails.
*
* Input:
* - inst : Encoder context.
* Output:
* - result_hz : The maximum playback rate in Hz.
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_GetMaxPlaybackRate(OpusEncInst* const inst,
int32_t* result_hz);
/* TODO(minyue): Check whether an API to check the FEC and the packet loss rate
* is needed. It might not be very useful since there are not many use cases and
* the caller can always maintain the states. */
/****************************************************************************
* WebRtcOpus_EnableFec()
*
* This function enables FEC for encoding.
*
* Input:
* - inst : Encoder context
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_EnableFec(OpusEncInst* inst);
/****************************************************************************
* WebRtcOpus_DisableFec()
*
* This function disables FEC for encoding.
*
* Input:
* - inst : Encoder context
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_DisableFec(OpusEncInst* inst);
/****************************************************************************
* WebRtcOpus_EnableDtx()
*
* This function enables Opus internal DTX for encoding.
*
* Input:
* - inst : Encoder context
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_EnableDtx(OpusEncInst* inst);
/****************************************************************************
* WebRtcOpus_DisableDtx()
*
* This function disables Opus internal DTX for encoding.
*
* Input:
* - inst : Encoder context
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_DisableDtx(OpusEncInst* inst);
/****************************************************************************
* WebRtcOpus_GetUseDtx()
*
* This function gets the DTX configuration used for encoding.
*
* Input:
* - inst : Encoder context
*
* Return value : 0 - Encoder does not use DTX.
* 1 - Encoder uses DTX.
* -1 - Error.
*/
int16_t WebRtcOpus_GetUseDtx(OpusEncInst* inst);
/****************************************************************************
* WebRtcOpus_GetUseDtx()
*
* This function gets if the encoder is in DTX.
*
* Input:
* - inst : Encoder context
*
* Return value : 0 - Encoder is not DTX.
* 1 - Encoder is in DTX.
* -1 - Error.
*/
int16_t WebRtcOpus_GetInDtx(OpusEncInst* inst);
/****************************************************************************
* WebRtcOpus_EnableCbr()
*
* This function enables CBR for encoding.
*
* Input:
* - inst : Encoder context
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_EnableCbr(OpusEncInst* inst);
/****************************************************************************
* WebRtcOpus_DisableCbr()
*
* This function disables CBR for encoding.
*
* Input:
* - inst : Encoder context
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_DisableCbr(OpusEncInst* inst);
/*
* WebRtcOpus_SetComplexity(...)
*
* This function adjusts the computational complexity. The effect is the same as
* calling the complexity setting of Opus as an Opus encoder related CTL.
*
* Input:
* - inst : Encoder context
* - complexity : New target complexity (0-10, inclusive)
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_SetComplexity(OpusEncInst* inst, int32_t complexity);
/*
* WebRtcOpus_GetBandwidth(...)
*
* This function returns the current bandwidth.
*
* Input:
* - inst : Encoder context
*
* Return value : Bandwidth - Success
* -1 - Error
*/
int32_t WebRtcOpus_GetBandwidth(OpusEncInst* inst);
/*
* WebRtcOpus_SetBandwidth(...)
*
* By default Opus decides which bandwidth to encode the signal in depending on
* the the bitrate. This function overrules the previous setting and forces the
* encoder to encode in narrowband/wideband/fullband/etc.
*
* Input:
* - inst : Encoder context
* - bandwidth : New target bandwidth. Valid values are:
* OPUS_BANDWIDTH_NARROWBAND
* OPUS_BANDWIDTH_MEDIUMBAND
* OPUS_BANDWIDTH_WIDEBAND
* OPUS_BANDWIDTH_SUPERWIDEBAND
* OPUS_BANDWIDTH_FULLBAND
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_SetBandwidth(OpusEncInst* inst, int32_t bandwidth);
/*
* WebRtcOpus_SetForceChannels(...)
*
* If the encoder is initialized as a stereo encoder, Opus will by default
* decide whether to encode in mono or stereo based on the bitrate. This
* function overrules the previous setting, and forces the encoder to encode
* in auto/mono/stereo.
*
* If the Encoder is initialized as a mono encoder, and one tries to force
* stereo, the function will return an error.
*
* Input:
* - inst : Encoder context
* - num_channels : 0 - Not forced
* 1 - Mono
* 2 - Stereo
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_SetForceChannels(OpusEncInst* inst, size_t num_channels);
int16_t WebRtcOpus_DecoderCreate(OpusDecInst** inst,
size_t channels,
int sample_rate_hz);
/****************************************************************************
* WebRtcOpus_MultistreamDecoderCreate(...)
*
* This function creates an Opus decoder with any supported channel count.
*
* Input:
* - channels : number of output channels that the decoder
* will produce.
* - streams : number of encoded streams, as described in
* RFC 7845.
* - coupled_streams : number of coupled streams, as described in
* RFC 7845.
* - channel_mapping : the channel mapping; pointer to array of
* `channel` bytes, as described in RFC 7845.
*
* Output:
* - inst : a pointer to a Decoder context that is created
* if success.
*
* Return value : 0 - Success
* -1 - Error
*/
int16_t WebRtcOpus_MultistreamDecoderCreate(
OpusDecInst** inst,
size_t channels,
size_t streams,
size_t coupled_streams,
const unsigned char* channel_mapping);
int16_t WebRtcOpus_DecoderFree(OpusDecInst* inst);
/****************************************************************************
* WebRtcOpus_DecoderChannels(...)
*
* This function returns the number of channels created for Opus decoder.
*/
size_t WebRtcOpus_DecoderChannels(OpusDecInst* inst);
/****************************************************************************
* WebRtcOpus_DecoderInit(...)
*
* This function resets state of the decoder.
*
* Input:
* - inst : Decoder context
*/
void WebRtcOpus_DecoderInit(OpusDecInst* inst);
/****************************************************************************
* WebRtcOpus_Decode(...)
*
* This function decodes an Opus packet into one or more audio frames at the
* ACM interface's sampling rate (32 kHz).
*
* Input:
* - inst : Decoder context
* - encoded : Encoded data
* - encoded_bytes : Bytes in encoded vector
*
* Output:
* - decoded : The decoded vector
* - audio_type : 1 normal, 2 CNG
*
* Return value : >0 - Samples per channel in decoded vector
* -1 - Error
*/
int WebRtcOpus_Decode(OpusDecInst* inst,
const uint8_t* encoded,
size_t encoded_bytes,
int16_t* decoded,
int16_t* audio_type);
/****************************************************************************
* WebRtcOpus_DecodeFec(...)
*
* This function decodes the FEC data from an Opus packet into one or more audio
* frames at the ACM interface's sampling rate (32 kHz).
*
* Input:
* - inst : Decoder context
* - encoded : Encoded data
* - encoded_bytes : Bytes in encoded vector
*
* Output:
* - decoded : The decoded vector (previous frame)
*
* Return value : >0 - Samples per channel in decoded vector
* 0 - No FEC data in the packet
* -1 - Error
*/
int WebRtcOpus_DecodeFec(OpusDecInst* inst,
const uint8_t* encoded,
size_t encoded_bytes,
int16_t* decoded,
int16_t* audio_type);
/****************************************************************************
* WebRtcOpus_DurationEst(...)
*
* This function calculates the duration of an opus packet.
* Input:
* - inst : Decoder context
* - payload : Encoded data pointer
* - payload_length_bytes : Bytes of encoded data
*
* Return value : The duration of the packet, in samples per
* channel.
*/
int WebRtcOpus_DurationEst(OpusDecInst* inst,
const uint8_t* payload,
size_t payload_length_bytes);
/****************************************************************************
* WebRtcOpus_PlcDuration(...)
*
* This function calculates the duration of a frame returned by packet loss
* concealment (PLC).
*
* Input:
* - inst : Decoder context
*
* Return value : The duration of a frame returned by PLC, in
* samples per channel.
*/
int WebRtcOpus_PlcDuration(OpusDecInst* inst);
/* TODO(minyue): Check whether it is needed to add a decoder context to the
* arguments, like WebRtcOpus_DurationEst(...). In fact, the packet itself tells
* the duration. The decoder context in WebRtcOpus_DurationEst(...) is not used.
* So it may be advisable to remove it from WebRtcOpus_DurationEst(...). */
/****************************************************************************
* WebRtcOpus_FecDurationEst(...)
*
* This function calculates the duration of the FEC data within an opus packet.
* Input:
* - payload : Encoded data pointer
* - payload_length_bytes : Bytes of encoded data
* - sample_rate_hz : Sample rate of output audio
*
* Return value : >0 - The duration of the FEC data in the
* packet in samples per channel.
* 0 - No FEC data in the packet.
*/
int WebRtcOpus_FecDurationEst(const uint8_t* payload,
size_t payload_length_bytes,
int sample_rate_hz);
/****************************************************************************
* WebRtcOpus_PacketHasFec(...)
*
* This function detects if an opus packet has FEC.
* Input:
* - payload : Encoded data pointer
* - payload_length_bytes : Bytes of encoded data
*
* Return value : 0 - the packet does NOT contain FEC.
* 1 - the packet contains FEC.
*/
int WebRtcOpus_PacketHasFec(const uint8_t* payload,
size_t payload_length_bytes);
/****************************************************************************
* WebRtcOpus_PacketHasVoiceActivity(...)
*
* This function returns the SILK VAD information encoded in the opus packet.
* For CELT-only packets that do not have VAD information, it returns -1.
* Input:
* - payload : Encoded data pointer
* - payload_length_bytes : Bytes of encoded data
*
* Return value : 0 - no frame had the VAD flag set.
* 1 - at least one frame had the VAD flag set.
* -1 - VAD status could not be determined.
*/
int WebRtcOpus_PacketHasVoiceActivity(const uint8_t* payload,
size_t payload_length_bytes);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_