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