Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

fix(export): validate staged MP4 before replacing destination

songsong1efff3da58f0
diff --git a/crates/compositor/src/export_control.rs b/crates/compositor/src/export_control.rs
index 8542c55ea..4be350265 100644
--- a/crates/compositor/src/export_control.rs
+++ b/crates/compositor/src/export_control.rs
@@ -106,6 +106,144 @@ pub(crate) fn with_staged_output<T>(
result
}
+/// Render and close an MP4, then verify a displayable decoded frame before
+/// publishing it. A positive encoder submission count alone is insufficient:
+/// a zero-duration MP4 sample can be flagged discard by the demuxer.
+pub(crate) fn with_validated_mp4_output<T>(
+ target: &Path,
+ control: &ExportControl,
+ render: impl FnOnce(File, &Path) -> Result<T>,
+) -> Result<T> {
+ with_staged_output(target, control, |file, staged| {
+ let stats = render(file, staged)?;
+ validate_video_frame(staged, control).context("validating exported video")?;
+ Ok(stats)
+ })
+}
+
+/// Own every FFmpeg allocation so validation closes the file before publication
+/// or cleanup, including on cancellation and partially initialized error paths.
+#[derive(Default)]
+struct VideoValidation {
+ input: *mut crate::ffi::AVFormatContext,
+ decoder: *mut crate::ffi::AVCodecContext,
+ packet: *mut crate::ffi::AVPacket,
+ frame: *mut crate::ffi::AVFrame,
+}
+
+impl Drop for VideoValidation {
+ fn drop(&mut self) {
+ unsafe {
+ crate::ffi::av_frame_free(&mut self.frame);
+ crate::ffi::av_packet_free(&mut self.packet);
+ crate::ffi::avcodec_free_context(&mut self.decoder);
+ if !self.input.is_null() {
+ crate::ffi::avformat_close_input(&mut self.input);
+ }
+ }
+ }
+}
+
+/// Decode only until the first displayable frame. Decode discard-marked preroll
+/// packets to preserve reference state, but never accept discard-marked frames.
+/// This excludes zero-duration MP4 edit-list samples. Drain delayed frames
+/// at EOF, and remain cancellable while scanning interleaved audio packets.
+fn validate_video_frame(path: &Path, control: &ExportControl) -> Result<()> {
+ use crate::ffi::*;
+ use std::{ffi::CString, ptr};
+
+ control.check()?;
+ let path = CString::new(path.to_string_lossy().as_bytes())?;
+ let mut video = VideoValidation::default();
+ unsafe {
+ averr(
+ avformat_open_input(
+ &mut video.input,
+ path.as_ptr(),
+ ptr::null(),
+ ptr::null_mut(),
+ ),
+ "open exported video",
+ )?;
+ averr(
+ avformat_find_stream_info(video.input, ptr::null_mut()),
+ "read exported video streams",
+ )?;
+ let index = av_find_best_stream(
+ video.input,
+ AVMediaType::AVMEDIA_TYPE_VIDEO,
+ -1,
+ -1,
+ ptr::null_mut(),
+ 0,
+ );
+ averr(index, "find exported video stream")?;
+ let stream = sn_fmt_stream(video.input, index);
+ let params = (*stream).codecpar;
+ let codec = avcodec_find_decoder((*params).codec_id);
+ if codec.is_null() {
+ bail!("No decoder is available for the exported video.");
+ }
+ video.decoder = avcodec_alloc_context3(codec);
+ video.packet = av_packet_alloc();
+ video.frame = av_frame_alloc();
+ if video.decoder.is_null() || video.packet.is_null() || video.frame.is_null() {
+ bail!("Could not allocate exported video validation buffers.");
+ }
+ averr(
+ avcodec_parameters_to_context(video.decoder, params),
+ "configure exported video decoder",
+ )?;
+ averr(
+ avcodec_open2(video.decoder, codec, ptr::null_mut()),
+ "open exported video decoder",
+ )?;
+ let mut draining = false;
+ loop {
+ control.check()?;
+ let received = avcodec_receive_frame(video.decoder, video.frame);
+ if received >= 0 {
+ let displayable = (*video.frame).flags & AV_FRAME_FLAG_DISCARD as i32 == 0
+ && (*video.frame).width > 0
+ && (*video.frame).height > 0;
+ av_frame_unref(video.frame);
+ if displayable {
+ return Ok(());
+ }
+ continue;
+ }
+ if received == AVERROR_EOF || (draining && received == AVERROR_EAGAIN) {
+ bail!("The exported video has no decodable displayable frames. The destination has not been replaced.");
+ }
+ averr(
+ if received == AVERROR_EAGAIN {
+ 0
+ } else {
+ received
+ },
+ "decode exported video frame",
+ )?;
+ let read = av_read_frame(video.input, video.packet);
+ if read == AVERROR_EOF {
+ averr(
+ avcodec_send_packet(video.decoder, ptr::null()),
+ "flush exported video decoder",
+ )?;
+ draining = true;
+ } else {
+ averr(read, "read exported video packet")?;
+ let sent = if (*video.packet).stream_index == index {
+ avcodec_send_packet(video.decoder, video.packet)
+ } else {
+ 0
+ };
+ av_packet_unref(video.packet);
+ averr(sent, "send exported video packet")?;
+ }
+ }
+ }
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -129,6 +267,38 @@ mod tests {
fn drop(&mut self) { let _ = fs::remove_dir_all(&self.0); }
}
+ /// An invalid completed file must not replace the destination or leave a partial.
+ #[test]
+ fn invalid_mp4_is_rejected_before_publication() {
+ let dir = TestDir::new();
+ let target = dir.0.join("out.mp4");
+ fs::write(&target, b"previous export").unwrap();
+ let result = with_validated_mp4_output(&target, &ExportControl::default(), |mut file, _| {
+ file.write_all(b"not an MP4")?;
+ Ok(1)
+ });
+ assert!(format!("{:#}", result.unwrap_err()).contains("validating exported video"));
+ assert_eq!(fs::read(&target).unwrap(), b"previous export");
+ dir.assert_only("out.mp4");
+ }
+
+ /// Cancellation after rendering wins before validation and publication.
+ #[test]
+ fn cancellation_before_mp4_validation_preserves_destination() {
+ let dir = TestDir::new();
+ let target = dir.0.join("out.mp4");
+ fs::write(&target, b"previous export").unwrap();
+ let control = ExportControl::default();
+ let result = with_validated_mp4_output(&target, &control, |mut file, _| {
+ file.write_all(b"not an MP4")?;
+ assert!(control.cancel());
+ Ok(1)
+ });
+ assert!(result.unwrap_err().is::<ExportCancelled>());
+ assert_eq!(fs::read(&target).unwrap(), b"previous export");
+ dir.assert_only("out.mp4");
+ }
+
#[test]
fn cancellation_before_rendering_never_opens_output() {
let dir = TestDir::new();
diff --git a/crates/compositor/src/pipeline_linux.rs b/crates/compositor/src/pipeline_linux.rs
index e0fd1c262..15c8d2b15 100644
--- a/crates/compositor/src/pipeline_linux.rs
+++ b/crates/compositor/src/pipeline_linux.rs
@@ -35,7 +35,7 @@ use crate::audio::{
use crate::audio_jobs::{decode_and_stretch_clip_audio, ClipAudioJobs};
use crate::config::Cfg;
use crate::d3d::Gpu;
-use crate::export_control::{with_staged_output, ExportControl};
+use crate::export_control::{with_validated_mp4_output, ExportControl};
use crate::ffi::AVFrame;
use crate::linux_decode::SwDecoder;
use crate::timeline_walk::NextFrameTime;
@@ -872,7 +872,7 @@ pub fn run_composited_multi_cancellable(
progress: &mut dyn FnMut(u64),
control: &ExportControl,
) -> Result<Stats> {
- with_staged_output(Path::new(out), control, |file, staged| {
+ with_validated_mp4_output(Path::new(out), control, |file, staged| {
drop(file); // ffmpeg le rouvre par son nom
run_multi_inner(clips, &staged.to_string_lossy(), gpu, comp, cfg, params, progress, control)
})
diff --git a/crates/compositor/src/pipeline_macos.rs b/crates/compositor/src/pipeline_macos.rs
index 638b664f4..5cebfa1ed 100644
--- a/crates/compositor/src/pipeline_macos.rs
+++ b/crates/compositor/src/pipeline_macos.rs
@@ -37,7 +37,7 @@ use crate::audio::{
use crate::audio_jobs::{decode_and_stretch_clip_audio, ClipAudioJobs};
use crate::compositor::Compositor;
use crate::d3d::Gpu;
-use crate::export_control::{with_staged_output, ExportControl};
+use crate::export_control::{with_validated_mp4_output, ExportControl};
use crate::timeline_walk::NextFrameTime;
use anyhow::{anyhow, bail, Result};
use std::ffi::{c_void, CString};
@@ -1185,7 +1185,7 @@ pub fn run_composited_multi_cancellable(
progress: &mut dyn FnMut(u64),
control: &ExportControl,
) -> Result<Stats> {
- with_staged_output(Path::new(out), control, |file, staged| {
+ with_validated_mp4_output(Path::new(out), control, |file, staged| {
drop(file); // ffmpeg le rouvre par son nom
run_multi_inner(clips, &staged.to_string_lossy(), gpu, comp, cfg, params, progress, control)
})
@@ -1391,7 +1391,7 @@ fn run_multi_inner(
"write_trailer",
)?;
// Fichier fermé et contexte libéré par `_output` en fin de portée, avant que
- // `with_staged_output` ne renomme le MP4.
+ // `with_validated_mp4_output` ne renomme le MP4.
}
let wall_s = t0.elapsed().as_secs_f64();
diff --git a/crates/compositor/src/pipeline_windows.rs b/crates/compositor/src/pipeline_windows.rs
index 28bcc4faa..a697326b5 100644
--- a/crates/compositor/src/pipeline_windows.rs
+++ b/crates/compositor/src/pipeline_windows.rs
@@ -13,7 +13,7 @@ use crate::config::Cfg;
use crate::cpu_frames::CpuFrames;
use crate::cursor::CursorTrack;
use crate::d3d::{Backend, Gpu};
-use crate::export_control::{with_staged_output, ExportControl};
+use crate::export_control::{with_validated_mp4_output, ExportControl};
use crate::ffi::*;
use crate::regions::{speed_segments_for_window, SpeedSegment};
use crate::scene::Scene;
@@ -1343,7 +1343,7 @@ pub fn run_composited_multi_cancellable(
progress: &mut dyn FnMut(u64),
control: &ExportControl,
) -> Result<Stats> {
- with_staged_output(Path::new(out), control, |file, staged| {
+ with_validated_mp4_output(Path::new(out), control, |file, staged| {
drop(file); // ffmpeg le rouvre par son nom
unsafe {
run_multi_inner(clips, &staged.to_string_lossy(), gpu, comp, cfg, params, progress, control)
@@ -1875,7 +1875,7 @@ unsafe fn run_multi_inner(
let wall_s = t0.elapsed().as_secs_f64();
// teardown : les gardes et les Drop (décodeurs, encodeurs) en fin de portée — fichier fermé
- // avant que `with_staged_output` ne le renomme.
+ // avant que `with_validated_mp4_output` ne le renomme.
let fps = frames as f64 / wall_s;
Ok(Stats { frames, wall_s, fps, video_duration_s: frames as f64 / out_fps as f64 })
}
diff --git a/crates/compositor/src/timeline_walk.rs b/crates/compositor/src/timeline_walk.rs
index 28e8518ad..59c00150e 100644
--- a/crates/compositor/src/timeline_walk.rs
+++ b/crates/compositor/src/timeline_walk.rs
@@ -262,6 +262,7 @@ unsafe fn catch_up(dec: &mut Decoder, target: f64, clip_start: f64) -> Result<()
/// hide a genuinely truncated camera recording.
const CLIP_START_TAIL_TOLERANCE_SEC: f64 = 0.5;
+/// Seek a clip start, holding the last frame only within the normal tail margin.
unsafe fn seek_clip_start(decoder: &mut Decoder, target: f64) -> Result<bool> {
let frame = decoder.seek_to_or_last(target)?;
Ok(!frame.is_null()
@@ -412,7 +413,9 @@ unsafe fn walk_timeline(
// un seul seek keyframe, puis chaque décodeur avance selon son propre pts jusqu'aux
// temps source demandés par les spans de vitesse.
- if !seek_clip_start(sdec, clip.source_start_sec)? {
+ if !seek_clip_start(sdec, clip.source_start_sec)
+ .with_context(|| format!("Cannot export clip {}: could not read the screen video.", clip_index + 1))?
+ {
bail!("Cannot export clip {}: the screen video has no readable frame at the clip's start.", clip_index + 1);
}
let webcam_start = if has_camera {
diff --git a/crates/compositor/tests/export_timing.rs b/crates/compositor/tests/export_timing.rs
index 8581ebe2c..ba917d202 100644
--- a/crates/compositor/tests/export_timing.rs
+++ b/crates/compositor/tests/export_timing.rs
@@ -231,6 +231,7 @@ fn mp4_export_rejects_an_unreadable_camera_without_publishing() {
std::fs::remove_dir_all(out_dir).expect("remove test outputs");
}
+/// An entirely out-of-range timeline cannot publish an empty replacement.
#[test]
fn mp4_export_rejects_a_timeline_that_produces_no_frames() {
let Some(dir) = media_dir() else {
@@ -426,6 +427,103 @@ fn mp4_export_bounds_tail_recovery_and_reports_the_correct_source() {
std::fs::remove_dir_all(out_dir).expect("remove test outputs");
}
+/// The staged decode check must accept short exports in both supported MP4 codecs.
+#[cfg(target_os = "macos")]
+#[test]
+fn mp4_export_validation_accepts_h264_and_hevc() {
+ let Some(dir) = media_dir() else {
+ eprintln!("skipped: set OPENSCREEN_TEST_MEDIA");
+ return;
+ };
+ let out_dir = dir.join(format!("validated_codecs-{}", std::process::id()));
+ std::fs::create_dir_all(&out_dir).expect("output dir");
+ let gpu = Gpu::create(false).expect("gpu");
+ let comp = Compositor::new_sized(&gpu, 640, 360).expect("compositor");
+ for codec in [ExportCodec::H264, ExportCodec::H265] {
+ let params = ExportParams {
+ width: 640, height: 360, fps: Some(30), codec, bit_rate: None,
+ };
+ let mut clip = whole_clip(&dir);
+ clip.source_end_sec = 0.2;
+ let out = out_dir.join("out.mp4");
+ std::fs::write(&out, b"previous export").expect("seed destination");
+ let stats = pipeline::run_composited_multi(
+ &[clip], &out.to_string_lossy(), &gpu, &comp, &Cfg::c8(), &params, &mut |_| {},
+ ).expect("valid encoded video must pass validation");
+ assert_eq!(stats.frames, 6);
+ assert_ne!(std::fs::read(&out).unwrap(), b"previous export");
+ std::fs::remove_file(out).expect("remove output");
+ assert_eq!(std::fs::read_dir(&out_dir).unwrap().count(), 0);
+ }
+ std::fs::remove_dir(out_dir).expect("remove output dir");
+}
+
+/// VideoToolbox can mux one tail sample with zero duration and mark it discard.
+/// A positive composed-frame count must not let that file replace a good export.
+#[cfg(target_os = "macos")]
+#[test]
+fn mp4_export_rejects_an_undecodable_single_tail_frame_without_publishing() {
+ let Some(dir) = media_dir() else {
+ eprintln!("skipped: set OPENSCREEN_TEST_MEDIA");
+ return;
+ };
+ let out_dir = dir.join(format!("undecodable_single_tail-{}", std::process::id()));
+ std::fs::create_dir_all(&out_dir).expect("output dir");
+ let out = out_dir.join("out.mp4");
+ let gpu = Gpu::create(false).expect("gpu");
+ let comp = Compositor::new_sized(&gpu, 640, 360).expect("compositor");
+ let params = ExportParams {
+ width: 640,
+ height: 360,
+ fps: Some(30),
+ codec: ExportCodec::H264,
+ bit_rate: None,
+ };
+ let mut tail = whole_clip(&dir);
+ tail.webcam.clear();
+ tail.source_start_sec = SOURCE_SEC - 0.01;
+ for existing_destination in [false, true] {
+ if existing_destination {
+ std::fs::write(&out, b"previous export").expect("seed destination");
+ }
+ let result = pipeline::run_composited_multi(
+ &[ClipSource {
+ screen: tail.screen.clone(),
+ webcam: String::new(),
+ source_start_sec: tail.source_start_sec,
+ source_end_sec: tail.source_end_sec,
+ webcam_offset_sec: 0.0,
+ has_audio: false,
+ }],
+ &out.to_string_lossy(),
+ &gpu,
+ &comp,
+ &Cfg::c8(),
+ &params,
+ &mut |_| {},
+ );
+ let error = result
+ .err()
+ .expect("undecodable output must not be published");
+ assert!(
+ format!("{error:#}").contains("validating exported video"),
+ "{error:#}"
+ );
+ if existing_destination {
+ assert_eq!(std::fs::read(&out).unwrap(), b"previous export");
+ std::fs::remove_file(&out).expect("remove destination");
+ } else {
+ assert!(!out.exists());
+ }
+ assert_eq!(
+ std::fs::read_dir(&out_dir).unwrap().count(),
+ 0,
+ "partial output left behind"
+ );
+ }
+ std::fs::remove_dir(out_dir).expect("remove output dir");
+}
+
/// Cancelling an MP4 mid-render stops the walk at the next frame, reports `ExportCancelled`,
/// and publishes nothing: the destination keeps what it held and no partial is left beside
/// it. On Windows that last check also proves the muxer closed its file, since an open
diff --git a/technical-documentation/architecture/export-pipeline.md b/technical-documentation/architecture/export-pipeline.md
index 6149c5d46..79bdcb80d 100644
--- a/technical-documentation/architecture/export-pipeline.md
+++ b/technical-documentation/architecture/export-pipeline.md
@@ -153,7 +153,14 @@ and **one** encoder + muxer pair:
within the 0.5-second tail margin (audio can outlast video). Clips starting
beyond their declared end within this margin retain the existing skip
behavior; an entirely empty export still fails. Screen-only clips report
- screen errors, including errors from the stand-in decoder.
+ screen errors, including errors from the stand-in decoder. MP4 export then
+ closes and reopens the staged file and software-decodes until the first
+ displayable video frame before replacing the destination. Discard-marked
+ preroll is decoded to maintain reference state, but discard-marked output
+ frames do not satisfy validation. A single muxed sample or positive render
+ count is not sufficient. Validation errors or cancellation remove the staged
+ file and preserve the destination. This is a first-frame check, not a
+ full-file integrity scan; encoder timing for single-frame files is not repaired.
- **Imported audio tracks** (voiceover / BGM / SFX, issue #350) are mixed
on top of the assembled programme by `audio.rs::mix_external_tracks`,
diff --git a/technical-documentation/testing/manual-e2e-checklist.md b/technical-documentation/testing/manual-e2e-checklist.md
index c6bf2102e..f09cf468b 100644
--- a/technical-documentation/testing/manual-e2e-checklist.md
+++ b/technical-documentation/testing/manual-e2e-checklist.md
@@ -913,6 +913,7 @@ These checks are the human slice: an agent cannot click Apple's picker (see abov
| Date | Build / tag | Platform | Pass/fail | Notes |
|------|-------------|----------|-----------|-------|
+| 2026-10-24 | dev CodeRabbit follow-up to PR #1377; rebuilt addon SHA256 `8fe1baab14e941a5ba6d73b5596a27190a75edcd8b49630b451868f829bdaf71` | macOS 15.7.1, Apple Silicon | Partial — undecodable output rejected; destination preserved; retry passed | Computer-use reopened the same synthetic tail-only project used in the previous run, selected an existing synthetic MP4, and confirmed the native replace prompt. Export now reports validation failure instead of Saved. Destination SHA256 remained `854b0911778da18c2a456d3eb227da749c0af2138ad52092180156ed138a6a48`; no partial output remained. Without restarting the app, loaded the four-second valid clip plus tail and retried MP4 1080p/30: Saved, native walk 121 frames, independent ffprobe 120 decoded frames / 4.000 s at 1752×1080, full-file decode exit 0. This closes the publication-safety gap observed in the previous row; single-frame encoder timing itself remains unchanged. Native tests also cover absent/existing destination, malformed output, cancellation and successful H264/HEVC export. Recording, Presenter Overlay, unrelated editor features, Windows/Linux runtime and release packaging were not exercised. |
| 2026-10-24 | dev `fix/reject-empty-exports`, PR #1377 follow-up; rebuilt addon SHA256 `2ad4ce50da3e2e8dd2a6dc67017048d5ae515f5b0d7143d509d727c9d09c29da` | macOS 15.7.1, Apple Silicon | Partial — multiclip GUI export passed; single-frame muxing limit observed | Computer-use opened an isolated profile and a synthetic four-second clip followed by a 10 ms tail starting at 3.99 s. MP4 1080p/30 displayed Saved; native walk reported 121 frames, independent ffprobe decoded 120 frames / 4.000 s at 1752×1080, and full-file decode completed without errors. Tail alone produced one muxed video sample with zero video duration and no decoded video frames; this additional single-frame muxing case is unresolved and no baseline attribution is claimed. Initial native-path entry failed; selecting the prepared project in the file list worked. Native export/inspection tests separately: 7 passed, 1 existing macOS frame-count-probe stub failure. Recording, Presenter Overlay compatibility, other editor features, Windows/Linux runtime and release validation were not exercised. |
| 2026-09-23 | dev `fix/725-hidden-cursor-auto-zoom`; rebuilt compositor addon SHA256 `a0bcd61e17084c010141049a9978121e45be2985449ff1618ab6a3145f8381f6` | Windows 11 Home 26200 | Partial — issue #725 slider slice passed | Human-driven real recording in the Electron dev build: moving a slider whose application cursor becomes hidden kept the reconstructed cursor hidden in the Studio recording and did not create a click-driven automatic zoom for that press. A visible control click still produced the normal automatic zoom. Sidecar inspection independently confirmed the hidden interval (`visible: false`) and that no zoom was centred on the press immediately preceding it. Recording, stop and editor open passed. Not covered: export, packaged build, audio/webcam, tray/HUD, other editor features, macOS or Linux. |
| 2026-09-12 | dev `fix/643-gif-export-cancel`, based on `fbe461e9`; rebuilt compositor addon SHA256 `128c89fe65a459b3f17721d610ea9a78e0d3e980e9eb0b5fb2b0e5d018619e15` | Windows | Partial — export cancellation passed | Computer-use OS input, real Electron and native save dialog, imported synthetic 8 s source. GIF 15 FPS / Medium (720p) / loop on: observed 55/120 frames, clicked Cancel while rendering (pending snapshot 104/120), returned to the same options; no final or partial output remained. Retried in that dialog to the same path and received Saved to; resulting GIF is 1280×720, 120 frames, 8,200,202 bytes, fully decodes with ffmpeg (exit 0). Automated real-addon tests separately pass existing-destination preservation, GIF retry, ordinary GIF and MP4 export. Desktop adapter required screenshot-based coordinates and Ctrl+O to reach the editor; HUD reachability is not claimed. An unrelated process error window partly obscured the retry success screenshot; file verification independently passed. Skipped: recording, audio/mic, webcam, tray/HUD, effect/caption comparisons, second viewer, macOS/Linux and release promotion. Task-local profile and evidence retained; test app stopped. |