PlayheadClock: transcript follows the show #5

New issue

Closed

opened 2026-08-09 20:42:21 +00:00 by aiko · 1 comment

aiko commented

2026-08-09 20:42:21 +00:00

Owner

Parent

#1 — PRD: Kurageyomi

What to build

The transcript follows the show. This is the slice the first four exist to reach.

Add PlayheadClock: it combines the last reported position, wall-clock elapsed time since that
report, and paused state into a current position, and selects the Cue covering it. Pure and
testable — no network, no DOM at its boundary.

The page highlights the current Cue and keeps it in view, and holds a wake lock while playback
is running so the screen does not sleep mid-episode.

The reason interpolation is necessary: reports arrive on a 10-second throttle while playing, so
without a local clock the phone shows text up to ten seconds stale. Pause, unpause, and seeks
beyond about 5 seconds of drift arrive immediately, so those are resync points — the clock
should snap to them rather than easing toward them.

This slice answers the open question in the PRD: whether interpolated position feels tight
enough to read along with in practice. That is a judgement made by watching an episode with it,
not by a passing test. If it feels wrong, say so on this issue before building anything on top
of it — the answer changes what the rest of the app should be.

Acceptance criteria

PlayheadClock interpolates between reports using wall-clock elapsed time
A paused Playback Session freezes the clock rather than drifting forward
A seek snaps the clock to the new position immediately
Cue selection is correct at exact Cue boundaries
A report that is never superseded does not run the clock past the end of the media
The current Cue is highlighted and scrolled into view on the phone
The screen stays awake while playback is running, and the lock is released when it stops
PlayheadClock has tests covering the above with injected time
A verdict is recorded on this issue on whether reading along actually feels right

Blocked by

## Parent #1 — PRD: Kurageyomi ## What to build The transcript follows the show. This is the slice the first four exist to reach. Add `PlayheadClock`: it combines the last reported position, wall-clock elapsed time since that report, and paused state into a current position, and selects the Cue covering it. Pure and testable — no network, no DOM at its boundary. The page highlights the current Cue and keeps it in view, and holds a wake lock while playback is running so the screen does not sleep mid-episode. The reason interpolation is necessary: reports arrive on a 10-second throttle while playing, so without a local clock the phone shows text up to ten seconds stale. Pause, unpause, and seeks beyond about 5 seconds of drift arrive immediately, so those are resync points — the clock should snap to them rather than easing toward them. **This slice answers the open question in the PRD**: whether interpolated position feels tight enough to read along with in practice. That is a judgement made by watching an episode with it, not by a passing test. If it feels wrong, say so on this issue before building anything on top of it — the answer changes what the rest of the app should be. ## Acceptance criteria - [ ] `PlayheadClock` interpolates between reports using wall-clock elapsed time - [ ] A paused Playback Session freezes the clock rather than drifting forward - [ ] A seek snaps the clock to the new position immediately - [ ] Cue selection is correct at exact Cue boundaries - [ ] A report that is never superseded does not run the clock past the end of the media - [ ] The current Cue is highlighted and scrolled into view on the phone - [ ] The screen stays awake while playback is running, and the lock is released when it stops - [ ] `PlayheadClock` has tests covering the above with injected time - [ ] A verdict is recorded on this issue on whether reading along actually feels right ## Blocked by - #3 - #4

aiko added the

ready-for-agent

label

2026-08-09 20:42:21 +00:00

aiko referenced this issue from a commit

2026-08-09 23:11:14 +00:00

feat: phone follows a live Playback Session

aiko referenced this issue

2026-08-09 23:11:53 +00:00

Deploy the plugin to dionysus and verify on the Pixel #6

aiko commented

2026-08-10 08:10:19 +00:00

Author

Owner

This was generated by AI during triage.

Verdict given after watching: interpolating between the ten-second reports is tight enough to read along with. This was the riskiest assumption in the design and it holds.

The transcript-reset bug found during that session is fixed — the following screen was rebuilt on every 2s poll, discarding the scroll position, after which the highlight scrolled back to the current line. It is now built once and updated in place, with the cue list swapped only when the transcript actually changes.

Remaining imperfection is pause/unpause lag, which is polling latency rather than the clock. Tracked in #7.

> *This was generated by AI during triage.* Verdict given after watching: interpolating between the ten-second reports is tight enough to read along with. This was the riskiest assumption in the design and it holds. The transcript-reset bug found during that session is fixed — the following screen was rebuilt on every 2s poll, discarding the scroll position, after which the highlight scrolled back to the current line. It is now built once and updated in place, with the cue list swapped only when the transcript actually changes. Remaining imperfection is pause/unpause lag, which is polling latency rather than the clock. Tracked in #7.

aiko closed this issue

2026-08-10 08:10:19 +00:00