Jellyfin/Kodi PoC: player-owned channel playback with ErsatzTV as channel engine #357

Closed
opened 2026-07-14 20:59:41 +02:00 by timothy · 8 comments
Owner

Goal

Run a small, high-priority feasibility PoC for a possible new direction for this fork:

  • keep ErsatzTV as the channel, schedule, programming, API, and automation control plane;
  • add a Jellyfin plugin/integration path;
  • let the actual playback client direct-play/decode media whenever possible instead of sending a continuously transcoded stream through an ErsatzTV/FFmpeg middleman;
  • let Jellyfin negotiate a fallback transcode only when a client truly requires it.

The intended payoff is better video quality, playback stability, and resource use without losing the channel-surfing experience.

This is a PoC and go/no-go decision, not authorization for a rewrite.

Non-negotiable behavior to preserve

  • Virtual channel creation and editing.
  • Fast next/previous channel surfing.
  • Kodi support is mandatory: the current IPTV/PVR experience must remain viable, including M3U/XMLTV, EPG data, tuning, and channel switching.
  • Existing and planned API work remains first-class.
  • MCP/tooling support remains first-class rather than becoming a UI-only afterthought.
  • The channel-creation wizards and simpler programming workflow remain part of the direction.
  • Existing channel/schedule definitions must remain reusable.

PoC scope

Build the smallest vertical slice that can answer the architecture question:

  1. Expose at least two existing ErsatzTV-managed virtual channels through a Jellyfin plugin or adapter.
  2. Tune and surf those channels from Kodi with EPG data visible.
  3. Cross at least two scheduled-program boundaries using representative media.
  4. Demonstrate whether playback can use direct media/player-owned decoding without an ErsatzTV transcoder process in the path; document any Jellyfin/client transcode fallback.
  5. Compare startup time, channel-change time, A/V stability, observed quality, and server resource use with the current middleman path.
  6. Prototype configuration in Jellyfin, a separate web UI, or a deliberately split arrangement, while keeping one authoritative backend state.

Feasibility questions

  • Can Jellyfin's plugin/live-TV surfaces represent ErsatzTV channels, guide data, and the correct in-progress offset without manufacturing a continuous transcoded stream?
  • Can Kodi retain the existing IPTV Simple/PVR-style M3U/XMLTV experience, or would a Jellyfin-specific Kodi path be required?
  • How are scheduled program transitions, seeking into the current program, pause/resume, authentication, remote clients, and mixed media capabilities handled?
  • Which current channel, schedule, collection, API/auth, MCP, and SPA/wizard components can be reused unchanged?
  • Where must configuration live so Jellyfin and a separate web UI do not create competing sources of truth?

Reuse and migration safeguards

  • No destructive schema changes in the PoC.
  • Put the experimental playback path behind an explicit feature flag or isolated adapter.
  • Preserve existing API contracts and M3U/XMLTV behavior during evaluation.
  • Keep a per-client/per-channel fallback to the current playback path until a go decision.
  • Produce a component-by-component reuse matrix before proposing implementation.
  • Do not abandon or duplicate existing API/MCP/wizard work without an explicit migration plan.

Related but not duplicate: #178 (Jellyfin control/config integration), #176 (channel-first creation/wizards), and #58/#62 (MCP/API create-channel foundations).

Done when / go-no-go gate

  • A short architecture note identifies the Jellyfin and Kodi integration seams and the playback ownership model.
  • The vertical PoC demonstrates two virtual channels, EPG, Kodi tuning/channel surfing, and scheduled program transitions.
  • Direct/player-owned playback versus fallback transcoding is verified from the actual process/network path.
  • Quality, stability, channel-change latency, and server-resource observations are recorded against the current path.
  • A reuse matrix covers the current channel model, schedules/programming, API, MCP, wizards, and configuration UI.
  • Blocking gaps and required compromises are explicit, especially any loss of Kodi IPTV/EPG behavior.
  • A go/no-go recommendation and incremental migration/rollback plan are documented before implementation issues are opened.
