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