diff --git a/komorebi-recorder/src/lib.rs b/komorebi-recorder/src/lib.rs index 95235f52..6aae8dbc 100644 --- a/komorebi-recorder/src/lib.rs +++ b/komorebi-recorder/src/lib.rs @@ -59,6 +59,7 @@ //! | [`av`] and [`selftest`] | decoding the recorded video and checking it against the clocks | //! | [`doctor`] | what a recording leans on, and probes that measure it | //! | [`report`] | answers as text for a terminal | +//! | [`playback`] | a clock that runs forwards or backwards, and the decoding that follows it | //! //! # What is not supported //! @@ -84,6 +85,7 @@ pub mod incidents; pub mod komorebi_link; pub mod lock; pub mod platform; +pub mod playback; pub mod power; pub mod recorder; pub mod recovery; diff --git a/komorebi-recorder/src/playback/engine.rs b/komorebi-recorder/src/playback/engine.rs new file mode 100644 index 00000000..c67d7990 --- /dev/null +++ b/komorebi-recorder/src/playback/engine.rs @@ -0,0 +1,1011 @@ +//! Keeping the picture of every display in step with the playhead. +//! +//! A worker thread owns the decoding: the decoder's objects (`AVFoundation`'s on macOS, Media +//! Foundation's on Windows) belong to the thread that made them. It follows the [`Transport`]: +//! whatever the clock says the time is, it makes sure each display's published frame is the one +//! that was on screen then. A display that had no video at that moment publishes a gap. +//! +//! Playing never waits for the decoder to be "ready": position comes from the clock, and if the +//! decoder falls behind, the frame shown is the latest one it has. +//! +//! # How the worker follows the playhead +//! +//! | the playhead | what the worker does | +//! |---|---| +//! | paused, or playing forwards | decodes forwards, holding the next frame until its time is due, and publishes it then | +//! | playing backwards | decodes half a second ending at the playhead, serves it newest first, and decodes the stretch before it once the playhead is a quarter of a second from the start of the frames it has decoded | +//! | moved (any change to the transport, or to the width) | drops the frames it has decoded, opens the video at the new time and publishes the frame that was on screen then | +//! | more than a second and a half from the frame being shown | the same: a jump, not playing along | +//! | on a display with no video at that time | publishes a gap, and goes on publishing it until there is video | +//! | the decoder fails | publishes the failure, drops the frames it has decoded and tries again on its next pass | +//! +//! A pass runs every 3 ms while playing and every 100 ms while paused, and at once when something +//! wakes the worker (every change made through [`Playback`]). After a stream of jumps, such as +//! scrubbing, the published frames end at the last place asked for. +//! +//! # What is shared +//! +//! The worker is handed the manifest and the session path when it starts. After that [`Playback`] +//! and the worker share the transport, the published views and a few counters behind an `Arc`, and +//! a channel of commands (look again, step a frame, quit). [`Playback::version`] counts +//! published views, so a window that redraws when it moves does not have to compare pictures. +//! +//! Covered by the tests in this module that build sessions of numbered videos (`ffmpeg` makes +//! them; without it they skip): `seeking_shows_the_frame_that_was_on_screen_at_that_time`, +//! `playing_forwards_follows_the_clock`, `playing_backwards_runs_the_frames_in_reverse`, +//! `stepping_moves_by_exactly_one_frame`, `a_display_with_no_video_shows_a_gap_and_then_its_frames`, +//! `scrubbing_wildly_ends_on_the_last_place_asked_for` and `a_looped_region_stays_inside_the_region`. + +use super::transport::Transport; +use crate::analysis::guard::SessionPath; +use crate::analysis::video::SessionVideo; +use crate::analysis::video::Stream; +use crate::av::Scale; +use crate::session::Manifest; +use color_eyre::eyre; +use crossbeam_channel::Receiver; +use crossbeam_channel::Sender; +use crossbeam_channel::bounded; +use parking_lot::Mutex; +use std::collections::HashMap; +use std::sync::Arc; +use std::sync::atomic::AtomicBool; +use std::sync::atomic::AtomicU32; +use std::sync::atomic::AtomicU64; +use std::sync::atomic::Ordering; +use std::thread::JoinHandle; +use std::time::Duration; +use std::time::Instant; + +/// How much video is decoded at a time to play backwards: short enough to hold in memory at the +/// size it is drawn. +const REVERSE_CHUNK_S: f64 = 0.5; + +/// When playing backwards, decode the stretch before the one in hand once the playhead is this +/// close to its start. +const PREFETCH_S: f64 = 0.25; + +/// A playhead further than this from the frame being shown is a jump, not playing along. +const JUMP_S: f64 = 1.5; + +/// A decoded frame, RGBA, ready to become a texture. +/// +/// Published behind an [`Arc`], so a new frame is a new allocation and its address says whether +/// the picture changed. +#[derive(Debug, PartialEq)] +pub struct Frame { + /// When it was put on screen, in session video time. A published frame is not later than the + /// playhead it was published for, to within a microsecond. + pub shown_s: f64, + /// The width in pixels. Frames are decoded at the width asked of the [`Playback`] (see + /// [`Playback::set_width`]), keeping the aspect ratio of the recording. + pub width: u32, + /// The height in pixels. + pub height: u32, + /// The pixels as `R, G, B, A` bytes, row by row with no padding between rows: four bytes for + /// each of `width` times `height` pixels. The alpha of every pixel is `255`, so straight + /// (unpremultiplied) and premultiplied alpha agree. + pub rgba: Vec, +} + +/// The picture to draw for a display: the answer of [`Playback::view`]. +/// +/// A window draws a [`Frame`](DisplayView::Frame) as a picture and every other variant as a +/// placeholder. +#[derive(Debug, Clone)] +pub enum DisplayView { + /// Nothing decoded yet. + Loading, + /// The frame that was on screen at the playhead. + Frame(Arc), + /// The display had no video at the playhead: unplugged, asleep, or not yet recorded. + Gap, + /// Decoding failed. Holds the error with its causes, as the `{:#}` format of an error report + /// shows them. The worker tries again on its next pass, and a pass that succeeds replaces this + /// with the frame. + Failed(String), +} + +enum Command { + /// The transport changed: look again. + Wake, + /// Move one frame of `display` forwards (`1`) or backwards (`-1`). + Step { + display: u32, + direction: i32, + }, + Quit, +} + +struct Shared { + transport: Mutex, + epoch: Instant, + /// Bumped whenever the transport is changed from outside, so the worker knows its decoding + /// position may be stale. + generation: AtomicU64, + views: Mutex>, + /// Bumped whenever a view changes: a hint to redraw. + version: AtomicU64, + width: AtomicU32, + stopping: AtomicBool, +} + +impl Shared { + fn now(&self) -> f64 { + self.epoch.elapsed().as_secs_f64() + } + + fn publish(&self, display: u32, view: DisplayView) { + self.views.lock().insert(display, view); + self.version.fetch_add(1, Ordering::Release); + } +} + +/// The playback of one session: a clock and the pictures that go with it. +/// +/// A `Playback` owns a [`Transport`] and the thread that decodes for it. Every method takes +/// `&self`. The control methods +/// ([`seek`](Playback::seek), [`play`](Playback::play), [`pause`](Playback::pause), +/// [`toggle`](Playback::toggle), [`set_rate`](Playback::set_rate), +/// [`set_loop`](Playback::set_loop), [`step`](Playback::step) and +/// [`set_width`](Playback::set_width)) change the clock and wake the worker, and the queries +/// ([`position`](Playback::position), [`is_playing`](Playback::is_playing), +/// [`rate`](Playback::rate), [`looping`](Playback::looping), [`view`](Playback::view) and +/// [`version`](Playback::version)) read it. The controls are those of [`Transport`], with the +/// clock supplied (seconds since the `Playback` started), so the rules there hold: positions are +/// clamped, rates are limited to [`MIN_RATE`](super::transport::MIN_RATE) and +/// [`MAX_RATE`](super::transport::MAX_RATE), and a [`seek`](Playback::seek) after the playhead +/// ran into an end sets it moving again. +/// +/// Dropping a `Playback` stops the worker and waits for it to finish what it is decoding. +/// +/// The decoded pictures are not what is in the video file: they are scaled to the width asked for. +/// Playing needs a decoder, which macOS and Windows have; see [`crate::av::supported`]. +/// +/// # Example +/// +/// Playing a session needs its video on disk, so this compiles but does not run. The behavior is +/// covered by the tests of this module, for example +/// `seeking_shows_the_frame_that_was_on_screen_at_that_time` and +/// `playing_forwards_follows_the_clock`. +/// +/// ```rust,no_run +/// use komorebi_recorder::analysis::guard::SessionPath; +/// use komorebi_recorder::playback::{DisplayView, Playback}; +/// use komorebi_recorder::session::Session; +/// use std::path::Path; +/// +/// let guard = SessionPath::new(Path::new("/recordings/20261026T120000Z"))?; +/// let manifest = Session::open(guard.root())?.manifest()?; +/// let playback = Playback::start(manifest, guard, 1600)?; +/// +/// // start playing at normal speed from two seconds in +/// playback.seek(2.0); +/// playback.play(1.0); +/// +/// // each time the window is drawn: ask where the playhead is, and what to show +/// let seconds = playback.position(); +/// for &display in playback.displays() { +/// match playback.view(display) { +/// DisplayView::Frame(frame) => println!("{display}: {}x{}", frame.width, frame.height), +/// DisplayView::Gap => println!("{display}: no video at {seconds:.1} s"), +/// DisplayView::Loading | DisplayView::Failed(_) => {} +/// } +/// } +/// # Ok::<(), Box>(()) +/// ``` +pub struct Playback { + shared: Arc, + commands: Sender, + worker: Option>, + displays: Vec, +} + +fn rgba_of(bgra: &[u8]) -> Vec { + let mut rgba = Vec::with_capacity(bgra.len()); + for pixel in bgra.as_chunks::<4>().0 { + rgba.extend_from_slice(&[pixel[2], pixel[1], pixel[0], 255]); + } + rgba +} + +impl Playback { + /// Starts the playback of `manifest`'s video, paused at the beginning. + /// + /// `guard` is the session directory the video files are read from, and `width` is how wide + /// decoded frames are wanted, in pixels (at least 64: a smaller value is raised to it). The + /// duration of the [`Transport`] is the end of [`Manifest::video_span`], and the displays are + /// those with at least one recorded frame, in ascending order of id and each once. + /// + /// A session with no video plays: there is nothing to show, and the clock still runs. + /// + /// # Errors + /// + /// Fails only if the worker thread cannot be started (the operating system refused a new + /// thread). A video file that cannot be opened or decoded is not an error here: the display it + /// belongs to shows [`DisplayView::Failed`]. + /// + /// [`Manifest::video_span`]: crate::session::Manifest::video_span + pub fn start(manifest: Manifest, guard: SessionPath, width: u32) -> eyre::Result { + let displays: Vec = { + let mut ids: Vec = manifest + .displays + .iter() + .filter(|entry| entry.result.frames > 0) + .map(|entry| entry.result.display.id) + .collect(); + ids.sort_unstable(); + ids.dedup(); + ids + }; + + let shared = Arc::new(Shared { + transport: Mutex::new(Transport::new(manifest.video_span().1)), + epoch: Instant::now(), + generation: AtomicU64::new(1), + views: Mutex::new(HashMap::new()), + version: AtomicU64::new(0), + width: AtomicU32::new(width.max(64)), + stopping: AtomicBool::new(false), + }); + + let (commands, inbox) = bounded::(256); + let worker_shared = shared.clone(); + let worker_displays = displays.clone(); + let worker = std::thread::Builder::new() + .name("playback".to_string()) + .spawn(move || run(&worker_shared, &inbox, &manifest, &guard, &worker_displays))?; + + Ok(Self { + shared, + commands, + worker: Some(worker), + displays, + }) + } + + /// Returns the ids of the displays that have video, in ascending order. + /// + /// These are the displays the worker follows: the ones with at least one recorded frame in the + /// manifest, in any segment of the recording. + #[must_use] + pub fn displays(&self) -> &[u32] { + &self.displays + } + + fn changed(&self) { + self.shared.generation.fetch_add(1, Ordering::AcqRel); + let _ = self.commands.try_send(Command::Wake); + } + + /// Returns the duration of the recording in session video seconds: the end of the video. + #[must_use] + pub fn duration_s(&self) -> f64 { + self.shared.transport.lock().duration_s() + } + + /// Returns where the playhead is now, in session video time (see [`Transport::position`]). + #[must_use] + pub fn position(&self) -> f64 { + self.shared.transport.lock().position(self.shared.now()) + } + + /// Returns `true` if and only if the playhead is moving now (see [`Transport::is_playing`]). + #[must_use] + pub fn is_playing(&self) -> bool { + self.shared.transport.lock().is_playing(self.shared.now()) + } + + /// Returns the rate the playhead plays at, negative for backwards (see [`Transport::rate`]). + #[must_use] + pub fn rate(&self) -> f64 { + self.shared.transport.lock().rate() + } + + /// Returns the loop region, if one is set (see [`Transport::looping`]). + #[must_use] + pub fn looping(&self) -> Option<(f64, f64)> { + self.shared.transport.lock().looping() + } + + /// Moves the playhead to `time` and wakes the worker, which publishes the frame that was on + /// screen then (see [`Transport::seek`]). + /// + /// The frame arrives later, not before this returns: watch [`Playback::view`] or + /// [`Playback::version`]. + pub fn seek(&self, time: f64) { + let now = self.shared.now(); + self.shared.transport.lock().seek(time, now); + self.changed(); + } + + /// Plays at `rate` from where the playhead is: negative for backwards (see + /// [`Transport::play`]). + pub fn play(&self, rate: f64) { + let now = self.shared.now(); + self.shared.transport.lock().play(rate, now); + self.changed(); + } + + /// Stops the playhead where it is (see [`Transport::pause`]). + pub fn pause(&self) { + let now = self.shared.now(); + self.shared.transport.lock().pause(now); + self.changed(); + } + + /// Plays if the playhead is not moving, and pauses if it is (see [`Transport::toggle`]). + pub fn toggle(&self) { + let now = self.shared.now(); + self.shared.transport.lock().toggle(now); + self.changed(); + } + + /// Changes the speed without moving the playhead or starting it (see + /// [`Transport::set_rate`]). + pub fn set_rate(&self, rate: f64) { + let now = self.shared.now(); + self.shared.transport.lock().set_rate(rate, now); + self.changed(); + } + + /// Sets the region to repeat while playing, or clears it with `None` (see + /// [`Transport::set_loop`]). + pub fn set_loop(&self, region: Option<(f64, f64)>) { + let now = self.shared.now(); + self.shared.transport.lock().set_loop(region, now); + self.changed(); + } + + /// Pauses and moves the playhead one frame of `display` forwards or backwards. + /// + /// A positive `direction` steps forwards; zero and negative values step backwards. The worker + /// moves the playhead to the time the neighboring frame was put on screen, so what the display + /// shows afterwards is exactly that frame. If `display` has no frame showing (it is loading, in + /// a gap, has failed, or is not one of the [`displays`](Playback::displays)) or has no frame in + /// that direction, the playhead does not move, but it is still paused. + pub fn step(&self, display: u32, direction: i32) { + self.pause(); + let _ = self.commands.try_send(Command::Step { + display, + direction: direction.signum(), + }); + } + + /// Changes how wide decoded frames are wanted, in pixels, with at least 64 (a smaller value is + /// raised to it). + /// + /// The worker decodes again at the playhead, so the frames that follow have the new width. + pub fn set_width(&self, width: u32) { + self.shared.width.store(width.max(64), Ordering::Release); + self.changed(); + } + + /// Returns what to draw for `display` now. + /// + /// It is [`DisplayView::Loading`] until the worker has published something for `display`, + /// which includes any id that is not one of the [`displays`](Playback::displays). + #[must_use] + pub fn view(&self, display: u32) -> DisplayView { + self.shared + .views + .lock() + .get(&display) + .cloned() + .unwrap_or(DisplayView::Loading) + } + + /// Returns a counter that increases whenever a view is published for any display; redraw when + /// it moves. + /// + /// The counter is a hint that something may have changed. It does not say what: ask + /// [`Playback::view`]. + #[must_use] + pub fn version(&self) -> u64 { + self.shared.version.load(Ordering::Acquire) + } +} + +impl Drop for Playback { + fn drop(&mut self) { + self.shared.stopping.store(true, Ordering::Release); + let _ = self.commands.try_send(Command::Quit); + if let Some(worker) = self.worker.take() { + let _ = worker.join(); + } + } +} + +/// Where the decoding of one display has got to. +struct Cursor { + display: u32, + generation: u64, + width: u32, + /// The frame published now. + current: Option>, + /// Forwards: the next frame, decoded but not due yet. + ahead: Option>, + stream: Option, + /// Backwards: a short stretch decoded, oldest first. + behind: Vec>, + gap: bool, +} + +impl Cursor { + fn new(display: u32) -> Self { + Self { + display, + generation: 0, + width: 0, + current: None, + ahead: None, + stream: None, + behind: Vec::new(), + gap: false, + } + } + + fn forget(&mut self) { + self.stream = None; + self.ahead = None; + self.behind.clear(); + } +} + +fn frame_of(shown_s: f64, frame: &crate::av::Frame) -> Arc { + Arc::new(Frame { + shown_s, + width: frame.width, + height: frame.height, + rgba: rgba_of(&frame.bgra), + }) +} + +/// Decode forwards from `time`: the frame on screen then becomes the current one and the next is +/// held ahead. +fn restart_forwards( + cursor: &mut Cursor, + video: &SessionVideo, + shared: &Shared, + time: f64, +) -> eyre::Result<()> { + cursor.forget(); + let Some(mut stream) = video.open_at(cursor.display, time, None, Scale::Width(cursor.width))? + else { + cursor.current = None; + cursor.gap = true; + shared.publish(cursor.display, DisplayView::Gap); + return Ok(()); + }; + + cursor.gap = false; + if let Some((shown_s, frame)) = stream.next_frame()? { + let first = frame_of(shown_s, &frame); + cursor.current = Some(first.clone()); + shared.publish(cursor.display, DisplayView::Frame(first)); + } + cursor.ahead = stream + .next_frame()? + .map(|(shown_s, frame)| frame_of(shown_s, &frame)); + cursor.stream = Some(stream); + Ok(()) +} + +/// Decode `REVERSE_CHUNK_S` of video ending at `until`, oldest first, for playing backwards. +fn fill_behind(cursor: &mut Cursor, video: &SessionVideo, until: f64) -> eyre::Result<()> { + let from = (until - REVERSE_CHUNK_S).max(0.0); + cursor.behind.clear(); + let Some(mut stream) = video.open_at( + cursor.display, + from, + Some(until), + Scale::Width(cursor.width), + )? + else { + return Ok(()); + }; + + while let Some((shown_s, frame)) = stream.next_frame()? { + cursor.behind.push(frame_of(shown_s, &frame)); + } + Ok(()) +} + +/// Everything `follow` needs to know about the moment it is following. +struct Moment { + time: f64, + playing: bool, + rate: f64, + generation: u64, + width: u32, +} + +/// Make the published frame of `cursor` the one on screen at `moment.time`. +fn follow( + cursor: &mut Cursor, + video: &SessionVideo, + shared: &Shared, + moment: &Moment, +) -> eyre::Result<()> { + let time = moment.time; + let resynchronize = cursor.generation != moment.generation || cursor.width != moment.width; + cursor.generation = moment.generation; + cursor.width = moment.width; + + // a display with no video at this moment shows a gap, and goes on showing one + if !video.has_video_at(cursor.display, time) { + if !cursor.gap { + cursor.forget(); + cursor.current = None; + cursor.gap = true; + shared.publish(cursor.display, DisplayView::Gap); + } + return Ok(()); + } + + if moment.playing && moment.rate < 0.0 { + // backwards: serve frames out of a decoded stretch, decoding the stretch before it when + // the playhead runs off the start of it + let needs_fill = resynchronize + || cursor.gap + || cursor + .behind + .first() + .is_none_or(|first| time < first.shown_s) + || cursor + .behind + .last() + .is_some_and(|last| time > last.shown_s + JUMP_S); + if needs_fill { + cursor.stream = None; + cursor.ahead = None; + cursor.gap = false; + fill_behind(cursor, video, time)?; + } else if let Some(first) = cursor.behind.first().map(|first| first.shown_s) + && time - first < PREFETCH_S + && first > 0.0 + { + // running low: decode the stretch before this one now, so it is there when needed + let mut earlier = Vec::new(); + if let Some(mut stream) = video.open_at( + cursor.display, + (first - REVERSE_CHUNK_S).max(0.0), + Some(first), + Scale::Width(cursor.width), + )? { + while let Some((shown_s, frame)) = stream.next_frame()? { + if shown_s < first - 1e-6 { + earlier.push(frame_of(shown_s, &frame)); + } + } + } + earlier.append(&mut cursor.behind); + cursor.behind = earlier; + // what is already behind the playhead's direction of travel is no longer wanted + cursor + .behind + .retain(|frame| frame.shown_s <= time + REVERSE_CHUNK_S * 2.0); + } + + let wanted = cursor + .behind + .iter() + .rev() + .find(|frame| frame.shown_s <= time + 1e-6) + .cloned(); + if let Some(wanted) = wanted + && cursor + .current + .as_ref() + .is_none_or(|current| (current.shown_s - wanted.shown_s).abs() > 1e-9) + { + cursor.current = Some(wanted.clone()); + shared.publish(cursor.display, DisplayView::Frame(wanted)); + } + return Ok(()); + } + + // forwards or paused: carry on from where the decoder is, unless the playhead jumped + let can_continue = + !resynchronize && !cursor.gap && cursor.stream.is_some() && cursor.current.is_some(); + if can_continue { + let current_s = cursor + .current + .as_ref() + .map_or(0.0, |current| current.shown_s); + let ahead_due = cursor + .ahead + .as_ref() + .is_some_and(|ahead| ahead.shown_s <= time + 1e-6); + let far_ahead = ahead_due + && cursor + .ahead + .as_ref() + .is_some_and(|ahead| time - ahead.shown_s > JUMP_S); + let went_back = current_s > time + 1e-6; + + if !far_ahead && !went_back { + let mut advanced = false; + while cursor + .ahead + .as_ref() + .is_some_and(|ahead| ahead.shown_s <= time + 1e-6) + { + cursor.current = cursor.ahead.take(); + advanced = true; + cursor.ahead = match cursor.stream.as_mut() { + Some(stream) => stream + .next_frame()? + .map(|(shown_s, frame)| frame_of(shown_s, &frame)), + None => None, + }; + } + if advanced && let Some(current) = &cursor.current { + shared.publish(cursor.display, DisplayView::Frame(current.clone())); + } + return Ok(()); + } + } + + restart_forwards(cursor, video, shared, time) +} + +/// The worker. +fn run( + shared: &Shared, + inbox: &Receiver, + manifest: &Manifest, + guard: &SessionPath, + displays: &[u32], +) { + let video = SessionVideo::new(manifest, guard); + let mut cursors: Vec = displays + .iter() + .map(|display| Cursor::new(*display)) + .collect(); + + loop { + if shared.stopping.load(Ordering::Acquire) { + return; + } + + // commands first: a step moves the transport, which the rest of this pass then follows + let mut quit = false; + while let Ok(command) = inbox.try_recv() { + match command { + Command::Quit => quit = true, + Command::Wake => {} + Command::Step { display, direction } => { + if let Some(cursor) = + cursors.iter_mut().find(|cursor| cursor.display == display) + { + step(cursor, &video, shared, direction); + } + } + } + } + if quit { + return; + } + + let now = shared.now(); + let (time, playing, rate) = { + let transport = shared.transport.lock(); + ( + transport.position(now), + transport.is_playing(now), + transport.rate(), + ) + }; + let moment = Moment { + time, + playing, + rate, + generation: shared.generation.load(Ordering::Acquire), + width: shared.width.load(Ordering::Acquire), + }; + + for cursor in &mut cursors { + if let Err(error) = follow(cursor, &video, shared, &moment) { + cursor.forget(); + cursor.current = None; + shared.publish(cursor.display, DisplayView::Failed(format!("{error:#}"))); + } + } + + // playing is paced finely; paused, there is nothing to do until something changes + let wait = if playing { + Duration::from_millis(3) + } else { + Duration::from_millis(100) + }; + match inbox.recv_timeout(wait) { + Ok(Command::Quit) | Err(crossbeam_channel::RecvTimeoutError::Disconnected) => return, + Ok(Command::Step { display, direction }) => { + if let Some(cursor) = cursors.iter_mut().find(|cursor| cursor.display == display) { + step(cursor, &video, shared, direction); + } + } + Ok(Command::Wake) | Err(crossbeam_channel::RecvTimeoutError::Timeout) => {} + } + } +} + +/// Move the playhead to the frame after (or before) the one `cursor` shows. +fn step(cursor: &mut Cursor, video: &SessionVideo, shared: &Shared, direction: i32) { + let Some(shown) = cursor.current.as_ref().map(|frame| frame.shown_s) else { + return; + }; + + let target = if direction > 0 { + // the next frame is the one held ahead, or the first after the current if nothing is + let mut stream = + match video.open_at(cursor.display, shown, None, Scale::Width(cursor.width)) { + Ok(Some(stream)) => stream, + _ => return, + }; + let mut found = None; + while let Ok(Some((time, _))) = stream.next_frame() { + if time > shown + 1e-6 { + found = Some(time); + break; + } + } + found + } else { + // the last frame before the current one, from the stretch of video just before it + let from = (shown - REVERSE_CHUNK_S).max(0.0); + let mut stream = match video.open_at( + cursor.display, + from, + Some(shown), + Scale::Width(cursor.width), + ) { + Ok(Some(stream)) => stream, + _ => return, + }; + let mut previous = None; + while let Ok(Some((time, _))) = stream.next_frame() { + if time < shown - 1e-6 { + previous = Some(time); + } + } + previous + }; + + if let Some(target) = target { + let now = shared.now(); + shared.transport.lock().seek(target, now); + shared.generation.fetch_add(1, Ordering::AcqRel); + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testkit; + use crate::testkit::SessionBuilder; + use std::time::Instant; + + const FPS: u32 = 30; + + /// A session with display 1 numbered 0..90 at 30 fps and display 2 only from 1.0 s to 3.0 s. + fn playback(name: &str) -> Option { + if !testkit::ffmpeg_available() { + eprintln!("skipped: ffmpeg is not available to make a test video"); + return None; + } + + let (session, manifest) = SessionBuilder::new(name) + .video(1, 0.0, 90, FPS) + .video(2, 1.0, 60, FPS) + .build(); + let guard = SessionPath::new(&session.dir).expect("guard"); + Some(Playback::start(manifest, guard, 128).expect("start")) + } + + /// Wait until `check` holds, up to a few seconds. + fn eventually(what: &str, mut check: impl FnMut() -> bool) { + let deadline = Instant::now() + Duration::from_secs(8); + while Instant::now() < deadline { + if check() { + return; + } + std::thread::sleep(Duration::from_millis(10)); + } + panic!("timed out waiting for {what}"); + } + + /// Which frame number a display is showing, if it is showing one. + fn shown(playback: &Playback, display: u32) -> Option { + match playback.view(display) { + DisplayView::Frame(frame) => Some(testkit::numbered_frame_index( + &frame.rgba, + frame.width, + frame.height, + )), + _ => None, + } + } + + #[test] + fn seeking_shows_the_frame_that_was_on_screen_at_that_time() { + let Some(playback) = playback("playback-seek") else { + return; + }; + + for (time, expected) in [(1.0, 30), (0.5, 15), (2.5, 75), (0.0, 0)] { + playback.seek(time); + eventually(&format!("frame {expected} at {time}"), || { + shown(&playback, 1) == Some(expected) + }); + } + assert!(!playback.is_playing()); + } + + #[test] + fn playing_forwards_follows_the_clock() { + let Some(playback) = playback("playback-forward") else { + return; + }; + + playback.seek(0.5); + eventually("the first frame", || shown(&playback, 1) == Some(15)); + // slowly, so that how busy the machine is cannot decide whether it catches up + playback.play(0.25); + assert!(playback.is_playing()); + + // the picture moves on, and catches up with the clock: it is the frame for the time (to + // within a few frames of decode lag) and never a frame from the future + eventually("the picture to advance", || { + shown(&playback, 1).is_some_and(|frame| frame > 15) + }); + eventually("the picture to be the one for the time", || { + let position = playback.position(); + let expected = (position * f64::from(FPS)) as i64; + shown(&playback, 1).is_some_and(|frame| { + let frame = i64::from(frame); + position < 2.9 && frame <= expected + 1 && expected - frame <= 6 + }) + }); + + playback.pause(); + assert!(!playback.is_playing()); + let held = playback.position(); + std::thread::sleep(Duration::from_millis(200)); + assert!( + (playback.position() - held).abs() < 1e-9, + "paused means still" + ); + } + + #[test] + fn playing_backwards_runs_the_frames_in_reverse() { + let Some(playback) = playback("playback-reverse") else { + return; + }; + + playback.seek(2.0); + eventually("frame 60", || shown(&playback, 1) == Some(60)); + playback.play(-0.25); + + eventually("the picture to go back", || { + shown(&playback, 1).is_some_and(|frame| frame < 60) + }); + // and to be the frame for the time: at or before the playhead, close behind it in time + eventually("the picture to be the one for the time", || { + let position = playback.position(); + let expected = (position * f64::from(FPS)) as i64; + shown(&playback, 1).is_some_and(|frame| { + let frame = i64::from(frame); + position > 0.2 && frame <= expected + 1 && expected - frame <= 6 + }) + }); + + // it keeps going back past the stretch it started with + let first = shown(&playback, 1).expect("a frame"); + eventually("the picture to keep going back", || { + shown(&playback, 1).is_some_and(|frame| frame + 20 < first) + }); + } + + #[test] + fn stepping_moves_by_exactly_one_frame() { + let Some(playback) = playback("playback-step") else { + return; + }; + + playback.seek(1.0); + eventually("frame 30", || shown(&playback, 1) == Some(30)); + + playback.step(1, 1); + eventually("frame 31", || shown(&playback, 1) == Some(31)); + assert!((playback.position() - 31.0 / f64::from(FPS)).abs() < 0.002); + + playback.step(1, -1); + eventually("frame 30 again", || shown(&playback, 1) == Some(30)); + playback.step(1, -1); + eventually("frame 29", || shown(&playback, 1) == Some(29)); + assert!(!playback.is_playing()); + } + + #[test] + fn a_display_with_no_video_shows_a_gap_and_then_its_frames() { + let Some(playback) = playback("playback-gap") else { + return; + }; + + playback.seek(0.5); + eventually("a gap on display 2", || { + matches!(playback.view(2), DisplayView::Gap) + }); + eventually("display 1's frame", || shown(&playback, 1) == Some(15)); + + playback.seek(1.5); + // display 2 starts at 1.0 s, so 1.5 s is its 15th frame + eventually("display 2's frame", || shown(&playback, 2) == Some(15)); + eventually("display 1's frame", || shown(&playback, 1) == Some(45)); + + playback.seek(3.5); + eventually("a gap on display 2 again", || { + matches!(playback.view(2), DisplayView::Gap) + }); + } + + #[test] + fn scrubbing_wildly_ends_on_the_last_place_asked_for() { + let Some(playback) = playback("playback-scrub") else { + return; + }; + + for index in 0..60 { + playback.seek(f64::from(index % 9) * 0.3); + } + playback.seek(2.2); + + eventually("frame 66", || shown(&playback, 1) == Some(66)); + // and it stays there + std::thread::sleep(Duration::from_millis(250)); + assert_eq!(shown(&playback, 1), Some(66)); + } + + #[test] + fn a_looped_region_stays_inside_the_region() { + let Some(playback) = playback("playback-loop") else { + return; + }; + + playback.seek(1.0); + playback.set_loop(Some((1.0, 1.5))); + playback.play(1.0); + + let started = Instant::now(); + while started.elapsed() < Duration::from_millis(1400) { + let position = playback.position(); + assert!( + (1.0..=1.5).contains(&position), + "position {position} left the loop" + ); + if let Some(frame) = shown(&playback, 1) { + assert!( + (28..=47).contains(&frame), + "frame {frame} is outside the loop" + ); + } + std::thread::sleep(Duration::from_millis(15)); + } + assert!(playback.is_playing()); + } + + #[test] + fn a_session_with_no_video_has_nothing_to_play_and_does_not_fail() { + let (session, manifest) = SessionBuilder::new("playback-none").build(); + let guard = SessionPath::new(&session.dir).expect("guard"); + let playback = Playback::start(manifest, guard, 128).expect("start"); + + assert!(playback.displays().is_empty()); + playback.play(1.0); + playback.seek(2.0); + assert!(playback.position() >= 2.0); + } +} diff --git a/komorebi-recorder/src/playback/mod.rs b/komorebi-recorder/src/playback/mod.rs new file mode 100644 index 00000000..332b6d0e --- /dev/null +++ b/komorebi-recorder/src/playback/mod.rs @@ -0,0 +1,34 @@ +//! Playing the recording: a clock that can run forwards or backwards at any speed, and an engine +//! that keeps the frame of every display in step with it. +//! +//! The clock ([`transport`]) is plain arithmetic with no window and no decoder, so it is tested to +//! the millisecond. The engine ([`engine`]) owns the decoding on its own thread, since the decoder's +//! objects (`AVFoundation`'s on macOS, Media Foundation's on Windows) belong to the thread that +//! made them, and publishes the frame to show for each display. Whatever draws (the viewer) asks +//! the engine what time it is and what to show, and never decodes itself. +//! +//! | type | role | +//! |---|---| +//! | [`Transport`] | the playhead: position, rate (negative for backwards), loop region; no clock of its own | +//! | [`Playback`] | the transport behind a lock, plus the worker thread that decodes for it | +//! | [`DisplayView`] | what to draw for one display now: loading, a frame, a gap or a failure | +//! | [`Frame`] | one decoded picture, RGBA, ready to become a texture | +//! +//! # Where it sits +//! +//! This layer reads video through [`crate::analysis::video::SessionVideo`], which maps a moment of +//! session video time on a display to the segment file that has it, and through [`crate::av`], the +//! decoder of the host the viewer runs on (the host axis: macOS and Windows have one). The viewer +//! (`crate::viewer`) is the only caller. On a host with no decoder [`Playback::start`] still +//! succeeds and each display's view becomes [`DisplayView::Failed`] saying so. +//! +//! The flavor of komorebi that produced the session does not matter here: only the manifest's +//! displays and their video segments are read. + +pub mod engine; +pub mod transport; + +pub use engine::DisplayView; +pub use engine::Frame; +pub use engine::Playback; +pub use transport::Transport; diff --git a/komorebi-recorder/src/playback/transport.rs b/komorebi-recorder/src/playback/transport.rs new file mode 100644 index 00000000..ce62d164 --- /dev/null +++ b/komorebi-recorder/src/playback/transport.rs @@ -0,0 +1,656 @@ +//! The playhead: where in the recording it is, and whether and how fast it is moving. +//! +//! A [`Transport`] is plain arithmetic. It has no window, no decoder and no clock of its own: every +//! method that depends on time takes `now`, a reading of any monotonic clock in seconds (the +//! [`Playback`](super::Playback) engine passes the seconds since it started). That makes it exact +//! and testable to the millisecond without waiting for anything. +//! +//! Position is computed from a starting point, a rate and the time that has passed, never +//! accumulated frame by frame, so it does not drift whatever the frame rate of the video or of the +//! window drawing it. Times are session video seconds: seconds from the start of the recording's +//! video, so a recording [`Manifest::video_span`] reports as `(0.0, d)` is a transport of +//! duration `d`. +//! +//! # The model +//! +//! A transport remembers where the playhead was at one moment (the anchor), whether it is playing, +//! the rate and an optional loop region. Asked for the position at a later `now`, it adds +//! `rate * (now - anchor time)` to the anchor and then applies the ends of the recording or the +//! loop region. Calls that change how it moves first settle the position at `now`, so a change of +//! rate or direction never jumps the playhead. +//! +//! | rule | detail | +//! |---|---| +//! | range | the position is always within `0.0..=duration_s`; [`Transport::seek`] clamps | +//! | ends | playing into an end stops there; [`Transport::is_playing`] then returns `false` | +//! | speed | the magnitude of the rate is within `MIN_RATE..=MAX_RATE`; the sign is the direction | +//! | restart | playing forwards from the end (or backwards from the start) starts over at the other end | +//! | loop | a region repeats for as long as the transport is playing; it has no end | +//! +//! `now` must not decrease between calls. That is not checked: an earlier `now` moves the +//! playhead the other way. +//! +//! The limits are [`MIN_RATE`] and [`MAX_RATE`]. +//! +//! [`Manifest::video_span`]: crate::session::Manifest::video_span + +/// The fastest the playhead may move, as a multiple of real time, in either direction. +/// +/// [`Transport::play`] and [`Transport::set_rate`] clamp the magnitude of a rate to +/// [`MIN_RATE`]`..=MAX_RATE`. +pub const MAX_RATE: f64 = 8.0; +/// The slowest the playhead may move, as a multiple of real time, in either direction. +/// +/// A rate of zero is not a rate: it becomes `MIN_RATE` (forwards). Pause instead. +pub const MIN_RATE: f64 = 0.1; + +/// The playhead over a recording of a fixed duration: where it is, and whether and how fast it +/// moves. +/// +/// Every value is a position in session video seconds, and every method that depends on time takes +/// `now` in seconds from any monotonic clock. The position is guaranteed to stay within +/// `0.0..=duration_s`. See the [module documentation](self) for the model. +/// +/// A transport does not decode or draw anything, and nothing here is shared between threads: +/// [`Playback`](super::Playback) keeps one behind a lock and hands out `now`. +/// +/// # Example +/// +/// A ten second recording, played from the 2 s mark and then paused: +/// +/// ```rust +/// use komorebi_recorder::playback::Transport; +/// +/// let mut transport = Transport::new(10.0); +/// assert_eq!(transport.position(0.0), 0.0); +/// assert!(!transport.is_playing(0.0)); +/// +/// // `now` is any monotonic clock: here, 100.0 s on it +/// transport.seek(2.0, 100.0); +/// transport.play(1.0, 100.0); +/// assert_eq!(transport.position(100.5), 2.5); +/// +/// transport.pause(101.0); +/// assert_eq!(transport.position(150.0), 3.0, "paused means still"); +/// ``` +/// +/// # Invariants +/// +/// That the position stays within the recording, that the rate stays within its limits and that a +/// loop region is never empty are kept by every method, and the fields are private so that no +/// other way of making a `Transport` can bypass them. The compiler enforces the second part: +/// +/// ```rust,compile_fail,E0451 +/// use komorebi_recorder::playback::Transport; +/// +/// let transport = Transport { +/// duration_s: -1.0, +/// anchor_s: 50.0, +/// anchored_at: 0.0, +/// playing: false, +/// rate: 0.0, +/// looping: None, +/// }; +/// ``` +/// +/// [`Transport::new`] is the way in, and it treats a negative duration as zero: +/// +/// ```rust +/// use komorebi_recorder::playback::Transport; +/// +/// let transport = Transport::new(-1.0); +/// assert_eq!(transport.duration_s(), 0.0); +/// assert_eq!(transport.position(0.0), 0.0); +/// ``` +#[derive(Debug, Clone, PartialEq)] +pub struct Transport { + duration_s: f64, + /// Where it was at `anchored_at`. + anchor_s: f64, + anchored_at: f64, + playing: bool, + /// Speed as a multiple of real time; negative plays backwards. + rate: f64, + looping: Option<(f64, f64)>, +} + +impl Transport { + /// Returns a paused transport at the start of a recording `duration_s` seconds long. + /// + /// The rate is `1.0` and there is no loop region. A negative `duration_s` is treated as `0.0`. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::playback::Transport; + /// + /// let transport = Transport::new(-3.0); + /// assert_eq!(transport.duration_s(), 0.0); + /// assert_eq!(transport.rate(), 1.0); + /// assert_eq!(transport.looping(), None); + /// ``` + #[must_use] + pub fn new(duration_s: f64) -> Self { + Self { + duration_s: duration_s.max(0.0), + anchor_s: 0.0, + anchored_at: 0.0, + playing: false, + rate: 1.0, + looping: None, + } + } + + /// Returns the duration of the recording in seconds, as given to [`Transport::new`]. + #[must_use] + pub fn duration_s(&self) -> f64 { + self.duration_s + } + + /// Returns the speed it plays at when playing, as a multiple of real time: negative for + /// backwards. + /// + /// A paused transport still has a rate, the one it resumes at. The magnitude is guaranteed to be + /// within [`MIN_RATE`]`..=`[`MAX_RATE`]. + #[must_use] + pub fn rate(&self) -> f64 { + self.rate + } + + /// Returns the loop region as `(from, to)` in session video seconds, if one is set. + /// + /// It is guaranteed that `from < to` and that both lie within `0.0..=duration_s`. See + /// [`Transport::set_loop`]. + #[must_use] + pub fn looping(&self) -> Option<(f64, f64)> { + self.looping + } + + /// Returns where the playhead is at `now`, in session video seconds. + /// + /// A paused transport is where it was left. A playing one has moved `rate * (now - then)` from + /// where it was at `then`, the last time something changed how it moves, and: + /// + /// - stops at `0.0` or `duration_s` if that takes it past an end, or + /// - wraps within the loop region, if there is one, when it passes the far end of the region + /// in its direction of travel (see [`Transport::set_loop`]). + /// + /// The result is guaranteed to be within `0.0..=duration_s`. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::playback::Transport; + /// + /// let mut transport = Transport::new(10.0); + /// transport.seek(8.0, 0.0); + /// transport.play(1.0, 0.0); + /// assert_eq!(transport.position(1.5), 9.5); + /// assert_eq!(transport.position(5.0), 10.0, "it stops at the end"); + /// + /// // twice as fast, backwards, from the middle + /// transport.seek(5.0, 10.0); + /// transport.play(-2.0, 10.0); + /// assert_eq!(transport.position(11.0), 3.0); + /// ``` + #[must_use] + pub fn position(&self, now: f64) -> f64 { + if !self.playing { + return self.anchor_s; + } + + let raw = self.anchor_s + self.rate * (now - self.anchored_at); + if let Some((from, to)) = self.looping + && to > from + { + if self.rate > 0.0 && raw >= to && self.anchor_s <= to { + return from + (raw - from).rem_euclid(to - from); + } + if self.rate < 0.0 && raw <= from && self.anchor_s >= from { + return to - (to - raw).rem_euclid(to - from); + } + } + + raw.clamp(0.0, self.duration_s) + } + + /// Returns `true` if and only if the playhead is moving at `now`: it was set playing and has + /// not run into an end. + /// + /// With a loop region set it is moving for as long as it was set playing, since a loop has no + /// end. That includes a playhead the region does not capture, which has run to an end of the + /// recording and stays there (see [`Transport::set_loop`]). + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::playback::Transport; + /// + /// let mut transport = Transport::new(10.0); + /// transport.seek(9.0, 0.0); + /// transport.play(1.0, 0.0); + /// assert!(transport.is_playing(0.5)); + /// assert!(!transport.is_playing(2.0), "it ran into the end at 1.0"); + /// ``` + #[must_use] + pub fn is_playing(&self, now: f64) -> bool { + if !self.playing { + return false; + } + if self.looping.is_some() { + return true; + } + + let raw = self.anchor_s + self.rate * (now - self.anchored_at); + !(self.rate > 0.0 && raw >= self.duration_s || self.rate < 0.0 && raw <= 0.0) + } + + /// Settle: if it ran into an end it stops there. + fn settle(&mut self, now: f64) { + let here = self.position(now); + let moving = self.is_playing(now); + self.anchor_s = here; + self.anchored_at = now; + self.playing = moving; + } + + /// Moves the playhead to `time` at `now`, clamped to `0.0..=duration_s`. + /// + /// The rate and the loop region are untouched, and a playing transport carries on playing from + /// the new place while a paused one stays paused. A `time` outside the recording is clamped, + /// not an error. + /// + /// A transport that ran into an end and stopped there still counts as set playing, so seeking + /// it sets it moving again from the new place. [`Transport::pause`] first to keep it still. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::playback::Transport; + /// + /// let mut transport = Transport::new(10.0); + /// transport.play(1.0, 0.0); + /// transport.seek(6.0, 2.0); + /// assert!(transport.is_playing(2.0)); + /// assert_eq!(transport.position(3.0), 7.0); + /// + /// transport.seek(99.0, 3.0); + /// assert_eq!(transport.position(3.0), 10.0); + /// transport.seek(-5.0, 3.0); + /// assert_eq!(transport.position(3.0), 0.0); + /// + /// // paused stays paused + /// transport.pause(3.0); + /// transport.seek(4.0, 4.0); + /// assert!(!transport.is_playing(5.0)); + /// assert_eq!(transport.position(5.0), 4.0); + /// ``` + /// + /// # Example: seeking after running into the end + /// + /// ```rust + /// use komorebi_recorder::playback::Transport; + /// + /// let mut transport = Transport::new(10.0); + /// transport.seek(8.0, 0.0); + /// transport.play(1.0, 0.0); + /// assert!(!transport.is_playing(5.0), "stopped at the end"); + /// + /// transport.seek(1.0, 6.0); + /// assert!(transport.is_playing(6.5), "moving again"); + /// assert_eq!(transport.position(7.0), 2.0); + /// ``` + pub fn seek(&mut self, time: f64, now: f64) { + self.anchor_s = time.clamp(0.0, self.duration_s); + self.anchored_at = now; + } + + /// Starts playing at `rate` from where the playhead is at `now`: negative for backwards. + /// + /// The magnitude of `rate` is clamped to [`MIN_RATE`]`..=`[`MAX_RATE`], so a rate of zero plays + /// forwards at `MIN_RATE`. Playing forwards from the end of the recording (or backwards from the + /// start) starts over from the other end. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::playback::transport::{Transport, MAX_RATE}; + /// + /// let mut transport = Transport::new(10.0); + /// transport.seek(10.0, 0.0); + /// transport.play(1.0, 0.0); + /// assert_eq!(transport.position(1.0), 1.0, "from the end it starts over"); + /// + /// // backwards, from where it is now, and no faster than the limit + /// transport.play(-1000.0, 1.0); + /// assert_eq!(transport.rate(), -MAX_RATE); + /// assert_eq!(transport.position(1.0), 1.0); + /// assert_eq!(transport.position(1.125), 0.0); + /// ``` + pub fn play(&mut self, rate: f64, now: f64) { + self.settle(now); + let magnitude = rate.abs().clamp(MIN_RATE, MAX_RATE); + self.rate = if rate < 0.0 { -magnitude } else { magnitude }; + + // playing forwards from the end (or backwards from the start) starts over + if self.rate > 0.0 && self.anchor_s >= self.duration_s { + self.anchor_s = 0.0; + } else if self.rate < 0.0 && self.anchor_s <= 0.0 { + self.anchor_s = self.duration_s; + } + self.anchored_at = now; + self.playing = true; + } + + /// Stops the playhead where it is at `now`. + /// + /// The rate is kept, so [`Transport::toggle`] resumes at the same speed. + pub fn pause(&mut self, now: f64) { + self.settle(now); + self.playing = false; + } + + /// Plays if the playhead is not moving at `now`, and pauses if it is. + /// + /// Playing resumes at the current rate. A playhead stopped at an end is not moving, so toggling + /// it plays, starting over as [`Transport::play`] does. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::playback::Transport; + /// + /// let mut transport = Transport::new(10.0); + /// transport.set_rate(2.0, 0.0); + /// transport.toggle(0.0); + /// assert!(transport.is_playing(1.0)); + /// assert_eq!(transport.position(1.0), 2.0); + /// + /// transport.toggle(1.0); + /// assert!(!transport.is_playing(2.0)); + /// assert_eq!(transport.position(2.0), 2.0); + /// + /// // resuming carries on from there at the same speed + /// transport.toggle(5.0); + /// assert_eq!(transport.position(6.0), 4.0); + /// ``` + pub fn toggle(&mut self, now: f64) { + if self.is_playing(now) { + self.pause(now); + } else { + let rate = self.rate; + self.play(rate, now); + } + } + + /// Changes the speed without moving the playhead and without starting or stopping it. + /// + /// The magnitude of `rate` is clamped to [`MIN_RATE`]`..=`[`MAX_RATE`] as in + /// [`Transport::play`]. If the playhead is moving at `now` it carries on from where it is at the + /// new speed; otherwise it stays still and the new rate applies when it next plays. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::playback::transport::{Transport, MAX_RATE, MIN_RATE}; + /// + /// let mut transport = Transport::new(10.0); + /// transport.play(1.0, 0.0); + /// transport.set_rate(4.0, 2.0); + /// assert_eq!(transport.position(2.0), 2.0, "the playhead did not jump"); + /// assert_eq!(transport.position(3.0), 6.0); + /// + /// // paused stays paused + /// transport.pause(3.0); + /// transport.set_rate(0.5, 4.0); + /// assert!(!transport.is_playing(5.0)); + /// + /// transport.set_rate(1000.0, 5.0); + /// assert_eq!(transport.rate(), MAX_RATE); + /// transport.set_rate(0.0, 5.0); + /// assert_eq!(transport.rate(), MIN_RATE); + /// ``` + pub fn set_rate(&mut self, rate: f64, now: f64) { + let was_playing = self.is_playing(now); + self.settle(now); + let magnitude = rate.abs().clamp(MIN_RATE, MAX_RATE); + self.rate = if rate < 0.0 { -magnitude } else { magnitude }; + self.playing = was_playing; + } + + /// Sets the region `(from, to)` to repeat while playing, or clears it with `None`. + /// + /// Both ends are clamped to `0.0..=duration_s`, and a region that is then empty or backwards + /// (`to <= from`) clears the loop like `None`. The playhead is settled at `now` first. + /// + /// While a region is set and the transport is playing, a playhead that reaches the far end of + /// the region in its direction of travel wraps to the near end: forwards past `to` it returns + /// from `from`, backwards past `from` it returns from `to`. A playhead that starts before the + /// region plays on to it and wraps when it passes the far end, not when it enters. One that is + /// already past the far end (after `to` going forwards, before `from` going backwards) never + /// wraps: the region is ignored and it runs to the end of the recording, and + /// [`Transport::is_playing`] stays `true`. [`Transport::seek`] into the region to start looping. + /// + /// # Example + /// + /// ```rust + /// use komorebi_recorder::playback::Transport; + /// + /// let mut transport = Transport::new(10.0); + /// transport.set_loop(Some((2.0, 4.0)), 0.0); + /// transport.seek(3.0, 0.0); + /// transport.play(1.0, 0.0); + /// + /// assert_eq!(transport.position(0.5), 3.5); + /// assert_eq!(transport.position(1.5), 2.5, "wrapped past 4.0"); + /// assert_eq!(transport.position(100.0), 3.0); + /// assert!(transport.is_playing(100.0), "a loop never ends"); + /// + /// // backwards wraps the other way + /// transport.play(-1.0, 100.0); + /// assert_eq!(transport.position(100.5), 2.5); + /// assert_eq!(transport.position(101.5), 3.5, "wrapped below 2.0"); + /// + /// // an empty or backwards region is no region, and a long one is cut to the recording + /// transport.set_loop(Some((5.0, 5.0)), 101.5); + /// assert_eq!(transport.looping(), None); + /// transport.set_loop(Some((2.0, 99.0)), 101.5); + /// assert_eq!(transport.looping(), Some((2.0, 10.0))); + /// transport.set_loop(None, 101.5); + /// assert_eq!(transport.looping(), None); + /// ``` + /// + /// # Example: a playhead past the region is not looped + /// + /// ```rust + /// use komorebi_recorder::playback::Transport; + /// + /// let mut transport = Transport::new(10.0); + /// transport.set_loop(Some((2.0, 4.0)), 0.0); + /// transport.seek(8.0, 0.0); + /// transport.play(1.0, 0.0); + /// + /// assert_eq!(transport.position(100.0), 10.0, "it ran to the end"); + /// assert!(transport.is_playing(100.0)); + /// + /// // seeking into the region starts the loop + /// transport.seek(3.0, 100.0); + /// assert_eq!(transport.position(101.5), 2.5); + /// ``` + pub fn set_loop(&mut self, region: Option<(f64, f64)>, now: f64) { + self.settle(now); + self.looping = region + .map(|(from, to)| { + ( + from.clamp(0.0, self.duration_s), + to.clamp(0.0, self.duration_s), + ) + }) + .filter(|(from, to)| to > from); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn close(a: f64, b: f64) -> bool { + (a - b).abs() < 1e-9 + } + + #[test] + fn a_new_transport_is_paused_at_the_start() { + let transport = Transport::new(10.0); + assert!(close(transport.position(0.0), 0.0)); + assert!(close(transport.position(100.0), 0.0)); + assert!(!transport.is_playing(100.0)); + } + + #[test] + fn playing_advances_with_the_clock_not_with_frames() { + let mut transport = Transport::new(10.0); + transport.seek(2.0, 50.0); + transport.play(1.0, 50.0); + + assert!(close(transport.position(50.0), 2.0)); + assert!(close(transport.position(50.5), 2.5)); + assert!(close(transport.position(53.25), 5.25)); + assert!(transport.is_playing(53.25)); + } + + #[test] + fn the_speed_scales_the_movement_and_can_run_backwards() { + let mut transport = Transport::new(10.0); + transport.seek(5.0, 0.0); + transport.play(2.0, 0.0); + assert!(close(transport.position(1.0), 7.0)); + + transport.play(-0.5, 1.0); + assert!(close(transport.position(1.0), 7.0)); + assert!(close(transport.position(3.0), 6.0)); + assert!(transport.rate() < 0.0); + } + + #[test] + fn pausing_freezes_where_it_was() { + let mut transport = Transport::new(10.0); + transport.play(1.0, 0.0); + transport.pause(3.0); + + assert!(close(transport.position(3.0), 3.0)); + assert!(close(transport.position(99.0), 3.0)); + assert!(!transport.is_playing(99.0)); + + // resuming carries on from there at the same speed + transport.toggle(100.0); + assert!(close(transport.position(101.0), 4.0)); + } + + #[test] + fn it_stops_at_either_end() { + let mut transport = Transport::new(10.0); + transport.seek(8.0, 0.0); + transport.play(1.0, 0.0); + assert!(close(transport.position(5.0), 10.0)); + assert!(!transport.is_playing(5.0)); + + transport.seek(1.0, 6.0); + transport.play(-1.0, 6.0); + assert!(close(transport.position(9.0), 0.0)); + assert!(!transport.is_playing(9.0)); + } + + #[test] + fn playing_from_the_end_starts_over() { + let mut transport = Transport::new(10.0); + transport.seek(10.0, 0.0); + transport.play(1.0, 0.0); + assert!(close(transport.position(1.0), 1.0)); + + transport.seek(0.0, 2.0); + transport.play(-1.0, 2.0); + assert!(close(transport.position(3.0), 9.0)); + } + + #[test] + fn seeking_while_playing_keeps_playing_from_the_new_place() { + let mut transport = Transport::new(10.0); + transport.play(1.0, 0.0); + transport.seek(6.0, 2.0); + + assert!(transport.is_playing(2.0)); + assert!(close(transport.position(2.0), 6.0)); + assert!(close(transport.position(3.0), 7.0)); + + // and out of range is clamped, not an error + transport.seek(99.0, 3.0); + assert!(close(transport.position(3.0), 10.0)); + transport.seek(-5.0, 3.0); + assert!(close(transport.position(3.0), 0.0)); + } + + #[test] + fn a_region_repeats() { + let mut transport = Transport::new(10.0); + transport.set_loop(Some((2.0, 4.0)), 0.0); + transport.seek(3.0, 0.0); + transport.play(1.0, 0.0); + + assert!(close(transport.position(0.5), 3.5)); + assert!(close(transport.position(1.5), 2.5), "wrapped past 4.0"); + assert!(close(transport.position(100.0), 3.0)); + assert!(transport.is_playing(100.0), "a loop never ends"); + + // backwards wraps the other way + transport.play(-1.0, 100.0); + assert!(close(transport.position(100.5), 2.5)); + assert!(close(transport.position(101.5), 3.5), "wrapped below 2.0"); + } + + #[test] + fn playing_into_a_region_from_before_it_does_not_wrap_early() { + let mut transport = Transport::new(10.0); + transport.set_loop(Some((4.0, 6.0)), 0.0); + transport.seek(1.0, 0.0); + transport.play(1.0, 0.0); + + assert!(close(transport.position(2.0), 3.0)); + assert!(close(transport.position(4.0), 5.0)); + assert!( + close(transport.position(5.5), 4.5), + "wrapped once it passed the end of the region" + ); + } + + #[test] + fn a_degenerate_region_is_no_region() { + let mut transport = Transport::new(10.0); + transport.set_loop(Some((5.0, 5.0)), 0.0); + assert_eq!(transport.looping(), None); + transport.set_loop(Some((6.0, 3.0)), 0.0); + assert_eq!(transport.looping(), None); + transport.set_loop(Some((2.0, 99.0)), 0.0); + assert_eq!(transport.looping(), Some((2.0, 10.0))); + } + + #[test] + fn changing_the_speed_does_not_move_the_playhead_or_start_it() { + let mut transport = Transport::new(10.0); + transport.play(1.0, 0.0); + transport.set_rate(4.0, 2.0); + assert!(close(transport.position(2.0), 2.0)); + assert!(close(transport.position(3.0), 6.0)); + + transport.pause(3.0); + transport.set_rate(0.5, 4.0); + assert!(!transport.is_playing(5.0)); + assert!(close(transport.position(5.0), 6.0)); + assert!(close(transport.rate(), 0.5)); + + // out-of-range speeds are held to the limits + transport.set_rate(1000.0, 5.0); + assert!(close(transport.rate(), MAX_RATE)); + transport.set_rate(0.0, 5.0); + assert!(close(transport.rate(), MIN_RATE)); + } +}