craft-time: preserve SoundCraft time API and serialization

Cargo.lock

@@ -717,6 +717,8 @@ version = "0.1.0"
 dependencies = [
  "proptest",
  "serde",
+ "serde_json",
+ "thiserror 2.0.21",
 ]
 
 [[package]]

crates/time/Cargo.toml

@@ -12,6 +12,8 @@ workspace = true
 
 [dependencies]
 serde = { workspace = true }
+thiserror.workspace = true
 
 [dev-dependencies]
+serde_json = { workspace = true }
 proptest = "1.4"

crates/time/src/lib.rs

@@ -15,6 +15,10 @@ use serde::{Deserialize, Serialize};
 use std::fmt;
 use std::ops::{Add, AddAssign, Div, Mul, Neg, Rem, Sub, SubAssign};
 
+/// SoundCraft's sample-index, tempo-map, grid, and display-time API, retained verbatim for
+/// session-format compatibility while sharing the broader Craft time primitives above.
+pub mod soundcraft;
+
 /// Clock ticks per second: 254 016 000 000.
 pub const TICKS_PER_SECOND: i64 = 254_016_000_000;
 

crates/time/src/soundcraft/format.rs

@@ -0,0 +1,241 @@
+//! Formatting and parsing positions in the five timebases.
+
+use super::{BarBeat, FrameRate, SampleRate, Samples, TempoMap, TimeError, Timecode, timecode::feet_frames};
+
+/// The counters' and rulers' timebases.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum TimeFormat {
+    BarsBeats,
+    #[default]
+    MinSecs,
+    Timecode,
+    FeetFrames,
+    Samples,
+}
+
+impl TimeFormat {
+    pub const ALL: [TimeFormat; 5] = [TimeFormat::BarsBeats, TimeFormat::MinSecs, TimeFormat::Timecode, TimeFormat::FeetFrames, TimeFormat::Samples];
+
+    pub fn label(self) -> &'static str {
+        match self {
+            TimeFormat::BarsBeats => "Bars|Beats",
+            TimeFormat::MinSecs => "Min:Secs",
+            TimeFormat::Timecode => "Timecode",
+            TimeFormat::FeetFrames => "Feet+Frames",
+            TimeFormat::Samples => "Samples",
+        }
+    }
+
+    pub fn id(self) -> &'static str {
+        match self {
+            TimeFormat::BarsBeats => "bars_beats",
+            TimeFormat::MinSecs => "min_secs",
+            TimeFormat::Timecode => "timecode",
+            TimeFormat::FeetFrames => "feet_frames",
+            TimeFormat::Samples => "samples",
+        }
+    }
+
+    pub fn from_id(id: &str) -> Option<TimeFormat> {
+        TimeFormat::ALL.into_iter().find(|f| f.id() == id || f.label().eq_ignore_ascii_case(id))
+    }
+}
+
+fn min_secs(s: Samples, sr: SampleRate) -> String {
+    let neg = s < 0;
+    // Integer maths: a float `seconds * 1000` lands just below exact millisecond positions.
+    let ms_total = i64::try_from(i128::from(s).abs() * 1000 / i128::from(sr.hz().max(1))).unwrap_or(i64::MAX);
+    let mins = ms_total / 60_000;
+    let secs = (ms_total / 1000) % 60;
+    let ms = ms_total % 1000;
+    format!("{}{mins}:{secs:02}.{ms:03}", if neg { "-" } else { "" })
+}
+
+/// Format an absolute position. `tc_start` is the timecode of sample 0 in samples, `ff_start` the
+/// feet+frames reading of sample 0 in frames.
+pub fn format_position(s: Samples, fmt: TimeFormat, sr: SampleRate, map: &TempoMap, rate: FrameRate, tc_start: Samples, ff_start: i64) -> String {
+    match fmt {
+        TimeFormat::Samples => s.to_string(),
+        TimeFormat::MinSecs => min_secs(s, sr),
+        TimeFormat::Timecode => Timecode::from_samples(s.saturating_add(tc_start), rate, sr).format(rate),
+        TimeFormat::FeetFrames => {
+            let (ft, fr) = feet_frames(s, rate, sr, ff_start);
+            format!("{ft}+{fr:02}")
+        }
+        TimeFormat::BarsBeats => {
+            let bb = map.bar_beat_at(s, sr);
+            format!("{}| {}| {:03}", bb.bar, bb.beat, bb.tick)
+        }
+    }
+}
+
+/// Format a length starting at `start` (Bars|Beats lengths count from 0|0|000).
+pub fn format_length(start: Samples, len: Samples, fmt: TimeFormat, sr: SampleRate, map: &TempoMap, rate: FrameRate) -> String {
+    match fmt {
+        TimeFormat::BarsBeats => {
+            let t0 = map.samples_to_ticks(start, sr);
+            let t1 = map.samples_to_ticks(start.saturating_add(len), sr);
+            let m = map.meter_at_tick(t0);
+            let d = (t1 - t0).max(0);
+            let bars = d / m.ticks_per_bar().max(1);
+            let rem = d % m.ticks_per_bar().max(1);
+            format!("{bars}| {}| {:03}", rem / m.ticks_per_beat().max(1), rem % m.ticks_per_beat().max(1))
+        }
+        TimeFormat::Timecode => Timecode::from_samples(len, rate, sr).format(rate),
+        other => format_position(len, other, sr, map, rate, 0, 0),
+    }
+}
+
+/// Parse a position typed into a counter or dialog.
+pub fn parse_position(
+    text: &str,
+    fmt: TimeFormat,
+    sr: SampleRate,
+    map: &TempoMap,
+    rate: FrameRate,
+    tc_start: Samples,
+    ff_start: i64,
+) -> Result<Samples, TimeError> {
+    let t = text.trim();
+    let err = || TimeError::Parse(t.to_string(), fmt.label());
+    match fmt {
+        TimeFormat::Samples => t.replace([',', '_'], "").parse::<i64>().map_err(|_| err()),
+        TimeFormat::MinSecs => {
+            let (neg, body) = match t.strip_prefix('-') {
+                Some(r) => (true, r),
+                None => (false, t),
+            };
+            let (m, s) = match body.split_once(':') {
+                Some((m, s)) => (m.trim().parse::<f64>().map_err(|_| err())?, s.trim().parse::<f64>().map_err(|_| err())?),
+                None => (0.0, body.parse::<f64>().map_err(|_| err())?),
+            };
+            if !m.is_finite() || !s.is_finite() || m < 0.0 || s < 0.0 {
+                return Err(err());
+            }
+            let v = sr.samples(m * 60.0 + s);
+            Ok(if neg { -v } else { v })
+        }
+        TimeFormat::Timecode => {
+            let tc = Timecode::parse(t)?;
+            if tc.minutes >= 60 || tc.seconds >= 60 || tc.frames >= rate.nominal().max(1) {
+                return Err(err());
+            }
+            if rate.is_drop() && tc.seconds == 0 && tc.minutes % 10 != 0 {
+                let dropped = if rate.nominal() >= 60 { 4 } else { 2 };
+                if tc.frames < dropped {
+                    return Err(err());
+                }
+            }
+            Ok(tc.to_samples(rate, sr).saturating_sub(tc_start))
+        }
+        TimeFormat::FeetFrames => {
+            let (ft, fr) = t.split_once('+').ok_or_else(err)?;
+            let ft: i64 = ft.trim().parse().map_err(|_| err())?;
+            let fr: i64 = fr.trim().parse().map_err(|_| err())?;
+            Ok(rate.samples_at_frame(ft.saturating_mul(16).saturating_add(fr).saturating_sub(ff_start), sr))
+        }
+        TimeFormat::BarsBeats => {
+            let parts: Vec<i64> =
+                t.split(['|', '.', ' ']).filter(|p| !p.is_empty()).map(str::parse::<i64>).collect::<Result<_, _>>().map_err(|_| err())?;
+            let bb = BarBeat {
+                bar: *parts.first().ok_or_else(err)?,
+                beat: parts.get(1).copied().unwrap_or(1).max(1),
+                tick: parts.get(2).copied().unwrap_or(0).max(0),
+            };
+            Ok(map.samples_at_bar_beat(bb, sr))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn ctx() -> (SampleRate, TempoMap, FrameRate) {
+        (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps30)
+    }
+
+    #[test]
+    fn huge_typed_positions_parse_without_overflowing() {
+        let (sr, map, rate) = ctx();
+        for (text, fmt) in [
+            ("999999999999999999:0", TimeFormat::Timecode),
+            ("100000000000000:00:00:00", TimeFormat::Timecode),
+            ("-9223372036854775808", TimeFormat::BarsBeats),
+        ] {
+            let _ = parse_position(text, fmt, sr, &map, rate, 0, 0);
+        }
+    }
+
+    #[test]
+    fn formats_like_pro_tools_counters() {
+        let (sr, map, rate) = ctx();
+        assert_eq!(format_position(0, TimeFormat::MinSecs, sr, &map, rate, 0, 0), "0:00.000");
+        assert_eq!(format_position(48_000 * 75 + 24_000, TimeFormat::MinSecs, sr, &map, rate, 0, 0), "1:15.500");
+        assert_eq!(format_position(0, TimeFormat::BarsBeats, sr, &map, rate, 0, 0), "1| 1| 000");
+        assert_eq!(format_position(48_000, TimeFormat::Timecode, sr, &map, rate, 0, 0), "00:00:01:00");
+        assert_eq!(format_position(12345, TimeFormat::Samples, sr, &map, rate, 0, 0), "12345");
+    }
+
+    #[test]
+    fn minimum_bar_parses_without_overflow() {
+        let (sr, map, rate) = ctx();
+        let p = |t: &str| parse_position(t, TimeFormat::BarsBeats, sr, &map, rate, 0, 0);
+        assert!(p("-9223372036854775808|01|000").is_ok_and(|s| s < 0));
+        assert_eq!(p("2|3|000").ok(), Some(144_000));
+        assert_eq!(p("0|1|000").ok(), Some(-96_000));
+    }
+
+    #[test]
+    fn parse_round_trips() {
+        let (sr, map, rate) = ctx();
+        for fmt in TimeFormat::ALL {
+            for s in [0i64, 48_000, 96_000 * 3, 1_440_000] {
+                let text = format_position(s, fmt, sr, &map, rate, 0, 0);
+                let back = parse_position(&text, fmt, sr, &map, rate, 0, 0).unwrap();
+                assert!((back - s).abs() <= 48, "{fmt:?} {s} → {text} → {back}");
+            }
+        }
+    }
+
+    #[test]
+    fn parse_round_trips_timecode_negative() {
+        let (sr, map, _) = ctx();
+        let rate = FrameRate::Fps25;
+        for fmt in [TimeFormat::Timecode, TimeFormat::FeetFrames] {
+            for s in [-48_000i64, -96_000 * 3, -1_440_000] {
+                let text = format_position(s, fmt, sr, &map, rate, 0, 0);
+                let back = parse_position(&text, fmt, sr, &map, rate, 0, 0).unwrap();
+                assert_eq!(back, s, "{fmt:?} {s} → {text} → {back}");
+            }
+        }
+    }
+
+    #[test]
+    fn parse_rejects_garbage() {
+        let (sr, map, rate) = ctx();
+        assert!(parse_position("abc", TimeFormat::Samples, sr, &map, rate, 0, 0).is_err());
+        assert!(parse_position("1:x", TimeFormat::MinSecs, sr, &map, rate, 0, 0).is_err());
+        assert!(parse_position("", TimeFormat::BarsBeats, sr, &map, rate, 0, 0).is_err());
+    }
+
+    #[test]
+    fn drop_frame_skipped_labels_are_rejected() {
+        let (sr, map, _) = ctx();
+        for (rate, skipped) in [
+            (FrameRate::Fps29_97Drop, &["00:01:00;00", "00:01:00;01"][..]),
+            (FrameRate::Fps59_94Drop, &["00:01:00;00", "00:01:00;01", "00:01:00;02", "00:01:00;03"][..]),
+        ] {
+            for text in skipped {
+                assert!(parse_position(text, TimeFormat::Timecode, sr, &map, rate, 0, 0).is_err(), "accepted skipped label {text} at {rate:?}");
+            }
+            assert!(parse_position("00:10:00;00", TimeFormat::Timecode, sr, &map, rate, 0, 0).is_ok());
+        }
+    }
+
+    #[test]
+    fn bar_lengths() {
+        let (sr, map, rate) = ctx();
+        assert_eq!(format_length(0, 96_000 + 24_000, TimeFormat::BarsBeats, sr, &map, rate), "1| 1| 000");
+    }
+}

crates/time/src/soundcraft/grid.rs

@@ -0,0 +1,809 @@
+//! Grid and Nudge values: musical or absolute step sizes, grid lines and snapping.
+
+use super::{FrameRate, SampleRate, Samples, TICKS_PER_QUARTER, TempoMap, Timecode, to_samples};
+
+/// Note values for Bars|Beats grids.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum NoteValue {
+    Bar,
+    Whole,
+    Half,
+    Quarter,
+    Eighth,
+    Sixteenth,
+    ThirtySecond,
+    SixtyFourth,
+}
+
+impl NoteValue {
+    /// Every musical increment in menu order, from largest to smallest.
+    pub const ALL: [NoteValue; 8] = [
+        NoteValue::Bar,
+        NoteValue::Whole,
+        NoteValue::Half,
+        NoteValue::Quarter,
+        NoteValue::Eighth,
+        NoteValue::Sixteenth,
+        NoteValue::ThirtySecond,
+        NoteValue::SixtyFourth,
+    ];
+    /// Returns the nominal tick length; bars are adjusted for the active meter when used.
+    pub fn ticks(self) -> i64 {
+        match self {
+            NoteValue::Bar => TICKS_PER_QUARTER * 4,
+            NoteValue::Whole => TICKS_PER_QUARTER * 4,
+            NoteValue::Half => TICKS_PER_QUARTER * 2,
+            NoteValue::Quarter => TICKS_PER_QUARTER,
+            NoteValue::Eighth => TICKS_PER_QUARTER / 2,
+            NoteValue::Sixteenth => TICKS_PER_QUARTER / 4,
+            NoteValue::ThirtySecond => TICKS_PER_QUARTER / 8,
+            NoteValue::SixtyFourth => TICKS_PER_QUARTER / 16,
+        }
+    }
+    /// Returns the menu label for this musical increment.
+    pub fn label(self) -> &'static str {
+        match self {
+            NoteValue::Bar => "1 bar",
+            NoteValue::Whole => "Whole note",
+            NoteValue::Half => "1/2 note",
+            NoteValue::Quarter => "1/4 note",
+            NoteValue::Eighth => "1/8 note",
+            NoteValue::Sixteenth => "1/16 note",
+            NoteValue::ThirtySecond => "1/32 note",
+            NoteValue::SixtyFourth => "1/64 note",
+        }
+    }
+}
+
+/// The time scale used by a Grid or Nudge value.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum GridScale {
+    BarsBeats,
+    MinSecs,
+    Timecode,
+    FeetFrames,
+    Samples,
+    ClipsMarkers,
+}
+
+impl GridScale {
+    /// Numeric time scales shared by Grid and Nudge.
+    pub const TIME: [GridScale; 5] = [GridScale::BarsBeats, GridScale::MinSecs, GridScale::Timecode, GridScale::FeetFrames, GridScale::Samples];
+
+    /// Returns the user-facing scale label.
+    pub fn label(self) -> &'static str {
+        match self {
+            GridScale::BarsBeats => "Bars|Beats",
+            GridScale::MinSecs => "Min:Secs",
+            GridScale::Timecode => "Timecode",
+            GridScale::FeetFrames => "Feet+Frames",
+            GridScale::Samples => "Samples",
+            GridScale::ClipsMarkers => "Clips/Markers",
+        }
+    }
+
+    /// Returns the stable command and session identifier.
+    pub fn id(self) -> &'static str {
+        match self {
+            GridScale::BarsBeats => "bars_beats",
+            GridScale::MinSecs => "min_secs",
+            GridScale::Timecode => "timecode",
+            GridScale::FeetFrames => "feet_frames",
+            GridScale::Samples => "samples",
+            GridScale::ClipsMarkers => "clips_markers",
+        }
+    }
+
+    /// Parses a stable identifier or user-facing label.
+    pub fn from_id(id: &str) -> Option<GridScale> {
+        Self::TIME.into_iter().chain([GridScale::ClipsMarkers]).find(|scale| scale.id() == id || scale.label().eq_ignore_ascii_case(id))
+    }
+}
+
+/// Timecode Grid/Nudge increments, ordered independently of the session frame rate.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum TimecodeValue {
+    Second,
+    /// Five physical frames, independent of skipped drop-frame labels.
+    FiveFrames,
+    Frame,
+    HalfFrame,
+    QuarterFrame,
+    SubFrame,
+}
+
+impl TimecodeValue {
+    /// Every Timecode increment in menu order, from largest to smallest.
+    pub const ALL: [TimecodeValue; 6] = [
+        TimecodeValue::Second,
+        TimecodeValue::FiveFrames,
+        TimecodeValue::Frame,
+        TimecodeValue::HalfFrame,
+        TimecodeValue::QuarterFrame,
+        TimecodeValue::SubFrame,
+    ];
+
+    /// Returns the user-facing increment label.
+    pub fn label(self) -> &'static str {
+        match self {
+            TimecodeValue::Second => "1 second",
+            TimecodeValue::FiveFrames => "5 frames",
+            TimecodeValue::Frame => "1 frame",
+            TimecodeValue::HalfFrame => "1/2 frame",
+            TimecodeValue::QuarterFrame => "1/4 frame",
+            TimecodeValue::SubFrame => "1 subframe",
+        }
+    }
+
+    /// Returns the stable command and session identifier.
+    pub fn id(self) -> &'static str {
+        match self {
+            TimecodeValue::Second => "second",
+            TimecodeValue::FiveFrames => "5_frames",
+            TimecodeValue::Frame => "frame",
+            TimecodeValue::HalfFrame => "half_frame",
+            TimecodeValue::QuarterFrame => "quarter_frame",
+            TimecodeValue::SubFrame => "subframe",
+        }
+    }
+
+    /// Parses a stable identifier or user-facing label.
+    pub fn from_id(id: &str) -> Option<TimecodeValue> {
+        Self::ALL.into_iter().find(|value| value.id() == id || value.label().eq_ignore_ascii_case(id))
+    }
+
+    /// Returns the increment length in frames at the session rate.
+    fn frames(self, rate: FrameRate) -> f64 {
+        match self {
+            TimecodeValue::Second => rate.nominal() as f64,
+            TimecodeValue::FiveFrames => 5.0,
+            TimecodeValue::Frame => 1.0,
+            TimecodeValue::HalfFrame => 0.5,
+            TimecodeValue::QuarterFrame => 0.25,
+            TimecodeValue::SubFrame => 0.01,
+        }
+    }
+}
+
+/// Feet+Frames Grid/Nudge increments in physical frames, independent of drop-frame label skips.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub enum FeetFramesValue {
+    Foot,
+    Frame,
+    QuarterFrame,
+    SubFrame,
+}
+
+impl FeetFramesValue {
+    /// Every Feet+Frames increment in menu order, from largest to smallest.
+    pub const ALL: [FeetFramesValue; 4] = [FeetFramesValue::Foot, FeetFramesValue::Frame, FeetFramesValue::QuarterFrame, FeetFramesValue::SubFrame];
+
+    /// Returns the user-facing increment label.
+    pub fn label(self) -> &'static str {
+        match self {
+            FeetFramesValue::Foot => "1 foot",
+            FeetFramesValue::Frame => "1 frame",
+            FeetFramesValue::QuarterFrame => "1/4 frame",
+            FeetFramesValue::SubFrame => "1 subframe",
+        }
+    }
+
+    /// Returns the stable command and session identifier.
+    pub fn id(self) -> &'static str {
+        match self {
+            FeetFramesValue::Foot => "foot",
+            FeetFramesValue::Frame => "frame",
+            FeetFramesValue::QuarterFrame => "quarter_frame",
+            FeetFramesValue::SubFrame => "subframe",
+        }
+    }
+
+    /// Parses a stable identifier or user-facing label.
+    pub fn from_id(id: &str) -> Option<FeetFramesValue> {
+        Self::ALL.into_iter().find(|value| value.id() == id || value.label().eq_ignore_ascii_case(id))
+    }
+
+    /// Returns the increment length in frames.
+    fn frames(self) -> f64 {
+        let (num, den) = self.frame_ratio();
+        num as f64 / den as f64
+    }
+
+    /// Exact numerator and denominator of the increment in physical frames.
+    fn frame_ratio(self) -> (i128, i128) {
+        match self {
+            Self::Foot => (16, 1),
+            Self::Frame => (1, 1),
+            Self::QuarterFrame => (1, 4),
+            Self::SubFrame => (1, 100),
+        }
+    }
+
+    /// Apply the counter origin in frames before rounding once to the nearest sample.
+    fn sample_line(self, index: i128, sr: SampleRate, rate: FrameRate, origin: i64) -> Samples {
+        let (num, den) = self.frame_ratio();
+        let (rate_num, rate_den) = rate.rational();
+        let frames = index * num - i128::from(origin) * den;
+        let samples = frames * i128::from(sr.hz().max(1)) * i128::from(rate_den);
+        let divisor = den * i128::from(rate_num);
+        let magnitude = (samples.abs() + divisor / 2) / divisor;
+        let rounded = if samples < 0 { -magnitude } else { magnitude };
+        i64::try_from(rounded).unwrap_or(if rounded < 0 { i64::MIN } else { i64::MAX })
+    }
+
+    /// Find a line index using exact frame arithmetic, allowing for whole-sample rounding.
+    fn line_index(self, position: Samples, sr: SampleRate, rate: FrameRate, origin: i64) -> i128 {
+        let (num, den) = self.frame_ratio();
+        let (rate_num, rate_den) = rate.rational();
+        let scale = i128::from(sr.hz().max(1)) * i128::from(rate_den);
+        let frames = i128::from(position) * i128::from(rate_num) + i128::from(origin) * scale;
+        let mut index = (frames * den).div_euclid(scale * num);
+        if self.sample_line(index + 1, sr, rate, origin) <= position {
+            index += 1;
+        }
+        index
+    }
+
+    /// The Feet+Frames line at or before a sample, relative to the counter's frame origin.
+    pub fn line_at_or_before(self, position: Samples, sr: SampleRate, rate: FrameRate, origin: i64) -> Samples {
+        self.sample_line(self.line_index(position, sr, rate, origin), sr, rate, origin)
+    }
+
+    /// The next distinct sample line; subframe increments may share a sample at low sample rates.
+    fn next_line(self, position: Samples, sr: SampleRate, rate: FrameRate, origin: i64) -> Samples {
+        self.sample_line(self.line_index(position, sr, rate, origin) + 1, sr, rate, origin).max(position.saturating_add(1))
+    }
+
+    /// Snap against frame-origin lines, choosing the earlier line when distances are equal.
+    pub fn snap(self, position: Samples, sr: SampleRate, rate: FrameRate, origin: i64) -> Samples {
+        let lo = self.line_at_or_before(position, sr, rate, origin);
+        let hi = self.next_line(lo, sr, rate, origin);
+        if i128::from(position) - i128::from(lo) <= i128::from(hi) - i128::from(position) { lo } else { hi }
+    }
+
+    /// Distinct Feet+Frames sample lines within `[start, end)`, capped at `max`.
+    pub fn lines(self, start: Samples, end: Samples, sr: SampleRate, rate: FrameRate, origin: i64, max: usize) -> Vec<Samples> {
+        let mut out = Vec::new();
+        let mut line = self.line_at_or_before(start, sr, rate, origin);
+        while line < end && out.len() < max {
+            if line >= start {
+                out.push(line);
+            }
+            let next = self.next_line(line, sr, rate, origin);
+            if next <= line {
+                break;
+            }
+            line = next;
+        }
+        out
+    }
+}
+
+/// A grid or nudge step.
+#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
+pub enum GridValue {
+    /// Musical: note value, optionally dotted or triplet.
+    Note { value: NoteValue, dotted: bool, triplet: bool },
+    /// Absolute seconds (Min:Secs grids: 0.001 … 1 s).
+    Seconds(f64),
+    /// Frames at the session timecode rate.
+    /// Kept for sessions and commands written before named timecode increments were added.
+    Frames(i64),
+    /// A named Timecode increment, including fractional frames and one second.
+    Timecode(TimecodeValue),
+    /// A Feet+Frames increment (one foot is 16 frames).
+    FeetFrames(FeetFramesValue),
+    /// Raw samples.
+    Samples(i64),
+}
+
+impl Default for GridValue {
+    /// Starts on a straight sixteenth-note Bars|Beats grid.
+    fn default() -> Self {
+        GridValue::Note { value: NoteValue::Sixteenth, dotted: false, triplet: false }
+    }
+}
+
+impl GridValue {
+    /// Returns the user-facing label for this increment.
+    pub fn label(&self) -> String {
+        match self {
+            GridValue::Note { value, dotted, triplet } => {
+                let mut s = value.label().to_string();
+                if *dotted {
+                    s.push_str(" dotted");
+                }
+                if *triplet {
+                    s.push_str(" triplet");
+                }
+                s
+            }
+            GridValue::Seconds(s) => {
+                if *s >= 1.0 {
+                    format!("{s} second{}", if *s == 1.0 { "" } else { "s" })
+                } else {
+                    format!("{} ms", (s * 1000.0).round() as i64)
+                }
+            }
+            GridValue::Frames(f) => format!("{f} frame{}", if *f == 1 { "" } else { "s" }),
+            GridValue::Timecode(value) => value.label().to_string(),
+            GridValue::FeetFrames(value) => value.label().to_string(),
+            GridValue::Samples(n) => format!("{n} sample{}", if *n == 1 { "" } else { "s" }),
+        }
+    }
+
+    /// Returns the time scale to which this increment belongs.
+    pub fn scale(self) -> GridScale {
+        match self {
+            GridValue::Note { .. } => GridScale::BarsBeats,
+            GridValue::Seconds(_) => GridScale::MinSecs,
+            GridValue::Frames(_) | GridValue::Timecode(_) => GridScale::Timecode,
+            GridValue::FeetFrames(_) => GridScale::FeetFrames,
+            GridValue::Samples(_) => GridScale::Samples,
+        }
+    }
+
+    /// Returns the default increment for a newly selected time scale.
+    pub fn for_scale(scale: GridScale) -> GridValue {
+        match scale {
+            GridScale::BarsBeats => GridValue::default(),
+            GridScale::MinSecs => GridValue::Seconds(1.0),
+            GridScale::Timecode => GridValue::Timecode(TimecodeValue::Frame),
+            GridScale::FeetFrames => GridValue::FeetFrames(FeetFramesValue::Frame),
+            GridScale::Samples => GridValue::Samples(100),
+            GridScale::ClipsMarkers => GridValue::default(),
+        }
+    }
+
+    /// The next larger or smaller menu value of the same kind, or `self` at either end. Note values keep
+    /// their dot or triplet modifier.
+    pub fn stepped(self, larger: bool) -> GridValue {
+        /// Finds the next value in a numeric increment ladder without wrapping.
+        fn next<T: PartialOrd + Copy>(ladder: &[T], v: T, larger: bool) -> Option<T> {
+            if larger { ladder.iter().copied().find(|x| *x > v) } else { ladder.iter().rev().copied().find(|x| *x < v) }
+        }
+        match self {
+            GridValue::Note { value, dotted, triplet } => {
+                let i = NoteValue::ALL.iter().position(|v| *v == value).unwrap_or(0);
+                let j = if larger { i.checked_sub(1) } else { i.checked_add(1) };
+                j.and_then(|j| NoteValue::ALL.get(j)).map_or(self, |&value| GridValue::Note { value, dotted, triplet })
+            }
+            GridValue::Seconds(s) => next(&[0.001, 0.01, 0.1, 0.5, 1.0], s, larger).map_or(self, GridValue::Seconds),
+            GridValue::Frames(f) => next(&[1, 10, 100], f, larger).map_or(self, GridValue::Frames),
+            GridValue::Timecode(value) => step_enum(&TimecodeValue::ALL, value, larger).map_or(self, GridValue::Timecode),
+            GridValue::FeetFrames(value) => step_enum(&FeetFramesValue::ALL, value, larger).map_or(self, GridValue::FeetFrames),
+            GridValue::Samples(n) => next(&[1, 2, 10, 100, 1_000, 10_000], n, larger).map_or(self, GridValue::Samples),
+        }
+    }
+
+    fn note_ticks(value: NoteValue, dotted: bool, triplet: bool, map: &TempoMap, at_tick: i64) -> i64 {
+        let base = if value == NoteValue::Bar { map.meter_at_tick(at_tick).ticks_per_bar() } else { value.ticks() };
+        let mut t = base;
+        if dotted {
+            t = t * 3 / 2;
+        }
+        if triplet {
+            t = t * 2 / 3;
+        }
+        t.max(1)
+    }
+
+    /// The step in samples at position `at` (musical steps depend on tempo).
+    pub fn step_samples(&self, at: Samples, sr: SampleRate, map: &TempoMap, rate: FrameRate) -> Samples {
+        match *self {
+            GridValue::Note { value, dotted, triplet } => {
+                let t0 = map.samples_to_ticks(at, sr);
+                let dt = Self::note_ticks(value, dotted, triplet, map, t0);
+                (map.tick_to_samples(t0.saturating_add(dt), sr).saturating_sub(map.tick_to_samples(t0, sr))).max(1)
+            }
+            GridValue::Seconds(s) => sr.samples(s.clamp(0.000_01, 3600.0)).max(1),
+            GridValue::Frames(f) => to_samples(rate.samples_per_frame(sr) * f.clamp(1, 1_000_000) as f64).max(1),
+            GridValue::Timecode(value) => to_samples(rate.samples_per_frame(sr) * value.frames(rate)).max(1),
+            GridValue::FeetFrames(value) => to_samples(rate.samples_per_frame(sr) * value.frames()).max(1),
+            GridValue::Samples(n) => n.max(1),
+        }
+    }
+
+    /// Nearest grid line to `pos`.
+    pub fn snap(&self, pos: Samples, sr: SampleRate, map: &TempoMap, rate: FrameRate) -> Samples {
+        if let Self::FeetFrames(value) = *self {
+            return value.snap(pos, sr, rate, 0);
+        }
+        let lo = self.line_at_or_before(pos, sr, map, rate);
+        let hi = self.next_line(lo, sr, map, rate);
+        if (pos - lo) <= (hi - pos) { lo } else { hi }
+    }
+
+    /// The grid line at or before `pos`.
+    pub fn line_at_or_before(&self, pos: Samples, sr: SampleRate, map: &TempoMap, rate: FrameRate) -> Samples {
+        match *self {
+            Self::FeetFrames(value) => value.line_at_or_before(pos, sr, rate, 0),
+            GridValue::Note { value, dotted, triplet } => {
+                // Float ticks can land a hair either side of a line's own tick.
+                let mut t = map.samples_to_ticks_f(pos, sr).floor() as i64;
+                if map.tick_to_samples(t, sr) > pos {
+                    t = t.saturating_sub(1);
+                } else if map.tick_to_samples(t.saturating_add(1), sr) <= pos {
+                    t = t.saturating_add(1);
+                }
+                // Sub-bar values restart at each bar so odd meters stay aligned. A whole note is
+                // always four quarter notes and therefore keeps a continuous tick origin.
+                let bb = map.bar_beat_at_tick(t);
+                let bar_tick = map.bar_start_tick(bb.bar);
+                let origin = if value == NoteValue::Whole { 0 } else { bar_tick };
+                let step = Self::note_ticks(value, dotted, triplet, map, origin);
+                let k = (t - origin).div_euclid(step);
+                map.tick_to_samples(origin + k * step, sr)
+            }
+            _ => self.abs_line(self.abs_index_at_or_before(pos, sr, rate), sr, rate),
+        }
+    }
+
+    /// Position of absolute grid line `k` (Seconds, Frames, Samples), at an exact multiple of the step
+    /// rounded once, so rounding never accumulates from line to line.
+    fn abs_line(&self, k: i64, sr: SampleRate, rate: FrameRate) -> Samples {
+        if let Self::FeetFrames(value) = *self {
+            return value.sample_line(i128::from(k), sr, rate, 0);
+        }
+        if matches!(self, GridValue::Timecode(TimecodeValue::Second)) && rate.is_drop() {
+            return rate.samples_at_frame(Self::drop_second_frame(k, rate), sr);
+        }
+        if let Some(frames) = self.frame_step(rate) {
+            let whole = frames.round();
+            if frames == whole {
+                return rate.samples_at_frame(k.saturating_mul(whole as i64), sr);
+            }
+            let step = (rate.samples_per_frame(sr) * frames).max(1.0);
+            return to_samples(k as f64 * step);
+        }
+        match *self {
+            GridValue::Seconds(s) => to_samples(k as f64 * Self::seconds_step(s, sr)),
+            GridValue::Samples(n) => k.saturating_mul(n.max(1)),
+            GridValue::Note { .. } => 0,
+            GridValue::Frames(_) | GridValue::Timecode(_) | GridValue::FeetFrames(_) => 0,
+        }
+    }
+
+    /// Index of the absolute grid line at or before `pos`.
+    fn abs_index_at_or_before(&self, pos: Samples, sr: SampleRate, rate: FrameRate) -> i64 {
+        if matches!(self, GridValue::Timecode(TimecodeValue::Second)) && rate.is_drop() {
+            let tc = Timecode::from_frames(rate.frames_at(pos, sr), rate);
+            let magnitude = tc.hours.saturating_mul(3600).saturating_add(tc.minutes.saturating_mul(60)).saturating_add(tc.seconds);
+            let mut k = if tc.negative { magnitude.saturating_neg() } else { magnitude };
+            while self.abs_line(k, sr, rate) > pos {
+                let previous = k.saturating_sub(1);
+                if previous == k {
+                    break;
+                }
+                k = previous;
+            }
+            while self.abs_line(k.saturating_add(1), sr, rate) <= pos {
+                let next = k.saturating_add(1);
+                if next == k {
+                    break;
+                }
+                k = next;
+            }
+            return k;
+        }
+        let mut k = if let Some(frames) = self.frame_step(rate) {
+            let step = (rate.samples_per_frame(sr) * frames).max(1.0);
+            (pos as f64 / step).floor() as i64
+        } else {
+            match *self {
+                GridValue::Seconds(s) => (pos as f64 / Self::seconds_step(s, sr)).floor() as i64,
+                GridValue::Samples(n) => return pos.div_euclid(n.max(1)),
+                GridValue::Note { .. } => return 0,
+                GridValue::Frames(_) | GridValue::Timecode(_) | GridValue::FeetFrames(_) => return 0,
+            }
+        };
+        // Lines are rounded to whole samples, so the floored index can be one off either way.
+        if self.abs_line(k, sr, rate) > pos {
+            k = k.saturating_sub(1);
+        } else if self.abs_line(k.saturating_add(1), sr, rate) <= pos {
+            k = k.saturating_add(1);
+        }
+        k
+    }
+
+    /// The exact (fractional) Seconds step in samples, at least one sample.
+    fn seconds_step(s: f64, sr: SampleRate) -> f64 {
+        (s.clamp(0.000_01, 3600.0) * sr.as_f64()).max(1.0)
+    }
+
+    /// Maps a signed whole-second timecode label to its physical frame at a drop-frame rate.
+    fn drop_second_frame(index: i64, rate: FrameRate) -> i64 {
+        let seconds = index.unsigned_abs();
+        let total_minutes = seconds / 60;
+        let frames = if seconds.is_multiple_of(60) && !total_minutes.is_multiple_of(10) { if rate.nominal() >= 60 { 4 } else { 2 } } else { 0 };
+        Timecode {
+            negative: index < 0,
+            hours: i64::try_from(seconds / 3600).unwrap_or(i64::MAX),
+            minutes: i64::try_from((seconds / 60) % 60).unwrap_or(0),
+            seconds: i64::try_from(seconds % 60).unwrap_or(0),
+            frames,
+        }
+        .to_frames(rate)
+    }
+
+    /// A frame-based increment as a possibly fractional number of frames.
+    fn frame_step(&self, rate: FrameRate) -> Option<f64> {
+        match *self {
+            GridValue::Frames(frames) => Some(frames.clamp(1, 1_000_000) as f64),
+            GridValue::Timecode(value) => Some(value.frames(rate)),
+            GridValue::FeetFrames(value) => Some(value.frames()),
+            _ => None,
+        }
+    }
+
+    /// The first grid line strictly after `line`.
+    pub fn next_line(&self, line: Samples, sr: SampleRate, map: &TempoMap, rate: FrameRate) -> Samples {
+        if let Self::FeetFrames(value) = *self {
+            return value.next_line(line, sr, rate, 0);
+        }
+        if !matches!(self, GridValue::Note { .. }) {
+            let next = self.abs_line(self.abs_index_at_or_before(line, sr, rate).saturating_add(1), sr, rate);
+            return if next > line { next } else { line.saturating_add(1) };
+        }
+        let step = self.step_samples(line, sr, map, rate);
+        let candidate = self.line_at_or_before(line.saturating_add(step), sr, map, rate);
+        if candidate > line { candidate } else { line.saturating_add(step) }
+    }
+
+    /// All grid lines within `[start, end)`, capped at `max` lines.
+    pub fn lines(&self, start: Samples, end: Samples, sr: SampleRate, map: &TempoMap, rate: FrameRate, max: usize) -> Vec<Samples> {
+        if let Self::FeetFrames(value) = *self {
+            return value.lines(start, end, sr, rate, 0, max);
+        }
+        let mut out = Vec::new();
+        let mut p = self.line_at_or_before(start, sr, map, rate);
+        while p < end && out.len() < max {
+            if p >= start {
+                out.push(p);
+            }
+            let n = self.next_line(p, sr, map, rate);
+            if n <= p {
+                break;
+            }
+            p = n;
+        }
+        out
+    }
+}
+
+/// Moves one position through an ordered increment menu without wrapping.
+fn step_enum<T: Copy + PartialEq>(values: &[T], value: T, larger: bool) -> Option<T> {
+    let index = values.iter().position(|candidate| *candidate == value)?;
+    let next = if larger { index.checked_sub(1) } else { index.checked_add(1) }?;
+    values.get(next).copied()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Frame origins are subtracted before rounding whole frames, quarter frames and subframes.
+    #[test]
+    fn feet_frames_origins_round_only_after_applying_the_frame_offset() {
+        let (sr, rate) = (SampleRate::HZ_48000, FrameRate::Fps29_97);
+        for at in [49_650, 100_901, 177_778] {
+            assert_eq!(FeetFramesValue::Foot.line_at_or_before(at, sr, rate, 1), at);
+            assert_eq!(FeetFramesValue::Foot.snap(at - 1, sr, rate, 1), at);
+        }
+        assert_eq!(FeetFramesValue::QuarterFrame.snap(50_049, sr, rate, 1), 50_050);
+        assert_eq!(FeetFramesValue::SubFrame.lines(49_665, 49_667, sr, rate, 1, 4), [49_666]);
+    }
+
+    /// Dense subframes retain distinct sample lines and remain bounded with extreme signed origins.
+    #[test]
+    fn feet_frames_subframes_handle_dense_steps_and_extreme_origins() {
+        let sr = SampleRate::new(8_000).unwrap();
+        let rate = FrameRate::Fps120;
+        for origin in [i64::MIN, -1, 0, 1, i64::MAX] {
+            assert_eq!(FeetFramesValue::SubFrame.lines(-3, 4, sr, rate, origin, 20), [-3, -2, -1, 0, 1, 2, 3]);
+            for at in [i64::MIN, -1, 0, 1, i64::MAX] {
+                assert_eq!(FeetFramesValue::SubFrame.line_at_or_before(at, sr, rate, origin), at);
+                assert_eq!(FeetFramesValue::SubFrame.snap(at, sr, rate, origin), at);
+            }
+        }
+    }
+
+    #[test]
+    fn grid_lines_are_their_own_line_at_odd_tempos() {
+        let (g, sr, rate) = (GridValue::default(), SampleRate::HZ_48000, FrameRate::Fps30);
+        for bpm in [90.0, 95.0, 110.0, 130.0, 140.0] {
+            let map = TempoMap::new(bpm, 4, 4).unwrap();
+            let mut line = 0;
+            for _ in 0..64 {
+                assert_eq!(g.line_at_or_before(line, sr, &map, rate), line, "{bpm} bpm");
+                line = g.next_line(line, sr, &map, rate);
+            }
+        }
+    }
+
+    /// Musical boundaries stay exact across a tempo change while absolute scales remain
+    /// independent of the tempo map.
+    #[test]
+    fn grids_stay_aligned_across_a_tempo_change() {
+        let (sr, rate) = (SampleRate::HZ_48000, FrameRate::Fps29_97Drop);
+        let mut map = TempoMap::default();
+        map.set_tempo(TICKS_PER_QUARTER * 4, 90.0).unwrap();
+        let musical = GridValue::Note { value: NoteValue::Quarter, dotted: false, triplet: false };
+        for tick in [0, TICKS_PER_QUARTER * 3, TICKS_PER_QUARTER * 4, TICKS_PER_QUARTER * 5] {
+            let line = map.tick_to_samples(tick, sr);
+            assert_eq!(musical.line_at_or_before(line, sr, &map, rate), line);
+        }
+        for absolute in [
+            GridValue::Seconds(0.5),
+            GridValue::Timecode(TimecodeValue::Second),
+            GridValue::FeetFrames(FeetFramesValue::Foot),
+            GridValue::Samples(1_000),
+        ] {
+            let line = absolute.next_line(absolute.line_at_or_before(100_000, sr, &map, rate), sr, &map, rate);
+            assert_eq!(absolute.line_at_or_before(line, sr, &map, rate), line, "{absolute:?}");
+        }
+    }
+
+    #[test]
+    fn sixteenth_grid_at_120() {
+        let g = GridValue::default();
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps30);
+        assert_eq!(g.step_samples(0, sr, &map, rate), 6000);
+        assert_eq!(g.snap(2900, sr, &map, rate), 0);
+        assert_eq!(g.snap(3100, sr, &map, rate), 6000);
+        assert_eq!(g.lines(0, 24_000, sr, &map, rate, 100), vec![0, 6000, 12000, 18000]);
+    }
+
+    /// Absolute increments report their expected sample lengths at a fixed rate.
+    #[test]
+    fn absolute_grids() {
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps25);
+        assert_eq!(GridValue::Seconds(1.0).snap(70_000, sr, &map, rate), 48_000);
+        assert_eq!(GridValue::Frames(1).step_samples(0, sr, &map, rate), 1920);
+        assert_eq!(GridValue::Timecode(TimecodeValue::Second).step_samples(0, sr, &map, rate), 48_000);
+        assert_eq!(GridValue::Timecode(TimecodeValue::FiveFrames).step_samples(0, sr, &map, rate), 9_600);
+        assert_eq!(GridValue::Timecode(TimecodeValue::HalfFrame).step_samples(0, sr, &map, rate), 960);
+        assert_eq!(GridValue::Timecode(TimecodeValue::QuarterFrame).step_samples(0, sr, &map, rate), 480);
+        assert_eq!(GridValue::Timecode(TimecodeValue::SubFrame).step_samples(0, sr, &map, rate), 19);
+        assert_eq!(GridValue::FeetFrames(FeetFramesValue::Foot).step_samples(0, sr, &map, rate), 30_720);
+        assert_eq!(GridValue::Samples(0).step_samples(0, sr, &map, rate), 1);
+    }
+
+    /// Bar length follows the meter while a whole note always spans four quarter notes.
+    #[test]
+    fn a_bar_and_a_whole_note_differ_in_three_four() {
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::new(120.0, 3, 4).unwrap(), FrameRate::Fps25);
+        let note = |value| GridValue::Note { value, dotted: false, triplet: false };
+        assert_eq!(note(NoteValue::Bar).step_samples(0, sr, &map, rate), 72_000);
+        assert_eq!(note(NoteValue::Whole).step_samples(0, sr, &map, rate), 96_000);
+        assert_eq!(note(NoteValue::Bar).line_at_or_before(96_000, sr, &map, rate), 72_000);
+        assert_eq!(note(NoteValue::Whole).line_at_or_before(96_000, sr, &map, rate), 96_000);
+        assert_eq!(note(NoteValue::Half).lines(0, 150_000, sr, &map, rate, 10), [0, 48_000, 72_000, 120_000, 144_000]);
+    }
+
+    #[test]
+    fn seconds_grid_lines_land_on_whole_seconds() {
+        let (sr, map, rate) = (SampleRate::HZ_44100, TempoMap::default(), FrameRate::Fps30);
+        for g in [GridValue::Seconds(0.001), GridValue::Seconds(0.01)] {
+            for n in 0..20 {
+                let s = n * 44_100;
+                assert_eq!(g.snap(s, sr, &map, rate), s, "{g:?} at {n} s");
+                assert_eq!(g.line_at_or_before(s, sr, &map, rate), s, "{g:?} at {n} s");
+            }
+        }
+    }
+
+    /// Legacy frame grids stay aligned to exact frame starts at fractional rates.
+    #[test]
+    fn frame_grid_lines_land_on_frame_starts() {
+        let sr = SampleRate::HZ_48000;
+        let map = TempoMap::default();
+        for rate in [FrameRate::Fps29_97, FrameRate::Fps23_976] {
+            for f in [1, 10] {
+                let g = GridValue::Frames(f);
+                for k in (0..5000).step_by(37) {
+                    let s = rate.samples_at_frame(k, sr);
+                    let line = rate.samples_at_frame(k.div_euclid(f) * f, sr);
+                    assert_eq!(g.line_at_or_before(s, sr, &map, rate), line, "{rate:?} {f} frames at frame {k}");
+                    if k % f == 0 {
+                        assert_eq!(g.snap(s, sr, &map, rate), s, "{rate:?} {f} frames at frame {k}");
+                    }
+                }
+                let start = rate.samples_at_frame(4000, sr);
+                let end = rate.samples_at_frame(4000 + 20 * f, sr);
+                let want: Vec<_> = (0..20).map(|i| rate.samples_at_frame(4000 + i * f, sr)).collect();
+                assert_eq!(g.lines(start, end, sr, &map, rate, 100), want, "{rate:?} {f} frames");
+            }
+        }
+    }
+
+    /// Named whole- and sub-frame grids retain the exact-multiple calculation used by legacy frame grids.
+    #[test]
+    fn named_frame_grids_land_on_exact_subdivisions() {
+        let sr = SampleRate::HZ_48000;
+        let map = TempoMap::default();
+        let grids = TimecodeValue::ALL.into_iter().map(GridValue::Timecode).chain(FeetFramesValue::ALL.into_iter().map(GridValue::FeetFrames));
+        for rate in [FrameRate::Fps29_97, FrameRate::Fps23_976] {
+            for grid in grids.clone() {
+                for index in 0..200 {
+                    let line = grid.abs_line(index, sr, rate);
+                    assert_eq!(grid.line_at_or_before(line, sr, &map, rate), line, "{grid:?} {rate:?} line {index}");
+                    assert_eq!(grid.next_line(line, sr, &map, rate), grid.abs_line(index + 1, sr, rate), "{grid:?} {rate:?} line {index}");
+                }
+            }
+        }
+    }
+
+    /// Drop-frame second grids follow labelled second boundaries in both timeline directions.
+    #[test]
+    fn drop_frame_second_grids_follow_timecode_labels() {
+        let sr = SampleRate::HZ_48000;
+        let map = TempoMap::default();
+        let grid = GridValue::Timecode(TimecodeValue::Second);
+        for rate in [FrameRate::Fps29_97Drop, FrameRate::Fps59_94Drop] {
+            for seconds in [0, 59, 60, 61, 600, 601, 3600] {
+                let frame = GridValue::drop_second_frame(seconds, rate);
+                let line = rate.samples_at_frame(frame, sr);
+                assert_eq!(grid.line_at_or_before(line, sr, &map, rate), line, "{rate:?} second {seconds}");
+                assert_eq!(grid.line_at_or_before(-line, sr, &map, rate), -line, "{rate:?} second -{seconds}");
+                for offset in -2..=rate.nominal() + 2 {
+                    let position = rate.samples_at_frame(frame.saturating_add(offset), sr);
+                    let before = grid.line_at_or_before(position, sr, &map, rate);
+                    assert!(before <= position, "{rate:?} second {seconds}, frame offset {offset}");
+                    assert!(grid.next_line(before, sr, &map, rate) > position, "{rate:?} second {seconds}, frame offset {offset}");
+                }
+            }
+            let labelled = Timecode { negative: false, hours: 0, minutes: 1, seconds: 1, frames: 0 }.to_samples(rate, sr);
+            assert_eq!(grid.snap(labelled, sr, &map, rate), labelled);
+        }
+
+        for (rate, minute_frame) in [(FrameRate::Fps29_97Drop, 1800), (FrameRate::Fps59_94Drop, 3600)] {
+            let boundary = rate.samples_at_frame(minute_frame, sr);
+            assert_eq!(grid.line_at_or_before(boundary, sr, &map, rate), boundary, "{rate:?} positive minute boundary");
+            assert_eq!(grid.snap(boundary, sr, &map, rate), boundary, "{rate:?} positive minute snap");
+            assert_eq!(grid.line_at_or_before(-boundary, sr, &map, rate), -boundary, "{rate:?} negative minute boundary");
+            assert_eq!(grid.snap(-boundary, sr, &map, rate), -boundary, "{rate:?} negative minute snap");
+        }
+    }
+
+    #[test]
+    fn lines_are_capped() {
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps25);
+        assert_eq!(GridValue::Samples(1).lines(0, 1_000_000, sr, &map, rate, 50).len(), 50);
+    }
+
+    #[test]
+    fn triplets_and_dots() {
+        let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps25);
+        let t = GridValue::Note { value: NoteValue::Quarter, dotted: false, triplet: true };
+        assert_eq!(t.step_samples(0, sr, &map, rate), 16_000);
+        let d = GridValue::Note { value: NoteValue::Quarter, dotted: true, triplet: false };
+        assert_eq!(d.step_samples(0, sr, &map, rate), 36_000);
+    }
+
+    /// Stepping follows each menu ladder and stops at its endpoints.
+    #[test]
+    fn values_step_to_the_next_larger_or_smaller() {
+        let note = |value, triplet| GridValue::Note { value, dotted: false, triplet };
+        assert_eq!(note(NoteValue::Sixteenth, false).stepped(true), note(NoteValue::Eighth, false));
+        assert_eq!(note(NoteValue::Eighth, true).stepped(false), note(NoteValue::Sixteenth, true));
+        assert_eq!(note(NoteValue::Bar, false).stepped(true), note(NoteValue::Bar, false));
+        assert_eq!(note(NoteValue::SixtyFourth, false).stepped(false), note(NoteValue::SixtyFourth, false));
+        assert_eq!(GridValue::Seconds(0.01).stepped(true), GridValue::Seconds(0.1));
+        assert_eq!(GridValue::Seconds(0.5).stepped(false), GridValue::Seconds(0.1));
+        assert_eq!(GridValue::Seconds(1.0).stepped(true), GridValue::Seconds(1.0));
+        assert_eq!(GridValue::Frames(1).stepped(true), GridValue::Frames(10));
+        assert_eq!(GridValue::Timecode(TimecodeValue::Frame).stepped(false), GridValue::Timecode(TimecodeValue::HalfFrame));
+        assert_eq!(GridValue::FeetFrames(FeetFramesValue::Frame).stepped(true), GridValue::FeetFrames(FeetFramesValue::Foot));
+        assert_eq!(GridValue::Samples(100).stepped(false), GridValue::Samples(10));
+        assert_eq!(GridValue::Samples(1).stepped(true), GridValue::Samples(2));
+        assert_eq!(GridValue::Samples(1).stepped(false), GridValue::Samples(1));
+    }
+
+    #[test]
+    fn snap_at_extreme_position_does_not_overflow() {
+        let sr = SampleRate::new(8000).unwrap();
+        let map = TempoMap::new(1000.0, 4, 4).unwrap();
+        let _ = GridValue::default().snap(i64::MAX, sr, &map, FrameRate::Fps30);
+    }
+}

