1 /* 2 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_INTERFACE_OPUS_INTERFACE_H_ 12 #define WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_INTERFACE_OPUS_INTERFACE_H_ 13 14 #include "webrtc/typedefs.h" 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 // Opaque wrapper types for the codec state. 21 typedef struct WebRtcOpusEncInst OpusEncInst; 22 typedef struct WebRtcOpusDecInst OpusDecInst; 23 24 int16_t WebRtcOpus_EncoderCreate(OpusEncInst** inst, int32_t channels); 25 int16_t WebRtcOpus_EncoderFree(OpusEncInst* inst); 26 27 /**************************************************************************** 28 * WebRtcOpus_Encode(...) 29 * 30 * This function encodes audio as a series of Opus frames and inserts 31 * it into a packet. Input buffer can be any length. 32 * 33 * Input: 34 * - inst : Encoder context 35 * - audio_in : Input speech data buffer 36 * - samples : Samples per channel in audio_in 37 * - length_encoded_buffer : Output buffer size 38 * 39 * Output: 40 * - encoded : Output compressed data buffer 41 * 42 * Return value : >0 - Length (in bytes) of coded data 43 * -1 - Error 44 */ 45 int16_t WebRtcOpus_Encode(OpusEncInst* inst, int16_t* audio_in, int16_t samples, 46 int16_t length_encoded_buffer, uint8_t* encoded); 47 48 /**************************************************************************** 49 * WebRtcOpus_SetBitRate(...) 50 * 51 * This function adjusts the target bitrate of the encoder. 52 * 53 * Input: 54 * - inst : Encoder context 55 * - rate : New target bitrate 56 * 57 * Return value : 0 - Success 58 * -1 - Error 59 */ 60 int16_t WebRtcOpus_SetBitRate(OpusEncInst* inst, int32_t rate); 61 62 /**************************************************************************** 63 * WebRtcOpus_SetPacketLossRate(...) 64 * 65 * This function configures the encoder's expected packet loss percentage. 66 * 67 * Input: 68 * - inst : Encoder context 69 * - loss_rate : loss percentage in the range 0-100, inclusive. 70 * Return value : 0 - Success 71 * -1 - Error 72 */ 73 int16_t WebRtcOpus_SetPacketLossRate(OpusEncInst* inst, int32_t loss_rate); 74 75 /* TODO(minyue): Check whether an API to check the FEC and the packet loss rate 76 * is needed. It might not be very useful since there are not many use cases and 77 * the caller can always maintain the states. */ 78 79 /**************************************************************************** 80 * WebRtcOpus_EnableFec() 81 * 82 * This function enables FEC for encoding. 83 * 84 * Input: 85 * - inst : Encoder context 86 * 87 * Return value : 0 - Success 88 * -1 - Error 89 */ 90 int16_t WebRtcOpus_EnableFec(OpusEncInst* inst); 91 92 /**************************************************************************** 93 * WebRtcOpus_DisableFec() 94 * 95 * This function disables FEC for encoding. 96 * 97 * Input: 98 * - inst : Encoder context 99 * 100 * Return value : 0 - Success 101 * -1 - Error 102 */ 103 int16_t WebRtcOpus_DisableFec(OpusEncInst* inst); 104 105 /* 106 * WebRtcOpus_SetComplexity(...) 107 * 108 * This function adjusts the computational complexity. The effect is the same as 109 * calling the complexity setting of Opus as an Opus encoder related CTL. 110 * 111 * Input: 112 * - inst : Encoder context 113 * - complexity : New target complexity (0-10, inclusive) 114 * 115 * Return value : 0 - Success 116 * -1 - Error 117 */ 118 int16_t WebRtcOpus_SetComplexity(OpusEncInst* inst, int32_t complexity); 119 120 int16_t WebRtcOpus_DecoderCreate(OpusDecInst** inst, int channels); 121 int16_t WebRtcOpus_DecoderFree(OpusDecInst* inst); 122 123 /**************************************************************************** 124 * WebRtcOpus_DecoderChannels(...) 125 * 126 * This function returns the number of channels created for Opus decoder. 127 */ 128 int WebRtcOpus_DecoderChannels(OpusDecInst* inst); 129 130 /**************************************************************************** 131 * WebRtcOpus_DecoderInit(...) 132 * 133 * This function resets state of the decoder. 134 * 135 * Input: 136 * - inst : Decoder context 137 * 138 * Return value : 0 - Success 139 * -1 - Error 140 */ 141 int16_t WebRtcOpus_DecoderInitNew(OpusDecInst* inst); 142 int16_t WebRtcOpus_DecoderInit(OpusDecInst* inst); 143 int16_t WebRtcOpus_DecoderInitSlave(OpusDecInst* inst); 144 145 /**************************************************************************** 146 * WebRtcOpus_Decode(...) 147 * 148 * This function decodes an Opus packet into one or more audio frames at the 149 * ACM interface's sampling rate (32 kHz). 150 * 151 * Input: 152 * - inst : Decoder context 153 * - encoded : Encoded data 154 * - encoded_bytes : Bytes in encoded vector 155 * 156 * Output: 157 * - decoded : The decoded vector 158 * - audio_type : 1 normal, 2 CNG (for Opus it should 159 * always return 1 since we're not using Opus's 160 * built-in DTX/CNG scheme) 161 * 162 * Return value : >0 - Samples per channel in decoded vector 163 * -1 - Error 164 */ 165 int16_t WebRtcOpus_DecodeNew(OpusDecInst* inst, const uint8_t* encoded, 166 int16_t encoded_bytes, int16_t* decoded, 167 int16_t* audio_type); 168 int16_t WebRtcOpus_Decode(OpusDecInst* inst, const int16_t* encoded, 169 int16_t encoded_bytes, int16_t* decoded, 170 int16_t* audio_type); 171 int16_t WebRtcOpus_DecodeSlave(OpusDecInst* inst, const int16_t* encoded, 172 int16_t encoded_bytes, int16_t* decoded, 173 int16_t* audio_type); 174 175 /**************************************************************************** 176 * WebRtcOpus_DecodePlc(...) 177 * TODO(tlegrand): Remove master and slave functions when NetEq4 is in place. 178 * WebRtcOpus_DecodePlcMaster(...) 179 * WebRtcOpus_DecodePlcSlave(...) 180 * 181 * This function processes PLC for opus frame(s). 182 * Input: 183 * - inst : Decoder context 184 * - number_of_lost_frames : Number of PLC frames to produce 185 * 186 * Output: 187 * - decoded : The decoded vector 188 * 189 * Return value : >0 - number of samples in decoded PLC vector 190 * -1 - Error 191 */ 192 int16_t WebRtcOpus_DecodePlc(OpusDecInst* inst, int16_t* decoded, 193 int16_t number_of_lost_frames); 194 int16_t WebRtcOpus_DecodePlcMaster(OpusDecInst* inst, int16_t* decoded, 195 int16_t number_of_lost_frames); 196 int16_t WebRtcOpus_DecodePlcSlave(OpusDecInst* inst, int16_t* decoded, 197 int16_t number_of_lost_frames); 198 199 /**************************************************************************** 200 * WebRtcOpus_DecodeFec(...) 201 * 202 * This function decodes the FEC data from an Opus packet into one or more audio 203 * frames at the ACM interface's sampling rate (32 kHz). 204 * 205 * Input: 206 * - inst : Decoder context 207 * - encoded : Encoded data 208 * - encoded_bytes : Bytes in encoded vector 209 * 210 * Output: 211 * - decoded : The decoded vector (previous frame) 212 * 213 * Return value : >0 - Samples per channel in decoded vector 214 * 0 - No FEC data in the packet 215 * -1 - Error 216 */ 217 int16_t WebRtcOpus_DecodeFec(OpusDecInst* inst, const uint8_t* encoded, 218 int16_t encoded_bytes, int16_t* decoded, 219 int16_t* audio_type); 220 221 /**************************************************************************** 222 * WebRtcOpus_DurationEst(...) 223 * 224 * This function calculates the duration of an opus packet. 225 * Input: 226 * - inst : Decoder context 227 * - payload : Encoded data pointer 228 * - payload_length_bytes : Bytes of encoded data 229 * 230 * Return value : The duration of the packet, in samples. 231 */ 232 int WebRtcOpus_DurationEst(OpusDecInst* inst, 233 const uint8_t* payload, 234 int payload_length_bytes); 235 236 /* TODO(minyue): Check whether it is needed to add a decoder context to the 237 * arguments, like WebRtcOpus_DurationEst(...). In fact, the packet itself tells 238 * the duration. The decoder context in WebRtcOpus_DurationEst(...) is not used. 239 * So it may be advisable to remove it from WebRtcOpus_DurationEst(...). */ 240 241 /**************************************************************************** 242 * WebRtcOpus_FecDurationEst(...) 243 * 244 * This function calculates the duration of the FEC data within an opus packet. 245 * Input: 246 * - payload : Encoded data pointer 247 * - payload_length_bytes : Bytes of encoded data 248 * 249 * Return value : >0 - The duration of the FEC data in the 250 * packet in samples. 251 * 0 - No FEC data in the packet. 252 */ 253 int WebRtcOpus_FecDurationEst(const uint8_t* payload, 254 int payload_length_bytes); 255 256 /**************************************************************************** 257 * WebRtcOpus_PacketHasFec(...) 258 * 259 * This function detects if an opus packet has FEC. 260 * Input: 261 * - payload : Encoded data pointer 262 * - payload_length_bytes : Bytes of encoded data 263 * 264 * Return value : 0 - the packet does NOT contain FEC. 265 * 1 - the packet contains FEC. 266 */ 267 int WebRtcOpus_PacketHasFec(const uint8_t* payload, 268 int payload_length_bytes); 269 270 #ifdef __cplusplus 271 } // extern "C" 272 #endif 273 274 #endif // WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_INTERFACE_OPUS_INTERFACE_H_ 275