1 /* 2 * Copyright (c) 2011 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_ISAC_MAIN_INCLUDE_ISAC_H_ 12 #define MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_INCLUDE_ISAC_H_ 13 14 #include <stddef.h> 15 16 #include "modules/audio_coding/codecs/isac/bandwidth_info.h" 17 18 typedef struct WebRtcISACStruct ISACStruct; 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 /****************************************************************************** 25 * WebRtcIsac_Create(...) 26 * 27 * This function creates an ISAC instance, which will contain the state 28 * information for one coding/decoding channel. 29 * 30 * Input: 31 * - *ISAC_main_inst : a pointer to the coder instance. 32 * 33 * Return value : 0 - Ok 34 * -1 - Error 35 */ 36 37 int16_t WebRtcIsac_Create(ISACStruct** ISAC_main_inst); 38 39 /****************************************************************************** 40 * WebRtcIsac_Free(...) 41 * 42 * This function frees the ISAC instance created at the beginning. 43 * 44 * Input: 45 * - ISAC_main_inst : an ISAC instance. 46 * 47 * Return value : 0 - Ok 48 * -1 - Error 49 */ 50 51 int16_t WebRtcIsac_Free(ISACStruct* ISAC_main_inst); 52 53 /****************************************************************************** 54 * WebRtcIsac_EncoderInit(...) 55 * 56 * This function initializes an ISAC instance prior to the encoder calls. 57 * 58 * Input: 59 * - ISAC_main_inst : ISAC instance. 60 * - CodingMode : 0 -> Bit rate and frame length are 61 * automatically adjusted to available bandwidth 62 * on transmission channel, just valid if codec 63 * is created to work in wideband mode. 64 * 1 -> User sets a frame length and a target bit 65 * rate which is taken as the maximum 66 * short-term average bit rate. 67 * 68 * Return value : 0 - Ok 69 * -1 - Error 70 */ 71 72 int16_t WebRtcIsac_EncoderInit(ISACStruct* ISAC_main_inst, int16_t CodingMode); 73 74 /****************************************************************************** 75 * WebRtcIsac_Encode(...) 76 * 77 * This function encodes 10ms audio blocks and inserts it into a package. 78 * Input speech length has 160 samples if operating at 16 kHz sampling 79 * rate, or 320 if operating at 32 kHz sampling rate. The encoder buffers the 80 * input audio until the whole frame is buffered then proceeds with encoding. 81 * 82 * 83 * Input: 84 * - ISAC_main_inst : ISAC instance. 85 * - speechIn : input speech vector. 86 * 87 * Output: 88 * - encoded : the encoded data vector 89 * 90 * Return value: 91 * : >0 - Length (in bytes) of coded data 92 * : 0 - The buffer didn't reach the chosen 93 * frame-size so it keeps buffering speech 94 * samples. 95 * : -1 - Error 96 */ 97 98 int WebRtcIsac_Encode(ISACStruct* ISAC_main_inst, 99 const int16_t* speechIn, 100 uint8_t* encoded); 101 102 /****************************************************************************** 103 * WebRtcIsac_DecoderInit(...) 104 * 105 * This function initializes an ISAC instance prior to the decoder calls. 106 * 107 * Input: 108 * - ISAC_main_inst : ISAC instance. 109 */ 110 111 void WebRtcIsac_DecoderInit(ISACStruct* ISAC_main_inst); 112 113 /****************************************************************************** 114 * WebRtcIsac_UpdateBwEstimate(...) 115 * 116 * This function updates the estimate of the bandwidth. 117 * 118 * Input: 119 * - ISAC_main_inst : ISAC instance. 120 * - encoded : encoded ISAC frame(s). 121 * - packet_size : size of the packet. 122 * - rtp_seq_number : the RTP number of the packet. 123 * - send_ts : the RTP send timestamp, given in samples 124 * - arr_ts : the arrival time of the packet (from NetEq) 125 * in samples. 126 * 127 * Return value : 0 - Ok 128 * -1 - Error 129 */ 130 131 int16_t WebRtcIsac_UpdateBwEstimate(ISACStruct* ISAC_main_inst, 132 const uint8_t* encoded, 133 size_t packet_size, 134 uint16_t rtp_seq_number, 135 uint32_t send_ts, 136 uint32_t arr_ts); 137 138 /****************************************************************************** 139 * WebRtcIsac_Decode(...) 140 * 141 * This function decodes an ISAC frame. At 16 kHz sampling rate, the length 142 * of the output audio could be either 480 or 960 samples, equivalent to 143 * 30 or 60 ms respectively. At 32 kHz sampling rate, the length of the 144 * output audio is 960 samples, which is 30 ms. 145 * 146 * Input: 147 * - ISAC_main_inst : ISAC instance. 148 * - encoded : encoded ISAC frame(s). 149 * - len : bytes in encoded vector. 150 * 151 * Output: 152 * - decoded : The decoded vector. 153 * 154 * Return value : >0 - number of samples in decoded vector. 155 * -1 - Error. 156 */ 157 158 int WebRtcIsac_Decode(ISACStruct* ISAC_main_inst, 159 const uint8_t* encoded, 160 size_t len, 161 int16_t* decoded, 162 int16_t* speechType); 163 164 /****************************************************************************** 165 * WebRtcIsac_DecodePlc(...) 166 * 167 * This function conducts PLC for ISAC frame(s). Output speech length 168 * will be a multiple of frames, i.e. multiples of 30 ms audio. Therefore, 169 * the output is multiple of 480 samples if operating at 16 kHz and multiple 170 * of 960 if operating at 32 kHz. 171 * 172 * Input: 173 * - ISAC_main_inst : ISAC instance. 174 * - noOfLostFrames : Number of PLC frames to produce. 175 * 176 * Output: 177 * - decoded : The decoded vector. 178 * 179 * Return value : Number of samples in decoded PLC vector 180 */ 181 182 size_t WebRtcIsac_DecodePlc(ISACStruct* ISAC_main_inst, 183 int16_t* decoded, 184 size_t noOfLostFrames); 185 186 /****************************************************************************** 187 * WebRtcIsac_Control(...) 188 * 189 * This function sets the limit on the short-term average bit-rate and the 190 * frame length. Should be used only in Instantaneous mode. At 16 kHz sampling 191 * rate, an average bit-rate between 10000 to 32000 bps is valid and a 192 * frame-size of 30 or 60 ms is acceptable. At 32 kHz, an average bit-rate 193 * between 10000 to 56000 is acceptable, and the valid frame-size is 30 ms. 194 * 195 * Input: 196 * - ISAC_main_inst : ISAC instance. 197 * - rate : limit on the short-term average bit rate, 198 * in bits/second. 199 * - framesize : frame-size in millisecond. 200 * 201 * Return value : 0 - ok 202 * -1 - Error 203 */ 204 205 int16_t WebRtcIsac_Control(ISACStruct* ISAC_main_inst, 206 int32_t rate, 207 int framesize); 208 209 void WebRtcIsac_SetInitialBweBottleneck(ISACStruct* ISAC_main_inst, 210 int bottleneck_bits_per_second); 211 212 /****************************************************************************** 213 * WebRtcIsac_ControlBwe(...) 214 * 215 * This function sets the initial values of bottleneck and frame-size if 216 * iSAC is used in channel-adaptive mode. Therefore, this API is not 217 * applicable if the codec is created to operate in super-wideband mode. 218 * 219 * Through this API, users can enforce a frame-size for all values of 220 * bottleneck. Then iSAC will not automatically change the frame-size. 221 * 222 * 223 * Input: 224 * - ISAC_main_inst : ISAC instance. 225 * - rateBPS : initial value of bottleneck in bits/second 226 * 10000 <= rateBPS <= 56000 is accepted 227 * For default bottleneck set rateBPS = 0 228 * - frameSizeMs : number of milliseconds per frame (30 or 60) 229 * - enforceFrameSize : 1 to enforce the given frame-size through 230 * out the adaptation process, 0 to let iSAC 231 * change the frame-size if required. 232 * 233 * Return value : 0 - ok 234 * -1 - Error 235 */ 236 237 int16_t WebRtcIsac_ControlBwe(ISACStruct* ISAC_main_inst, 238 int32_t rateBPS, 239 int frameSizeMs, 240 int16_t enforceFrameSize); 241 242 /****************************************************************************** 243 * WebRtcIsac_ReadFrameLen(...) 244 * 245 * This function returns the length of the frame represented in the packet. 246 * 247 * Input: 248 * - encoded : Encoded bit-stream 249 * 250 * Output: 251 * - frameLength : Length of frame in packet (in samples) 252 * 253 */ 254 255 int16_t WebRtcIsac_ReadFrameLen(const ISACStruct* ISAC_main_inst, 256 const uint8_t* encoded, 257 int16_t* frameLength); 258 259 /****************************************************************************** 260 * WebRtcIsac_version(...) 261 * 262 * This function returns the version number. 263 * 264 * Output: 265 * - version : Pointer to character string 266 * 267 */ 268 269 void WebRtcIsac_version(char* version); 270 271 /****************************************************************************** 272 * WebRtcIsac_GetErrorCode(...) 273 * 274 * This function can be used to check the error code of an iSAC instance. When 275 * a function returns -1 a error code will be set for that instance. The 276 * function below extract the code of the last error that occurred in the 277 * specified instance. 278 * 279 * Input: 280 * - ISAC_main_inst : ISAC instance 281 * 282 * Return value : Error code 283 */ 284 285 int16_t WebRtcIsac_GetErrorCode(ISACStruct* ISAC_main_inst); 286 287 /**************************************************************************** 288 * WebRtcIsac_GetUplinkBw(...) 289 * 290 * This function outputs the target bottleneck of the codec. In 291 * channel-adaptive mode, the target bottleneck is specified through in-band 292 * signalling retreived by bandwidth estimator. 293 * In channel-independent, also called instantaneous mode, the target 294 * bottleneck is provided to the encoder by calling xxx_control(...). If 295 * xxx_control is never called the default values is returned. The default 296 * value for bottleneck at 16 kHz encoder sampling rate is 32000 bits/sec, 297 * and it is 56000 bits/sec for 32 kHz sampling rate. 298 * Note that the output is the iSAC internal operating bottleneck which might 299 * differ slightly from the one provided through xxx_control(). 300 * 301 * Input: 302 * - ISAC_main_inst : iSAC instance 303 * 304 * Output: 305 * - *bottleneck : bottleneck in bits/sec 306 * 307 * Return value : -1 if error happens 308 * 0 bit-rates computed correctly. 309 */ 310 311 int16_t WebRtcIsac_GetUplinkBw(ISACStruct* ISAC_main_inst, int32_t* bottleneck); 312 313 /****************************************************************************** 314 * WebRtcIsac_SetMaxPayloadSize(...) 315 * 316 * This function sets a limit for the maximum payload size of iSAC. The same 317 * value is used both for 30 and 60 ms packets. If the encoder sampling rate 318 * is 16 kHz the maximum payload size is between 120 and 400 bytes. If the 319 * encoder sampling rate is 32 kHz the maximum payload size is between 120 320 * and 600 bytes. 321 * 322 * If an out of range limit is used, the function returns -1, but the closest 323 * valid value will be applied. 324 * 325 * --------------- 326 * IMPORTANT NOTES 327 * --------------- 328 * The size of a packet is limited to the minimum of 'max-payload-size' and 329 * 'max-rate.' For instance, let's assume the max-payload-size is set to 330 * 170 bytes, and max-rate is set to 40 kbps. Note that a limit of 40 kbps 331 * translates to 150 bytes for 30ms frame-size & 300 bytes for 60ms 332 * frame-size. Then a packet with a frame-size of 30 ms is limited to 150, 333 * i.e. min(170, 150), and a packet with 60 ms frame-size is limited to 334 * 170 bytes, i.e. min(170, 300). 335 * 336 * Input: 337 * - ISAC_main_inst : iSAC instance 338 * - maxPayloadBytes : maximum size of the payload in bytes 339 * valid values are between 120 and 400 bytes 340 * if encoder sampling rate is 16 kHz. For 341 * 32 kHz encoder sampling rate valid values 342 * are between 120 and 600 bytes. 343 * 344 * Return value : 0 if successful 345 * -1 if error happens 346 */ 347 348 int16_t WebRtcIsac_SetMaxPayloadSize(ISACStruct* ISAC_main_inst, 349 int16_t maxPayloadBytes); 350 351 /****************************************************************************** 352 * WebRtcIsac_SetMaxRate(...) 353 * 354 * This function sets the maximum rate which the codec may not exceed for 355 * any signal packet. The maximum rate is defined and payload-size per 356 * frame-size in bits per second. 357 * 358 * The codec has a maximum rate of 53400 bits per second (200 bytes per 30 359 * ms) if the encoder sampling rate is 16kHz, and 160 kbps (600 bytes/30 ms) 360 * if the encoder sampling rate is 32 kHz. 361 * 362 * It is possible to set a maximum rate between 32000 and 53400 bits/sec 363 * in wideband mode, and 32000 to 160000 bits/sec in super-wideband mode. 364 * 365 * If an out of range limit is used, the function returns -1, but the closest 366 * valid value will be applied. 367 * 368 * --------------- 369 * IMPORTANT NOTES 370 * --------------- 371 * The size of a packet is limited to the minimum of 'max-payload-size' and 372 * 'max-rate.' For instance, let's assume the max-payload-size is set to 373 * 170 bytes, and max-rate is set to 40 kbps. Note that a limit of 40 kbps 374 * translates to 150 bytes for 30ms frame-size & 300 bytes for 60ms 375 * frame-size. Then a packet with a frame-size of 30 ms is limited to 150, 376 * i.e. min(170, 150), and a packet with 60 ms frame-size is limited to 377 * 170 bytes, min(170, 300). 378 * 379 * Input: 380 * - ISAC_main_inst : iSAC instance 381 * - maxRate : maximum rate in bits per second, 382 * valid values are 32000 to 53400 bits/sec in 383 * wideband mode, and 32000 to 160000 bits/sec in 384 * super-wideband mode. 385 * 386 * Return value : 0 if successful 387 * -1 if error happens 388 */ 389 390 int16_t WebRtcIsac_SetMaxRate(ISACStruct* ISAC_main_inst, int32_t maxRate); 391 392 /****************************************************************************** 393 * WebRtcIsac_DecSampRate() 394 * Return the sampling rate of the decoded audio. 395 * 396 * Input: 397 * - ISAC_main_inst : iSAC instance 398 * 399 * Return value : sampling frequency in Hertz. 400 * 401 */ 402 403 uint16_t WebRtcIsac_DecSampRate(ISACStruct* ISAC_main_inst); 404 405 /****************************************************************************** 406 * WebRtcIsac_EncSampRate() 407 * 408 * Input: 409 * - ISAC_main_inst : iSAC instance 410 * 411 * Return value : sampling rate in Hertz. 412 * 413 */ 414 415 uint16_t WebRtcIsac_EncSampRate(ISACStruct* ISAC_main_inst); 416 417 /****************************************************************************** 418 * WebRtcIsac_SetDecSampRate() 419 * Set the sampling rate of the decoder. Initialization of the decoder WILL 420 * NOT overwrite the sampling rate of the encoder. The default value is 16 kHz 421 * which is set when the instance is created. 422 * 423 * Input: 424 * - ISAC_main_inst : iSAC instance 425 * - sampRate : sampling rate in Hertz. 426 * 427 * Return value : 0 if successful 428 * -1 if failed. 429 */ 430 431 int16_t WebRtcIsac_SetDecSampRate(ISACStruct* ISAC_main_inst, 432 uint16_t samp_rate_hz); 433 434 /****************************************************************************** 435 * WebRtcIsac_SetEncSampRate() 436 * Set the sampling rate of the encoder. Initialization of the encoder WILL 437 * NOT overwrite the sampling rate of the encoder. The default value is 16 kHz 438 * which is set when the instance is created. The encoding-mode and the 439 * bottleneck remain unchanged by this call, however, the maximum rate and 440 * maximum payload-size will reset to their default value. 441 * 442 * Input: 443 * - ISAC_main_inst : iSAC instance 444 * - sampRate : sampling rate in Hertz. 445 * 446 * Return value : 0 if successful 447 * -1 if failed. 448 */ 449 450 int16_t WebRtcIsac_SetEncSampRate(ISACStruct* ISAC_main_inst, 451 uint16_t sample_rate_hz); 452 453 /****************************************************************************** 454 * WebRtcIsac_GetNewBitStream(...) 455 * 456 * This function returns encoded data, with the recieved bwe-index in the 457 * stream. If the rate is set to a value less than bottleneck of codec 458 * the new bistream will be re-encoded with the given target rate. 459 * It should always return a complete packet, i.e. only called once 460 * even for 60 msec frames. 461 * 462 * NOTE 1! This function does not write in the ISACStruct, it is not allowed. 463 * NOTE 2! Currently not implemented for SWB mode. 464 * NOTE 3! Rates larger than the bottleneck of the codec will be limited 465 * to the current bottleneck. 466 * 467 * Input: 468 * - ISAC_main_inst : ISAC instance. 469 * - bweIndex : Index of bandwidth estimate to put in new 470 * bitstream 471 * - rate : target rate of the transcoder is bits/sec. 472 * Valid values are the accepted rate in iSAC, 473 * i.e. 10000 to 56000. 474 * - isRCU : if the new bit-stream is an RCU 475 * stream. Note that the rate parameter always indicates the target rate of the 476 * main payload, regardless of 'isRCU' value. 477 * 478 * Output: 479 * - encoded : The encoded data vector 480 * 481 * Return value : >0 - Length (in bytes) of coded data 482 * -1 - Error or called in SWB mode 483 * NOTE! No error code is written to 484 * the struct since it is only allowed to read 485 * the struct. 486 */ 487 int16_t WebRtcIsac_GetNewBitStream(ISACStruct* ISAC_main_inst, 488 int16_t bweIndex, 489 int16_t jitterInfo, 490 int32_t rate, 491 uint8_t* encoded, 492 int16_t isRCU); 493 494 /**************************************************************************** 495 * WebRtcIsac_GetDownLinkBwIndex(...) 496 * 497 * This function returns index representing the Bandwidth estimate from 498 * other side to this side. 499 * 500 * Input: 501 * - ISAC_main_inst : iSAC struct 502 * 503 * Output: 504 * - bweIndex : Bandwidth estimate to transmit to other side. 505 * 506 */ 507 508 int16_t WebRtcIsac_GetDownLinkBwIndex(ISACStruct* ISAC_main_inst, 509 int16_t* bweIndex, 510 int16_t* jitterInfo); 511 512 /**************************************************************************** 513 * WebRtcIsac_UpdateUplinkBw(...) 514 * 515 * This function takes an index representing the Bandwidth estimate from 516 * this side to other side and updates BWE. 517 * 518 * Input: 519 * - ISAC_main_inst : iSAC struct 520 * - bweIndex : Bandwidth estimate from other side. 521 * 522 */ 523 524 int16_t WebRtcIsac_UpdateUplinkBw(ISACStruct* ISAC_main_inst, int16_t bweIndex); 525 526 /**************************************************************************** 527 * WebRtcIsac_ReadBwIndex(...) 528 * 529 * This function returns the index of the Bandwidth estimate from the bitstream. 530 * 531 * Input: 532 * - encoded : Encoded bitstream 533 * 534 * Output: 535 * - frameLength : Length of frame in packet (in samples) 536 * - bweIndex : Bandwidth estimate in bitstream 537 * 538 */ 539 540 int16_t WebRtcIsac_ReadBwIndex(const uint8_t* encoded, int16_t* bweIndex); 541 542 /******************************************************************************* 543 * WebRtcIsac_GetNewFrameLen(...) 544 * 545 * returns the frame lenght (in samples) of the next packet. In the case of 546 * channel-adaptive mode, iSAC decides on its frame lenght based on the 547 * estimated bottleneck this allows a user to prepare for the next packet (at 548 * the encoder) 549 * 550 * The primary usage is in CE to make the iSAC works in channel-adaptive mode 551 * 552 * Input: 553 * - ISAC_main_inst : iSAC struct 554 * 555 * Return Value : frame lenght in samples 556 * 557 */ 558 559 int16_t WebRtcIsac_GetNewFrameLen(ISACStruct* ISAC_main_inst); 560 561 /**************************************************************************** 562 * WebRtcIsac_GetRedPayload(...) 563 * 564 * Populates "encoded" with the redundant payload of the recently encoded 565 * frame. This function has to be called once that WebRtcIsac_Encode(...) 566 * returns a positive value. Regardless of the frame-size this function will 567 * be called only once after encoding is completed. 568 * 569 * Input: 570 * - ISAC_main_inst : iSAC struct 571 * 572 * Output: 573 * - encoded : the encoded data vector 574 * 575 * 576 * Return value: 577 * : >0 - Length (in bytes) of coded data 578 * : -1 - Error 579 * 580 * 581 */ 582 int16_t WebRtcIsac_GetRedPayload(ISACStruct* ISAC_main_inst, uint8_t* encoded); 583 584 /**************************************************************************** 585 * WebRtcIsac_DecodeRcu(...) 586 * 587 * This function decodes a redundant (RCU) iSAC frame. Function is called in 588 * NetEq with a stored RCU payload i case of packet loss. Output speech length 589 * will be a multiple of 480 samples: 480 or 960 samples, 590 * depending on the framesize (30 or 60 ms). 591 * 592 * Input: 593 * - ISAC_main_inst : ISAC instance. 594 * - encoded : encoded ISAC RCU frame(s) 595 * - len : bytes in encoded vector 596 * 597 * Output: 598 * - decoded : The decoded vector 599 * 600 * Return value : >0 - number of samples in decoded vector 601 * -1 - Error 602 */ 603 int WebRtcIsac_DecodeRcu(ISACStruct* ISAC_main_inst, 604 const uint8_t* encoded, 605 size_t len, 606 int16_t* decoded, 607 int16_t* speechType); 608 609 /* If |inst| is a decoder but not an encoder: tell it what sample rate the 610 encoder is using, for bandwidth estimation purposes. */ 611 void WebRtcIsac_SetEncSampRateInDecoder(ISACStruct* inst, int sample_rate_hz); 612 613 #if defined(__cplusplus) 614 } 615 #endif 616 617 #endif /* MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_INCLUDE_ISAC_H_ */ 618