Skip to content

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

fix(audio): a batch volume sets each clip's level, not a key at the playhead (#219)

Jareerf6e0e07edcc1
diff --git a/src/crates/concat/src/batch_volume.rs b/src/crates/concat/src/batch_volume.rs
index 225a29b1..ec5c2789 100644
--- a/src/crates/concat/src/batch_volume.rs
+++ b/src/crates/concat/src/batch_volume.rs
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: 2026 Jareer and Concat contributors
//! The audio-only batch exposed by the inspector, separate from title styling.
-use concat_project::model::{ClipKind, Project};
+use concat_project::model::{Clip, ClipKind, KeyProperty, Project};
/// A batch must consist entirely of sound sources. Mixed selections are not
/// silently reduced to a subset; locked lanes are left untouched.
@@ -42,10 +42,101 @@ pub fn targets(
}
}
+/// Sets one clip of a batch to `level` (a gain), the way CapCut's batch
+/// volume does: it is the clip's level that changes, not a key at the
+/// playhead. A clip with no keys on its volume takes the level as it is.
+/// A clip whose volume rides keeps its ride: every key moves by the same
+/// number of decibels - the knob's unit - so the gain at `at` lands on
+/// `level` and a fade keeps its shape, a key at silence staying silent.
+/// Where the ride is silent at `at`, its loudest key is what lands on
+/// `level`; a ride silent everywhere is lifted to it.
+///
+/// `original` is the clip as the document has it: each step of a drag is
+/// read against where the drag began, so the shape is never worn down.
+pub fn set_level(clip: &mut Clip, original: &Clip, level: f64, at: f64) {
+ let level = level.max(0.0);
+ if !original.is_keyed(KeyProperty::Volume) {
+ clip.volume = level;
+ return;
+ }
+ let loudest = original
+ .keys_on(KeyProperty::Volume)
+ .map(|key| key.value)
+ .fold(0.0_f64, f64::max);
+ let here = original.value_at(KeyProperty::Volume, at);
+ let from = if here > 1e-6 { here } else { loudest };
+ let values = original.keys_on(KeyProperty::Volume).map(|key| {
+ if from > 1e-6 {
+ key.value * level / from
+ } else {
+ level
+ }
+ });
+ let keys = clip
+ .keys
+ .iter_mut()
+ .filter(|key| key.property == KeyProperty::Volume);
+ for (key, value) in keys.zip(values) {
+ key.value = value.max(0.0);
+ }
+}
+
#[cfg(test)]
mod tests {
use super::*;
- use concat_project::model::Clip;
+ use concat_project::model::{ClipKey, KeyEase};
+
+ fn ride(values: &[(f64, f64)]) -> Clip {
+ let mut clip = Clip::blank("c", "T1", ClipKind::Audio, "clip", 0.0, 10.0);
+ clip.keys = values
+ .iter()
+ .map(|&(at, value)| ClipKey {
+ property: KeyProperty::Volume,
+ at,
+ value,
+ ease: KeyEase::LINEAR,
+ })
+ .collect();
+ clip
+ }
+
+ fn volumes(clip: &Clip) -> Vec<f64> {
+ clip.keys_on(KeyProperty::Volume)
+ .map(|key| key.value)
+ .collect()
+ }
+
+ #[test]
+ fn an_unkeyed_clip_takes_the_level_and_gains_no_key() {
+ let original = Clip::blank("c", "T1", ClipKind::Audio, "clip", 0.0, 10.0);
+ let mut clip = original.clone();
+ set_level(&mut clip, &original, 0.5, 0.3);
+ assert_eq!(clip.volume, 0.5);
+ assert!(clip.keys.is_empty());
+ }
+
+ #[test]
+ fn a_keyed_clip_moves_its_whole_ride_and_keeps_a_fade_to_silence() {
+ // Full, then a fade to silence; the playhead at the start.
+ let original = ride(&[(0.0, 1.0), (0.5, 1.0), (1.0, 0.0)]);
+ let mut clip = original.clone();
+ set_level(&mut clip, &original, 0.5, 0.0);
+ assert_eq!(volumes(&clip), vec![0.5, 0.5, 0.0]);
+ assert_eq!(clip.keys.len(), 3, "no key is added at the playhead");
+ // A drag's next step is read against the document, not the last
+ // step: the same answer, however many steps it took.
+ set_level(&mut clip, &original, 0.5, 0.0);
+ assert_eq!(volumes(&clip), vec![0.5, 0.5, 0.0]);
+ // At the silent end, the loudest key is what lands on the level.
+ let mut clip = original.clone();
+ set_level(&mut clip, &original, 2.0, 1.0);
+ assert_eq!(volumes(&clip), vec![2.0, 2.0, 0.0]);
+ // Silent everywhere: lifted to the level.
+ let silent = ride(&[(0.0, 0.0), (1.0, 0.0)]);
+ let mut clip = silent.clone();
+ set_level(&mut clip, &silent, 0.8, 0.5);
+ assert_eq!(volumes(&clip), vec![0.8, 0.8]);
+ }
fn project(kinds: &[ClipKind]) -> (Project, Vec<String>) {
let mut project = Project::new();
diff --git a/src/crates/concat/src/studio.rs b/src/crates/concat/src/studio.rs
index 0cb5a70f..aadf2ff7 100644
--- a/src/crates/concat/src/studio.rs
+++ b/src/crates/concat/src/studio.rs
@@ -4790,7 +4790,9 @@ impl Studio {
/// accumulated edits into commands.
pub fn clip_set(&mut self, field: ClipField, value: f32) {
let mut ids = self.edit_targets();
- if ids.is_empty() && field == ClipField::Volume {
+ // A batch of sounds takes the level alone; see `batch_volume`.
+ let batch_volume = ids.is_empty() && field == ClipField::Volume;
+ if batch_volume {
ids = self.volume_targets();
}
if ids.is_empty() {
@@ -4832,9 +4834,24 @@ impl Studio {
.unwrap_or(value),
_ => value,
};
+ // The clip as the document has it, for a batch level: a drag's
+ // every step is read against where it started, not against
+ // the last step, so a ride's shape is not worn down on the way.
+ let original = batch_volume
+ .then(|| {
+ self.session
+ .as_ref()
+ .and_then(|session| session.project().active().clip(&id))
+ .cloned()
+ })
+ .flatten();
let Some(clip) = self.echo_clip_mut(&id) else {
continue;
};
+ if let Some(original) = original {
+ crate::batch_volume::set_level(clip, &original, value, at);
+ continue;
+ }
let text = clip.text.get_or_insert_with(TextStyle::default);
match field {
ClipField::Scale => {
@@ -11757,4 +11774,93 @@ mod tests {
assert_eq!(place_in(&after, 2.5), 0.25);
assert_eq!(place_in(&after, 12.0), 1.0, "held to the end");
}
+
+ /// A batch level lands on every clip as the inspector commits it - one
+ /// batch of each clip's commands - and one undo takes all of it back:
+ /// the plain clip's level and the keyed clip's whole ride, with no key
+ /// left behind at the playhead.
+ #[test]
+ fn a_batch_level_is_one_undo_step_for_every_clip() {
+ use concat_project::model::{KeyEase, KeyProperty, MediaKind};
+ let mut editor = concat_project::Editor::new();
+ let media_id = editor
+ .apply(Command::AddMedia {
+ item: concat_project::commands::NewMedia {
+ path: "/a.wav".to_owned(),
+ name: "a.wav".to_owned(),
+ duration: Some(10.0),
+ kind: MediaKind::Audio,
+ width: None,
+ height: None,
+ frame_rate: None,
+ frame_rate_fraction: None,
+ video_codec: None,
+ audio_codec: Some("pcm".to_owned()),
+ has_audio: true,
+ audio_tracks: Vec::new(),
+ origin: None,
+ color_space: Default::default(),
+ },
+ })
+ .expect("adds")
+ .created_id
+ .expect("id");
+ let track_id = editor.project().active().tracks[0].id.clone();
+ let mut ids = Vec::new();
+ for start in [0.0, 20.0] {
+ let id = editor
+ .apply(Command::AddClip {
+ media_id: media_id.clone(),
+ track_id: track_id.clone(),
+ start,
+ ripple: false,
+ })
+ .expect("adds")
+ .created_id
+ .expect("id");
+ ids.push(id);
+ }
+ // The second rides: full, then faded out.
+ for (at, value) in [(0.0, 1.0), (1.0, 0.0)] {
+ editor
+ .apply(Command::SetClipKey {
+ clip_id: ids[1].clone(),
+ property: KeyProperty::Volume,
+ at,
+ value,
+ ease: KeyEase::LINEAR,
+ })
+ .expect("keys");
+ }
+ editor.end_gesture();
+ let document = editor.project().clone();
+
+ let mut commands = Vec::new();
+ for id in &ids {
+ let before = document.active().clip(id).expect("clip");
+ let mut after = before.clone();
+ crate::batch_volume::set_level(&mut after, before, 0.5, 0.0);
+ commands.extend(super::clip_commands(id, before, &after));
+ }
+ editor.apply(Command::Batch { commands }).expect("applies");
+ let clip = |editor: &concat_project::Editor, id: &str| {
+ editor.project().active().clip(id).expect("clip").clone()
+ };
+ assert_eq!(clip(&editor, &ids[0]).volume, 0.5);
+ let keyed = clip(&editor, &ids[1]);
+ let ride: Vec<f64> = keyed
+ .keys_on(KeyProperty::Volume)
+ .map(|key| key.value)
+ .collect();
+ assert_eq!(ride, vec![0.5, 0.0], "the ride moved, no key was added");
+
+ assert!(editor.undo());
+ for id in &ids {
+ assert_eq!(
+ clip(&editor, id),
+ *document.active().clip(id).expect("clip"),
+ "one undo puts {id} back"
+ );
+ }
+ }
}