Open source Loom alternative. Beautiful, shareable screen recordings.
Rust appcapcossloommacnextjsnextjs15open-sourceossreactrecordrustscreen-capturescreen-recorderscreenshotsolidjstauritauri-apptypescriptvite
use cap_project::{
InstantRecordingMeta, Platform, ProjectConfiguration, RecordingMeta, RecordingMetaInner,
};
use cap_recording::{
CameraFeed, DoneFut, MicrophoneFeed, PipelineStoppedByUser,
feeds::{camera, microphone},
instant_recording,
screen_capture::ScreenCaptureTarget,
studio_recording::{self, ActorHandle as StudioActorHandle},
upload_resume::UploadLock,
};
use clap::{Args, ValueEnum};
use futures::FutureExt;
use kameo::Actor as _;
use scap_targets::{DisplayId, WindowId};
use serde::Serialize;
use std::{
env::current_dir,
io::IsTerminal,
path::{Path, PathBuf},
process::Stdio,
sync::Arc,
time::{Duration, Instant},
};
use tokio::io::AsyncBufReadExt;
use tracing::debug;
use uuid::Uuid;
use crate::{
OutputFormat, resolve_format,
session::{self, Session, SessionStatus},
write_json, write_json_line,
};
/// Recording inputs shared between the foreground recorder, the `--detach` parent, and the
/// re-exec'd background worker. Kept in one struct so the worker can be invoked with exactly the
/// flags the parent received (see [`RecordParams::to_cli_args`]).
#[derive(Args, Clone)]
pub struct RecordParams {
#[command(flatten)]
target: RecordTargets,
/// Recording mode to use
#[arg(long, value_enum, default_value_t = RecordMode::Studio)]
mode: RecordMode,
/// Capture from the camera with this device id (see `cap targets cameras`)
#[arg(long)]
camera: Option<String>,
/// Capture from the microphone with this device name (see `cap targets mics`)
#[arg(long)]
mic: Option<String>,
/// Whether to capture system audio
#[arg(long)]
system_audio: bool,
#[arg(
long,
help = "New '.cap' project path (defaults to <recordingId>.cap in the working directory). The path must not already exist, including an empty directory."
)]
path: Option<PathBuf>,
/// Maximum fps to record at (clamped to 1-120; camera recordings follow the desktop camera cap)
#[arg(long)]
fps: Option<u32>,
/// Stop automatically after N seconds
#[arg(long)]
duration: Option<f64>,
}
impl RecordParams {
fn validate(&self) -> Result<(), String> {
if self.duration.is_some_and(|duration| {
// `> u64::MAX` would panic in `Duration::from_secs_f64` (used by `wait_for_stop`).
!duration.is_finite() || duration <= 0.0 || duration > u64::MAX as f64
}) {
return Err("Duration must be a positive, finite number of seconds".to_string());
}
if self.fps == Some(0) {
return Err("--fps must be greater than 0".to_string());
}
Ok(())
}
fn to_cli_args(&self) -> Vec<String> {
let mut args = Vec::new();
if let Some(id) = &self.target.screen {
args.push("--screen".to_string());
args.push(id.to_string());
}
if let Some(id) = &self.target.window {
args.push("--window".to_string());
args.push(id.to_string());
}
args.push("--mode".to_string());
args.push(self.mode.to_string());
if let Some(camera) = &self.camera {
args.push("--camera".to_string());
args.push(camera.clone());
}
if let Some(mic) = &self.mic {
args.push("--mic".to_string());
args.push(mic.clone());
}
if self.system_audio {
args.push("--system-audio".to_string());
}
if let Some(path) = &self.path {
args.push("--path".to_string());
args.push(path.display().to_string());
}
if let Some(fps) = self.fps {
args.push("--fps".to_string());
args.push(fps.to_string());
}
if let Some(duration) = self.duration {
args.push("--duration".to_string());
args.push(duration.to_string());
}
args
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)]
pub enum RecordMode {
Studio,
Instant,
}
impl std::fmt::Display for RecordMode {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Studio => f.write_str("studio"),
Self::Instant => f.write_str("instant"),
}
}
}
#[derive(Args)]
pub struct RecordStart {
#[command(flatten)]
params: RecordParams,
/// Record in the background and return immediately; stop later with `cap record stop`
#[arg(long)]
detach: bool,
/// Output format for status events
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
/// Hidden worker entrypoint. `cap record start --detach` re-execs the binary as
/// `cap record __session-run` so the recording outlives the parent process.
#[derive(Args)]
pub struct SessionRunArgs {
#[command(flatten)]
params: RecordParams,
#[arg(long)]
session_id: String,
}
#[derive(Args)]
pub struct RecordStopArgs {
/// recordingId returned by `cap record start --detach`
#[arg(long)]
id: Option<String>,
/// The '.cap' project path of the recording to stop (alternative to --id)
#[arg(long)]
path: Option<PathBuf>,
/// Seconds to wait for the recording to finalize before giving up
#[arg(long, default_value_t = 30.0)]
timeout: f64,
/// Output format for status events
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
impl RecordStart {
pub async fn run(self, json: bool) -> Result<(), String> {
let format = resolve_format(json, self.format);
match self.run_inner(format).await {
Ok(()) => Ok(()),
Err(error) => {
if format == OutputFormat::Json {
let _ = write_json_line(&RecordEvent::Error { error: &error });
}
Err(error)
}
}
}
async fn run_inner(self, format: OutputFormat) -> Result<(), String> {
self.params.validate()?;
if self.detach {
run_detached(self.params, format).await
} else {
run_foreground(self.params, format).await
}
}
}
async fn run_foreground(params: RecordParams, format: OutputFormat) -> Result<(), String> {
let interactive = std::io::stdin().is_terminal();
// Without --duration the recorder blocks for a stop signal. A non-interactive caller (agent, CI,
// /dev/null stdin) hits EOF immediately and would otherwise produce a ~0s recording that exits
// successfully. Require an explicit duration, or point them at the detached lifecycle.
if params.duration.is_none() && !interactive {
return Err(
"Recording without --duration requires an interactive terminal; pass --duration <seconds>, \
or use `cap record start --detach` and stop it later with `cap record stop`"
.to_string(),
);
}
let recording_id = new_recording_id();
let target = resolve_target(¶ms)?;
let path = resolve_path(¶ms, &recording_id)?;
let actor = start_recording(¶ms, target, path.clone()).await?;
let path_display = path.display().to_string();
// The recording is now writing to disk, so every path from here must finalize the actor.
if let Err(error) = emit_record_event(
format,
&RecordEvent::Started {
recording_id: &recording_id,
pid: std::process::id(),
path: &path_display,
},
) {
if let Ok(completed) = actor.stop().await {
let _ = finalize_completed(completed).await;
}
return Err(error);
}
if params.duration.is_none() && interactive && format == OutputFormat::Text {
println!("Press Enter to stop (or send SIGINT/SIGTERM)");
}
let completed = finalize(actor, params.duration, interactive, None).await?;
crate::automation::run_recording_finished(
completed.project_path(),
automation_mode(params.mode),
)
.await;
emit_stopped(format, &completed)
}
fn automation_mode(mode: RecordMode) -> cap_automation::AutomationRecordingMode {
match mode {
RecordMode::Studio => cap_automation::AutomationRecordingMode::Studio,
RecordMode::Instant => cap_automation::AutomationRecordingMode::Instant,
}
}
async fn run_detached(params: RecordParams, format: OutputFormat) -> Result<(), String> {
let recording_id = new_recording_id();
// Validate the target up front so a bad --screen/--window fails fast with a clear message rather
// than surfacing later from the background worker's log.
resolve_target(¶ms)?;
let path = resolve_path(¶ms, &recording_id)?;
let path = if path.is_absolute() {
path
} else {
current_dir()
.map_err(|e| format!("Could not determine current directory: {e}"))?
.join(path)
};
let exe =
std::env::current_exe().map_err(|e| format!("Could not locate the cap executable: {e}"))?;
let sessions_dir = session::sessions_dir()?;
std::fs::create_dir_all(&sessions_dir)
.map_err(|e| format!("Could not create sessions dir: {e}"))?;
let log_path = session::log_file(&recording_id)?;
let log = std::fs::File::create(&log_path)
.map_err(|e| format!("Could not create session log {}: {e}", log_path.display()))?;
let log_err = log
.try_clone()
.map_err(|e| format!("Could not prepare session log: {e}"))?;
let mut worker_params = params.clone();
worker_params.path = Some(path.clone());
let mut command = std::process::Command::new(&exe);
command
.arg("record")
.arg("__session-run")
.arg("--session-id")
.arg(&recording_id)
.args(worker_params.to_cli_args())
.stdin(Stdio::null())
.stdout(Stdio::from(log))
.stderr(Stdio::from(log_err));
// Detach from the parent so closing the parent's shell/pipeline does not signal the recording
// worker. On unix this means a new process group; on Windows, no console + a new process group so
// a Ctrl-C / console-close in the launching terminal does not reach the worker.
#[cfg(unix)]
{
use std::os::unix::process::CommandExt;
command.process_group(0);
}
#[cfg(windows)]
{
use std::os::windows::process::CommandExt;
const DETACHED_PROCESS: u32 = 0x0000_0008;
const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
command.creation_flags(DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP);
}
let child = command
.spawn()
.map_err(|e| format!("Could not start the recording worker: {e}"))?;
let pid = child.id();
let session = wait_for_session_ready(&recording_id, child).await?;
if let Err(error) = emit_record_event(
format,
&RecordEvent::Started {
recording_id: &recording_id,
pid,
path: &session.path.display().to_string(),
},
) {
// The worker is already recording in its own process group. If we cannot hand the caller the
// recordingId it could never stop it, so tear the recording down rather than leak an orphan.
let _ = session::request_stop(&recording_id);
if session::process_alive(pid) {
session::terminate(pid);
}
return Err(format!(
"{error}; background recording {recording_id} was stopped because its start event could not be delivered"
));
}
Ok(())
}
async fn wait_for_session_ready(
recording_id: &str,
mut child: std::process::Child,
) -> Result<Session, String> {
let deadline = Instant::now() + Duration::from_secs(20);
loop {
if let Ok(Some(status)) = child.try_wait() {
// The worker has provably exited. A clean `Stopped` is success (a short `--duration` run can
// finish before the parent's first poll); a leftover `Recording` means it died mid-recording
// without finalizing, so fall through to the error rather than report a healthy start.
if let Ok(session) = session::read_session(recording_id) {
match session.status {
SessionStatus::Stopped => return Ok(session),
SessionStatus::Error => {
return Err(session
.error
.unwrap_or_else(|| "recording worker failed to start".to_string()));
}
SessionStatus::Recording if session::process_alive(session.pid) => {
return Ok(session);
}
SessionStatus::Recording => {}
}
}
let log = session::log_file(recording_id)
.map(|p| p.display().to_string())
.unwrap_or_default();
return Err(format!(
"recording worker exited before finalizing the recording ({status}); see {log}"
));
}
if let Ok(session) = session::read_session(recording_id) {
match session.status {
SessionStatus::Recording | SessionStatus::Stopped => return Ok(session),
SessionStatus::Error => {
let _ = child.kill();
return Err(session
.error
.unwrap_or_else(|| "recording failed to start".to_string()));
}
}
}
if Instant::now() >= deadline {
let _ = child.kill();
return Err("timed out waiting for the recording to start".to_string());
}
tokio::time::sleep(Duration::from_millis(150)).await;
}
}
impl SessionRunArgs {
pub async fn run(self) -> Result<(), String> {
let recording_id = self.session_id;
match session_worker(self.params, &recording_id).await {
Ok(()) => Ok(()),
Err(error) => {
// Record the failure so the parent (`record start`) and `record stop` can surface it
// instead of an opaque exit. Reuse the startedAt/path the worker may already have
// written for the Recording session so the Error row keeps the real start time, which
// `record status` sorts by.
let prior = session::read_session(&recording_id).ok();
let _ = session::write_session(&Session {
pid: std::process::id(),
path: prior.as_ref().map(|s| s.path.clone()).unwrap_or_default(),
status: SessionStatus::Error,
started_at: prior
.as_ref()
.and_then(|s| s.started_at)
.or_else(session::now_unix),
recording_meta_exists: None,
error: Some(error.clone()),
recording_id,
});
Err(error)
}
}
}
}
async fn session_worker(params: RecordParams, recording_id: &str) -> Result<(), String> {
let target = resolve_target(¶ms)?;
let path = params
.path
.clone()
.ok_or_else(|| "internal: detached worker started without --path".to_string())?;
let actor = start_recording(¶ms, target, path.clone()).await?;
// Stamp the start time once; reusing it for the Stopped write keeps `startedAt` meaning the start
// (not the stop), which `list_sessions` relies on to sort recordings newest-first.
let started_at = session::now_unix();
session::write_session(&Session {
recording_id: recording_id.to_string(),
pid: std::process::id(),
path: path.clone(),
status: SessionStatus::Recording,
started_at,
recording_meta_exists: None,
error: None,
})?;
let stop_path = session::stop_file(recording_id)?;
let completed = finalize(actor, params.duration, false, Some(&stop_path)).await?;
crate::automation::run_recording_finished(
completed.project_path(),
automation_mode(params.mode),
)
.await;
let recording_meta_exists = completed
.project_path()
.join("recording-meta.json")
.exists();
session::write_session(&Session {
recording_id: recording_id.to_string(),
pid: std::process::id(),
path: completed.project_path().to_path_buf(),
status: SessionStatus::Stopped,
started_at,
recording_meta_exists: Some(recording_meta_exists),
error: None,
})
}
impl RecordStopArgs {
pub async fn run(self, json: bool) -> Result<(), String> {
let format = resolve_format(json, self.format);
match self.run_inner(format).await {
Ok(()) => Ok(()),
Err(error) => {
if format == OutputFormat::Json {
let _ = write_json_line(&RecordEvent::Error { error: &error });
}
Err(error)
}
}
}
async fn run_inner(self, format: OutputFormat) -> Result<(), String> {
let session = resolve_session(self.id.as_deref(), self.path.as_deref())?;
let id = session.recording_id.clone();
if session.status == SessionStatus::Stopped {
emit_record_event(
format,
&RecordEvent::Stopped {
path: &session.path.display().to_string(),
recording_meta_exists: session.recording_meta_exists.unwrap_or(true),
},
)?;
cleanup_session(&id, &session.path);
return Ok(());
}
session::request_stop(&id)?;
let deadline = Instant::now() + Duration::from_secs_f64(self.timeout.max(0.0));
loop {
let current = session::read_session(&id).unwrap_or_else(|_| session.clone());
match current.status {
SessionStatus::Stopped => {
emit_record_event(
format,
&RecordEvent::Stopped {
path: ¤t.path.display().to_string(),
recording_meta_exists: current.recording_meta_exists.unwrap_or(true),
},
)?;
cleanup_session(&id, ¤t.path);
return Ok(());
}
SessionStatus::Error => {
cleanup_session(&id, ¤t.path);
return Err(current
.error
.unwrap_or_else(|| "recording failed".to_string()));
}
SessionStatus::Recording => {}
}
if !session::process_alive(current.pid) {
let recording_meta_exists = current.path.join("recording-meta.json").exists();
if !recording_meta_exists {
return fail_dead_session(
current,
"recording process exited without finalizing the recording".to_string(),
);
}
if let Err(error) = crate::project::validate_project(¤t.path) {
return fail_dead_session(current, error);
}
cleanup_session(&id, ¤t.path);
return emit_record_event(
format,
&RecordEvent::Stopped {
path: ¤t.path.display().to_string(),
recording_meta_exists: true,
},
);
}
if Instant::now() >= deadline {
if session::process_alive(current.pid) {
session::terminate(current.pid);
}
return Err(format!(
"timed out after {}s waiting for recording '{id}' to stop",
self.timeout
));
}
tokio::time::sleep(Duration::from_millis(150)).await;
}
}
}
fn cleanup_session(id: &str, project_path: &Path) {
if let Err(error) = session::archive_log(id, project_path) {
debug!("{error}");
}
session::cleanup(id);
}
fn fail_dead_session(session: Session, error: String) -> Result<(), String> {
let _ = session::write_session(&Session {
status: SessionStatus::Error,
error: Some(error.clone()),
..session
});
Err(error)
}
fn resolve_session(id: Option<&str>, path: Option<&Path>) -> Result<Session, String> {
if let Some(id) = id {
return session::read_session(id);
}
let sessions = session::list_sessions()?;
if let Some(path) = path {
let wanted = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
return sessions
.into_iter()
.find(|s| {
s.path == path
|| std::fs::canonicalize(&s.path).is_ok_and(|resolved| resolved == wanted)
})
.ok_or_else(|| format!("No recording session found for path {}", path.display()));
}
let mut active: Vec<Session> = sessions
.into_iter()
.filter(|s| s.status == SessionStatus::Recording)
.collect();
match active.len() {
0 => Err(
"No active recording sessions. Start one with `cap record start --detach`".to_string(),
),
1 => Ok(active.remove(0)),
_ => {
let ids: Vec<&str> = active.iter().map(|s| s.recording_id.as_str()).collect();
Err(format!(
"Multiple active recordings; pass --id <recordingId>. Active: {ids:?}"
))
}
}
}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct SessionStatusRow {
recording_id: String,
pid: u32,
path: PathBuf,
status: SessionStatus,
alive: bool,
#[serde(skip_serializing_if = "Option::is_none")]
started_at: Option<u64>,
#[serde(skip_serializing_if = "Option::is_none")]
error: Option<String>,
}
pub fn status(format: OutputFormat) -> Result<(), String> {
let rows: Vec<SessionStatusRow> = session::list_sessions()?
.into_iter()
.map(session_status_row)
.collect();
match format {
OutputFormat::Json => write_json(&rows),
OutputFormat::Text => {
if rows.is_empty() {
println!("No recording sessions");
return Ok(());
}
for row in &rows {
let status = match row.status {
SessionStatus::Recording => "recording",
SessionStatus::Stopped => "stopped",
SessionStatus::Error => "error",
};
println!(
"{} [{status}] pid {} {}",
row.recording_id,
row.pid,
row.path.display()
);
}
Ok(())
}
}
}
fn session_status_row(session: Session) -> SessionStatusRow {
let alive = session.status == SessionStatus::Recording && session::process_alive(session.pid);
session_status_row_with_alive(session, alive)
}
fn session_status_row_with_alive(session: Session, alive: bool) -> SessionStatusRow {
let process_gone = session.status == SessionStatus::Recording && !alive;
let status = if process_gone {
SessionStatus::Error
} else {
session.status
};
let error = if process_gone {
Some("recording process is not running".to_string())
} else {
session.error
};
SessionStatusRow {
recording_id: session.recording_id,
pid: session.pid,
path: session.path,
status,
alive,
started_at: session.started_at,
error,
}
}
enum ActorHandle {
Studio(StudioActorHandle),
Instant {
actor: instant_recording::ActorHandle,
_upload_lock: UploadLock,
},
}
impl ActorHandle {
fn done_fut(&self) -> DoneFut {
match self {
Self::Studio(actor) => actor.done_fut(),
Self::Instant { actor, .. } => actor.done_fut(),
}
}
async fn stop(&self) -> Result<CompletedRecording, String> {
match self {
Self::Studio(actor) => actor
.stop()
.await
.map(Box::new)
.map(CompletedRecording::Studio)
.map_err(|e| format!("{e:#}")),
Self::Instant { actor, .. } => actor
.stop()
.await
.map(CompletedRecording::Instant)
.map_err(|e| format!("{e:#}")),
}
}
}
enum CompletedRecording {
Studio(Box<studio_recording::CompletedRecording>),
Instant(instant_recording::CompletedRecording),
}
impl CompletedRecording {
fn project_path(&self) -> &Path {
match self {
Self::Studio(recording) => &recording.project_path,
Self::Instant(recording) => &recording.project_path,
}
}
}
async fn start_recording(
params: &RecordParams,
target: ScreenCaptureTarget,
path: PathBuf,
) -> Result<ActorHandle, String> {
let upload_lock = prepare_recording_project(
&path,
params.mode,
params.mic.is_some() || params.system_audio,
)?;
#[cfg(target_os = "macos")]
let target_for_shareable_content = target.clone();
let camera_only_target = matches!(target, ScreenCaptureTarget::CameraOnly);
let mut studio_builder = studio_recording::Actor::builder(path.clone(), target.clone())
.with_system_audio(params.system_audio);
let mut instant_builder =
instant_recording::Actor::builder(path, target).with_system_audio(params.system_audio);
let mut camera_active = false;
let camera_recorded =
!(cfg!(target_os = "macos") && params.mode == RecordMode::Instant && !camera_only_target);
// Feeds must be locked and attached before build(); the lock keeps the device open for the whole
// recording, so the feed actor handle itself does not need to be retained.
// macOS Instant recordings capture only the screen (the desktop app's camera bubble is part of
// the screen), so a camera opened here would run for the whole recording without being recorded.
if params.camera.is_some() && !camera_recorded {
eprintln!(
"warning: --camera is ignored for Instant recordings on macOS; the camera is only recorded in Studio mode"
);
}
if let Some(device_id) = params.camera.as_deref().filter(|_| camera_recorded) {
let info = cap_camera::list_cameras()
.find(|c| c.device_id() == device_id)
.ok_or_else(|| {
let available: Vec<String> = cap_camera::list_cameras()
.map(|c| c.device_id().to_string())
.collect();
format!(
"Camera with id '{device_id}' not found. Available device ids: {available:?} \
(see `cap targets cameras`)"
)
})?;
let id = camera::DeviceOrModelID::from_info(&info);
let camera_feed = CameraFeed::spawn(CameraFeed::default());
camera_feed
.ask(camera::SetInput { id, settings: None })
.await
.map_err(|e| format!("Failed to set camera input: {e}"))?
.await
.map_err(|e| format!("Camera failed to connect: {e}"))?;
let lock = camera_feed
.ask(camera::Lock)
.await
.map_err(|e| format!("Failed to lock camera feed: {e}"))?;
let lock = Arc::new(lock);
studio_builder = studio_builder.with_camera_feed(lock.clone());
instant_builder = instant_builder.with_camera_feed(lock);
camera_active = true;
}
if let Some(mic_name) = params.mic.as_deref() {
let available = MicrophoneFeed::list();
if !available.contains_key(mic_name) {
let names: Vec<&str> = available.keys().map(String::as_str).collect();
return Err(format!(
"Microphone '{mic_name}' not found. Available: {names:?} (see `cap targets mics`)"
));
}
let (error_tx, _error_rx) = flume::bounded(16);
let mic_feed = MicrophoneFeed::spawn(MicrophoneFeed::new(error_tx));
mic_feed
.ask(microphone::SetInput {
label: mic_name.to_string(),
settings: None,
})
.await
.map_err(|e| format!("Failed to set mic input: {e}"))?
.await
.map_err(|e| format!("Mic failed to connect: {e}"))?;
// The stream needs a moment to warm up before locking on slower devices.
tokio::time::sleep(Duration::from_millis(100)).await;
let lock = mic_feed
.ask(microphone::Lock)
.await
.map_err(|e| format!("Failed to lock mic feed: {e}"))?;
let lock = Arc::new(lock);
studio_builder = studio_builder.with_mic_feed(lock.clone());
instant_builder = instant_builder.with_mic_feed(lock);
}
match params.mode {
RecordMode::Studio => {
let builder = cap_recording::RecordingDefaults::default().apply_to_studio_builder(
studio_builder,
camera_active,
params.fps,
);
builder
.build(
#[cfg(target_os = "macos")]
Some(
acquire_shareable_content_for_target(&target_for_shareable_content).await?,
),
)
.await
.map(ActorHandle::Studio)
.map_err(|e| e.to_string())
}
RecordMode::Instant => {
let upload_lock = upload_lock
.ok_or_else(|| "Instant recording project ownership is unavailable".to_string())?;
let mut builder = instant_builder;
#[cfg(target_os = "linux")]
if camera_active {
builder = builder.with_linux_camera_composition();
}
builder = builder.with_max_output_size(
cap_recording::RecordingDefaults::default().instant_mode_max_resolution,
);
if let Some(fps) = params.fps {
builder = builder.with_max_fps(fps);
}
// As in the desktop app: the screen and audio tracks both start at
// the gate's arm time, so a microphone that is ready late does not
// move all audio early. The CLI has no start cue to wait for.
let start_gate = cap_recording::RecordingStartGate::new();
builder = builder.with_start_gate(start_gate.clone());
let actor = builder
.build(
#[cfg(target_os = "macos")]
Some(
acquire_shareable_content_for_target(&target_for_shareable_content).await?,
),
)
.await
.map_err(|e| e.to_string())?;
start_gate.arm();
Ok(ActorHandle::Instant {
actor,
_upload_lock: upload_lock,
})
}
}
}
#[cfg(target_os = "macos")]
async fn acquire_shareable_content_for_target(
target: &ScreenCaptureTarget,
) -> Result<cap_recording::SendableShareableContent, String> {
let mut available_display_ids = Vec::new();
for attempt in 0..3 {
let shareable_content = read_shareable_content().await?;
available_display_ids = shareable_content_display_ids(&shareable_content);
if !shareable_content_missing_target_display(target, &shareable_content) {
return Ok(shareable_content);
}
if attempt < 2 {
tokio::time::sleep(Duration::from_millis(150)).await;
}
}
let requested_display = target
.display()
.map(|display| display.id().to_string())
.unwrap_or_else(|| "none".to_string());
Err(format!(
"ScreenCaptureKit shareable content missing target display {requested_display}. Available display ids: {available_display_ids:?}"
))
}
#[cfg(target_os = "macos")]
async fn read_shareable_content() -> Result<cap_recording::SendableShareableContent, String> {
let content = cidre::sc::ShareableContent::current()
.await
.map_err(|e| format!("Failed to read shareable content: {e}"))?;
if !content.displays().is_empty() {
return Ok(cap_recording::SendableShareableContent::from(content));
}
let process_content = cidre::sc::ShareableContent::current_process()
.await
.map_err(|e| format!("Failed to read current-process shareable content: {e}"))?;
if !process_content.displays().is_empty() {
return Ok(cap_recording::SendableShareableContent::from(
process_content,
));
}
Ok(cap_recording::SendableShareableContent::from(content))
}
#[cfg(target_os = "macos")]
fn shareable_content_missing_target_display(
target: &ScreenCaptureTarget,
shareable_content: &cap_recording::SendableShareableContent,
) -> bool {
match target.display() {
Some(display) => display
.raw_handle()
.as_sc(shareable_content.retained())
.is_none(),
None => false,
}
}
#[cfg(target_os = "macos")]
fn shareable_content_display_ids(
shareable_content: &cap_recording::SendableShareableContent,
) -> Vec<String> {
shareable_content
.retained()
.displays()
.iter()
.map(|display| display.display_id().0.to_string())
.collect()
}
/// Wait for the stop trigger, then finalize the recording. A panic between start and stop would
/// otherwise drop the actor without writing recording-meta.json (`ActorHandle` has no `Drop`),
/// leaving an unrecoverable .cap; catch it and best-effort finalize so the recording is recoverable.
///
/// Studio recordings are fragmented while recording, so a graceful stop finalizes those fragments
/// before the `.cap` is returned.
async fn finalize(
actor: ActorHandle,
duration: Option<f64>,
interactive: bool,
stop_file: Option<&Path>,
) -> Result<CompletedRecording, String> {
let outcome = std::panic::AssertUnwindSafe(async {
finalize_after_stop_trigger(
actor.done_fut().map(|result| match result {
Err(error) if error.is_caused_by::<PipelineStoppedByUser>() => Ok(()),
result => result.map_err(|error| error.to_string()),
}),
wait_for_stop(duration, interactive, stop_file),
async { finalize_completed(actor.stop().await?).await },
)
.await
})
.catch_unwind()
.await;
match outcome {
Ok(result) => result,
Err(_) => {
let completed = actor
.stop()
.await
.map_err(|e| format!("recording panicked; finalize failed: {e}"))?;
finalize_completed(completed).await
}
}
}
async fn finalize_after_stop_trigger<T>(
capture_done: impl Future<Output = Result<(), String>>,
stop_requested: impl Future<Output = ()>,
finalize: impl Future<Output = Result<T, String>>,
) -> Result<T, String> {
let capture_result = tokio::select! {
biased;
result = capture_done => result,
_ = stop_requested => Ok(()),
};
let finalized = finalize.await;
capture_result?;
finalized
}
async fn finalize_completed(
mut completed: CompletedRecording,
) -> Result<CompletedRecording, String> {
match &mut completed {
CompletedRecording::Studio(recording) => {
let project_path = recording.project_path.clone();
tokio::task::spawn_blocking(move || {
cap_recording::recovery::RecoveryManager::remux_if_needed(&project_path)
})
.await
.map_err(|e| format!("recording finalize task failed: {e}"))?
.map_err(|e| format!("Failed to finalize recording: {e}"))?;
}
CompletedRecording::Instant(recording) => {
finalize_instant_output(recording).await?;
persist_instant_recording_meta(recording)?;
}
}
Ok(completed)
}
async fn finalize_instant_output(
recording: &mut instant_recording::CompletedRecording,
) -> Result<(), String> {
let completion = recording.clean_completion.take();
let project_path = recording.project_path.clone();
let output_path = project_path.join("content/output.mp4");
let audio_dir = project_path.join("content/audio");
if std::fs::metadata(&output_path)
.map(|metadata| metadata.len() > 0)
.unwrap_or(false)
&& !audio_dir.exists()
{
return Ok(());
}
let display_dir = project_path.join("content/display");
tokio::task::spawn_blocking(move || match completion {
Some(completion) => {
cap_recording::recovery::RecoveryManager::finalize_completed_instant_output(
&display_dir,
&audio_dir,
&output_path,
completion,
)
}
None => cap_recording::recovery::RecoveryManager::finalize_instant_output(
&display_dir,
&audio_dir,
&output_path,
),
})
.await
.map_err(|e| format!("instant recording finalize task failed: {e}"))?
.map_err(|e| format!("Failed to finalize instant recording: {e}"))?;
Ok(())
}
fn prepare_recording_project(
path: &Path,
mode: RecordMode,
required_audio: bool,
) -> Result<Option<UploadLock>, String> {
if let Some(parent) = path
.parent()
.filter(|parent| !parent.as_os_str().is_empty())
{
std::fs::create_dir_all(parent)
.map_err(|error| format!("Failed to create recording parent directory: {error}"))?;
}
std::fs::create_dir(path).map_err(|error| {
if error.kind() == std::io::ErrorKind::AlreadyExists {
"Recording project already exists; choose a fresh --path".to_string()
} else {
format!("Failed to reserve recording project directory: {error}")
}
})?;
if mode == RecordMode::Studio {
return Ok(None);
}
let upload_lock = UploadLock::acquire(path)
.map_err(|error| format!("Failed to reserve Instant recording ownership: {error}"))?;
let content = path.join("content");
std::fs::create_dir(&content)
.map_err(|error| format!("Failed to create recording content directory: {error}"))?;
if required_audio {
// Recovery treats this directory as required-audio intent, even before audio setup succeeds.
std::fs::create_dir(content.join("audio"))
.map_err(|error| format!("Failed to preserve recording audio requirement: {error}"))?;
}
RecordingMeta {
platform: Some(Platform::default()),
project_path: path.to_path_buf(),
pretty_name: path
.file_stem()
.and_then(|name| name.to_str())
.filter(|name| !name.is_empty())
.unwrap_or("Cap Recording")
.to_string(),
sharing: None,
inner: RecordingMetaInner::Instant(InstantRecordingMeta::InProgress { recording: true }),
upload: None,
}
.save_for_project()
.map_err(|error| format!("Failed to save initial instant recording meta: {error}"))?;
Ok(Some(upload_lock))
}
fn persist_instant_recording_meta(
recording: &instant_recording::CompletedRecording,
) -> Result<(), String> {
let pretty_name = recording
.project_path
.file_stem()
.and_then(|name| name.to_str())
.filter(|name| !name.is_empty())
.unwrap_or("Cap Recording")
.to_string();
let meta = match &recording.meta {
InstantRecordingMeta::Complete { .. } => recording.meta.clone(),
InstantRecordingMeta::InProgress { .. } => InstantRecordingMeta::Failed {
error: "instant recording stopped before completion".to_string(),
},
InstantRecordingMeta::Failed { .. } => recording.meta.clone(),
};
RecordingMeta {
platform: Some(Platform::default()),
project_path: recording.project_path.clone(),
pretty_name,
sharing: None,
inner: RecordingMetaInner::Instant(meta),
upload: None,
}
.save_for_project()
.map_err(|e| format!("Failed to save instant recording meta: {e}"))?;
ProjectConfiguration::default()
.write(&recording.project_path)
.map_err(|e| format!("Failed to save instant project config: {e}"))
}
fn emit_stopped(format: OutputFormat, completed: &CompletedRecording) -> Result<(), String> {
let recording_meta_exists = completed
.project_path()
.join("recording-meta.json")
.exists();
emit_record_event(
format,
&RecordEvent::Stopped {
path: &completed.project_path().display().to_string(),
recording_meta_exists,
},
)
}
fn new_recording_id() -> String {
Uuid::new_v4().simple().to_string()[..12].to_string()
}
fn resolve_path(params: &RecordParams, recording_id: &str) -> Result<PathBuf, String> {
match ¶ms.path {
Some(path) => Ok(path.clone()),
None => current_dir()
.map_err(|e| format!("Could not determine current directory: {e}"))
.map(|dir| dir.join(format!("{recording_id}.cap"))),
}
}
fn resolve_target(params: &RecordParams) -> Result<ScreenCaptureTarget, String> {
match (¶ms.target.screen, ¶ms.target.window) {
(Some(id), _) => cap_recording::screen_capture::list_displays()
.into_iter()
.find(|s| &s.0.id == id)
.map(|(s, _)| ScreenCaptureTarget::Display { id: s.id })
.ok_or_else(|| {
let available: Vec<String> = cap_recording::screen_capture::list_displays()
.into_iter()
.map(|(s, _)| s.id.to_string())
.collect();
format!(
"Screen with id '{id}' not found. Available screen ids: {available:?} \
(see `cap targets screens`)"
)
}),
(_, Some(id)) => cap_recording::screen_capture::list_windows()
.into_iter()
.find(|s| &s.0.id == id)
.map(|(s, _)| ScreenCaptureTarget::Window { id: s.id })
.ok_or_else(|| {
format!(
"Window with id '{id}' not found. Run `cap targets windows` to list window ids"
)
}),
_ => Err(
"No target specified; pass --screen <id> or --window <id> (see `cap targets`)"
.to_string(),
),
}
}
/// Block until the recording should stop: the duration elapses, the user presses Enter (interactive
/// only), the process receives SIGINT/SIGTERM, or a detached worker's stop file appears. Every branch
/// resolves so the caller can finalize the recording gracefully instead of being killed mid-write.
async fn wait_for_stop(duration: Option<f64>, interactive: bool, stop_file: Option<&Path>) {
#[cfg(unix)]
let mut term = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()).ok();
tokio::select! {
_ = async {
match duration {
Some(d) => tokio::time::sleep(Duration::from_secs_f64(d)).await,
None => std::future::pending::<()>().await,
}
} => {}
_ = async {
if duration.is_none() && interactive {
let _ = tokio::io::BufReader::new(tokio::io::stdin())
.read_line(&mut String::new())
.await;
} else {
std::future::pending::<()>().await;
}
} => {}
_ = tokio::signal::ctrl_c() => {}
_ = async {
#[cfg(unix)]
if let Some(term) = term.as_mut() {
term.recv().await;
return;
}
std::future::pending::<()>().await;
} => {}
_ = async {
match stop_file {
Some(path) => loop {
if session::stop_requested(path) {
return;
}
tokio::time::sleep(Duration::from_millis(150)).await;
},
None => std::future::pending::<()>().await,
}
} => {}
}
}
#[derive(Args, Clone)]
struct RecordTargets {
/// ID of the screen to capture
#[arg(long, group = "target")]
screen: Option<DisplayId>,
/// ID of the window to capture
#[arg(long, group = "target")]
window: Option<WindowId>,
}
// `rename_all` only renames the variant tags (started/stopped/error); `rename_all_fields` is what
// camelCases the fields inside each variant (recordingId, recordingMetaExists) — without it they leak
// as snake_case and break the camelCase contract the rest of the CLI and the docs promise.
#[derive(Serialize)]
#[serde(
tag = "type",
rename_all = "camelCase",
rename_all_fields = "camelCase"
)]
enum RecordEvent<'a> {
Started {
recording_id: &'a str,
pid: u32,
path: &'a str,
},
Stopped {
path: &'a str,
recording_meta_exists: bool,
},
Error {
error: &'a str,
},
}
fn emit_record_event(format: OutputFormat, event: &RecordEvent<'_>) -> Result<(), String> {
match format {
OutputFormat::Text => {
match event {
RecordEvent::Started {
recording_id,
pid,
path,
} => println!("Recording started: {path} (id {recording_id}, pid {pid})"),
RecordEvent::Stopped {
path,
recording_meta_exists,
} => {
println!("Recording stopped: {path}");
if !recording_meta_exists {
println!("warning: recording-meta.json was not written");
}
}
RecordEvent::Error { error } => println!("Recording error: {error}"),
}
Ok(())
}
OutputFormat::Json => write_json_line(event),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn instant_project_is_discoverable_before_capture_with_required_audio_intent() {
let root = tempfile::tempdir().unwrap();
for required_audio in [false, true] {
let project = root
.path()
.join("nested")
.join(format!("{required_audio}.cap"));
let _ownership =
prepare_recording_project(&project, RecordMode::Instant, required_audio).unwrap();
let meta = RecordingMeta::load_for_project(&project).unwrap();
assert!(matches!(
meta.inner,
RecordingMetaInner::Instant(InstantRecordingMeta::InProgress { recording: true })
));
assert_eq!(meta.project_path, project);
assert_eq!(meta.pretty_name, required_audio.to_string());
assert!(meta.platform.is_some());
assert!(meta.sharing.is_none());
assert!(meta.upload.is_none());
assert!(project.join("content").is_dir());
assert_eq!(project.join("content/audio").is_dir(), required_audio);
assert!(!project.join("content/output.mp4").exists());
assert!(!project.join("project-config.json").exists());
}
}
#[test]
fn recording_project_reservation_preserves_existing_recording_bytes_in_both_modes() {
let root = tempfile::tempdir().unwrap();
for mode in [RecordMode::Studio, RecordMode::Instant] {
let project = root.path().join(format!("{mode}.cap"));
let _ownership =
prepare_recording_project(&project, RecordMode::Instant, false).unwrap();
let mut meta = RecordingMeta::load_for_project(&project).unwrap();
meta.inner = RecordingMetaInner::Instant(InstantRecordingMeta::Complete {
fps: 30,
sample_rate: None,
});
meta.save_for_project().unwrap();
let original_meta = std::fs::read(project.join("recording-meta.json")).unwrap();
let output = project.join("content/output.mp4");
std::fs::write(&output, b"existing recording media").unwrap();
let error = prepare_recording_project(&project, mode, true)
.err()
.unwrap();
assert!(error.contains("choose a fresh --path"));
assert_eq!(
std::fs::read(project.join("recording-meta.json")).unwrap(),
original_meta
);
assert_eq!(std::fs::read(output).unwrap(), b"existing recording media");
assert!(!project.join("content/audio").exists());
}
}
#[test]
fn studio_project_is_reserved_before_engine_initialization() {
let root = tempfile::tempdir().unwrap();
let project = root.path().join("nested/recording.cap");
assert!(
prepare_recording_project(&project, RecordMode::Studio, true)
.unwrap()
.is_none()
);
assert!(project.is_dir());
assert_eq!(std::fs::read_dir(project).unwrap().count(), 0);
}
#[test]
fn recording_project_reservation_rejects_existing_empty_directory_and_file() {
let root = tempfile::tempdir().unwrap();
let directory = root.path().join("empty.cap");
std::fs::create_dir(&directory).unwrap();
for mode in [RecordMode::Studio, RecordMode::Instant] {
assert!(prepare_recording_project(&directory, mode, false).is_err());
assert!(prepare_recording_project(&directory.join("."), mode, false).is_err());
}
assert_eq!(std::fs::read_dir(&directory).unwrap().count(), 0);
let file = root.path().join("file.cap");
std::fs::write(&file, b"preserve this file").unwrap();
for mode in [RecordMode::Studio, RecordMode::Instant] {
assert!(prepare_recording_project(&file, mode, false).is_err());
}
assert_eq!(std::fs::read(file).unwrap(), b"preserve this file");
}
#[cfg(unix)]
#[test]
fn recording_project_reservation_rejects_live_and_dangling_symlinks() {
let root = tempfile::tempdir().unwrap();
for dangling in [false, true] {
let target = root.path().join(format!("target-{dangling}"));
if !dangling {
std::fs::create_dir(&target).unwrap();
std::fs::write(target.join("original"), b"original media").unwrap();
}
let project = root.path().join(format!("link-{dangling}.cap"));
std::os::unix::fs::symlink(&target, &project).unwrap();
for mode in [RecordMode::Studio, RecordMode::Instant] {
assert!(prepare_recording_project(&project, mode, true).is_err());
}
assert_eq!(std::fs::read_link(&project).unwrap(), target);
if dangling {
assert!(!target.exists());
} else {
assert_eq!(std::fs::read_dir(&target).unwrap().count(), 1);
assert_eq!(
std::fs::read(target.join("original")).unwrap(),
b"original media"
);
}
}
}
#[test]
fn concurrent_instant_project_reservations_have_one_owner() {
let root = tempfile::tempdir().unwrap();
let project = root.path().join("recording.cap");
let barrier = Arc::new(std::sync::Barrier::new(8));
let handles: Vec<_> = (0..8)
.map(|_| {
let project = project.clone();
let barrier = barrier.clone();
std::thread::spawn(move || {
barrier.wait();
prepare_recording_project(&project, RecordMode::Instant, true)
})
})
.collect();
let successful = handles
.into_iter()
.map(|handle| handle.join().unwrap())
.filter(Result::is_ok)
.count();
assert_eq!(successful, 1);
assert!(project.join("content/audio").is_dir());
let meta = RecordingMeta::load_for_project(&project).unwrap();
assert!(matches!(
meta.inner,
RecordingMetaInner::Instant(InstantRecordingMeta::InProgress { recording: true })
));
}
#[test]
fn incomplete_instant_project_never_validates_as_stopped_with_existing_output() {
let root = tempfile::tempdir().unwrap();
let project = root.path().join("recording.cap");
let _ownership = prepare_recording_project(&project, RecordMode::Instant, false).unwrap();
std::fs::write(project.join("content/output.mp4"), b"unvalidated media").unwrap();
let mut meta = RecordingMeta::load_for_project(&project).unwrap();
for state in [
InstantRecordingMeta::InProgress { recording: true },
InstantRecordingMeta::InProgress { recording: false },
InstantRecordingMeta::Failed {
error: "capture failed".to_string(),
},
] {
meta.inner = RecordingMetaInner::Instant(state);
meta.save_for_project().unwrap();
assert!(crate::project::validate_project(&project).is_err());
}
}
#[test]
fn live_instant_project_excludes_repair_until_ownership_is_released() {
let root = tempfile::tempdir().unwrap();
let project = root.path().join("recording.cap");
let ownership = prepare_recording_project(&project, RecordMode::Instant, false)
.unwrap()
.unwrap();
assert!(RecordingMeta::load_for_project(&project).is_ok());
assert!(matches!(
UploadLock::acquire(&project),
Err(cap_recording::upload_resume::UploadLockError::Busy)
));
drop(ownership);
let recovered = UploadLock::acquire(&project).unwrap();
assert_eq!(recovered.project_path(), project.canonicalize().unwrap());
}
#[tokio::test]
async fn capture_failure_finalizes_without_waiting_for_stop_request() {
let finalized = std::cell::Cell::new(false);
let result = finalize_after_stop_trigger(
std::future::ready(Err("capture window disappeared".to_string())),
std::future::pending(),
async {
finalized.set(true);
Err::<(), _>("display".to_string())
},
)
.await;
assert!(finalized.get());
assert_eq!(result.unwrap_err(), "capture window disappeared");
}
#[tokio::test]
async fn stop_request_finalizes_while_capture_is_running() {
let result = finalize_after_stop_trigger(
std::future::pending(),
std::future::ready(()),
std::future::ready(Ok(42)),
)
.await;
assert_eq!(result.unwrap(), 42);
}
#[tokio::test]
async fn completed_capture_finalizes_without_stop_request() {
let result = finalize_after_stop_trigger(
std::future::ready(Ok(())),
std::future::pending(),
std::future::ready(Ok(42)),
)
.await;
assert_eq!(result.unwrap(), 42);
}
#[tokio::test]
async fn finalization_error_is_returned_after_stop_request() {
let result = finalize_after_stop_trigger(
std::future::pending(),
std::future::ready(()),
std::future::ready(Err::<(), _>("failed to finalize recording".to_string())),
)
.await;
assert_eq!(result.unwrap_err(), "failed to finalize recording");
}
#[test]
fn record_event_fields_are_camel_case() {
let started = serde_json::to_value(RecordEvent::Started {
recording_id: "abc",
pid: 1,
path: "p",
})
.unwrap();
assert_eq!(started["type"], "started");
assert_eq!(started["recordingId"], "abc");
assert!(started.get("recording_id").is_none());
let stopped = serde_json::to_value(RecordEvent::Stopped {
path: "p",
recording_meta_exists: true,
})
.unwrap();
assert_eq!(stopped["type"], "stopped");
assert_eq!(stopped["recordingMetaExists"], true);
assert!(stopped.get("recording_meta_exists").is_none());
}
#[test]
fn dead_recording_session_reports_error_status() {
let row = session_status_row_with_alive(
Session {
recording_id: "abc".to_string(),
pid: 123,
path: PathBuf::from("recording.cap"),
status: SessionStatus::Recording,
started_at: Some(1),
recording_meta_exists: None,
error: None,
},
false,
);
assert!(matches!(row.status, SessionStatus::Error));
assert!(!row.alive);
assert_eq!(
row.error.as_deref(),
Some("recording process is not running")
);
}
}