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