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 #include "modules/rtp_rtcp/source/ulpfec_generator.h"
12
13 #include <string.h>
14
15 #include <cstdint>
16 #include <memory>
17 #include <utility>
18
19 #include "modules/rtp_rtcp/include/rtp_rtcp_defines.h"
20 #include "modules/rtp_rtcp/source/byte_io.h"
21 #include "modules/rtp_rtcp/source/forward_error_correction.h"
22 #include "modules/rtp_rtcp/source/forward_error_correction_internal.h"
23 #include "rtc_base/checks.h"
24 #include "rtc_base/synchronization/mutex.h"
25
26 namespace webrtc {
27
28 namespace {
29
30 constexpr size_t kRedForFecHeaderLength = 1;
31
32 // This controls the maximum amount of excess overhead (actual - target)
33 // allowed in order to trigger EncodeFec(), before `params_.max_fec_frames`
34 // is reached. Overhead here is defined as relative to number of media packets.
35 constexpr int kMaxExcessOverhead = 50; // Q8.
36
37 // This is the minimum number of media packets required (above some protection
38 // level) in order to trigger EncodeFec(), before `params_.max_fec_frames` is
39 // reached.
40 constexpr size_t kMinMediaPackets = 4;
41
42 // Threshold on the received FEC protection level, above which we enforce at
43 // least `kMinMediaPackets` packets for the FEC code. Below this
44 // threshold `kMinMediaPackets` is set to default value of 1.
45 //
46 // The range is between 0 and 255, where 255 corresponds to 100% overhead
47 // (relative to the number of protected media packets).
48 constexpr uint8_t kHighProtectionThreshold = 80;
49
50 // This threshold is used to adapt the `kMinMediaPackets` threshold, based
51 // on the average number of packets per frame seen so far. When there are few
52 // packets per frame (as given by this threshold), at least
53 // `kMinMediaPackets` + 1 packets are sent to the FEC code.
54 constexpr float kMinMediaPacketsAdaptationThreshold = 2.0f;
55
56 // At construction time, we don't know the SSRC that is used for the generated
57 // FEC packets, but we still need to give it to the ForwardErrorCorrection ctor
58 // to be used in the decoding.
59 // TODO(brandtr): Get rid of this awkwardness by splitting
60 // ForwardErrorCorrection in two objects -- one encoder and one decoder.
61 constexpr uint32_t kUnknownSsrc = 0;
62
63 } // namespace
64
65 UlpfecGenerator::Params::Params() = default;
Params(FecProtectionParams delta_params,FecProtectionParams keyframe_params)66 UlpfecGenerator::Params::Params(FecProtectionParams delta_params,
67 FecProtectionParams keyframe_params)
68 : delta_params(delta_params), keyframe_params(keyframe_params) {}
69
UlpfecGenerator(int red_payload_type,int ulpfec_payload_type,Clock * clock)70 UlpfecGenerator::UlpfecGenerator(int red_payload_type,
71 int ulpfec_payload_type,
72 Clock* clock)
73 : red_payload_type_(red_payload_type),
74 ulpfec_payload_type_(ulpfec_payload_type),
75 clock_(clock),
76 fec_(ForwardErrorCorrection::CreateUlpfec(kUnknownSsrc)),
77 num_protected_frames_(0),
78 min_num_media_packets_(1),
79 media_contains_keyframe_(false),
80 fec_bitrate_(/*max_window_size_ms=*/1000, RateStatistics::kBpsScale) {}
81
82 // Used by FlexFecSender, payload types are unused.
UlpfecGenerator(std::unique_ptr<ForwardErrorCorrection> fec,Clock * clock)83 UlpfecGenerator::UlpfecGenerator(std::unique_ptr<ForwardErrorCorrection> fec,
84 Clock* clock)
85 : red_payload_type_(0),
86 ulpfec_payload_type_(0),
87 clock_(clock),
88 fec_(std::move(fec)),
89 num_protected_frames_(0),
90 min_num_media_packets_(1),
91 media_contains_keyframe_(false),
92 fec_bitrate_(/*max_window_size_ms=*/1000, RateStatistics::kBpsScale) {}
93
94 UlpfecGenerator::~UlpfecGenerator() = default;
95
SetProtectionParameters(const FecProtectionParams & delta_params,const FecProtectionParams & key_params)96 void UlpfecGenerator::SetProtectionParameters(
97 const FecProtectionParams& delta_params,
98 const FecProtectionParams& key_params) {
99 RTC_DCHECK_GE(delta_params.fec_rate, 0);
100 RTC_DCHECK_LE(delta_params.fec_rate, 255);
101 RTC_DCHECK_GE(key_params.fec_rate, 0);
102 RTC_DCHECK_LE(key_params.fec_rate, 255);
103 // Store the new params and apply them for the next set of FEC packets being
104 // produced.
105 MutexLock lock(&mutex_);
106 pending_params_.emplace(delta_params, key_params);
107 }
108
AddPacketAndGenerateFec(const RtpPacketToSend & packet)109 void UlpfecGenerator::AddPacketAndGenerateFec(const RtpPacketToSend& packet) {
110 RTC_DCHECK_RUNS_SERIALIZED(&race_checker_);
111 RTC_DCHECK(generated_fec_packets_.empty());
112
113 {
114 MutexLock lock(&mutex_);
115 if (pending_params_) {
116 current_params_ = *pending_params_;
117 pending_params_.reset();
118
119 if (CurrentParams().fec_rate > kHighProtectionThreshold) {
120 min_num_media_packets_ = kMinMediaPackets;
121 } else {
122 min_num_media_packets_ = 1;
123 }
124 }
125 }
126
127 if (packet.is_key_frame()) {
128 media_contains_keyframe_ = true;
129 }
130 const bool complete_frame = packet.Marker();
131 if (media_packets_.size() < kUlpfecMaxMediaPackets) {
132 // Our packet masks can only protect up to `kUlpfecMaxMediaPackets` packets.
133 auto fec_packet = std::make_unique<ForwardErrorCorrection::Packet>();
134 fec_packet->data = packet.Buffer();
135 media_packets_.push_back(std::move(fec_packet));
136
137 // Keep a copy of the last RTP packet, so we can copy the RTP header
138 // from it when creating newly generated ULPFEC+RED packets.
139 RTC_DCHECK_GE(packet.headers_size(), kRtpHeaderSize);
140 last_media_packet_ = packet;
141 }
142
143 if (complete_frame) {
144 ++num_protected_frames_;
145 }
146
147 auto params = CurrentParams();
148
149 // Produce FEC over at most `params_.max_fec_frames` frames, or as soon as:
150 // (1) the excess overhead (actual overhead - requested/target overhead) is
151 // less than `kMaxExcessOverhead`, and
152 // (2) at least `min_num_media_packets_` media packets is reached.
153 if (complete_frame &&
154 (num_protected_frames_ >= params.max_fec_frames ||
155 (ExcessOverheadBelowMax() && MinimumMediaPacketsReached()))) {
156 // We are not using Unequal Protection feature of the parity erasure code.
157 constexpr int kNumImportantPackets = 0;
158 constexpr bool kUseUnequalProtection = false;
159 fec_->EncodeFec(media_packets_, params.fec_rate, kNumImportantPackets,
160 kUseUnequalProtection, params.fec_mask_type,
161 &generated_fec_packets_);
162 if (generated_fec_packets_.empty()) {
163 ResetState();
164 }
165 }
166 }
167
ExcessOverheadBelowMax() const168 bool UlpfecGenerator::ExcessOverheadBelowMax() const {
169 RTC_DCHECK_RUNS_SERIALIZED(&race_checker_);
170
171 return ((Overhead() - CurrentParams().fec_rate) < kMaxExcessOverhead);
172 }
173
MinimumMediaPacketsReached() const174 bool UlpfecGenerator::MinimumMediaPacketsReached() const {
175 RTC_DCHECK_RUNS_SERIALIZED(&race_checker_);
176 float average_num_packets_per_frame =
177 static_cast<float>(media_packets_.size()) / num_protected_frames_;
178 int num_media_packets = static_cast<int>(media_packets_.size());
179 if (average_num_packets_per_frame < kMinMediaPacketsAdaptationThreshold) {
180 return num_media_packets >= min_num_media_packets_;
181 } else {
182 // For larger rates (more packets/frame), increase the threshold.
183 // TODO(brandtr): Investigate what impact this adaptation has.
184 return num_media_packets >= min_num_media_packets_ + 1;
185 }
186 }
187
CurrentParams() const188 const FecProtectionParams& UlpfecGenerator::CurrentParams() const {
189 RTC_DCHECK_RUNS_SERIALIZED(&race_checker_);
190 return media_contains_keyframe_ ? current_params_.keyframe_params
191 : current_params_.delta_params;
192 }
193
MaxPacketOverhead() const194 size_t UlpfecGenerator::MaxPacketOverhead() const {
195 RTC_DCHECK_RUNS_SERIALIZED(&race_checker_);
196 return fec_->MaxPacketOverhead();
197 }
198
GetFecPackets()199 std::vector<std::unique_ptr<RtpPacketToSend>> UlpfecGenerator::GetFecPackets() {
200 RTC_DCHECK_RUNS_SERIALIZED(&race_checker_);
201 if (generated_fec_packets_.empty()) {
202 return std::vector<std::unique_ptr<RtpPacketToSend>>();
203 }
204
205 // Wrap FEC packet (including FEC headers) in a RED packet. Since the
206 // FEC packets in `generated_fec_packets_` don't have RTP headers, we
207 // reuse the header from the last media packet.
208 RTC_CHECK(last_media_packet_.has_value());
209 last_media_packet_->SetPayloadSize(0);
210
211 std::vector<std::unique_ptr<RtpPacketToSend>> fec_packets;
212 fec_packets.reserve(generated_fec_packets_.size());
213
214 size_t total_fec_size_bytes = 0;
215 for (const auto* fec_packet : generated_fec_packets_) {
216 std::unique_ptr<RtpPacketToSend> red_packet =
217 std::make_unique<RtpPacketToSend>(*last_media_packet_);
218 red_packet->SetPayloadType(red_payload_type_);
219 red_packet->SetMarker(false);
220 uint8_t* payload_buffer = red_packet->SetPayloadSize(
221 kRedForFecHeaderLength + fec_packet->data.size());
222 // Primary RED header with F bit unset.
223 // See https://tools.ietf.org/html/rfc2198#section-3
224 payload_buffer[0] = ulpfec_payload_type_; // RED header.
225 memcpy(&payload_buffer[1], fec_packet->data.data(),
226 fec_packet->data.size());
227 total_fec_size_bytes += red_packet->size();
228 red_packet->set_packet_type(RtpPacketMediaType::kForwardErrorCorrection);
229 red_packet->set_allow_retransmission(false);
230 red_packet->set_is_red(true);
231 red_packet->set_fec_protect_packet(false);
232 fec_packets.push_back(std::move(red_packet));
233 }
234
235 ResetState();
236
237 MutexLock lock(&mutex_);
238 fec_bitrate_.Update(total_fec_size_bytes, clock_->TimeInMilliseconds());
239
240 return fec_packets;
241 }
242
CurrentFecRate() const243 DataRate UlpfecGenerator::CurrentFecRate() const {
244 MutexLock lock(&mutex_);
245 return DataRate::BitsPerSec(
246 fec_bitrate_.Rate(clock_->TimeInMilliseconds()).value_or(0));
247 }
248
Overhead() const249 int UlpfecGenerator::Overhead() const {
250 RTC_DCHECK_RUNS_SERIALIZED(&race_checker_);
251 RTC_DCHECK(!media_packets_.empty());
252 int num_fec_packets =
253 fec_->NumFecPackets(media_packets_.size(), CurrentParams().fec_rate);
254
255 // Return the overhead in Q8.
256 return (num_fec_packets << 8) / media_packets_.size();
257 }
258
ResetState()259 void UlpfecGenerator::ResetState() {
260 RTC_DCHECK_RUNS_SERIALIZED(&race_checker_);
261 media_packets_.clear();
262 last_media_packet_.reset();
263 generated_fec_packets_.clear();
264 num_protected_frames_ = 0;
265 media_contains_keyframe_ = false;
266 }
267
268 } // namespace webrtc
269