## Goal Run a small, high-priority feasibility PoC for a possible new direction for this fork: - keep ErsatzTV as the channel, schedule, programming, API, and automation control plane; - add a Jellyfin plugin/integration path; - let the actual playback client direct-play/decode media whenever possible instead of sending a continuously transcoded stream through an ErsatzTV/FFmpeg middleman; - let Jellyfin negotiate a fallback transcode only when a client truly requires it. The intended payoff is better video quality, playback stability, and resource use without losing the channel-surfing experience. This is a PoC and go/no-go decision, not authorization for a rewrite. ## Non-negotiable behavior to preserve - Virtual channel creation and editing. - Fast next/previous channel surfing. - **Kodi support is mandatory**: the current IPTV/PVR experience must remain viable, including M3U/XMLTV, EPG data, tuning, and channel switching. - Existing and planned API work remains first-class. - MCP/tooling support remains first-class rather than becoming a UI-only afterthought. - The channel-creation wizards and simpler programming workflow remain part of the direction. - Existing channel/schedule definitions must remain reusable. ## PoC scope Build the smallest vertical slice that can answer the architecture question: 1. Expose at least two existing ErsatzTV-managed virtual channels through a Jellyfin plugin or adapter. 2. Tune and surf those channels from Kodi with EPG data visible. 3. Cross at least two scheduled-program boundaries using representative media. 4. Demonstrate whether playback can use direct media/player-owned decoding without an ErsatzTV transcoder process in the path; document any Jellyfin/client transcode fallback. 5. Compare startup time, channel-change time, A/V stability, observed quality, and server resource use with the current middleman path. 6. Prototype configuration in Jellyfin, a separate web UI, or a deliberately split arrangement, while keeping one authoritative backend state. ## Feasibility questions - Can Jellyfin's plugin/live-TV surfaces represent ErsatzTV channels, guide data, and the correct in-progress offset without manufacturing a continuous transcoded stream? - Can Kodi retain the existing IPTV Simple/PVR-style M3U/XMLTV experience, or would a Jellyfin-specific Kodi path be required? - How are scheduled program transitions, seeking into the current program, pause/resume, authentication, remote clients, and mixed media capabilities handled? - Which current channel, schedule, collection, API/auth, MCP, and SPA/wizard components can be reused unchanged? - Where must configuration live so Jellyfin and a separate web UI do not create competing sources of truth? ## Reuse and migration safeguards - No destructive schema changes in the PoC. - Put the experimental playback path behind an explicit feature flag or isolated adapter. - Preserve existing API contracts and M3U/XMLTV behavior during evaluation. - Keep a per-client/per-channel fallback to the current playback path until a go decision. - Produce a component-by-component reuse matrix before proposing implementation. - Do not abandon or duplicate existing API/MCP/wizard work without an explicit migration plan. Related but not duplicate: #178 (Jellyfin control/config integration), #176 (channel-first creation/wizards), and #58/#62 (MCP/API create-channel foundations). ## Done when / go-no-go gate - [ ] A short architecture note identifies the Jellyfin and Kodi integration seams and the playback ownership model. - [ ] The vertical PoC demonstrates two virtual channels, EPG, Kodi tuning/channel surfing, and scheduled program transitions. - [ ] Direct/player-owned playback versus fallback transcoding is verified from the actual process/network path. - [ ] Quality, stability, channel-change latency, and server-resource observations are recorded against the current path. - [ ] A reuse matrix covers the current channel model, schedules/programming, API, MCP, wizards, and configuration UI. - [ ] Blocking gaps and required compromises are explicit, especially any loss of Kodi IPTV/EPG behavior. - [ ] A go/no-go recommendation and incremental migration/rollback plan are documented before implementation issues are opened.
timothy added the enhancementapijellyfinpriority: highfrontend labels 2026-07-14 20:59:41 +02:00
timothy added the in-progress label 2026-07-14 21:02:32 +02:00
Author
Owner

Claiming #357 for the Jellyfin/Kodi player-owned playback feasibility PoC. I’ll keep the experiment isolated, preserve M3U/XMLTV/API behavior, document architecture/reuse findings and measured evidence, and run the project completion protocol before handoff.

Claiming #357 for the Jellyfin/Kodi player-owned playback feasibility PoC. I’ll keep the experiment isolated, preserve M3U/XMLTV/API behavior, document architecture/reuse findings and measured evidence, and run the project completion protocol before handoff.
Author
Owner

