feat(playback): seek 5s with arrow keys for local and cached tracks

Add Left/Right seek for file-backed sources (local files and cached
downloads). seek_to reopens and re-decodes the input, skips to the
target position, and clears the sample tap buffer; stream-first sources
return false and ignore the keys. Seek target is clamped to track
bounds and syncs elapsed time plus media-session playback state.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: program247365

README.md

@@ -222,12 +222,16 @@ Or just don't set it. Looper falls back to local-only without complaint.
 |-----|--------|
 | `Enter` | Replay the selected track from the default history browser |
 | `Space` | Pause / Resume |
+| `Left` / `Right` | Seek backward / forward 5 seconds |
 | `f` | Toggle fullscreen visualizer |
 | `s` | Toggle favorite for the currently playing track |
 | `p` | Toggle the played-songs panel |
 | `Cmd-P` | Attempt to toggle the played-songs panel when the terminal forwards the modifier |
 | `q` / `Ctrl-C` | Quit |
 
+Seeking is available for local files and cached downloads. Live or stream-first
+sources ignore the arrow keys.
+
 ### Played-Songs Panel
 
 Bare `looper` opens directly into playlist history. During playback, the played-songs panel is hidden by default and opens over the minimal UI.

docs/plans/2026-06-15-arrow-key-seek-design.md

@@ -0,0 +1,29 @@
+# Arrow-Key Seek Design
+
+## Goal
+
+During playback, pressing the right arrow seeks five seconds forward in the
+current track. Pressing the left arrow seeks five seconds backward.
+
+## Behavior
+
+- Arrow keys work on the normal playback screen.
+- The played-songs panel and default history browser keep their existing key
+  behavior.
+- Playlist navigation remains on `n` and `b`; arrow keys seek within the
+  current playlist track.
+- Seeking clamps at the start of the track and, when duration is known, the end
+  of the track.
+- Seeking applies to local files and cached downloads. Live or stream-first
+  sources without a local seekable file ignore the arrow keys.
+
+## Implementation
+
+Add seek-forward and seek-back commands to playback input handling, implement a
+small seek primitive in the audio player, and keep `AppState` elapsed-time
+tracking in sync with the new playback position.
+
+## Verification
+
+Add focused unit coverage for arrow-key command mapping and seek clamping.
+Run the Rust test suite after implementation.

src/audio.rs

@@ -152,6 +152,28 @@ impl AudioPlayer {
         self.sink.stop();
     }
 
+    pub fn seek_to(&self, position: Duration) -> Result<bool> {
+        if !matches!(self.input, PlaybackInput::File(_)) {
+            return Ok(false);
+        }
+
+        let (reader, _, _) = open_input(&self.input)?;
+        let source = decode_input(reader, &self.input)?
+            .convert_samples::<f32>()
+            .skip_duration(position);
+        let tapped = SampleTap {
+            inner: source,
+            buf: self.sample_buf.clone(),
+        };
+
+        self.sink.stop();
+        self.sink.append(tapped);
+        if let Ok(mut buf) = self.sample_buf.lock() {
+            buf.clear();
+        }
+        Ok(true)
+    }
+
     /// If this player loops a file-backed source and the sink has drained,
     /// reopen the file, decode a fresh source, and queue it. Returns true
     /// when a refill happened so the caller can advance its loop counter.

src/main.rs

@@ -60,6 +60,7 @@ PLAYBACK BEHAVIOR:
 TUI CONTROLS:
     q / Ctrl-C     Quit
     Space          Pause / resume
+    Left / Right   Seek backward / forward 5 seconds (local/cached)
     n              Next track (playlist mode)
     b              Previous track (playlist mode)
     f              Toggle fullscreen visualizer

src/play_loop.rs

@@ -31,6 +31,8 @@ use crate::tui::{
     HistoryPanelState, StartupProgressState, StartupScreenState, N_BANDS,
 };
 
+const SEEK_STEP: Duration = Duration::from_secs(5);
+
 pub struct PlaybackContext<'a> {
     pub cmd_rx: &'a Receiver<KeyCommand>,
     pub media: Option<MediaSessionHandle>,
