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_FIX_INCLUDE_ISACFIX_H_ 12 #define WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_FIX_INCLUDE_ISACFIX_H_ 13 14 #include <stddef.h> 15 16 #include "webrtc/modules/audio_coding/codecs/isac/bandwidth_info.h" 17 #include "webrtc/typedefs.h" 18 19 typedef struct { 20 void *dummy; 21 } ISACFIX_MainStruct; 22 23 24 #if defined(__cplusplus) 25 extern "C" { 26 #endif 27 28 29 /************************************************************************** 30 * WebRtcIsacfix_AssignSize(...) 31 * 32 * Functions used when malloc is not allowed 33 * Output the number of bytes needed to allocate for iSAC struct. 34 * 35 */ 36 37 int16_t WebRtcIsacfix_AssignSize(int *sizeinbytes); 38 39 /************************************************************************** 40 * WebRtcIsacfix_Assign(...) 41 * 42 * Functions used when malloc is not allowed, it 43 * places a struct at the given address. 44 * 45 * Input: 46 * - *ISAC_main_inst : a pointer to the coder instance. 47 * - ISACFIX_inst_Addr : address of the memory where a space is 48 * for iSAC structure. 49 * 50 * Return value : 0 - Ok 51 * -1 - Error 52 */ 53 54 int16_t WebRtcIsacfix_Assign(ISACFIX_MainStruct **inst, 55 void *ISACFIX_inst_Addr); 56 57 /**************************************************************************** 58 * WebRtcIsacfix_Create(...) 59 * 60 * This function creates an ISAC instance, which will contain the state 61 * information for one coding/decoding channel. 62 * 63 * Input: 64 * - *ISAC_main_inst : a pointer to the coder instance. 65 * 66 * Return value : 0 - Ok 67 * -1 - Error 68 */ 69 70 int16_t WebRtcIsacfix_Create(ISACFIX_MainStruct **ISAC_main_inst); 71 72 73 /**************************************************************************** 74 * WebRtcIsacfix_Free(...) 75 * 76 * This function frees the ISAC instance created at the beginning. 77 * 78 * Input: 79 * - ISAC_main_inst : a ISAC instance. 80 * 81 * Return value : 0 - Ok 82 * -1 - Error 83 */ 84 85 int16_t WebRtcIsacfix_Free(ISACFIX_MainStruct *ISAC_main_inst); 86 87 88 /**************************************************************************** 89 * WebRtcIsacfix_EncoderInit(...) 90 * 91 * This function initializes an ISAC instance prior to the encoder calls. 92 * 93 * Input: 94 * - ISAC_main_inst : ISAC instance. 95 * - CodingMode : 0 - Bit rate and frame length are automatically 96 * adjusted to available bandwidth on 97 * transmission channel. 98 * 1 - User sets a frame length and a target bit 99 * rate which is taken as the maximum short-term 100 * average bit rate. 101 * 102 * Return value : 0 - Ok 103 * -1 - Error 104 */ 105 106 int16_t WebRtcIsacfix_EncoderInit(ISACFIX_MainStruct *ISAC_main_inst, 107 int16_t CodingMode); 108 109 110 /**************************************************************************** 111 * WebRtcIsacfix_Encode(...) 112 * 113 * This function encodes 10ms frame(s) and inserts it into a package. 114 * Input speech length has to be 160 samples (10ms). The encoder buffers those 115 * 10ms frames until it reaches the chosen Framesize (480 or 960 samples 116 * corresponding to 30 or 60 ms frames), and then proceeds to the encoding. 117 * 118 * Input: 119 * - ISAC_main_inst : ISAC instance. 120 * - speechIn : input speech vector. 121 * 122 * Output: 123 * - encoded : the encoded data vector 124 * 125 * Return value : >0 - Length (in bytes) of coded data 126 * 0 - The buffer didn't reach the chosen framesize 127 * so it keeps buffering speech samples. 128 * -1 - Error 129 */ 130 131 int WebRtcIsacfix_Encode(ISACFIX_MainStruct *ISAC_main_inst, 132 const int16_t *speechIn, 133 uint8_t* encoded); 134 135 136 137 /**************************************************************************** 138 * WebRtcIsacfix_EncodeNb(...) 139 * 140 * This function encodes 10ms narrow band (8 kHz sampling) frame(s) and inserts 141 * it into a package. Input speech length has to be 80 samples (10ms). The encoder 142 * interpolates into wide-band (16 kHz sampling) buffers those 143 * 10ms frames until it reaches the chosen Framesize (480 or 960 wide-band samples 144 * corresponding to 30 or 60 ms frames), and then proceeds to the encoding. 145 * 146 * The function is enabled if WEBRTC_ISAC_FIX_NB_CALLS_ENABLED is defined 147 * 148 * Input: 149 * - ISAC_main_inst : ISAC instance. 150 * - speechIn : input speech vector. 151 * 152 * Output: 153 * - encoded : the encoded data vector 154 * 155 * Return value : >0 - Length (in bytes) of coded data 156 * 0 - The buffer didn't reach the chosen framesize 157 * so it keeps buffering speech samples. 158 * -1 - Error 159 */ 160 161 162 #ifdef WEBRTC_ISAC_FIX_NB_CALLS_ENABLED 163 int16_t WebRtcIsacfix_EncodeNb(ISACFIX_MainStruct *ISAC_main_inst, 164 const int16_t *speechIn, 165 int16_t *encoded); 166 #endif // WEBRTC_ISAC_FIX_NB_CALLS_ENABLED 167 168 169 170 /**************************************************************************** 171 * WebRtcIsacfix_DecoderInit(...) 172 * 173 * This function initializes an ISAC instance prior to the decoder calls. 174 * 175 * Input: 176 * - ISAC_main_inst : ISAC instance. 177 */ 178 179 void WebRtcIsacfix_DecoderInit(ISACFIX_MainStruct* ISAC_main_inst); 180 181 /**************************************************************************** 182 * WebRtcIsacfix_UpdateBwEstimate1(...) 183 * 184 * This function updates the estimate of the bandwidth. 185 * 186 * Input: 187 * - ISAC_main_inst : ISAC instance. 188 * - encoded : encoded ISAC frame(s). 189 * - packet_size : size of the packet in bytes. 190 * - rtp_seq_number : the RTP number of the packet. 191 * - arr_ts : the arrival time of the packet (from NetEq) 192 * in samples. 193 * 194 * Return value : 0 - Ok 195 * -1 - Error 196 */ 197 198 int16_t WebRtcIsacfix_UpdateBwEstimate1(ISACFIX_MainStruct *ISAC_main_inst, 199 const uint8_t* encoded, 200 size_t packet_size, 201 uint16_t rtp_seq_number, 202 uint32_t arr_ts); 203 204 /**************************************************************************** 205 * WebRtcIsacfix_UpdateBwEstimate(...) 206 * 207 * This function updates the estimate of the bandwidth. 208 * 209 * Input: 210 * - ISAC_main_inst : ISAC instance. 211 * - encoded : encoded ISAC frame(s). 212 * - packet_size : size of the packet in bytes. 213 * - rtp_seq_number : the RTP number of the packet. 214 * - send_ts : the send time of the packet from RTP header, 215 * in samples. 216 * - arr_ts : the arrival time of the packet (from NetEq) 217 * in samples. 218 * 219 * Return value : 0 - Ok 220 * -1 - Error 221 */ 222 223 int16_t WebRtcIsacfix_UpdateBwEstimate(ISACFIX_MainStruct *ISAC_main_inst, 224 const uint8_t* encoded, 225 size_t packet_size, 226 uint16_t rtp_seq_number, 227 uint32_t send_ts, 228 uint32_t arr_ts); 229 230 /**************************************************************************** 231 * WebRtcIsacfix_Decode(...) 232 * 233 * This function decodes an ISAC frame. Output speech length 234 * will be a multiple of 480 samples: 480 or 960 samples, 235 * depending on the framesize (30 or 60 ms). 236 * 237 * Input: 238 * - ISAC_main_inst : ISAC instance. 239 * - encoded : encoded ISAC frame(s) 240 * - len : bytes in encoded vector 241 * 242 * Output: 243 * - decoded : The decoded vector 244 * 245 * Return value : >0 - number of samples in decoded vector 246 * -1 - Error 247 */ 248 249 int WebRtcIsacfix_Decode(ISACFIX_MainStruct *ISAC_main_inst, 250 const uint8_t* encoded, 251 size_t len, 252 int16_t *decoded, 253 int16_t *speechType); 254 255 256 /**************************************************************************** 257 * WebRtcIsacfix_DecodeNb(...) 258 * 259 * This function decodes a ISAC frame in narrow-band (8 kHz sampling). 260 * Output speech length will be a multiple of 240 samples: 240 or 480 samples, 261 * depending on the framesize (30 or 60 ms). 262 * 263 * The function is enabled if WEBRTC_ISAC_FIX_NB_CALLS_ENABLED is defined 264 * 265 * Input: 266 * - ISAC_main_inst : ISAC instance. 267 * - encoded : encoded ISAC frame(s) 268 * - len : bytes in encoded vector 269 * 270 * Output: 271 * - decoded : The decoded vector 272 * 273 * Return value : >0 - number of samples in decoded vector 274 * -1 - Error 275 */ 276 277 #ifdef WEBRTC_ISAC_FIX_NB_CALLS_ENABLED 278 int WebRtcIsacfix_DecodeNb(ISACFIX_MainStruct *ISAC_main_inst, 279 const uint16_t *encoded, 280 size_t len, 281 int16_t *decoded, 282 int16_t *speechType); 283 #endif // WEBRTC_ISAC_FIX_NB_CALLS_ENABLED 284 285 286 /**************************************************************************** 287 * WebRtcIsacfix_DecodePlcNb(...) 288 * 289 * This function conducts PLC for ISAC frame(s) in narrow-band (8kHz sampling). 290 * Output speech length will be "240*noOfLostFrames" samples 291 * that equevalent of "30*noOfLostFrames" millisecond. 292 * 293 * The function is enabled if WEBRTC_ISAC_FIX_NB_CALLS_ENABLED is defined 294 * 295 * Input: 296 * - ISAC_main_inst : ISAC instance. 297 * - noOfLostFrames : Number of PLC frames (240 sample=30ms) to produce 298 * NOTE! Maximum number is 2 (480 samples = 60ms) 299 * 300 * Output: 301 * - decoded : The decoded vector 302 * 303 * Return value : Number of samples in decoded PLC vector 304 */ 305 306 #ifdef WEBRTC_ISAC_FIX_NB_CALLS_ENABLED 307 size_t WebRtcIsacfix_DecodePlcNb(ISACFIX_MainStruct *ISAC_main_inst, 308 int16_t *decoded, 309 size_t noOfLostFrames); 310 #endif // WEBRTC_ISAC_FIX_NB_CALLS_ENABLED 311 312 313 314 315 /**************************************************************************** 316 * WebRtcIsacfix_DecodePlc(...) 317 * 318 * This function conducts PLC for ISAC frame(s) in wide-band (16kHz sampling). 319 * Output speech length will be "480*noOfLostFrames" samples 320 * that is equevalent of "30*noOfLostFrames" millisecond. 321 * 322 * Input: 323 * - ISAC_main_inst : ISAC instance. 324 * - noOfLostFrames : Number of PLC frames (480sample = 30ms) 325 * to produce 326 * NOTE! Maximum number is 2 (960 samples = 60ms) 327 * 328 * Output: 329 * - decoded : The decoded vector 330 * 331 * Return value : Number of samples in decoded PLC vector 332 */ 333 334 size_t WebRtcIsacfix_DecodePlc(ISACFIX_MainStruct *ISAC_main_inst, 335 int16_t *decoded, 336 size_t noOfLostFrames ); 337 338 339 /**************************************************************************** 340 * WebRtcIsacfix_ReadFrameLen(...) 341 * 342 * This function returns the length of the frame represented in the packet. 343 * 344 * Input: 345 * - encoded : Encoded bitstream 346 * - encoded_len_bytes : Length of the bitstream in bytes. 347 * 348 * Output: 349 * - frameLength : Length of frame in packet (in samples) 350 * 351 */ 352 353 int16_t WebRtcIsacfix_ReadFrameLen(const uint8_t* encoded, 354 size_t encoded_len_bytes, 355 size_t* frameLength); 356 357 /**************************************************************************** 358 * WebRtcIsacfix_Control(...) 359 * 360 * This function sets the limit on the short-term average bit rate and the 361 * frame length. Should be used only in Instantaneous mode. 362 * 363 * Input: 364 * - ISAC_main_inst : ISAC instance. 365 * - rate : limit on the short-term average bit rate, 366 * in bits/second (between 10000 and 32000) 367 * - framesize : number of milliseconds per frame (30 or 60) 368 * 369 * Return value : 0 - ok 370 * -1 - Error 371 */ 372 373 int16_t WebRtcIsacfix_Control(ISACFIX_MainStruct *ISAC_main_inst, 374 int16_t rate, 375 int framesize); 376 377 void WebRtcIsacfix_SetInitialBweBottleneck(ISACFIX_MainStruct* ISAC_main_inst, 378 int bottleneck_bits_per_second); 379 380 /**************************************************************************** 381 * WebRtcIsacfix_ControlBwe(...) 382 * 383 * This function sets the initial values of bottleneck and frame-size if 384 * iSAC is used in channel-adaptive mode. Through this API, users can 385 * enforce a frame-size for all values of bottleneck. Then iSAC will not 386 * automatically change the frame-size. 387 * 388 * 389 * Input: 390 * - ISAC_main_inst : ISAC instance. 391 * - rateBPS : initial value of bottleneck in bits/second 392 * 10000 <= rateBPS <= 32000 is accepted 393 * - frameSizeMs : number of milliseconds per frame (30 or 60) 394 * - enforceFrameSize : 1 to enforce the given frame-size through out 395 * the adaptation process, 0 to let iSAC change 396 * the frame-size if required. 397 * 398 * Return value : 0 - ok 399 * -1 - Error 400 */ 401 402 int16_t WebRtcIsacfix_ControlBwe(ISACFIX_MainStruct *ISAC_main_inst, 403 int16_t rateBPS, 404 int frameSizeMs, 405 int16_t enforceFrameSize); 406 407 408 409 /**************************************************************************** 410 * WebRtcIsacfix_version(...) 411 * 412 * This function returns the version number. 413 * 414 * Output: 415 * - version : Pointer to character string 416 * 417 */ 418 419 void WebRtcIsacfix_version(char *version); 420 421 422 /**************************************************************************** 423 * WebRtcIsacfix_GetErrorCode(...) 424 * 425 * This function can be used to check the error code of an iSAC instance. When 426 * a function returns -1 a error code will be set for that instance. The 427 * function below extract the code of the last error that occured in the 428 * specified instance. 429 * 430 * Input: 431 * - ISAC_main_inst : ISAC instance 432 * 433 * Return value : Error code 434 */ 435 436 int16_t WebRtcIsacfix_GetErrorCode(ISACFIX_MainStruct *ISAC_main_inst); 437 438 439 /**************************************************************************** 440 * WebRtcIsacfix_GetUplinkBw(...) 441 * 442 * This function return iSAC send bitrate 443 * 444 * Input: 445 * - ISAC_main_inst : iSAC instance 446 * 447 * Return value : <0 Error code 448 * else bitrate 449 */ 450 451 int32_t WebRtcIsacfix_GetUplinkBw(ISACFIX_MainStruct *ISAC_main_inst); 452 453 454 /**************************************************************************** 455 * WebRtcIsacfix_SetMaxPayloadSize(...) 456 * 457 * This function sets a limit for the maximum payload size of iSAC. The same 458 * value is used both for 30 and 60 msec packets. 459 * The absolute max will be valid until next time the function is called. 460 * NOTE! This function may override the function WebRtcIsacfix_SetMaxRate() 461 * 462 * Input: 463 * - ISAC_main_inst : iSAC instance 464 * - maxPayloadBytes : maximum size of the payload in bytes 465 * valid values are between 100 and 400 bytes 466 * 467 * 468 * Return value : 0 if sucessful 469 * -1 if error happens 470 */ 471 472 int16_t WebRtcIsacfix_SetMaxPayloadSize(ISACFIX_MainStruct *ISAC_main_inst, 473 int16_t maxPayloadBytes); 474 475 476 /**************************************************************************** 477 * WebRtcIsacfix_SetMaxRate(...) 478 * 479 * This function sets the maximum rate which the codec may not exceed for a 480 * singel packet. The maximum rate is set in bits per second. 481 * The codec has an absolute maximum rate of 53400 bits per second (200 bytes 482 * per 30 msec). 483 * It is possible to set a maximum rate between 32000 and 53400 bits per second. 484 * 485 * The rate limit is valid until next time the function is called. 486 * 487 * NOTE! Packet size will never go above the value set if calling 488 * WebRtcIsacfix_SetMaxPayloadSize() (default max packet size is 400 bytes). 489 * 490 * Input: 491 * - ISAC_main_inst : iSAC instance 492 * - maxRateInBytes : maximum rate in bits per second, 493 * valid values are 32000 to 53400 bits 494 * 495 * Return value : 0 if sucessful 496 * -1 if error happens 497 */ 498 499 int16_t WebRtcIsacfix_SetMaxRate(ISACFIX_MainStruct *ISAC_main_inst, 500 int32_t maxRate); 501 502 /**************************************************************************** 503 * WebRtcIsacfix_CreateInternal(...) 504 * 505 * This function creates the memory that is used to store data in the encoder 506 * 507 * Input: 508 * - *ISAC_main_inst : a pointer to the coder instance. 509 * 510 * Return value : 0 - Ok 511 * -1 - Error 512 */ 513 514 int16_t WebRtcIsacfix_CreateInternal(ISACFIX_MainStruct *ISAC_main_inst); 515 516 517 /**************************************************************************** 518 * WebRtcIsacfix_FreeInternal(...) 519 * 520 * This function frees the internal memory for storing encoder data. 521 * 522 * Input: 523 * - ISAC_main_inst : an ISAC instance. 524 * 525 * Return value : 0 - Ok 526 * -1 - Error 527 */ 528 529 int16_t WebRtcIsacfix_FreeInternal(ISACFIX_MainStruct *ISAC_main_inst); 530 531 532 /**************************************************************************** 533 * WebRtcIsacfix_GetNewBitStream(...) 534 * 535 * This function returns encoded data, with the recieved bwe-index in the 536 * stream. It should always return a complete packet, i.e. only called once 537 * even for 60 msec frames 538 * 539 * Input: 540 * - ISAC_main_inst : ISAC instance. 541 * - bweIndex : index of bandwidth estimate to put in new bitstream 542 * - scale : factor for rate change (0.4 ~=> half the rate, 1 no change). 543 * 544 * Output: 545 * - encoded : the encoded data vector 546 * 547 * Return value : >0 - Length (in bytes) of coded data 548 * -1 - Error 549 */ 550 551 int16_t WebRtcIsacfix_GetNewBitStream(ISACFIX_MainStruct *ISAC_main_inst, 552 int16_t bweIndex, 553 float scale, 554 uint8_t* encoded); 555 556 557 /**************************************************************************** 558 * WebRtcIsacfix_GetDownLinkBwIndex(...) 559 * 560 * This function returns index representing the Bandwidth estimate from 561 * other side to this side. 562 * 563 * Input: 564 * - ISAC_main_inst : iSAC struct 565 * 566 * Output: 567 * - rateIndex : Bandwidth estimate to transmit to other side. 568 * 569 */ 570 571 int16_t WebRtcIsacfix_GetDownLinkBwIndex(ISACFIX_MainStruct* ISAC_main_inst, 572 int16_t* rateIndex); 573 574 575 /**************************************************************************** 576 * WebRtcIsacfix_UpdateUplinkBw(...) 577 * 578 * This function takes an index representing the Bandwidth estimate from 579 * this side to other side and updates BWE. 580 * 581 * Input: 582 * - ISAC_main_inst : iSAC struct 583 * - rateIndex : Bandwidth estimate from other side. 584 * 585 */ 586 587 int16_t WebRtcIsacfix_UpdateUplinkBw(ISACFIX_MainStruct* ISAC_main_inst, 588 int16_t rateIndex); 589 590 591 /**************************************************************************** 592 * WebRtcIsacfix_ReadBwIndex(...) 593 * 594 * This function returns the index of the Bandwidth estimate from the bitstream. 595 * 596 * Input: 597 * - encoded : Encoded bitstream 598 * - encoded_len_bytes : Length of the bitstream in bytes. 599 * 600 * Output: 601 * - rateIndex : Bandwidth estimate in bitstream 602 * 603 */ 604 605 int16_t WebRtcIsacfix_ReadBwIndex(const uint8_t* encoded, 606 size_t encoded_len_bytes, 607 int16_t* rateIndex); 608 609 610 /**************************************************************************** 611 * WebRtcIsacfix_GetNewFrameLen(...) 612 * 613 * This function return the next frame length (in samples) of iSAC. 614 * 615 * Input: 616 * -ISAC_main_inst : iSAC instance 617 * 618 * Return value : frame lenght in samples 619 */ 620 621 int16_t WebRtcIsacfix_GetNewFrameLen(ISACFIX_MainStruct *ISAC_main_inst); 622 623 /* Fills in an IsacBandwidthInfo struct. */ 624 void WebRtcIsacfix_GetBandwidthInfo(ISACFIX_MainStruct* ISAC_main_inst, 625 IsacBandwidthInfo* bwinfo); 626 627 /* Uses the values from an IsacBandwidthInfo struct. */ 628 void WebRtcIsacfix_SetBandwidthInfo(ISACFIX_MainStruct* ISAC_main_inst, 629 const IsacBandwidthInfo* bwinfo); 630 631 #if defined(__cplusplus) 632 } 633 #endif 634 635 636 637 #endif /* WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_FIX_INCLUDE_ISACFIX_H_ */ 638