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 /* 199 * WebRtcOpus_SetForceChannels(...) 200 * 201 * If the encoder is initialized as a stereo encoder, Opus will by default 202 * decide whether to encode in mono or stereo based on the bitrate. This 203 * function overrules the previous setting, and forces the encoder to encode 204 * in auto/mono/stereo. 205 * 206 * If the Encoder is initialized as a mono encoder, and one tries to force 207 * stereo, the function will return an error. 208 * 209 * Input: 210 * - inst : Encoder context 211 * - num_channels : 0 - Not forced 212 * 1 - Mono 213 * 2 - Stereo 214 * 215 * Return value : 0 - Success 216 * -1 - Error 217 */ 218 int16_t WebRtcOpus_SetForceChannels(OpusEncInst* inst, size_t num_channels); 219 220 int16_t WebRtcOpus_DecoderCreate(OpusDecInst** inst, size_t channels); 221 int16_t WebRtcOpus_DecoderFree(OpusDecInst* inst); 222 223 /**************************************************************************** 224 * WebRtcOpus_DecoderChannels(...) 225 * 226 * This function returns the number of channels created for Opus decoder. 227 */ 228 size_t WebRtcOpus_DecoderChannels(OpusDecInst* inst); 229 230 /**************************************************************************** 231 * WebRtcOpus_DecoderInit(...) 232 * 233 * This function resets state of the decoder. 234 * 235 * Input: 236 * - inst : Decoder context 237 */ 238 void WebRtcOpus_DecoderInit(OpusDecInst* inst); 239 240 /**************************************************************************** 241 * WebRtcOpus_Decode(...) 242 * 243 * This function decodes an Opus packet into one or more audio frames at the 244 * ACM interface's sampling rate (32 kHz). 245 * 246 * Input: 247 * - inst : Decoder context 248 * - encoded : Encoded data 249 * - encoded_bytes : Bytes in encoded vector 250 * 251 * Output: 252 * - decoded : The decoded vector 253 * - audio_type : 1 normal, 2 CNG (for Opus it should 254 * always return 1 since we're not using Opus's 255 * built-in DTX/CNG scheme) 256 * 257 * Return value : >0 - Samples per channel in decoded vector 258 * -1 - Error 259 */ 260 int WebRtcOpus_Decode(OpusDecInst* inst, const uint8_t* encoded, 261 size_t encoded_bytes, int16_t* decoded, 262 int16_t* audio_type); 263 264 /**************************************************************************** 265 * WebRtcOpus_DecodePlc(...) 266 * 267 * This function processes PLC for opus frame(s). 268 * Input: 269 * - inst : Decoder context 270 * - number_of_lost_frames : Number of PLC frames to produce 271 * 272 * Output: 273 * - decoded : The decoded vector 274 * 275 * Return value : >0 - number of samples in decoded PLC vector 276 * -1 - Error 277 */ 278 int WebRtcOpus_DecodePlc(OpusDecInst* inst, int16_t* decoded, 279 int number_of_lost_frames); 280 281 /**************************************************************************** 282 * WebRtcOpus_DecodeFec(...) 283 * 284 * This function decodes the FEC data from an Opus packet into one or more audio 285 * frames at the ACM interface's sampling rate (32 kHz). 286 * 287 * Input: 288 * - inst : Decoder context 289 * - encoded : Encoded data 290 * - encoded_bytes : Bytes in encoded vector 291 * 292 * Output: 293 * - decoded : The decoded vector (previous frame) 294 * 295 * Return value : >0 - Samples per channel in decoded vector 296 * 0 - No FEC data in the packet 297 * -1 - Error 298 */ 299 int WebRtcOpus_DecodeFec(OpusDecInst* inst, const uint8_t* encoded, 300 size_t encoded_bytes, int16_t* decoded, 301 int16_t* audio_type); 302 303 /**************************************************************************** 304 * WebRtcOpus_DurationEst(...) 305 * 306 * This function calculates the duration of an opus packet. 307 * Input: 308 * - inst : Decoder context 309 * - payload : Encoded data pointer 310 * - payload_length_bytes : Bytes of encoded data 311 * 312 * Return value : The duration of the packet, in samples per 313 * channel. 314 */ 315 int WebRtcOpus_DurationEst(OpusDecInst* inst, 316 const uint8_t* payload, 317 size_t payload_length_bytes); 318 319 /**************************************************************************** 320 * WebRtcOpus_PlcDuration(...) 321 * 322 * This function calculates the duration of a frame returned by packet loss 323 * concealment (PLC). 324 * 325 * Input: 326 * - inst : Decoder context 327 * 328 * Return value : The duration of a frame returned by PLC, in 329 * samples per channel. 330 */ 331 int WebRtcOpus_PlcDuration(OpusDecInst* inst); 332 333 /* TODO(minyue): Check whether it is needed to add a decoder context to the 334 * arguments, like WebRtcOpus_DurationEst(...). In fact, the packet itself tells 335 * the duration. The decoder context in WebRtcOpus_DurationEst(...) is not used. 336 * So it may be advisable to remove it from WebRtcOpus_DurationEst(...). */ 337 338 /**************************************************************************** 339 * WebRtcOpus_FecDurationEst(...) 340 * 341 * This function calculates the duration of the FEC data within an opus packet. 342 * Input: 343 * - payload : Encoded data pointer 344 * - payload_length_bytes : Bytes of encoded data 345 * 346 * Return value : >0 - The duration of the FEC data in the 347 * packet in samples per channel. 348 * 0 - No FEC data in the packet. 349 */ 350 int WebRtcOpus_FecDurationEst(const uint8_t* payload, 351 size_t payload_length_bytes); 352 353 /**************************************************************************** 354 * WebRtcOpus_PacketHasFec(...) 355 * 356 * This function detects if an opus packet has FEC. 357 * Input: 358 * - payload : Encoded data pointer 359 * - payload_length_bytes : Bytes of encoded data 360 * 361 * Return value : 0 - the packet does NOT contain FEC. 362 * 1 - the packet contains FEC. 363 */ 364 int WebRtcOpus_PacketHasFec(const uint8_t* payload, 365 size_t payload_length_bytes); 366 367 #ifdef __cplusplus 368 } // extern "C" 369 #endif 370 371 #endif // WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_ 372