Resume/bookmark playback position for sequential channels (personal continue-watching) #68

Closed
opened 2026-07-01 23:02:11 +02:00 by timothy · 4 comments
Owner

Part of #62 context, but reframed — this is NOT "always-on vs on-demand / stream running" and NOT dizqueTV's wall-clock rewind-simulation. It is a personal resume/bookmark for sequential channels.

Goal

For a channel of sequential content (e.g. a Breaking Bad channel), the channel remembers where the viewer stopped and resumes there on next tune-in — like Plex "Continue Watching," but presented as a linear channel.

Behavior

  • Watch the channel, get partway through an episode, stop.
  • A week later, tune in → it resumes exactly where you left off (optionally rewound a minute or two for context).
  • On stop, it re-saves the new position for next time.
  • Applies to sequential/chronological channels; a per-channel (and ideally per-viewer) saved playback position.

Prior art

Exists in PseudoTV (related to its "Pause Channel" / resume behavior — exact name to confirm) and the user has seen it in another IPTV tool (possibly ErsatzTV or Tunarr). So it's a proven concept to borrow.

⚠️ The make-or-break requirement: EPG must stay in sync with the resumed position

The user's real-world pain with an existing implementation: the EPG kept ticking on wall-clock time while the stream resumed from the saved position — so the guide showed e.g. S2E3 while tuning in actually played S1E1. The guide and the actual playback desynced, which defeats the feature.

Requirement: when a channel is in resume mode, the XMLTV/EPG must be generated from the paused/resumed playout timeline, not a free-running wall clock. The "now / next" the guide advertises must match exactly what a viewer gets on tune-in. This is the primary thing to get right and the main differentiator vs. existing implementations.

Investigation / open questions

  • IPTV streams are effectively stateless/broadcast; ErsatzTV needs to (a) detect when the viewer stops (session end) and record the position, and (b) on re-tune, start the playout from the saved position rather than the live wall-clock point.
  • EPG generation (ChannelGuide / GetChannelGuideHandler) must read the resume state so the guide reflects actual upcoming content, not elapsed wall-clock. Interaction with XmltvTimeZone/block behavior to verify.
  • Confirm how PseudoTV keeps its guide consistent (or whether it sidesteps EPG entirely).
  • Per-viewer vs per-channel: one household → per-channel may suffice; multi-viewer needs identity.
  • This is essentially an alternate playout mode: "advance only while watched," with the playout clock frozen when unwatched.

Scope

  • New playout mode / channel behavior: "sequential, resume where I left off," with a frozen-when-unwatched clock.
  • Persist playback position; hook stream start/stop to save/restore it.
  • EPG derived from the resume timeline (core requirement above).
  • UI: mark such channels; optionally show a resume indicator.

Related: #59, #62.

Done-when

  • Guide/EPG stays in sync with the resumed on-demand timeline (cached XMLTV rebuilt on thaw)
  • Tests: handler enqueues guide rebuild on shift + negative controls; PlayoutTimeShifter reports the shifted channel number
  • Docs updated (channels.md, domain-model.md, decisions.md)
  • Adversarial review passed
