Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

fix(recording): offset the gated Instant video timeline instead of its first capture time

Richie McIlroyd1f0add355bd
diff --git a/crates/recording/src/output_pipeline/core.rs b/crates/recording/src/output_pipeline/core.rs
index 3e856fb6e..5611519d6 100644
--- a/crates/recording/src/output_pipeline/core.rs
+++ b/crates/recording/src/output_pipeline/core.rs
@@ -1663,6 +1663,24 @@ fn stamped_on_host_clock(timestamp: &Timestamp) -> bool {
// and the minimum hand-off lag are used, so the offset cancels.
const CAPTURE_TIME_OFFSET_NS: i128 = 1 << 62;
+// The first frame stays at the track's start, the arm point; every later
+// frame moves by the first frame's lead over it.
+fn shift_from_origin(
+ duration: Duration,
+ is_first_frame: bool,
+ origin_lead: Option<(Instant, Duration)>,
+) -> Duration {
+ match origin_lead {
+ Some((_, lead)) if !is_first_frame => duration + lead,
+ _ => duration,
+ }
+}
+
+fn lead_back(master_ns: u64, origin_lead: Option<(Instant, Duration)>) -> u64 {
+ let lead_ns = origin_lead.map_or(0, |(_, lead)| lead.as_nanos() as u64);
+ master_ns.saturating_sub(lead_ns)
+}
+
fn capture_elapsed(raw_ns: i64, total_pause: Duration) -> Duration {
let ns = i128::from(raw_ns) - total_pause.as_nanos() as i128 + CAPTURE_TIME_OFFSET_NS;
Duration::from_nanos(ns.clamp(0, i128::from(u64::MAX)) as u64)
@@ -3494,6 +3512,11 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
// followed the arm within a frame interval.
let mut held_frame: Option<TVideo::Frame> = None;
let mut wall_clock_origin = timestamps.instant();
+ // Set when the start gate puts the video origin at its arm point (see
+ // `RecordingStartGate::video_origin_lead`). Capture times flow through
+ // clock remapping and drift tracking unchanged; only the muxed
+ // timeline is offset.
+ let mut origin_lead: Option<(Instant, Duration)> = None;
let res = stop_token
.run_until_cancelled(async {
@@ -3553,13 +3576,9 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
gate.offset_secs(timestamp).unwrap_or_default() * 1000.0,
"Start gate admitted first video frame"
);
- // The first frame is shown from the arm point;
- // every later frame keeps its own capture time.
- if gate.video_origin_at_arm()
- && let Some(armed) = gate.armed_instant()
- {
- timestamp = Timestamp::Instant(armed);
- }
+ origin_lead = gate
+ .armed_instant()
+ .zip(gate.video_origin_lead(timestamp));
}
wall_clock_origin = gate
.armed_instant()
@@ -3572,7 +3591,9 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
let is_first_frame = first_tx.is_some();
if let Some(first_tx) = first_tx.take() {
- let _ = first_tx.send(timestamp);
+ let _ = first_tx.send(
+ origin_lead.map_or(timestamp, |(armed, _)| Timestamp::Instant(armed)),
+ );
}
let remap =
@@ -3587,7 +3608,7 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
}
if is_first_frame && let Some(gate) = &video_start_gate {
- gate.publish(remap.master_ns);
+ gate.publish(lead_back(remap.master_ns, origin_lead));
debug!(
video_start_ns = remap.master_ns,
"Published video start timestamp to encoder-pair gate"
@@ -3621,7 +3642,12 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
};
if first_frame_offset.is_none() {
- first_frame_offset = Some(remap.duration().saturating_sub(total_pause_duration));
+ first_frame_offset = Some(
+ remap
+ .duration()
+ .saturating_sub(total_pause_duration)
+ .saturating_sub(origin_lead.map_or(Duration::ZERO, |(_, lead)| lead)),
+ );
}
let resynced = anomaly_tracker.take_resync_flag();
@@ -3641,6 +3667,7 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
wall_clock_elapsed,
resynced || matches!(remap.outcome, SourceClockOutcome::HardReset),
);
+ let duration = shift_from_origin(duration, is_first_frame, origin_lead);
timestamp_span.record(duration);
if frame_count.is_multiple_of(300) {
@@ -3697,16 +3724,14 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
match tokio::time::timeout_at(drain_deadline, video_rx.next()).await {
Ok(Some(frame)) => {
- let mut timestamp = frame.timestamp();
+ let timestamp = frame.timestamp();
if let Some(gate) = &start_gate {
if !gate.admits_video(timestamp) {
continue;
}
- if gate.video_origin_at_arm()
- && let Some(armed) = gate.armed_instant()
- {
- timestamp = Timestamp::Instant(armed);
- }
+ origin_lead = gate
+ .armed_instant()
+ .zip(gate.video_origin_lead(timestamp));
wall_clock_origin = gate
.armed_instant()
.unwrap_or(timestamps.instant());
@@ -3717,7 +3742,10 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
let is_first_frame = first_tx.is_some();
if let Some(first_tx) = first_tx.take() {
- let _ = first_tx.send(timestamp);
+ let _ = first_tx.send(
+ origin_lead
+ .map_or(timestamp, |(armed, _)| Timestamp::Instant(armed)),
+ );
}
let remap =
@@ -3727,7 +3755,7 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
}
if is_first_frame && let Some(gate) = &video_start_gate {
- gate.publish(remap.master_ns);
+ gate.publish(lead_back(remap.master_ns, origin_lead));
debug!(
video_start_ns = remap.master_ns,
"Published video start timestamp to encoder-pair gate (drain path)"
@@ -3761,7 +3789,12 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
if first_frame_offset.is_none() {
first_frame_offset = Some(
- remap.duration().saturating_sub(shared_pause.total_pause_duration()),
+ remap
+ .duration()
+ .saturating_sub(shared_pause.total_pause_duration())
+ .saturating_sub(
+ origin_lead.map_or(Duration::ZERO, |(_, lead)| lead),
+ ),
);
}
@@ -3779,6 +3812,7 @@ fn spawn_video_encoder<TMutex: VideoMuxer<VideoFrame = TVideo::Frame>, TVideo: V
wall_clock_elapsed,
resynced || matches!(remap.outcome, SourceClockOutcome::HardReset),
);
+ let duration = shift_from_origin(duration, is_first_frame, origin_lead);
timestamp_span.record(duration);
let duplicate = frame.duplicate();
@@ -8823,6 +8857,57 @@ mod tests {
assert!(timestamps.len() >= 3, "{timestamps:?}");
}
+ #[tokio::test]
+ async fn primed_instant_video_starts_at_the_arm_point() {
+ let temp_dir = tempfile::tempdir().unwrap();
+ let gate = RecordingStartGate::new();
+ gate.set_video_origin_at_arm();
+ let (sender, receiver) = flume::bounded(8);
+ let sent = Arc::new(std::sync::Mutex::new(Vec::new()));
+ let pipeline = OutputPipeline::builder(temp_dir.path().join("instant.mp4"))
+ .with_video::<ChannelVideoSource<StaticFrame>>(ChannelVideoSourceConfig::new(
+ VideoInfo::from_raw(cap_media_info::RawVideoFormat::Bgra, 16, 16, 30),
+ receiver,
+ ))
+ .with_timestamps(Timestamps::now())
+ .with_start_gate(Some(gate.clone()))
+ .build::<ObservedMuxer>(sent.clone())
+ .await
+ .unwrap();
+
+ let armed = Timestamps::now();
+ assert!(gate.arm_at(armed));
+ // Fresh frames from 20 ms after the arm point, one frame interval
+ // apart, each delivered when it is captured.
+ for offset_ms in [20u64, 53, 86] {
+ let captured = armed.instant() + Duration::from_millis(offset_ms);
+ tokio::time::sleep_until(captured.into()).await;
+ sender
+ .send_async(StaticFrame {
+ timestamp: Timestamp::Instant(captured),
+ })
+ .await
+ .unwrap();
+ }
+ tokio::time::sleep(Duration::from_millis(33)).await;
+ let outcome = pipeline.stop().await.unwrap();
+
+ match outcome.first_timestamp {
+ Timestamp::Instant(instant) => assert_eq!(instant, armed.instant()),
+ other => panic!("unexpected first timestamp {other:?}"),
+ }
+ let timestamps = sent.lock().unwrap().clone();
+ assert_eq!(timestamps.first(), Some(&Duration::ZERO));
+ // Later frames keep their capture times relative to the arm point.
+ for (index, expected_ms) in [(1, 53), (2, 86)] {
+ let muxed = timestamps.get(index).copied().expect("frame muxed");
+ assert!(
+ muxed.abs_diff(Duration::from_millis(expected_ms)) <= Duration::from_millis(2),
+ "{timestamps:?}"
+ );
+ }
+ }
+
#[tokio::test]
async fn primed_static_screen_opens_on_the_frame_held_at_the_arm_point() {
let temp_dir = tempfile::tempdir().unwrap();
diff --git a/crates/recording/src/output_pipeline/start_gate.rs b/crates/recording/src/output_pipeline/start_gate.rs
index 9e13f3792..2825720dc 100644
--- a/crates/recording/src/output_pipeline/start_gate.rs
+++ b/crates/recording/src/output_pipeline/start_gate.rs
@@ -54,8 +54,17 @@ impl RecordingStartGate {
self.0.video_origin_at_arm.store(true, Ordering::Release);
}
- pub(crate) fn video_origin_at_arm(&self) -> bool {
- self.0.video_origin_at_arm.load(Ordering::Acquire)
+ /// How far the first admitted video frame was captured after the arm
+ /// point, when [`Self::set_video_origin_at_arm`] is on. The video track
+ /// then starts at the arm point: the first frame is shown from there and
+ /// every later frame is muxed this much later than its offset from the
+ /// first, so each keeps its capture time relative to the arm point.
+ pub(crate) fn video_origin_lead(&self, admitted: Timestamp) -> Option<Duration> {
+ if !self.0.video_origin_at_arm.load(Ordering::Acquire) {
+ return None;
+ }
+ let offset = self.offset_secs(admitted)?;
+ Some(Duration::from_secs_f64(offset.max(0.0)))
}
pub fn arm(&self) -> bool {
@@ -166,6 +175,24 @@ mod tests {
}
}
+ #[test]
+ fn video_origin_lead_only_when_asked() {
+ let armed = Timestamps::now();
+ let admitted = at(armed, 21);
+
+ let gate = RecordingStartGate::new();
+ assert!(gate.arm_at(armed));
+ assert_eq!(gate.video_origin_lead(admitted), None);
+
+ let gate = RecordingStartGate::new();
+ gate.set_video_origin_at_arm();
+ assert_eq!(gate.video_origin_lead(admitted), None, "closed gate");
+ assert!(gate.arm_at(armed));
+ let lead = gate.video_origin_lead(admitted).unwrap();
+ assert!(lead.abs_diff(Duration::from_millis(21)) < Duration::from_micros(1));
+ assert_eq!(gate.video_origin_lead(at(armed, 0)), Some(Duration::ZERO));
+ }
+
#[test]
fn closed_gate_admits_nothing() {
let gate = RecordingStartGate::new();