Done (phase-one feasibility slice; issue remains open)

What was done: Added the authenticated scheduled-source read and a standalone, default-off Jellyfin 12.0-rc2 Live TV probe; verified guide import, native Jellyfin source selection/transcoding, schedule offsets, one programme boundary, and playback-history behavior in a disposable loopback clone. PR #358 records a no-go for replacing the continuous stream with a server-plugin-only path on the current Jellyfin contract.

Root cause: n/a — architecture feasibility PoC. The blocking contract gaps are that ILiveTvService receives neither the schedule-derived initial offset nor a viewer/session identity, stock Jellyfin web tunes at zero, and Jellyfin does not retune an already-open native source at the EPG boundary.

Files changed: Scheduled playback-source API/DTO/handler/controller plus OpenAPI/generated types; standalone Jellyfin plugin and focused tests; architecture evidence, reuse matrix, decision, and rollback documentation.

Verification: Local full restore/build/test passed; final full solution test run passed (plugin 12/12, application 1599/1599, plus all other solution projects). Web API generation, lint, typecheck, 761 tests, and production build passed. Scoped formatting and diff checks passed. Exact-head cold review reported no findings at 97397906e3771baa68355248b3a6bf8f4d4733d0. Gitea Actions run #641 is green: .NET, SQLite/MySQL migration integrity, formatting, API-doc sync, decisions append-only, and docs reminder all passed; the PR-only image-push job skipped as designed. Disposable containers, volumes, images, snapshots, binaries, and helper scripts were removed.

Deferred: Kodi implementation/tuning, a second boundary, finite-file EOF, long A/V stability, and visual comparison were deliberately stopped because initial position and the first clean boundary had already failed the required architecture. Per-user backing-library authorization also remains unavailable through this provider seam. Retain the existing M3U/XMLTV continuous path.

Follow-up issues: None opened. Keep #357 open under its original acceptance gate; reconsider only after an upstream Jellyfin offset/session/transition seam or a deliberately thin client companion is proven.

Docs updated: docs/player-owned-playback-poc.md, docs/decisions.md, the docs index, endpoint index, and plugin README.

PR: #358

## Done (phase-one feasibility slice; issue remains open) **What was done**: Added the authenticated scheduled-source read and a standalone, default-off Jellyfin 12.0-rc2 Live TV probe; verified guide import, native Jellyfin source selection/transcoding, schedule offsets, one programme boundary, and playback-history behavior in a disposable loopback clone. PR #358 records a **no-go** for replacing the continuous stream with a server-plugin-only path on the current Jellyfin contract. **Root cause**: n/a — architecture feasibility PoC. The blocking contract gaps are that `ILiveTvService` receives neither the schedule-derived initial offset nor a viewer/session identity, stock Jellyfin web tunes at zero, and Jellyfin does not retune an already-open native source at the EPG boundary. **Files changed**: Scheduled playback-source API/DTO/handler/controller plus OpenAPI/generated types; standalone Jellyfin plugin and focused tests; architecture evidence, reuse matrix, decision, and rollback documentation. **Verification**: Local full restore/build/test passed; final full solution test run passed (plugin 12/12, application 1599/1599, plus all other solution projects). Web API generation, lint, typecheck, 761 tests, and production build passed. Scoped formatting and diff checks passed. Exact-head cold review reported no findings at `97397906e3771baa68355248b3a6bf8f4d4733d0`. Gitea Actions run #641 is green: .NET, SQLite/MySQL migration integrity, formatting, API-doc sync, decisions append-only, and docs reminder all passed; the PR-only image-push job skipped as designed. Disposable containers, volumes, images, snapshots, binaries, and helper scripts were removed. **Deferred**: Kodi implementation/tuning, a second boundary, finite-file EOF, long A/V stability, and visual comparison were deliberately stopped because initial position and the first clean boundary had already failed the required architecture. Per-user backing-library authorization also remains unavailable through this provider seam. Retain the existing M3U/XMLTV continuous path. **Follow-up issues**: None opened. Keep #357 open under its original acceptance gate; reconsider only after an upstream Jellyfin offset/session/transition seam or a deliberately thin client companion is proven. **Docs updated**: `docs/player-owned-playback-poc.md`, `docs/decisions.md`, the docs index, endpoint index, and plugin README. PR: https://gitea.tblindustries.be/timothy/ersatztv/pulls/358
timothy removed the in-progress label 2026-07-15 20:30:48 +02:00
Author
Owner