Part of #62 context, but **reframed** — this is NOT "always-on vs on-demand / stream running" and NOT dizqueTV's wall-clock rewind-simulation. It is a **personal resume/bookmark for sequential channels.** ## Goal For a channel of sequential content (e.g. a Breaking Bad channel), the channel remembers **where the viewer stopped** and resumes there on next tune-in — like Plex "Continue Watching," but presented as a linear channel. ## Behavior - Watch the channel, get partway through an episode, stop. - A week later, tune in → it **resumes exactly where you left off** (optionally rewound a minute or two for context). - On stop, it **re-saves** the new position for next time. - Applies to sequential/chronological channels; a per-channel (and ideally per-viewer) saved playback position. ## Prior art Exists in **PseudoTV** (related to its "Pause Channel" / resume behavior — exact name to confirm) and the user has seen it in another IPTV tool (possibly ErsatzTV or Tunarr). So it's a proven concept to borrow. ## ⚠️ The make-or-break requirement: EPG must stay in sync with the resumed position The user's real-world pain with an existing implementation: **the EPG kept ticking on wall-clock time while the stream resumed from the saved position** — so the guide showed e.g. S2E3 while tuning in actually played S1E1. The guide and the actual playback desynced, which defeats the feature. **Requirement:** when a channel is in resume mode, the **XMLTV/EPG must be generated from the paused/resumed playout timeline, not a free-running wall clock.** The "now / next" the guide advertises must match exactly what a viewer gets on tune-in. This is the primary thing to get right and the main differentiator vs. existing implementations. ## Investigation / open questions - IPTV streams are effectively stateless/broadcast; ErsatzTV needs to (a) detect when the viewer stops (session end) and record the position, and (b) on re-tune, start the playout from the saved position rather than the live wall-clock point. - **EPG generation** (`ChannelGuide` / `GetChannelGuideHandler`) must read the resume state so the guide reflects actual upcoming content, not elapsed wall-clock. Interaction with `XmltvTimeZone`/block behavior to verify. - Confirm how PseudoTV keeps its guide consistent (or whether it sidesteps EPG entirely). - Per-viewer vs per-channel: one household → per-channel may suffice; multi-viewer needs identity. - This is essentially an alternate playout mode: "advance only while watched," with the playout clock frozen when unwatched. ## Scope - New **playout mode / channel behavior**: "sequential, resume where I left off," with a frozen-when-unwatched clock. - Persist playback position; hook stream start/stop to save/restore it. - **EPG derived from the resume timeline** (core requirement above). - UI: mark such channels; optionally show a resume indicator. Related: #59, #62. ## Done-when - [x] Guide/EPG stays in sync with the resumed on-demand timeline (cached XMLTV rebuilt on thaw) - [x] Tests: handler enqueues guide rebuild on shift + negative controls; `PlayoutTimeShifter` reports the shifted channel number - [x] Docs updated (channels.md, domain-model.md, decisions.md) - [x] Adversarial review passed
timothy changed title from Investigate "always-on vs on-demand" playout mode for channels to Resume/bookmark playback position for sequential channels (personal continue-watching) 2026-07-01 23:44:43 +02:00
timothy added the contentenhancementpriority: high labels 2026-07-01 23:44:47 +02:00
timothy added priority: low and removed priority: high labels 2026-07-11 19:04:42 +02:00
Author
Owner

Claiming — design/investigation only, not implementation

