opus_interface.h (19786B)
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" // IWYU pragma: export 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_GetUseDtx() 250 * 251 * This function gets if the encoder is in DTX. 252 * 253 * Input: 254 * - inst : Encoder context 255 * 256 * Return value : 0 - Encoder is not DTX. 257 * 1 - Encoder is in DTX. 258 * -1 - Error. 259 */ 260 int16_t WebRtcOpus_GetInDtx(OpusEncInst* inst); 261 262 /**************************************************************************** 263 * WebRtcOpus_EnableCbr() 264 * 265 * This function enables CBR for encoding. 266 * 267 * Input: 268 * - inst : Encoder context 269 * 270 * Return value : 0 - Success 271 * -1 - Error 272 */ 273 int16_t WebRtcOpus_EnableCbr(OpusEncInst* inst); 274 275 /**************************************************************************** 276 * WebRtcOpus_DisableCbr() 277 * 278 * This function disables CBR for encoding. 279 * 280 * Input: 281 * - inst : Encoder context 282 * 283 * Return value : 0 - Success 284 * -1 - Error 285 */ 286 int16_t WebRtcOpus_DisableCbr(OpusEncInst* inst); 287 288 /* 289 * WebRtcOpus_SetComplexity(...) 290 * 291 * This function adjusts the computational complexity. The effect is the same as 292 * calling the complexity setting of Opus as an Opus encoder related CTL. 293 * 294 * Input: 295 * - inst : Encoder context 296 * - complexity : New target complexity (0-10, inclusive) 297 * 298 * Return value : 0 - Success 299 * -1 - Error 300 */ 301 int16_t WebRtcOpus_SetComplexity(OpusEncInst* inst, int32_t complexity); 302 303 /* 304 * WebRtcOpus_GetBandwidth(...) 305 * 306 * This function returns the current bandwidth. 307 * 308 * Input: 309 * - inst : Encoder context 310 * 311 * Return value : Bandwidth - Success 312 * -1 - Error 313 */ 314 int32_t WebRtcOpus_GetBandwidth(OpusEncInst* inst); 315 316 /* 317 * WebRtcOpus_SetBandwidth(...) 318 * 319 * By default Opus decides which bandwidth to encode the signal in depending on 320 * the the bitrate. This function overrules the previous setting and forces the 321 * encoder to encode in narrowband/wideband/fullband/etc. 322 * 323 * Input: 324 * - inst : Encoder context 325 * - bandwidth : New target bandwidth. Valid values are: 326 * OPUS_BANDWIDTH_NARROWBAND 327 * OPUS_BANDWIDTH_MEDIUMBAND 328 * OPUS_BANDWIDTH_WIDEBAND 329 * OPUS_BANDWIDTH_SUPERWIDEBAND 330 * OPUS_BANDWIDTH_FULLBAND 331 * 332 * Return value : 0 - Success 333 * -1 - Error 334 */ 335 int16_t WebRtcOpus_SetBandwidth(OpusEncInst* inst, int32_t bandwidth); 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 425 * 426 * Return value : >0 - Samples per channel in decoded vector 427 * -1 - Error 428 */ 429 int WebRtcOpus_Decode(OpusDecInst* inst, 430 const uint8_t* encoded, 431 size_t encoded_bytes, 432 int16_t* decoded, 433 int16_t* audio_type); 434 435 /**************************************************************************** 436 * WebRtcOpus_DecodeFec(...) 437 * 438 * This function decodes the FEC data from an Opus packet into one or more audio 439 * frames at the ACM interface's sampling rate (32 kHz). 440 * 441 * Input: 442 * - inst : Decoder context 443 * - encoded : Encoded data 444 * - encoded_bytes : Bytes in encoded vector 445 * 446 * Output: 447 * - decoded : The decoded vector (previous frame) 448 * 449 * Return value : >0 - Samples per channel in decoded vector 450 * 0 - No FEC data in the packet 451 * -1 - Error 452 */ 453 int WebRtcOpus_DecodeFec(OpusDecInst* inst, 454 const uint8_t* encoded, 455 size_t encoded_bytes, 456 int16_t* decoded, 457 int16_t* audio_type); 458 459 /**************************************************************************** 460 * WebRtcOpus_DurationEst(...) 461 * 462 * This function calculates the duration of an opus packet. 463 * Input: 464 * - inst : Decoder context 465 * - payload : Encoded data pointer 466 * - payload_length_bytes : Bytes of encoded data 467 * 468 * Return value : The duration of the packet, in samples per 469 * channel. 470 */ 471 int WebRtcOpus_DurationEst(OpusDecInst* inst, 472 const uint8_t* payload, 473 size_t payload_length_bytes); 474 475 /**************************************************************************** 476 * WebRtcOpus_PlcDuration(...) 477 * 478 * This function calculates the duration of a frame returned by packet loss 479 * concealment (PLC). 480 * 481 * Input: 482 * - inst : Decoder context 483 * 484 * Return value : The duration of a frame returned by PLC, in 485 * samples per channel. 486 */ 487 int WebRtcOpus_PlcDuration(OpusDecInst* inst); 488 489 /* TODO(minyue): Check whether it is needed to add a decoder context to the 490 * arguments, like WebRtcOpus_DurationEst(...). In fact, the packet itself tells 491 * the duration. The decoder context in WebRtcOpus_DurationEst(...) is not used. 492 * So it may be advisable to remove it from WebRtcOpus_DurationEst(...). */ 493 494 /**************************************************************************** 495 * WebRtcOpus_FecDurationEst(...) 496 * 497 * This function calculates the duration of the FEC data within an opus packet. 498 * Input: 499 * - payload : Encoded data pointer 500 * - payload_length_bytes : Bytes of encoded data 501 * - sample_rate_hz : Sample rate of output audio 502 * 503 * Return value : >0 - The duration of the FEC data in the 504 * packet in samples per channel. 505 * 0 - No FEC data in the packet. 506 */ 507 int WebRtcOpus_FecDurationEst(const uint8_t* payload, 508 size_t payload_length_bytes, 509 int sample_rate_hz); 510 511 /**************************************************************************** 512 * WebRtcOpus_PacketHasFec(...) 513 * 514 * This function detects if an opus packet has FEC. 515 * Input: 516 * - payload : Encoded data pointer 517 * - payload_length_bytes : Bytes of encoded data 518 * 519 * Return value : 0 - the packet does NOT contain FEC. 520 * 1 - the packet contains FEC. 521 */ 522 int WebRtcOpus_PacketHasFec(const uint8_t* payload, 523 size_t payload_length_bytes); 524 525 /**************************************************************************** 526 * WebRtcOpus_PacketHasVoiceActivity(...) 527 * 528 * This function returns the SILK VAD information encoded in the opus packet. 529 * For CELT-only packets that do not have VAD information, it returns -1. 530 * Input: 531 * - payload : Encoded data pointer 532 * - payload_length_bytes : Bytes of encoded data 533 * 534 * Return value : 0 - no frame had the VAD flag set. 535 * 1 - at least one frame had the VAD flag set. 536 * -1 - VAD status could not be determined. 537 */ 538 int WebRtcOpus_PacketHasVoiceActivity(const uint8_t* payload, 539 size_t payload_length_bytes); 540 541 #ifdef __cplusplus 542 } // extern "C" 543 #endif 544 545 #endif // MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_