Parked architecture options after the live PoC

This records the three paths discussed after the stock Jellyfin result. It preserves the research; it does not authorize implementation. In every path, ChicoryTV remains authoritative for channels, schedules, wizards, advanced configuration, API, and MCP. Jellyfin-side configuration should stay minimal.

1. Preferred contingency: private Jellyfin Live TV fork

Continue using Jellyfin's existing Live TV guide, channel UI, virtual-channel session/history behavior, and native direct-play/transcode pipeline. Maintain a small private patch stack across Jellyfin server/model and jellyfin-web:

  • add an optional provider capability, without changing existing ILiveTvService implementations, carrying current schedule offset, next transition, and user/session context;
  • have patched web playback start at that offset and reopen the channel at the transition;
  • define simple linear-TV semantics for finite backing files: the channel clock wins; tune/resume/boundary resolves whatever is airing now, and channel changes cancel old transition state.

The boundary work is still needed even though native Live TV is reused: its current stream model expects one continuous/infinite source, while this path replaces finite library files. A paused or buffered viewer can therefore be behind the wall-clock EPG unless the fork defines the rule above. Other Jellyfin clients remain stock and would not gain these semantics unless patched too.

Expected cost is moderate initial work, not a Jellyfin rewrite: additive server/model hooks, web-player behavior, tests, and a custom image. Small upstream releases may accept the commits unchanged, but every upgrade still needs a rebuild and live smoke test; major playback/Live TV refactors may require rebasing. Do not depend on upstream acceptance.

2. Backup: plugin-backed ChicoryTV TV-mode web UI

Ignore Jellyfin Live TV and provide a dedicated EPG/channel-player experience that owns channel surfing, current-item offset, and boundary switching while using normal Jellyfin playback/transcoding. This avoids a Jellyfin fork but owns substantially more client/UI behavior. Official mobile/TV clients would not inherit it, and backing-item history suppression would need an explicit design.

3. Current fallback: keep ErsatzTV transport and tune it

Retain the supported continuous M3U/XMLTV path for Jellyfin/Kodi and create a separate performance-tuning backlog item. Measure actual FFmpeg commands, startup/channel-change latency, CPU/GPU, buffering, and quality before changing remux/direct-stream opportunities, hardware acceleration, presets, GOP/keyframes, segment sizing, audio, or subtitle behavior.

Decision / status

Park all three implementation directions for now and return to the main handoff/queue. #357 remains open/parked as the research record. PR #358 remains an evidence/probe PR; this comment neither merges it nor turns the probe into a supported product surface.

## Parked architecture options after the live PoC This records the three paths discussed after the stock Jellyfin result. It preserves the research; it does **not** authorize implementation. In every path, ChicoryTV remains authoritative for channels, schedules, wizards, advanced configuration, API, and MCP. Jellyfin-side configuration should stay minimal. ### 1. Preferred contingency: private Jellyfin Live TV fork Continue using Jellyfin's existing Live TV guide, channel UI, virtual-channel session/history behavior, and native direct-play/transcode pipeline. Maintain a small private patch stack across Jellyfin server/model and `jellyfin-web`: - add an optional provider capability, without changing existing `ILiveTvService` implementations, carrying current schedule offset, next transition, and user/session context; - have patched web playback start at that offset and reopen the channel at the transition; - define simple linear-TV semantics for finite backing files: the channel clock wins; tune/resume/boundary resolves whatever is airing now, and channel changes cancel old transition state. The boundary work is still needed even though native Live TV is reused: its current stream model expects one continuous/infinite source, while this path replaces finite library files. A paused or buffered viewer can therefore be behind the wall-clock EPG unless the fork defines the rule above. Other Jellyfin clients remain stock and would not gain these semantics unless patched too. Expected cost is moderate initial work, not a Jellyfin rewrite: additive server/model hooks, web-player behavior, tests, and a custom image. Small upstream releases may accept the commits unchanged, but every upgrade still needs a rebuild and live smoke test; major playback/Live TV refactors may require rebasing. Do not depend on upstream acceptance. ### 2. Backup: plugin-backed ChicoryTV TV-mode web UI Ignore Jellyfin Live TV and provide a dedicated EPG/channel-player experience that owns channel surfing, current-item offset, and boundary switching while using normal Jellyfin playback/transcoding. This avoids a Jellyfin fork but owns substantially more client/UI behavior. Official mobile/TV clients would not inherit it, and backing-item history suppression would need an explicit design. ### 3. Current fallback: keep ErsatzTV transport and tune it Retain the supported continuous M3U/XMLTV path for Jellyfin/Kodi and create a separate performance-tuning backlog item. Measure actual FFmpeg commands, startup/channel-change latency, CPU/GPU, buffering, and quality before changing remux/direct-stream opportunities, hardware acceleration, presets, GOP/keyframes, segment sizing, audio, or subtitle behavior. ### Decision / status Park all three implementation directions for now and return to the main handoff/queue. #357 remains open/parked as the research record. PR #358 remains an evidence/probe PR; this comment neither merges it nor turns the probe into a supported product surface.
timothy added the in-progress label 2026-07-16 16:23:47 +02:00
Author
Owner

