Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

19.5 KB
Raw Blame
//! Fixture projects. Every fixture is generated by code from a spec and a
//! seed; nothing binary is checked in.
//!
//! Two generators share the project layout:
//! - [`write_fixture`] writes tracks directly with exact presentation times.
//!   It is fast and deterministic and is how exotic timing is produced: VFR
//!   holds of several seconds, jittery cameras, late starts.
//! - [`crate::pipeline`] records through the real recording pipeline in real
//!   time (channel sources -> mux loop -> encoders -> containers).
//!
//! Source truth is never taken from the spec: [`SourceTruth::read`] decodes
//! every written track and reads each frame's marker and presentation time.

use std::path::{Path, PathBuf};

use anyhow::{Context, bail};
use cap_project::{
    AudioMeta, BackgroundSource, ClipConfiguration, MultipleSegment, MultipleSegments, Platform,
    ProjectConfiguration, RecordingMeta, RecordingMetaInner, StudioRecordingMeta,
    StudioRecordingStatus, TimelineConfiguration, TimelineSegment, VideoMeta,
};
use relative_path::RelativePathBuf;
use serde::{Deserialize, Serialize};

use crate::{
    audio_code::{self, AudioSource},
    media::{self, AudioCodec, VideoWriter, VideoWriterConfig},
    video_code::{self, FrameMarker, StreamKind},
};

/// Bump when generated output changes so cached fixtures are rebuilt.
pub const GENERATOR_VERSION: u32 = 2;

/// splitmix64: tiny deterministic PRNG; every fixture prints its seed.
#[derive(Clone)]
pub struct Rng(u64);

impl Rng {
    pub fn new(seed: u64) -> Self {
        Self(seed)
    }

    pub fn next_u64(&mut self) -> u64 {
        self.0 = self.0.wrapping_add(0x9E37_79B9_7F4A_7C15);
        let mut z = self.0;
        z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
        z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
        z ^ (z >> 31)
    }

    pub fn f64(&mut self) -> f64 {
        (self.next_u64() >> 11) as f64 / (1u64 << 53) as f64
    }

    pub fn range(&mut self, lo: u64, hi: u64) -> u64 {
        lo + self.next_u64() % (hi - lo + 1)
    }
}

/// Source frame slots on the nominal grid: frame `k` is presented at
/// `k / fps`. Slot numbers double as marker indices, so a report saying
/// "source frame 1797" also says "59.9 s into the track at 30 fps".
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub enum Timing {
    /// Every slot from 0 to `duration * fps`.
    Constant { duration: f64 },
    /// Constant rate with no frames inside the given (start, length) holds,
    /// like a static screen under VFR capture.
    Holds {
        duration: f64,
        holds: Vec<(f64, f64)>,
    },
    /// A source delivering below its nominal rate with jitter: consecutive
    /// frames are 1..=4 slots apart (mean ~2.4), with a rare 6..=12 slot
    /// stall, and no frames inside `holds`.
    Jittery {
        duration: f64,
        seed: u64,
        holds: Vec<(f64, f64)>,
    },
    /// Explicit slots.
    Slots(Vec<u32>),
}

impl Timing {
    pub fn slots(&self, fps: u32) -> Vec<u32> {
        match self {
            Timing::Constant { duration } => {
                (0..(duration * f64::from(fps)).round() as u32).collect()
            }
            Timing::Holds { duration, holds } => (0..(duration * f64::from(fps)).round() as u32)
                .filter(|&k| {
                    let t = f64::from(k) / f64::from(fps);
                    !holds.iter().any(|&(s, l)| t > s && t < s + l)
                })
                .collect(),
            Timing::Jittery {
                duration,
                seed,
                holds,
            } => {
                let mut rng = Rng::new(*seed);
                let end = (duration * f64::from(fps)).round() as u32;
                let mut out = Vec::new();
                let mut k = 0;
                while k < end {
                    let t = f64::from(k) / f64::from(fps);
                    if !holds.iter().any(|&(s, l)| t > s && t < s + l) {
                        out.push(k);
                    }
                    let r = rng.f64();
                    k += if r < 0.02 {
                        rng.range(6, 12) as u32
                    } else if r < 0.17 {
                        1
                    } else if r < 0.62 {
                        2
                    } else if r < 0.87 {
                        3
                    } else {
                        4
                    };
                }
                out
            }
            Timing::Slots(slots) => slots.clone(),
        }
    }

