Skip to content

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

fix: captions land above the video, not under it

Domica27c064f9abed
diff --git a/src/crates/concat-api/src/lib.rs b/src/crates/concat-api/src/lib.rs
index d09f58d3..eba1ed34 100644
--- a/src/crates/concat-api/src/lib.rs
+++ b/src/crates/concat-api/src/lib.rs
@@ -828,6 +828,7 @@ mod tests {
Request::EditApply {
path: "/p".to_owned(),
command: Box::new(Command::AddTextClip {
+ above: false,
track_id: None,
start: 1.5,
style: None,
@@ -978,6 +979,7 @@ mod tests {
ok(api.dispatch(Request::EditApply {
path: path.clone(),
command: Box::new(Command::AddTextClip {
+ above: false,
track_id: None,
start: 0.0,
style: None,
diff --git a/src/crates/concat-export/src/flatten.rs b/src/crates/concat-export/src/flatten.rs
index 323d8c45..c1bb3b5c 100644
--- a/src/crates/concat-export/src/flatten.rs
+++ b/src/crates/concat-export/src/flatten.rs
@@ -350,6 +350,7 @@ mod tests {
editor
.apply(Command::AddTextClip {
track_id,
+ above: false,
start: 0.0,
style: None,
duration: None,
diff --git a/src/crates/concat-host/src/titles.rs b/src/crates/concat-host/src/titles.rs
index f9bd0b31..27e55c2e 100644
--- a/src/crates/concat-host/src/titles.rs
+++ b/src/crates/concat-host/src/titles.rs
@@ -414,6 +414,7 @@ mod tests {
let mut editor = Editor::new();
let id = editor
.apply(Command::AddTextClip {
+ above: false,
track_id: None,
start: 2.0,
style: None,
diff --git a/src/crates/concat-host/tests/export.rs b/src/crates/concat-host/tests/export.rs
index 3aefa22f..570cd8d5 100644
--- a/src/crates/concat-host/tests/export.rs
+++ b/src/crates/concat-host/tests/export.rs
@@ -968,6 +968,7 @@ fn every_edit_still_exports() {
let exported = studio.export("layer");
exported.expect_length(end);
studio.apply(Command::AddTextClip {
+ above: false,
track_id: None,
start: 3.0,
style: Some(TextStyle {
diff --git a/src/crates/concat-project/src/animation.rs b/src/crates/concat-project/src/animation.rs
index 32fb8232..727309a3 100644
--- a/src/crates/concat-project/src/animation.rs
+++ b/src/crates/concat-project/src/animation.rs
@@ -305,6 +305,7 @@ mod tests {
let mut editor = Editor::new();
let id = editor
.apply(Command::AddTextClip {
+ above: false,
track_id: None,
start: 0.0,
style: None,
diff --git a/src/crates/concat-project/src/commands/clips.rs b/src/crates/concat-project/src/commands/clips.rs
index 4a062546..2bead257 100644
--- a/src/crates/concat-project/src/commands/clips.rs
+++ b/src/crates/concat-project/src/commands/clips.rs
@@ -66,6 +66,7 @@ pub(super) fn apply(
style,
duration,
offset_y,
+ above,
} => {
let style = style.unwrap_or_default();
let duration = duration
@@ -75,6 +76,21 @@ pub(super) fn apply(
let track_id = match track_id {
Some(id) if timeline.track(&id).is_some() => id,
Some(_) => return Err(CommandError::TrackGone),
+ None if above => match first_free_track_above(timeline, start, duration) {
+ Some(id) => id,
+ None => {
+ // Every lane above the video is taken: mint one at
+ // the top for the caption to land on.
+ let id = mint.next("t");
+ timeline.tracks.push(Track {
+ id: id.clone(),
+ visible: true,
+ muted: false,
+ extra: Default::default(),
+ });
+ id
+ }
+ },
None => {
first_free_track(timeline, start, duration).ok_or(CommandError::NoTracks)?
}
@@ -504,6 +520,36 @@ fn first_free_track(timeline: &Timeline, start: f64, duration: f64) -> Option<St
.map(|track| track.id.clone())
}
+/// First free lane *above* the highest one occupied over `[start, start +
+/// duration)`. `None` when every lane above is taken, which is the caller's
+/// cue to mint a new one at the top.
+///
+/// Captions go through this so they sit over the video, not under it. The
+/// plain `first_free_track` still walks from the bottom, which is what a
+/// title added by hand wants.
+fn first_free_track_above(timeline: &Timeline, start: f64, duration: f64) -> Option<String> {
+ let end = start + duration;
+ let occupied = |track_id: &str| {
+ timeline.clips.iter().any(|clip| {
+ clip.track_id == track_id && clip.start < end && start < clip.start + clip.duration
+ })
+ };
+ let floor = timeline
+ .tracks
+ .iter()
+ .enumerate()
+ .filter(|(_, track)| occupied(&track.id))
+ .map(|(row, _)| row + 1)
+ .max()
+ .unwrap_or(0);
+ timeline
+ .tracks
+ .iter()
+ .skip(floor)
+ .find(|track| !occupied(&track.id))
+ .map(|track| track.id.clone())
+}
+
/// Where each piece of a clip cut at `offset` begins in the source.
/// Forwards, the head keeps its in-point and the tail starts `offset ×
/// speed` later. Backwards, the head shows the late end of the span, so
diff --git a/src/crates/concat-project/src/commands/mod.rs b/src/crates/concat-project/src/commands/mod.rs
index 9d852bff..878574bb 100644
--- a/src/crates/concat-project/src/commands/mod.rs
+++ b/src/crates/concat-project/src/commands/mod.rs
@@ -286,6 +286,14 @@ pub enum Command {
/// The lane to place it on. None picks the first free track like
/// [`Command::AddClipAtFirstFree`]; naming a vanished track errs.
track_id: Option<String>,
+ /// When `track_id` is None and this is true, the clip lands on the
+ /// first free lane *above* the highest one occupied over its span,
+ /// minting a new lane at the top when every one above is taken. Set
+ /// by the caption run so captions sit over the video rather than
+ /// under it; a plain title leaves it false and keeps the old
+ /// bottom-first behaviour. Ignored when `track_id` names a track.
+ #[serde(default)]
+ above: bool,
/// Timeline position in seconds, floored at 0.
start: f64,
/// The words and their look. None means [`TextStyle::default`].
diff --git a/src/crates/concat-project/src/lib.rs b/src/crates/concat-project/src/lib.rs
index 2e58cf08..16862d78 100644
--- a/src/crates/concat-project/src/lib.rs
+++ b/src/crates/concat-project/src/lib.rs
@@ -1827,6 +1827,7 @@ mod tests {
let mut editor = Editor::new();
let clip_id = editor
.apply(Command::AddTextClip {
+ above: false,
track_id: None,
start: 2.0,
style: Some(TextStyle {
@@ -1865,6 +1866,190 @@ mod tests {
assert_eq!(restored.project(), editor.project());
}
+ #[test]
+ fn a_caption_lands_above_the_highest_occupied_lane() {
+ let mut editor = Editor::new();
+ let media_id = editor
+ .apply(media("/a.mp4", 10.0, true))
+ .expect("adds")
+ .created_id
+ .expect("id");
+ let video_track = editor.project().active().tracks[2].id.clone();
+ editor
+ .apply(Command::AddClip {
+ media_id,
+ track_id: video_track.clone(),
+ start: 0.0,
+ })
+ .expect("adds");
+
+ let caption_id = editor
+ .apply(Command::AddTextClip {
+ track_id: None,
+ above: true,
+ start: 0.0,
+ style: Some(TextStyle {
+ content: "hi".to_owned(),
+ ..TextStyle::default()
+ }),
+ duration: Some(5.0),
+ offset_y: None,
+ })
+ .expect("adds")
+ .created_id
+ .expect("id");
+
+ let caption = editor.project().active().clip(&caption_id).expect("exists");
+ let tracks = &editor.project().active().tracks;
+ let caption_row = tracks
+ .iter()
+ .position(|t| t.id == caption.track_id)
+ .expect("row");
+ let video_row = tracks
+ .iter()
+ .position(|t| t.id == video_track)
+ .expect("row");
+ assert!(
+ caption_row > video_row,
+ "a caption must land above the video, not under it"
+ );
+ }
+
+ #[test]
+ fn a_caption_on_an_empty_timeline_lands_on_the_bottom_lane() {
+ let mut editor = Editor::new();
+ let caption_id = editor
+ .apply(Command::AddTextClip {
+ track_id: None,
+ above: true,
+ start: 0.0,
+ style: Some(TextStyle {
+ content: "hi".to_owned(),
+ ..TextStyle::default()
+ }),
+ duration: Some(5.0),
+ offset_y: None,
+ })
+ .expect("adds")
+ .created_id
+ .expect("id");
+
+ let caption = editor.project().active().clip(&caption_id).expect("exists");
+ let tracks = &editor.project().active().tracks;
+ let caption_row = tracks
+ .iter()
+ .position(|t| t.id == caption.track_id)
+ .expect("row");
+ assert_eq!(
+ caption_row, 0,
+ "with nothing occupied, the caption takes the bottom lane"
+ );
+ }
+
+ #[test]
+ fn a_plain_title_still_lands_on_the_first_free_lane_from_the_bottom() {
+ let mut editor = Editor::new();
+ let media_id = editor
+ .apply(media("/a.mp4", 10.0, true))
+ .expect("adds")
+ .created_id
+ .expect("id");
+ let video_track = editor.project().active().tracks[2].id.clone();
+ editor
+ .apply(Command::AddClip {
+ media_id,
+ track_id: video_track,
+ start: 0.0,
+ })
+ .expect("adds");
+
+ let title_id = editor
+ .apply(Command::AddTextClip {
+ track_id: None,
+ above: false,
+ start: 0.0,
+ style: Some(TextStyle {
+ content: "title".to_owned(),
+ ..TextStyle::default()
+ }),
+ duration: Some(5.0),
+ offset_y: None,
+ })
+ .expect("adds")
+ .created_id
+ .expect("id");
+
+ let title = editor.project().active().clip(&title_id).expect("exists");
+ let tracks = &editor.project().active().tracks;
+ let title_row = tracks
+ .iter()
+ .position(|t| t.id == title.track_id)
+ .expect("row");
+ assert_eq!(
+ title_row, 0,
+ "a plain title keeps the old bottom-first behaviour"
+ );
+ }
+
+ #[test]
+ fn a_caption_mints_a_new_lane_when_every_lane_above_is_taken() {
+ let mut editor = Editor::new();
+ let media_id = editor
+ .apply(media("/a.mp4", 10.0, true))
+ .expect("adds")
+ .created_id
+ .expect("id");
+ let track_ids: Vec<String> = editor
+ .project()
+ .active()
+ .tracks
+ .iter()
+ .map(|t| t.id.clone())
+ .collect();
+ for track_id in &track_ids {
+ editor
+ .apply(Command::AddClip {
+ media_id: media_id.clone(),
+ track_id: track_id.clone(),
+ start: 0.0,
+ })
+ .expect("adds");
+ }
+
+ let caption_id = editor
+ .apply(Command::AddTextClip {
+ track_id: None,
+ above: true,
+ start: 0.0,
+ style: Some(TextStyle {
+ content: "hi".to_owned(),
+ ..TextStyle::default()
+ }),
+ duration: Some(5.0),
+ offset_y: None,
+ })
+ .expect("adds")
+ .created_id
+ .expect("id");
+
+ let caption = editor.project().active().clip(&caption_id).expect("exists");
+ let tracks = &editor.project().active().tracks;
+ assert_eq!(
+ tracks.len(),
+ track_ids.len() + 1,
+ "one lane was minted at the top for the caption"
+ );
+ let caption_row = tracks
+ .iter()
+ .position(|t| t.id == caption.track_id)
+ .expect("row");
+ assert_eq!(
+ caption_row,
+ track_ids.len(),
+ "the caption sits on the newly minted top lane"
+ );
+ }
+
#[test]
fn a_tolerated_no_op_records_no_undo_entry() {
// The applied flag replaced a deep state compare; if a missing-id
@@ -2386,6 +2571,7 @@ mod tests {
let clip_id = editor
.apply(Command::AddTextClip {
+ above: false,
track_id: None,
start: 0.0,
style: Some(TextStyle {
@@ -2455,6 +2641,7 @@ mod tests {
start: 2.0,
},
Command::AddTextClip {
+ above: false,
track_id: Some("T1".to_owned()),
start: 0.0,
style: Some(TextStyle::default()),
diff --git a/src/crates/concat/src/panes/captions.rs b/src/crates/concat/src/panes/captions.rs
index 8e6c8c0c..a571bb9f 100644
--- a/src/crates/concat/src/panes/captions.rs
+++ b/src/crates/concat/src/panes/captions.rs
@@ -276,6 +276,7 @@ fn caption_clip(text: String, start: f64, duration: f64, look: (f64, f64)) -> Co
let (offset_y, font_size) = look;
Command::AddTextClip {
track_id: None,
+ above: true,
start,
style: Some(TextStyle {
content: text,
diff --git a/src/crates/concat/src/studio.rs b/src/crates/concat/src/studio.rs
index 36c57563..b9fbe89c 100644
--- a/src/crates/concat/src/studio.rs
+++ b/src/crates/concat/src/studio.rs
@@ -2274,6 +2274,7 @@ impl Studio {
style: Some(style),
duration: Some(duration),
offset_y,
+ above: false,
};
match font {
Some((family, path)) => self.apply(Command::Batch {
@@ -4383,6 +4384,7 @@ impl Studio {
let end = source.start + source.duration;
if source.kind == model::ClipKind::Text {
let created = self.apply(Command::AddTextClip {
+ above: false,
track_id: Some(source.track_id.clone()),
start: end,
style: source.text.clone(),