Claiming this issue for the current queue session. I’ll start with bounded architecture and feasibility reconnaissance, define the smallest vertical PoC and its measurement plan, then implement and verify the slice against the issue’s go/no-go criteria. I’ll record any environment-dependent blocker explicitly rather than broadening the experiment.

Claiming this issue for the current queue session. I’ll start with bounded architecture and feasibility reconnaissance, define the smallest vertical PoC and its measurement plan, then implement and verify the slice against the issue’s go/no-go criteria. I’ll record any environment-dependent blocker explicitly rather than broadening the experiment.
Author
Owner

Releasing this claim after reading the issue comments. The completed phase-one PoC already records the current server-plugin path as a no-go, and the later architecture note explicitly parks all three follow-on implementation directions and says it does not authorize implementation. Proceeding would therefore expand scope beyond the issue’s current authorization. No code or issue state beyond this temporary claim was changed.

Releasing this claim after reading the issue comments. The completed phase-one PoC already records the current server-plugin path as a no-go, and the later architecture note explicitly parks all three follow-on implementation directions and says it does not authorize implementation. Proceeding would therefore expand scope beyond the issue’s current authorization. No code or issue state beyond this temporary claim was changed.
timothy removed the in-progress label 2026-07-16 16:24:37 +02:00
timothy added the in-progress label 2026-07-16 18:32:03 +02:00
Author
Owner

Claiming this for the current ChicoryTV queue session. I’ll first reconcile the existing discussion with the live Jellyfin/Kodi integration surfaces, then build the smallest isolated, reversible vertical PoC and report evidence against every go/no-go criterion. No rewrite or destructive schema change is implied by this claim.

Claiming this for the current ChicoryTV queue session. I’ll first reconcile the existing discussion with the live Jellyfin/Kodi integration surfaces, then build the smallest isolated, reversible vertical PoC and report evidence against every go/no-go criterion. No rewrite or destructive schema change is implied by this claim.
timothy added parked and removed in-progress labels 2026-07-16 18:33:27 +02:00
Author
Owner

Releasing today’s automatic queue claim after operator clarification: this is a parked experimental PoC, not a normal queue pickup. Added the parked label, which means exclude from automatic ranking and work only when explicitly selected by the user. No implementation work was started.

Releasing today’s automatic queue claim after operator clarification: this is a parked experimental PoC, not a normal queue pickup. Added the `parked` label, which means **exclude from automatic ranking and work only when explicitly selected by the user**. No implementation work was started.
Author
Owner

Closing as part of backlog grooming (2026-07-17). Convention decided this session: parked = no concrete plans to work on → close rather than leave lingering (reopen instantly if/when we decide to pursue the player-owned-playback PoC). The idea and rationale are preserved in the body above; related threads #178, #176, #58/#62 remain open.

Closing as part of backlog grooming (2026-07-17). Convention decided this session: `parked` = no concrete plans to work on → close rather than leave lingering (reopen instantly if/when we decide to pursue the player-owned-playback PoC). The idea and rationale are preserved in the body above; related threads #178, #176, #58/#62 remain open.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#357