/* * Copyright (c) 2011 The WebRTC project authors. All Rights Reserved. * * Use of this source code is governed by a BSD-style license * that can be found in the LICENSE file in the root of the source * tree. An additional intellectual property rights grant can be found * in the file PATENTS. All contributing project authors may * be found in the AUTHORS file in the root of the source tree. */ #ifndef WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_FIX_INTERFACE_ISACFIX_H_ #define WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_FIX_INTERFACE_ISACFIX_H_ /* * Define the fixpoint numeric formats */ #include "typedefs.h" typedef struct { void *dummy; } ISACFIX_MainStruct; #if defined(__cplusplus) extern "C" { #endif /************************************************************************** * WebRtcIsacfix_AssignSize(...) * * Functions used when malloc is not allowed * Output the number of bytes needed to allocate for iSAC struct. * */ WebRtc_Word16 WebRtcIsacfix_AssignSize(int *sizeinbytes); /************************************************************************** * WebRtcIsacfix_Assign(...) * * Functions used when malloc is not allowed, it * places a struct at the given address. * * Input: * - *ISAC_main_inst : a pointer to the coder instance. * - ISACFIX_inst_Addr : address of the memory where a space is * for iSAC structure. * * Return value : 0 - Ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_Assign(ISACFIX_MainStruct **inst, void *ISACFIX_inst_Addr); /**************************************************************************** * WebRtcIsacfix_Create(...) * * This function creates an ISAC instance, which will contain the state * information for one coding/decoding channel. * * Input: * - *ISAC_main_inst : a pointer to the coder instance. * * Return value : 0 - Ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_Create(ISACFIX_MainStruct **ISAC_main_inst); /**************************************************************************** * WebRtcIsacfix_Free(...) * * This function frees the ISAC instance created at the beginning. * * Input: * - ISAC_main_inst : a ISAC instance. * * Return value : 0 - Ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_Free(ISACFIX_MainStruct *ISAC_main_inst); /**************************************************************************** * WebRtcIsacfix_EncoderInit(...) * * This function initializes an ISAC instance prior to the encoder calls. * * Input: * - ISAC_main_inst : ISAC instance. * - CodingMode : 0 - Bit rate and frame length are automatically * adjusted to available bandwidth on * transmission channel. * 1 - User sets a frame length and a target bit * rate which is taken as the maximum short-term * average bit rate. * * Return value : 0 - Ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_EncoderInit(ISACFIX_MainStruct *ISAC_main_inst, WebRtc_Word16 CodingMode); /**************************************************************************** * WebRtcIsacfix_Encode(...) * * This function encodes 10ms frame(s) and inserts it into a package. * Input speech length has to be 160 samples (10ms). The encoder buffers those * 10ms frames until it reaches the chosen Framesize (480 or 960 samples * corresponding to 30 or 60 ms frames), and then proceeds to the encoding. * * Input: * - ISAC_main_inst : ISAC instance. * - speechIn : input speech vector. * * Output: * - encoded : the encoded data vector * * Return value : >0 - Length (in bytes) of coded data * 0 - The buffer didn't reach the chosen framesize * so it keeps buffering speech samples. * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_Encode(ISACFIX_MainStruct *ISAC_main_inst, const WebRtc_Word16 *speechIn, WebRtc_Word16 *encoded); /**************************************************************************** * WebRtcIsacfix_EncodeNb(...) * * This function encodes 10ms narrow band (8 kHz sampling) frame(s) and inserts * it into a package. Input speech length has to be 80 samples (10ms). The encoder * interpolates into wide-band (16 kHz sampling) buffers those * 10ms frames until it reaches the chosen Framesize (480 or 960 wide-band samples * corresponding to 30 or 60 ms frames), and then proceeds to the encoding. * * The function is enabled if WEBRTC_ISAC_FIX_NB_CALLS_ENABLED is defined * * Input: * - ISAC_main_inst : ISAC instance. * - speechIn : input speech vector. * * Output: * - encoded : the encoded data vector * * Return value : >0 - Length (in bytes) of coded data * 0 - The buffer didn't reach the chosen framesize * so it keeps buffering speech samples. * -1 - Error */ #ifdef WEBRTC_ISAC_FIX_NB_CALLS_ENABLED WebRtc_Word16 WebRtcIsacfix_EncodeNb(ISACFIX_MainStruct *ISAC_main_inst, const WebRtc_Word16 *speechIn, WebRtc_Word16 *encoded); #endif // WEBRTC_ISAC_FIX_NB_CALLS_ENABLED /**************************************************************************** * WebRtcIsacfix_DecoderInit(...) * * This function initializes an ISAC instance prior to the decoder calls. * * Input: * - ISAC_main_inst : ISAC instance. * * Return value * : 0 - Ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_DecoderInit(ISACFIX_MainStruct *ISAC_main_inst); /**************************************************************************** * WebRtcIsacfix_UpdateBwEstimate1(...) * * This function updates the estimate of the bandwidth. * * Input: * - ISAC_main_inst : ISAC instance. * - encoded : encoded ISAC frame(s). * - packet_size : size of the packet. * - rtp_seq_number : the RTP number of the packet. * - arr_ts : the arrival time of the packet (from NetEq) * in samples. * * Return value : 0 - Ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_UpdateBwEstimate1(ISACFIX_MainStruct *ISAC_main_inst, const WebRtc_UWord16 *encoded, WebRtc_Word32 packet_size, WebRtc_UWord16 rtp_seq_number, WebRtc_UWord32 arr_ts); /**************************************************************************** * WebRtcIsacfix_UpdateBwEstimate(...) * * This function updates the estimate of the bandwidth. * * Input: * - ISAC_main_inst : ISAC instance. * - encoded : encoded ISAC frame(s). * - packet_size : size of the packet. * - rtp_seq_number : the RTP number of the packet. * - send_ts : the send time of the packet from RTP header, * in samples. * - arr_ts : the arrival time of the packet (from NetEq) * in samples. * * Return value : 0 - Ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_UpdateBwEstimate(ISACFIX_MainStruct *ISAC_main_inst, const WebRtc_UWord16 *encoded, WebRtc_Word32 packet_size, WebRtc_UWord16 rtp_seq_number, WebRtc_UWord32 send_ts, WebRtc_UWord32 arr_ts); /**************************************************************************** * WebRtcIsacfix_Decode(...) * * This function decodes an ISAC frame. Output speech length * will be a multiple of 480 samples: 480 or 960 samples, * depending on the framesize (30 or 60 ms). * * Input: * - ISAC_main_inst : ISAC instance. * - encoded : encoded ISAC frame(s) * - len : bytes in encoded vector * * Output: * - decoded : The decoded vector * * Return value : >0 - number of samples in decoded vector * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_Decode(ISACFIX_MainStruct *ISAC_main_inst, const WebRtc_UWord16 *encoded, WebRtc_Word16 len, WebRtc_Word16 *decoded, WebRtc_Word16 *speechType); /**************************************************************************** * WebRtcIsacfix_DecodeNb(...) * * This function decodes a ISAC frame in narrow-band (8 kHz sampling). * Output speech length will be a multiple of 240 samples: 240 or 480 samples, * depending on the framesize (30 or 60 ms). * * The function is enabled if WEBRTC_ISAC_FIX_NB_CALLS_ENABLED is defined * * Input: * - ISAC_main_inst : ISAC instance. * - encoded : encoded ISAC frame(s) * - len : bytes in encoded vector * * Output: * - decoded : The decoded vector * * Return value : >0 - number of samples in decoded vector * -1 - Error */ #ifdef WEBRTC_ISAC_FIX_NB_CALLS_ENABLED WebRtc_Word16 WebRtcIsacfix_DecodeNb(ISACFIX_MainStruct *ISAC_main_inst, const WebRtc_UWord16 *encoded, WebRtc_Word16 len, WebRtc_Word16 *decoded, WebRtc_Word16 *speechType); #endif // WEBRTC_ISAC_FIX_NB_CALLS_ENABLED /**************************************************************************** * WebRtcIsacfix_DecodePlcNb(...) * * This function conducts PLC for ISAC frame(s) in narrow-band (8kHz sampling). * Output speech length will be "240*noOfLostFrames" samples * that equevalent of "30*noOfLostFrames" millisecond. * * The function is enabled if WEBRTC_ISAC_FIX_NB_CALLS_ENABLED is defined * * Input: * - ISAC_main_inst : ISAC instance. * - noOfLostFrames : Number of PLC frames (240 sample=30ms) to produce * NOTE! Maximum number is 2 (480 samples = 60ms) * * Output: * - decoded : The decoded vector * * Return value : >0 - number of samples in decoded PLC vector * -1 - Error */ #ifdef WEBRTC_ISAC_FIX_NB_CALLS_ENABLED WebRtc_Word16 WebRtcIsacfix_DecodePlcNb(ISACFIX_MainStruct *ISAC_main_inst, WebRtc_Word16 *decoded, WebRtc_Word16 noOfLostFrames ); #endif // WEBRTC_ISAC_FIX_NB_CALLS_ENABLED /**************************************************************************** * WebRtcIsacfix_DecodePlc(...) * * This function conducts PLC for ISAC frame(s) in wide-band (16kHz sampling). * Output speech length will be "480*noOfLostFrames" samples * that is equevalent of "30*noOfLostFrames" millisecond. * * Input: * - ISAC_main_inst : ISAC instance. * - noOfLostFrames : Number of PLC frames (480sample = 30ms) * to produce * NOTE! Maximum number is 2 (960 samples = 60ms) * * Output: * - decoded : The decoded vector * * Return value : >0 - number of samples in decoded PLC vector * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_DecodePlc(ISACFIX_MainStruct *ISAC_main_inst, WebRtc_Word16 *decoded, WebRtc_Word16 noOfLostFrames ); /**************************************************************************** * WebRtcIsacfix_ReadFrameLen(...) * * This function returns the length of the frame represented in the packet. * * Input: * - encoded : Encoded bitstream * * Output: * - frameLength : Length of frame in packet (in samples) * */ WebRtc_Word16 WebRtcIsacfix_ReadFrameLen(const WebRtc_Word16* encoded, WebRtc_Word16* frameLength); /**************************************************************************** * WebRtcIsacfix_Control(...) * * This function sets the limit on the short-term average bit rate and the * frame length. Should be used only in Instantaneous mode. * * Input: * - ISAC_main_inst : ISAC instance. * - rate : limit on the short-term average bit rate, * in bits/second (between 10000 and 32000) * - framesize : number of milliseconds per frame (30 or 60) * * Return value : 0 - ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_Control(ISACFIX_MainStruct *ISAC_main_inst, WebRtc_Word16 rate, WebRtc_Word16 framesize); /**************************************************************************** * WebRtcIsacfix_ControlBwe(...) * * This function sets the initial values of bottleneck and frame-size if * iSAC is used in channel-adaptive mode. Through this API, users can * enforce a frame-size for all values of bottleneck. Then iSAC will not * automatically change the frame-size. * * * Input: * - ISAC_main_inst : ISAC instance. * - rateBPS : initial value of bottleneck in bits/second * 10000 <= rateBPS <= 32000 is accepted * - frameSizeMs : number of milliseconds per frame (30 or 60) * - enforceFrameSize : 1 to enforce the given frame-size through out * the adaptation process, 0 to let iSAC change * the frame-size if required. * * Return value : 0 - ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_ControlBwe(ISACFIX_MainStruct *ISAC_main_inst, WebRtc_Word16 rateBPS, WebRtc_Word16 frameSizeMs, WebRtc_Word16 enforceFrameSize); /**************************************************************************** * WebRtcIsacfix_version(...) * * This function returns the version number. * * Output: * - version : Pointer to character string * */ void WebRtcIsacfix_version(char *version); /**************************************************************************** * WebRtcIsacfix_GetErrorCode(...) * * This function can be used to check the error code of an iSAC instance. When * a function returns -1 a error code will be set for that instance. The * function below extract the code of the last error that occured in the * specified instance. * * Input: * - ISAC_main_inst : ISAC instance * * Return value : Error code */ WebRtc_Word16 WebRtcIsacfix_GetErrorCode(ISACFIX_MainStruct *ISAC_main_inst); /**************************************************************************** * WebRtcIsacfix_GetUplinkBw(...) * * This function return iSAC send bitrate * * Input: * - ISAC_main_inst : iSAC instance * * Return value : <0 Error code * else bitrate */ WebRtc_Word32 WebRtcIsacfix_GetUplinkBw(ISACFIX_MainStruct *ISAC_main_inst); /**************************************************************************** * WebRtcIsacfix_SetMaxPayloadSize(...) * * This function sets a limit for the maximum payload size of iSAC. The same * value is used both for 30 and 60 msec packets. * The absolute max will be valid until next time the function is called. * NOTE! This function may override the function WebRtcIsacfix_SetMaxRate() * * Input: * - ISAC_main_inst : iSAC instance * - maxPayloadBytes : maximum size of the payload in bytes * valid values are between 100 and 400 bytes * * * Return value : 0 if sucessful * -1 if error happens */ WebRtc_Word16 WebRtcIsacfix_SetMaxPayloadSize(ISACFIX_MainStruct *ISAC_main_inst, WebRtc_Word16 maxPayloadBytes); /**************************************************************************** * WebRtcIsacfix_SetMaxRate(...) * * This function sets the maximum rate which the codec may not exceed for a * singel packet. The maximum rate is set in bits per second. * The codec has an absolute maximum rate of 53400 bits per second (200 bytes * per 30 msec). * It is possible to set a maximum rate between 32000 and 53400 bits per second. * * The rate limit is valid until next time the function is called. * * NOTE! Packet size will never go above the value set if calling * WebRtcIsacfix_SetMaxPayloadSize() (default max packet size is 400 bytes). * * Input: * - ISAC_main_inst : iSAC instance * - maxRateInBytes : maximum rate in bits per second, * valid values are 32000 to 53400 bits * * Return value : 0 if sucessful * -1 if error happens */ WebRtc_Word16 WebRtcIsacfix_SetMaxRate(ISACFIX_MainStruct *ISAC_main_inst, WebRtc_Word32 maxRate); /**************************************************************************** * WebRtcIsacfix_CreateInternal(...) * * This function creates the memory that is used to store data in the encoder * * Input: * - *ISAC_main_inst : a pointer to the coder instance. * * Return value : 0 - Ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_CreateInternal(ISACFIX_MainStruct *ISAC_main_inst); /**************************************************************************** * WebRtcIsacfix_FreeInternal(...) * * This function frees the internal memory for storing encoder data. * * Input: * - ISAC_main_inst : an ISAC instance. * * Return value : 0 - Ok * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_FreeInternal(ISACFIX_MainStruct *ISAC_main_inst); /**************************************************************************** * WebRtcIsacfix_GetNewBitStream(...) * * This function returns encoded data, with the recieved bwe-index in the * stream. It should always return a complete packet, i.e. only called once * even for 60 msec frames * * Input: * - ISAC_main_inst : ISAC instance. * - bweIndex : index of bandwidth estimate to put in new bitstream * - scale : factor for rate change (0.4 ~=> half the rate, 1 no change). * * Output: * - encoded : the encoded data vector * * Return value : >0 - Length (in bytes) of coded data * -1 - Error */ WebRtc_Word16 WebRtcIsacfix_GetNewBitStream(ISACFIX_MainStruct *ISAC_main_inst, WebRtc_Word16 bweIndex, float scale, WebRtc_Word16 *encoded); /**************************************************************************** * WebRtcIsacfix_GetDownLinkBwIndex(...) * * This function returns index representing the Bandwidth estimate from * other side to this side. * * Input: * - ISAC_main_inst : iSAC struct * * Output: * - rateIndex : Bandwidth estimate to transmit to other side. * */ WebRtc_Word16 WebRtcIsacfix_GetDownLinkBwIndex(ISACFIX_MainStruct* ISAC_main_inst, WebRtc_Word16* rateIndex); /**************************************************************************** * WebRtcIsacfix_UpdateUplinkBw(...) * * This function takes an index representing the Bandwidth estimate from * this side to other side and updates BWE. * * Input: * - ISAC_main_inst : iSAC struct * - rateIndex : Bandwidth estimate from other side. * */ WebRtc_Word16 WebRtcIsacfix_UpdateUplinkBw(ISACFIX_MainStruct* ISAC_main_inst, WebRtc_Word16 rateIndex); /**************************************************************************** * WebRtcIsacfix_ReadBwIndex(...) * * This function returns the index of the Bandwidth estimate from the bitstream. * * Input: * - encoded : Encoded bitstream * * Output: * - rateIndex : Bandwidth estimate in bitstream * */ WebRtc_Word16 WebRtcIsacfix_ReadBwIndex(const WebRtc_Word16* encoded, WebRtc_Word16* rateIndex); /**************************************************************************** * WebRtcIsacfix_GetNewFrameLen(...) * * This function return the next frame length (in samples) of iSAC. * * Input: * -ISAC_main_inst : iSAC instance * * Return value : frame lenght in samples */ WebRtc_Word16 WebRtcIsacfix_GetNewFrameLen(ISACFIX_MainStruct *ISAC_main_inst); #if defined(__cplusplus) } #endif #endif /* WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_FIX_INTERFACE_ISACFIX_H_ */