f67d38b35cc5
timeline_volume.rs
//! The Volume line on audio clips (#223): the clip's Volume level over time, with its keyframes,
//! on the same scale as the track faders. As in Premiere, drag the line up or down to change the
//! level (with keyframes: the stretch between the two around the pointer), Cmd/Ctrl-click it or
//! click it with the Pen tool to add a keyframe, drag keyframes, right-click one to delete it.
//! Presses on the line go through the Timeline's own hit-testing ([`super::timeline_hit`]), so a
//! right-click on it still opens the clip menu.
//!
//! Automation ids: `timeline.clip.<id>.volume` (a point on the line),
//! `timeline.clip.<id>.volume.kf.<n>` (the keyframes) and `….kf.<n>.delete` (their menu).
use egui::{Color32, CursorIcon, Pos2, Rect, Sense, Stroke, pos2, vec2};
use filmcraft_project::mixer::{FADER_MAX_DB, FADER_MIN_DB};
use filmcraft_project::{ClipId, Param, Sequence, TrackItem, TrackKind};
use filmcraft_time::Tick;
use serde_json::{Value, json};
use super::mixer::{db_to_pos, pos_to_db};
use super::timeline::{Layout, Row};
use super::timeline_hit::EDGE_PX;
use crate::FilmcraftApp;
use crate::icons::{self, Icon};
use crate::state::Tool;
use crate::theme::Tokens;
const KEY_COL: Color32 = Color32::from_rgb(0xc8, 0xc8, 0xc8);
/// Where the line goes in a clip drawn at `body`: under the name, down to the bottom edge.
fn band(body: Rect) -> Rect {
Rect::from_min_max(pos2(body.min.x, body.min.y + 17.0), pos2(body.max.x, body.max.y - 3.0))
}
fn level(it: &TrackItem) -> Option<&Param> {
it.effect("volume")?.param("level")
}
/// The level (dB) the clip plays at timeline time `t`.
fn level_at(it: &TrackItem, t: Tick) -> f64 {
level(it).map_or(0.0, |p| p.f64_at(it.source_time_at(t)))
}
/// The clip's Volume as a gain at timeline time `t`, for its waveform (1 when Volume is off or
/// bypassed, as the mixer plays it).
pub fn gain_at(it: &TrackItem, t: Tick) -> f32 {
match it.effect("volume").filter(|e| e.enabled && !e.param("bypass").and_then(|p| p.value.as_bool()).unwrap_or(false)) {
Some(e) => filmcraft_render::audio::db_to_gain(e.f64_at("level", it.source_time_at(t))),
None => 1.0,
}
}
/// Timeline time of media time `m`, the inverse of [`TrackItem::moving_source_time_at`].
fn timeline_time(it: &TrackItem, m: Tick) -> Tick {
let rel = if it.reverse { it.source_out().0.saturating_sub(1).saturating_sub(m.0) } else { m.0.saturating_sub(it.source_in.0) };
Tick(it.start.0.saturating_add((rel as f64 / it.speed.abs().max(1e-6)).round() as i64))
}
fn x_of(it: &TrackItem, body: Rect, t: Tick) -> f32 {
body.min.x + (t.0.saturating_sub(it.start.0) as f64 / it.duration.0.max(1) as f64) as f32 * body.width()
}
fn t_at(it: &TrackItem, body: Rect, x: f32) -> Tick {
let f = ((x - body.min.x) / body.width().max(1.0)).clamp(0.0, 1.0) as f64;
Tick(it.start.0.saturating_add((f * it.duration.0 as f64) as i64))
}
fn y_of(body: Rect, db: f64) -> f32 {
let b = band(body);
b.max.y - db_to_pos(db) * b.height()
}
/// The line from `x0` to `x1`; keyframes bend it, so it then gets a point every 2 px.
fn line(it: &TrackItem, body: Rect, x0: f32, x1: f32) -> Vec<Pos2> {
let n = if level(it).is_some_and(Param::is_animated) { (((x1 - x0) / 2.0).ceil() as usize).clamp(1, 4096) } else { 1 };
(0..=n)
.map(|i| {
let x = x0 + (x1 - x0) * i as f32 / n as f32;
pos2(x, y_of(body, level_at(it, t_at(it, body, x))))
})
.collect()
}
/// The keyframes: media time and where each is drawn.
fn keys(it: &TrackItem, body: Rect) -> Vec<(Tick, Pos2)> {
let Some(p) = level(it) else { return Vec::new() };
p.keyframes.iter().map(|k| (k.time, pos2(x_of(it, body, timeline_time(it, k.time)), y_of(body, k.value.as_f64().unwrap_or(0.0))))).collect()
}
/// Draw the line over an audio clip drawn at `body`: white with a dark shadow.
pub fn paint(p: &egui::Painter, body: Rect, it: &TrackItem) {
let vis = p.clip_rect().intersect(body);
if band(body).height() < 6.0 || vis.width() <= 0.0 {
return;
}
let p = p.with_clip_rect(vis);
let pts = line(it, body, vis.min.x, vis.max.x);
p.add(egui::Shape::line(pts.iter().map(|q| *q + vec2(0.0, 1.0)).collect(), Stroke::new(1.0, Color32::BLACK)));
p.add(egui::Shape::line(pts, Stroke::new(1.0, Color32::WHITE)));
for (_, c) in keys(it, body).into_iter().filter(|(_, c)| vis.expand(6.0).contains(*c)) {
icons::paint(&p, Rect::from_center_size(c, vec2(9.0, 9.0)), Icon::Keyframe, KEY_COL);
}
}
/// A drag of a clip's Volume line, pressed at height `y` where the line was at `from` dB. `keys`
/// are the keyframes on either side of that point, which move with it (none: the level is not
/// animated). `last` is the level sent last: the first change starts the drag's undo step.
#[derive(Clone, Debug)]
pub struct LineDrag {
clip: ClipId,
from: f64,
y: f32,
keys: [Option<(Tick, f64)>; 2],
last: Option<f64>,
}
impl LineDrag {
/// Whether the drag has changed the volume yet (its first change began an undo step).
pub fn changed(&self) -> bool {
self.last.is_some()
}
}
fn find<'a>(seq: &'a Sequence, layout: &'a Layout, clip: ClipId) -> Option<(&'a Row, &'a TrackItem)> {
let (tid, it) = seq.find_item(clip)?;
Some((layout.rows.iter().find(|r| r.track == tid)?, it))
}
fn body(layout: &Layout, r: &Row, it: &TrackItem) -> Rect {
Rect::from_min_max(pos2(layout.x_of(it.start), r.rect.min.y + 1.0), pos2(layout.x_of(it.end()), r.rect.max.y - 1.0))
}
/// Whether `pos` is on `clip`'s Volume line, within 4 px.
pub fn on_line(seq: &Sequence, layout: &Layout, clip: ClipId, pos: Pos2) -> bool {
let Some((r, it)) = find(seq, layout, clip) else { return false };
if r.kind != TrackKind::Audio || r.lane || seq.track(r.track).is_none_or(|t| t.locked) {
return false;
}
let body = body(layout, r, it);
band(body).height() >= 6.0 && (pos.y - y_of(body, level_at(it, t_at(it, body, pos.x)))).abs() <= 4.0
}
/// A press on `clip`'s line at `at` that became a drag.
pub fn start(seq: &Sequence, layout: &Layout, clip: ClipId, at: Pos2) -> Option<LineDrag> {
let (r, it) = find(seq, layout, clip)?;
let t = t_at(it, body(layout, r, it), at.x);
let m = it.source_time_at(t);
let keys = level(it).filter(|p| p.is_animated()).map_or([None, None], |p| {
let i = p.keyframes.partition_point(|k| k.time <= m);
let kv = |j: Option<usize>| j.and_then(|j| p.keyframes.get(j)).map(|k| (k.time, k.value.as_f64().unwrap_or(0.0)));
[kv(i.checked_sub(1)), kv(Some(i))]
});
Some(LineDrag { clip, from: level_at(it, t), y: at.y, keys, last: None })
}
/// Follow the pointer, now at height `y`. The clip changes as the line moves, so it is heard.
pub fn drag(app: &mut FilmcraftApp, ui: &egui::Ui, seq: &Sequence, layout: &Layout, mut d: LineDrag, y: f32) -> LineDrag {
let Some((r, it)) = find(seq, layout, d.clip) else { return d };
let db = pos_to_db(db_to_pos(d.from) + (d.y - y) / band(body(layout, r, it)).height().max(1.0));
tip(ui, db);
if d.last == Some(db) {
return d;
}
let begin = d.last.is_none();
let mut acts = Vec::new();
if d.keys.iter().all(Option::is_none) {
acts.push(("effects.setParam", json!({"clip": d.clip.0, "effect": "volume", "param": "level", "value": db, "merge": true, "begin": begin})));
}
for (n, (m, v)) in d.keys.iter().flatten().enumerate() {
let v = (v + db - d.from).clamp(FADER_MIN_DB, FADER_MAX_DB);
let p = json!({"clip": d.clip.0, "effect": "volume", "param": "level", "mediaTime": m.0, "value": v, "merge": true, "begin": begin && n == 0});
acts.push(("effects.setKeyframe", p));
}
run(app, acts);
d.last = Some(db);
d
}
/// The Pen tool or a Cmd/Ctrl-click on `clip`'s line at `x`: a keyframe there.
pub fn add_keyframe(app: &mut FilmcraftApp, seq: &Sequence, layout: &Layout, clip: ClipId, x: f32) {
let Some((r, it)) = find(seq, layout, clip) else { return };
let t = seq.settings.frame_rate.snap_nearest(t_at(it, body(layout, r, it), x));
run(app, vec![("effects.addKeyframe", json!({"clip": clip.0, "effect": "volume", "param": "level", "time": t.0}))]);
}
fn run(app: &mut FilmcraftApp, acts: Vec<(&str, Value)>) {
for (id, p) in acts {
if let Err(e) = app.session.execute(id, p) {
app.ui.status = e.to_string();
}
}
}
/// The level next to the pointer while dragging: one line, always as wide, so it does not jump.
fn tip(ui: &egui::Ui, db: f64) {
let text = if db <= FADER_MIN_DB { format!("{:>7} dB", "-∞") } else { format!("{db:>+7.2} dB") };
egui::Tooltip::always_open(ui.ctx().clone(), ui.layer_id(), egui::Id::unique("tl-volume-tip"), egui::PopupAnchor::Pointer).show(|ui| {
ui.add(egui::Label::new(egui::RichText::new(text).font(Tokens::mono(12.0))).wrap_mode(egui::TextWrapMode::Extend));
});
}
/// A keyframe being dragged: `index` of `clip`, grabbed `grab` away from its centre.
#[derive(Clone, Copy)]
struct KeyDrag {
clip: ClipId,
index: usize,
grab: egui::Vec2,
begun: bool,
}
/// Single stable id for the in-flight audio keyframe drag; interaction runs above the clips.
fn key_drag_id() -> egui::Id {
egui::Id::unique("tl-volume-key-drag")
}
/// The keyframes on the lines of the audio clips in view: drag one in time and level, right-click
/// it to delete it. Runs after the timeline's own interaction, so they are above the clip.
pub fn interact(app: &mut FilmcraftApp, ui: &mut egui::Ui, seq: &Sequence, layout: &Layout, aclip: Rect) {
let held: Option<KeyDrag> = ui.data(|d| d.get_temp(key_drag_id()));
if held.is_some() && ui.input(|i| i.key_pressed(egui::Key::Escape)) {
if let Some(h) = held
&& h.begun
{
let _ = app.session.execute("edit.undo", json!({}));
}
ui.data_mut(|d| d.remove::<KeyDrag>(key_drag_id()));
return;
}
if held.is_none() && (app.tl.drag.is_some() || !matches!(app.ui.tool, Tool::Selection | Tool::Pen)) {
return;
}
let area = aclip.intersect(layout.content);
let pointer = ui.input(|i| i.pointer.interact_pos());
let rate = seq.settings.frame_rate;
let mut next = held;
let mut acts: Vec<(&str, Value)> = Vec::new();
for r in layout.rows.iter().filter(|r| r.kind == TrackKind::Audio && !r.lane) {
let Some(tr) = seq.track(r.track).filter(|t| !t.locked) else { continue };
let row = r.rect.intersect(area);
if row.height() <= 0.0 {
continue;
}
for it in &tr.items {
let body = body(layout, r, it);
let vis = body.intersect(row);
if vis.width() <= 0.0 || band(body).height() < 6.0 {
continue;
}
// a point on the line for agents, away from the trim zones at the edges
let edge = EDGE_PX.min(body.width() / 3.0);
let (x0, x1) = (vis.min.x.max(body.min.x + edge), vis.max.x.min(body.max.x - edge));
if x1 > x0 {
let xm = (x0 + x1) / 2.0;
let c = pos2(xm, y_of(body, level_at(it, t_at(it, body, xm))));
app.auto.add(&format!("timeline.clip.{}.volume", it.id.0), Rect::from_center_size(c, vec2(12.0, 8.0)), "Volume");
}
let ks = keys(it, body);
for (i, &(time, c)) in ks.iter().enumerate() {
if !vis.expand2(vec2(5.0, 0.0)).contains(c) {
continue;
}
let kr = Rect::from_center_size(c, vec2(11.0, 11.0));
let resp = ui.interact(kr, egui::Id::unique(("tl-volume-kf", it.id.0, i)), Sense::click_and_drag());
app.auto.add(&format!("timeline.clip.{}.volume.kf.{i}", it.id.0), kr, "Volume keyframe");
let mine = held.filter(|h| h.clip == it.id && h.index == i);
if resp.hovered() || mine.is_some() {
icons::paint(&ui.painter().with_clip_rect(area), Rect::from_center_size(c, vec2(9.0, 9.0)), Icon::Keyframe, Color32::WHITE);
ui.ctx().set_cursor_icon(CursorIcon::Move);
}
if resp.drag_started_by(egui::PointerButton::Primary)
&& let Some(p) = pointer
{
next = Some(KeyDrag { clip: it.id, index: i, grab: p - c, begun: false });
}
if let (Some(h), Some(p)) = (mine, pointer)
&& resp.dragged()
{
let q = p - h.grab;
// on a frame, at least a frame away from the keyframes on either side
let fd = rate.frame_duration();
let now = timeline_time(it, time);
let (mut lo, mut hi) = (it.start, Tick(it.end().0.saturating_sub(fd.0)));
for j in [i.checked_sub(1), i.checked_add(1)].into_iter().flatten() {
if let Some(&(m, _)) = ks.get(j) {
let n = timeline_time(it, m);
if n < now {
lo = lo.max(Tick(n.0.saturating_add(fd.0)));
} else {
hi = hi.min(Tick(n.0.saturating_sub(fd.0)));
}
}
}
let t = if lo <= hi { rate.snap_nearest(t_at(it, body, q.x)).max(lo).min(hi) } else { now };
let db = pos_to_db((band(body).max.y - q.y) / band(body).height());
if resp.drag_delta() != egui::Vec2::ZERO {
let to = it.moving_source_time_at(t);
let p = json!({"clip": h.clip.0, "effect": "volume", "param": "level", "mediaTime": time.0, "to": to.0, "value": db, "merge": true, "begin": !h.begun});
acts.push(("effects.moveKeyframe", p));
next = Some(KeyDrag { begun: true, ..h });
}
tip(ui, db);
}
resp.context_menu(|ui| {
let b = ui.button(tl!("Delete"));
app.auto.add(&format!("timeline.clip.{}.volume.kf.{i}.delete", it.id.0), b.rect, "Delete");
if b.clicked() {
acts.push(("effects.deleteKeyframe", json!({"clip": it.id.0, "effect": "volume", "param": "level", "mediaTime": time.0})));
ui.close();
}
});
}
}
}
if !ui.input(|i| i.pointer.any_down()) {
next = None;
}
match next {
Some(h) => ui.data_mut(|d| {
d.insert_temp(key_drag_id(), h);
}),
None => ui.data_mut(|d| d.remove::<KeyDrag>(key_drag_id())),
}
run(app, acts);
}
#[cfg(test)]
mod tests {
use super::*;
use filmcraft_project::{ItemId, Label};
fn clip(speed: f64, reverse: bool) -> TrackItem {
TrackItem {
custom_label_color: None,
id: ClipId(1),
item: ItemId(1),
name: String::new(),
label: Label::Iris,
start: Tick(1_000),
duration: Tick(4_000),
source_in: Tick(500),
speed,
reverse,
enabled: true,
link: None,
group: None,
effects: filmcraft_project::effect::intrinsic_audio(),
markers: Vec::new(),
gain_db: 0.0,
frame_hold: None,
scale_to_frame: false,
essential: None,
multicam: None,
time_interpolation: Default::default(),
maintain_pitch: false,
hold_filters: false,
field_options: None,
source_channels: Vec::new(),
audio_stream: 0,
graphic: None,
}
}
#[test]
fn keyframes_sit_where_their_media_time_plays() {
for (speed, reverse) in [(1.0, false), (2.0, false), (0.5, false), (1.0, true), (2.0, true)] {
let it = clip(speed, reverse);
for t in [1_000, 1_001, 2_500, 4_999] {
let m = it.moving_source_time_at(Tick(t));
assert!((timeline_time(&it, m).0 - t).abs() <= 1, "speed {speed} reverse {reverse}: {t}");
}
}
}
#[test]
fn damaged_keyframe_times_do_not_panic() {
for (speed, reverse) in [(1.0, false), (1e-12, true), (f64::NAN, false), (-3.0, true)] {
let mut it = clip(speed, reverse);
let p = it.effect_mut("volume").and_then(|e| e.param_mut("level")).unwrap();
p.put_keyframe(Tick(i64::MIN), filmcraft_project::ParamValue::Float(f64::NAN));
p.put_keyframe(Tick(i64::MAX), filmcraft_project::ParamValue::Float(1e300));
let body = Rect::from_min_max(pos2(0.0, 0.0), pos2(400.0, 80.0));
assert_eq!(keys(&it, body).len(), 2);
}
}
#[test]
fn the_waveform_gain_is_the_volume_that_plays() {
let mut it = clip(1.0, false);
assert_eq!(gain_at(&it, Tick(2_000)), 1.0);
let e = it.effect_mut("volume").unwrap();
e.param_mut("level").unwrap().value = filmcraft_project::ParamValue::Float(-6.0);
assert!((gain_at(&it, Tick(2_000)) - 0.501).abs() < 0.01);
let e = it.effect_mut("volume").unwrap();
e.param_mut("bypass").unwrap().value = filmcraft_project::ParamValue::Bool(true);
assert_eq!(gain_at(&it, Tick(2_000)), 1.0, "bypassed");
}
#[test]
fn the_line_follows_the_level() {
let mut it = clip(1.0, false);
let body = Rect::from_min_max(pos2(0.0, 0.0), pos2(400.0, 80.0));
let flat = line(&it, body, 0.0, 400.0);
assert_eq!(flat.len(), 2);
assert!(flat.iter().all(|p| (p.y - y_of(body, 0.0)).abs() < 1e-3));
let p = it.effect_mut("volume").and_then(|e| e.param_mut("level")).unwrap();
p.put_keyframe(Tick(500), filmcraft_project::ParamValue::Float(0.0));
p.put_keyframe(Tick(4_500), filmcraft_project::ParamValue::Float(-20.0));
let ramp = line(&it, body, 0.0, 400.0);
assert!(ramp.len() > 100);
assert!(ramp.windows(2).all(|w| w[1].y >= w[0].y), "goes down as the level falls");
assert!(ramp.last().unwrap().y > y_of(body, -19.0));
// damaged geometry draws nothing silly rather than looping or panicking
assert_eq!(line(&it, body, 0.0, f32::NAN).len(), 2);
assert!(line(&it, body, 0.0, f32::INFINITY).len() <= 4097);
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.