Picked up as part of bundle B (closing out the #62 epic), but deliberately scoped down. Stating that up front so nobody reads this claim as "resume mode is being built."

Why: despite the "Part of #62" framing, this is not a peer of #67. The body describes a new playout mode — an "advance only while watched" playout clock that freezes when unwatched, persisted per-channel (per-viewer?) position, plus the make-or-break requirement that XMLTV/EPG be generated from the resumed timeline rather than a free-running wall clock (GetChannelGuideHandler). The body's own "Investigation / open questions" section is unresolved. Building that blind, in the same session as an image-upload convenience, is how a half-designed playout mode ships.

Deliverable this session: a design write-up posted to this issue — resume-state model and where it persists, how the EPG derives from the resumed timeline (the primary differentiator), per-channel vs per-viewer, and interaction with existing playout modes / XmltvTimeZone. Implementation follows as separate tracked work once that design is agreed.

Claim will be released with the design comment.

## Claiming — **design/investigation only**, not implementation Picked up as part of bundle B (closing out the #62 epic), but deliberately scoped down. Stating that up front so nobody reads this claim as "resume mode is being built." **Why**: despite the "Part of #62" framing, this is not a peer of #67. The body describes a **new playout mode** — an "advance only while watched" playout clock that freezes when unwatched, persisted per-channel (per-viewer?) position, plus the make-or-break requirement that **XMLTV/EPG be generated from the resumed timeline rather than a free-running wall clock** (`GetChannelGuideHandler`). The body's own "Investigation / open questions" section is unresolved. Building that blind, in the same session as an image-upload convenience, is how a half-designed playout mode ships. **Deliverable this session**: a design write-up posted to this issue — resume-state model and where it persists, how the EPG derives from the resumed timeline (the primary differentiator), per-channel vs per-viewer, and interaction with existing playout modes / `XmltvTimeZone`. Implementation follows as separate tracked work once that design is agreed. Claim will be released with the design comment.
timothy added the in-progress label 2026-07-20 19:26:57 +02:00
Author
Owner

Claim released — design NOT delivered, issue untouched

Claimed alongside #67 as part of a "close out the #62 epic" bundle, scoped to a design/investigation deliverable only. That design was not produced. Nothing here was started beyond reading the issue body; no code, no recon, no partial write-up. Releasing the claim so the next session picks this up clean.

Why it's being deferred rather than rushed: this is not a peer of #67. It needs a new playout mode with an "advance only while watched" clock that freezes when unwatched, persisted per-channel (per-viewer?) position, and — the make-or-break requirement in the body — an XMLTV/EPG derived from the resumed timeline instead of a free-running wall clock. Getting that wrong reproduces the exact bug the issue was filed about (guide advertising S2E3 while tune-in plays S1E1). It deserves a fresh session with its own recon of the playout timeline, the anchor/history model, and GetChannelGuideHandler, not the tail of an unrelated session.

One piece of context worth carrying forward (learned while working #67 in the same area): the closest existing analogue in the codebase is the mirror-channel mechanism (PlayoutSource.Mirror + PlayoutOffset), which already rebases one channel's timeline relative to another's — worth reading before designing a freeze/resume clock from scratch.

Still open, unblocked, and unclaimed.

## Claim released — design NOT delivered, issue untouched Claimed alongside #67 as part of a "close out the #62 epic" bundle, scoped to a design/investigation deliverable only. **That design was not produced.** Nothing here was started beyond reading the issue body; no code, no recon, no partial write-up. Releasing the claim so the next session picks this up clean. **Why it's being deferred rather than rushed**: this is not a peer of #67. It needs a new playout mode with an "advance only while watched" clock that freezes when unwatched, persisted per-channel (per-viewer?) position, and — the make-or-break requirement in the body — an **XMLTV/EPG derived from the resumed timeline instead of a free-running wall clock**. Getting that wrong reproduces the exact bug the issue was filed about (guide advertising S2E3 while tune-in plays S1E1). It deserves a fresh session with its own recon of the playout timeline, the anchor/history model, and `GetChannelGuideHandler`, not the tail of an unrelated session. **One piece of context worth carrying forward** (learned while working #67 in the same area): the closest existing analogue in the codebase is the mirror-channel mechanism (`PlayoutSource.Mirror` + `PlayoutOffset`), which already rebases one channel's timeline relative to another's — worth reading before designing a freeze/resume clock from scratch. Still open, unblocked, and unclaimed.
timothy removed the in-progress label 2026-07-20 21:40:33 +02:00
timothy added the in-progress label 2026-07-21 18:38:56 +02:00
Author
Owner

Claiming — design/investigation deliverable (per the prior claim's scope)

Picking this up as a design write-up, not implementation, exactly as the earlier claim intended. Session goal: resolve the open questions — resume-state model + persistence, EPG-derived-from-resumed-timeline (the make-or-break requirement), per-channel vs per-viewer, and interaction with existing playout modes / the mirror-channel PlayoutOffset rebasing machinery flagged by the prior session. Implementation to follow as separate tracked work once the design is agreed.

Starting with recon of the tune-in→PlayoutItem timing path, GetChannelGuideHandler, and the PlayoutSource.Mirror + PlayoutOffset mechanism.

## Claiming — design/investigation deliverable (per the prior claim's scope) Picking this up as a **design write-up**, not implementation, exactly as the earlier claim intended. Session goal: resolve the open questions — resume-state model + persistence, EPG-derived-from-resumed-timeline (the make-or-break requirement), per-channel vs per-viewer, and interaction with existing playout modes / the mirror-channel `PlayoutOffset` rebasing machinery flagged by the prior session. Implementation to follow as separate tracked work once the design is agreed. Starting with recon of the tune-in→PlayoutItem timing path, `GetChannelGuideHandler`, and the `PlayoutSource.Mirror` + `PlayoutOffset` mechanism.
Author
Owner

Closing record

Outcome: Shipped in PR #540 (branch fix/68-ondemand-guide-refresh, head dfed9a39). Merge pending — the only CI red is an unrelated flaky SPA test (LibrariesScreen.test.tsx:292, scan-polling waitFor timeout); needs an operator re-run of the Build & test (.NET) job. fixes #68 will auto-close this issue on merge.

Recon finding (the real story): the feature #68 describes already exists as PlayoutMode.OnDemand — Playout.OnDemandCheckpoint persists the viewer's position, UpdateOnDemandCheckpoint advances it while watching (minus one segmenter-timeout of rewind-for-context), and PlayoutTimeShifter.TimeShift slides the whole materialized timeline forward on tune-in so the paused item is active again. Because the shift rewrites GuideStart/GuideFinish alongside Start/Finish and both guide + playback read the same PlayoutItem rows, ErsatzTV freezes guide and playback together — structurally avoiding the free-running-wall-clock desync this issue was filed about.

Root cause of the residual gap: TimeShift rewrote the stored rows but the XMLTV guide is served from a cached .xml fragment that only RefreshChannelData rebuilds, and the tune-in path never enqueued it (build/config edits did). So an external EPG client (Jellyfin) polling after a thaw could see a stale timeline until the next incidental rebuild — a cache-freshness bug, not a timing-model flaw.

Files changed: IPlayoutTimeShifter.cs (returns List<string> — shifted channel + its mirrors), PlayoutTimeShifter.cs (mirror fan-out after a non-zero shift), TimeShiftOnDemandPlayoutHandler.cs (enqueue RefreshChannelData on CancellationToken.None), + PlayoutTimeShifterTests.cs / TimeShiftOnDemandPlayoutHandlerTests.cs (9 tests).

Decisions/conventions changed: added scheduling.ondemand-guide-refresh-on-thaw to docs/decisions.md.

Reusable knowledge: OnDemand PlayoutMode is the resume/bookmark feature; a mirror channel of an on-demand source needs its guide refreshed on the source's thaw (same fan-out BuildPlayoutHandler already does).

Verification: 1793 C# tests green (9 new; non-vacuity proven by a compiling negative control); the flaky SPA test passes 3/3 locally. Two cold adversarial reviews → MERGEABLE. Live-E2E not required (internal background MediatR command, not an /api/* write-path handler).

Deferred: per-viewer resume (single per-channel checkpoint; #68 says per-channel suffices for one household).

Docs updated: docs/channels.md (On-demand resume section), docs/domain-model.md, docs/decisions.md (+ regenerated catalog).

## Closing record **Outcome:** Shipped in PR #540 (branch `fix/68-ondemand-guide-refresh`, head `dfed9a39`). **Merge pending** — the only CI red is an unrelated flaky SPA test (`LibrariesScreen.test.tsx:292`, scan-polling `waitFor` timeout); needs an operator re-run of the `Build & test (.NET)` job. `fixes #68` will auto-close this issue on merge. **Recon finding (the real story):** the feature #68 describes already exists as `PlayoutMode.OnDemand` — `Playout.OnDemandCheckpoint` persists the viewer's position, `UpdateOnDemandCheckpoint` advances it while watching (minus one segmenter-timeout of rewind-for-context), and `PlayoutTimeShifter.TimeShift` slides the whole materialized timeline forward on tune-in so the paused item is active again. Because the shift rewrites `GuideStart/GuideFinish` alongside `Start/Finish` and both guide + playback read the same `PlayoutItem` rows, ErsatzTV **freezes guide and playback together** — structurally avoiding the free-running-wall-clock desync this issue was filed about. **Root cause of the residual gap:** `TimeShift` rewrote the stored rows but the XMLTV guide is served from a **cached** `.xml` fragment that only `RefreshChannelData` rebuilds, and the tune-in path never enqueued it (build/config edits did). So an external EPG client (Jellyfin) polling after a thaw could see a stale timeline until the next incidental rebuild — a cache-freshness bug, not a timing-model flaw. **Files changed:** `IPlayoutTimeShifter.cs` (returns `List<string>` — shifted channel + its mirrors), `PlayoutTimeShifter.cs` (mirror fan-out after a non-zero shift), `TimeShiftOnDemandPlayoutHandler.cs` (enqueue `RefreshChannelData` on `CancellationToken.None`), + `PlayoutTimeShifterTests.cs` / `TimeShiftOnDemandPlayoutHandlerTests.cs` (9 tests). **Decisions/conventions changed:** added `scheduling.ondemand-guide-refresh-on-thaw` to docs/decisions.md. **Reusable knowledge:** OnDemand PlayoutMode *is* the resume/bookmark feature; a mirror channel of an on-demand source needs its guide refreshed on the source's thaw (same fan-out `BuildPlayoutHandler` already does). **Verification:** 1793 C# tests green (9 new; non-vacuity proven by a compiling negative control); the flaky SPA test passes 3/3 locally. Two cold adversarial reviews → MERGEABLE. Live-E2E not required (internal background MediatR command, not an `/api/*` write-path handler). **Deferred:** per-viewer resume (single per-channel checkpoint; #68 says per-channel suffices for one household). **Docs updated:** docs/channels.md (On-demand resume section), docs/domain-model.md, docs/decisions.md (+ regenerated catalog).
timothy removed the in-progress label 2026-07-21 19:49:28 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#68