crates/time/src/soundcraft/mod.rs

@@ -0,0 +1,155 @@
+//! SoundCraft timebases.
+//!
+//! Every position in a session is an absolute sample index (`i64`) at the session sample rate.
+//! This crate converts those positions to and from the five Pro Tools-style timebases
+//! (Bars|Beats, Min:Secs, Timecode, Feet+Frames, Samples) through a [`TempoMap`], and computes
+//! grid lines and snapping for the Grid / Nudge values.
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+
+mod format;
+mod grid;
+mod tempo;
+mod timecode;
+
+pub use format::{TimeFormat, format_length, format_position, parse_position};
+pub use grid::{FeetFramesValue, GridScale, GridValue, NoteValue, TimecodeValue};
+pub use tempo::{BarBeat, MeterEvent, TICKS_PER_QUARTER, TempoEvent, TempoMap};
+pub use timecode::{FrameRate, Timecode};
+
+/// A position or length in samples.
+pub type Samples = i64;
+
+/// Largest position accepted from parameters and files: 2^40 samples (about 265 days at 48 kHz).
+/// Clamping there keeps every later addition and subtraction on positions far away from overflow.
+pub const MAX_POSITION: Samples = 1 << 40;
+
+/// Errors from parsing or converting time values.
+#[derive(Debug, Clone, PartialEq, thiserror::Error)]
+pub enum TimeError {
+    #[error("cannot parse `{0}` as a {1} value")]
+    Parse(String, &'static str),
+    #[error("invalid sample rate {0}")]
+    SampleRate(u32),
+    #[error("invalid tempo {0}")]
+    Tempo(f64),
+    #[error("invalid meter {0}/{1}")]
+    Meter(u32, u32),
+}
+
+/// Sample rates supported by sessions (Pro Tools offers 44.1 k – 192 k; we accept 8 k – 768 k).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub struct SampleRate(u32);
+
+impl SampleRate {
+    pub const HZ_44100: SampleRate = SampleRate(44_100);
+    pub const HZ_48000: SampleRate = SampleRate(48_000);
+    pub const COMMON: [u32; 8] = [44_100, 48_000, 88_200, 96_000, 176_400, 192_000, 352_800, 384_000];
+
+    pub fn new(hz: u32) -> Result<Self, TimeError> {
+        if (8_000..=768_000).contains(&hz) { Ok(SampleRate(hz)) } else { Err(TimeError::SampleRate(hz)) }
+    }
+    pub fn hz(self) -> u32 {
+        self.0
+    }
+    pub fn as_f64(self) -> f64 {
+        f64::from(self.0)
+    }
+    /// Samples → seconds.
+    pub fn seconds(self, s: Samples) -> f64 {
+        s as f64 / self.as_f64()
+    }
+    /// Seconds → samples, rounded to nearest and saturated.
+    pub fn samples(self, seconds: f64) -> Samples {
+        to_samples(seconds * self.as_f64())
+    }
+}
+
+impl Default for SampleRate {
+    fn default() -> Self {
+        SampleRate::HZ_48000
+    }
+}
+
+/// Round a float sample count to `i64`, mapping NaN to 0 and saturating infinities.
+pub fn to_samples(v: f64) -> Samples {
+    if v.is_nan() {
+        0
+    } else if v >= i64::MAX as f64 {
+        i64::MAX
+    } else if v <= i64::MIN as f64 {
+        i64::MIN
+    } else {
+        v.round() as i64
+    }
+}
+
+/// A half-open sample range `[start, end)`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub struct Range {
+    pub start: Samples,
+    pub end: Samples,
+}
+
+impl Range {
+    pub fn new(a: Samples, b: Samples) -> Self {
+        if a <= b { Range { start: a, end: b } } else { Range { start: b, end: a } }
+    }
+    pub fn point(at: Samples) -> Self {
+        Range { start: at, end: at }
+    }
+    pub fn len(&self) -> Samples {
+        self.end.saturating_sub(self.start)
+    }
+    pub fn is_empty(&self) -> bool {
+        self.end <= self.start
+    }
+    pub fn contains(&self, s: Samples) -> bool {
+        s >= self.start && s < self.end
+    }
+    pub fn overlaps(&self, o: &Range) -> bool {
+        self.start < o.end && o.start < self.end
+    }
+    pub fn intersect(&self, o: &Range) -> Option<Range> {
+        let s = self.start.max(o.start);
+        let e = self.end.min(o.end);
+        (s < e).then_some(Range { start: s, end: e })
+    }
+    pub fn shifted(&self, by: Samples) -> Range {
+        Range { start: self.start.saturating_add(by), end: self.end.saturating_add(by) }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sample_rate_bounds() {
+        assert!(SampleRate::new(48_000).is_ok());
+        assert!(SampleRate::new(0).is_err());
+        assert!(SampleRate::new(10_000_000).is_err());
+    }
+
+    #[test]
+    fn seconds_round_trip() {
+        let sr = SampleRate::HZ_44100;
+        assert_eq!(sr.samples(1.0), 44_100);
+        assert!((sr.seconds(22_050) - 0.5).abs() < 1e-12);
+    }
+
+    #[test]
+    fn to_samples_is_total() {
+        assert_eq!(to_samples(f64::NAN), 0);
+        assert_eq!(to_samples(f64::INFINITY), i64::MAX);
+        assert_eq!(to_samples(f64::NEG_INFINITY), i64::MIN);
+    }
+
+    #[test]
+    fn range_ops() {
+        let a = Range::new(10, 0);
+        assert_eq!(a, Range { start: 0, end: 10 });
+        assert_eq!(a.intersect(&Range::new(5, 20)), Some(Range::new(5, 10)));
+        assert_eq!(a.intersect(&Range::new(10, 20)), None);
+        assert!(a.contains(9) && !a.contains(10));
+    }
+}

crates/time/src/soundcraft/tempo.rs

@@ -0,0 +1,622 @@
+//! Tempo and meter maps: the conversion between musical time (ticks) and samples.
+
+use super::{MAX_POSITION, SampleRate, Samples, TimeError, to_samples};
+
+/// Ticks per quarter note (Pro Tools' resolution).
+pub const TICKS_PER_QUARTER: i64 = 960;
+
+/// A tempo change at a tick position. `bpm` is quarter notes per minute.
+#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct TempoEvent {
+    pub tick: i64,
+    pub bpm: f64,
+}
+
+/// A meter (time signature) change at a tick position, which must fall on a bar line.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct MeterEvent {
+    pub tick: i64,
+    pub numerator: u32,
+    pub denominator: u32,
+}
+
+impl MeterEvent {
+    pub fn ticks_per_beat(&self) -> i64 {
+        let d = i64::from(self.denominator.max(1));
+        (TICKS_PER_QUARTER * 4 / d).max(1)
+    }
+    pub fn ticks_per_bar(&self) -> i64 {
+        self.ticks_per_beat().saturating_mul(i64::from(self.numerator.max(1)))
+    }
+}
+
+/// A musical position: 1-based bar and beat plus ticks within the beat.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct BarBeat {
+    pub bar: i64,
+    pub beat: i64,
+    pub tick: i64,
+}
+
+/// Tempo and meter changes for a session. Always has at least one of each, at tick 0.
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+#[serde(from = "TempoMapData")]
+pub struct TempoMap {
+    tempos: Vec<TempoEvent>,
+    meters: Vec<MeterEvent>,
+    /// For each tempo event, the elapsed time at its tick in quarter-note minutes (ticks / bpm,
+    /// summed over the earlier segments). Lets tick/sample conversions binary-search the segment
+    /// instead of walking every earlier tempo change, so converting many positions against a large
+    /// tempo map stays O(log n) each. Rebuilt whenever `tempos` changes.
+    #[serde(skip)]
+    elapsed: Vec<f64>,
+}
+
+/// The serialized form of [`TempoMap`], without the derived lookup table.
+#[derive(serde::Deserialize)]
+struct TempoMapData {
+    tempos: Vec<TempoEvent>,
+    meters: Vec<MeterEvent>,
+}
+
+impl From<TempoMapData> for TempoMap {
+    fn from(d: TempoMapData) -> Self {
+        TempoMap::from_parts(d.tempos, d.meters)
+    }
+}
+
+impl Default for TempoMap {
+    fn default() -> Self {
+        TempoMap::from_parts(vec![TempoEvent { tick: 0, bpm: 120.0 }], vec![MeterEvent { tick: 0, numerator: 4, denominator: 4 }])
+    }
+}
+
+fn valid_bpm(bpm: f64) -> Result<f64, TimeError> {
+    if bpm.is_finite() && (5.0..=1000.0).contains(&bpm) { Ok(bpm) } else { Err(TimeError::Tempo(bpm)) }
+}
+
+fn valid_meter(numerator: u32, denominator: u32) -> bool {
+    (1..=64).contains(&numerator) && [1, 2, 4, 8, 16, 32, 64].contains(&denominator)
+}
+
+impl TempoMap {
+    fn from_parts(tempos: Vec<TempoEvent>, meters: Vec<MeterEvent>) -> Self {
+        let mut m = TempoMap { tempos, meters, elapsed: Vec::new() };
+        m.reindex();
+        m
+    }
+
+    /// Rebuild `elapsed` from `tempos`. The first segment runs from tick 0 at the first tempo.
+    fn reindex(&mut self) {
+        let mut elapsed = Vec::with_capacity(self.tempos.len());
+        let mut acc = 0.0;
+        let mut seg_tick = 0i64;
+        let mut bpm = self.tempos.first().map_or(120.0, |e| e.bpm);
+        for (i, e) in self.tempos.iter().enumerate() {
+            if i > 0 {
+                // Saturating: a file's ticks are indexed before `sanitize` orders them.
+                acc += e.tick.saturating_sub(seg_tick) as f64 / bpm;
+                seg_tick = e.tick;
+                bpm = e.bpm;
+            }
+            elapsed.push(acc);
+        }
+        self.elapsed = elapsed;
+    }
+
+    /// Samples per quarter-note minute (the unit of `elapsed`) at `sr`.
+    fn samples_per_elapsed(sr: SampleRate) -> f64 {
+        sr.as_f64() * 60.0 / TICKS_PER_QUARTER as f64
+    }
+
+    /// The tempo segment `i` (an index into `tempos`, 0 when it is empty): its start tick (0 for
+    /// the first), bpm and elapsed time at its start.
+    fn segment(&self, i: usize) -> (i64, f64, f64) {
+        let bpm = self.tempos.get(i).or(self.tempos.first()).map_or(120.0, |e| e.bpm);
+        let tick = if i == 0 { 0 } else { self.tempos.get(i).map_or(0, |e| e.tick) };
+        (tick, bpm, self.elapsed.get(i).copied().unwrap_or(0.0))
+    }
+
+    pub fn new(bpm: f64, numerator: u32, denominator: u32) -> Result<Self, TimeError> {
+        let mut m = TempoMap::default();
+        m.set_tempo(0, bpm)?;
+        m.set_meter(0, numerator, denominator)?;
+        Ok(m)
+    }
+
+    pub fn tempos(&self) -> &[TempoEvent] {
+        &self.tempos
+    }
+    pub fn meters(&self) -> &[MeterEvent] {
+        &self.meters
+    }
+
+    /// Repair a map read from a file: only valid tempos and meters within `0..=MAX_POSITION` ticks, in
+    /// tick order, with one of each at tick 0.
+    pub fn sanitize(&mut self) {
+        self.tempos.retain(|e| (0..=MAX_POSITION).contains(&e.tick) && valid_bpm(e.bpm).is_ok());
+        self.tempos.sort_by_key(|e| e.tick);
+        self.tempos.dedup_by_key(|e| e.tick);
+        if self.tempos.first().is_none_or(|e| e.tick > 0) {
+            let bpm = self.tempos.first().map_or(120.0, |e| e.bpm);
+            self.tempos.insert(0, TempoEvent { tick: 0, bpm });
+        }
+        self.meters.retain(|m| (0..=MAX_POSITION).contains(&m.tick) && valid_meter(m.numerator, m.denominator));
+        self.meters.sort_by_key(|m| m.tick);
+        self.meters.dedup_by_key(|m| m.tick);
+        if self.meters.first().is_none_or(|m| m.tick > 0) {
+            let (numerator, denominator) = self.meters.first().map_or((4, 4), |m| (m.numerator, m.denominator));
+            self.meters.insert(0, MeterEvent { tick: 0, numerator, denominator });
+        }
+        self.reindex();
+    }
+
+    /// Insert or replace the tempo at `tick`.
+    pub fn set_tempo(&mut self, tick: i64, bpm: f64) -> Result<(), TimeError> {
+        let bpm = valid_bpm(bpm)?;
+        let tick = tick.max(0);
+        match self.tempos.binary_search_by(|e| e.tick.cmp(&tick)) {
+            Ok(i) => {
+                if let Some(e) = self.tempos.get_mut(i) {
+                    e.bpm = bpm;
+                }
+            }
+            Err(i) => self.tempos.insert(i, TempoEvent { tick, bpm }),
+        }
+        self.reindex();
+        Ok(())
+    }
+
+    /// Remove a tempo event (the one at tick 0 is kept).
+    pub fn remove_tempo(&mut self, tick: i64) -> bool {
+        if tick == 0 {
+            return false;
+        }
+        let before = self.tempos.len();
+        self.tempos.retain(|e| e.tick != tick);
+        self.reindex();
+        before != self.tempos.len()
+    }
+
+    /// Insert or replace the meter at `tick` (snapped to the bar line at or before it).
+    /// Later meter changes keep their bar numbers, so they stay on bar lines.
+    pub fn set_meter(&mut self, tick: i64, numerator: u32, denominator: u32) -> Result<(), TimeError> {
+        if !valid_meter(numerator, denominator) {
+            return Err(TimeError::Meter(numerator, denominator));
+        }
+        let tick = if tick <= 0 { 0 } else { self.bar_start_tick(self.bar_beat_at_tick(tick).bar) };
+        let later = self.take_meters_after(tick);
+        self.put_meter(MeterEvent { tick, numerator, denominator });
+        self.restore_meters_at_bars(later);
+        Ok(())
+    }
+
+    /// Remove a meter event (the one at tick 0 is kept). Later meter changes keep their bar numbers.
+    pub fn remove_meter(&mut self, tick: i64) -> bool {
+        if tick == 0 || !self.meters.iter().any(|e| e.tick == tick) {
+            return false;
+        }
+        let later = self.take_meters_after(tick);
+        self.meters.retain(|e| e.tick != tick);
+        self.restore_meters_at_bars(later);
+        true
+    }
+
+    fn put_meter(&mut self, ev: MeterEvent) {
+        match self.meters.binary_search_by(|e| e.tick.cmp(&ev.tick)) {
+            Ok(i) => {
+                if let Some(e) = self.meters.get_mut(i) {
+                    *e = ev;
+                }
+            }
+            Err(i) => self.meters.insert(i, ev),
+        }
+    }
+
+    /// Remove the meters after `tick`, returning each with the bar it starts: the bar
+    /// [`Self::bar_beat_at_tick`] gives its tick, counted in one pass over the map rather than one
+    /// walk per meter, so a session with many meter changes edits in linear time.
+    fn take_meters_after(&mut self, tick: i64) -> Vec<(i64, MeterEvent)> {
+        let mut later = Vec::new();
+        let (mut bar, mut seg_tick) = (1i64, 0i64);
+        for (i, m) in self.meters.iter().enumerate() {
+            let tpb = m.ticks_per_bar();
+            if m.tick > tick {
+                later.push((bar.saturating_add(m.tick.saturating_sub(seg_tick) / tpb), *m));
+            }
+            if let Some(n) = self.meters.get(i + 1) {
+                bar = bar.saturating_add(ceil_div(n.tick.saturating_sub(seg_tick), tpb));
+                seg_tick = n.tick;
+            }
+        }
+        self.meters.retain(|e| e.tick <= tick);
+        later
+    }
+
+    /// The bar and tick of the last meter's segment, where [`Self::bar_start_tick`]'s walk ends.
+    fn last_segment(&self) -> (i64, i64) {
+        let (mut cur_bar, mut cur_tick) = (1i64, 0i64);
+        for (i, m) in self.meters.iter().enumerate() {
+            if let Some(n) = self.meters.get(i + 1) {
+                cur_bar = cur_bar.saturating_add(ceil_div(n.tick.saturating_sub(cur_tick), m.ticks_per_bar()));
+                cur_tick = n.tick;
+            }
+        }
+        (cur_bar, cur_tick)
+    }
+
+    /// Put meters back at the start of their bars under the current earlier meters, in bar order.
+    /// Each lands at or past the last meter, so the walk to its bar resumes from there; a bar
+    /// before it (meters off their bar lines) takes the full walk.
+    fn restore_meters_at_bars(&mut self, later: Vec<(i64, MeterEvent)>) {
+        let (mut cur_bar, mut cur_tick) = self.last_segment();
+        for (bar, ev) in later {
+            let tick = if bar >= cur_bar {
+                let tpb = self.meters.last().map_or(MeterEvent { tick: 0, numerator: 4, denominator: 4 }, |m| *m).ticks_per_bar();
+                cur_tick.saturating_add(bar.saturating_sub(cur_bar).saturating_mul(tpb))
+            } else {
+                self.bar_start_tick(bar)
+            };
+            self.put_meter(MeterEvent { tick, ..ev });
+            (cur_bar, cur_tick) = if bar >= cur_bar { (bar, tick) } else { self.last_segment() };
+        }
+    }
+
+    /// Tempo in effect at `tick`.
+    pub fn tempo_at_tick(&self, tick: i64) -> f64 {
+        let mut bpm = self.tempos.first().map_or(120.0, |e| e.bpm);
+        for e in &self.tempos {
+            if e.tick <= tick {
+                bpm = e.bpm;
+            } else {
+                break;
+            }
+        }
+        bpm
+    }
+
+    /// Meter in effect at `tick`.
+    pub fn meter_at_tick(&self, tick: i64) -> MeterEvent {
+        let mut m = self.meters.first().copied().unwrap_or(MeterEvent { tick: 0, numerator: 4, denominator: 4 });
+        for e in &self.meters {
+            if e.tick <= tick {
+                m = *e;
+            } else {
+                break;
+            }
+        }
+        m
+    }
+
+    fn samples_per_tick(bpm: f64, sr: SampleRate) -> f64 {
+        sr.as_f64() * 60.0 / (bpm * TICKS_PER_QUARTER as f64)
+    }
+
+    /// Ticks → samples (exact for constant-tempo segments).
+    pub fn tick_to_samples(&self, tick: i64, sr: SampleRate) -> Samples {
+        to_samples(self.tick_to_samples_f(tick, sr))
+    }
+
+    fn tick_to_samples_f(&self, tick: i64, sr: SampleRate) -> f64 {
+        // Tempo events after the first that start before `tick` (the segments it has passed).
+        let passed = self.tempos.get(1..).map_or(0, |rest| rest.partition_point(|e| e.tick < tick));
+        let (seg_tick, bpm, elapsed) = self.segment(passed);
+        elapsed * Self::samples_per_elapsed(sr) + (tick - seg_tick) as f64 * Self::samples_per_tick(bpm, sr)
+    }
+
+    /// Samples → ticks (fractional).
+    pub fn samples_to_ticks_f(&self, s: Samples, sr: SampleRate) -> f64 {
+        let s = s as f64;
+        let scale = Self::samples_per_elapsed(sr);
+        // Tempo events after the first that start at or before `s`.
+        let passed = self.elapsed.get(1..).map_or(0, |rest| rest.partition_point(|e| e * scale <= s));
+        let (seg_tick, bpm, elapsed) = self.segment(passed);
+        seg_tick as f64 + (s - elapsed * scale) / Self::samples_per_tick(bpm, sr)
+    }
+
+    pub fn samples_to_ticks(&self, s: Samples, sr: SampleRate) -> i64 {
+        to_samples(self.samples_to_ticks_f(s, sr))
+    }
+
+    /// Tick of the first beat of `bar` (1-based; bars before 1 extend the first meter backwards).
+    pub fn bar_start_tick(&self, bar: i64) -> i64 {
+        let mut cur_bar = 1i64;
+        let mut cur_tick = 0i64;
+        let first = self.meter_at_tick(0);
+        if bar < 1 {
+            return bar.saturating_sub(1).saturating_mul(first.ticks_per_bar());
+        }
+        for (i, m) in self.meters.iter().enumerate() {
+            let next_tick = self.meters.get(i + 1).map(|n| n.tick);
+            let tpb = m.ticks_per_bar();
+            let bars_in_seg = next_tick.map(|nt| ceil_div(nt.saturating_sub(cur_tick), tpb));
+            match bars_in_seg {
+                Some(n) if bar >= cur_bar.saturating_add(n) => {
+                    cur_bar = cur_bar.saturating_add(n);
+                    cur_tick = next_tick.unwrap_or(cur_tick);
+                }
+                _ => return cur_tick.saturating_add((bar - cur_bar).saturating_mul(tpb)),
+            }
+        }
+        cur_tick
+    }
+
+    /// Bar|beat|tick at `tick`.
+    pub fn bar_beat_at_tick(&self, tick: i64) -> BarBeat {
+        let first = self.meter_at_tick(0);
+        if tick < 0 {
+            let tpb = first.ticks_per_bar();
+            let abs = tick.unsigned_abs();
+            let tpb_u = tpb.unsigned_abs();
+            let bars_back_u = abs / tpb_u + u64::from(!abs.is_multiple_of(tpb_u));
+            let bars_back = i64::try_from(bars_back_u).unwrap_or(i64::MAX);
+            // Offset of `tick` inside its bar, without negating `i64::MIN`.
+            let within = ((tpb_u - abs % tpb_u) % tpb_u) as i64;
+            let beat_t = first.ticks_per_beat();
+            return BarBeat { bar: 1 - bars_back, beat: within / beat_t + 1, tick: within % beat_t };
+        }
+        let mut bar = 1i64;
+        let mut seg_tick = 0i64;
+        for (i, m) in self.meters.iter().enumerate() {
+            let tpb = m.ticks_per_bar();
+            if let Some(n) = self.meters.get(i + 1)
+                && tick >= n.tick
+            {
+                bar = bar.saturating_add(ceil_div(n.tick.saturating_sub(seg_tick), tpb));
+                seg_tick = n.tick;
+                continue;
+            }
+            let rel = tick - seg_tick;
+            let bars = rel / tpb;
+            let within = rel % tpb;
+            let beat_t = m.ticks_per_beat();
+            return BarBeat { bar: bar + bars, beat: within / beat_t + 1, tick: within % beat_t };
+        }
+        BarBeat { bar, beat: 1, tick: 0 }
+    }
+
+    /// Bar|beat|tick → tick.
+    pub fn tick_at_bar_beat(&self, bb: BarBeat) -> i64 {
+        let start = self.bar_start_tick(bb.bar);
+        let m = self.meter_at_tick(start);
+        start.saturating_add(bb.beat.saturating_sub(1).max(0).saturating_mul(m.ticks_per_beat())).saturating_add(bb.tick)
+    }
+
+    pub fn bar_beat_at(&self, s: Samples, sr: SampleRate) -> BarBeat {
+        self.bar_beat_at_tick(self.samples_to_ticks(s, sr))
+    }
+
+    pub fn samples_at_bar_beat(&self, bb: BarBeat, sr: SampleRate) -> Samples {
+        self.tick_to_samples(self.tick_at_bar_beat(bb), sr)
+    }
+
+    /// Scale every tempo by `factor` (Tempo Operations › Scale).
+    pub fn scale_tempos(&mut self, factor: f64) -> Result<(), TimeError> {
+        let mut out = self.tempos.clone();
+        for e in &mut out {
+            e.bpm = valid_bpm(e.bpm * factor)?;
+        }
+        self.tempos = out;
+        self.reindex();
+        Ok(())
+    }
+}
+
+/// Ceiling division for a non-negative `num` and positive `den`, without overflow.
+fn ceil_div(num: i64, den: i64) -> i64 {
+    num / den + i64::from(num % den != 0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_map_is_120_4_4() {
+        let m = TempoMap::default();
+        let sr = SampleRate::HZ_48000;
+        // One bar of 4/4 at 120 bpm = 2 seconds.
+        assert_eq!(m.samples_at_bar_beat(BarBeat { bar: 2, beat: 1, tick: 0 }, sr), 96_000);
+        assert_eq!(m.bar_beat_at(96_000, sr), BarBeat { bar: 2, beat: 1, tick: 0 });
+        assert_eq!(m.bar_beat_at(24_000, sr), BarBeat { bar: 1, beat: 2, tick: 0 });
+    }
+
+    #[test]
+    fn meter_near_max_tick_does_not_overflow() {
+        let mut m = TempoMap::default();
+        m.set_meter(i64::MAX, 7, 8).unwrap();
+        let bb = m.bar_beat_at_tick(i64::MAX);
+        assert!(bb.bar > 1);
+        assert!(m.bar_start_tick(bb.bar) > 0);
+        assert!(m.bar_start_tick(i64::MAX) > 0);
+    }
+
+    #[test]
+    fn minimum_bar_saturates_instead_of_overflowing() {
+        let m = TempoMap::default();
+        assert_eq!(m.bar_start_tick(i64::MIN), i64::MIN);
+        assert_eq!(m.bar_start_tick(0), -TICKS_PER_QUARTER * 4);
+    }
+
+    #[test]
+    fn minimum_beat_is_clamped_without_overflow() {
+        let m = TempoMap::default();
+        assert_eq!(m.tick_at_bar_beat(BarBeat { bar: 1, beat: i64::MIN, tick: 0 }), 0);
+    }
+
+    #[test]
+    fn bar_beat_at_min_tick_does_not_overflow() {
+        let m = TempoMap::default();
+        let bb = m.bar_beat_at_tick(i64::MIN);
+        assert!(bb.bar < 1);
+        assert!(bb.beat >= 1 && bb.tick >= 0);
+        assert_eq!(m.bar_beat_at_tick(-1).bar, 0);
+    }
+
+    #[test]
+    fn tempo_change_is_integrated() {
+        let mut m = TempoMap::default();
+        let sr = SampleRate::HZ_48000;
+        m.set_tempo(TICKS_PER_QUARTER * 4, 60.0).unwrap();
+        // Bar 1 at 120 = 96000 samples; bar 2 at 60 = 192000 samples.
+        assert_eq!(m.tick_to_samples(TICKS_PER_QUARTER * 8, sr), 96_000 + 192_000);
+        assert_eq!(m.samples_to_ticks(96_000 + 192_000, sr), TICKS_PER_QUARTER * 8);
+    }
+
+    #[test]
+    fn meter_change_counts_bars() {
+        let mut m = TempoMap::default();
+        // 2 bars of 4/4 then 3/4.
+        m.set_meter(TICKS_PER_QUARTER * 8, 3, 4).unwrap();
+        assert_eq!(m.bar_beat_at_tick(TICKS_PER_QUARTER * 8), BarBeat { bar: 3, beat: 1, tick: 0 });
+        assert_eq!(m.bar_beat_at_tick(TICKS_PER_QUARTER * 11), BarBeat { bar: 4, beat: 1, tick: 0 });
+        assert_eq!(m.bar_start_tick(4), TICKS_PER_QUARTER * 11);
+        let bb = BarBeat { bar: 4, beat: 2, tick: 10 };
+        assert_eq!(m.bar_beat_at_tick(m.tick_at_bar_beat(bb)), bb);
+    }
+
+    #[test]
+    fn editing_an_early_meter_keeps_later_bars_and_scales_linearly() {
+        // 200 000 meter changes, one per bar, built directly: a walk per meter would take
+        // minutes to edit here, and even to build through `set_meter`.
+        let mut m = TempoMap::new(120.0, 4, 4).unwrap();
+        let mut tick = 0;
+        for bar in 1..200_000i64 {
+            let numerator = 3 + (bar % 2) as u32;
+            tick += m.meters.last().map_or(0, MeterEvent::ticks_per_bar);
+            m.meters.push(MeterEvent { tick, numerator, denominator: 4 });
+        }
+        let sample = [1usize, 1_000, 199_998];
+        let bars = |m: &TempoMap| sample.map(|i| m.bar_beat_at_tick(m.meters[i].tick).bar);
+        assert_eq!(bars(&m), [2, 1_001, 199_999]);
+        m.set_meter(0, 7, 8).unwrap();
+        assert_eq!(bars(&m), [2, 1_001, 199_999], "later meters keep their bar numbers");
+        assert_eq!(m.meters.len(), 200_000);
+        assert!(m.meters.windows(2).all(|w| w[0].tick < w[1].tick));
+        assert!(m.remove_meter(m.meters[1].tick));
+        assert_eq!([1usize, 999, 199_997].map(|i| m.bar_beat_at_tick(m.meters[i].tick).bar), [3, 1_001, 199_999]);
+        // Meters off their bar lines (counted as bars 2 and 4) land where they always did: on
+        // bar 2 of the new meter, then two bars of their own later.
+        let mut off = TempoMap::new(120.0, 4, 4).unwrap();
+        off.meters.push(MeterEvent { tick: 100, numerator: 3, denominator: 4 });
+        off.meters.push(MeterEvent { tick: 5_000, numerator: 5, denominator: 4 });
+        off.set_meter(0, 2, 4).unwrap();
+        let placed: Vec<(i64, u32)> = off.meters.iter().map(|e| (e.tick, e.numerator)).collect();
+        assert_eq!(placed, vec![(0, 2), (2 * TICKS_PER_QUARTER, 3), (8 * TICKS_PER_QUARTER, 5)]);
+    }
+
+    #[test]
+    fn eighth_note_meters() {
+        let m = TempoMap::new(120.0, 6, 8).unwrap();
+        assert_eq!(m.bar_beat_at_tick(TICKS_PER_QUARTER * 3), BarBeat { bar: 2, beat: 1, tick: 0 });
+        assert_eq!(m.bar_beat_at_tick(TICKS_PER_QUARTER / 2), BarBeat { bar: 1, beat: 2, tick: 0 });
+    }
+
+    #[test]
+    fn sanitize_keeps_what_the_setters_accept() {
+        let tempo = |tick, bpm| TempoEvent { tick, bpm };
+        let meter = |tick, numerator, denominator| MeterEvent { tick, numerator, denominator };
+        let mut m = TempoMap::from_parts(
+            vec![tempo(960, 4e9), tempo(3840, 90.0), tempo(-5, 100.0), tempo(1920, 60.0), tempo(1920, 70.0)],
+            vec![meter(0, 0, 4), meter(3840, 3, 4)],
+        );
+        m.sanitize();
+        assert_eq!(m.tempos(), [tempo(0, 60.0), tempo(1920, 60.0), tempo(3840, 90.0)]);
+        assert_eq!(m.meters(), [meter(0, 3, 4), meter(3840, 3, 4)]);
+        let mut empty = TempoMap::from_parts(Vec::new(), Vec::new());
+        empty.sanitize();
+        assert_eq!(empty, TempoMap::default());
+    }
+
+    #[test]
+    fn sanitize_drops_events_beyond_the_position_range() {
+        let mut m = TempoMap::from_parts(
+            vec![TempoEvent { tick: 0, bpm: 120.0 }, TempoEvent { tick: i64::MAX, bpm: 90.0 }],
+            vec![MeterEvent { tick: 0, numerator: 4, denominator: 4 }, MeterEvent { tick: i64::MAX, numerator: 3, denominator: 4 }],
+        );
+        m.sanitize();
+        assert_eq!(m, TempoMap::default());
+        assert_eq!(m.bar_start_tick(2), TICKS_PER_QUARTER * 4);
+    }
+
+    #[test]
+    fn rejects_bad_values() {
+        let mut m = TempoMap::default();
+        assert!(m.set_tempo(0, f64::NAN).is_err());
+        assert!(m.set_tempo(0, 0.0).is_err());
+        assert!(m.set_meter(0, 0, 4).is_err());
+        assert!(m.set_meter(0, 4, 3).is_err());
+        assert!(!m.remove_tempo(0));
+    }
+
+    #[test]
+    fn negative_positions() {
+        let m = TempoMap::default();
+        assert_eq!(m.bar_beat_at_tick(-TICKS_PER_QUARTER * 4), BarBeat { bar: 0, beat: 1, tick: 0 });
+        assert_eq!(m.bar_beat_at_tick(-TICKS_PER_QUARTER), BarBeat { bar: 0, beat: 4, tick: 0 });
+    }
+
+    /// The segment walk the indexed conversions replaced, kept as the reference they must match.
+    fn linear_tick_to_samples(m: &TempoMap, tick: i64, sr: SampleRate) -> i64 {
+        let mut acc = 0.0;
+        let mut seg_tick = 0i64;
+        let mut bpm = m.tempos[0].bpm;
+        for e in m.tempos.iter().skip(1) {
+            if e.tick >= tick {
+                break;
+            }
+            acc += (e.tick - seg_tick) as f64 * TempoMap::samples_per_tick(bpm, sr);
+            seg_tick = e.tick;
+            bpm = e.bpm;
+        }
+        to_samples(acc + (tick - seg_tick) as f64 * TempoMap::samples_per_tick(bpm, sr))
+    }
+
+    #[test]
+    fn indexed_conversions_match_the_segment_walk() {
+        let sr = SampleRate::HZ_48000;
+        let mut m = TempoMap::default();
+        for i in 1..200i64 {
+            m.set_tempo(i * 487, 40.0 + ((i * 37) % 300) as f64).unwrap();
+        }
+        assert!(m.remove_tempo(487 * 50));
+        for tick in (-1000..200 * 487 + 5000).step_by(113) {
+            let s = m.tick_to_samples(tick, sr);
+            assert_eq!(s, linear_tick_to_samples(&m, tick, sr), "tick {tick}");
+            assert!((m.samples_to_ticks(s, sr) - tick).abs() <= 1, "tick {tick}");
+        }
+        let json = serde_json::to_string(&m).unwrap();
+        assert!(!json.contains("elapsed"));
+        let back: TempoMap = serde_json::from_str(&json).unwrap();
+        assert_eq!(back, m);
+        assert_eq!(back.tick_to_samples(150 * 487 + 3, sr), m.tick_to_samples(150 * 487 + 3, sr));
+    }
+
+    #[test]
+    fn a_file_with_wild_ticks_is_indexed_without_overflow() {
+        let json = r#"{"tempos":[{"tick":0,"bpm":120.0},{"tick":-9223372036854775808,"bpm":100.0},{"tick":9223372036854775807,"bpm":90.0}],"meters":[{"tick":0,"numerator":4,"denominator":4}]}"#;
+        let mut m: TempoMap = serde_json::from_str(json).unwrap();
+        m.sanitize();
+        assert_eq!(m.tempos().first().map(|e| e.tick), Some(0));
+        assert_eq!(m.elapsed.len(), m.tempos().len());
+    }
+
+    #[test]
+    fn conversions_against_a_large_tempo_map_stay_fast() {
+        // 200k tempo changes, then 200k conversions each way: quadratic if every conversion walks
+        // the earlier segments, well under a second when it binary-searches them.
+        let sr = SampleRate::HZ_48000;
+        let n = 200_000i64;
+        let tempos = (0..n).map(|i| TempoEvent { tick: i * 10, bpm: 60.0 + (i % 7) as f64 }).collect();
+        let mut m = TempoMap::from_parts(tempos, vec![MeterEvent { tick: 0, numerator: 4, denominator: 4 }]);
+        m.sanitize();
+        let start = std::time::Instant::now();
+        let mut sum = 0i64;
+        for i in 0..n {
+            let s = m.tick_to_samples(i * 10 + 5, sr);
+            sum = sum.wrapping_add(s).wrapping_add(m.samples_to_ticks(s, sr));
+        }
+        assert!(sum != 0);
+        assert!(start.elapsed() < std::time::Duration::from_secs(5), "{:?}", start.elapsed());
+    }
+}

crates/time/src/soundcraft/timecode.rs

@@ -0,0 +1,309 @@
+//! SMPTE timecode and Feet+Frames.
+
+use super::{SampleRate, Samples, TimeError};
+
+/// Session timecode rates.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, serde::Serialize, serde::Deserialize)]
+pub enum FrameRate {
+    Fps23_976,
+    #[default]
+    Fps24,
+    Fps25,
+    Fps29_97,
+    Fps29_97Drop,
+    Fps30,
+    Fps47_952,
+    Fps48,
+    Fps50,
+    Fps59_94,
+    Fps59_94Drop,
+    Fps60,
+    Fps100,
+    Fps119_88,
+    Fps120,
+}
+
+impl FrameRate {
+    pub const ALL: [FrameRate; 15] = [
+        FrameRate::Fps23_976,
+        FrameRate::Fps24,
+        FrameRate::Fps25,
+        FrameRate::Fps29_97,
+        FrameRate::Fps29_97Drop,
+        FrameRate::Fps30,
+        FrameRate::Fps47_952,
+        FrameRate::Fps48,
+        FrameRate::Fps50,
+        FrameRate::Fps59_94,
+        FrameRate::Fps59_94Drop,
+        FrameRate::Fps60,
+        FrameRate::Fps100,
+        FrameRate::Fps119_88,
+        FrameRate::Fps120,
+    ];
+
+    /// Real frames per second as a rational (num, den).
+    pub fn rational(self) -> (i64, i64) {
+        match self {
+            FrameRate::Fps23_976 => (24_000, 1001),
+            FrameRate::Fps24 => (24, 1),
+            FrameRate::Fps25 => (25, 1),
+            FrameRate::Fps29_97 | FrameRate::Fps29_97Drop => (30_000, 1001),
+            FrameRate::Fps30 => (30, 1),
+            FrameRate::Fps47_952 => (48_000, 1001),
+            FrameRate::Fps48 => (48, 1),
+            FrameRate::Fps50 => (50, 1),
+            FrameRate::Fps59_94 | FrameRate::Fps59_94Drop => (60_000, 1001),
+            FrameRate::Fps60 => (60, 1),
+            FrameRate::Fps100 => (100, 1),
+            FrameRate::Fps119_88 => (120_000, 1001),
+            FrameRate::Fps120 => (120, 1),
+        }
+    }
+
+    /// Frames per labelled second (the counting base).
+    pub fn nominal(self) -> i64 {
+        let (n, d) = self.rational();
+        (n + d / 2) / d
+    }
+
+    pub fn is_drop(self) -> bool {
+        matches!(self, FrameRate::Fps29_97Drop | FrameRate::Fps59_94Drop)
+    }
+
+    pub fn label(self) -> &'static str {
+        match self {
+            FrameRate::Fps23_976 => "23.976",
+            FrameRate::Fps24 => "24",
+            FrameRate::Fps25 => "25",
+            FrameRate::Fps29_97 => "29.97",
+            FrameRate::Fps29_97Drop => "29.97 Drop",
+            FrameRate::Fps30 => "30",
+            FrameRate::Fps47_952 => "47.952",
+            FrameRate::Fps48 => "48",
+            FrameRate::Fps50 => "50",
+            FrameRate::Fps59_94 => "59.94",
+            FrameRate::Fps59_94Drop => "59.94 Drop",
+            FrameRate::Fps60 => "60",
+            FrameRate::Fps100 => "100",
+            FrameRate::Fps119_88 => "119.88",
+            FrameRate::Fps120 => "120",
+        }
+    }
+
+    /// Whole frame index at a sample position (floored).
+    pub fn frames_at(self, s: Samples, sr: SampleRate) -> i64 {
+        let (n, d) = self.rational();
+        let num = i128::from(s) * i128::from(n);
+        let den = i128::from(sr.hz()) * i128::from(d);
+        if den == 0 {
+            return 0;
+        }
+        i64::try_from(num.div_euclid(den)).unwrap_or(0)
+    }
+
+    /// Sample position of the start of frame `f`.
+    pub fn samples_at_frame(self, f: i64, sr: SampleRate) -> Samples {
+        let (n, d) = self.rational();
+        if n == 0 {
+            return 0;
+        }
+        // Round half away from zero so negative frames mirror positive ones.
+        let mag = (i128::from(f.unsigned_abs()) * i128::from(sr.hz()) * i128::from(d) + i128::from(n) / 2) / i128::from(n);
+        let v = if f < 0 { -mag } else { mag };
+        i64::try_from(v).unwrap_or(if v < 0 { i64::MIN } else { i64::MAX })
+    }
+
+    /// Samples per frame (fractional).
+    pub fn samples_per_frame(self, sr: SampleRate) -> f64 {
+        let (n, d) = self.rational();
+        sr.as_f64() * d as f64 / n as f64
+    }
+}
+
+/// A timecode label.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct Timecode {
+    pub negative: bool,
+    pub hours: i64,
+    pub minutes: i64,
+    pub seconds: i64,
+    pub frames: i64,
+}
+
+impl Timecode {
+    /// Label for an absolute frame count.
+    pub fn from_frames(frames: i64, rate: FrameRate) -> Timecode {
+        let negative = frames < 0;
+        // Drop-frame labels can exceed i64::MAX even when the frame count fits. Widen before
+        // taking the magnitude so i64::MIN is represented exactly too.
+        let mut f = i128::from(frames).abs();
+        let base = i128::from(rate.nominal().max(1));
+        if rate.is_drop() {
+            // Drop 2 (or 4) labels each minute except every tenth.
+            let drop = if base >= 60 { 4 } else { 2 };
+            let per_10min = base * 600 - drop * 9;
+            let per_min = base * 60 - drop;
+            let tens = f / per_10min;
+            let rem = f % per_10min;
+            let extra = if rem > drop { drop * 9 * tens + drop * ((rem - drop) / per_min) } else { drop * 9 * tens };
+            f += extra;
+        }
+        let frames_l = f % base;
+        let total_secs = f / base;
+        Timecode {
+            negative,
+            hours: i64::try_from(total_secs / 3600).unwrap_or(i64::MAX),
+            minutes: i64::try_from((total_secs / 60) % 60).unwrap_or(0),
+            seconds: i64::try_from(total_secs % 60).unwrap_or(0),
+            frames: i64::try_from(frames_l).unwrap_or(0),
+        }
+    }
+
+    /// Absolute frame count of this label.
+    pub fn to_frames(&self, rate: FrameRate) -> i64 {
+        let base = rate.nominal().max(1);
+        let total_min = i128::from(self.hours) * 60 + i128::from(self.minutes);
+        let mut f = (total_min * 60 + i128::from(self.seconds)) * i128::from(base) + i128::from(self.frames);
+        if rate.is_drop() {
+            let drop = if base >= 60 { 4 } else { 2 };
+            f -= drop * (total_min - total_min / 10);
+        }
+        let f = if self.negative { -f } else { f };
+        i64::try_from(f).unwrap_or(if f < 0 { i64::MIN } else { i64::MAX })
+    }
+
+    pub fn from_samples(s: Samples, rate: FrameRate, sr: SampleRate) -> Timecode {
+        Timecode::from_frames(rate.frames_at(s, sr), rate)
+    }
+
+    pub fn to_samples(&self, rate: FrameRate, sr: SampleRate) -> Samples {
+        rate.samples_at_frame(self.to_frames(rate), sr)
+    }
+
+    pub fn format(&self, rate: FrameRate) -> String {
+        let sep = if rate.is_drop() { ';' } else { ':' };
+        let sign = if self.negative { "-" } else { "" };
+        format!("{sign}{:02}:{:02}:{:02}{sep}{:02}", self.hours, self.minutes, self.seconds, self.frames)
+    }
+
+    /// Parse `HH:MM:SS:FF` (also `;` / `.` separators and fewer fields, right-aligned).
+    pub fn parse(text: &str) -> Result<Timecode, TimeError> {
+        let t = text.trim();
+        let (negative, t) = match t.strip_prefix('-') {
+            Some(r) => (true, r),
+            None => (false, t),
+        };
+        let parts: Vec<&str> = t.split([':', ';', '.']).collect();
+        if parts.is_empty() || parts.len() > 4 {
+            return Err(TimeError::Parse(text.to_string(), "timecode"));
+        }
+        let mut nums = [0i64; 4];
+        let offset = 4 - parts.len();
+        for (i, p) in parts.iter().enumerate() {
+            let v: i64 = p.trim().parse().map_err(|_| TimeError::Parse(text.to_string(), "timecode"))?;
+            if v < 0 {
+                return Err(TimeError::Parse(text.to_string(), "timecode"));
+            }
+            if let Some(slot) = nums.get_mut(offset + i) {
+                *slot = v;
+            }
+        }
+        Ok(Timecode { negative, hours: nums[0], minutes: nums[1], seconds: nums[2], frames: nums[3] })
+    }
+}
+
+/// Feet+Frames for 35 mm film (16 frames per foot), `start` frames in at sample 0.
+pub fn feet_frames(s: Samples, rate: FrameRate, sr: SampleRate, start: i64) -> (i64, i64) {
+    let f = rate.frames_at(s, sr).saturating_add(start);
+    (f.div_euclid(16), f.rem_euclid(16))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn non_drop_round_trip() {
+        let sr = SampleRate::HZ_48000;
+        let tc = Timecode::from_samples(48_000 * 3661, FrameRate::Fps25, sr);
+        assert_eq!(tc.format(FrameRate::Fps25), "01:01:01:00");
+        assert_eq!(tc.to_samples(FrameRate::Fps25, sr), 48_000 * 3661);
+    }
+
+    #[test]
+    fn negative_timecode_rounds_symmetrically() {
+        let sr = SampleRate::HZ_48000;
+        let tc = Timecode::parse("-00:00:01:00").unwrap();
+        assert_eq!(tc.to_samples(FrameRate::Fps25, sr), -48_000);
+        for r in [FrameRate::Fps25, FrameRate::Fps29_97, FrameRate::Fps29_97Drop, FrameRate::Fps23_976] {
+            for f in [1i64, 7, 25, 1799, 107_892] {
+                assert_eq!(r.samples_at_frame(-f, sr), -r.samples_at_frame(f, sr), "{r:?} frame {f}");
+            }
+        }
+    }
+
+    #[test]
+    fn drop_frame_labels() {
+        let r = FrameRate::Fps29_97Drop;
+        // Frame 1800 is the first frame of minute 1 → labelled 00:01:00;02.
+        assert_eq!(Timecode::from_frames(1800, r).format(r), "00:01:00;02");
+        assert_eq!(Timecode::from_frames(1799, r).format(r), "00:00:59;29");
+        // Minute 10 keeps its labels.
+        assert_eq!(Timecode::from_frames(17_982, r).format(r), "00:10:00;00");
+        for f in [0, 1, 1799, 1800, 1801, 17_981, 17_982, 107_892, 500_000] {
+            assert_eq!(Timecode::from_frames(f, r).to_frames(r), f, "frame {f}");
+        }
+    }
+
+    #[test]
+    fn huge_timecode_saturates_instead_of_overflowing() {
+        let sr = SampleRate::HZ_48000;
+        for r in [FrameRate::Fps30, FrameRate::Fps29_97Drop] {
+            let tc = Timecode::parse("9223372036854775807:00:00:00").unwrap();
+            assert_eq!(tc.to_samples(r, sr), i64::MAX);
+            let tc = Timecode::parse("-9223372036854775807:00:00:00").unwrap();
+            assert_eq!(tc.to_samples(r, sr), i64::MIN);
+        }
+        let tc = Timecode::parse("01:02:03:04").unwrap();
+        assert_eq!(tc.to_samples(FrameRate::Fps30, sr), 178_710_400);
+    }
+
+    #[test]
+    fn extreme_frame_counts_round_trip_at_every_rate() {
+        for rate in FrameRate::ALL {
+            for frames in [i64::MIN, i64::MIN + 1, -1, 0, 1, i64::MAX - 1, i64::MAX] {
+                let tc = Timecode::from_frames(frames, rate);
+                assert_eq!(tc.to_frames(rate), frames, "{rate:?}: {frames}");
+                assert_eq!(tc.negative, frames < 0);
+                assert!((0..60).contains(&tc.minutes));
+                assert!((0..60).contains(&tc.seconds));
+                assert!((0..rate.nominal()).contains(&tc.frames));
+                assert_eq!(Timecode::parse(&tc.format(rate)).unwrap(), tc);
+            }
+        }
+    }
+
+    #[test]
+    fn extreme_drop_frame_labels_do_not_overflow() {
+        for rate in [FrameRate::Fps29_97Drop, FrameRate::Fps59_94Drop] {
+            assert_eq!(Timecode::from_frames(i64::MAX, rate).to_frames(rate), i64::MAX);
+        }
+    }
+
+    #[test]
+    fn parse_variants() {
+        let tc = Timecode::parse("01:02:03:04").unwrap();
+        assert_eq!((tc.hours, tc.minutes, tc.seconds, tc.frames), (1, 2, 3, 4));
+        let tc = Timecode::parse("3:04").unwrap();
+        assert_eq!((tc.seconds, tc.frames), (3, 4));
+        assert!(Timecode::parse("a:b").is_err());
+        assert!(Timecode::parse("1:2:3:4:5").is_err());
+    }
+
+    #[test]
+    fn feet_and_frames() {
+        let sr = SampleRate::HZ_48000;
+        assert_eq!(feet_frames(48_000, FrameRate::Fps24, sr, 0), (1, 8));
+    }
+}