    pub fn duration(&self, fps: u32) -> f64 {
        match self {
            Timing::Constant { duration }
            | Timing::Holds { duration, .. }
            | Timing::Jittery { duration, .. } => *duration,
            Timing::Slots(slots) => {
                f64::from(slots.last().copied().unwrap_or(0) + 1) / f64::from(fps)
            }
        }
    }
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct VideoTrackSpec {
    pub width: u32,
    pub height: u32,
    pub fps: u32,
    pub timing: Timing,
    /// Frames between keyframes. Pick values whose keyframe times are not on
    /// a 10 ms grid to exercise seek rounding.
    pub gop: u32,
    pub b_frames: u32,
    /// Presentation time of the first slot inside the file (0 for every real
    /// recording; non-zero models a file whose pts start late).
    pub pts_offset: f64,
    /// `start_time` written to recording-meta.json.
    pub start_time: f64,
    /// Encoder used for the track.
    #[serde(default)]
    pub encoder: TrackEncoder,
}

#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
pub enum TrackEncoder {
    /// libx264 with exact GOP control (all platforms).
    #[default]
    X264,
    /// The product's macOS AVAssetWriter/VideoToolbox encoder. Falls back to
    /// libx264 on other platforms.
    AvFoundation,
}

impl VideoTrackSpec {
    pub fn new(width: u32, height: u32, fps: u32, timing: Timing) -> Self {
        Self {
            width,
            height,
            fps,
            timing,
            gop: fps * 2 + 1,
            b_frames: 0,
            pts_offset: 0.0,
            start_time: 0.0,
            encoder: TrackEncoder::X264,
        }
    }
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct AudioTrackSpec {
    pub source: AudioSource,
    pub sample_rate: u32,
    pub channels: u16,
    pub duration: f64,
    pub start_time: f64,
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct SegmentSpec {
    pub display: VideoTrackSpec,
    pub camera: Option<VideoTrackSpec>,
    pub mic: Option<AudioTrackSpec>,
    pub system_audio: Option<AudioTrackSpec>,
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct FixtureSpec {
    pub name: String,
    pub segments: Vec<SegmentSpec>,
}

/// Stable cache key over a spec and the generator version.
pub fn cache_key(name: &str, spec: &impl Serialize) -> String {
    let json = serde_json::to_string(spec).unwrap_or_default();
    let mut hash: u64 = 0xcbf2_9ce4_8422_2325 ^ u64::from(GENERATOR_VERSION);
    for byte in json.bytes() {
        hash ^= u64::from(byte);
        hash = hash.wrapping_mul(0x0100_0000_01b3);
    }
    format!("{name}-{hash:016x}")
}

impl FixtureSpec {
    pub fn cache_key(&self) -> String {
        cache_key(&self.name, self)
    }
}

pub(crate) fn segment_dir(i: usize) -> String {
    format!("content/segments/segment-{i}")
}

fn write_video_track(
    path: &Path,
    kind: StreamKind,
    segment: u8,
    spec: &VideoTrackSpec,
) -> anyhow::Result<()> {
    #[cfg(target_os = "macos")]
    if spec.encoder == TrackEncoder::AvFoundation {
        let times: Vec<(u32, f64)> = spec
            .timing
            .slots(spec.fps)
            .into_iter()
            .map(|slot| {
                (
                    slot,
                    spec.pts_offset + f64::from(slot) / f64::from(spec.fps),
                )
            })
            .collect();
        return crate::fixture_avf::write_video_track(
            path,
            |slot| FrameMarker::new(kind, segment, slot),
            spec.width,
            spec.height,
            spec.fps,
            &times,
        );
    }
    let mut config = VideoWriterConfig::new(spec.width, spec.height, spec.fps);
    config.gop = spec.gop;
    config.b_frames = spec.b_frames;
    let mut writer = VideoWriter::create(path, &config)?;
    for slot in spec.timing.slots(spec.fps) {
        let marker = FrameMarker::new(kind, segment, slot);
        let rgba = video_code::marker_rgba(marker, spec.width as usize, spec.height as usize);
        writer.write_rgba(
            &rgba,
            spec.pts_offset + f64::from(slot) / f64::from(spec.fps),
        )?;
    }
    writer.finish()?;
    Ok(())
}

fn write_audio_track(path: &Path, spec: &AudioTrackSpec) -> anyhow::Result<()> {
    let samples = (spec.duration * f64::from(spec.sample_rate)).round() as usize;
    let mut mono = vec![0.0f32; samples];
    let schedule = audio_code::standard_schedule(spec.source, 0.1, spec.duration - 0.1, 0.5);
    audio_code::render_markers(
        &mut mono,
        spec.sample_rate,
        spec.source,
        &schedule,
        audio_code::DEFAULT_AMPLITUDE,
    );
    let channels = vec![mono; usize::from(spec.channels.max(1))];
    media::write_audio(path, &channels, spec.sample_rate, AudioCodec::Opus, 96_000)
}

/// Writes recording-meta.json and a default project-config.json for the
/// given segments and returns the meta.
pub fn write_project_files(
    dir: &Path,
    name: &str,
    segments: Vec<MultipleSegment>,
) -> anyhow::Result<RecordingMeta> {
    let mut timeline = Vec::new();
    let mut clips = Vec::new();
    for (i, segment) in segments.iter().enumerate() {
        let display = dir.join(segment.display.path.as_str());
        let duration = media::video_packet_times(&display)?
            .last()
            .copied()
            .unwrap_or(0.0)
            + 1.0 / f64::from(segment.display.fps);
        timeline.push(TimelineSegment {
            recording_clip: i as u32,
            start: 0.0,
            end: duration,
            timescale: 1.0,
            name: None,
            speed_audio_mode: None,
            hide_cursor: None,
            volume: None,
        });
        clips.push(ClipConfiguration {
            index: i as u32,
            offsets: segment.calculate_audio_offsets(),
            offsets_auto_calculated: true,
        });
    }
    let meta = RecordingMeta {
        platform: Some(Platform::default()),
        project_path: dir.to_path_buf(),
        pretty_name: name.to_string(),
        sharing: None,
        inner: RecordingMetaInner::Studio(Box::new(StudioRecordingMeta::MultipleSegments {
            inner: MultipleSegments {
                segments,
                cursors: Default::default(),
                status: Some(StudioRecordingStatus::Complete),
            },
        })),
        upload: None,
    };
    meta.save_for_project()
        .map_err(|e| anyhow::anyhow!("save recording meta: {e:?}"))?;
    let mut config = verification_project_config();
    config.timeline = Some(TimelineConfiguration {
        segments: timeline,
        transitions: Vec::new(),
        zoom_segments: Vec::new(),
        scene_segments: Vec::new(),
        style_segments: Vec::new(),
        image_segments: Vec::new(),
        mask_segments: Vec::new(),
        text_segments: Vec::new(),
        caption_segments: Vec::new(),
        keyboard_segments: Vec::new(),
        audio_segments: Vec::new(),
        camera3d_segments: Vec::new(),
    });
    config.clips = clips;
    config.write(dir)?;
    Ok(meta)
}

/// Product defaults with a neutral background (never mistaken for a key
/// colour) and no screen motion blur (which blends neighbouring frames).
pub fn verification_project_config() -> ProjectConfiguration {
    let mut config = ProjectConfiguration::default();
    config.background.source = BackgroundSource::Color {
        value: [60, 60, 60],
        alpha: 255,
    };
    config.screen_motion_blur = 0.0;
    config
}

/// Writes a fixture project with exact timing into `dir` (created).
pub fn write_fixture(spec: &FixtureSpec, dir: &Path) -> anyhow::Result<()> {
    if dir.exists() {
        std::fs::remove_dir_all(dir)?;
    }
    let mut segments = Vec::new();
    for (i, segment) in spec.segments.iter().enumerate() {
        let seg_dir = segment_dir(i);
        std::fs::create_dir_all(dir.join(&seg_dir))?;
        let rel = |file: &str| RelativePathBuf::from(format!("{seg_dir}/{file}"));
        write_video_track(
            &dir.join(rel("display.mp4").as_str()),
            StreamKind::Screen,
            i as u8,
            &segment.display,
        )
        .context("display track")?;
        let camera = match &segment.camera {
            Some(camera) => {
                write_video_track(
                    &dir.join(rel("camera.mp4").as_str()),
                    StreamKind::Camera,
                    i as u8,
                    camera,
                )
                .context("camera track")?;
                Some(VideoMeta {
                    path: rel("camera.mp4"),
                    fps: camera.fps,
                    start_time: Some(camera.start_time),
                    device_id: None,
                })
            }
            None => None,
        };
        let audio = |spec: &Option<AudioTrackSpec>, file: &str| -> anyhow::Result<_> {
            Ok(match spec {
                Some(a) => {
                    write_audio_track(&dir.join(rel(file).as_str()), a)?;
                    Some(AudioMeta {
                        path: rel(file),
                        start_time: Some(a.start_time),
                        device_id: None,
                        gap_summary: None,
                        digital_silence_ms: None,
                    })
                }
                None => None,
            })
        };
        let mic = audio(&segment.mic, "audio-input.ogg")?;
        let system_audio = audio(&segment.system_audio, "system_audio.ogg")?;
        segments.push(MultipleSegment {
            display: VideoMeta {
                path: rel("display.mp4"),
                fps: segment.display.fps,
                start_time: Some(segment.display.start_time),
                device_id: None,
            },
            camera,
            mic,
            system_audio,
            cursor: None,
            keyboard: None,
            display_notch: None,
        });
    }
    write_project_files(dir, &spec.name, segments)?;
    Ok(())
}

/// Root for generated fixtures: `CAP_VERIFY_FIXTURE_DIR`, else
/// `<target>/verify-fixtures`. CI caches this directory keyed by the
/// generator sources.
pub fn fixture_root() -> PathBuf {
    if let Some(dir) = std::env::var_os("CAP_VERIFY_FIXTURE_DIR") {
        return PathBuf::from(dir);
    }
    let manifest = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
    let target = std::env::var_os("CARGO_TARGET_DIR")
        .map(PathBuf::from)
        .unwrap_or_else(|| manifest.join("../../target"));
    target.join("verify-fixtures")
}

/// Returns a ready fixture, generating it unless a complete cached copy with
/// the same key exists. Safe to call from parallel test processes.
pub fn ensure_fixture(
    spec: &FixtureSpec,
    generate: impl FnOnce(&FixtureSpec, &Path) -> anyhow::Result<()>,
) -> anyhow::Result<PathBuf> {
    ensure_fixture_keyed(spec.cache_key(), |dir| generate(spec, dir))
}

/// [`ensure_fixture`] for any generator, keyed by `key`.
pub fn ensure_fixture_keyed(
    key: String,
    generate: impl FnOnce(&Path) -> anyhow::Result<()>,
) -> anyhow::Result<PathBuf> {
    let root = fixture_root();
    std::fs::create_dir_all(&root)?;
    let dir = root.join(format!("{key}.cap"));
    let done = root.join(format!("{key}.complete"));
    if done.exists() && dir.exists() {
        return Ok(dir);
    }
    static GENERATING: std::sync::Mutex<()> = std::sync::Mutex::new(());
    let _serial = GENERATING.lock().unwrap_or_else(|e| e.into_inner());
    if done.exists() && dir.exists() {
        return Ok(dir);
    }
    static NEXT: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0);
    let staging = root.join(format!(
        "{key}.{}-{}.tmp.cap",
        std::process::id(),
        NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
    ));
    generate(&staging)?;
    // Paths inside recording-meta.json are relative, so the staged project
    // stays valid after the rename.
    if dir.exists() {
        let _ = std::fs::remove_dir_all(&staging);
    } else if let Err(error) = std::fs::rename(&staging, &dir) {
        if !dir.exists() {
            bail!("publish fixture {dir:?}: {error}");
        }
        let _ = std::fs::remove_dir_all(&staging);
    }
    std::fs::write(&done, key)?;
    Ok(dir)
}

/// One decoded source frame: its presentation time in the file and marker.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
pub struct SourceFrame {
    pub pts_secs: f64,
    pub index: u32,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct TrackTruth {
    pub kind: StreamKind,
    pub segment: u8,
    /// Frames in presentation order.
    pub frames: Vec<SourceFrame>,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct SegmentTruth {
    pub screen: TrackTruth,
    pub camera: Option<TrackTruth>,
}

/// Ground truth for a project, read back from its files.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct SourceTruth {
    pub segments: Vec<SegmentTruth>,
}

impl SourceTruth {
    pub fn read(project: &Path) -> anyhow::Result<Self> {
        let cache = project.join("verify-truth.json");
        if let Ok(text) = std::fs::read_to_string(&cache)
            && let Ok(truth) = serde_json::from_str(&text)
        {
            return Ok(truth);
        }
        let meta = RecordingMeta::load_for_project(project)
            .map_err(|e| anyhow::anyhow!("load meta: {e:?}"))?;
        let Some(StudioRecordingMeta::MultipleSegments { inner }) = meta.studio_meta() else {
            bail!("not a multi-segment studio project");
        };
        let mut segments = Vec::new();
        for (i, segment) in inner.segments.iter().enumerate() {
            let screen = read_track(
                &project.join(segment.display.path.as_str()),
                StreamKind::Screen,
                i as u8,
            )?;
            let camera = match &segment.camera {
                Some(camera) => Some(read_track(
                    &project.join(camera.path.as_str()),
                    StreamKind::Camera,
                    i as u8,
                )?),
                None => None,
            };
            segments.push(SegmentTruth { screen, camera });
        }
        let truth = SourceTruth { segments };
        let _ = std::fs::write(&cache, serde_json::to_string(&truth)?);
        Ok(truth)
    }
}

fn read_track(path: &Path, kind: StreamKind, segment: u8) -> anyhow::Result<TrackTruth> {
    let mut frames = Vec::new();
    let mut bad = Vec::new();
    media::decode_video(path, |picture| {
        match video_code::read_stream(&picture.view(), kind).marker() {
            Some(marker) if marker.segment == segment => frames.push(SourceFrame {
                pts_secs: picture.pts_secs,
                index: marker.index,
            }),
            other => bad.push((picture.pts_secs, other)),
        }
    })?;
    if !bad.is_empty() {
        bail!(
            "{path:?}: {} source frames without a readable {} marker (first at {:.3}s)",
            bad.len(),
            kind.name(),
            bad[0].0
        );
    }
    frames.sort_by(|a, b| a.pts_secs.total_cmp(&b.pts_secs));
    Ok(TrackTruth {
        kind,
        segment,
        frames,
    })
}