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 MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_ 12 #define MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_ 13 14 #include <stddef.h> 15 #include <stdint.h> 16 17 #include "modules/audio_coding/codecs/opus/opus_inst.h" 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 // Opaque wrapper types for the codec state. 24 typedef struct WebRtcOpusEncInst OpusEncInst; 25 typedef struct WebRtcOpusDecInst OpusDecInst; 26 27 /**************************************************************************** 28 * WebRtcOpus_EncoderCreate(...) 29 * 30 * This function creates an Opus encoder that encodes mono or stereo. 31 * 32 * Input: 33 * - channels : number of channels; 1 or 2. 34 * - application : 0 - VOIP applications. 35 * Favor speech intelligibility. 36 * 1 - Audio applications. 37 * Favor faithfulness to the original input. 38 * - sample_rate_hz : sample rate of input audio 39 * 40 * Output: 41 * - inst : a pointer to Encoder context that is created 42 * if success. 43 * 44 * Return value : 0 - Success 45 * -1 - Error 46 */ 47 int16_t WebRtcOpus_EncoderCreate(OpusEncInst** inst, 48 size_t channels, 49 int32_t application, 50 int sample_rate_hz); 51 52 /**************************************************************************** 53 * WebRtcOpus_MultistreamEncoderCreate(...) 54 * 55 * This function creates an Opus encoder with any supported channel count. 56 * 57 * Input: 58 * - channels : number of channels in the input of the encoder. 59 * - application : 0 - VOIP applications. 60 * Favor speech intelligibility. 61 * 1 - Audio applications. 62 * Favor faithfulness to the original input. 63 * - streams : number of streams, as described in RFC 7845. 64 * - coupled_streams : number of coupled streams, as described in 65 * RFC 7845. 66 * - channel_mapping : the channel mapping; pointer to array of 67 * `channel` bytes, as described in RFC 7845. 68 * 69 * Output: 70 * - inst : a pointer to Encoder context that is created 71 * if success. 72 * 73 * Return value : 0 - Success 74 * -1 - Error 75 */ 76 int16_t WebRtcOpus_MultistreamEncoderCreate( 77 OpusEncInst** inst, 78 size_t channels, 79 int32_t application, 80 size_t streams, 81 size_t coupled_streams, 82 const unsigned char* channel_mapping); 83 84 int16_t WebRtcOpus_EncoderFree(OpusEncInst* inst); 85 86 /**************************************************************************** 87 * WebRtcOpus_Encode(...) 88 * 89 * This function encodes audio as a series of Opus frames and inserts 90 * it into a packet. Input buffer can be any length. 91 * 92 * Input: 93 * - inst : Encoder context 94 * - audio_in : Input speech data buffer 95 * - samples : Samples per channel in audio_in 96 * - length_encoded_buffer : Output buffer size 97 * 98 * Output: 99 * - encoded : Output compressed data buffer 100 * 101 * Return value : >=0 - Length (in bytes) of coded data 102 * -1 - Error 103 */ 104 int WebRtcOpus_Encode(OpusEncInst* inst, 105 const int16_t* audio_in, 106 size_t samples, 107 size_t length_encoded_buffer, 108 uint8_t* encoded); 109 110 /**************************************************************************** 111 * WebRtcOpus_SetBitRate(...) 112 * 113 * This function adjusts the target bitrate of the encoder. 114 * 115 * Input: 116 * - inst : Encoder context 117 * - rate : New target bitrate 118 * 119 * Return value : 0 - Success 120 * -1 - Error 121 */ 122 int16_t WebRtcOpus_SetBitRate(OpusEncInst* inst, int32_t rate); 123 124 /**************************************************************************** 125 * WebRtcOpus_SetPacketLossRate(...) 126 * 127 * This function configures the encoder's expected packet loss percentage. 128 * 129 * Input: 130 * - inst : Encoder context 131 * - loss_rate : loss percentage in the range 0-100, inclusive. 132 * Return value : 0 - Success 133 * -1 - Error 134 */ 135 int16_t WebRtcOpus_SetPacketLossRate(OpusEncInst* inst, int32_t loss_rate); 136 137 /**************************************************************************** 138 * WebRtcOpus_SetMaxPlaybackRate(...) 139 * 140 * Configures the maximum playback rate for encoding. Due to hardware 141 * limitations, the receiver may render audio up to a playback rate. Opus 142 * encoder can use this information to optimize for network usage and encoding 143 * complexity. This will affect the audio bandwidth in the coded audio. However, 144 * the input/output sample rate is not affected. 145 * 146 * Input: 147 * - inst : Encoder context 148 * - frequency_hz : Maximum playback rate in Hz. 149 * This parameter can take any value. The relation 150 * between the value and the Opus internal mode is 151 * as following: 152 * frequency_hz <= 8000 narrow band 153 * 8000 < frequency_hz <= 12000 medium band 154 * 12000 < frequency_hz <= 16000 wide band 155 * 16000 < frequency_hz <= 24000 super wide band 156 * frequency_hz > 24000 full band 157 * Return value : 0 - Success 158 * -1 - Error 159 */ 160 int16_t WebRtcOpus_SetMaxPlaybackRate(OpusEncInst* inst, int32_t frequency_hz); 161 162 /**************************************************************************** 163 * WebRtcOpus_GetMaxPlaybackRate(...) 164 * 165 * Queries the maximum playback rate for encoding. If different single-stream 166 * encoders have different maximum playback rates, this function fails. 167 * 168 * Input: 169 * - inst : Encoder context. 170 * Output: 171 * - result_hz : The maximum playback rate in Hz. 172 * Return value : 0 - Success 173 * -1 - Error 174 */ 175 int16_t WebRtcOpus_GetMaxPlaybackRate(OpusEncInst* const inst, 176 int32_t* result_hz); 177 178 /* TODO(minyue): Check whether an API to check the FEC and the packet loss rate 179 * is needed. It might not be very useful since there are not many use cases and 180 * the caller can always maintain the states. */ 181 182 /**************************************************************************** 183 * WebRtcOpus_EnableFec() 184 * 185 * This function enables FEC for encoding. 186 * 187 * Input: 188 * - inst : Encoder context 189 * 190 * Return value : 0 - Success 191 * -1 - Error 192 */ 193 int16_t WebRtcOpus_EnableFec(OpusEncInst* inst); 194 195 /**************************************************************************** 196 * WebRtcOpus_DisableFec() 197 * 198 * This function disables FEC for encoding. 199 * 200 * Input: 201 * - inst : Encoder context 202 * 203 * Return value : 0 - Success 204 * -1 - Error 205 */ 206 int16_t WebRtcOpus_DisableFec(OpusEncInst* inst); 207 208 /**************************************************************************** 209 * WebRtcOpus_EnableDtx() 210 * 211 * This function enables Opus internal DTX for encoding. 212 * 213 * Input: 214 * - inst : Encoder context 215 * 216 * Return value : 0 - Success 217 * -1 - Error 218 */ 219 int16_t WebRtcOpus_EnableDtx(OpusEncInst* inst); 220 221 /**************************************************************************** 222 * WebRtcOpus_DisableDtx() 223 * 224 * This function disables Opus internal DTX for encoding. 225 * 226 * Input: 227 * - inst : Encoder context 228 * 229 * Return value : 0 - Success 230 * -1 - Error 231 */ 232 int16_t WebRtcOpus_DisableDtx(OpusEncInst* inst); 233 234 /**************************************************************************** 235 * WebRtcOpus_EnableCbr() 236 * 237 * This function enables CBR for encoding. 238 * 239 * Input: 240 * - inst : Encoder context 241 * 242 * Return value : 0 - Success 243 * -1 - Error 244 */ 245 int16_t WebRtcOpus_EnableCbr(OpusEncInst* inst); 246 247 /**************************************************************************** 248 * WebRtcOpus_DisableCbr() 249 * 250 * This function disables CBR for encoding. 251 * 252 * Input: 253 * - inst : Encoder context 254 * 255 * Return value : 0 - Success 256 * -1 - Error 257 */ 258 int16_t WebRtcOpus_DisableCbr(OpusEncInst* inst); 259 260 /* 261 * WebRtcOpus_SetComplexity(...) 262 * 263 * This function adjusts the computational complexity. The effect is the same as 264 * calling the complexity setting of Opus as an Opus encoder related CTL. 265 * 266 * Input: 267 * - inst : Encoder context 268 * - complexity : New target complexity (0-10, inclusive) 269 * 270 * Return value : 0 - Success 271 * -1 - Error 272 */ 273 int16_t WebRtcOpus_SetComplexity(OpusEncInst* inst, int32_t complexity); 274 275 /* 276 * WebRtcOpus_GetBandwidth(...) 277 * 278 * This function returns the current bandwidth. 279 * 280 * Input: 281 * - inst : Encoder context 282 * 283 * Return value : Bandwidth - Success 284 * -1 - Error 285 */ 286 int32_t WebRtcOpus_GetBandwidth(OpusEncInst* inst); 287 288 /* 289 * WebRtcOpus_SetBandwidth(...) 290 * 291 * By default Opus decides which bandwidth to encode the signal in depending on 292 * the the bitrate. This function overrules the previous setting and forces the 293 * encoder to encode in narrowband/wideband/fullband/etc. 294 * 295 * Input: 296 * - inst : Encoder context 297 * - bandwidth : New target bandwidth. Valid values are: 298 * OPUS_BANDWIDTH_NARROWBAND 299 * OPUS_BANDWIDTH_MEDIUMBAND 300 * OPUS_BANDWIDTH_WIDEBAND 301 * OPUS_BANDWIDTH_SUPERWIDEBAND 302 * OPUS_BANDWIDTH_FULLBAND 303 * 304 * Return value : 0 - Success 305 * -1 - Error 306 */ 307 int16_t WebRtcOpus_SetBandwidth(OpusEncInst* inst, int32_t bandwidth); 308 309 /* 310 * WebRtcOpus_GetInDtx(...) 311 * 312 * Gets the DTX state of the encoder. 313 * 314 * Input: 315 * - inst : Encoder context 316 * 317 * Return value : -1 - Error. 318 * 1 - Last encoded frame was comfort noise update during DTX. 319 * 0 - Last encoded frame was encoded with encoder not in DTX. 320 */ 321 int32_t WebRtcOpus_GetInDtx(OpusEncInst* inst); 322 323 /* 324 * WebRtcOpus_SetForceChannels(...) 325 * 326 * If the encoder is initialized as a stereo encoder, Opus will by default 327 * decide whether to encode in mono or stereo based on the bitrate. This 328 * function overrules the previous setting, and forces the encoder to encode 329 * in auto/mono/stereo. 330 * 331 * If the Encoder is initialized as a mono encoder, and one tries to force 332 * stereo, the function will return an error. 333 * 334 * Input: 335 * - inst : Encoder context 336 * - num_channels : 0 - Not forced 337 * 1 - Mono 338 * 2 - Stereo 339 * 340 * Return value : 0 - Success 341 * -1 - Error 342 */ 343 int16_t WebRtcOpus_SetForceChannels(OpusEncInst* inst, size_t num_channels); 344 345 int16_t WebRtcOpus_DecoderCreate(OpusDecInst** inst, 346 size_t channels, 347 int sample_rate_hz); 348 349 /**************************************************************************** 350 * WebRtcOpus_MultistreamDecoderCreate(...) 351 * 352 * This function creates an Opus decoder with any supported channel count. 353 * 354 * Input: 355 * - channels : number of output channels that the decoder 356 * will produce. 357 * - streams : number of encoded streams, as described in 358 * RFC 7845. 359 * - coupled_streams : number of coupled streams, as described in 360 * RFC 7845. 361 * - channel_mapping : the channel mapping; pointer to array of 362 * `channel` bytes, as described in RFC 7845. 363 * 364 * Output: 365 * - inst : a pointer to a Decoder context that is created 366 * if success. 367 * 368 * Return value : 0 - Success 369 * -1 - Error 370 */ 371 int16_t WebRtcOpus_MultistreamDecoderCreate( 372 OpusDecInst** inst, 373 size_t channels, 374 size_t streams, 375 size_t coupled_streams, 376 const unsigned char* channel_mapping); 377 378 int16_t WebRtcOpus_DecoderFree(OpusDecInst* inst); 379 380 /**************************************************************************** 381 * WebRtcOpus_DecoderChannels(...) 382 * 383 * This function returns the number of channels created for Opus decoder. 384 */ 385 size_t WebRtcOpus_DecoderChannels(OpusDecInst* inst); 386 387 /**************************************************************************** 388 * WebRtcOpus_DecoderInit(...) 389 * 390 * This function resets state of the decoder. 391 * 392 * Input: 393 * - inst : Decoder context 394 */ 395 void WebRtcOpus_DecoderInit(OpusDecInst* inst); 396 397 /**************************************************************************** 398 * WebRtcOpus_Decode(...) 399 * 400 * This function decodes an Opus packet into one or more audio frames at the 401 * ACM interface's sampling rate (32 kHz). 402 * 403 * Input: 404 * - inst : Decoder context 405 * - encoded : Encoded data 406 * - encoded_bytes : Bytes in encoded vector 407 * 408 * Output: 409 * - decoded : The decoded vector 410 * - audio_type : 1 normal, 2 CNG (for Opus it should 411 * always return 1 since we're not using Opus's 412 * built-in DTX/CNG scheme) 413 * 414 * Return value : >0 - Samples per channel in decoded vector 415 * -1 - Error 416 */ 417 int WebRtcOpus_Decode(OpusDecInst* inst, 418 const uint8_t* encoded, 419 size_t encoded_bytes, 420 int16_t* decoded, 421 int16_t* audio_type); 422 423 /**************************************************************************** 424 * WebRtcOpus_DecodeFec(...) 425 * 426 * This function decodes the FEC data from an Opus packet into one or more audio 427 * frames at the ACM interface's sampling rate (32 kHz). 428 * 429 * Input: 430 * - inst : Decoder context 431 * - encoded : Encoded data 432 * - encoded_bytes : Bytes in encoded vector 433 * 434 * Output: 435 * - decoded : The decoded vector (previous frame) 436 * 437 * Return value : >0 - Samples per channel in decoded vector 438 * 0 - No FEC data in the packet 439 * -1 - Error 440 */ 441 int WebRtcOpus_DecodeFec(OpusDecInst* inst, 442 const uint8_t* encoded, 443 size_t encoded_bytes, 444 int16_t* decoded, 445 int16_t* audio_type); 446 447 /**************************************************************************** 448 * WebRtcOpus_DurationEst(...) 449 * 450 * This function calculates the duration of an opus packet. 451 * Input: 452 * - inst : Decoder context 453 * - payload : Encoded data pointer 454 * - payload_length_bytes : Bytes of encoded data 455 * 456 * Return value : The duration of the packet, in samples per 457 * channel. 458 */ 459 int WebRtcOpus_DurationEst(OpusDecInst* inst, 460 const uint8_t* payload, 461 size_t payload_length_bytes); 462 463 /**************************************************************************** 464 * WebRtcOpus_PlcDuration(...) 465 * 466 * This function calculates the duration of a frame returned by packet loss 467 * concealment (PLC). 468 * 469 * Input: 470 * - inst : Decoder context 471 * 472 * Return value : The duration of a frame returned by PLC, in 473 * samples per channel. 474 */ 475 int WebRtcOpus_PlcDuration(OpusDecInst* inst); 476 477 /* TODO(minyue): Check whether it is needed to add a decoder context to the 478 * arguments, like WebRtcOpus_DurationEst(...). In fact, the packet itself tells 479 * the duration. The decoder context in WebRtcOpus_DurationEst(...) is not used. 480 * So it may be advisable to remove it from WebRtcOpus_DurationEst(...). */ 481 482 /**************************************************************************** 483 * WebRtcOpus_FecDurationEst(...) 484 * 485 * This function calculates the duration of the FEC data within an opus packet. 486 * Input: 487 * - payload : Encoded data pointer 488 * - payload_length_bytes : Bytes of encoded data 489 * - sample_rate_hz : Sample rate of output audio 490 * 491 * Return value : >0 - The duration of the FEC data in the 492 * packet in samples per channel. 493 * 0 - No FEC data in the packet. 494 */ 495 int WebRtcOpus_FecDurationEst(const uint8_t* payload, 496 size_t payload_length_bytes, 497 int sample_rate_hz); 498 499 /**************************************************************************** 500 * WebRtcOpus_PacketHasFec(...) 501 * 502 * This function detects if an opus packet has FEC. 503 * Input: 504 * - payload : Encoded data pointer 505 * - payload_length_bytes : Bytes of encoded data 506 * 507 * Return value : 0 - the packet does NOT contain FEC. 508 * 1 - the packet contains FEC. 509 */ 510 int WebRtcOpus_PacketHasFec(const uint8_t* payload, 511 size_t payload_length_bytes); 512 513 /**************************************************************************** 514 * WebRtcOpus_PacketHasVoiceActivity(...) 515 * 516 * This function returns the SILK VAD information encoded in the opus packet. 517 * For CELT-only packets that do not have VAD information, it returns -1. 518 * Input: 519 * - payload : Encoded data pointer 520 * - payload_length_bytes : Bytes of encoded data 521 * 522 * Return value : 0 - no frame had the VAD flag set. 523 * 1 - at least one frame had the VAD flag set. 524 * -1 - VAD status could not be determined. 525 */ 526 int WebRtcOpus_PacketHasVoiceActivity(const uint8_t* payload, 527 size_t payload_length_bytes); 528 529 #ifdef __cplusplus 530 } // extern "C" 531 #endif 532 533 #endif // MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_ 534