vtome 0.2.5

//! When to show a frame, and what to do when it is late.
//!
//! Playback is a question of timing rather than of decoding: the decoder
//! produces pictures with presentation stamps, and something has to decide
//! which one belongs on screen right now. That decision is here, separated from
//! anything that draws, so it can be tested without a GPU and against a clock
//! that does not have to be real time.
//!
//! # Audio is the master, always
//!
//! When vtome runs next to `atome`, the audio clock leads and video follows. A
//! dropped frame is invisible at 24 fps; a resampled or stuttered audio buffer
//! is immediately audible. So playback runs against any [`MasterClock`] —
//! implement it over the audio engine's play position and video will chase it.
//!
//! # One timeline, many clips
//!
//! The engine keeps a single timeline, a [`SharedClock`]: atome's output clock
//! when there is audio (the `atome` feature implements [`MasterClock`] for
//! `atome::PlayClock`), a [`Monotonic`] one when there is not. Every clip
//! follows it through a [`Follower`] — its own play, pause, and seek, measured
//! on the shared timeline rather than on a clock of its own. Clips cannot
//! drift apart from each other or from the sound, because there is only one
//! thing for them to drift from.

use std::sync::Arc;
use std::time::{Duration, Instant};

/// Something that knows what time it is in a stream.
///
/// The audio engine implements this over its own play position, which is the
/// only clock in the system that is not allowed to drift.
pub trait MasterClock: Send + Sync {
    /// How far into the stream playback currently is.
    fn position(&self) -> Duration;

    /// Whether it is running. A paused master freezes video too.
    fn is_running(&self) -> bool {
        true
    }
}

/// A clock of vtome's own, driven by the machine's monotonic time.
///
/// The fallback when there is no audio to follow.
#[derive(Debug)]
pub struct Clock {
    /// Where playback was when it last started or was seeked.
    anchor_position: Duration,
    /// When that was, in monotonic time. `None` while paused.
    anchor_instant: Option<Instant>,
    rate: f64,
}

impl Default for Clock {
    fn default() -> Self {
        Clock::new()
    }
}

impl Clock {
    /// A clock at zero, paused.
    pub fn new() -> Self {
        Clock {
            anchor_position: Duration::ZERO,
            anchor_instant: None,
            rate: 1.0,
        }
    }

    /// Starts, or resumes, from wherever it is.
    pub fn play(&mut self) {
        if self.anchor_instant.is_none() {
            self.anchor_instant = Some(Instant::now());
        }
    }

    /// Stops, keeping the position.
    pub fn pause(&mut self) {
        if self.anchor_instant.is_some() {
            // Fold elapsed time into the anchor before dropping it, or the
            // pause would rewind to wherever the last seek was.
            self.anchor_position = self.position();
            self.anchor_instant = None;
        }
    }

    /// Whether it is running.
    pub fn is_running(&self) -> bool {
        self.anchor_instant.is_some()
    }

    /// Moves to a position. Keeps running if it was running.
    pub fn seek(&mut self, position: Duration) {
        self.anchor_position = position;

        if self.anchor_instant.is_some() {
            self.anchor_instant = Some(Instant::now());
        }
    }

    /// Playback speed. 1.0 is normal, 0.5 is half.
    ///
    /// Clamped to something sane: a rate of zero is what `pause` is for, and a
    /// negative one is not implemented — decoders run forwards.
    pub fn set_rate(&mut self, rate: f64) {
        // Fold in the time spent at the old rate before changing it.
        if self.anchor_instant.is_some() {
            self.anchor_position = self.position();
            self.anchor_instant = Some(Instant::now());
        }

        self.rate = rate.clamp(0.01, 16.0);
    }

    /// The current rate.
    pub fn rate(&self) -> f64 {
        self.rate
    }
}

impl MasterClock for Clock {
    fn position(&self) -> Duration {
        match self.anchor_instant {
            Some(started) => self.anchor_position + started.elapsed().mul_f64(self.rate),
            None => self.anchor_position,
        }
    }

    fn is_running(&self) -> bool {
        self.anchor_instant.is_some()
    }
}

/// A timeline every clip can hold: the engine's.
pub type SharedClock = Arc<dyn MasterClock>;

/// A master that runs from the moment it is made and never stops — the
/// engine's timeline when there is no audio to follow.
#[derive(Clone, Copy, Debug)]
pub struct Monotonic {
    started: Instant,
}

impl Monotonic {
    /// Starting now, at zero.
    pub fn new() -> Self {
        Monotonic {
            started: Instant::now(),
        }
    }

    /// Starting now, as a [`SharedClock`].
    pub fn shared() -> SharedClock {
        Arc::new(Monotonic::new())
    }
}

