1 /*
2  *  Copyright (c) 2012 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 // This class estimates the incoming available bandwidth.
12 
13 #ifndef WEBRTC_MODULES_REMOTE_BITRATE_ESTIMATOR_INCLUDE_REMOTE_BITRATE_ESTIMATOR_H_
14 #define WEBRTC_MODULES_REMOTE_BITRATE_ESTIMATOR_INCLUDE_REMOTE_BITRATE_ESTIMATOR_H_
15 
16 #include <map>
17 #include <vector>
18 
19 #include "webrtc/common_types.h"
20 #include "webrtc/modules/interface/module.h"
21 #include "webrtc/modules/interface/module_common_types.h"
22 #include "webrtc/typedefs.h"
23 
24 namespace webrtc {
25 
26 class Clock;
27 
28 enum RateControlType {
29   kMimdControl,
30   kAimdControl
31 };
32 
33 // RemoteBitrateObserver is used to signal changes in bitrate estimates for
34 // the incoming streams.
35 class RemoteBitrateObserver {
36  public:
37   // Called when a receive channel group has a new bitrate estimate for the
38   // incoming streams.
39   virtual void OnReceiveBitrateChanged(const std::vector<unsigned int>& ssrcs,
40                                        unsigned int bitrate) = 0;
41 
~RemoteBitrateObserver()42   virtual ~RemoteBitrateObserver() {}
43 };
44 
45 struct ReceiveBandwidthEstimatorStats {
ReceiveBandwidthEstimatorStatsReceiveBandwidthEstimatorStats46   ReceiveBandwidthEstimatorStats() : total_propagation_time_delta_ms(0) {}
47 
48   // The "propagation_time_delta" of a frame is defined as (d_arrival - d_sent),
49   // where d_arrival is the delta of the arrival times of the frame and the
50   // previous frame, d_sent is the delta of the sent times of the frame and
51   // the previous frame. The sent time is calculated from the RTP timestamp.
52 
53   // |total_propagation_time_delta_ms| is the sum of the propagation_time_deltas
54   // of all received frames, except that it's is adjusted to 0 when it becomes
55   // negative.
56   int total_propagation_time_delta_ms;
57   // The propagation_time_deltas for the frames arrived in the last
58   // kProcessIntervalMs using the clock passed to
59   // RemoteBitrateEstimatorFactory::Create.
60   std::vector<int> recent_propagation_time_delta_ms;
61   // The arrival times for the frames arrived in the last kProcessIntervalMs
62   // using the clock passed to RemoteBitrateEstimatorFactory::Create.
63   std::vector<int64_t> recent_arrival_time_ms;
64 };
65 
66 struct PacketInfo {
PacketInfoPacketInfo67   PacketInfo(int64_t arrival_time_ms,
68              int64_t send_time_ms,
69              uint16_t sequence_number,
70              size_t payload_size)
71       : arrival_time_ms(arrival_time_ms),
72         send_time_ms(send_time_ms),
73         sequence_number(sequence_number),
74         payload_size(payload_size) {}
75   // Time corresponding to when the packet was received. Timestamped with the
76   // receiver's clock.
77   int64_t arrival_time_ms;
78   // Time corresponding to when the packet was sent, timestamped with the
79   // sender's clock.
80   int64_t send_time_ms;
81   // Packet identifier, incremented with 1 for every packet generated by the
82   // sender.
83   uint16_t sequence_number;
84   // Size of the packet excluding RTP headers.
85   size_t payload_size;
86 };
87 
88 class RemoteBitrateEstimator : public CallStatsObserver, public Module {
89  public:
~RemoteBitrateEstimator()90   virtual ~RemoteBitrateEstimator() {}
91 
IncomingPacketFeedbackVector(const std::vector<PacketInfo> & packet_feedback_vector)92   virtual void IncomingPacketFeedbackVector(
93       const std::vector<PacketInfo>& packet_feedback_vector) {
94     assert(false);
95   }
96 
97   // Called for each incoming packet. Updates the incoming payload bitrate
98   // estimate and the over-use detector. If an over-use is detected the
99   // remote bitrate estimate will be updated. Note that |payload_size| is the
100   // packet size excluding headers.
101   // Note that |arrival_time_ms| can be of an arbitrary time base.
102   virtual void IncomingPacket(int64_t arrival_time_ms,
103                               size_t payload_size,
104                               const RTPHeader& header) = 0;
105 
106   // Removes all data for |ssrc|.
107   virtual void RemoveStream(unsigned int ssrc) = 0;
108 
109   // Returns true if a valid estimate exists and sets |bitrate_bps| to the
110   // estimated payload bitrate in bits per second. |ssrcs| is the list of ssrcs
111   // currently being received and of which the bitrate estimate is based upon.
112   virtual bool LatestEstimate(std::vector<unsigned int>* ssrcs,
113                               unsigned int* bitrate_bps) const = 0;
114 
115   // Returns true if the statistics are available.
116   virtual bool GetStats(ReceiveBandwidthEstimatorStats* output) const = 0;
117 
118  protected:
119   static const int64_t kProcessIntervalMs = 1000;
120   static const int64_t kStreamTimeOutMs = 2000;
121 };
122 
123 struct RemoteBitrateEstimatorFactory {
RemoteBitrateEstimatorFactoryRemoteBitrateEstimatorFactory124   RemoteBitrateEstimatorFactory() {}
~RemoteBitrateEstimatorFactoryRemoteBitrateEstimatorFactory125   virtual ~RemoteBitrateEstimatorFactory() {}
126 
127   virtual RemoteBitrateEstimator* Create(
128       RemoteBitrateObserver* observer,
129       Clock* clock,
130       RateControlType control_type,
131       uint32_t min_bitrate_bps) const;
132 };
133 
134 struct AbsoluteSendTimeRemoteBitrateEstimatorFactory
135     : public RemoteBitrateEstimatorFactory {
AbsoluteSendTimeRemoteBitrateEstimatorFactoryAbsoluteSendTimeRemoteBitrateEstimatorFactory136   AbsoluteSendTimeRemoteBitrateEstimatorFactory() {}
~AbsoluteSendTimeRemoteBitrateEstimatorFactoryAbsoluteSendTimeRemoteBitrateEstimatorFactory137   virtual ~AbsoluteSendTimeRemoteBitrateEstimatorFactory() {}
138 
139   virtual RemoteBitrateEstimator* Create(
140       RemoteBitrateObserver* observer,
141       Clock* clock,
142       RateControlType control_type,
143       uint32_t min_bitrate_bps) const;
144 };
145 }  // namespace webrtc
146 
147 #endif  // WEBRTC_MODULES_REMOTE_BITRATE_ESTIMATOR_INCLUDE_REMOTE_BITRATE_ESTIMATOR_H_
148