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