Admin: a settings gear, and a head start behind live for every tune #117

Closed
opened 2026-11-08 11:18:31 -05:00 by cmoriarty · 4 comments
Owner

The owner wants a newly watched channel to start further behind live, as a setting. The Admin page should get a settings gear that opens a settings pane.

What happens

The buffer today (#53, deepened by #97):

  • What it does: the app holds the newest segments back from the player and releases one each time the last would have played out. A source that sends late, then two at once, reaches the player as a steady clock.
  • How deep: CHANNEL_BUFFER_SEGMENTS deep, 2 segments by default (4–8 s). The watch raises it to as much as 30 s for a bursty source. That is only an env var; there is no setting in the app.
  • The depth is a ceiling, not a level.
    • A tune starts with depth segments held, and the rest of the source's backlog is released at once ("a player starts near the edge, so the backlog buys no time").
    • After that, the reserve only grows when the source sends faster than real time, in a burst. A deeper depth fills nothing by itself.
    • On Liverpool (2026-11-08) the depth was raised to 22 s (11 segments of 2 s), yet the card showed 0–2 s held, because the source never burst.
  • What it can't fix: a source slower than real time (#101) drains any reserve; a bigger one only delays the first freeze.

The tune:

  • On 2026-11-08 at 16:07Z the owner tuned the Bengals' warm background channel in Emby for Android. It started a little choppy, then played well.
  • The app saw no dry spell, filler or late release.
  • The served segments' listed lengths matched their real video to the millisecond, with no dropped frames, so the release clock is right.
  • A start with 4–8 s in hand has little room for any first-minute hitch, the app's or the player's.

Freezes with the buffer above zero: the owner sees skips and freezes while the card's buffer reads above zero. Possible reasons, each to confirm:

  • The gauge is a snapshot. A source running late drains to zero, gets one segment, and releases it late. The gauge shows that one segment between polls; the late releases and dry spells are the record.
  • Swaps and recoveries skip. Another stream runs at another delay, so the splice jumps the game forward or back.
  • Downstream. Emby or Jellyfin re-streams the channel to the player, and a stall there is invisible to the app.

The idea

  1. A head start, as a setting: "Start behind live", in seconds (0–60; default to be decided, 15 s suggested).
    • A warm channel nobody watches holds back until its reserve reaches the head start. Nobody is watching, so the pause costs nothing. A tune then starts with the full reserve at once.
    • A cold tune keeps the source's backlog as reserve instead of releasing it all. When the backlog is shorter than the head start, the first picture waits for the rest. Whether that wait is capped is the owner's call.
    • The depth becomes at least the head start's worth of segments, so later bursts refill it as now.
    • 0 behaves as today.
    • Every player: holding back in the app works for Emby, Jellyfin and the browser alike, where EXT-X-START depends on the player.
  2. A settings gear in the Admin top bar opens a settings pane, one screen with a help icon per setting and no free text:
    • Background channels: the switch, the count and the kept-warm chips, moved from the flame's popover. The flame stays as the live count and cost.
    • Playback: the head start, as a stepper or slider with its seconds.
    • Saved in settings.json (#100) and applied to the next tune.
  3. The buffer gauge says level against target: for example "9.7 / 15 s", amber when it is under half. A dry spell or late release is marked where it happened, so a freeze that is not on the card points downstream.

Done when

  • In the unit lane:
    • a warm channel nobody watches holds back to the head start;
    • a tune's first served playlist ends the head start behind what the app holds;
    • a cold tune keeps its backlog as reserve;
    • a head start of 0 serves as today;
    • the setting is saved, survives a restart, and PUT /api/settings/playback refuses values outside 0–60.
  • In the frontend tests:
    • the gear opens the pane;
    • the background controls work from it;
    • the head start's stepper saves;
    • the gauge shows level against target.
  • Live: a tune of a warm channel shows the head start on the card's buffer from its first poll.
The owner wants a newly watched channel to start further behind live, as a setting. The Admin page should get a settings gear that opens a settings pane. ## What happens **The buffer today** (#53, deepened by #97): - **What it does:** the app holds the newest segments back from the player and releases one each time the last would have played out. A source that sends late, then two at once, reaches the player as a steady clock. - **How deep:** `CHANNEL_BUFFER_SEGMENTS` deep, 2 segments by default (4–8 s). The watch raises it to as much as 30 s for a bursty source. That is only an env var; there is no setting in the app. - **The depth is a ceiling, not a level.** - A tune starts with `depth` segments held, and the rest of the source's backlog is released at once ("a player starts near the edge, so the backlog buys no time"). - After that, the reserve only grows when the source sends faster than real time, in a burst. A deeper depth fills nothing by itself. - On Liverpool (2026-11-08) the depth was raised to 22 s (11 segments of 2 s), yet the card showed 0–2 s held, because the source never burst. - **What it can't fix:** a source slower than real time (#101) drains any reserve; a bigger one only delays the first freeze. **The tune:** - On 2026-11-08 at 16:07Z the owner tuned the Bengals' warm background channel in Emby for Android. It started a little choppy, then played well. - The app saw no dry spell, filler or late release. - The served segments' listed lengths matched their real video to the millisecond, with no dropped frames, so the release clock is right. - A start with 4–8 s in hand has little room for any first-minute hitch, the app's or the player's. **Freezes with the buffer above zero:** the owner sees skips and freezes while the card's buffer reads above zero. Possible reasons, each to confirm: - **The gauge is a snapshot.** A source running late drains to zero, gets one segment, and releases it late. The gauge shows that one segment between polls; the late releases and dry spells are the record. - **Swaps and recoveries skip.** Another stream runs at another delay, so the splice jumps the game forward or back. - **Downstream.** Emby or Jellyfin re-streams the channel to the player, and a stall there is invisible to the app. ## The idea 1. **A head start, as a setting:** "Start behind live", in seconds (0–60; default to be decided, 15 s suggested). - **A warm channel nobody watches** holds back until its reserve reaches the head start. Nobody is watching, so the pause costs nothing. A tune then starts with the full reserve at once. - **A cold tune** keeps the source's backlog as reserve instead of releasing it all. When the backlog is shorter than the head start, the first picture waits for the rest. Whether that wait is capped is the owner's call. - **The depth** becomes at least the head start's worth of segments, so later bursts refill it as now. - **0** behaves as today. - **Every player:** holding back in the app works for Emby, Jellyfin and the browser alike, where `EXT-X-START` depends on the player. 2. **A settings gear in the Admin top bar** opens a settings pane, one screen with a help icon per setting and no free text: - **Background channels:** the switch, the count and the kept-warm chips, moved from the flame's popover. The flame stays as the live count and cost. - **Playback:** the head start, as a stepper or slider with its seconds. - Saved in `settings.json` (#100) and applied to the next tune. 3. **The buffer gauge says level against target:** for example "9.7 / 15 s", amber when it is under half. A dry spell or late release is marked where it happened, so a freeze that is not on the card points downstream. ## Done when - **In the unit lane:** - a warm channel nobody watches holds back to the head start; - a tune's first served playlist ends the head start behind what the app holds; - a cold tune keeps its backlog as reserve; - a head start of 0 serves as today; - the setting is saved, survives a restart, and `PUT /api/settings/playback` refuses values outside 0–60. - **In the frontend tests:** - the gear opens the pane; - the background controls work from it; - the head start's stepper saves; - the gauge shows level against target. - **Live:** a tune of a warm channel shows the head start on the card's buffer from its first poll.
Author
Owner

Owner's decision (2026-11-08): the head start defaults to 15 s.

**Owner's decision (2026-11-08):** the head start defaults to **15 s**.
Author
Owner

Owner's decision (2026-11-08): a cold tune always waits for the full head start (15 s by default), with no limit on the extra wait.

Why it matters little: Emby's lineup is every Ready game, but up to the background count (1–10, already a setting) of followed live games are kept warm. So a cold tune from Emby happens only:

  • with more games live than the count;
  • before kickoff (background channels start once a game is live);
  • right after a restart or deploy.

The web app's tunes are for testing.

Implementation note: while it waits, the channel must still answer the media server's playlist polls (filler or the loading card), or Emby's reader may give up.

**Owner's decision (2026-11-08):** a cold tune always waits for the full head start (15 s by default), with no limit on the extra wait. Why it matters little: Emby's lineup is every Ready game, but up to the background count (1–10, already a setting) of followed live games are kept warm. So a cold tune from Emby happens only: - with more games live than the count; - before kickoff (background channels start once a game is live); - right after a restart or deploy. The web app's tunes are for testing. **Implementation note:** while it waits, the channel must still answer the media server's playlist polls (filler or the loading card), or Emby's reader may give up.
Author
Owner

Closing: merged to develop in PR #119 (merge 73f86a3), milestone 39. It deploys once nobody is watching.

What changed:

  • A gear in the Admin top bar opens the settings pane. The background channels moved there, and the flame is now a readout that opens the pane.
  • Playback's "Start behind live" defaults to 15 s, with a range of 0–30 s. The channel keeps 20 segments in memory, so 30 s is the most it can hold.
  • A background channel nobody watches fills its head start before a tune.
  • A viewer's cold tune plays the "Starting behind live" card until it has the full head start, as decided.
  • The buffer gauge shows level against target.

Not seen live yet: a tune with the head start in hand, and a cold tune's card.

Closing: merged to develop in PR #119 (merge 73f86a3), milestone 39. It deploys once nobody is watching. **What changed:** - A gear in the Admin top bar opens the settings pane. The background channels moved there, and the flame is now a readout that opens the pane. - Playback's "Start behind live" defaults to 15 s, with a range of 0–30 s. The channel keeps 20 segments in memory, so 30 s is the most it can hold. - A background channel nobody watches fills its head start before a tune. - A viewer's cold tune plays the "Starting behind live" card until it has the full head start, as decided. - The buffer gauge shows level against target. **Not seen live yet:** a tune with the head start in hand, and a cold tune's card.
Author
Owner

Deployed 2026-11-08 17:27:26Z: commit 73f86a3, container a07efdae03b6, 36.6 s down, no errors in the log. Live: the head start is 15 s. Man Utd vs. Aston Villa's background channel, nobody watching, held 16 s of its 16 s target (8 segments) and stayed Healthy.

Deployed 2026-11-08 17:27:26Z: commit 73f86a3, container a07efdae03b6, 36.6 s down, no errors in the log. **Live:** the head start is 15 s. Man Utd vs. Aston Villa's background channel, nobody watching, held 16 s of its 16 s target (8 segments) and stayed Healthy.
Sign in to join this conversation.
No labels
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/sports-breaker#117
No description provided.