-readrate 1.05 paces input reading at wall clock so a channel behaves like live TV — but it applies from the very first read. OutputFormatHls.SegmentSeconds is 4 and the segmenter serves the playlist only once the first segment exists, so the playlist cannot physically appear sooner than ~4/1.05 ≈ 3.8 s.
The bimodality earlier rounds could not explain was never about the media. HlsSessionWorker.cs:246 grants an unthrottled SeekAndWorkAhead start only while _workAheadCount < ffmpeg.segmenter.work_ahead_limit (prod: 1); every concurrent tune-in falls back to the throttled path. Confirmed by prediction on prod — three concurrent tunes of idle channels:
ch
slot
firstGop
122
✅ work-ahead
866 ms
102
❌ realtime
3845 ms
105
❌ realtime
6357 ms
This is why the fast/slow split correlated with nothing about the file — the variable was slot availability, which is also why the same channel varied 7.2× between tunes.
Two prior hypotheses falsified (not deferred)
Measured on real prod media, interleaved arms:
arm
times (ms)
accurate seek (current default)
168/95, 154/128, 611/523, 174/106, 151/119
-noaccurate_seek
79/79, 90/92, 410/421, 75/80, 76/79
-probesize 2M -analyzeduration 2M
94/95, 129/127, 507/518, 106/104, 122/119
The issue's ranked #1 driver (subtitle burn-in / seeking far from a keyframe) costs 30–100 ms; probe caps buy 20–50 ms. Neither can account for seconds. Recorded in decisions.md so they aren't re-proposed.
The change
Add -readrate_initial_burst (FFmpeg ≥ 6.1) next to -readrate on the normal playback path, gated on runtime capability detection through the existing FFmpegKnownOption/HasOption machinery — whose AllOptions list had simply been empty, making this its first entry. An older binary silently keeps today's behaviour rather than failing to launch.
Measured, same file, time from launch to live.m3u8 existing:
arm
run 1
run 2
-readrate 1.05 (today)
5369 ms
5344 ms
-readrate 1.05 -readrate_initial_burst 8
648 ms
649 ms
no readrate
740 ms
650 ms
Deliberately not raising workAheadSegmenterLimit: that budget exists to stop N viewers launching N unthrottled transcodes, and bumping it trades away a real resource guarantee for what the burst gets for free.
Scope and honest caveats (all recorded in decisions.md)
The burst is per ffmpeg process — i.e. per playout item — not per session. Item boundaries burst too. Consequences accepted: transitions get the same head start, but a channel whose items are shorter than the burst transcodes every item unthrottled, so work_ahead_limit's instantaneous-concurrency guarantee is weaker than before — weaker, not absent, since the transcodedBuffer <= 1min gate still caps the loop at a 60 s buffer and average CPU is unchanged. Making it strictly cold-start-only would need a "first process of this session" flag plumbed through FFmpegState; not judged worth it for a bounded peak.
Still images are excluded — their video input is paced by the realtime filter and takes no readrate, so a burst would only run a song's separate audio input ahead of the video, for zero cold-start gain.
Concat / WrapSegmenter keep the unburst single-arg constructor (they read already-written segments; bursting would gallop through them) — now pinned by a regression test.
Non-HLS realtime outputs (TransportStream, HLS-Direct) burst too, since FFmpegPlaybackSettingsCalculator makes them unconditionally realtime. Untested by the benchmark, which was segmenter-only; kept because the same first-read throttle delays those clients identically.
Verification
Full suite: 4949 passed, 0 failed. Four new tests (burst present / absent by capability, still-image exclusion, concat never bursts).
Negative control run: inverting the still-image guard fails 2 tests in both directions — the tests are non-vacuous. (First attempt at this control was itself invalid: a mv-restored file kept an older mtime so MSBuild skipped the rebuild — the #250 stale---no-build trap. Redone with a forced rebuild.)
Capability detection verified against the real binary: OptionRegex matches ffmpeg -h long's -readrate_initial_burst <seconds> line, and the exact generated argument order is accepted by our 7.1.1.
Independent cold-context adversarial review: MERGEABLE, having independently reproduced the mechanism on FFmpeg 8.1.2 (first segment 8.25 s → 1.09 s). Its findings 1/2/4 are folded in above; 3 is documented as a stated trade.
BOM + dotnet format gate pass (2 legacy BOMs stripped per #311).
Docs
docs/decisions.md entry added. No API/route/SPA change, so no api-conventions/blazor-route-parity/OpenAPI regeneration needed.
Post-merge: ersatztv-test tracks :latest, so the burst can be confirmed end-to-end there against a real channel before it reaches prod in a release.
Fixes #350.
## Root cause
`-readrate 1.05` paces input reading at wall clock so a channel behaves like live TV — but it applies **from the very first read**. `OutputFormatHls.SegmentSeconds` is 4 and the segmenter serves the playlist only once the first segment exists, so the playlist *cannot physically appear* sooner than ~4/1.05 ≈ 3.8 s.
The bimodality earlier rounds could not explain was never about the media. `HlsSessionWorker.cs:246` grants an unthrottled `SeekAndWorkAhead` start only while `_workAheadCount < ffmpeg.segmenter.work_ahead_limit` (prod: **1**); every concurrent tune-in falls back to the throttled path. Confirmed by prediction on prod — three concurrent tunes of idle channels:
| ch | slot | `firstGop` |
|----|------|------:|
| 122 | ✅ work-ahead | **866 ms** |
| 102 | ❌ realtime | **3845 ms** |
| 105 | ❌ realtime | **6357 ms** |
This is why the fast/slow split correlated with nothing about the file — the variable was slot availability, which is also why the same channel varied 7.2× between tunes.
## Two prior hypotheses falsified (not deferred)
Measured on real prod media, interleaved arms:
| arm | times (ms) |
|---|---|
| accurate seek (current default) | 168/95, 154/128, 611/523, 174/106, 151/119 |
| `-noaccurate_seek` | 79/79, 90/92, 410/421, 75/80, 76/79 |
| `-probesize 2M -analyzeduration 2M` | 94/95, 129/127, 507/518, 106/104, 122/119 |
The issue's ranked **#1 driver** (subtitle burn-in / seeking far from a keyframe) costs **30–100 ms**; probe caps buy 20–50 ms. Neither can account for seconds. Recorded in `decisions.md` so they aren't re-proposed.
## The change
Add `-readrate_initial_burst` (FFmpeg ≥ 6.1) next to `-readrate` on the normal playback path, gated on **runtime capability detection** through the existing `FFmpegKnownOption`/`HasOption` machinery — whose `AllOptions` list had simply been empty, making this its first entry. An older binary silently keeps today's behaviour rather than failing to launch.
Measured, same file, time from launch to `live.m3u8` existing:
| arm | run 1 | run 2 |
|---|---|---|
| `-readrate 1.05` (today) | 5369 ms | 5344 ms |
| `-readrate 1.05 -readrate_initial_burst 8` | **648 ms** | **649 ms** |
| no readrate | 740 ms | 650 ms |
Deliberately **not** raising `workAheadSegmenterLimit`: that budget exists to stop N viewers launching N unthrottled transcodes, and bumping it trades away a real resource guarantee for what the burst gets for free.
## Scope and honest caveats (all recorded in `decisions.md`)
- **The burst is per ffmpeg process — i.e. per playout item — not per session.** Item boundaries burst too. Consequences accepted: transitions get the same head start, but a channel whose items are shorter than the burst transcodes every item unthrottled, so `work_ahead_limit`'s instantaneous-concurrency guarantee is *weaker* than before — weaker, not absent, since the `transcodedBuffer <= 1min` gate still caps the loop at a 60 s buffer and average CPU is unchanged. Making it strictly cold-start-only would need a "first process of this session" flag plumbed through `FFmpegState`; not judged worth it for a bounded peak.
- **Still images are excluded** — their video input is paced by the realtime *filter* and takes no readrate, so a burst would only run a song's separate audio input ahead of the video, for zero cold-start gain.
- **Concat / WrapSegmenter keep the unburst single-arg constructor** (they read already-written segments; bursting would gallop through them) — now pinned by a regression test.
- **Non-HLS realtime outputs (`TransportStream`, HLS-Direct) burst too**, since `FFmpegPlaybackSettingsCalculator` makes them unconditionally realtime. Untested by the benchmark, which was segmenter-only; kept because the same first-read throttle delays those clients identically.
## Verification
- Full suite: **4949 passed, 0 failed**. Four new tests (burst present / absent by capability, still-image exclusion, concat never bursts).
- **Negative control run**: inverting the still-image guard fails 2 tests in both directions — the tests are non-vacuous. (First attempt at this control was itself invalid: a `mv`-restored file kept an older mtime so MSBuild skipped the rebuild — the #250 stale-`--no-build` trap. Redone with a forced rebuild.)
- Capability detection verified against the real binary: `OptionRegex` matches `ffmpeg -h long`'s `-readrate_initial_burst <seconds>` line, and the exact generated argument order is accepted by our 7.1.1.
- Independent cold-context adversarial review: `MERGEABLE`, having independently reproduced the mechanism on FFmpeg 8.1.2 (first segment **8.25 s → 1.09 s**). Its findings 1/2/4 are folded in above; 3 is documented as a stated trade.
- BOM + `dotnet format` gate pass (2 legacy BOMs stripped per #311).
## Docs
`docs/decisions.md` entry added. No API/route/SPA change, so no `api-conventions`/`blazor-route-parity`/OpenAPI regeneration needed.
**Post-merge**: `ersatztv-test` tracks `:latest`, so the burst can be confirmed end-to-end there against a real channel before it reaches prod in a release.
`-readrate 1.05` paces input reading at wall clock so a channel behaves like
live TV, but it applies from the very first read. With 4s HLS segments and the
segmenter waiting for the first one, the playlist could not appear sooner than
~4/1.05 = 3.8s, so every tune-in that did not win a work-ahead slot paid a
multi-second wait.
Add `-readrate_initial_burst` (FFmpeg >= 6.1) next to `-readrate` on the normal
playback path, gated on runtime capability detection via the existing
`FFmpegKnownOption`/`HasOption` machinery, whose option list had simply been
empty. Measured on real prod media: time-to-first-playlist 5369/5344ms ->
648/649ms.
Root cause detail: the cold-start bimodality earlier rounds could not explain
was never about the media. `HlsSessionWorker` grants an unthrottled start only
while `_workAheadCount < work_ahead_limit` (prod: 1), so concurrent tune-ins
fall back to the throttled path. Confirmed on prod with three concurrent tunes:
firstGop 866ms for the slot winner vs 3845ms and 6357ms. This also falsifies the
issue's ranked #1 driver — accurate-seek decode-discard measures 30-100ms on
real media, and probe caps 20-50ms; neither can account for seconds.
Still images are excluded: their video input is paced by the realtime filter and
takes no readrate, so a burst would only run a song's separate audio input ahead
of the video. Concat/WrapSegmenter keep the unburst single-arg constructor.
fixes#350
Re-review of the fix commit flagged two ways the new tests could pass
vacuously in future: the burst assertion was a bare substring (satisfiable
by any input carrying the option) and the still-image test asserted only an
absence. Anchor the first on the input path plus an occurrence count, and
give the second a positive anchor.
Three cold-context, review-only passes, each starting from a fresh brief:
pass
scope
outcome
1
full diff (pre-fix tree)
MERGEABLE with 6 findings; independently reproduced the mechanism on FFmpeg 8.1.2 — first segment 8.25 s → 1.09 s
2
the folded fix commit (1359bb61)
MERGEABLE; verified the still-image guard is the exact logical complement of AppliesTo, confirmed non-vacuity by mutation, checked every decisions.md claim against the code
3
the test-hardening commit (0e3b0ca3)
MERGEABLE
Findings folded in (pass 1): the per-process/per-item overstatement in the docs and code comment; the still-image guard (a song's separate audio input would otherwise burst ahead of its realtime-filter-paced video, for zero cold-start gain); the InitialSegmentCount caveat. Folded from pass 2: both test-robustness findings — the burst assertion is now anchored to the input path plus an occurrence count, and the still-image test has a positive anchor so it cannot pass vacuously.
Stated, not silently accepted: pass 1's finding 3 (non-HLS realtime outputs also burst, which the benchmark did not cover) is kept deliberately and recorded in decisions.md with its reasoning, rather than being scoped out on an untested hunch.
One process note worth recording: my first negative control falsely passed. I had restored the mutated file with mv from a .bak, which preserved the older mtime, so MSBuild skipped the rebuild and the test ran against a stale assembly — the #250 stale---no-build trap in a new disguise. Redone with a forced rebuild, the control fails in both directions, which is what makes the non-vacuity claim above worth anything.
## Independent review chain
Three cold-context, review-only passes, each starting from a fresh brief:
| pass | scope | outcome |
|---|---|---|
| 1 | full diff (pre-fix tree) | MERGEABLE with 6 findings; **independently reproduced the mechanism** on FFmpeg 8.1.2 — first segment 8.25 s → 1.09 s |
| 2 | the folded fix commit (`1359bb61`) | MERGEABLE; verified the still-image guard is the exact logical complement of `AppliesTo`, confirmed non-vacuity by mutation, checked every `decisions.md` claim against the code |
| 3 | the test-hardening commit (`0e3b0ca3`) | MERGEABLE |
**Findings folded in** (pass 1): the per-process/per-item overstatement in the docs and code comment; the still-image guard (a song's *separate* audio input would otherwise burst ahead of its realtime-filter-paced video, for zero cold-start gain); the `InitialSegmentCount` caveat. **Folded from pass 2**: both test-robustness findings — the burst assertion is now anchored to the input path plus an occurrence count, and the still-image test has a positive anchor so it cannot pass vacuously.
**Stated, not silently accepted**: pass 1's finding 3 (non-HLS realtime outputs also burst, which the benchmark did not cover) is kept deliberately and recorded in `decisions.md` with its reasoning, rather than being scoped out on an untested hunch.
One process note worth recording: my first negative control **falsely passed**. I had restored the mutated file with `mv` from a `.bak`, which preserved the older mtime, so MSBuild skipped the rebuild and the test ran against a stale assembly — the #250 stale-`--no-build` trap in a new disguise. Redone with a forced rebuild, the control fails in both directions, which is what makes the non-vacuity claim above worth anything.
Review-verdict: MERGEABLE @ 0e3b0ca3
timothy
merged commit 34d76095a2 into main2026-07-21 00:33:40 +02:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Fixes #350.
Root cause
-readrate 1.05paces input reading at wall clock so a channel behaves like live TV — but it applies from the very first read.OutputFormatHls.SegmentSecondsis 4 and the segmenter serves the playlist only once the first segment exists, so the playlist cannot physically appear sooner than ~4/1.05 ≈ 3.8 s.The bimodality earlier rounds could not explain was never about the media.
HlsSessionWorker.cs:246grants an unthrottledSeekAndWorkAheadstart only while_workAheadCount < ffmpeg.segmenter.work_ahead_limit(prod: 1); every concurrent tune-in falls back to the throttled path. Confirmed by prediction on prod — three concurrent tunes of idle channels:firstGopThis is why the fast/slow split correlated with nothing about the file — the variable was slot availability, which is also why the same channel varied 7.2× between tunes.
Two prior hypotheses falsified (not deferred)
Measured on real prod media, interleaved arms:
-noaccurate_seek-probesize 2M -analyzeduration 2MThe issue's ranked #1 driver (subtitle burn-in / seeking far from a keyframe) costs 30–100 ms; probe caps buy 20–50 ms. Neither can account for seconds. Recorded in
decisions.mdso they aren't re-proposed.The change
Add
-readrate_initial_burst(FFmpeg ≥ 6.1) next to-readrateon the normal playback path, gated on runtime capability detection through the existingFFmpegKnownOption/HasOptionmachinery — whoseAllOptionslist had simply been empty, making this its first entry. An older binary silently keeps today's behaviour rather than failing to launch.Measured, same file, time from launch to
live.m3u8existing:-readrate 1.05(today)-readrate 1.05 -readrate_initial_burst 8Deliberately not raising
workAheadSegmenterLimit: that budget exists to stop N viewers launching N unthrottled transcodes, and bumping it trades away a real resource guarantee for what the burst gets for free.Scope and honest caveats (all recorded in
decisions.md)work_ahead_limit's instantaneous-concurrency guarantee is weaker than before — weaker, not absent, since thetranscodedBuffer <= 1mingate still caps the loop at a 60 s buffer and average CPU is unchanged. Making it strictly cold-start-only would need a "first process of this session" flag plumbed throughFFmpegState; not judged worth it for a bounded peak.TransportStream, HLS-Direct) burst too, sinceFFmpegPlaybackSettingsCalculatormakes them unconditionally realtime. Untested by the benchmark, which was segmenter-only; kept because the same first-read throttle delays those clients identically.Verification
mv-restored file kept an older mtime so MSBuild skipped the rebuild — the #250 stale---no-buildtrap. Redone with a forced rebuild.)OptionRegexmatchesffmpeg -h long's-readrate_initial_burst <seconds>line, and the exact generated argument order is accepted by our 7.1.1.MERGEABLE, having independently reproduced the mechanism on FFmpeg 8.1.2 (first segment 8.25 s → 1.09 s). Its findings 1/2/4 are folded in above; 3 is documented as a stated trade.dotnet formatgate pass (2 legacy BOMs stripped per #311).Docs
docs/decisions.mdentry added. No API/route/SPA change, so noapi-conventions/blazor-route-parity/OpenAPI regeneration needed.Post-merge:
ersatztv-testtracks:latest, so the burst can be confirmed end-to-end there against a real channel before it reaches prod in a release.Independent review chain
Three cold-context, review-only passes, each starting from a fresh brief:
1359bb61)AppliesTo, confirmed non-vacuity by mutation, checked everydecisions.mdclaim against the code0e3b0ca3)Findings folded in (pass 1): the per-process/per-item overstatement in the docs and code comment; the still-image guard (a song's separate audio input would otherwise burst ahead of its realtime-filter-paced video, for zero cold-start gain); the
InitialSegmentCountcaveat. Folded from pass 2: both test-robustness findings — the burst assertion is now anchored to the input path plus an occurrence count, and the still-image test has a positive anchor so it cannot pass vacuously.Stated, not silently accepted: pass 1's finding 3 (non-HLS realtime outputs also burst, which the benchmark did not cover) is kept deliberately and recorded in
decisions.mdwith its reasoning, rather than being scoped out on an untested hunch.One process note worth recording: my first negative control falsely passed. I had restored the mutated file with
mvfrom a.bak, which preserved the older mtime, so MSBuild skipped the rebuild and the test ran against a stale assembly — the #250 stale---no-buildtrap in a new disguise. Redone with a forced rebuild, the control fails in both directions, which is what makes the non-vacuity claim above worth anything.Review-verdict: MERGEABLE @
0e3b0ca3