Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

fix(recording): keep track start times for crash recovery

Richie McIlroyee6011964a4e
diff --git a/crates/recording/src/output_pipeline/core.rs b/crates/recording/src/output_pipeline/core.rs
index 9669bb48c..960574421 100644
--- a/crates/recording/src/output_pipeline/core.rs
+++ b/crates/recording/src/output_pipeline/core.rs
@@ -2829,6 +2829,7 @@ impl<TVideo: VideoSource> OutputPipelineBuilder<HasVideo<TVideo>> {
let video_info = video_source.video_info();
let mut video_source = PreparedVideoSource::new(video_source);
let (first_tx, first_rx) = oneshot::channel();
+ let (first_rx, first_seen) = observe_first_timestamp(first_rx);
let audio = setup_audio_sources(
&mut setup_ctx,
@@ -2905,6 +2906,7 @@ impl<TVideo: VideoSource> OutputPipelineBuilder<HasVideo<TVideo>> {
.is_some_and(|scope| scope.requires_joined_stop()),
path,
first_timestamp_rx: first_rx,
+ first_timestamp: first_seen,
video_info: Some(video_info),
stop_token: Some(build_ctx.stop_token.clone().drop_guard()),
done_fut: build_ctx.done_rx,
@@ -2948,6 +2950,7 @@ impl OutputPipelineBuilder<NoVideo> {
);
let (first_tx, first_rx) = oneshot::channel();
+ let (first_rx, first_seen) = observe_first_timestamp(first_rx);
let audio = setup_audio_sources(
&mut setup_ctx,
@@ -2995,6 +2998,7 @@ impl OutputPipelineBuilder<NoVideo> {
.is_some_and(|scope| scope.requires_joined_stop()),
path,
first_timestamp_rx: first_rx,
+ first_timestamp: first_seen,
stop_token: Some(build_ctx.stop_token.clone().drop_guard()),
video_info: None,
done_fut: build_ctx.done_rx,
@@ -4586,10 +4590,30 @@ async fn setup_audio_sources(
pub type DoneFut = Shared<BoxFuture<'static, Result<(), PipelineDoneError>>>;
+/// Forwards the first timestamp to the receiver `stop` consumes and to a
+/// watch observers can read while the pipeline records.
+fn observe_first_timestamp(
+ first_rx: oneshot::Receiver<Timestamp>,
+) -> (
+ oneshot::Receiver<Timestamp>,
+ tokio::sync::watch::Receiver<Option<Timestamp>>,
+) {
+ let (forward_tx, forward_rx) = oneshot::channel();
+ let (seen_tx, seen_rx) = tokio::sync::watch::channel(None);
+ tokio::spawn(async move {
+ if let Ok(timestamp) = first_rx.await {
+ seen_tx.send_replace(Some(timestamp));
+ let _ = forward_tx.send(timestamp);
+ }
+ });
+ (forward_rx, seen_rx)
+}
+
pub struct OutputPipeline {
joined_stop: bool,
path: PathBuf,
pub first_timestamp_rx: oneshot::Receiver<Timestamp>,
+ first_timestamp: tokio::sync::watch::Receiver<Option<Timestamp>>,
video_info: Option<VideoInfo>,
stop_token: Option<DropGuard>,
done_fut: DoneFut,
@@ -4672,6 +4696,12 @@ impl OutputPipeline {
&self.path
}
+ /// The first frame's capture timestamp once the pipeline has one, while
+ /// it records (`first_timestamp_rx` is consumed by `stop`).
+ pub fn first_timestamp_watch(&self) -> tokio::sync::watch::Receiver<Option<Timestamp>> {
+ self.first_timestamp.clone()
+ }
+
pub async fn stop(self) -> anyhow::Result<FinishedOutputPipeline> {
let outcome = self.stop_with_outcome().await?;
match outcome.media_error {
diff --git a/crates/recording/src/recovery.rs b/crates/recording/src/recovery.rs
index 3d9445ff3..710684fbe 100644
--- a/crates/recording/src/recovery.rs
+++ b/crates/recording/src/recovery.rs
@@ -147,6 +147,18 @@ pub enum RecoveryError {
pub struct RecoveryManager;
+/// Track start times the recorder writes beside an in-progress segment
+/// (`crate::studio_recording::SegmentStartTimes`); the in-progress meta has
+/// no segments, so this is what recovery aligns the tracks with.
+pub const SEGMENT_START_TIMES_FILE: &str = "start-times.json";
+
+fn persisted_start_times(segment_dir: &Path) -> Option<crate::studio_recording::SegmentStartTimes> {
+ let raw = std::fs::read(segment_dir.join(SEGMENT_START_TIMES_FILE)).ok()?;
+ serde_json::from_slice(&raw)
+ .inspect_err(|error| warn!(%error, "Ignoring unreadable segment start times"))
+ .ok()
+}
+
const EXPORT_SEEK_PROBE_SAMPLE_COUNT: usize = 8;
impl RecoveryManager {
@@ -2351,7 +2363,10 @@ impl RecoveryManager {
}
};
- let display_start_time = original_segment.and_then(|s| s.display.start_time);
+ let persisted = persisted_start_times(&segment_dir);
+ let display_start_time = original_segment
+ .and_then(|s| s.display.start_time)
+ .or(persisted.map(|times| times.display));
let get_start_time_or_fallback = |original_time: Option<f64>| -> Option<f64> {
start_time_or_display_fallback(original_time, display_start_time)
@@ -2374,7 +2389,8 @@ impl RecoveryManager {
start_time: get_start_time_or_fallback(
original_segment
.and_then(|s| s.camera.as_ref())
- .and_then(|c| c.start_time),
+ .and_then(|c| c.start_time)
+ .or(persisted.and_then(|times| times.camera)),
),
device_id: original_segment
.and_then(|s| s.camera.as_ref())
@@ -2397,7 +2413,8 @@ impl RecoveryManager {
start_time: get_start_time_or_fallback(
original_segment
.and_then(|s| s.mic.as_ref())
- .and_then(|m| m.start_time),
+ .and_then(|m| m.start_time)
+ .or(persisted.and_then(|times| times.mic)),
),
device_id: original_segment
.and_then(|s| s.mic.as_ref())
@@ -2422,7 +2439,8 @@ impl RecoveryManager {
start_time: get_start_time_or_fallback(
original_segment
.and_then(|s| s.system_audio.as_ref())
- .and_then(|a| a.start_time),
+ .and_then(|a| a.start_time)
+ .or(persisted.and_then(|times| times.system_audio)),
),
device_id: original_segment
.and_then(|s| s.system_audio.as_ref())
diff --git a/crates/recording/src/studio_recording.rs b/crates/recording/src/studio_recording.rs
index 4917df973..0be84abd6 100644
--- a/crates/recording/src/studio_recording.rs
+++ b/crates/recording/src/studio_recording.rs
@@ -1453,11 +1453,68 @@ fn write_recording_failure_diagnostics(
impl Pipeline {
fn epoch(&self) -> Timestamps {
- self.start_gate
+ pipeline_epoch(self.start_time, self.start_gate.as_ref())
+ }
+
+ /// Writes the tracks' start times beside the segment as soon as their
+ /// first frames arrive and again as more tracks start, so a crash keeps
+ /// the alignment a normal stop would persist. Ends once every track has
+ /// started or the pipeline is gone.
+ fn spawn_start_time_persister(&self) {
+ let Some(segment_dir) = self.screen.path().parent().map(Path::to_path_buf) else {
+ return;
+ };
+ let start_time = self.start_time;
+ let start_gate = self.start_gate.clone();
+ let mut display = self.screen.first_timestamp_watch();
+ let mut mic = self.microphone.as_ref().map(|p| p.first_timestamp_watch());
+ let mut camera = self.camera.as_ref().map(|p| p.first_timestamp_watch());
+ let mut system_audio = self
+ .system_audio
.as_ref()
- .and_then(RecordingStartGate::armed_at)
- .filter(|armed| armed.instant() > self.start_time.instant())
- .unwrap_or(self.start_time)
+ .map(|p| p.first_timestamp_watch());
+ tokio::spawn(async move {
+ let mut written = None;
+ loop {
+ let first = |watch: &Option<tokio::sync::watch::Receiver<Option<Timestamp>>>| {
+ watch.as_ref().and_then(|watch| *watch.borrow())
+ };
+ if let Some(display_first) = *display.borrow() {
+ let times = SegmentStartTimes::compute(
+ pipeline_epoch(start_time, start_gate.as_ref()),
+ display_first,
+ first(&mic),
+ first(&camera),
+ first(&system_audio),
+ );
+ if written != Some(times) {
+ if let Err(error) = write_segment_start_times(&segment_dir, &times) {
+ warn!(%error, "Failed to persist segment start times");
+ }
+ written = Some(times);
+ }
+ }
+ let pending = |watch: &Option<tokio::sync::watch::Receiver<Option<Timestamp>>>| {
+ watch.as_ref().is_some_and(|watch| watch.borrow().is_none())
+ };
+ if display.borrow().is_some()
+ && !pending(&mic)
+ && !pending(&camera)
+ && !pending(&system_audio)
+ {
+ return;
+ }
+ let alive = tokio::select! {
+ result = display.changed(), if display.borrow().is_none() => result.is_ok(),
+ alive = first_timestamp_change(&mut mic) => alive,
+ alive = first_timestamp_change(&mut camera) => alive,
+ alive = first_timestamp_change(&mut system_audio) => alive,
+ };
+ if !alive {
+ return;
+ }
+ }
+ });
}
#[cfg(target_os = "linux")]
@@ -2541,6 +2598,55 @@ pub struct CompletedRecording {
pub clean_stopped: Option<CleanStoppedStudio>,
}
+/// Tracks starting within one audio output buffer of each other are treated
+/// as simultaneous.
+const CROSS_TRACK_SNAP_SECS: f64 =
+ cap_timestamp::AUDIO_OUTPUT_FRAMES as f64 / cap_timestamp::DEFAULT_SAMPLE_RATE as f64;
+
+/// Each track's start relative to the segment epoch, as persisted in the
+/// recording meta. Also written beside an in-progress segment
+/// (`crate::recovery::SEGMENT_START_TIMES_FILE`) so crash recovery aligns the
+/// tracks exactly like a normal stop.
+#[derive(Clone, Copy, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct SegmentStartTimes {
+ pub display: f64,
+ pub camera: Option<f64>,
+ pub mic: Option<f64>,
+ pub system_audio: Option<f64>,
+}
+
+impl SegmentStartTimes {
+ pub fn compute(
+ epoch: Timestamps,
+ display: Timestamp,
+ mic: Option<Timestamp>,
+ camera: Option<Timestamp>,
+ system_audio: Option<Timestamp>,
+ ) -> Self {
+ let to_start_time = |timestamp: Timestamp| timestamp.signed_duration_since_secs(epoch);
+ let mic = mic.map(to_start_time);
+ let camera = camera.map(|camera| {
+ snap_nearby_start_time(to_start_time(camera), mic, CROSS_TRACK_SNAP_SECS)
+ });
+ let raw_display = to_start_time(display);
+ let display = if camera.is_some() {
+ snap_nearby_start_time(raw_display, camera, CROSS_TRACK_SNAP_SECS)
+ } else {
+ snap_nearby_start_time(raw_display, mic, CROSS_TRACK_SNAP_SECS)
+ };
+ let system_audio = system_audio.map(|audio| {
+ let reference = mic.or(Some(display));
+ snap_nearby_start_time(to_start_time(audio), reference, CROSS_TRACK_SNAP_SECS)
+ });
+ Self {
+ display,
+ camera,
+ mic,
+ system_audio,
+ }
+ }
+}
+
fn snap_nearby_start_time(
raw_start: f64,
reference_start: Option<f64>,
@@ -2563,12 +2669,9 @@ async fn stop_recording(
known_failure: Option<String>,
) -> anyhow::Result<CompletedRecording> {
use cap_project::*;
- use cap_timestamp::{AUDIO_OUTPUT_FRAMES, DEFAULT_SAMPLE_RATE};
const DEFAULT_FPS: u32 = 30;
- const CROSS_TRACK_SNAP_SECS: f64 = AUDIO_OUTPUT_FRAMES as f64 / DEFAULT_SAMPLE_RATE as f64;
-
let make_relative = |path: &PathBuf| -> RelativePathBuf {
match path.strip_prefix(&recording_dir) {
Ok(stripped) => RelativePathBuf::from_path(stripped).unwrap_or_else(|_| {
@@ -2603,26 +2706,25 @@ async fn stop_recording(
.into_iter()
.enumerate()
.map(|(segment_index, s)| {
- let to_start_time =
- |timestamp: Timestamp| timestamp.signed_duration_since_secs(s.pipeline.start_time);
-
- let mic_start_time = s
- .pipeline
- .microphone
- .as_ref()
- .map(|mic| to_start_time(mic.first_timestamp));
-
- let camera_start_time = s.pipeline.camera.as_ref().map(|camera| {
- let raw_camera_start = to_start_time(camera.first_timestamp);
- snap_nearby_start_time(raw_camera_start, mic_start_time, CROSS_TRACK_SNAP_SECS)
- });
-
- let raw_display_start = to_start_time(s.pipeline.screen.first_timestamp);
- let display_start_time = if camera_start_time.is_some() {
- snap_nearby_start_time(raw_display_start, camera_start_time, CROSS_TRACK_SNAP_SECS)
- } else {
- snap_nearby_start_time(raw_display_start, mic_start_time, CROSS_TRACK_SNAP_SECS)
- };
+ let start_times = SegmentStartTimes::compute(
+ s.pipeline.start_time,
+ s.pipeline.screen.first_timestamp,
+ s.pipeline
+ .microphone
+ .as_ref()
+ .map(|mic| mic.first_timestamp),
+ s.pipeline
+ .camera
+ .as_ref()
+ .map(|camera| camera.first_timestamp),
+ s.pipeline
+ .system_audio
+ .as_ref()
+ .map(|audio| audio.first_timestamp),
+ );
+ let mic_start_time = start_times.mic;
+ let camera_start_time = start_times.camera;
+ let display_start_time = start_times.display;
let diagnostics =
(!s.pipeline.track_failures.is_empty()).then(|| SegmentFailureDiagnostics {
@@ -2703,27 +2805,11 @@ async fn stop_recording(
device_id: s.mic_device_id.clone(),
gap_summary: to_project_gap_summary(mic.audio_gap_summary),
}),
- system_audio: s.pipeline.system_audio.map(|audio| {
- let raw_sys_start = to_start_time(audio.first_timestamp);
- let sys_start_time = if let Some(mic_start) = mic_start_time {
- snap_nearby_start_time(
- raw_sys_start,
- Some(mic_start),
- CROSS_TRACK_SNAP_SECS,
- )
- } else {
- snap_nearby_start_time(
- raw_sys_start,
- Some(display_start_time),
- CROSS_TRACK_SNAP_SECS,
- )
- };
- AudioMeta {
- path: make_relative(&audio.path),
- start_time: Some(sys_start_time),
- device_id: None,
- gap_summary: to_project_gap_summary(audio.audio_gap_summary),
- }
+ system_audio: s.pipeline.system_audio.map(|audio| AudioMeta {
+ path: make_relative(&audio.path),
+ start_time: start_times.system_audio,
+ device_id: None,
+ gap_summary: to_project_gap_summary(audio.audio_gap_summary),
}),
cursor: s
.pipeline
@@ -2997,6 +3083,7 @@ impl SegmentPipelineFactory {
fn commit_next(&mut self, pipeline: &mut Pipeline) {
self.index += 1;
pipeline.spawn_watcher(self.completion_tx.clone());
+ pipeline.spawn_start_time_persister();
}
#[cfg(not(target_os = "linux"))]
@@ -3042,6 +3129,9 @@ impl SegmentPipelineFactory {
self.index += 1;
pipeline.spawn_watcher(self.completion_tx.clone());
+ if self.fragmented || cfg!(windows) {
+ pipeline.spawn_start_time_persister();
+ }
Ok(pipeline)
}
@@ -3605,6 +3695,34 @@ fn persist_final_recording_meta(
Ok(recording_meta)
}
+/// Resolves when a track that has not started yet starts (`true`) or its
+/// pipeline is gone (`false`); never for absent or started tracks.
+async fn first_timestamp_change(
+ watch: &mut Option<tokio::sync::watch::Receiver<Option<Timestamp>>>,
+) -> bool {
+ match watch {
+ Some(watch) if watch.borrow().is_none() => watch.changed().await.is_ok(),
+ _ => std::future::pending().await,
+ }
+}
+
+fn pipeline_epoch(start_time: Timestamps, start_gate: Option<&RecordingStartGate>) -> Timestamps {
+ start_gate
+ .and_then(RecordingStartGate::armed_at)
+ .filter(|armed| armed.instant() > start_time.instant())
+ .unwrap_or(start_time)
+}
+
+fn write_segment_start_times(segment_dir: &Path, times: &SegmentStartTimes) -> std::io::Result<()> {
+ let path = segment_dir.join(crate::recovery::SEGMENT_START_TIMES_FILE);
+ let temp = path.with_extension("json.tmp");
+ std::fs::write(
+ &temp,
+ serde_json::to_vec(times).map_err(std::io::Error::other)?,
+ )?;
+ std::fs::rename(&temp, &path)
+}
+
fn write_in_progress_meta(recording_dir: &Path) -> anyhow::Result<()> {
use chrono::Local;
@@ -5349,6 +5467,95 @@ mod tests {
}
}
+ #[tokio::test]
+ async fn in_progress_segments_persist_the_start_times_a_normal_stop_records() {
+ let temp = tempfile::tempdir().unwrap();
+ let segment_dir = temp.path().join("content/segments/segment-0");
+ std::fs::create_dir_all(&segment_dir).unwrap();
+ let timestamps = Timestamps::now();
+ let (screen_tx, screen_rx) = flume::bounded(4);
+ let screen = OutputPipeline::builder(segment_dir.join("display"))
+ .with_video::<ChannelVideoSource<TestVideoFrame>>(ChannelVideoSourceConfig::new(
+ test_video_info(),
+ screen_rx,
+ ))
+ .with_timestamps(timestamps)
+ .build::<SuccessfulVideoMuxer>(())
+ .await
+ .unwrap();
+ let (mut mic_tx, mic_rx) = futures::channel::mpsc::channel(16);
+ let microphone = OutputPipeline::builder(segment_dir.join("audio-input"))
+ .with_audio_source::<ChannelAudioSource>(ChannelAudioSourceConfig::new(
+ test_audio_info(),
+ mic_rx,
+ ))
+ .with_timestamps(timestamps)
+ .build::<SuccessfulVideoMuxer>(())
+ .await
+ .unwrap();
+ let pipeline = Pipeline {
+ start_time: timestamps,
+ start_gate: None,
+ screen,
+ microphone: Some(microphone),
+ camera: None,
+ system_audio: None,
+ cursor: None,
+ track_failures: Arc::new(std::sync::Mutex::new(Vec::new())),
+ watcher_task: None,
+ #[cfg(any(target_os = "linux", windows))]
+ stopping: Arc::new(std::sync::atomic::AtomicBool::new(false)),
+ };
+ pipeline.spawn_start_time_persister();
+ let persisted = || -> Option<SegmentStartTimes> {
+ serde_json::from_slice(
+ &std::fs::read(segment_dir.join(crate::recovery::SEGMENT_START_TIMES_FILE)).ok()?,
+ )
+ .ok()
+ };
+
+ let base = timestamps.instant();
+ screen_tx
+ .send_async(TestVideoFrame {
+ timestamp: Timestamp::Instant(base + Duration::from_millis(200)),
+ })
+ .await
+ .unwrap();
+ let deadline = Instant::now() + Duration::from_secs(5);
+ while persisted().is_none() && Instant::now() < deadline {
+ tokio::time::sleep(Duration::from_millis(10)).await;
+ }
+ let display_only = persisted().expect("display start persisted before the mic starts");
+ assert_eq!(display_only.mic, None);
+
+ for k in 0..10u64 {
+ mic_tx
+ .try_send(crate::output_pipeline::AudioFrame::new(
+ test_audio_info().empty_frame(960),
+ Timestamp::Instant(base + Duration::from_millis(500 + k * 20)),
+ ))
+ .unwrap();
+ }
+ let deadline = Instant::now() + Duration::from_secs(5);
+ while persisted().is_none_or(|times| times.mic.is_none()) && Instant::now() < deadline {
+ tokio::time::sleep(Duration::from_millis(10)).await;
+ }
+ let during = persisted().expect("start times persisted");
+
+ drop(screen_tx);
+ drop(mic_tx);
+ let finished = pipeline.stop().await.unwrap().pipeline;
+ let at_stop = SegmentStartTimes::compute(
+ finished.start_time,
+ finished.screen.first_timestamp,
+ finished.microphone.as_ref().map(|mic| mic.first_timestamp),
+ None,
+ None,
+ );
+ assert_eq!(during, at_stop);
+ assert!(during.mic.unwrap() > during.display);
+ }
+
fn test_video_info() -> VideoInfo {
VideoInfo::from_raw(cap_media_info::RawVideoFormat::Bgra, 16, 16, 30)
}
diff --git a/crates/recording/tests/recovery.rs b/crates/recording/tests/recovery.rs
index 9472d1838..e6729b4cc 100644
--- a/crates/recording/tests/recovery.rs
+++ b/crates/recording/tests/recovery.rs
@@ -2292,3 +2292,50 @@ fn instant_recovery_rebuilds_corrupt_prior_output_only_from_valid_required_raw()
}
}
}
+
+#[test]
+fn recovery_aligns_tracks_with_the_start_times_persisted_while_recording() {
+ test_utils::init_tracing();
+
+ let recording = TestRecording::new().unwrap();
+ let display_dir = recording.create_display_dir(0).unwrap();
+ write_synthetic_fragments(&display_dir, 180, Duration::from_secs(2));
+
+ // What the recorder leaves: an in-progress meta without segments, plus
+ // the start times it persisted beside the segment.
+ let meta = RecordingMeta {
+ platform: None,
+ project_path: recording.path().to_path_buf(),
+ pretty_name: "Test Recording".to_string(),
+ sharing: None,
+ upload: None,
+ inner: RecordingMetaInner::Studio(Box::new(StudioRecordingMeta::MultipleSegments {
+ inner: MultipleSegments {
+ segments: Vec::new(),
+ cursors: Cursors::default(),
+ status: Some(StudioRecordingStatus::InProgress),
+ },
+ })),
+ };
+ std::fs::write(
+ recording.path().join("recording-meta.json"),
+ serde_json::to_string_pretty(&meta).unwrap(),
+ )
+ .unwrap();
+ std::fs::write(
+ display_dir
+ .parent()
+ .unwrap()
+ .join(cap_recording::recovery::SEGMENT_START_TIMES_FILE),
+ br#"{"display":0.412,"camera":null,"mic":0.25,"system_audio":null}"#,
+ )
+ .unwrap();
+
+ let incomplete = RecoveryManager::inspect_recording(recording.path()).unwrap();
+ let recovered = RecoveryManager::recover(&incomplete).expect("recovery should succeed");
+
+ let StudioRecordingMeta::MultipleSegments { inner } = recovered.meta else {
+ panic!("segmented meta expected");
+ };
+ assert_eq!(inner.segments[0].display.start_time, Some(0.412));
+}