1 /*
2 * Copyright (c) 2016 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 "rtc_base/timestamp_aligner.h"
12
13 #include <cstdlib>
14 #include <limits>
15
16 #include "rtc_base/checks.h"
17 #include "rtc_base/logging.h"
18 #include "rtc_base/time_utils.h"
19
20 namespace rtc {
21
TimestampAligner()22 TimestampAligner::TimestampAligner()
23 : frames_seen_(0),
24 offset_us_(0),
25 clip_bias_us_(0),
26 prev_translated_time_us_(std::numeric_limits<int64_t>::min()),
27 prev_time_offset_us_(0) {}
28
~TimestampAligner()29 TimestampAligner::~TimestampAligner() {}
30
TranslateTimestamp(int64_t capturer_time_us,int64_t system_time_us)31 int64_t TimestampAligner::TranslateTimestamp(int64_t capturer_time_us,
32 int64_t system_time_us) {
33 const int64_t translated_timestamp = ClipTimestamp(
34 capturer_time_us + UpdateOffset(capturer_time_us, system_time_us),
35 system_time_us);
36 prev_time_offset_us_ = translated_timestamp - capturer_time_us;
37 return translated_timestamp;
38 }
39
TranslateTimestamp(int64_t capturer_time_us) const40 int64_t TimestampAligner::TranslateTimestamp(int64_t capturer_time_us) const {
41 return capturer_time_us + prev_time_offset_us_;
42 }
43
UpdateOffset(int64_t capturer_time_us,int64_t system_time_us)44 int64_t TimestampAligner::UpdateOffset(int64_t capturer_time_us,
45 int64_t system_time_us) {
46 // Estimate the offset between system monotonic time and the capturer's
47 // time. The capturer is assumed to provide more
48 // accurate timestamps than we get from the system time. But the
49 // capturer may use its own free-running clock with a large offset and
50 // a small drift compared to the system clock. So the model is
51 // basically
52 //
53 // y_k = c_0 + c_1 * x_k + v_k
54 //
55 // where x_k is the capturer's timestamp, believed to be accurate in its
56 // own scale. y_k is our reading of the system clock. v_k is the
57 // measurement noise, i.e., the delay from frame capture until the
58 // system clock was read.
59 //
60 // It's possible to do (weighted) least-squares estimation of both
61 // c_0 and c_1. Then we get the constants as c_1 = Cov(x,y) /
62 // Var(x), and c_0 = mean(y) - c_1 * mean(x). Substituting this c_0,
63 // we can rearrange the model as
64 //
65 // y_k = mean(y) + (x_k - mean(x)) + (c_1 - 1) * (x_k - mean(x)) + v_k
66 //
67 // Now if we use a weighted average which gradually forgets old
68 // values, x_k - mean(x) is bounded, of the same order as the time
69 // constant (and close to constant for a steady frame rate). In
70 // addition, the frequency error |c_1 - 1| should be small. Cameras
71 // with a frequency error up to 3000 ppm (3 ms drift per second)
72 // have been observed, but frequency errors below 100 ppm could be
73 // expected of any cheap crystal.
74 //
75 // Bottom line is that we ignore the c_1 term, and use only the estimator
76 //
77 // x_k + mean(y-x)
78 //
79 // where mean is plain averaging for initial samples, followed by
80 // exponential averaging.
81
82 // The input for averaging, y_k - x_k in the above notation.
83 int64_t diff_us = system_time_us - capturer_time_us;
84 // The deviation from the current average.
85 int64_t error_us = diff_us - offset_us_;
86
87 // If the current difference is far from the currently estimated
88 // offset, the filter is reset. This could happen, e.g., if the
89 // capturer's clock is reset, cameras are plugged in and out, or
90 // the application process is temporarily suspended. Expected to
91 // happen for the very first timestamp (|frames_seen_| = 0). The
92 // threshold of 300 ms should make this unlikely in normal
93 // operation, and at the same time, converging gradually rather than
94 // resetting the filter should be tolerable for jumps in capturer's time
95 // below this threshold.
96 static const int64_t kResetThresholdUs = 300000;
97 if (std::abs(error_us) > kResetThresholdUs) {
98 RTC_LOG(LS_INFO) << "Resetting timestamp translation after averaging "
99 << frames_seen_ << " frames. Old offset: " << offset_us_
100 << ", new offset: " << diff_us;
101 frames_seen_ = 0;
102 clip_bias_us_ = 0;
103 }
104
105 static const int kWindowSize = 100;
106 if (frames_seen_ < kWindowSize) {
107 ++frames_seen_;
108 }
109 offset_us_ += error_us / frames_seen_;
110 return offset_us_;
111 }
112
ClipTimestamp(int64_t filtered_time_us,int64_t system_time_us)113 int64_t TimestampAligner::ClipTimestamp(int64_t filtered_time_us,
114 int64_t system_time_us) {
115 const int64_t kMinFrameIntervalUs = rtc::kNumMicrosecsPerMillisec;
116 // Clip to make sure we don't produce timestamps in the future.
117 int64_t time_us = filtered_time_us - clip_bias_us_;
118 if (time_us > system_time_us) {
119 clip_bias_us_ += time_us - system_time_us;
120 time_us = system_time_us;
121 }
122 // Make timestamps monotonic, with a minimum inter-frame interval of 1 ms.
123 else if (time_us < prev_translated_time_us_ + kMinFrameIntervalUs) {
124 time_us = prev_translated_time_us_ + kMinFrameIntervalUs;
125 if (time_us > system_time_us) {
126 // In the anomalous case that this function is called with values of
127 // |system_time_us| less than |kMinFrameIntervalUs| apart, we may output
128 // timestamps with with too short inter-frame interval. We may even return
129 // duplicate timestamps in case this function is called several times with
130 // exactly the same |system_time_us|.
131 RTC_LOG(LS_WARNING) << "too short translated timestamp interval: "
132 "system time (us) = "
133 << system_time_us << ", interval (us) = "
134 << system_time_us - prev_translated_time_us_;
135 time_us = system_time_us;
136 }
137 }
138 RTC_DCHECK_GE(time_us, prev_translated_time_us_);
139 RTC_DCHECK_LE(time_us, system_time_us);
140 prev_translated_time_us_ = time_us;
141 return time_us;
142 }
143
144 } // namespace rtc
145