@@ -158,6 +160,8 @@ fn browse_history_session(
                     | KeyCommand::TogglePause
                     | KeyCommand::NextTrack
                     | KeyCommand::PreviousTrack
+                    | KeyCommand::SeekForward
+                    | KeyCommand::SeekBackward
                     | KeyCommand::ToggleFullscreen
                     | KeyCommand::ToggleFavorite
                     | KeyCommand::ToggleHistory => {}
@@ -348,7 +352,8 @@ fn run_loop(
     ctx: &PlaybackContext,
 ) -> Result<LoopAction> {
     // Frame rate control: only render when needed
-    const RENDER_FPS: u64 = 30; // Target 30 FPS while playing
+    // Target 30 FPS while playing.
+    const RENDER_FPS: u64 = 30;
     // The paused screensaver's slowest sinusoid cycles every ~13s, so a few
     // frames per second is indistinguishable to the eye and keeps idle CPU low.
     const RENDER_FPS_PAUSED: u64 = 4;
@@ -486,6 +491,16 @@ fn dispatch_command(
                 Ok(None)
             }
         }
+        KeyCommand::SeekForward => {
+            seek_track(state, player, SeekDirection::Forward, media)?;
+            *needs_render = true;
+            Ok(None)
+        }
+        KeyCommand::SeekBackward => {
+            seek_track(state, player, SeekDirection::Backward, media)?;
+            *needs_render = true;
+            Ok(None)
+        }
         KeyCommand::ToggleFullscreen => {
             state.fullscreen = !state.fullscreen;
             *needs_render = true;
@@ -576,13 +591,63 @@ fn dispatch_command(
     }
 }
 
+#[derive(Clone, Copy)]
+enum SeekDirection {
+    Backward,
+    Forward,
+}
+
+fn seek_track(
+    state: &mut AppState,
+    player: &AudioPlayer,
+    direction: SeekDirection,
+    media: Option<&MediaSessionHandle>,
+) -> Result<()> {
+    let target = seek_target(state.elapsed(), direction, state.duration);
+    if !player.seek_to(target)? {
+        return Ok(());
+    }
+
+    set_elapsed(state, target);
+    if let Some(media) = media {
+        media.set_playback(state.paused, state.elapsed());
+    }
+    Ok(())
+}
+
+fn seek_target(
+    current: Duration,
+    direction: SeekDirection,
+    duration: Option<Duration>,
+) -> Duration {
+    let target = match direction {
+        SeekDirection::Backward => current.saturating_sub(SEEK_STEP),
+        SeekDirection::Forward => current + SEEK_STEP,
+    };
+
+    match duration {
+        Some(duration) => target.min(duration),
+        None => target,
+    }
+}
+
+fn set_elapsed(state: &mut AppState, elapsed: Duration) {
+    if state.paused {
+        state.pause_elapsed = elapsed;
+    } else {
+        state.loop_start = Instant::now() - elapsed;
+    }
+}
+
 #[derive(Debug, Eq, PartialEq)]
 pub(crate) enum KeyCommand {
     None,
     Quit,
     TogglePause,
     NextTrack,
     PreviousTrack,
+    SeekForward,
+    SeekBackward,
     ToggleFullscreen,
     ToggleFavorite,
     ToggleHistory,
@@ -619,6 +684,8 @@ fn handle_key_event(key: KeyEvent, state: &AppState) -> KeyCommand {
             (KeyCode::Char(' '), _) => KeyCommand::TogglePause,
             (KeyCode::Char('n'), _) => KeyCommand::NextTrack,
             (KeyCode::Char('b'), _) => KeyCommand::PreviousTrack,
+            (KeyCode::Right, _) => KeyCommand::SeekForward,
+            (KeyCode::Left, _) => KeyCommand::SeekBackward,
             (KeyCode::Char('f'), _) => KeyCommand::ToggleFullscreen,
             (KeyCode::Char('s'), _) => KeyCommand::ToggleFavorite,
             (KeyCode::Char('p'), modifiers) if modifiers.contains(KeyModifiers::SUPER) => {
@@ -1429,6 +1496,43 @@ mod tests {
         );
     }
 
+    #[test]
+    fn arrow_keys_seek_during_playback() {
+        let state = base_state();
+        assert_eq!(
+            handle_key_event(KeyEvent::new(KeyCode::Right, KeyModifiers::NONE), &state),
+            KeyCommand::SeekForward
+        );
+        assert_eq!(
+            handle_key_event(KeyEvent::new(KeyCode::Left, KeyModifiers::NONE), &state),
+            KeyCommand::SeekBackward
+        );
+    }
+
+    #[test]
+    fn seek_target_clamps_to_track_bounds() {
+        assert_eq!(
+            seek_target(
+                Duration::from_secs(2),
+                SeekDirection::Backward,
+                Some(Duration::from_secs(30))
+            ),
+            Duration::from_secs(0)
+        );
+        assert_eq!(
+            seek_target(
+                Duration::from_secs(28),
+                SeekDirection::Forward,
+                Some(Duration::from_secs(30))
+            ),
+            Duration::from_secs(30)
+        );
+        assert_eq!(
+            seek_target(Duration::from_secs(28), SeekDirection::Forward, None),
+            Duration::from_secs(33)
+        );
+    }
+
     #[test]
     fn history_uses_vim_keys() {
         let mut state = base_state();
@@ -1478,6 +1582,14 @@ mod tests {
             ),
             KeyCommand::HistorySortNext
         );
+        assert_eq!(
+            handle_key_event(KeyEvent::new(KeyCode::Right, KeyModifiers::NONE), &state),
+            KeyCommand::None
+        );
+        assert_eq!(
+            handle_key_event(KeyEvent::new(KeyCode::Left, KeyModifiers::NONE), &state),
+            KeyCommand::None
+        );
     }
 
     #[test]