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/*
12 * bandwidth_estimator.h
13 *
14 * This header file contains the API for the Bandwidth Estimator
15 * designed for iSAC.
16 *
17 */
18
19#ifndef WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_SOURCE_BANDWIDTH_ESTIMATOR_H_
20#define WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_SOURCE_BANDWIDTH_ESTIMATOR_H_
21
22#include "structs.h"
23#include "settings.h"
24
25
26#define MIN_ISAC_BW     10000
27#define MIN_ISAC_BW_LB  10000
28#define MIN_ISAC_BW_UB  25000
29
30#define MAX_ISAC_BW     56000
31#define MAX_ISAC_BW_UB  32000
32#define MAX_ISAC_BW_LB  32000
33
34#define MIN_ISAC_MD     5
35#define MAX_ISAC_MD     25
36
37// assumed header size, in bytes; we don't know the exact number
38// (header compression may be used)
39#define HEADER_SIZE        35
40
41// Initial Frame-Size, in ms, for Wideband & Super-Wideband Mode
42#define INIT_FRAME_LEN_WB  60
43#define INIT_FRAME_LEN_SWB 30
44
45// Initial Bottleneck Estimate, in bits/sec, for
46// Wideband & Super-wideband mode
47#define INIT_BN_EST_WB     20e3f
48#define INIT_BN_EST_SWB    56e3f
49
50// Initial Header rate (header rate depends on frame-size),
51// in bits/sec, for Wideband & Super-Wideband mode.
52#define INIT_HDR_RATE_WB                                                \
53  ((float)HEADER_SIZE * 8.0f * 1000.0f / (float)INIT_FRAME_LEN_WB)
54#define INIT_HDR_RATE_SWB                                               \
55  ((float)HEADER_SIZE * 8.0f * 1000.0f / (float)INIT_FRAME_LEN_SWB)
56
57// number of packets in a row for a high rate burst
58#define BURST_LEN       3
59
60// ms, max time between two full bursts
61#define BURST_INTERVAL  500
62
63// number of packets in a row for initial high rate burst
64#define INIT_BURST_LEN  5
65
66// bits/s, rate for the first BURST_LEN packets
67#define INIT_RATE_WB       INIT_BN_EST_WB
68#define INIT_RATE_SWB      INIT_BN_EST_SWB
69
70
71#if defined(__cplusplus)
72extern "C" {
73#endif
74
75  /* This function initializes the struct                    */
76  /* to be called before using the struct for anything else  */
77  /* returns 0 if everything went fine, -1 otherwise         */
78  WebRtc_Word32 WebRtcIsac_InitBandwidthEstimator(
79      BwEstimatorstr*           bwest_str,
80      enum IsacSamplingRate encoderSampRate,
81      enum IsacSamplingRate decoderSampRate);
82
83  /* This function updates the receiving estimate                                                      */
84  /* Parameters:                                                                                       */
85  /* rtp_number    - value from RTP packet, from NetEq                                                 */
86  /* frame length  - length of signal frame in ms, from iSAC decoder                                   */
87  /* send_ts       - value in RTP header giving send time in samples                                   */
88  /* arr_ts        - value given by timeGetTime() time of arrival in samples of packet from NetEq      */
89  /* pksize        - size of packet in bytes, from NetEq                                               */
90  /* Index         - integer (range 0...23) indicating bottle neck & jitter as estimated by other side */
91  /* returns 0 if everything went fine, -1 otherwise                                                   */
92  WebRtc_Word16 WebRtcIsac_UpdateBandwidthEstimator(
93      BwEstimatorstr*    bwest_str,
94      const WebRtc_UWord16 rtp_number,
95      const WebRtc_Word32  frame_length,
96      const WebRtc_UWord32 send_ts,
97      const WebRtc_UWord32 arr_ts,
98      const WebRtc_Word32  pksize);
99
100  /* Update receiving estimates. Used when we only receive BWE index, no iSAC data packet. */
101  WebRtc_Word16 WebRtcIsac_UpdateUplinkBwImpl(
102      BwEstimatorstr*           bwest_str,
103      WebRtc_Word16               Index,
104      enum IsacSamplingRate encoderSamplingFreq);
105
106  /* Returns the bandwidth/jitter estimation code (integer 0...23) to put in the sending iSAC payload */
107  WebRtc_UWord16 WebRtcIsac_GetDownlinkBwJitIndexImpl(
108      BwEstimatorstr*           bwest_str,
109      WebRtc_Word16*              bottleneckIndex,
110      WebRtc_Word16*              jitterInfo,
111      enum IsacSamplingRate decoderSamplingFreq);
112
113  /* Returns the bandwidth estimation (in bps) */
114  WebRtc_Word32 WebRtcIsac_GetDownlinkBandwidth(
115      const BwEstimatorstr *bwest_str);
116
117  /* Returns the max delay (in ms) */
118  WebRtc_Word32 WebRtcIsac_GetDownlinkMaxDelay(
119      const BwEstimatorstr *bwest_str);
120
121  /* Returns the bandwidth that iSAC should send with in bps */
122  void WebRtcIsac_GetUplinkBandwidth(
123      const BwEstimatorstr* bwest_str,
124      WebRtc_Word32*          bitRate);
125
126  /* Returns the max delay value from the other side in ms */
127  WebRtc_Word32 WebRtcIsac_GetUplinkMaxDelay(
128      const BwEstimatorstr *bwest_str);
129
130
131  /*
132   * update amount of data in bottle neck buffer and burst handling
133   * returns minimum payload size (bytes)
134   */
135  int WebRtcIsac_GetMinBytes(
136      RateModel*         State,
137      int                StreamSize,    /* bytes in bitstream */
138      const int          FrameLen,      /* ms per frame */
139      const double       BottleNeck,    /* bottle neck rate; excl headers (bps) */
140      const double       DelayBuildUp,  /* max delay from bottleneck buffering (ms) */
141      enum ISACBandwidth bandwidth
142      /*,WebRtc_Word16        frequentLargePackets*/);
143
144  /*
145   * update long-term average bitrate and amount of data in buffer
146   */
147  void WebRtcIsac_UpdateRateModel(
148      RateModel*   State,
149      int          StreamSize,                /* bytes in bitstream */
150      const int    FrameSamples,        /* samples per frame */
151      const double BottleNeck);       /* bottle neck rate; excl headers (bps) */
152
153
154  void WebRtcIsac_InitRateModel(
155      RateModel *State);
156
157  /* Returns the new framelength value (input argument: bottle_neck) */
158  int WebRtcIsac_GetNewFrameLength(
159      double bottle_neck,
160      int    current_framelength);
161
162  /* Returns the new SNR value (input argument: bottle_neck) */
163  double WebRtcIsac_GetSnr(
164      double bottle_neck,
165      int    new_framelength);
166
167
168  WebRtc_Word16 WebRtcIsac_UpdateUplinkJitter(
169      BwEstimatorstr*              bwest_str,
170      WebRtc_Word32                  index);
171
172#if defined(__cplusplus)
173}
174#endif
175
176
177#endif /* WEBRTC_MODULES_AUDIO_CODING_CODECS_ISAC_MAIN_SOURCE_BANDWIDTH_ESTIMATOR_H_ */
178