Skip to content

The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.

Add CapCut-style freeze frame at the playhead.

ActArteche4781f7feb2f
diff --git a/engine/crates/concat-project/src/commands.rs b/engine/crates/concat-project/src/commands.rs
index 03b7b771..e849b4fa 100644
--- a/engine/crates/concat-project/src/commands.rs
+++ b/engine/crates/concat-project/src/commands.rs
@@ -26,6 +26,8 @@ const DEFAULT_TEXT_DURATION: f64 = 4.0;
/// How long a layer covers when first placed. Editorial default, not a fact.
const DEFAULT_LAYER_DURATION: f64 = 5.0;
const MIN_CLIP_DURATION: f64 = 1.0 / 60.0;
+/// Default hold for a CapCut-style freeze when the caller omits duration.
+const DEFAULT_FREEZE_DURATION: f64 = 1.0;
/// The engine's speed range (concat-media `SPEED_RANGE`), verbatim.
const MIN_SPEED: f64 = 0.0625;
const MAX_SPEED: f64 = 16.0;
@@ -386,6 +388,25 @@ pub enum Command {
/// The cut point, in timeline seconds.
time: f64,
},
+ /// CapCut-style freeze at `time`: splits `clip_id`, inserts a still of
+ /// `duration` on the same track, and ripples later clips on that track
+ /// by `duration`. Video needs a probed `still` (host-extracted jpg);
+ /// image clips may omit it and reuse their media. Audio and text are
+ /// no-ops. `created_id` is the freeze clip.
+ FreezeFrame {
+ /// The picture clip under the playhead.
+ clip_id: String,
+ /// Timeline playhead; must fall strictly inside the clip.
+ time: f64,
+ /// Editorial length of the hold. Floored at [`MIN_CLIP_DURATION`];
+ /// when absent or non-positive, uses [`DEFAULT_FREEZE_DURATION`].
+ #[serde(default)]
+ duration: Option<f64>,
+ /// Probed still file. Required for video; ignored for image when
+ /// reusing the existing media.
+ #[serde(default)]
+ still: Option<NewMedia>,
+ },
/// Rejoins split pieces into the earliest piece, which keeps its id.
/// Errs with a user-facing sentence ([`why_not_merge`]) unless the
/// pieces sit on one track, come from one file at one speed, touch
@@ -1211,6 +1232,125 @@ pub fn apply(
})
}
+ Command::FreezeFrame {
+ clip_id,
+ time,
+ duration,
+ still,
+ } => {
+ let hold = duration
+ .filter(|value| *value > 0.0)
+ .unwrap_or(DEFAULT_FREEZE_DURATION)
+ .max(MIN_CLIP_DURATION);
+
+ let (kind, media_id, track_id, start, clip_duration, speed, source_start, picture) = {
+ let timeline = project.active();
+ let Some(clip) = timeline.clip(&clip_id) else {
+ return Ok(Outcome::default());
+ };
+ if clip.kind != ClipKind::Video && clip.kind != ClipKind::Image {
+ return Ok(Outcome::default());
+ }
+ let offset = time - clip.start;
+ if offset <= MIN_CLIP_DURATION || offset >= clip.duration - MIN_CLIP_DURATION {
+ return Ok(Outcome::default());
+ }
+ (
+ clip.kind,
+ clip.media_id.clone(),
+ clip.track_id.clone(),
+ clip.start,
+ clip.duration,
+ clip.speed,
+ clip.source_start,
+ clip.clone(),
+ )
+ };
+
+ let freeze_media_id = if kind == ClipKind::Image && still.is_none() {
+ media_id
+ } else {
+ let Some(item) = still else {
+ return Ok(Outcome::default());
+ };
+ if let Some(existing) = project.media.iter().find(|media| media.path == item.path)
+ {
+ existing.id.clone()
+ } else {
+ let id = mint.next("m");
+ project.media.push(MediaItem {
+ id: id.clone(),
+ path: item.path,
+ name: item.name,
+ duration: item.duration,
+ kind: MediaKind::Image,
+ width: item.width,
+ height: item.height,
+ frame_rate: item.frame_rate,
+ frame_rate_fraction: item.frame_rate_fraction,
+ video_codec: item.video_codec,
+ audio_codec: None,
+ has_audio: false,
+ placeholder: false,
+ });
+ id
+ }
+ };
+
+ let timeline = project.active_mut();
+ let Some(index) = timeline.clips.iter().position(|clip| clip.id == clip_id) else {
+ return Ok(Outcome::default());
+ };
+ let offset = time - start;
+ let mut tail = timeline.clips[index].clone();
+ tail.id = mint.next("c");
+ tail.start = time;
+ tail.duration = clip_duration - offset;
+ tail.source_start = source_start + offset * speed;
+ tail.transition_in = None;
+ timeline.clips[index].duration = offset;
+ timeline.clips.insert(index + 1, tail);
+
+ // Ripple every later placement on this track (including the new
+ // tail) so the freeze does not sit on top of the remainder.
+ for clip in &mut timeline.clips {
+ if clip.track_id == track_id && clip.start >= time {
+ clip.start += hold;
+ }
+ }
+
+ // The still is the source clip turned into a picture: cloning it
+ // first carries every look field - transform, effects, crop,
+ // flips, whatever the model grows - and then the hold's own
+ // facts overwrite the moving ones.
+ let freeze_id = mint.next("c");
+ let mut frozen = picture;
+ frozen.id = freeze_id.clone();
+ frozen.track_id = track_id;
+ frozen.kind = ClipKind::Image;
+ frozen.media_id = freeze_media_id;
+ frozen.start = time;
+ frozen.duration = hold;
+ frozen.source_start = 0.0;
+ frozen.speed = 1.0;
+ frozen.speed_curve = None;
+ frozen.reverse = false;
+ frozen.volume = 1.0;
+ frozen.fade_in = 0.0;
+ frozen.fade_out = 0.0;
+ frozen.filters = Vec::new();
+ frozen.muted = None;
+ frozen.detached_from = None;
+ frozen.transition_in = None;
+ frozen.text = None;
+ timeline.clips.push(frozen);
+
+ Ok(Outcome {
+ created_id: Some(freeze_id),
+ applied: true,
+ })
+ }
+
Command::MergeClips { clip_ids } => {
let timeline = project.active_mut();
if let Some(reason) = why_not_merge(timeline, &clip_ids) {
diff --git a/engine/crates/concat-project/src/lib.rs b/engine/crates/concat-project/src/lib.rs
index 0e2ab305..1fdaa98a 100644
--- a/engine/crates/concat-project/src/lib.rs
+++ b/engine/crates/concat-project/src/lib.rs
@@ -37,7 +37,7 @@ pub use model::Project;
mod tests {
use serde_json::json;
- use crate::commands::{ClipMove, ClipPatch, Command, TrackFlag, TrimEdge};
+ use crate::commands::{ClipMove, ClipPatch, Command, NewMedia, TrackFlag, TrimEdge};
use crate::doc::DocumentSettings;
use crate::editor::Editor;
use crate::model::{ClipKind, MediaKind, TextStyle};
@@ -106,6 +106,55 @@ mod tests {
assert_eq!(editor.project().media.len(), 1);
}
+ #[test]
+ fn freeze_frame_holds_a_second_and_ripples_the_tail() {
+ let (mut editor, media_id, clip_id) = fixture();
+ let still = NewMedia {
+ path: "/freeze.jpg".into(),
+ name: "freeze.jpg".into(),
+ duration: None,
+ kind: MediaKind::Image,
+ width: Some(1920),
+ height: Some(1080),
+ frame_rate: None,
+ frame_rate_fraction: None,
+ video_codec: None,
+ audio_codec: None,
+ has_audio: false,
+ };
+ let freeze_id = editor
+ .apply(Command::FreezeFrame {
+ clip_id: clip_id.clone(),
+ time: 4.0,
+ duration: Some(1.0),
+ still: Some(still),
+ })
+ .expect("freezes")
+ .created_id
+ .expect("freeze id");
+
+ let clips = &editor.project().active().clips;
+ assert_eq!(clips.len(), 3, "head + freeze + tail");
+ let freeze = clips.iter().find(|clip| clip.id == freeze_id).expect("freeze");
+ assert_eq!(freeze.kind, ClipKind::Image);
+ assert_eq!(freeze.start, 4.0);
+ assert_eq!(freeze.duration, 1.0);
+ let tail = clips
+ .iter()
+ .find(|clip| clip.id != clip_id && clip.id != freeze_id)
+ .expect("tail");
+ assert_eq!(tail.start, 5.0, "tail ripples by the hold");
+ assert_eq!(tail.source_start, 4.0);
+ assert!(
+ editor
+ .project()
+ .media
+ .iter()
+ .any(|item| item.id != media_id && item.path == "/freeze.jpg"),
+ "still is imported"
+ );
+ }
+
#[test]
fn split_produces_source_continuous_halves_and_merge_rejoins_them() {
let (mut editor, _, clip_id) = fixture();
diff --git a/engine/crates/concat/src/studio.rs b/engine/crates/concat/src/studio.rs
index b6bba355..43cca0f5 100644
--- a/engine/crates/concat/src/studio.rs
+++ b/engine/crates/concat/src/studio.rs
@@ -31,7 +31,7 @@ use concat_host::preview::FrameSpec;
use concat_host::{
AnalyseRequest, Cutouts, ProjectInfo, RegionRequest, Session, media, projects, templates,
};
-use concat_media::Peaks;
+use concat_media::{Peaks, jpeg};
use concat_project::commands::{ClipMove, ClipPatch, TrackFlag, TrimEdge};
use concat_project::model::{
self, AppliedFilter, Clip, Project, TextAlign, TextStyle, Timeline, Track, Transition,
@@ -3860,6 +3860,90 @@ impl Studio {
};
}
+ /// CapCut-style freeze at the playhead on a picture clip.
+ ///
+ /// Video extracts a JPEG still into the project cache; images reuse their
+ /// media. The engine command splits the clip, inserts the hold, and
+ /// ripples the rest of the lane.
+ pub fn freeze_at_playhead(&mut self) {
+ let at = f64::from(self.playhead);
+ let edge = f64::from(MIN_DURATION);
+ let target = self
+ .menu_target
+ .clone()
+ .or_else(|| self.sole_selection())
+ .and_then(|id| self.clip(&id).cloned())
+ .filter(|clip| {
+ (clip.kind == model::ClipKind::Video || clip.kind == model::ClipKind::Image)
+ && !self.locked(&clip.track_id)
+ && at > clip.start + edge
+ && at < clip.start + clip.duration - edge
+ });
+ let Some(clip) = target else {
+ self.notify("Park the playhead inside a picture clip to freeze", true);
+ return;
+ };
+
+ let still = if clip.kind == model::ClipKind::Video {
+ let Some(media) = self
+ .project()
+ .media
+ .iter()
+ .find(|item| item.id == clip.media_id)
+ else {
+ return;
+ };
+ let Some(session) = self.session.as_ref() else {
+ return;
+ };
+ let project_path = session.path().to_owned();
+ let source_time = clip.source_start + (at - clip.start) * clip.speed;
+ let frame = match media::still_at(&media.path, source_time, 1280) {
+ Ok(frame) => frame,
+ Err(error) => {
+ self.notify(&error, true);
+ return;
+ }
+ };
+ let bytes = match jpeg(&frame, 4) {
+ Ok(bytes) => bytes,
+ Err(error) => {
+ self.notify(&format!("{error}"), true);
+ return;
+ }
+ };
+ let key = format!(
+ "freeze-{}-{}.jpg",
+ clip.id,
+ (source_time * 1000.0).round() as i64
+ );
+ if let Err(error) = media::write_artwork(&project_path, &key, &bytes) {
+ self.notify(&error, true);
+ return;
+ }
+ let path = format!("{project_path}/cache/{key}");
+ match media::probe(&path) {
+ Ok(summary) => Some(summary.to_new_media()),
+ Err(error) => {
+ self.notify(&error, true);
+ return;
+ }
+ }
+ } else {
+ None
+ };
+
+ let created = self.apply(Command::FreezeFrame {
+ clip_id: clip.id,
+ time: at,
+ duration: Some(1.0),
+ still,
+ });
+ if let Some(id) = created {
+ self.selection = vec![id];
+ }
+ }
+
/// A copy of `source` laid after it. Three commands, because a clip's
/// in-point and length are set by trims, not by placement.
pub fn duplicate(&mut self, source: &Clip) {
@@ -5821,6 +5905,15 @@ impl Studio {
"S",
straddled && !locked,
),
+ action(
+ "freeze",
+ "Freeze frame".into(),
+ Glyph::Frame,
+ "F",
+ straddled
+ && !locked
+ && (clip.kind == model::ClipKind::Video || clip.kind == model::ClipKind::Image),
+ ),
rule(),
];
let audible = clip.kind != model::ClipKind::Image;
@@ -6197,6 +6290,7 @@ impl Studio {
self.selection = vec![id.to_owned()];
self.split_at(at, true);
}
+ "freeze" => self.freeze_at_playhead(),
"mute" => {
let volume = if clip.volume <= 0.0 { 1.0 } else { 0.0 };
self.apply(Command::UpdateClip {