1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-*/
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this file,
* You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "DriftController.h"
#include <atomic>
#include <cmath>
#include <mutex>
#include "mozilla/CheckedInt.h"
#include "mozilla/Logging.h"
namespace mozilla {
LazyLogModule gDriftControllerGraphsLog("DriftControllerGraphs");
extern LazyLogModule gMediaTrackGraphLog;
#define LOG_CONTROLLER(level, controller, format, ...) \
MOZ_LOG(gMediaTrackGraphLog, level, \
("DriftController %p: (plot-id %u) " format, controller, \
(controller)->mPlotId, ##__VA_ARGS__))
#define LOG_PLOT_NAMES() \
MOZ_LOG( \
gDriftControllerGraphsLog, LogLevel::Verbose, \
("id,t,buffering,desired,buffersize,inlatency,outlatency,inrate," \
"outrate,hysteresisthreshold,corrected,hysteresiscorrected,configured," \
"p,i,d,kpp,kii,kdd,control"))
#define LOG_PLOT_VALUES(id, t, buffering, desired, buffersize, inlatency, \
outlatency, inrate, outrate, hysteresisthreshold, \
corrected, hysteresiscorrected, configured, p, i, d, \
kpp, kii, kdd, control) \
MOZ_LOG( \
gDriftControllerGraphsLog, LogLevel::Verbose, \
("DriftController %u,%.3f,%u,%" PRId64 ",%u,%" PRId64 ",%" PRId64 \
",%u,%u,%" PRId64 ",%.5f,%.5f,%ld,%d,%.5f,%.5f,%.5f,%.5f,%.5f,%.5f", \
id, t, buffering, desired, buffersize, inlatency, outlatency, inrate, \
outrate, hysteresisthreshold, corrected, hysteresiscorrected, \
configured, p, i, d, kpp, kii, kdd, control))
static uint8_t GenerateId() {
static std::atomic<uint8_t> id{0};
return ++id;
}
DriftController::DriftController(uint32_t aSourceRate, uint32_t aTargetRate,
media::TimeUnit aDesiredBuffering)
: mPlotId(GenerateId()),
mSourceRate(aSourceRate),
mTargetRate(aTargetRate),
mDesiredBuffering(aDesiredBuffering),
mCorrectedSourceRate(static_cast<float>(aSourceRate)),
mMeasuredSourceLatency(5),
mMeasuredTargetLatency(5) {
LOG_CONTROLLER(
LogLevel::Info, this,
"Created. Resampling %uHz->%uHz. Initial desired buffering: %.2fms.",
mSourceRate, mTargetRate, mDesiredBuffering.ToSeconds() * 1000.0);
static std::once_flag sOnceFlag;
std::call_once(sOnceFlag, [] { LOG_PLOT_NAMES(); });
}
void DriftController::SetDesiredBuffering(media::TimeUnit aDesiredBuffering) {
LOG_CONTROLLER(LogLevel::Debug, this, "SetDesiredBuffering %.2fms->%.2fms",
mDesiredBuffering.ToSeconds() * 1000.0,
aDesiredBuffering.ToSeconds() * 1000.0);
mLastDesiredBufferingChangeTime = mTotalTargetClock;
mDesiredBuffering = aDesiredBuffering.ToBase(mSourceRate);
}
void DriftController::ResetAfterUnderrun() {
mIntegral = 0.0;
mPreviousError = 0.0;
// Trigger a recalculation on the next clock update.
mTargetClock = mAdjustmentInterval;
}
uint32_t DriftController::GetCorrectedSourceRate() const {
return std::lround(mCorrectedSourceRate);
}
void DriftController::UpdateClock(media::TimeUnit aSourceDuration,
media::TimeUnit aTargetDuration,
uint32_t aBufferedFrames,
uint32_t aBufferSize) {
mTargetClock += aTargetDuration;
mTotalTargetClock += aTargetDuration;
mMeasuredTargetLatency.insert(aTargetDuration);
if (aSourceDuration.IsZero()) {
// Only update the clock after having received input, so input buffering
// estimates are somewhat recent. This helps stabilize the controller
// input (buffering measurements) when the input stream's callback
// interval is much larger than that of the output stream.
return;
}
mMeasuredSourceLatency.insert(aSourceDuration);
if (mTargetClock >= mAdjustmentInterval) {
// The adjustment interval has passed. Recalculate.
CalculateCorrection(aBufferedFrames, aBufferSize);
}
}
void DriftController::CalculateCorrection(uint32_t aBufferedFrames,
uint32_t aBufferSize) {
static constexpr float kProportionalGain = 0.07;
static constexpr float kIntegralGain = 0.006;
static constexpr float kDerivativeGain = 0.12;
// Maximum 0.1% change per update.
const float cap = static_cast<float>(mSourceRate) / 1000.0f;
// The integral term can make us grow far outside the cap. Impose a cap on
// it individually that is roughly equivalent to the final cap.
const float integralCap = cap / kIntegralGain;
// Use nominal (not corrected) source rate when interpreting desired
// buffering so that the set point is independent of the control value.
int32_t error = CheckedInt32(aBufferedFrames -
mDesiredBuffering.ToTicksAtRate(mSourceRate))
.value();
int32_t proportional = error;
// targetClockSec is the number of target clock seconds since last
// correction.
float targetClockSec = static_cast<float>(mTargetClock.ToSeconds());
// delta-t is targetClockSec.
float integralStep = std::clamp(static_cast<float>(error) * targetClockSec,
-integralCap, integralCap);
mIntegral += integralStep;
float derivative =
static_cast<float>(error - mPreviousError) / targetClockSec;
float controlSignal = kProportionalGain * static_cast<float>(proportional) +
kIntegralGain * mIntegral +
kDerivativeGain * derivative;
float correctedRate =
std::clamp(static_cast<float>(mSourceRate) + controlSignal,
mCorrectedSourceRate - cap, mCorrectedSourceRate + cap);
// mDesiredBuffering is divided by this to calculate the amount of
// hysteresis to apply. With a denominator of 5, an error within +/- 20% of
// the desired buffering will not make corrections to the source sample
// rate.
static constexpr uint32_t kHysteresisDenominator = 5; // +/- 20%
// +/- 10ms hysteresis maximum.
const media::TimeUnit hysteresisCap = media::TimeUnit::FromSeconds(0.01);
// For the minimum desired buffering of 10ms we have a hysteresis threshold
// of +/- 2ms (20%). This goes up to +/- 10ms (clamped) at most for when the
// desired buffering is 50 ms or higher.
const auto hysteresisThreshold =
std::min(hysteresisCap, mDesiredBuffering / kHysteresisDenominator)
.ToTicksAtRate(mSourceRate);
float hysteresisCorrectedRate = [&] {
uint32_t abserror = std::abs(error);
if (abserror > hysteresisThreshold) {
// The error is outside a hysteresis threshold boundary.
mDurationWithinHysteresis = media::TimeUnit::Zero();
mIntegralCenterForCap = Nothing();
mLastHysteresisBoundaryCorrection = Some(error);
return correctedRate;
}
// The error is within the hysteresis threshold boundaries.
mDurationWithinHysteresis += mTargetClock;
if (!mIntegralCenterForCap) {
mIntegralCenterForCap = Some(mIntegral);
}
// Would prefer std::signbit, but..
// https://github.com/microsoft/STL/issues/519.
if (mLastHysteresisBoundaryCorrection &&
(*mLastHysteresisBoundaryCorrection < 0) != (error < 0) &&
abserror > hysteresisThreshold * 3 / 10) {
// The error came from a boundary and just went 30% past the center line
// (of the distance between center and boundary). Correct now rather
// than when reaching the opposite boundary, so we have a chance of
// finding a stable rate.
mLastHysteresisBoundaryCorrection = Nothing();
return correctedRate;
}
return mCorrectedSourceRate;
}();
if (mDurationWithinHysteresis > mIntegralCapTimeLimit) {
// Impose a cap on the integral term to not let it grow unboundedly
// while we're within the hysteresis threshold boundaries. Since the
// integral is what finds the drift we center the cap around the integral's
// value when we entered the hysteresis threshold rarther than around 0. We
// impose the cap only after the error has been within the hysteresis
// threshold boundaries for some time, since it would otherwise increase the
// time it takes to reach stability.
mIntegral = std::clamp(mIntegral, *mIntegralCenterForCap - integralCap,
*mIntegralCenterForCap + integralCap);
}
LOG_CONTROLLER(
LogLevel::Verbose, this,
"Recalculating Correction: Nominal: %uHz->%uHz, Corrected: "
"%.2fHz->%uHz (diff %.2fHz), error: %.2fms (hysteresisThreshold: "
"%.2fms), buffering: %.2fms, desired buffering: %.2fms",
mSourceRate, mTargetRate, hysteresisCorrectedRate, mTargetRate,
hysteresisCorrectedRate - mCorrectedSourceRate,
media::TimeUnit(error, mSourceRate).ToSeconds() * 1000.0,
media::TimeUnit(hysteresisThreshold, mSourceRate).ToSeconds() * 1000.0,
media::TimeUnit(aBufferedFrames, mSourceRate).ToSeconds() * 1000.0,
mDesiredBuffering.ToSeconds() * 1000.0);
LOG_PLOT_VALUES(mPlotId, mTotalTargetClock.ToSeconds(), aBufferedFrames,
mDesiredBuffering.ToTicksAtRate(mSourceRate), aBufferSize,
mMeasuredSourceLatency.mean().ToTicksAtRate(mSourceRate),
mMeasuredTargetLatency.mean().ToTicksAtRate(mTargetRate),
mSourceRate, mTargetRate, hysteresisThreshold, correctedRate,
hysteresisCorrectedRate, std::lround(hysteresisCorrectedRate),
proportional, mIntegral, derivative,
kProportionalGain * proportional, kIntegralGain * mIntegral,
kDerivativeGain * derivative, controlSignal);
if (std::lround(mCorrectedSourceRate) !=
std::lround(hysteresisCorrectedRate)) {
++mNumCorrectionChanges;
}
mPreviousError = error;
mCorrectedSourceRate = std::max(1.f, hysteresisCorrectedRate);
// Reset the counters to prepare for the next period.
mTargetClock = media::TimeUnit::Zero();
}
} // namespace mozilla
#undef LOG_PLOT_VALUES
#undef LOG_PLOT_NAMES
#undef LOG_CONTROLLER
|
