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_OPUS_INTERFACE_H_ 12 #define WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_ 13 14 #include <stddef.h> 15 16 #include "webrtc/typedefs.h" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 // Opaque wrapper types for the codec state. 23 typedef struct WebRtcOpusEncInst OpusEncInst; 24 typedef struct WebRtcOpusDecInst OpusDecInst; 25 26 /**************************************************************************** 27 * WebRtcOpus_EncoderCreate(...) 28 * 29 * This function create an Opus encoder. 30 * 31 * Input: 32 * - channels : number of channels. 33 * - application : 0 - VOIP applications. 34 * Favor speech intelligibility. 35 * 1 - Audio applications. 36 * Favor faithfulness to the original input. 37 * 38 * Output: 39 * - inst : a pointer to Encoder context that is created 40 * if success. 41 * 42 * Return value : 0 - Success 43 * -1 - Error 44 */ 45 int16_t WebRtcOpus_EncoderCreate(OpusEncInst** inst, 46 size_t channels, 47 int32_t application); 48 49 int16_t WebRtcOpus_EncoderFree(OpusEncInst* inst); 50 51 /**************************************************************************** 52 * WebRtcOpus_Encode(...) 53 * 54 * This function encodes audio as a series of Opus frames and inserts 55 * it into a packet. Input buffer can be any length. 56 * 57 * Input: 58 * - inst : Encoder context 59 * - audio_in : Input speech data buffer 60 * - samples : Samples per channel in audio_in 61 * - length_encoded_buffer : Output buffer size 62 * 63 * Output: 64 * - encoded : Output compressed data buffer 65 * 66 * Return value : >=0 - Length (in bytes) of coded data 67 * -1 - Error 68 */ 69 int WebRtcOpus_Encode(OpusEncInst* inst, 70 const int16_t* audio_in, 71 size_t samples, 72 size_t length_encoded_buffer, 73 uint8_t* encoded); 74 75 /**************************************************************************** 76 * WebRtcOpus_SetBitRate(...) 77 * 78 * This function adjusts the target bitrate of the encoder. 79 * 80 * Input: 81 * - inst : Encoder context 82 * - rate : New target bitrate 83 * 84 * Return value : 0 - Success 85 * -1 - Error 86 */ 87 int16_t WebRtcOpus_SetBitRate(OpusEncInst* inst, int32_t rate); 88 89 /**************************************************************************** 90 * WebRtcOpus_SetPacketLossRate(...) 91 * 92 * This function configures the encoder's expected packet loss percentage. 93 * 94 * Input: 95 * - inst : Encoder context 96 * - loss_rate : loss percentage in the range 0-100, inclusive. 97 * Return value : 0 - Success 98 * -1 - Error 99 */ 100 int16_t WebRtcOpus_SetPacketLossRate(OpusEncInst* inst, int32_t loss_rate); 101 102 /**************************************************************************** 103 * WebRtcOpus_SetMaxPlaybackRate(...) 104 * 105 * Configures the maximum playback rate for encoding. Due to hardware 106 * limitations, the receiver may render audio up to a playback rate. Opus 107 * encoder can use this information to optimize for network usage and encoding 108 * complexity. This will affect the audio bandwidth in the coded audio. However, 109 * the input/output sample rate is not affected. 110 * 111 * Input: 112 * - inst : Encoder context 113 * - frequency_hz : Maximum playback rate in Hz. 114 * This parameter can take any value. The relation 115 * between the value and the Opus internal mode is 116 * as following: 117 * frequency_hz <= 8000 narrow band 118 * 8000 < frequency_hz <= 12000 medium band 119 * 12000 < frequency_hz <= 16000 wide band 120 * 16000 < frequency_hz <= 24000 super wide band 121 * frequency_hz > 24000 full band 122 * Return value : 0 - Success 123 * -1 - Error 124 */ 125 int16_t WebRtcOpus_SetMaxPlaybackRate(OpusEncInst* inst, int32_t frequency_hz); 126 127 /* TODO(minyue): Check whether an API to check the FEC and the packet loss rate 128 * is needed. It might not be very useful since there are not many use cases and 129 * the caller can always maintain the states. */ 130 131 /**************************************************************************** 132 * WebRtcOpus_EnableFec() 133 * 134 * This function enables FEC for encoding. 135 * 136 * Input: 137 * - inst : Encoder context 138 * 139 * Return value : 0 - Success 140 * -1 - Error 141 */ 142 int16_t WebRtcOpus_EnableFec(OpusEncInst* inst); 143 144 /**************************************************************************** 145 * WebRtcOpus_DisableFec() 146 * 147 * This function disables FEC for encoding. 148 * 149 * Input: 150 * - inst : Encoder context 151 * 152 * Return value : 0 - Success 153 * -1 - Error 154 */ 155 int16_t WebRtcOpus_DisableFec(OpusEncInst* inst); 156 157 /**************************************************************************** 158 * WebRtcOpus_EnableDtx() 159 * 160 * This function enables Opus internal DTX for encoding. 161 * 162 * Input: 163 * - inst : Encoder context 164 * 165 * Return value : 0 - Success 166 * -1 - Error 167 */ 168 int16_t WebRtcOpus_EnableDtx(OpusEncInst* inst); 169 170 /**************************************************************************** 171 * WebRtcOpus_DisableDtx() 172 * 173 * This function disables Opus internal DTX for encoding. 174 * 175 * Input: 176 * - inst : Encoder context 177 * 178 * Return value : 0 - Success 179 * -1 - Error 180 */ 181 int16_t WebRtcOpus_DisableDtx(OpusEncInst* inst); 182 183 /* 184 * WebRtcOpus_SetComplexity(...) 185 * 186 * This function adjusts the computational complexity. The effect is the same as 187 * calling the complexity setting of Opus as an Opus encoder related CTL. 188 * 189 * Input: 190 * - inst : Encoder context 191 * - complexity : New target complexity (0-10, inclusive) 192 * 193 * Return value : 0 - Success 194 * -1 - Error 195 */ 196 int16_t WebRtcOpus_SetComplexity(OpusEncInst* inst, int32_t complexity); 197 198 int16_t WebRtcOpus_DecoderCreate(OpusDecInst** inst, size_t channels); 199 int16_t WebRtcOpus_DecoderFree(OpusDecInst* inst); 200 201 /**************************************************************************** 202 * WebRtcOpus_DecoderChannels(...) 203 * 204 * This function returns the number of channels created for Opus decoder. 205 */ 206 size_t WebRtcOpus_DecoderChannels(OpusDecInst* inst); 207 208 /**************************************************************************** 209 * WebRtcOpus_DecoderInit(...) 210 * 211 * This function resets state of the decoder. 212 * 213 * Input: 214 * - inst : Decoder context 215 */ 216 void WebRtcOpus_DecoderInit(OpusDecInst* inst); 217 218 /**************************************************************************** 219 * WebRtcOpus_Decode(...) 220 * 221 * This function decodes an Opus packet into one or more audio frames at the 222 * ACM interface's sampling rate (32 kHz). 223 * 224 * Input: 225 * - inst : Decoder context 226 * - encoded : Encoded data 227 * - encoded_bytes : Bytes in encoded vector 228 * 229 * Output: 230 * - decoded : The decoded vector 231 * - audio_type : 1 normal, 2 CNG (for Opus it should 232 * always return 1 since we're not using Opus's 233 * built-in DTX/CNG scheme) 234 * 235 * Return value : >0 - Samples per channel in decoded vector 236 * -1 - Error 237 */ 238 int WebRtcOpus_Decode(OpusDecInst* inst, const uint8_t* encoded, 239 size_t encoded_bytes, int16_t* decoded, 240 int16_t* audio_type); 241 242 /**************************************************************************** 243 * WebRtcOpus_DecodePlc(...) 244 * 245 * This function processes PLC for opus frame(s). 246 * Input: 247 * - inst : Decoder context 248 * - number_of_lost_frames : Number of PLC frames to produce 249 * 250 * Output: 251 * - decoded : The decoded vector 252 * 253 * Return value : >0 - number of samples in decoded PLC vector 254 * -1 - Error 255 */ 256 int WebRtcOpus_DecodePlc(OpusDecInst* inst, int16_t* decoded, 257 int number_of_lost_frames); 258 259 /**************************************************************************** 260 * WebRtcOpus_DecodeFec(...) 261 * 262 * This function decodes the FEC data from an Opus packet into one or more audio 263 * frames at the ACM interface's sampling rate (32 kHz). 264 * 265 * Input: 266 * - inst : Decoder context 267 * - encoded : Encoded data 268 * - encoded_bytes : Bytes in encoded vector 269 * 270 * Output: 271 * - decoded : The decoded vector (previous frame) 272 * 273 * Return value : >0 - Samples per channel in decoded vector 274 * 0 - No FEC data in the packet 275 * -1 - Error 276 */ 277 int WebRtcOpus_DecodeFec(OpusDecInst* inst, const uint8_t* encoded, 278 size_t encoded_bytes, int16_t* decoded, 279 int16_t* audio_type); 280 281 /**************************************************************************** 282 * WebRtcOpus_DurationEst(...) 283 * 284 * This function calculates the duration of an opus packet. 285 * Input: 286 * - inst : Decoder context 287 * - payload : Encoded data pointer 288 * - payload_length_bytes : Bytes of encoded data 289 * 290 * Return value : The duration of the packet, in samples per 291 * channel. 292 */ 293 int WebRtcOpus_DurationEst(OpusDecInst* inst, 294 const uint8_t* payload, 295 size_t payload_length_bytes); 296 297 /**************************************************************************** 298 * WebRtcOpus_PlcDuration(...) 299 * 300 * This function calculates the duration of a frame returned by packet loss 301 * concealment (PLC). 302 * 303 * Input: 304 * - inst : Decoder context 305 * 306 * Return value : The duration of a frame returned by PLC, in 307 * samples per channel. 308 */ 309 int WebRtcOpus_PlcDuration(OpusDecInst* inst); 310 311 /* TODO(minyue): Check whether it is needed to add a decoder context to the 312 * arguments, like WebRtcOpus_DurationEst(...). In fact, the packet itself tells 313 * the duration. The decoder context in WebRtcOpus_DurationEst(...) is not used. 314 * So it may be advisable to remove it from WebRtcOpus_DurationEst(...). */ 315 316 /**************************************************************************** 317 * WebRtcOpus_FecDurationEst(...) 318 * 319 * This function calculates the duration of the FEC data within an opus packet. 320 * Input: 321 * - payload : Encoded data pointer 322 * - payload_length_bytes : Bytes of encoded data 323 * 324 * Return value : >0 - The duration of the FEC data in the 325 * packet in samples per channel. 326 * 0 - No FEC data in the packet. 327 */ 328 int WebRtcOpus_FecDurationEst(const uint8_t* payload, 329 size_t payload_length_bytes); 330 331 /**************************************************************************** 332 * WebRtcOpus_PacketHasFec(...) 333 * 334 * This function detects if an opus packet has FEC. 335 * Input: 336 * - payload : Encoded data pointer 337 * - payload_length_bytes : Bytes of encoded data 338 * 339 * Return value : 0 - the packet does NOT contain FEC. 340 * 1 - the packet contains FEC. 341 */ 342 int WebRtcOpus_PacketHasFec(const uint8_t* payload, 343 size_t payload_length_bytes); 344 345 #ifdef __cplusplus 346 } // extern "C" 347 #endif 348 349 #endif // WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_ 350