impl Default for Monotonic {
    fn default() -> Self {
        Monotonic::new()
    }
}

impl MasterClock for Monotonic {
    fn position(&self) -> Duration {
        self.started.elapsed()
    }
}

/// atome's output clock as a master: what the speakers are playing now, latency
/// included, so pictures land with the sound they belong to.
#[cfg(feature = "atome")]
impl MasterClock for atome::PlayClock {
    fn position(&self) -> Duration {
        atome::PlayClock::position(self)
    }

    fn is_running(&self) -> bool {
        atome::PlayClock::is_running(self)
    }
}

/// One clip's position, measured on a shared master.
///
/// Play, pause, and seek are the clip's own; the time between them is the
/// master's. Following a stopped master — an audio device that is paused or
/// gone — freezes the clip where it is, which is the only thing a picture
/// following a sound can sensibly do.
#[derive(Clone)]
pub struct Follower {
    master: SharedClock,
    /// Where the clip was when it last started, or was seeked while running.
    from: Duration,
    /// The master's position at that moment. `None` while paused.
    master_at: Option<Duration>,
}

impl std::fmt::Debug for Follower {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("Follower")
            .field("position", &self.position())
            .field("running", &self.master_at.is_some())
            .finish()
    }
}

impl Follower {
    /// Paused, at zero.
    pub fn new(master: SharedClock) -> Self {
        Follower {
            master,
            from: Duration::ZERO,
            master_at: None,
        }
    }

    /// Running, with the clip's zero at `master_position` on the master — in
    /// the past, so the clip is already some way in, or in the future, so it
    /// waits. See [`is_due`](Follower::is_due).
    pub fn starting_at(master: SharedClock, master_position: Duration) -> Self {
        Follower {
            master,
            from: Duration::ZERO,
            master_at: Some(master_position),
        }
    }

    /// The master this follows.
    pub fn master(&self) -> &SharedClock {
        &self.master
    }

    /// Starts, or resumes, from wherever the clip is.
    pub fn play(&mut self) {
        if self.master_at.is_none() {
            self.master_at = Some(self.master.position());
        }
    }

    /// Stops, keeping the position.
    pub fn pause(&mut self) {
        if self.master_at.is_some() {
            self.from = self.position();
            self.master_at = None;
        }
    }

    /// Moves to a position. Keeps running if it was running.
    pub fn seek(&mut self, position: Duration) {
        self.from = position;

        if self.master_at.is_some() {
            self.master_at = Some(self.master.position());
        }
    }

    /// Whether the clip itself is playing, whatever the master is doing.
    pub fn is_playing(&self) -> bool {
        self.master_at.is_some()
    }

    /// Whether the clip has reached its start: false only for a clip made
    /// with [`starting_at`](Follower::starting_at) a point the master has not
    /// got to yet.
    pub fn is_due(&self) -> bool {
        self.master_at
            .is_none_or(|at| self.master.position() >= at)
    }
}

impl MasterClock for Follower {
    fn position(&self) -> Duration {
        match self.master_at {
            Some(at) => self.from + self.master.position().saturating_sub(at),
            None => self.from,
        }
    }

    fn is_running(&self) -> bool {
        self.master_at.is_some() && self.master.is_running()
    }
}

/// What to do with a frame that is due at a given time.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Action {
    /// Draw it now.
    Present,
    /// Too early: wait this long and ask again. Not a sleep — a caller with a
    /// vsync to wait on has better things to block on.
    Wait(Duration),
    /// Too late to be worth drawing: throw it away and take the next one.
    ///
    /// The alternative is drawing every frame however late it is, which turns a
    /// brief stall into permanent lag.
    Drop,
}

/// The decision, and the count of how often it has gone each way.
///
/// Kept as a struct rather than a free function because the counters are what
/// makes a stuttering player diagnosable: dropped frames mean the decoder is
/// behind, repeats mean the display is faster than the content.
#[derive(Clone, Copy, Debug, Default)]
pub struct Pacing {
    /// How late a frame may be and still be worth drawing.
    tolerance: Duration,
    presented: u64,
    dropped: u64,
    repeated: u64,
}

impl Pacing {
    /// Half a frame interval of tolerance, which is the usual choice: a frame
    /// more than half an interval late would be replaced by the next one before
    /// anyone saw it.
    pub fn for_frame_rate(frames_per_second: f64) -> Self {
        let interval = if frames_per_second > 0.0 {
            Duration::from_secs_f64(1.0 / frames_per_second)
        } else {
            Duration::from_millis(40)
        };

        Pacing {
            tolerance: interval / 2,
            ..Pacing::default()
        }
    }

    /// A pacer with an explicit tolerance.
    pub fn with_tolerance(tolerance: Duration) -> Self {
        Pacing {
            tolerance,
            ..Pacing::default()
        }
    }

