crabidy/architecture/seek.md

Seek within the playing track

Context

Playback exposes track-level controls only: TogglePlay, Next, Prev, RestartTrack. There is no way to move inside a track, which hurts most where tracks are longest — the podcast providers (/rss, /fyyd) and audiobooks (/abs), where "I missed that sentence" and "skip the ad" are the two most common wishes.

The audio engine can already do it: PlayerEngine::seek_to and PlayerEngineCommand::SeekTo exist and are wired through Player::seek_to. Nothing calls them. There is no RPC, no playback command, no binding — and the one implementation that exists carries a panic (D5). So this feature is almost entirely wiring, plus a decision about where the arithmetic lives.

Goal: a step of about 15 seconds forward and backward, from every client.

Assumptions

Stated explicitly and settled by reading the code rather than by asking:

• A1 — Within the current track only. A backward seek at 3 s lands at 0, it does not step into the previous track; < / Ctrl-p are the track-level controls and stay that way. Crossing tracks would need the queue lock and the previous track's duration, for a gesture nobody expects to do that.
• A2 — The server owns the position. Clients render TrackPosition from the update stream and never predict it, exactly as they do for volume and play state. A seek therefore needs no optimistic UI and no rollback when it is refused.
• A3 — Fire-and-forget. Like every other playback RPC, Seek returns as soon as the command is queued. A refused seek is a server-side warning, not a client-visible error (D7).
• A4 — No autoplay. Seeking with nothing loaded does nothing; it does not start the queue. TogglePlay and RestartTrack are the controls that resume an idle player.

Options

The only real question is where the arithmetic lives: a seek is relative ("15 seconds back"), but the engine seeks to an absolute position.

Option A — the client computes the target

Seek(position_millis). Each client takes the last TrackPosition it received, adds ±15 s, clamps against the duration it was told, and sends an absolute target.

• The wire is a plain absolute seek, which a click on the progress bar maps onto directly. (That turned out not to need it either — see D10.)
• But the base is stale: positions are broadcast on a 250 ms tick and then cross the network. The step is 15 s, so 250 ms of drift is not the problem — repetition is. Press . three times quickly and all three presses read the same broadcast position, compute the same target, and the track advances 15 s instead of 45. That is the normal way people use a seek key.
• Every client re-implements clamping, so the end-of-track and unknown-duration edges have to be right in three places (TUI, web, CLI) instead of one.
• While paused no position updates arrive at all (the tick loop skips a paused sink), so a client's base position goes stale the moment you pause, and a paused seek would be computed from wherever playback stopped rather than from where the last seek left it.

Option B — the client sends a delta (chosen)

Seek(delta_millis), signed. The engine adds it to the live sink position, clamps, and seeks.

• Repeated presses compose exactly: each one reads the position the previous one produced, because the engine is a single-threaded command loop and try_seek updates the position before returning.
• Clamping policy lives in one place, next to the duration the engine already tracks.
• Clients get simpler, not more complex: a constant and one RPC call.
• Cost: absolute seek is not on the wire. A compatible proto3 addition if something ever needs it; click-to-seek did not (D10).

Decision: Option B. The composition argument decides it — Option A is wrong in the ordinary case of pressing the key twice.

Decisions

• D1 — The delta crosses the wire; the engine accumulates. Clients send a signed offset, never a target.

• D2 — One new RPC, relative only. Seek(SeekRequest) -> SeekResponse with sint32 delta_millis = 1. Milliseconds because TrackPosition already speaks milliseconds, so a future sub-second step needs no wire change; sint32 because zigzag encoding keeps negatives at one byte. Absolute seek stays deferred — adding a field later is compatible.

• D3 — The step size is a client constant. SEEK_STEP = 15 s, one named constant per client. The wire carries milliseconds, so making the step configurable later is a client-only change.

• D4 — Clamping. Backward past the start lands at 0. Forward past the end clamps to duration - 1 s when the duration is known, so the track runs out through the ordinary end-of-stream path and advances to the next one; the engine never has to seek to the exact end, whose behaviour differs per decoder. With an unknown duration (a length-less stream reports 0) there is no upper clamp — the decoder decides, and a refusal is just a warning.

• D5 — Fix the panic in seek_to. It currently does time.clamp(Duration::from_secs(1), duration). Ord::clamp asserts min <= max, and duration() yields 0 whenever the duration is unknown (HLS, some network streams) — so that call panics the engine thread, taking audio down with it, on any duration-less source. It is unreachable today only because nothing calls seek_to; wiring seek makes it reachable from user input, which the hard rules forbid. Replaced by saturating arithmetic with no assertions. The 1-second floor also went: landing at 0 is exactly what a backward seek near the start means.

• D6 — The engine reports the new position immediately. After a successful seek it emits PlayerMessage::Elapsed rather than waiting for the next 250 ms tick. This is not just about latency: tick() returns early for a paused or empty sink, so without this a seek while paused would leave every client showing the old position until playback resumed.

• D7 — Unseekable sources warn and change nothing. HLS (SoundCloud) is decoded with seekable = false precisely so symphonia never seeks it, and try_seek reports NotSupported. The server logs a warning and broadcasts nothing; clients keep showing the true position because they never moved it (A2). Consistent with how pause and set_volume failures are handled — no new status codes, no new client-side error path.

