tek/crates/tek_core/src/time.rs

use crate::*;
use std::iter::Iterator;

pub const DEFAULT_PPQ: f64 = 96.0;

/// The unit of time, an atomic 64-bit float.
///
/// According to https://stackoverflow.com/a/873367, as per IEEE754,
/// every integer between 1 and 2^53 can be represented exactly.
/// This should mean that, even at 192kHz sampling rate, over 1 year of audio
/// can be clocked in microseconds with f64 without losing precision.
#[derive(Debug, Default)]
pub struct TimeUnit(AtomicF64);
impl TimeUnit {
    pub fn get (&self) -> f64 { self.0.load(Ordering::Relaxed) }
    pub fn set (&self, value: f64) { self.0.store(value, Ordering::Relaxed) }
}
/// Temporal resolutions: sample rate, tempo, MIDI pulses per quaver (beat)
#[derive(Debug, Clone)]
pub struct Timebase {
    /// Audio samples per second
    pub sr:  TimeUnit,
    /// MIDI beats per minute
    pub bpm: TimeUnit,
    /// MIDI ticks per beat
    pub ppq: TimeUnit,
}
/// A point in time in all time scales (microsecond, sample, MIDI pulse)
#[derive(Debug, Default, Clone)]
pub struct Instant {
    pub timebase: Arc<Timebase>,
    /// Current time in microseconds
    pub usec:   TimeUnit,
    /// Current time in audio samples
    pub sample: TimeUnit,
    /// Current time in MIDI pulses
    pub pulse:  TimeUnit,
}
impl From<f64>   for TimeUnit  { fn from (value: f64)   -> Self { Self(value.into()) } }
impl From<usize> for TimeUnit  { fn from (value: usize) -> Self { Self((value as f64).into()) } }
impl Into<f64>   for TimeUnit  { fn into (self) -> f64   { self.get() } }
impl Into<usize> for TimeUnit  { fn into (self) -> usize { self.get() as usize } }
impl Into<f64>   for &TimeUnit { fn into (self) -> f64   { self.get() } }
impl Into<usize> for &TimeUnit { fn into (self) -> usize { self.get() as usize } }
impl Clone for TimeUnit { fn clone (&self) -> Self { Self(self.get().into()) } }
macro_rules! impl_op {
    ($Op:ident, $method:ident, |$a:ident,$b:ident|{$impl:expr}) => {
        impl $Op<Self> for TimeUnit {
            type Output = Self; #[inline] fn $method (self, other: Self) -> Self::Output {
                let $a = self.get(); let $b = other.get(); Self($impl.into())
            }
        }
        impl $Op<usize> for TimeUnit {
            type Output = Self; #[inline] fn $method (self, other: usize) -> Self::Output {
                let $a = self.get(); let $b = other as f64; Self($impl.into())
            }
        }
        impl $Op<f64> for TimeUnit {
            type Output = Self; #[inline] fn $method (self, other: f64) -> Self::Output {
                let $a = self.get(); let $b = other; Self($impl.into())
            }
        }
    }
}
impl_op!(Add, add, |a, b|{a + b});
impl_op!(Sub, sub, |a, b|{a - b});
impl_op!(Mul, mul, |a, b|{a * b});
impl_op!(Div, div, |a, b|{a / b});
impl_op!(Rem, rem, |a, b|{a % b});
impl Timebase {
    /// Specify sample rate, BPM and PPQ
    pub fn new (s: impl Into<TimeUnit>, b: impl Into<TimeUnit>, p: impl Into<TimeUnit>) -> Self {
        Self { sr: s.into(), bpm: b.into(), ppq: p.into() }
    }
    /// Iterate over ticks between start and end.
    pub fn pulses_between_samples (&self, start: usize, end: usize) -> TicksIterator {
        TicksIterator { fpt: self.samples_per_pulse(), sample: start, start, end }
    }
}
impl Default for Timebase { fn default () -> Self { Self::new(48000f64, 150f64, DEFAULT_PPQ) } }
impl Instant {
    pub fn zero (timebase: &Arc<Timebase>) -> Self {
        Self { usec: 0.into(), sample: 0.into(), pulse: 0.into(), timebase: timebase.clone() }
    }
    pub fn from_usec (timebase: &Arc<Timebase>, usec: f64) -> Self {
        Self {
            usec:     usec.into(),
            sample:   timebase.usecs_to_sample(usec).into(),
            pulse:    timebase.usecs_to_pulse(usec).into(),
            timebase: timebase.clone(),
        }
    }
    pub fn from_sample (timebase: &Arc<Timebase>, sample: f64) -> Self {
        Self {
            sample:   sample.into(),
            usec:     timebase.samples_to_usec(sample).into(),
            pulse:    timebase.samples_to_pulse(sample).into(),
            timebase: timebase.clone(),
        }
    }
    pub fn from_pulse (timebase: &Arc<Timebase>, pulse: f64) -> Self {
        Self {
            pulse:    pulse.into(),
            sample:   timebase.pulses_to_sample(pulse).into(),
            usec:     timebase.pulses_to_usec(pulse).into(),
            timebase: timebase.clone(),
        }
    }
    pub fn update_from_usec (&self, usec: f64) {
        self.usec.set(usec);
        self.pulse.set(self.timebase.usecs_to_pulse(usec));
        self.sample.set(self.timebase.usecs_to_sample(usec));
    }
    pub fn update_from_sample (&self, sample: f64) {
        self.usec.set(self.timebase.samples_to_usec(sample));
        self.pulse.set(self.timebase.samples_to_pulse(sample));
        self.sample.set(sample);
    }
    pub fn update_from_pulse (&self, pulse: f64) {
        self.usec.set(self.timebase.pulses_to_usec(pulse));
        self.pulse.set(pulse);
        self.sample.set(self.timebase.pulses_to_sample(pulse));
    }
    pub fn format_beat (&self) -> String {
        self.format_beats(self.pulse().get())
    }
}
/// Iterator that emits subsequent ticks within a range.
pub struct TicksIterator { fpt: f64, sample: usize, start: usize, end: usize, }
impl Iterator for TicksIterator {
    type Item = (usize, usize);
    fn next (&mut self) -> Option<Self::Item> {
        loop {
            if self.sample > self.end { return None }
            let fpt    = self.fpt;
            let sample = self.sample as f64;
            let start  = self.start;
            let end    = self.end;
            self.sample += 1;
            //println!("{fpt} {sample} {start} {end}");
            let jitter = sample.rem_euclid(fpt); // ramps
            let next_jitter = (sample + 1.0).rem_euclid(fpt);
            if jitter > next_jitter { // at crossing:
                let time = (sample as usize) % (end as usize-start as usize);
                let tick = (sample / fpt) as usize;
                return Some((time, tick))
            }
        }
    }
}
/// Something that defines a sample rate in hertz (samples per second)
pub trait SampleRate {
    /// Get the sample rate
    fn sr (&self) -> &TimeUnit;
    /// Return the duration of a sample in microseconds (floating)
    #[inline] fn usec_per_sample (&self) -> f64 { 1_000_000f64 / self.sr().get() }
    /// Return the duration of a sample in microseconds (floating)
    #[inline] fn sample_per_usec (&self) -> f64 { self.sr().get() / 1_000_000f64 }
    /// Convert a number of samples to microseconds (floating)
    #[inline] fn samples_to_usec (&self, samples: f64) -> f64 { samples * self.usec_per_sample() }
    /// Convert a number of microseconds to samples (floating)
    #[inline] fn usecs_to_sample (&self, usecs:   f64) -> f64 { usecs   * self.sample_per_usec() }
}
impl SampleRate for Timebase { #[inline] fn sr (&self) -> &TimeUnit { &self.sr } }
impl SampleRate for Instant  { #[inline] fn sr (&self) -> &TimeUnit { self.timebase.sr() } }
/// Something that defines a tempo in BPM (beats per minute)
/// and a MIDI resolution in pulses per beat (PPQ, pulses per quaver)
pub trait MIDITime {
    /// Get the tempo
    fn bpm (&self) -> &TimeUnit;
    // Get the PPQ
    fn ppq (&self) -> &TimeUnit;
    /// Return the duration fo a beat in microseconds
    #[inline] fn usec_per_beat (&self) -> f64 { 60_000_000f64 / self.bpm().get() }
    /// Return the number of beats in a second
    #[inline] fn beat_per_second (&self) -> f64 { self.bpm().get() / 60_000_000f64 }
    /// Return the number of microseconds corresponding to a note of the given duration
    #[inline] fn note_to_usec (&self, (num, den): (f64, f64)) -> f64 {
        4.0 * self.usec_per_beat() * num / den
    }
    /// Return duration of a pulse in microseconds (BPM-dependent)
    #[inline] fn pulse_per_usec (&self) -> f64 { self.ppq().get() / self.usec_per_beat() }
    /// Return duration of a pulse in microseconds (BPM-dependent)
    #[inline] fn usec_per_pulse (&self) -> f64 { self.usec_per_beat() / self.ppq().get() }
    /// Return number of pulses to which a number of microseconds corresponds (BPM-dependent)
    #[inline] fn usecs_to_pulse (&self, usec: f64) -> f64 { usec * self.pulse_per_usec() }
    /// Convert a number of pulses to a sample number (SR- and BPM-dependent)
    #[inline] fn pulses_to_usec (&self, pulse: f64) -> f64 { pulse / self.usec_per_pulse() }
    /// Return number of pulses in a second (BPM-dependent)
    #[inline] fn pulses_per_second (&self) -> f64 { self.beat_per_second() * self.ppq().get() }
    /// Return fraction of a pulse to which a sample corresponds (SR- and BPM-dependent)
    #[inline] fn pulses_per_sample (&self) -> f64 where Self: SampleRate {
        self.usec_per_pulse() / self.usec_per_sample()
    }
    /// Return number of samples in a pulse (SR- and BPM-dependent)
    #[inline] fn samples_per_pulse (&self) -> f64 where Self: SampleRate {
        self.sr().get() / self.pulses_per_second()
    }
    /// Convert a number of pulses to a sample number (SR- and BPM-dependent)
    #[inline] fn pulses_to_sample (&self, p: f64) -> f64 where Self: SampleRate {
        self.pulses_per_sample() * p
    }
    /// Convert a number of samples to a pulse number (SR- and BPM-dependent)
    #[inline] fn samples_to_pulse (&self, s: f64) -> f64 where Self: SampleRate {
        s / self.pulses_per_sample()
    }
    /// Return the number of samples corresponding to a note of the given duration
    #[inline] fn note_to_samples (&self, note: (f64, f64)) -> f64 where Self: SampleRate {
        self.usec_to_sample(self.note_to_usec(note))
    }
    /// Return the number of samples corresponding to the given number of microseconds
    #[inline] fn usec_to_sample (&self, usec: f64) -> f64 where Self: SampleRate {
        usec * self.sr().get() / 1000f64
    }
    /// Return the quantized position of a moment in time given a step
    #[inline] fn quantize (&self, step: (f64, f64), time: f64) -> (f64, f64) {
        let step = self.note_to_usec(step);
        (time / step, time % step)
    }
    /// Quantize a collection of events
    #[inline] fn quantize_into <E: Iterator<Item=(f64, f64)> + Sized, T> (
        &self, step: (f64, f64), events: E
    ) -> Vec<(f64, f64)> {
        events.map(|(time, event)|(self.quantize(step, time).0, event)).collect()
    }
    /// Format a number of pulses into Beat.Bar.Pulse
    #[inline] fn format_beats (&self, pulse: f64) -> String {
        let pulse = pulse as usize;
        let ppq   = self.ppq().get() as usize;
        let (beats, pulses) = if ppq > 0 { (pulse / ppq, pulse % ppq) } else { (0, 0) };
        let bars  = ((beats / 4) + 1) as usize;
        let beats = ((beats % 4) + 1) as usize;
        format!("{bars}.{beats}.{pulses:02}")
    }
}
impl MIDITime for Timebase {
    #[inline] fn bpm (&self) -> &TimeUnit { &self.bpm }
    #[inline] fn ppq (&self) -> &TimeUnit { &self.ppq }
}
impl MIDITime for Instant {
    #[inline] fn bpm (&self) -> &TimeUnit { &self.timebase.bpm() }
    #[inline] fn ppq (&self) -> &TimeUnit { &self.timebase.ppq() }
}
/// Something that refers to a point in time in samples
pub trait SamplePosition { fn sample (&self) -> &TimeUnit; }
impl SamplePosition for Instant { #[inline] fn sample (&self) -> &TimeUnit { &self.sample } }
/// Something that refers to a point in time in MIDI pulses
pub trait PulsePosition { fn pulse (&self) -> &TimeUnit; }
impl PulsePosition for Instant { #[inline] fn pulse (&self) -> &TimeUnit { &self.pulse } }
/// Something that refers to a point in time in microseconds
pub trait UsecPosition {
    fn usec (&self) -> &TimeUnit;
    #[inline] fn format_current_usec (&self) -> String {
        let usecs: usize       = self.usec().get() as usize;
        let (seconds, msecs)   = (usecs / 1000000, usecs / 1000 % 1000);
        let (minutes, seconds) = (seconds / 60, seconds % 60);
        format!("{minutes}:{seconds:02}:{msecs:03}")
    }
}
impl UsecPosition for Instant { #[inline] fn usec (&self) -> &TimeUnit { &self.usec } }
/// Something that defines launch quantization
pub trait LaunchSync {
    fn sync (&self) -> &TimeUnit;
    #[inline] fn next_launch_pulse (&self) -> usize where Self: PulsePosition {
        let sync  = self.sync().get()  as usize;
        let pulse = self.pulse().get() as usize;
        if pulse % sync == 0 { pulse } else { (pulse / sync + 1) * sync }
    }
}
/// Something that defines note quantization
pub trait Quantize { fn quant (&self) -> &TimeUnit; }
/// (pulses, name), assuming 96 PPQ
pub const NOTE_DURATIONS: [(usize, &str);26] = [
    (1,    "1/384"),
    (2,    "1/192"),
    (3,    "1/128"),
    (4,    "1/96"),
    (6,    "1/64"),
    (8,    "1/48"),
    (12,   "1/32"),
    (16,   "1/24"),
    (24,   "1/16"),
    (32,   "1/12"),
    (48,   "1/8"),
    (64,   "1/6"),
    (96,   "1/4"),
    (128,  "1/3"),
    (192,  "1/2"),
    (256,  "2/3"),
    (384,  "1/1"),
    (512,  "4/3"),
    (576,  "3/2"),
    (768,  "2/1"),
    (1152, "3/1"),
    (1536, "4/1"),
    (2304, "6/1"),
    (3072, "8/1"),
    (3456, "9/1"),
    (6144, "16/1"),
];
/// Returns the next shorter length
pub fn prev_note_length (pulses: usize) -> usize {
    for i in 1..=16 { let length = NOTE_DURATIONS[16-i].0; if length < pulses { return length } }
    pulses
}
/// Returns the next longer length
pub fn next_note_length (pulses: usize) -> usize {
    for (length, _) in &NOTE_DURATIONS { if *length > pulses { return *length } }
    pulses
}
pub fn pulses_to_name (pulses: usize) -> &'static str {
    for (length, name) in &NOTE_DURATIONS { if *length == pulses { return name } }
    ""
}
#[cfg(test)]
mod test {
    use super::*;
    #[test]
    fn test_samples_to_ticks () {
        let ticks = Ticks(12.3).between_samples(0, 100).collect::<Vec<_>>();
        println!("{ticks:?}");
    }
}