    /// What to do with a frame due at `frame_pts` when the master says `now`.
    pub fn decide(&mut self, frame_pts: Duration, now: Duration) -> Action {
        if frame_pts > now {
            let wait = frame_pts - now;

            // Within tolerance of due counts as due: waiting a millisecond to
            // be exactly on time misses the vsync it was aiming for.
            if wait <= self.tolerance {
                self.presented += 1;
                return Action::Present;
            }

            return Action::Wait(wait - self.tolerance);
        }

        let late = now - frame_pts;

        if late > self.tolerance {
            self.dropped += 1;
            return Action::Drop;
        }

        self.presented += 1;
        Action::Present
    }

    /// Records that the previous frame was shown again because no new one was
    /// ready.
    pub fn note_repeat(&mut self) {
        self.repeated += 1;
    }

    /// Presented, dropped, repeated.
    pub fn counts(&self) -> (u64, u64, u64) {
        (self.presented, self.dropped, self.repeated)
    }

    /// The share of frames that were dropped, for a health check that does not
    /// require the caller to do the arithmetic.
    pub fn drop_rate(&self) -> f64 {
        let total = self.presented + self.dropped;

        if total == 0 {
            return 0.0;
        }

        self.dropped as f64 / total as f64
    }

    /// Forgets the counters, without changing the tolerance.
    pub fn reset(&mut self) {
        self.presented = 0;
        self.dropped = 0;
        self.repeated = 0;
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A clock that says whatever the test wants, so pacing can be checked
    /// without waiting in real time.
    #[derive(Debug, Default)]
    struct FixedClock(Duration);

    impl MasterClock for FixedClock {
        fn position(&self) -> Duration {
            self.0
        }
    }

    #[test]
    fn a_new_clock_is_paused_at_zero() {
        let clock = Clock::new();

        assert_eq!(clock.position(), Duration::ZERO);
        assert!(!clock.is_running());
    }

    #[test]
    fn pausing_keeps_the_position_and_stops_it_advancing() {
        let mut clock = Clock::new();
        clock.seek(Duration::from_secs(5));
        clock.play();

        std::thread::sleep(Duration::from_millis(20));
        clock.pause();

        let paused_at = clock.position();
        assert!(paused_at >= Duration::from_secs(5));

        std::thread::sleep(Duration::from_millis(20));
        assert_eq!(clock.position(), paused_at, "a paused clock moved");
    }

    /// The bug this shape exists to prevent: pausing that rewinds to the last
    /// seek because elapsed time was never folded in.
    #[test]
    fn pausing_twice_does_not_rewind() {
        let mut clock = Clock::new();
        clock.play();
        std::thread::sleep(Duration::from_millis(20));

        clock.pause();
        let first = clock.position();
        clock.pause();

        assert_eq!(clock.position(), first);
    }

    #[test]
    fn rate_changes_do_not_lose_the_position() {
        let mut clock = Clock::new();
        clock.seek(Duration::from_secs(10));
        clock.play();
        std::thread::sleep(Duration::from_millis(10));

        clock.set_rate(2.0);
        assert!(clock.position() >= Duration::from_secs(10));
        assert_eq!(clock.rate(), 2.0);

        clock.set_rate(0.0);
        assert!(clock.rate() > 0.0, "zero rate is what pause is for");
    }

    #[test]
    fn a_frame_due_now_is_presented() {
        let mut pacing = Pacing::for_frame_rate(24.0);

        let action = pacing.decide(Duration::from_millis(100), Duration::from_millis(100));

        assert_eq!(action, Action::Present);
        assert_eq!(pacing.counts(), (1, 0, 0));
    }

    #[test]
    fn a_frame_from_the_future_asks_the_caller_to_wait() {
        let mut pacing = Pacing::with_tolerance(Duration::from_millis(5));

        let action = pacing.decide(Duration::from_millis(200), Duration::from_millis(100));

        assert_eq!(action, Action::Wait(Duration::from_millis(95)));
        assert_eq!(pacing.counts(), (0, 0, 0), "waiting is not presenting");
    }

    /// Lag that never recovers is the failure mode: a player that draws every
    /// frame however late falls further behind for the rest of the file.
    #[test]
    fn a_frame_too_late_to_matter_is_dropped() {
        let mut pacing = Pacing::for_frame_rate(24.0);

        let action = pacing.decide(Duration::from_millis(100), Duration::from_millis(500));

        assert_eq!(action, Action::Drop);
        assert_eq!(pacing.counts(), (0, 1, 0));
        assert_eq!(pacing.drop_rate(), 1.0);
    }

    #[test]
    fn a_frame_barely_early_is_presented_rather_than_waited_for() {
        let mut pacing = Pacing::for_frame_rate(24.0);

        // A millisecond early, against a ~20 ms tolerance.
        let action = pacing.decide(Duration::from_millis(101), Duration::from_millis(100));

        assert_eq!(action, Action::Present);
    }

    #[test]
    fn counters_survive_until_they_are_reset() {
        let mut pacing = Pacing::for_frame_rate(24.0);

        pacing.decide(Duration::ZERO, Duration::ZERO);
        pacing.decide(Duration::ZERO, Duration::from_secs(1));
        pacing.note_repeat();

        assert_eq!(pacing.counts(), (1, 1, 1));
        assert!((pacing.drop_rate() - 0.5).abs() < 1e-9);

        pacing.reset();
        assert_eq!(pacing.counts(), (0, 0, 0));
        assert_eq!(pacing.drop_rate(), 0.0);
    }

    /// A master a test moves by hand, shared the way the engine shares one.
    #[derive(Debug, Default)]
    struct HandClock {
        nanos: std::sync::atomic::AtomicU64,
        stopped: std::sync::atomic::AtomicBool,
    }

    impl HandClock {
        fn set(&self, position: Duration) {
            self.nanos
                .store(position.as_nanos() as u64, std::sync::atomic::Ordering::Relaxed);
        }
    }

    impl MasterClock for HandClock {
        fn position(&self) -> Duration {
            Duration::from_nanos(self.nanos.load(std::sync::atomic::Ordering::Relaxed))
        }

        fn is_running(&self) -> bool {
            !self.stopped.load(std::sync::atomic::Ordering::Relaxed)
        }
    }

    #[test]
    fn a_follower_measures_its_own_play_and_pause_on_the_master() {
        let master = Arc::new(HandClock::default());
        master.set(Duration::from_secs(100));

        let mut clip = Follower::new(master.clone());
        assert_eq!(clip.position(), Duration::ZERO, "paused at zero");

        clip.play();
        master.set(Duration::from_secs(103));
        assert_eq!(clip.position(), Duration::from_secs(3));

        clip.pause();
        master.set(Duration::from_secs(110));
        assert_eq!(clip.position(), Duration::from_secs(3), "paused clips hold");

        clip.play();
        master.set(Duration::from_secs(112));
        assert_eq!(clip.position(), Duration::from_secs(5));

        clip.seek(Duration::from_secs(60));
        master.set(Duration::from_secs(113));
        assert_eq!(clip.position(), Duration::from_secs(61));
    }

    /// Two clips on one master cannot drift apart: there is only one clock.
    #[test]
    fn clips_on_one_master_stay_together() {
        let master = Arc::new(HandClock::default());
        let mut first = Follower::new(master.clone());
        let mut second = Follower::new(master.clone());

        first.play();
        master.set(Duration::from_millis(500));
        second.play();
        master.set(Duration::from_millis(10_500));

        assert_eq!(first.position() - second.position(), Duration::from_millis(500));
    }

    /// The audio stops, the picture stops — and says so.
    #[test]
    fn a_stopped_master_stops_its_followers() {
        let master = Arc::new(HandClock::default());
        let mut clip = Follower::new(master.clone());
        clip.play();
        assert!(clip.is_running());

        master.stopped.store(true, std::sync::atomic::Ordering::Relaxed);
        assert!(!clip.is_running());
    }

    /// Lining a picture up with a sound scheduled for later on the master.
    #[test]
    fn a_clip_started_at_a_point_on_the_master_waits_for_it() {
        let master = Arc::new(HandClock::default());
        master.set(Duration::from_secs(5));

        let clip = Follower::starting_at(master.clone(), Duration::from_secs(8));
        assert!(!clip.is_due());
        assert_eq!(clip.position(), Duration::ZERO);

        master.set(Duration::from_secs(9));
        assert!(clip.is_due());
        assert_eq!(clip.position(), Duration::from_secs(1));
    }

    #[test]
    fn the_monotonic_master_runs_from_the_moment_it_is_made() {
        let master = Monotonic::shared();
        std::thread::sleep(Duration::from_millis(5));

        assert!(master.position() >= Duration::from_millis(5));
        assert!(master.is_running());
    }

    /// Video chases audio, which is the whole point of the trait.
    #[test]
    fn pacing_follows_whatever_master_it_is_given() {
        let master = FixedClock(Duration::from_millis(500));
        let mut pacing = Pacing::for_frame_rate(24.0);

        assert_eq!(
            pacing.decide(Duration::from_millis(500), master.position()),
            Action::Present
        );
        assert_eq!(
            pacing.decide(Duration::from_millis(100), master.position()),
            Action::Drop
        );
        assert!(master.is_running());
    }
}