Skip to content

perf(hls): subtitles served from the window walks; audit fixes for over-reads and declared-size allocations - #32

Closed
gravity-zero wants to merge 11 commits into
masterfrom
fix/planhls-subtitle-one-walk
Closed

gravity-zero wants to merge 11 commits into
masterfrom
fix/planhls-subtitle-one-walk

Conversation

@gravity-zero

Copy link
Copy Markdown
Owner

On-demand HLS read the source far more than it served once subtitles were involved. This branch removes that and fixes what two follow-up audits found along the way. Every fix comes with a test that is red before it.

Subtitles without a second walk (PlanHLS)

  • Before: without a subtitle index, each subtitle rendition walked the clusters again, on top of the walks of the video windows.

  • Now: the window walks keep the subtitle blocks they pass over, and a subtitle request takes its cues from them. It builds the windows it lacks, which the video then serves from.

  • Shared walk: a subtitle cursor's own walk serves the other subtitle tracks.

  • Damaged regions: one costs the harvest only the cluster it lies in.

  • Exactness kept:

    • the walk's 60 s strides and island routing;
    • nothing is built past a window longer than a stride, nor the last window;
    • on a network source, nothing is built behind the request.
  • New counter: HLSPlanStats.SubtitleHarvestedClusters.

  • Measured on real 1080p files, bytes asked of the source:

    Scenario Before After
    Local, sequential, 100 segments, 1 subtitle 213 % of what was served 113 % (102 % without subtitles)
    Local, 3 subtitles what 1 costs
    Network mount, 30 segments, 3 subtitles 1295 MB 656 MB
    Network mount, after a seek 1308 MB 732 MB
  • Identity checks: WebVTT and media segments are byte-identical to the old walk in every request order, seek and damage case tested, and across 18 scenarios (3 files x sequential/seek/tail x local/network).

Audit fixes

  • SynthesizeIndex goes on past a damaged region instead of ending the index there. A damaged 43 min episode planned 35 windows, the last one served as a single 2.2 GB segment; it now plans 309.
  • AudioStartDelays (and Diagnose) seeks over what precedes the first cluster instead of reading it. The attachments were read on every call: 26 MB -> 5.3 MB on a file with a 20 MiB font.
  • Allocations: a declared size is no longer allocated before its bytes arrive:
    • the block reader: 60 MiB for a 51-byte file;
    • AudioStartDelays, retime, reindex: 200 MiB for a 32-byte file.
  • Read-ahead hints: a window walk and a streamed segment no longer ask the disk to read past the end of the file. A remote source (mkv.RangeHinter) is never asked for an open-ended range.

Checks

  • Full gate (gofmt, tests, vet, golangci-lint) green on 9f2e44e.
  • Cross builds and vet for linux/windows/darwin/wasm/arm OK.
  • The media server's own test suite passes against this branch.

@gravity-zero gravity-zero mentioned this pull request Nov 19, 2026
@gravity-zero

Copy link
Copy Markdown
Owner Author

Shipped in v0.70.0 through #33: the same commits replayed on top of #31, with the CHANGELOG conflict resolved and the CI fixes (5c3af61, 7fe6b9b).

@gravity-zero
gravity-zero deleted the fix/planhls-subtitle-one-walk branch November 19, 2026 15:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant