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_GetUseDtx() 236 * 237 * This function gets the DTX configuration used for encoding. 238 * 239 * Input: 240 * - inst : Encoder context 241 * 242 * Return value : 0 - Encoder does not use DTX. 243 * 1 - Encoder uses DTX. 244 * -1 - Error. 245 */ 246 int16_t WebRtcOpus_GetUseDtx(OpusEncInst* inst); 247 248 /**************************************************************************** 249 * WebRtcOpus_EnableCbr() 250 * 251 * This function enables CBR for encoding. 252 * 253 * Input: 254 * - inst : Encoder context 255 * 256 * Return value : 0 - Success 257 * -1 - Error 258 */ 259 int16_t WebRtcOpus_EnableCbr(OpusEncInst* inst); 260 261 /**************************************************************************** 262 * WebRtcOpus_DisableCbr() 263 * 264 * This function disables CBR for encoding. 265 * 266 * Input: 267 * - inst : Encoder context 268 * 269 * Return value : 0 - Success 270 * -1 - Error 271 */ 272 int16_t WebRtcOpus_DisableCbr(OpusEncInst* inst); 273 274 /* 275 * WebRtcOpus_SetComplexity(...) 276 * 277 * This function adjusts the computational complexity. The effect is the same as 278 * calling the complexity setting of Opus as an Opus encoder related CTL. 279 * 280 * Input: 281 * - inst : Encoder context 282 * - complexity : New target complexity (0-10, inclusive) 283 * 284 * Return value : 0 - Success 285 * -1 - Error 286 */ 287 int16_t WebRtcOpus_SetComplexity(OpusEncInst* inst, int32_t complexity); 288 289 /* 290 * WebRtcOpus_GetBandwidth(...) 291 * 292 * This function returns the current bandwidth. 293 * 294 * Input: 295 * - inst : Encoder context 296 * 297 * Return value : Bandwidth - Success 298 * -1 - Error 299 */ 300 int32_t WebRtcOpus_GetBandwidth(OpusEncInst* inst); 301 302 /* 303 * WebRtcOpus_SetBandwidth(...) 304 * 305 * By default Opus decides which bandwidth to encode the signal in depending on 306 * the the bitrate. This function overrules the previous setting and forces the 307 * encoder to encode in narrowband/wideband/fullband/etc. 308 * 309 * Input: 310 * - inst : Encoder context 311 * - bandwidth : New target bandwidth. Valid values are: 312 * OPUS_BANDWIDTH_NARROWBAND 313 * OPUS_BANDWIDTH_MEDIUMBAND 314 * OPUS_BANDWIDTH_WIDEBAND 315 * OPUS_BANDWIDTH_SUPERWIDEBAND 316 * OPUS_BANDWIDTH_FULLBAND 317 * 318 * Return value : 0 - Success 319 * -1 - Error 320 */ 321 int16_t WebRtcOpus_SetBandwidth(OpusEncInst* inst, int32_t bandwidth); 322 323 /* 324 * WebRtcOpus_GetInDtx(...) 325 * 326 * Gets the DTX state of the encoder. 327 * 328 * Input: 329 * - inst : Encoder context 330 * 331 * Return value : -1 - Error. 332 * 1 - Last encoded frame was comfort noise update during DTX. 333 * 0 - Last encoded frame was encoded with encoder not in DTX. 334 */ 335 int32_t WebRtcOpus_GetInDtx(OpusEncInst* inst); 336 337 /* 338 * WebRtcOpus_SetForceChannels(...) 339 * 340 * If the encoder is initialized as a stereo encoder, Opus will by default 341 * decide whether to encode in mono or stereo based on the bitrate. This 342 * function overrules the previous setting, and forces the encoder to encode 343 * in auto/mono/stereo. 344 * 345 * If the Encoder is initialized as a mono encoder, and one tries to force 346 * stereo, the function will return an error. 347 * 348 * Input: 349 * - inst : Encoder context 350 * - num_channels : 0 - Not forced 351 * 1 - Mono 352 * 2 - Stereo 353 * 354 * Return value : 0 - Success 355 * -1 - Error 356 */ 357 int16_t WebRtcOpus_SetForceChannels(OpusEncInst* inst, size_t num_channels); 358 359 int16_t WebRtcOpus_DecoderCreate(OpusDecInst** inst, 360 size_t channels, 361 int sample_rate_hz); 362 363 /**************************************************************************** 364 * WebRtcOpus_MultistreamDecoderCreate(...) 365 * 366 * This function creates an Opus decoder with any supported channel count. 367 * 368 * Input: 369 * - channels : number of output channels that the decoder 370 * will produce. 371 * - streams : number of encoded streams, as described in 372 * RFC 7845. 373 * - coupled_streams : number of coupled streams, as described in 374 * RFC 7845. 375 * - channel_mapping : the channel mapping; pointer to array of 376 * `channel` bytes, as described in RFC 7845. 377 * 378 * Output: 379 * - inst : a pointer to a Decoder context that is created 380 * if success. 381 * 382 * Return value : 0 - Success 383 * -1 - Error 384 */ 385 int16_t WebRtcOpus_MultistreamDecoderCreate( 386 OpusDecInst** inst, 387 size_t channels, 388 size_t streams, 389 size_t coupled_streams, 390 const unsigned char* channel_mapping); 391 392 int16_t WebRtcOpus_DecoderFree(OpusDecInst* inst); 393 394 /**************************************************************************** 395 * WebRtcOpus_DecoderChannels(...) 396 * 397 * This function returns the number of channels created for Opus decoder. 398 */ 399 size_t WebRtcOpus_DecoderChannels(OpusDecInst* inst); 400 401 /**************************************************************************** 402 * WebRtcOpus_DecoderInit(...) 403 * 404 * This function resets state of the decoder. 405 * 406 * Input: 407 * - inst : Decoder context 408 */ 409 void WebRtcOpus_DecoderInit(OpusDecInst* inst); 410 411 /**************************************************************************** 412 * WebRtcOpus_Decode(...) 413 * 414 * This function decodes an Opus packet into one or more audio frames at the 415 * ACM interface's sampling rate (32 kHz). 416 * 417 * Input: 418 * - inst : Decoder context 419 * - encoded : Encoded data 420 * - encoded_bytes : Bytes in encoded vector 421 * 422 * Output: 423 * - decoded : The decoded vector 424 * - audio_type : 1 normal, 2 CNG (for Opus it should 425 * always return 1 since we're not using Opus's 426 * built-in DTX/CNG scheme) 427 * 428 * Return value : >0 - Samples per channel in decoded vector 429 * -1 - Error 430 */ 431 int WebRtcOpus_Decode(OpusDecInst* inst, 432 const uint8_t* encoded, 433 size_t encoded_bytes, 434 int16_t* decoded, 435 int16_t* audio_type); 436 437 /**************************************************************************** 438 * WebRtcOpus_DecodeFec(...) 439 * 440 * This function decodes the FEC data from an Opus packet into one or more audio 441 * frames at the ACM interface's sampling rate (32 kHz). 442 * 443 * Input: 444 * - inst : Decoder context 445 * - encoded : Encoded data 446 * - encoded_bytes : Bytes in encoded vector 447 * 448 * Output: 449 * - decoded : The decoded vector (previous frame) 450 * 451 * Return value : >0 - Samples per channel in decoded vector 452 * 0 - No FEC data in the packet 453 * -1 - Error 454 */ 455 int WebRtcOpus_DecodeFec(OpusDecInst* inst, 456 const uint8_t* encoded, 457 size_t encoded_bytes, 458 int16_t* decoded, 459 int16_t* audio_type); 460 461 /**************************************************************************** 462 * WebRtcOpus_DurationEst(...) 463 * 464 * This function calculates the duration of an opus packet. 465 * Input: 466 * - inst : Decoder context 467 * - payload : Encoded data pointer 468 * - payload_length_bytes : Bytes of encoded data 469 * 470 * Return value : The duration of the packet, in samples per 471 * channel. 472 */ 473 int WebRtcOpus_DurationEst(OpusDecInst* inst, 474 const uint8_t* payload, 475 size_t payload_length_bytes); 476 477 /**************************************************************************** 478 * WebRtcOpus_PlcDuration(...) 479 * 480 * This function calculates the duration of a frame returned by packet loss 481 * concealment (PLC). 482 * 483 * Input: 484 * - inst : Decoder context 485 * 486 * Return value : The duration of a frame returned by PLC, in 487 * samples per channel. 488 */ 489 int WebRtcOpus_PlcDuration(OpusDecInst* inst); 490 491 /* TODO(minyue): Check whether it is needed to add a decoder context to the 492 * arguments, like WebRtcOpus_DurationEst(...). In fact, the packet itself tells 493 * the duration. The decoder context in WebRtcOpus_DurationEst(...) is not used. 494 * So it may be advisable to remove it from WebRtcOpus_DurationEst(...). */ 495 496 /**************************************************************************** 497 * WebRtcOpus_FecDurationEst(...) 498 * 499 * This function calculates the duration of the FEC data within an opus packet. 500 * Input: 501 * - payload : Encoded data pointer 502 * - payload_length_bytes : Bytes of encoded data 503 * - sample_rate_hz : Sample rate of output audio 504 * 505 * Return value : >0 - The duration of the FEC data in the 506 * packet in samples per channel. 507 * 0 - No FEC data in the packet. 508 */ 509 int WebRtcOpus_FecDurationEst(const uint8_t* payload, 510 size_t payload_length_bytes, 511 int sample_rate_hz); 512 513 /**************************************************************************** 514 * WebRtcOpus_PacketHasFec(...) 515 * 516 * This function detects if an opus packet has FEC. 517 * Input: 518 * - payload : Encoded data pointer 519 * - payload_length_bytes : Bytes of encoded data 520 * 521 * Return value : 0 - the packet does NOT contain FEC. 522 * 1 - the packet contains FEC. 523 */ 524 int WebRtcOpus_PacketHasFec(const uint8_t* payload, 525 size_t payload_length_bytes); 526 527 /**************************************************************************** 528 * WebRtcOpus_PacketHasVoiceActivity(...) 529 * 530 * This function returns the SILK VAD information encoded in the opus packet. 531 * For CELT-only packets that do not have VAD information, it returns -1. 532 * Input: 533 * - payload : Encoded data pointer 534 * - payload_length_bytes : Bytes of encoded data 535 * 536 * Return value : 0 - no frame had the VAD flag set. 537 * 1 - at least one frame had the VAD flag set. 538 * -1 - VAD status could not be determined. 539 */ 540 int WebRtcOpus_PacketHasVoiceActivity(const uint8_t* payload, 541 size_t payload_length_bytes); 542 543 #ifdef __cplusplus 544 } // extern "C" 545 #endif 546 547 #endif // MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_ 548