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