Open source Loom alternative. Beautiful, shareable screen recordings.
Rust appcapcossloommacnextjsnextjs15open-sourceossreactrecordrustscreen-capturescreen-recorderscreenshotsolidjstauritauri-apptypescriptvite
//! 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,
×,
);
}
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,
})
}