• D8 — Bindings: two physical keys carry all four moves. ,/. seek 15 seconds back/forward and their shifted forms </> skip a whole track, in the global scope of both clients. The pair is self-teaching (same key, shift = bigger jump), </> are the marks engraved on those keys, and they match mpv's playlist controls. Settled after two rounds: ,/., then Ctrl-b/Ctrl-f at the user's request, then back once </> earned their place for a separate reason (below).

  The deciding property is that these are plain printable characters, so they collide with nothing a browser reserves. Ctrl-n — the long-standing "next track" — cannot be claimed in a browser at all: Chrome and Firefox handle it as "new window" above the page, where preventDefault cannot reach, unlike Ctrl-f, Ctrl-p or Ctrl-b. Reaching for the reserved-chord list is a trap the alphabetic keys avoid entirely. Ctrl-n/Ctrl-p stay bound as the terminal's primary chords (and Ctrl-p works in the browser too); the web help documents </>, the ones that always work.

• D9 — No feature flag. Seek is a few lines in the engine and one RPC arm; it carries no dependency of its own, so by the rule in architecture/build-features.md ("a feature must pay for itself in dependencies") it does not earn one.

• D10 — The web progress bar is clickable, still as an offset. A click maps the pointer's x within the gauge to a fraction of the duration and sends target - position. Relative is right here even though the gesture is absolute: the position it subtracts is the one drawn on the bar the user just aimed at, and it is at most one 250 ms tick stale — far under one pixel of the bar for any track worth seeking in. (The same staleness is fatal for a repeated key, which is why keys send a fixed step; see the Options section.) So click-to-seek needs no absolute field on the wire after all. The arithmetic lives in state.rs as a pure function, so it is unit-tested on the native target rather than only in a browser; geometry comes from current_target because the click may land on the fill rather than the track; a duration of 0 declines the click, since a bar with no scale has no position to click at.

  The web transport bar also gets ⏪/⏩ buttons, and the CLI gets cbd global seek <SECONDS>, which accepts negatives.

Structure

direction: right

clients: Clients {
  tui: cbd-tui\n`,` / `.`
  web: cbd-web\n`,` / `.` / ⏪⏩
  cli: cbd-cli\nglobal seek N
}

server: crabidy-server {
  rpc: RpcService::seek
  loop: playback loop\nPlaybackCommand::Seek
  fwd: poll_play_bus
}

engine: audio-player {
  player: Player::seek_by
  eng: PlayerEngine\nseek_by -> seek_clamped
  sink: rodio Player\ntry_seek
}

clients.tui -> server.rpc: Seek{delta_millis}
clients.web -> server.rpc: Seek{delta_millis}
clients.cli -> server.rpc: Seek{delta_millis}
server.rpc -> server.loop: bounded channel
server.loop -> engine.player: seek_by(delta)
engine.player -> engine.eng: SeekBy(delta, reply)
engine.eng -> engine.sink: try_seek(clamped target)
engine.eng -> server.fwd: PlayerMessage::Elapsed
server.fwd -> server.loop: PositionChanged
server.loop -> clients: TrackPosition broadcast

The delta stays a delta all the way down to the engine; the only place an absolute position is computed is PlayerEngine::seek_by, which is also the only place that knows the live sink position and the track duration.

Boundaries

• audio-player gains Player::seek_by(delta_millis: i64) and PlayerEngineCommand::SeekBy. The clamping helper is private; both seek_to (absolute, kept for the deferred extension) and seek_by go through it, so there is one clamping policy, not two.
• crabidy-core gains the Seek RPC and its two messages.
• crabidy-server gains PlaybackCommand::Seek { delta_millis } and the RPC arm. The playback loop only forwards; it holds no seek state.
• Clients gain an action, a binding, an RPC wrapper, and a constant each. No client-side position arithmetic anywhere (A2, D1).

Risks

• try_seek blocks the engine thread for up to ~5 ms (it waits for the audio callback to pick the order up). That thread already blocks for up to 30 s opening a network stream, so this is not a new class of stall — but it does mean seek is serialized behind an in-flight track open, which is correct anyway.
• Seeking while paused relies on rodio's periodic_access sitting outside pausable in the chain: a paused sink keeps being polled for silence, so the seek order is still picked up. Verified in rodio 0.22.2 (src/player.rs); if a future rodio inverts that order, a paused seek would block until unpause. Worth re-checking on a rodio bump.
• Network-backed sources seek inside stream_download's temp storage. A seek outside the downloaded window triggers a fresh range request, so a long forward seek can stall audio briefly. Bounded by the existing HTTP timeouts; no new failure mode.
• A 15-second step on a very short track always lands in the clamp, which is why the clamp has to be arithmetic that cannot assert (D5).

Deferred

Recorded, not dropped:

• Absolute seek (position_millis). Click-to-seek shipped without it (D10), so the only remaining use would be a client that wants to name a position without knowing the current one. A compatible proto3 addition if that ever appears.
• Configurable step size in the client configs, and a larger step on </> (same physical keys, shifted). Client-only once wanted.
• Chapter-aware seek for podcasts and audiobooks. No provider exposes chapter marks through the library model today.