From a8f7b943bfe9c75dfbdd34798ffe877ec7c8cfe4 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 13:40:46 +0100 Subject: [PATCH 01/11] fix(hls): a window walk and a streamed segment read ahead no further than the file --- mp4/hlsplan_ahead.go | 3 ++ mp4/hlsplan_window_hint_forged_test.go | 51 ++++++++++++++++++++++++++ mp4/hlsstream.go | 6 ++- 3 files changed, 59 insertions(+), 1 deletion(-) create mode 100644 mp4/hlsplan_window_hint_forged_test.go diff --git a/mp4/hlsplan_ahead.go b/mp4/hlsplan_ahead.go index 6f24a13..ac2bdab 100644 --- a/mp4/hlsplan_ahead.go +++ b/mp4/hlsplan_ahead.go @@ -65,6 +65,9 @@ func (p *HLSPlan) hintWindow(src io.Reader, n int, start int64) { // hintRange tells the source a walk is about to read [start, end): a local file has the kernel start reading it // all now, in the disk's own request sizes (adviseWillNeed), a remote one fetches it with one request. func (p *HLSPlan) hintRange(src io.Reader, start, end int64) { + if p.srcInfo != nil && end > p.srcInfo.Size() && end != math.MaxInt64 { + end = p.srcInfo.Size() // a range past the file's end (a window's look past the last cluster, a forged size) is not there to read + } if end <= start { return } diff --git a/mp4/hlsplan_window_hint_forged_test.go b/mp4/hlsplan_window_hint_forged_test.go new file mode 100644 index 0000000..b304a9b --- /dev/null +++ b/mp4/hlsplan_window_hint_forged_test.go @@ -0,0 +1,51 @@ +package mp4 + +import ( + "context" + "io" + "os" + "path/filepath" + "testing" +) + +// A window walk reads ahead no further than the file either: its range ran a look past the next window's cluster, +// past the end of a file whose last window is short. +func TestWindowWalkReadsAheadNoFurtherThanTheFile(t *testing.T) { + data, err := os.ReadFile("../internal/testdata/sample_subs.mkv") + if err != nil { + t.Fatal(err) + } + path := filepath.Join(t.TempDir(), "in.mkv") + if err := os.WriteFile(path, data, 0o644); err != nil { + t.Fatal(err) + } + type rng struct{ off, n int64 } + var will []rng + defer func(w func(*os.File, int64, int64)) { adviseWillNeed = w }(adviseWillNeed) + adviseWillNeed = func(_ *os.File, off, n int64) { will = append(will, rng{off, n}) } + defer func(f func(*os.File) bool) { networkSource = f }(networkSource) + networkSource = func(*os.File) bool { return false } + ctx := context.Background() + plan, err := PlanHLS(ctx, path, Options{SegmentMs: 2000, VideoOnly: true}) + if err != nil { + t.Fatal(err) + } + for n := 0; n < plan.NumSegments(); n++ { + h, err := plan.Open(ctx, plan.SegmentName(n)) + if err != nil { + t.Fatal(err) + } + if _, err := h.WriteTo(ctx, io.Discard); err != nil { + t.Fatal(err) + } + h.Close() + } + if len(will) == 0 { + t.Fatal("the walks read nothing ahead") + } + for _, w := range will { + if w.off+w.n > int64(len(data)) { + t.Errorf("read ahead [%d, %d) of a file of %d bytes", w.off, w.off+w.n, len(data)) + } + } +} diff --git a/mp4/hlsstream.go b/mp4/hlsstream.go index 4417814..899e4ec 100644 --- a/mp4/hlsstream.go +++ b/mp4/hlsstream.go @@ -1036,7 +1036,11 @@ func prefetch(f *os.File, pieces []span, window [2]int64, extend bool) *ahead { a.next, a.end = min(a.next, window[0]), max(a.end, window[1]) } if extend && f != nil { - a.end = roundUpTo(a.end, readAheadBytes(f)) + end := roundUpTo(a.end, readAheadBytes(f)) + if st, err := f.Stat(); err == nil && end > st.Size() { + end = max(a.end, st.Size()) // the chunk boundary past the file's end is not there to read + } + a.end = end } a.advance(a.next) return a From 2ad07b90edfa9584433729c4df689ef2cc570a67 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 13:47:07 +0100 Subject: [PATCH 02/11] perf(hls): subtitle renditions take their cues from the window walks instead of walking the file again --- CHANGELOG.md | 16 ++ docs/library.md | 12 ++ mp4/export_test.go | 4 + mp4/hlsplan.go | 1 + mp4/hlsplan_cueindex_test.go | 5 +- mp4/hlsplan_subharvest.go | 333 +++++++++++++++++++++++++++++++++ mp4/hlsplan_subharvest_test.go | 114 +++++++++++ mp4/hlsplan_subindex_test.go | 6 +- mp4/hlsplan_subtitle.go | 5 + mp4/hlsplan_walk.go | 25 ++- mp4/hlswindow.go | 3 + 11 files changed, 519 insertions(+), 5 deletions(-) create mode 100644 mp4/hlsplan_subharvest.go create mode 100644 mp4/hlsplan_subharvest_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index fa35adf..89ad1ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,22 @@ its series' file in [changelog/](changelog/) when a newer one ships. keeps the audio up to about a frame late past it, as before 0.62.0 (`docs/library.md`, HLS plan). +### Added + +- `HLSPlanStats.SubtitleHarvestedClusters`: the clusters a subtitle rendition + took its cues from as a window walk read them. + +### Fixed + +- `PlanHLS` without a subtitle index no longer walks the file again for each + subtitle rendition: the cues come from the window walks, and on a local + source a subtitle request builds the windows the video then serves from. A + 1080p episode played with one subtitle read 213 % of what was served, 108 % + now (102 % without the subtitle); three subtitles cost what one does + (`docs/library.md`, HLS plan). +- A window walk and a streamed segment no longer ask the disk to read ahead + past the end of the file. + ## [0.69.0] - 2026-11-17 ### Added diff --git a/docs/library.md b/docs/library.md index 7a82b1d..24de0fd 100644 --- a/docs/library.md +++ b/docs/library.md @@ -787,6 +787,18 @@ cluster, and each block read is checked against its cue like an index's. The plan counts both outcomes (`SubtitleCueIndexed`, `SubtitleCueUnverified`); `matroska.SubtitleIndexFromCues` is the same derivation for your own use. +With neither, the subtitle renditions take their cues from the window walks: +a walk reads every block of the clusters it covers, the subtitles' included, +so a cluster a walk read whole is not walked again for its subtitles. On a +local source whose segments are written from the source, a subtitle request +builds the window tables it lacks itself, and the video then serves from the +same walks: a viewer playing the video with a subtitle reads the file about +once (108 % of what was served over 100 segments of a real 1080p episode, 213 % +walking; three subtitles cost what one does). The tables run a little past the +request, by the 32.7 s a block may sit after its cluster. A cluster no walk read +whole, or one past a damaged region, is walked as before. `SubtitleHarvestedClusters` +counts the clusters served this way. + **Plan-time cost.** An MP4 plan builds `iframe.m3u8` eagerly, at `PlanHLS` time: the moov sample table already has every segment's exact sample count, sizes and sync flags, so it costs nothing extra. A Matroska plan instead diff --git a/mp4/export_test.go b/mp4/export_test.go index 6fc19bc..93387da 100644 --- a/mp4/export_test.go +++ b/mp4/export_test.go @@ -6,3 +6,7 @@ var ( BuildSubCursorFixtureForTest = buildSubCursorFixture BuildSeekFixtureForTest = buildSeekFixture ) + +// DisableSubHarvestForTest makes p walk the clusters for its subtitle cues as it did before the window walks +// harvested them: the reference the harvested cues are compared with. +func DisableSubHarvestForTest(p *HLSPlan) { p.harvest.off = true } diff --git a/mp4/hlsplan.go b/mp4/hlsplan.go index 631082c..6ec78ae 100644 --- a/mp4/hlsplan.go +++ b/mp4/hlsplan.go @@ -97,6 +97,7 @@ type HLSPlan struct { subs []hlsSubTrack // declared renditions; cues fetched lazily, then cached subMu []sync.Mutex // serialises each track's cue scans subScan []subScanState // per-track incremental cue scan state + harvest subHarvest // subtitle blocks the window walks read on their way (see subHarvest) segs []segInfo // per-segment duration/bytes (BANDWIDTH; ABR master reuse) mp4src bool // MP4 source: windows cut from the sample table, exact by construction share mp4Share // a remote MP4 window's audio, kept by its video read diff --git a/mp4/hlsplan_cueindex_test.go b/mp4/hlsplan_cueindex_test.go index 6049878..8a0eb3a 100644 --- a/mp4/hlsplan_cueindex_test.go +++ b/mp4/hlsplan_cueindex_test.go @@ -110,6 +110,7 @@ func TestPlanHLSSubtitleIndexDerivedFromCues(t *testing.T) { if err != nil { t.Fatal(err) } + mp4.DisableSubHarvestForTest(walked) cases := map[string]struct { src string indexed int64 @@ -144,8 +145,8 @@ func TestPlanHLSSubtitleIndexDerivedFromCues(t *testing.T) { } } st = plan.Stats() - if (st.SubtitleWalks > 0) != tc.walks || (st.SubtitleIndexedBlocks > 0) != tc.blocksByPos { - t.Errorf("%d walks, %d blocks by position; want walks=%v, byPosition=%v", st.SubtitleWalks, st.SubtitleIndexedBlocks, tc.walks, tc.blocksByPos) + if (st.SubtitleWalks+st.SubtitleHarvestedClusters > 0) != tc.walks || (st.SubtitleIndexedBlocks > 0) != tc.blocksByPos { + t.Errorf("%d walks, %d clusters harvested, %d blocks by position; want walked or harvested=%v, byPosition=%v", st.SubtitleWalks, st.SubtitleHarvestedClusters, st.SubtitleIndexedBlocks, tc.walks, tc.blocksByPos) } }) } diff --git a/mp4/hlsplan_subharvest.go b/mp4/hlsplan_subharvest.go new file mode 100644 index 0000000..b882684 --- /dev/null +++ b/mp4/hlsplan_subharvest.go @@ -0,0 +1,333 @@ +package mp4 + +import ( + "context" + "math" + "sort" + "sync" + + "github.com/gravity-zero/mkvgo/mkv" + "github.com/gravity-zero/mkvgo/mkv/reader" + "github.com/gravity-zero/mkvgo/mkv/subtitle" +) + +// subHarvest holds the subtitle blocks the window walks pass over. A window walk reads every block of the clusters +// it covers, the subtitle tracks' included, so a subtitle cursor takes its cues from there instead of walking those +// clusters a second time (a sequential viewer with one subtitle read the file twice, three subtitles four times). +// A cluster serves once the walks that met it read it whole between them; any other is walked as before. +type subHarvest struct { + mu sync.Mutex + clusters map[int64]*harvestCluster // by the cluster's start offset + held int // blocks held, bounded by maxHarvestBlocks + off bool +} + +// maxHarvestBlocks bounds the subtitle blocks a plan holds from its walks (a feature film's text tracks hold a few +// thousand); past it, clusters not yet met are walked as before. +const maxHarvestBlocks = 1 << 18 + +// harvestCluster is what the walks read of one cluster. +type harvestCluster struct { + ms int64 // the cluster's timestamp + spans [][2]int64 // block offsets read through, [lo, hi]; lo = the cluster's start when read from it, hi = MaxInt64 to its end + next int64 // the next cluster a walk met holding a kept block, -1 unknown, harvestEnd past the last + blocks []harvestBlock + whole bool // spans cover the cluster and next is known +} + +// harvestEnd is a cluster's next when a walk read it to the source's clean end. +const harvestEnd = -2 + +// harvestBlock is one subtitle frame as the cursor's walk would turn it into a cue. +type harvestBlock struct { + off int64 + frame int // index within a laced block + sub int // index in HLSPlan.subs + cue subtitle.Cue + ok, recovered bool + err error +} + +// harvestRec records one window walk, committed when the walk ends without error. +type harvestRec struct { + p *HLSPlan + subOf map[uint64]int + seat int64 // offset the reader was seated at + parts []*harvestCluster + starts []int64 + broken bool +} + +// harvestTracks returns the subtitle track IDs a window walk should read along, nil when none. +func (p *HLSPlan) harvestTracks() map[uint64]int { + if p.mp4src || len(p.subs) == 0 || p.harvest.off { + return nil + } + ids := make(map[uint64]int, len(p.subs)) + for i := range p.subs { + ids[p.subs[i].track.ID] = i + } + return ids +} + +// newHarvestRec starts a recording for a walk seated at seat; nil when the plan harvests nothing. +func (p *HLSPlan) newHarvestRec(subOf map[uint64]int, seat int64) *harvestRec { + if subOf == nil { + return nil + } + return &harvestRec{p: p, subOf: subOf, seat: seat} +} + +// observe folds in the block the walk's reader just returned, sub being its index in p.subs or -1 for a media block. +func (r *harvestRec) observe(pos reader.BlockPos, b *mkv.Block, sub int) { + if r == nil || r.broken { + return + } + n := len(r.parts) + if n == 0 || r.starts[n-1] != pos.ClusterStart { + ms, ok := r.p.clusterMs(pos.ClusterTS) + if !ok || (n > 0 && pos.ClusterStart < r.starts[n-1]) { + r.broken = true + return + } + lo := pos.ClusterStart + if n > 0 { + prev := r.parts[n-1] + prev.spans[0][1] = math.MaxInt64 // read to its end: the reader went on to this cluster + prev.next = pos.ClusterStart + } else if r.seat > pos.ClusterStart { + lo = r.seat // seated inside the cluster: what precedes the seat was not read + } + r.parts = append(r.parts, &harvestCluster{ms: ms, spans: [][2]int64{{lo, pos.Off}}, next: -1}) + r.starts = append(r.starts, pos.ClusterStart) + n++ + } + c := r.parts[n-1] + if pos.Off > c.spans[0][1] { + c.spans[0][1] = pos.Off + } + if sub < 0 { + return + } + if b.Data == nil && b.Size > 0 { // a payload the reader skipped: no cue to take + r.broken = true + return + } + frame := 0 + if k := len(c.blocks); k > 0 && c.blocks[k-1].off == pos.Off { + frame = c.blocks[k-1].frame + 1 + } + cue, ok, recovered, err := subCueFromBlockRecovered(&r.p.subs[sub].track, *b) + c.blocks = append(c.blocks, harvestBlock{off: pos.Off, frame: frame, sub: sub, cue: cue, ok: ok, recovered: recovered, err: err}) +} + +// end marks the walk's last cluster read to the source's clean end. +func (r *harvestRec) end() { + if r == nil || r.broken || len(r.parts) == 0 { + return + } + last := r.parts[len(r.parts)-1] + last.spans[0][1], last.next = math.MaxInt64, harvestEnd +} + +// commit merges a finished walk's clusters into the plan's harvest. +func (r *harvestRec) commit() { + if r == nil || r.broken || len(r.parts) == 0 { + return + } + h := &r.p.harvest + h.mu.Lock() + defer h.mu.Unlock() + if h.clusters == nil { + h.clusters = make(map[int64]*harvestCluster) + } + for k, part := range r.parts { + c := h.clusters[r.starts[k]] + if c == nil { + if h.held+len(part.blocks) > maxHarvestBlocks { + continue + } + c = &harvestCluster{ms: part.ms, next: -1} + h.clusters[r.starts[k]] = c + } + if c.whole { + continue + } + c.spans = append(c.spans, part.spans[0]) + if part.next != -1 { + c.next = part.next + } + before := len(c.blocks) + c.blocks = mergeHarvested(c.blocks, part.blocks) + h.held += len(c.blocks) - before + c.whole = c.next != -1 && spansCover(c.spans, r.starts[k]) + } +} + +// mergeHarvested adds the blocks of b that a is missing, keeping block order. +func mergeHarvested(a, b []harvestBlock) []harvestBlock { + if len(a) == 0 { + return append([]harvestBlock(nil), b...) + } + type key struct { + off int64 + frame int + } + have := make(map[key]bool, len(a)) + for _, x := range a { + have[key{x.off, x.frame}] = true + } + added := false + for _, x := range b { + if !have[key{x.off, x.frame}] { + a, added = append(a, x), true + } + } + if added { + sort.SliceStable(a, func(i, j int) bool { + if a[i].off != a[j].off { + return a[i].off < a[j].off + } + return a[i].frame < a[j].frame + }) + } + return a +} + +// spansCover reports whether the spans read a cluster starting at start through to its end with no gap. +func spansCover(spans [][2]int64, start int64) bool { + s := append([][2]int64(nil), spans...) + sort.Slice(s, func(i, j int) bool { return s[i][0] < s[j][0] }) + if s[0][0] > start { + return false + } + reach := s[0][1] + for _, x := range s[1:] { + if x[0] > reach { + return false + } + reach = max(reach, x[1]) + } + return reach == math.MaxInt64 +} + +// harvested returns the cluster at start as the walks read it: its timestamp (known), and when read whole, the +// subtitle track's blocks in it and the next cluster's start. +func (h *subHarvest) harvested(start int64, sub int) (ms int64, known, whole bool, next int64, blocks []harvestBlock) { + h.mu.Lock() + defer h.mu.Unlock() + c := h.clusters[start] + if c == nil { + return 0, false, false, -1, nil + } + if !c.whole { + return c.ms, true, false, -1, nil + } + for _, b := range c.blocks { + if b.sub == sub { + blocks = append(blocks, b) + } + } + return c.ms, true, true, c.next, blocks +} + +// prebuildsTables reports whether a subtitle cursor may build the window tables it needs: a local Matroska source +// the segments are written from, whose tables are structure only, so the video then serves from the very walk. +func (p *HLSPlan) prebuildsTables(ctx context.Context) bool { + return !p.mp4src && p.streams() && !p.networkSrc(ctx) +} + +// harvestWindow builds the table of a window whose walk reads the cluster at off, one not built yet in this scan; +// it reports whether it built one. +func (p *HLSPlan) harvestWindow(ctx context.Context, off int64, tried map[int]bool) bool { + k := sort.Search(min(len(p.offsets), p.segCount), func(k int) bool { return p.offsets[k] > off }) - 1 + for _, n := range []int{k, k - 1} { // a walk seated past the cluster's start leaves its head to the previous window's + if n < 0 || tried[n] { + continue + } + tried[n] = true + if _, err := p.table(ctx, n); err != nil { + return false + } + return true + } + return false +} + +// extendCursorHarvested is extendCursorLocked's scan served from the clusters the window walks read: stride by +// stride, the same blocks in the same order, building the window tables it lacks when the plan writes its segments +// from them. served is false when a cluster it needs was not read whole: the cursor stands on that cluster with +// what precedes it committed, and the walk serves from there. Caller holds subMu[i]. +func (p *HLSPlan) extendCursorHarvested(ctx context.Context, i int, cur *subCursor, target, uptoMs int64) (served bool, err error) { + st := &p.subScan[i] + build := p.prebuildsTables(ctx) + tried := map[int]bool{} + var took int64 + defer func() { + p.winMu.Lock() + p.stats.SubtitleHarvestedClusters += took + p.winMu.Unlock() + }() + for { + stopAt := cur.scanned + subScanStrideMs + if stopAt < cur.scanned { + stopAt = math.MaxInt64 + } + if target > cur.scanned && target < stopAt { + stopAt = target // a window built ahead is a walk the video may never use: build no further than this request needs + } + next := cur.next + if next == 0 { + next = p.offsets[0] + } + var local []subtitle.Cue + for { + ms, known, whole, after, blocks := p.harvest.harvested(next, i) + if known && ms > stopAt { + break // the walk's StopBeforeClusterMs: the stride ends before this cluster + } + if !whole { + if build && p.harvestWindow(ctx, next, tried) { + continue + } + cur.add(local...) + cur.next = next + if err := ctx.Err(); err != nil { + return true, err + } + return false, nil + } + for _, b := range blocks { + if b.err != nil { + st.err = b.err // the cue's own bytes: every scan would refuse them again + return true, st.err + } + p.noteRecovered(b.recovered) + if b.ok { + if b.cue.EndMs <= b.cue.StartMs || b.cue.EndMs-b.cue.StartMs > subFastMaxCueDurMs { + st.noFast = true + } + local = append(local, b.cue) + } + } + took++ + if after == harvestEnd { + cur.add(local...) + cur.done = true + return true, nil + } + next = after + } + cur.add(local...) + cur.next, cur.scanned = next, stopAt + if st.noFast && cur.baseMs > 0 { + return true, nil // the island is doomed; the caller falls back to the prefix + } + if cur.scanned >= target && !subNeedsNextCue(cur.cues, uptoMs) { + return true, nil + } + if err := ctx.Err(); err != nil { + return true, err + } + } +} diff --git a/mp4/hlsplan_subharvest_test.go b/mp4/hlsplan_subharvest_test.go new file mode 100644 index 0000000..0541d4b --- /dev/null +++ b/mp4/hlsplan_subharvest_test.go @@ -0,0 +1,114 @@ +package mp4_test + +import ( + "bytes" + "context" + "fmt" + "testing" + + "github.com/gravity-zero/mkvgo/mp4" +) + +func openAll(t *testing.T, plan *mp4.HLSPlan, name string) []byte { + t.Helper() + ctx := context.Background() + h, err := plan.Open(ctx, name) + if err != nil { + t.Fatalf("%s: %v", name, err) + } + defer h.Close() + var buf bytes.Buffer + if _, err := h.WriteTo(ctx, &buf); err != nil { + t.Fatalf("%s: %v", name, err) + } + return buf.Bytes() +} + +// The subtitle renditions take their cues from the clusters the window walks read, and serve the very WebVTT the +// cluster walk serves: every segment and whole-track file, in any order, whether the video was asked for before, +// after or not at all. +func TestPlanHLSSubtitleHarvestServesTheSameWebVTT(t *testing.T) { + ctx := context.Background() + videoFirst := map[string]func(plan *mp4.HLSPlan, n int) []int{ + "no video": func(*mp4.HLSPlan, int) []int { return nil }, + "the video before": func(_ *mp4.HLSPlan, n int) []int { return []int{n - 1} }, + "every other window": func(_ *mp4.HLSPlan, n int) []int { return []int{(n - 1) &^ 1} }, + } + for name, build := range map[string]func(testing.TB) string{ + "cues with durations": mp4.BuildSeekFixtureForTest, + "cues that end on the next cue": mp4.BuildSubCursorFixtureForTest, + } { + src := build(t) + for orderName, order := range subOrders { + for vName, video := range videoFirst { + t.Run(name+"/"+orderName+"/"+vName, func(t *testing.T) { + walked, err := mp4.PlanHLS(ctx, src, mp4.Options{SegmentMs: 2000}) + if err != nil { + t.Fatal(err) + } + mp4.DisableSubHarvestForTest(walked) + harvested, err := mp4.PlanHLS(ctx, src, mp4.Options{SegmentMs: 2000}) + if err != nil { + t.Fatal(err) + } + for _, res := range subNames(walked, order) { + var n int + if _, err := fmt.Sscanf(res[len("subX_"):], "%05d.vtt", &n); err == nil { + for _, v := range video(harvested, n) { + if v >= 0 && v < harvested.NumSegments() { + openAll(t, harvested, harvested.SegmentName(v)) + } + } + } + want, _, werr := walked.Resource(ctx, res) + got, _, gerr := harvested.Resource(ctx, res) + if werr != nil || gerr != nil { + t.Fatalf("%s: walked %v, harvested %v", res, werr, gerr) + } + if !bytes.Equal(got, want) { + t.Fatalf("%s differs when harvested:\n%s\n--- walked:\n%s", res, got, want) + } + } + if st := harvested.Stats(); st.SubtitleHarvestedClusters == 0 { + t.Errorf("no cluster harvested: %+v", st) + } + if st := walked.Stats(); st.SubtitleHarvestedClusters != 0 || st.SubtitleWalks == 0 { + t.Errorf("the reference harvested: %+v", st) + } + }) + } + } + } +} + +// The point of the harvest: a viewer playing the video with a subtitle reads the source once, as without the +// subtitle, instead of once more per subtitle rendition. +func TestPlanHLSSubtitleHarvestReadsTheSourceOnce(t *testing.T) { + ctx := context.Background() + src := mp4.BuildSeekFixtureForTest(t) + play := func(subs int, harvest bool) mp4.HLSPlanStats { + plan, err := mp4.PlanHLS(ctx, src, mp4.Options{SegmentMs: 2000, SourceAccess: mp4.SourceLocal}) + if err != nil { + t.Fatal(err) + } + if !harvest { + mp4.DisableSubHarvestForTest(plan) + } + for n := 0; n < plan.NumSegments(); n++ { // the whole file: a subtitle reads up to a stride ahead of the video, which the end evens out + openAll(t, plan, plan.SegmentName(n)) + for k := 1; k <= subs; k++ { + if _, _, err := plan.Resource(ctx, fmt.Sprintf("sub%d_%05d.vtt", k, n+1)); err != nil { + t.Fatal(err) + } + } + } + return plan.Stats() + } + alone, walked, harvested := play(0, true), play(2, false), play(2, true) + if walked.WalkReadBytes < 2*alone.WalkReadBytes { + t.Fatalf("the walked subtitles read %d bytes, the video alone %d: the fixture no longer shows the second walk", walked.WalkReadBytes, alone.WalkReadBytes) + } + if harvested.SubtitleWalks != 0 || harvested.WalkReadBytes*10 > alone.WalkReadBytes*11 { + t.Errorf("harvested: %d walks, %d bytes walked; the video alone %d, walked subtitles %d", harvested.SubtitleWalks, harvested.WalkReadBytes, alone.WalkReadBytes, walked.WalkReadBytes) + } +} diff --git a/mp4/hlsplan_subindex_test.go b/mp4/hlsplan_subindex_test.go index 55e0a32..e35a6a2 100644 --- a/mp4/hlsplan_subindex_test.go +++ b/mp4/hlsplan_subindex_test.go @@ -72,6 +72,7 @@ func TestPlanHLSSubtitleIndexServesTheSameWebVTT(t *testing.T) { if err != nil { t.Fatal(err) } + mp4.DisableSubHarvestForTest(walked) indexed, err := mp4.PlanHLS(ctx, src, mp4.Options{SegmentMs: 2000, SubtitleIndex: ix}) if err != nil { t.Fatal(err) @@ -181,6 +182,7 @@ func TestPlanHLSSubtitleIndexStaleFallsBackToTheWalk(t *testing.T) { if err != nil { t.Fatal(err) } + mp4.DisableSubHarvestForTest(walked) for name, index := range map[string]mp4.SubtitleBlockIndex{ "an index built from another file": other, "an index whose timecodes do not match": shiftedIndex{own}, @@ -196,8 +198,8 @@ func TestPlanHLSSubtitleIndexStaleFallsBackToTheWalk(t *testing.T) { t.Fatalf("%s: %s differs from the walk (%v, %v)", name, res, werr, gerr) } } - if st := plan.Stats(); st.SubtitleWalks == 0 || st.SubtitleIndexedBlocks != 0 { - t.Errorf("%s: %d walks, %d blocks kept from the index, want the walk alone", name, st.SubtitleWalks, st.SubtitleIndexedBlocks) + if st := plan.Stats(); st.SubtitleWalks+st.SubtitleHarvestedClusters == 0 || st.SubtitleIndexedBlocks != 0 { + t.Errorf("%s: %d walks, %d clusters harvested, %d blocks kept from the index, want the walk or the harvest alone", name, st.SubtitleWalks, st.SubtitleHarvestedClusters, st.SubtitleIndexedBlocks) } } } diff --git a/mp4/hlsplan_subtitle.go b/mp4/hlsplan_subtitle.go index 902e371..ec8eb1f 100644 --- a/mp4/hlsplan_subtitle.go +++ b/mp4/hlsplan_subtitle.go @@ -246,6 +246,11 @@ func (p *HLSPlan) extendCursorLocked(ctx context.Context, i int, cur *subCursor, // The index did not hold for this track: the walk below serves, from // the cursor as it stood. } + // The clusters the window walks read: the same scan, taken from them. + if served, err := p.extendCursorHarvested(ctx, i, cur, target, uptoMs); served || err != nil { + return err + } + start = cur.next // the first cluster the walks did not read whole p.winMu.Lock() p.stats.SubtitleWalks++ p.winMu.Unlock() diff --git a/mp4/hlsplan_walk.go b/mp4/hlsplan_walk.go index 07e82ad..35d9d1a 100644 --- a/mp4/hlsplan_walk.go +++ b/mp4/hlsplan_walk.go @@ -73,6 +73,11 @@ func (p *HLSPlan) walkWindow(ctx context.Context, n int, segStart, segEnd int64, var br *reader.BlockReader defer p.countWalk(&br)() var ahead [][]aheadBlock + subOf := p.harvestTracks() // the subtitle blocks are read along, for the subtitle renditions (see subHarvest) + kept := keep + for id := range subOf { + kept = append(kept[:len(kept):len(kept)], id) + } from := p.segPosAt(n) cold, err := p.pastDamage(p.coldStart(n)) // a seat inside a damaged region already met starts past it if err != nil { @@ -90,7 +95,11 @@ func (p *HLSPlan) walkWindow(ctx context.Context, n int, segStart, segEnd int64, } p.tolerateDamage(br) br.SetTrackDefaultDurations(p.trackDurs) - br.KeepTracks(keep...) + br.KeepTracks(kept...) + seat := cold + if from.Valid() { + seat = from.Off + } if !from.Valid() && cold < p.offsets[n] { // the clusters before the window's own, header-only, then the window's if ahead, err = p.coldAhead(ctx, src, br, n, index, segStart, structure, keepAudio); err != nil { return nil, nil, none, err @@ -103,11 +112,15 @@ func (p *HLSPlan) walkWindow(ctx context.Context, n int, segStart, segEnd int64, if err = br.RestartAt(own); err != nil { return nil, nil, none, err } + seat = own } br.SetHeaderOnly(structure) if keepAudio { br.SetHeaderOnlyTracks(p.tracks[p.videoIndex()].ft.outTrack.mkv.ID) + } else if subOf != nil { + br.SetHeaderOnlyTracks(keep...) // the subtitle payloads are read whatever the walk skips } + rec := p.newHarvestRec(subOf, seat) // The video is most of a window's bytes: its blocks are read straight // into the buffer its segment is served from (see windowInPlace), not @@ -192,8 +205,12 @@ func (p *HLSPlan) walkWindow(ctx context.Context, n int, segStart, segEnd int64, } } skips, inPlace = k, none + if rec != nil { + rec.broken = true // a damaged region passed over: this walk harvests nothing + } } if p.walkEnd(err) { // clean end, incl. a truncated/over-declared tail + rec.end() for ti := range p.tracks { if !crossed[ti] { p.learnTrackEnd(ti, maxInt64(seen[ti], segStart)) @@ -204,6 +221,11 @@ func (p *HLSPlan) walkWindow(ctx context.Context, n int, segStart, segEnd int64, if err != nil { return nil, nil, none, errf("read block: %w", err) } + if si, ok := subOf[b.TrackNumber]; ok { + rec.observe(br.Pos(), &b, si) + continue + } + rec.observe(br.Pos(), &b, -1) if farOff > 0 && crossedAny && !triedFar && p.walkedFar(from, br.Pos(), farOff) { // a track still missing far past the window: stored after the video? triedFar = true for ti := range p.tracks { @@ -328,6 +350,7 @@ func (p *HLSPlan) walkWindow(ctx context.Context, n int, segStart, segEnd int64, if segEnd < 1<<62 && p.fillDamage(windows, nextPts, resume, segStart, segEnd) { inPlace = none } + rec.commit() return windows, nextPts, inPlace, nil } diff --git a/mp4/hlswindow.go b/mp4/hlswindow.go index 74f43eb..fc94bd5 100644 --- a/mp4/hlswindow.go +++ b/mp4/hlswindow.go @@ -380,6 +380,9 @@ type HLSPlanStats struct { // name some blocks but could not be verified complete, which walk. SubtitleCueIndexed int64 SubtitleCueUnverified int64 + // SubtitleHarvestedClusters counts the clusters a subtitle rendition took its cues from as a window walk read + // them, instead of walking them again. + SubtitleHarvestedClusters int64 // SpreadLacedTracks counts the laced audio tracks whose frame size nothing // confirmed (no DefaultDuration, no frame size in the stream or a codec // table, no trusted frame count): their frames are spread over each From b012dceac233c79d88b6ca3df62ba88ed1443d2d Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 14:11:47 +0100 Subject: [PATCH 03/11] fix(hls): the subtitle harvest keeps the walk's strides and builds no window longer than a stride, nor the last --- CHANGELOG.md | 2 +- docs/library.md | 12 +- mp4/hlsplan_subharvest.go | 39 ++++-- mp4/hlsplan_subharvest_internal_test.go | 166 ++++++++++++++++++++++++ mp4/hlsplan_subharvest_test.go | 2 +- mp4/hlsplan_walk.go | 4 +- 6 files changed, 208 insertions(+), 17 deletions(-) create mode 100644 mp4/hlsplan_subharvest_internal_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 89ad1ee..8ac69be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,7 +27,7 @@ its series' file in [changelog/](changelog/) when a newer one ships. - `PlanHLS` without a subtitle index no longer walks the file again for each subtitle rendition: the cues come from the window walks, and on a local source a subtitle request builds the windows the video then serves from. A - 1080p episode played with one subtitle read 213 % of what was served, 108 % + 1080p episode played with one subtitle read 213 % of what was served, 113 % now (102 % without the subtitle); three subtitles cost what one does (`docs/library.md`, HLS plan). - A window walk and a streamed segment no longer ask the disk to read ahead diff --git a/docs/library.md b/docs/library.md index 24de0fd..808ea77 100644 --- a/docs/library.md +++ b/docs/library.md @@ -793,11 +793,13 @@ so a cluster a walk read whole is not walked again for its subtitles. On a local source whose segments are written from the source, a subtitle request builds the window tables it lacks itself, and the video then serves from the same walks: a viewer playing the video with a subtitle reads the file about -once (108 % of what was served over 100 segments of a real 1080p episode, 213 % -walking; three subtitles cost what one does). The tables run a little past the -request, by the 32.7 s a block may sit after its cluster. A cluster no walk read -whole, or one past a damaged region, is walked as before. `SubtitleHarvestedClusters` -counts the clusters served this way. +once (113 % of what was served over 100 segments of a real 1080p episode, 213 % +walking; three subtitles cost what one does). The tables run up to a minute +past the request, where the walk's strides stop. A window longer than a minute +and the last window, whose walk runs to the end of the file, are not built for +a subtitle; their clusters, any cluster no walk read whole and any past a +damaged region are walked as before. `SubtitleHarvestedClusters` counts the +clusters served from the walks. **Plan-time cost.** An MP4 plan builds `iframe.m3u8` eagerly, at `PlanHLS` time: the moov sample table already has every segment's exact sample count, diff --git a/mp4/hlsplan_subharvest.go b/mp4/hlsplan_subharvest.go index b882684..51b71d2 100644 --- a/mp4/hlsplan_subharvest.go +++ b/mp4/hlsplan_subharvest.go @@ -24,7 +24,7 @@ type subHarvest struct { // maxHarvestBlocks bounds the subtitle blocks a plan holds from its walks (a feature film's text tracks hold a few // thousand); past it, clusters not yet met are walked as before. -const maxHarvestBlocks = 1 << 18 +const maxHarvestBlocks = 1 << 16 // harvestCluster is what the walks read of one cluster. type harvestCluster struct { @@ -55,6 +55,7 @@ type harvestRec struct { seat int64 // offset the reader was seated at parts []*harvestCluster starts []int64 + count int64 // the reader's ClusterCount at the last block observed broken bool } @@ -78,11 +79,14 @@ func (p *HLSPlan) newHarvestRec(subOf map[uint64]int, seat int64) *harvestRec { return &harvestRec{p: p, subOf: subOf, seat: seat} } -// observe folds in the block the walk's reader just returned, sub being its index in p.subs or -1 for a media block. -func (r *harvestRec) observe(pos reader.BlockPos, b *mkv.Block, sub int) { +// observe folds in the block the walk's reader just returned, sub being its index in p.subs or -1 for a media block; +// count is the reader's ClusterCount. +func (r *harvestRec) observe(pos reader.BlockPos, count int64, b *mkv.Block, sub int) { if r == nil || r.broken { return } + passed := len(r.parts) > 0 && count != r.count && count != r.count+1 // a cluster holding no kept block lay between + r.count = count n := len(r.parts) if n == 0 || r.starts[n-1] != pos.ClusterStart { ms, ok := r.p.clusterMs(pos.ClusterTS) @@ -94,7 +98,9 @@ func (r *harvestRec) observe(pos reader.BlockPos, b *mkv.Block, sub int) { if n > 0 { prev := r.parts[n-1] prev.spans[0][1] = math.MaxInt64 // read to its end: the reader went on to this cluster - prev.next = pos.ClusterStart + if !passed { + prev.next = pos.ClusterStart // with one between, the walk's stop may fall on that one: left to the walk + } } else if r.seat > pos.ClusterStart { lo = r.seat // seated inside the cluster: what precedes the seat was not read } @@ -153,7 +159,7 @@ func (r *harvestRec) commit() { if c.whole { continue } - c.spans = append(c.spans, part.spans[0]) + c.spans = mergeSpans(append(c.spans, part.spans[0])) if part.next != -1 { c.next = part.next } @@ -194,6 +200,20 @@ func mergeHarvested(a, b []harvestBlock) []harvestBlock { return a } +// mergeSpans sorts the spans and joins those that meet, so a cluster read again by later walks holds no more spans. +func mergeSpans(spans [][2]int64) [][2]int64 { + sort.Slice(spans, func(i, j int) bool { return spans[i][0] < spans[j][0] }) + out := spans[:1] + for _, x := range spans[1:] { + if last := &out[len(out)-1]; x[0] <= last[1] { + last[1] = max(last[1], x[1]) + } else { + out = append(out, x) + } + } + return out +} + // spansCover reports whether the spans read a cluster starting at start through to its end with no gap. func spansCover(spans [][2]int64, start int64) bool { s := append([][2]int64(nil), spans...) @@ -245,6 +265,12 @@ func (p *HLSPlan) harvestWindow(ctx context.Context, off int64, tried map[int]bo if n < 0 || tried[n] { continue } + if n == p.segCount-1 { + continue // the last window's walk runs to the end of the file, whatever lies past its Cues: the stride bounds the walk's + } + if ms := p.windowMs(n); ms <= 0 || ms > subScanStrideMs { + continue // a window longer than the walk's stride reads more than the walk would + } tried[n] = true if _, err := p.table(ctx, n); err != nil { return false @@ -273,9 +299,6 @@ func (p *HLSPlan) extendCursorHarvested(ctx context.Context, i int, cur *subCurs if stopAt < cur.scanned { stopAt = math.MaxInt64 } - if target > cur.scanned && target < stopAt { - stopAt = target // a window built ahead is a walk the video may never use: build no further than this request needs - } next := cur.next if next == 0 { next = p.offsets[0] diff --git a/mp4/hlsplan_subharvest_internal_test.go b/mp4/hlsplan_subharvest_internal_test.go new file mode 100644 index 0000000..683f1bb --- /dev/null +++ b/mp4/hlsplan_subharvest_internal_test.go @@ -0,0 +1,166 @@ +package mp4 + +import ( + "bytes" + "context" + "fmt" + "os" + "path/filepath" + "testing" + + "github.com/gravity-zero/mkvgo/mkv" + "github.com/gravity-zero/mkvgo/mkv/writer" +) + +// buildLongCueFixture writes 400 s of video with a cue that outlasts subFastMaxCueDurMs, starting at 96 s. +func buildLongCueFixture(t *testing.T) string { + t.Helper() + w, h := uint32(320), uint32(240) + tracks := []mkv.Track{ + {ID: 1, Type: mkv.VideoTrack, Codec: "h264", CodecPrivate: fakeAVCC, Width: &w, Height: &h}, + {ID: 2, Type: mkv.SubtitleTrack, Codec: "srt", Language: "eng"}, + } + frame := append([]byte{0x00, 0x00, 0x00, 0x01, 0x65}, make([]byte, 1<<10)...) + var blks []mkv.Block + for i := 0; i < 2000; i++ { + blks = append(blks, mkv.Block{TrackNumber: 1, Timecode: int64(i) * 200, Keyframe: i%5 == 0, Data: frame}) + } + for _, b := range []mkv.Block{ + {TrackNumber: 2, Timecode: 1000, Duration: 2000, Data: []byte("head")}, + {TrackNumber: 2, Timecode: 96_000, Duration: 200_000, Data: []byte("the long cue")}, + } { + b.Keyframe = true + blks = append(blks, b) + } + for i := 1; i < len(blks); i++ { + for j := i; j > 0 && blks[j].Timecode < blks[j-1].Timecode; j-- { + blks[j], blks[j-1] = blks[j-1], blks[j] + } + } + path := filepath.Join(t.TempDir(), "long.mkv") + f, err := os.Create(path) + if err != nil { + t.Fatal(err) + } + defer f.Close() + const scale = 1_000_000 + c := &mkv.Container{Info: mkv.SegmentInfo{TimecodeScale: scale, MuxingApp: "mkvgo-test", WritingApp: "mkvgo-test"}} + m := writer.NewMKVWriter(f) + if err := m.WriteStart(); err != nil { + t.Fatal(err) + } + if err := m.WriteMetadata(c, tracks, 400_000); err != nil { + t.Fatal(err) + } + if err := writeTestClusters(m, scale, blks); err != nil { + t.Fatal(err) + } + if err := m.Finalize(); err != nil { + t.Fatal(err) + } + return path +} + +// A harvested scan stops where the walk's strides stop: a scan cut short at the request's own reach left a cue longer +// than the island margin unseen, and the jump that followed served an island that never reads it. +func TestSubtitleHarvestKeepsTheWalkStrides(t *testing.T) { + ctx := context.Background() + src := buildLongCueFixture(t) + walked, err := PlanHLS(ctx, src, Options{SegmentMs: 2000}) + if err != nil { + t.Fatal(err) + } + walked.harvest.off = true + harvested, err := PlanHLS(ctx, src, Options{SegmentMs: 2000, SourceAccess: SourceLocal}) + if err != nil { + t.Fatal(err) + } + for _, res := range []string{"sub1_00019.vtt", "sub1_00097.vtt"} { + want, _, werr := walked.Resource(ctx, res) + got, _, gerr := harvested.Resource(ctx, res) + if werr != nil || gerr != nil { + t.Fatalf("%s: walked %v, harvested %v", res, werr, gerr) + } + if res == "sub1_00097.vtt" && !bytes.Contains(want, []byte("the long cue")) { + t.Fatalf("the walk no longer serves the long cue at 192 s: the fixture misses the case\n%s", want) + } + if !bytes.Equal(got, want) { + t.Fatalf("%s differs when harvested:\n%s\n--- walked:\n%s", res, got, want) + } + } + if harvested.Stats().SubtitleHarvestedClusters == 0 { + t.Fatal("nothing harvested") + } +} + +// The media segments are the same bytes whether the walks read the subtitles along or not. +func TestSubtitleHarvestLeavesTheMediaAlone(t *testing.T) { + ctx := context.Background() + for _, build := range []func(testing.TB) string{buildSeekFixture, buildSubCursorFixture} { + src := build(t) + for _, local := range []bool{false, true} { + o := Options{SegmentMs: 2000} + if local { + o.SourceAccess = SourceLocal + } + plain, err := PlanHLS(ctx, src, o) + if err != nil { + t.Fatal(err) + } + plain.harvest.off = true + harvested, err := PlanHLS(ctx, src, o) + if err != nil { + t.Fatal(err) + } + for n := 0; n < harvested.NumSegments(); n++ { + if n%7 == 3 { // a subtitle asked first: its windows are walked for it + if _, _, err := harvested.Resource(ctx, fmt.Sprintf("sub1_%05d.vtt", n+1)); err != nil { + t.Fatal(err) + } + } + want, _, werr := plain.Resource(ctx, plain.SegmentName(n)) + got, _, gerr := harvested.Resource(ctx, harvested.SegmentName(n)) + if werr != nil || gerr != nil || !bytes.Equal(got, want) { + t.Fatalf("segment %d differs (local %v): %v, %v", n, local, werr, gerr) + } + } + } + } +} + +// A subtitle request builds no window longer than the walk's stride: a last window running over minutes the Cues +// leave out read the rest of the file for a subtitle the walk serves from a stride. +func TestSubtitleHarvestBuildsNoWindowLongerThanAStride(t *testing.T) { + ctx := context.Background() + src := buildSeekFixture(t) + plan, err := PlanHLS(ctx, src, Options{SegmentMs: 2 * subScanStrideMs, SourceAccess: SourceLocal}) + if err != nil { + t.Fatal(err) + } + if plan.windowMs(0) <= subScanStrideMs { + t.Fatalf("window 0 lasts %d ms: the fixture no longer has windows longer than a stride", plan.windowMs(0)) + } + if _, _, err := plan.Resource(ctx, "sub1_00001.vtt"); err != nil { + t.Fatal(err) + } + if st := plan.Stats(); st.TableBuilds != 0 || st.SubtitleWalks == 0 { + t.Errorf("%d tables built, %d walks: want the walk alone", st.TableBuilds, st.SubtitleWalks) + } +} + +// Nor the last window, whose walk runs to the end of the file: a file holding minutes past its Cues and its +// declared duration (a real episode: 2.6 GB past a last window declared 6.6 s long) read them all for one subtitle. +func TestSubtitleHarvestBuildsNotTheLastWindow(t *testing.T) { + ctx := context.Background() + plan, err := PlanHLS(ctx, buildSeekFixture(t), Options{SegmentMs: 2000, SourceAccess: SourceLocal}) + if err != nil { + t.Fatal(err) + } + last := plan.segCount - 1 + if plan.harvestWindow(ctx, plan.offsets[last], map[int]bool{last - 1: true}) { + t.Error("the last window was built for a subtitle") + } + if n := plan.Stats().TableBuilds; n != 0 { + t.Errorf("%d tables built", n) + } +} diff --git a/mp4/hlsplan_subharvest_test.go b/mp4/hlsplan_subharvest_test.go index 0541d4b..53033ab 100644 --- a/mp4/hlsplan_subharvest_test.go +++ b/mp4/hlsplan_subharvest_test.go @@ -108,7 +108,7 @@ func TestPlanHLSSubtitleHarvestReadsTheSourceOnce(t *testing.T) { if walked.WalkReadBytes < 2*alone.WalkReadBytes { t.Fatalf("the walked subtitles read %d bytes, the video alone %d: the fixture no longer shows the second walk", walked.WalkReadBytes, alone.WalkReadBytes) } - if harvested.SubtitleWalks != 0 || harvested.WalkReadBytes*10 > alone.WalkReadBytes*11 { + if harvested.SubtitleHarvestedClusters == 0 || harvested.WalkReadBytes*100 > alone.WalkReadBytes*102 { // the last window's clusters are walked t.Errorf("harvested: %d walks, %d bytes walked; the video alone %d, walked subtitles %d", harvested.SubtitleWalks, harvested.WalkReadBytes, alone.WalkReadBytes, walked.WalkReadBytes) } } diff --git a/mp4/hlsplan_walk.go b/mp4/hlsplan_walk.go index 35d9d1a..2bb8729 100644 --- a/mp4/hlsplan_walk.go +++ b/mp4/hlsplan_walk.go @@ -222,10 +222,10 @@ func (p *HLSPlan) walkWindow(ctx context.Context, n int, segStart, segEnd int64, return nil, nil, none, errf("read block: %w", err) } if si, ok := subOf[b.TrackNumber]; ok { - rec.observe(br.Pos(), &b, si) + rec.observe(br.Pos(), br.ClusterCount(), &b, si) continue } - rec.observe(br.Pos(), &b, -1) + rec.observe(br.Pos(), br.ClusterCount(), &b, -1) if farOff > 0 && crossedAny && !triedFar && p.walkedFar(from, br.Pos(), farOff) { // a track still missing far past the window: stored after the video? triedFar = true for ti := range p.tracks { From e4cb009fd9702a39afb3ad7acf5eb85c99460255 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 14:21:03 +0100 Subject: [PATCH 04/11] fix(hls): a synthesized index goes on past a damaged region instead of ending there --- CHANGELOG.md | 4 +++ mp4/hlsplan.go | 2 +- mp4/hlsplan_probe.go | 10 +++++-- mp4/hlsplan_synth_damage_test.go | 50 ++++++++++++++++++++++++++++++++ 4 files changed, 62 insertions(+), 4 deletions(-) create mode 100644 mp4/hlsplan_synth_damage_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 8ac69be..c2099cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,10 @@ its series' file in [changelog/](changelog/) when a newer one ships. (`docs/library.md`, HLS plan). - A window walk and a streamed segment no longer ask the disk to read ahead past the end of the file. +- `PlanHLS` with `SynthesizeIndex` passes over a damaged region as the window + walks do (`DamageBytes`) instead of ending the index there: the last window + ran over the rest of the file (a 43 min episode with damaged regions planned + 35 windows, the last served as one 2.2 GB segment; 309 now). ## [0.69.0] - 2026-11-17 diff --git a/mp4/hlsplan.go b/mp4/hlsplan.go index 6ec78ae..283ca64 100644 --- a/mp4/hlsplan.go +++ b/mp4/hlsplan.go @@ -441,7 +441,7 @@ func planHLS(ctx context.Context, srcPath string, opts ...Options) (*HLSPlan, er if !o.SynthesizeIndex { return nil, errf("%s: the Cues index no video keyframe: %w, or plan with Options.SynthesizeIndex (on-demand HLS seeks through them)", shown.Path(srcPath), mkv.ErrNoKeyframeIndex) } - cues, err = synthesizeVideoCues(ctx, srcPath, fs, c, vidID, p.trackDurs) + cues, err = p.synthesizeVideoCues(ctx, srcPath, fs, c, vidID, p.trackDurs) if err != nil { return nil, err } diff --git a/mp4/hlsplan_probe.go b/mp4/hlsplan_probe.go index 9f43356..29a6adc 100644 --- a/mp4/hlsplan_probe.go +++ b/mp4/hlsplan_probe.go @@ -272,8 +272,10 @@ func (p *HLSPlan) walkVideoHeadersOnly(ctx context.Context, fn func(mkv.Block) ( // payload bytes). The cost is the walk a persistent repair would pay anyway, // but nothing is written: the only road to seekable on-demand playback for a // source on a read-only mount. A structurally broken cluster stream still -// refuses (repair or salvage first). -func synthesizeVideoCues(ctx context.Context, srcPath string, fs *mkv.FS, c *mkv.Container, vidID uint64, trackDurs map[uint64]int64) ([]mkv.CuePoint, error) { +// refuses (repair or salvage first). A damaged region is passed over as the window walks pass over it +// (Options.DamageBytes): the cue points go on past it, where the synthesis stopped at the first one and left the +// last window to run over the rest of the file. +func (p *HLSPlan) synthesizeVideoCues(ctx context.Context, srcPath string, fs *mkv.FS, c *mkv.Container, vidID uint64, trackDurs map[uint64]int64) ([]mkv.CuePoint, error) { src, err := fs.DoOpen(srcPath) if err != nil { return nil, err @@ -286,6 +288,8 @@ func synthesizeVideoCues(ctx context.Context, srcPath string, fs *mkv.FS, c *mkv br.SetTrackDefaultDurations(trackDurs) br.KeepTracks(vidID) br.SetHeaderOnly(true) + p.tolerateDamage(br) + defer p.noteSkipped(br) var cues []mkv.CuePoint lastCluster := int64(-1) for { @@ -293,7 +297,7 @@ func synthesizeVideoCues(ctx context.Context, srcPath string, fs *mkv.FS, c *mkv return nil, err } b, err := br.Next() - if isBlockWalkEnd(err) { + if p.walkEnd(err) { return cues, nil } if err != nil { diff --git a/mp4/hlsplan_synth_damage_test.go b/mp4/hlsplan_synth_damage_test.go new file mode 100644 index 0000000..89fe37e --- /dev/null +++ b/mp4/hlsplan_synth_damage_test.go @@ -0,0 +1,50 @@ +package mp4 + +import ( + "bytes" + "context" + "testing" +) + +// A source without Cues and with a damaged region inside gets its index synthesized past the region, as its window +// walks pass over it: the synthesis stopped at the first damaged region, and the last window then ran over the rest +// of the file (a real 43 min episode planned 35 windows, the last served as one 2.2 GB segment). +func TestPlanHLSSynthesizeIndexPastADamagedRegion(t *testing.T) { + var blocks []genBlock + frame := make([]byte, 4<<10) + frame[0], frame[1], frame[2], frame[3], frame[4] = 0, 0, 0, 1, 0x65 + for i := 0; i < 1500; i++ { // 60 s of video, 40 ms frames, a keyframe each second + blocks = append(blocks, genBlock{track: 1, pts: int64(i) * 40, key: i%25 == 0, data: frame}) + } + tracks := synthFixtureTracks()[:1] + clean := buildNoCueMKV(t, tracks, blocks) + offs := clusterOffsets(t, clean) + if len(offs) < 50 { + t.Fatalf("%d clusters, want one a second", len(offs)) + } + bad := zeroedSource(t, clean, offs[30]+20<<10, offs[30]+40<<10) // 20 KiB inside the 30 s cluster + ctx := context.Background() + want, err := PlanHLS(ctx, clean, Options{SegmentMs: 2000, SynthesizeIndex: true}) + if err != nil { + t.Fatal(err) + } + plan, err := PlanHLS(ctx, bad, Options{SegmentMs: 2000, SynthesizeIndex: true}) + if err != nil { + t.Fatal(err) + } + if plan.NumSegments() != want.NumSegments() { + t.Fatalf("%d windows planned, %d on the undamaged file", plan.NumSegments(), want.NumSegments()) + } + last := plan.NumSegments() - 1 + got, err := plan.Segment(ctx, last) + if err != nil { + t.Fatal(err) + } + ref, err := want.Segment(ctx, last) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(got, ref) { + t.Errorf("the last window differs from the undamaged file's (%d vs %d bytes)", len(got), len(ref)) + } +} From 069430c00422bb9b23cb96b2a8c675046c172fb5 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 14:22:29 +0100 Subject: [PATCH 05/11] fix(ops): AudioStartDelays seeks over the attachments and allocates no declared cluster size --- CHANGELOG.md | 5 ++ mkv/ops/audiodelay.go | 29 +++++++--- mkv/ops/audiodelay_reads_test.go | 97 ++++++++++++++++++++++++++++++++ 3 files changed, 122 insertions(+), 9 deletions(-) create mode 100644 mkv/ops/audiodelay_reads_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index c2099cd..ce84bb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,11 @@ its series' file in [changelog/](changelog/) when a newer one ships. (`docs/library.md`, HLS plan). - A window walk and a streamed segment no longer ask the disk to read ahead past the end of the file. +- `AudioStartDelays` (and `Diagnose`) seek over what precedes the first + cluster instead of reading it: the attachments, a subtitle's fonts often + tens of MB, were read on every call. A cluster's declared size is no longer + allocated before its bytes arrive (a 32-byte file declaring 200 MiB + allocated 200 MiB). - `PlanHLS` with `SynthesizeIndex` passes over a damaged region as the window walks do (`DamageBytes`) instead of ending the index there: the last window ran over the rest of the file (a 43 min episode with damaged regions planned diff --git a/mkv/ops/audiodelay.go b/mkv/ops/audiodelay.go index ad8ffac..1ca1afb 100644 --- a/mkv/ops/audiodelay.go +++ b/mkv/ops/audiodelay.go @@ -100,6 +100,19 @@ func scanFirstBlockTimes(ctx context.Context, path string, fs *mkv.FS, want, vid } defer raw.Close() r := bufio.NewReaderSize(raw, reindexBufSize) + // skip passes n bytes over: a seek past what the buffer holds, so the attachments (fonts, tens of MB) stored + // ahead of the clusters are not read. + skip := func(n int64) error { + if n <= int64(r.Buffered()) { + _, err := r.Discard(int(n)) + return err + } + if _, err := raw.Seek(n-int64(r.Buffered()), io.SeekCurrent); err != nil { + return err + } + r.Reset(raw) + return nil + } ebmlHdr, _, err := ebml.ReadElementHeader(r) if err != nil || ebmlHdr.ID != ebml.IDEBMLHeader || ebmlHdr.Size < 0 { @@ -129,7 +142,7 @@ func scanFirstBlockTimes(ctx context.Context, path string, fs *mkv.FS, want, vid // The loop is tolerant past this point: a truncated or damaged tail does // not invalidate the first-block times already measured - the scan stops // and reports what it saw (Diagnose runs this on broken files by design). - var buf []byte + var buf bytes.Buffer var scanned int64 for scanned < audioDelayScanCap && !done() { if err := ctx.Err(); err != nil { @@ -143,20 +156,18 @@ func scanFirstBlockTimes(ctx context.Context, path string, fs *mkv.FS, want, vid break } if h.ID != mkv.IDCluster { - if _, err := io.CopyN(io.Discard, r, h.Size); err != nil { + if err := skip(h.Size); err != nil { break } continue } - if int(h.Size) > len(buf) { - buf = make([]byte, h.Size) - } - body := buf[:h.Size] - n, err := io.ReadFull(r, body) + // The body grows as its bytes arrive: a size the file only declares (forged, cut short) allocates nothing. + buf.Reset() + n, err := buf.ReadFrom(io.LimitReader(r, h.Size)) // A cut-off cluster still carries blocks up to the cut: scan the // prefix that was read, then stop. - scanClusterFirstTimes(body[:n], want, video, firstTC, &videoKF) - if err != nil { + scanClusterFirstTimes(buf.Bytes(), want, video, firstTC, &videoKF) + if err != nil || n < h.Size { break } scanned += h.Size diff --git a/mkv/ops/audiodelay_reads_test.go b/mkv/ops/audiodelay_reads_test.go new file mode 100644 index 0000000..81adcd1 --- /dev/null +++ b/mkv/ops/audiodelay_reads_test.go @@ -0,0 +1,97 @@ +package ops + +import ( + "context" + "os" + "path/filepath" + "runtime" + "testing" + + "github.com/gravity-zero/mkvgo/mkv" + "github.com/gravity-zero/mkvgo/mkv/writer" +) + +type countedFile struct { + *os.File + n *int64 +} + +func (f countedFile) Read(p []byte) (int, error) { + n, err := f.File.Read(p) + *f.n += int64(n) + return n, err +} + +// AudioStartDelays reads the first clusters, not what the muxer stored before them: the attachments (a subtitle's +// fonts, tens of MB) were read through on every call, from a NAS or over the network as much as from a disk. +func TestAudioStartDelaysSkipsTheAttachments(t *testing.T) { + path := filepath.Join(t.TempDir(), "fonts.mkv") + f, err := os.Create(path) + if err != nil { + t.Fatal(err) + } + mw := writer.NewMKVWriter(f) + if err := mw.WriteStart(); err != nil { + t.Fatal(err) + } + font := make([]byte, 20<<20) + c := &mkv.Container{ + Info: mkv.SegmentInfo{TimecodeScale: 1000000, MuxingApp: "test", WritingApp: "test"}, + Attachments: []mkv.Attachment{{ID: 1, Name: "font.ttf", MIMEType: "font/ttf", Size: int64(len(font)), Data: font}}, + } + if err := mw.WriteMetadata(c, []mkv.Track{videoTrack(1), audioTrack(2)}, 4000); err != nil { + t.Fatal(err) + } + for i := 0; i < 4; i++ { + ts := int64(i * 1000) + if err := mw.WriteClusterWithCues(ts, 1000000, []mkv.Block{ + {TrackNumber: 1, Timecode: ts, Keyframe: true, Data: []byte{0xAA}}, + {TrackNumber: 2, Timecode: ts + 300, Keyframe: true, Data: []byte{0x01}}, + }); err != nil { + t.Fatal(err) + } + } + if err := mw.Finalize(); err != nil { + t.Fatal(err) + } + f.Close() + var read int64 + fs := &mkv.FS{Open: func(p string) (mkv.ReadSeekCloser, error) { + f, err := os.Open(p) + if err != nil { + return nil, err + } + return countedFile{File: f, n: &read}, nil + }} + delays, err := AudioStartDelays(context.Background(), path, mkv.Options{FS: fs}) + if err != nil { + t.Fatal(err) + } + if delays[2] != 300_000_000 { + t.Errorf("delays = %+v, want track 2 = 300ms", delays) + } + if read > 2<<20 { + t.Errorf("%d bytes read for a file whose clusters weigh a few hundred: the 20 MiB attachment was read through", read) + } +} + +// A cluster's declared size allocates nothing the file does not hold: a few bytes declaring 200 MiB allocated it. +func TestAudioStartDelaysAllocatesNoDeclaredSize(t *testing.T) { + data := []byte{0x1A, 0x45, 0xDF, 0xA3, 0x80, // EBML header, empty + 0x18, 0x53, 0x80, 0x67, 0x01, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, // Segment, unknown size + 0x1F, 0x43, 0xB6, 0x75, 0x01, 0x00, 0x00, 0x00, 0x0C, 0x80, 0x00, 0x00, // Cluster declaring 200 MiB + 0xE7, 0x81, 0x00} // its Timestamp, then the file ends + path := filepath.Join(t.TempDir(), "forged.mkv") + if err := os.WriteFile(path, data, 0o644); err != nil { + t.Fatal(err) + } + var before, after runtime.MemStats + runtime.ReadMemStats(&before) + if _, _, err := scanFirstBlockTimes(context.Background(), path, mkv.FSFrom(nil), map[uint64]bool{2: true}, map[uint64]bool{1: true}); err != nil { + t.Fatal(err) + } + runtime.ReadMemStats(&after) + if got := after.TotalAlloc - before.TotalAlloc; got > 4<<20 { + t.Errorf("%d bytes allocated for a %d-byte file", got, len(data)) + } +} From cc91f20f5e67fa1b8ce0f594c535953ab633d745 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 14:23:05 +0100 Subject: [PATCH 06/11] fix(reader): a block's declared size allocates no more than the bytes that arrive --- CHANGELOG.md | 3 +++ mkv/reader/block_alloc_test.go | 35 ++++++++++++++++++++++++++++++++++ mkv/reader/blocks.go | 12 ++++++------ 3 files changed, 44 insertions(+), 6 deletions(-) create mode 100644 mkv/reader/block_alloc_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index ce84bb1..2e5358d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,9 @@ its series' file in [changelog/](changelog/) when a newer one ships. tens of MB, were read on every call. A cluster's declared size is no longer allocated before its bytes arrive (a 32-byte file declaring 200 MiB allocated 200 MiB). +- A block's declared size no longer allocates more than 8 MiB before its bytes + arrive (a 51-byte file declaring a 60 MiB block allocated 60 MiB on every + walk that met it). - `PlanHLS` with `SynthesizeIndex` passes over a damaged region as the window walks do (`DamageBytes`) instead of ending the index there: the last window ran over the rest of the file (a 43 min episode with damaged regions planned diff --git a/mkv/reader/block_alloc_test.go b/mkv/reader/block_alloc_test.go new file mode 100644 index 0000000..420876e --- /dev/null +++ b/mkv/reader/block_alloc_test.go @@ -0,0 +1,35 @@ +package reader + +import ( + "bytes" + "runtime" + "testing" +) + +// A block's declared size allocates no more than the bytes the file delivers: a few bytes declaring a 60 MiB block +// inside a cluster of unknown size allocated 60 MiB on every walk that met them. +func TestBlockReaderAllocatesNoDeclaredBlockSize(t *testing.T) { + for name, flags := range map[string]byte{"unlaced": 0x80, "laced": 0x82} { + t.Run(name, func(t *testing.T) { + data := []byte{0x1A, 0x45, 0xDF, 0xA3, 0x80, // EBML header, empty + 0x18, 0x53, 0x80, 0x67, 0x01, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, // Segment, unknown size + 0x1F, 0x43, 0xB6, 0x75, 0x01, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, // Cluster, unknown size + 0xE7, 0x81, 0x00, // Timestamp 0 + 0xA3, 0x13, 0xC0, 0x00, 0x00, 0x81, 0x00, 0x00, flags, // SimpleBlock declaring 60 MiB, track 1 + 0x00, 1, 2, 3, 4, 5, 6, 7, 8, 9} // ten bytes, then the file ends + br, err := NewBlockReader(bytes.NewReader(data), 1_000_000) + if err != nil { + t.Fatal(err) + } + var before, after runtime.MemStats + runtime.ReadMemStats(&before) + if _, err := br.Next(); err == nil { + t.Fatal("a block cut short must not read") + } + runtime.ReadMemStats(&after) + if got := after.TotalAlloc - before.TotalAlloc; got > 16<<20 { + t.Errorf("%d bytes allocated for a %d-byte file", got, len(data)) + } + }) + } +} diff --git a/mkv/reader/blocks.go b/mkv/reader/blocks.go index 54c2de9..9bacc35 100644 --- a/mkv/reader/blocks.go +++ b/mkv/reader/blocks.go @@ -983,10 +983,11 @@ func (br *BlockReader) parseBlock(size int64, simple bool) (mkv.Block, error) { if br.blockBuf != nil { data = br.blockBuf(uint64(trackNum), int(dataSize)) } - if int64(len(data)) != dataSize { - data = make([]byte, dataSize) - } - if _, err := io.ReadFull(br.r, data); err != nil { + if int64(len(data)) == dataSize { + if _, err := io.ReadFull(br.r, data); err != nil { + return mkv.Block{}, err + } + } else if data, err = readExact(br.r, dataSize); err != nil { // a declared size the file may not hold: grown as read return mkv.Block{}, err } return mkv.Block{ @@ -1016,8 +1017,7 @@ func (br *BlockReader) parseBlock(size int64, simple bool) (mkv.Block, error) { return mkv.Block{}, err } } else { - raw = make([]byte, dataSize) - if _, err := io.ReadFull(br.r, raw); err != nil { + if raw, err = readExact(br.r, dataSize); err != nil { return mkv.Block{}, err } if len(raw) == 0 { From c4a443418240c48417e1371dce61cd8dbd23c3f5 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 14:24:22 +0100 Subject: [PATCH 07/11] fix(ops): retime and reindex grow a cluster's buffer as its bytes arrive instead of allocating its declared size --- CHANGELOG.md | 2 ++ mkv/ops/readgrowing.go | 36 ++++++++++++++++++++++++++++++ mkv/ops/readgrowing_test.go | 44 +++++++++++++++++++++++++++++++++++++ mkv/ops/reindex.go | 16 ++++++-------- mkv/ops/retime.go | 7 ++---- 5 files changed, 91 insertions(+), 14 deletions(-) create mode 100644 mkv/ops/readgrowing.go create mode 100644 mkv/ops/readgrowing_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e5358d..15ded8a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,6 +40,8 @@ its series' file in [changelog/](changelog/) when a newer one ships. - A block's declared size no longer allocates more than 8 MiB before its bytes arrive (a 51-byte file declaring a 60 MiB block allocated 60 MiB on every walk that met it). +- `retime` and `reindex` no longer allocate a cluster's declared size before + its bytes arrive (a 32-byte file declaring a 200 MiB cluster allocated it). - `PlanHLS` with `SynthesizeIndex` passes over a damaged region as the window walks do (`DamageBytes`) instead of ending the index there: the last window ran over the rest of the file (a 43 min episode with damaged regions planned diff --git a/mkv/ops/readgrowing.go b/mkv/ops/readgrowing.go new file mode 100644 index 0000000..1c3a7f5 --- /dev/null +++ b/mkv/ops/readgrowing.go @@ -0,0 +1,36 @@ +package ops + +import ( + "io" + + "github.com/gravity-zero/mkvgo/internal/poison" +) + +// readGrowStep is how much a body read in place of a declared size grows its buffer at a time: a size the file only +// declares (forged, cut short) allocates in proportion to the bytes that arrive, not to the declaration. +const readGrowStep = 8 << 20 + +// readBody reads an element body of n declared bytes into buf, reused when it already holds n, grown as the bytes +// arrive otherwise. A short read returns what arrived with io.ErrUnexpectedEOF (or io.EOF when nothing did). +func readBody(r io.Reader, buf []byte, n int64) ([]byte, error) { + if int64(cap(buf)) >= n { + buf = poison.Reuse(buf, int(n)) + _, err := io.ReadFull(r, buf) + return buf, err + } + buf = buf[:0] + for int64(len(buf)) < n { + step := min(n-int64(len(buf)), max(int64(len(buf)), readGrowStep)) + next := make([]byte, len(buf), len(buf)+int(step)) + copy(next, buf) + got, err := io.ReadFull(r, next[len(next):cap(next)]) + buf = next[:len(next)+got] + if err != nil { + if err == io.EOF && len(buf) > 0 { + err = io.ErrUnexpectedEOF + } + return buf, err + } + } + return buf, nil +} diff --git a/mkv/ops/readgrowing_test.go b/mkv/ops/readgrowing_test.go new file mode 100644 index 0000000..534935a --- /dev/null +++ b/mkv/ops/readgrowing_test.go @@ -0,0 +1,44 @@ +package ops + +import ( + "bytes" + "context" + "io" + "runtime" + "testing" +) + +// A body read in place of its declared size allocates in proportion to the bytes that arrive. +func TestReadBodyAllocatesWhatArrives(t *testing.T) { + var before, after runtime.MemStats + runtime.ReadMemStats(&before) + got, err := readBody(bytes.NewReader([]byte("ten bytes!")), nil, 200<<20) + runtime.ReadMemStats(&after) + if err != io.ErrUnexpectedEOF || string(got) != "ten bytes!" { + t.Fatalf("readBody = %q, %v; want the ten bytes and io.ErrUnexpectedEOF", got, err) + } + if n := after.TotalAlloc - before.TotalAlloc; n > 16<<20 { + t.Errorf("%d bytes allocated for ten", n) + } + whole := bytes.Repeat([]byte{7}, 20<<20) + if got, err := readBody(bytes.NewReader(whole), make([]byte, 0, 1<<10), int64(len(whole))); err != nil || !bytes.Equal(got, whole) { + t.Fatalf("a body past one step: %d bytes, %v", len(got), err) + } +} + +// retime's scan allocates no cluster size a few bytes declare. +func TestRetimeScanAllocatesNoDeclaredClusterSize(t *testing.T) { + data := []byte{0x1A, 0x45, 0xDF, 0xA3, 0x80, // EBML header, empty + 0x18, 0x53, 0x80, 0x67, 0x01, 0x00, 0x00, 0x00, 0x0C, 0x80, 0x00, 0x20, // Segment declaring 200 MiB + 32 + 0x1F, 0x43, 0xB6, 0x75, 0x01, 0x00, 0x00, 0x00, 0x0C, 0x80, 0x00, 0x00, // Cluster declaring 200 MiB + 0xE7, 0x81, 0x00} // its Timestamp, then the file ends + var before, after runtime.MemStats + runtime.ReadMemStats(&before) + if _, _, err := retimeScan(context.Background(), bytes.NewReader(data), int64(len(data)), map[uint64]int64{1: 10}, nil, 1<<20); err == nil { + t.Fatal("a cluster cut short must not scan") + } + runtime.ReadMemStats(&after) + if n := after.TotalAlloc - before.TotalAlloc; n > 16<<20 { + t.Errorf("%d bytes allocated for a %d-byte file", n, len(data)) + } +} diff --git a/mkv/ops/reindex.go b/mkv/ops/reindex.go index b5fe41b..4308dea 100644 --- a/mkv/ops/reindex.go +++ b/mkv/ops/reindex.go @@ -16,7 +16,6 @@ import ( "github.com/gravity-zero/mkvgo/ebml" "github.com/gravity-zero/mkvgo/internal/mpegts" "github.com/gravity-zero/mkvgo/internal/oneopt" - "github.com/gravity-zero/mkvgo/internal/poison" "github.com/gravity-zero/mkvgo/mkv" "github.com/gravity-zero/mkvgo/mkv/reader" "github.com/gravity-zero/mkvgo/mkv/writer" @@ -116,12 +115,11 @@ func reindexFastCopy(mw *writer.MKVWriter, srcPath string, timecodeScale int64, } firstCluster = false - // Grow reusable buffer once. - clusterBuf = poison.Reuse(clusterBuf, int(h.Size)) - body := clusterBuf - if _, err := io.ReadFull(r, body); err != nil { + var err error + if clusterBuf, err = readBody(r, clusterBuf, h.Size); err != nil { return fmt.Errorf("reindex: read cluster body: %w", err) } + body := clusterBuf consumed += int64(hdrBytes) + h.Size // Capture output offset BEFORE writing - this is the ClusterPos. @@ -910,11 +908,11 @@ func reindexCopyOut(ctx context.Context, srcPath, dstPath string, fs *mkv.FS, sy return nil, 0, nil, fmt.Errorf("reindex: cluster size %d exceeds limit (%d)", h.Size, maxReindexClusterSize) } - clusterBuf = poison.Reuse(clusterBuf, int(h.Size)) - body := clusterBuf - if _, err := io.ReadFull(r, body); err != nil { - return nil, 0, nil, fmt.Errorf("reindex: read cluster body: %w", err) + var rerr error + if clusterBuf, rerr = readBody(r, clusterBuf, h.Size); rerr != nil { + return nil, 0, nil, fmt.Errorf("reindex: read cluster body: %w", rerr) } + body := clusterBuf if cause := clusterBodyParses(body, elemStart+int64(hdrBytes)); cause != nil { return nil, 0, nil, fmt.Errorf("reindex: cluster at %d: %w (a corrupted region can be skipped with Options.Resync / --resync): %w", elemStart, cause, ErrCorruptSource) } diff --git a/mkv/ops/retime.go b/mkv/ops/retime.go index 8cf9ad2..6bdbfda 100644 --- a/mkv/ops/retime.go +++ b/mkv/ops/retime.go @@ -533,13 +533,10 @@ func retimeScan(ctx context.Context, f io.ReadSeeker, size int64, shiftTC map[ui switch h.ID { case mkv.IDCluster, mkv.IDCues: - if int(h.Size) > len(buf) { - buf = make([]byte, h.Size) - } - body := buf[:h.Size] - if _, err := io.ReadFull(r, body); err != nil { + if buf, err = readBody(r, buf, h.Size); err != nil { return nil, nil, fmt.Errorf("retime: read 0x%X body: %w", h.ID, err) } + body := buf bodyOff := elemStart + int64(hdrBytes) var ps []retimePatch if h.ID == mkv.IDCluster { From e007e8d54af76e30d1c11252e004d9112bf46f87 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 14:47:22 +0100 Subject: [PATCH 08/11] fix(hls): a remote source is asked for no range past the file and never an open-ended one --- CHANGELOG.md | 4 ++- mp4/hlsplan_ahead.go | 15 +++++++++- mp4/hlsplan_peek_hint_test.go | 55 +++++++++++++++++++++++++++++++++++ mp4/hlsplan_probe.go | 16 +++++----- 4 files changed, 79 insertions(+), 11 deletions(-) create mode 100644 mp4/hlsplan_peek_hint_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 15ded8a..a95e3e2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,7 +31,9 @@ its series' file in [changelog/](changelog/) when a newer one ships. now (102 % without the subtitle); three subtitles cost what one does (`docs/library.md`, HLS plan). - A window walk and a streamed segment no longer ask the disk to read ahead - past the end of the file. + past the end of the file, and a remote source (`mkv.RangeHinter`) is no + longer asked for an open-ended range: the plan's head peek and its last + window hinted to `MaxInt64`. - `AudioStartDelays` (and `Diagnose`) seek over what precedes the first cluster instead of reading it: the attachments, a subtitle's fonts often tens of MB, were read on every call. A cluster's declared size is no longer diff --git a/mp4/hlsplan_ahead.go b/mp4/hlsplan_ahead.go index ac2bdab..048fbf0 100644 --- a/mp4/hlsplan_ahead.go +++ b/mp4/hlsplan_ahead.go @@ -74,7 +74,20 @@ func (p *HLSPlan) hintRange(src io.Reader, start, end int64) { if f, ok := src.(*os.File); ok && end != math.MaxInt64 && !p.onNetwork(f) { // the walk reads through the range: have it all coming in at once adviseWillNeed(f, start, end-start) } - if h, ok := src.(mkv.RangeHinter); ok { + p.hintRemote(src, start, end) +} + +// hintRemote asks a remote source for [start, end) in one request, the end held to the Segment's or the file's: an +// unbounded walk (the last window, a peek past the last cue) asked for an open-ended range. +func (p *HLSPlan) hintRemote(src io.Reader, start, end int64) { + h, ok := src.(mkv.RangeHinter) + if !ok { + return + } + if last := p.clusterEndOff(math.MaxInt64); last > 0 && end > last { + end = last + } + if end > start { h.HintRange(start, end) } } diff --git a/mp4/hlsplan_peek_hint_test.go b/mp4/hlsplan_peek_hint_test.go new file mode 100644 index 0000000..581a29b --- /dev/null +++ b/mp4/hlsplan_peek_hint_test.go @@ -0,0 +1,55 @@ +package mp4 + +import ( + "context" + "math" + "os" + "testing" + + "github.com/gravity-zero/mkvgo/mkv" +) + +type hintRecorder struct { + *os.File + hints *[][2]int64 +} + +func (h hintRecorder) HintRange(off, end int64) { *h.hints = append(*h.hints, [2]int64{off, end}) } + +// A remote source is asked for no range past the file's end, and never for an open-ended one: the plan's head peek +// hinted its source directly, past the cap the window walks have, and to MaxInt64 on a single-window file (an +// open-ended request a remote source then dropped, the connection with it). +func TestPlanHintsNoRangePastTheFile(t *testing.T) { + src := buildSeekFixture(t) + st, err := os.Stat(src) + if err != nil { + t.Fatal(err) + } + var hints [][2]int64 + fs := &mkv.FS{Open: func(p string) (mkv.ReadSeekCloser, error) { + f, err := os.Open(p) + if err != nil { + return nil, err + } + return hintRecorder{File: f, hints: &hints}, nil + }} + ctx := context.Background() + for _, segMs := range []int64{2000, 10_000_000} { // many windows, then one + hints = nil + plan, err := PlanHLS(ctx, src, Options{SegmentMs: segMs, FS: fs, StreamFromFS: true}) + if err != nil { + t.Fatal(err) + } + if _, err := plan.Segment(ctx, 0); err != nil { + t.Fatal(err) + } + if len(hints) == 0 { + t.Fatal("no range hinted") + } + for _, h := range hints { + if h[1] == math.MaxInt64 || h[1] > st.Size() { + t.Errorf("SegmentMs %d: range [%d, %d) hinted for a file of %d bytes", segMs, h[0], h[1], st.Size()) + } + } + } +} diff --git a/mp4/hlsplan_probe.go b/mp4/hlsplan_probe.go index 29a6adc..98a8ec9 100644 --- a/mp4/hlsplan_probe.go +++ b/mp4/hlsplan_probe.go @@ -174,17 +174,15 @@ func (p *HLSPlan) walkBlocksPos(ctx context.Context, off, end int64, headerOnly return err } defer src.Close() - if h, ok := src.(mkv.RangeHinter); ok { - // Unbounded, the walk runs until fn has seen enough: up to the next window's cluster, or the end past the last. - to := end - if to < 0 { - to = math.MaxInt64 - if i := sort.Search(len(p.offsets), func(k int) bool { return p.offsets[k] > off }); i < len(p.offsets) { - to = p.offsets[i] + windowPeekBytes - } + // Unbounded, the walk runs until fn has seen enough: up to the next window's cluster, or the end past the last. + to := end + if to < 0 { + to = math.MaxInt64 + if i := sort.Search(len(p.offsets), func(k int) bool { return p.offsets[k] > off }); i < len(p.offsets) { + to = p.offsets[i] + windowPeekBytes } - h.HintRange(off, to) } + p.hintRemote(src, off, to) br, err := p.blockReaderAt(src, off) if err != nil { return err From f0c0959aa68efd3ebcf36a25ee34bd8c187123c5 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 15:00:03 +0100 Subject: [PATCH 09/11] perf(hls): a subtitle request builds the windows it lacks on a network source too --- CHANGELOG.md | 9 ++-- docs/library.md | 16 ++++--- mp4/hlsplan_subharvest.go | 11 +++-- mp4/hlsplan_subharvest_internal_test.go | 9 ++-- mp4/hlsplan_subharvest_test.go | 62 +++++++++++++------------ 5 files changed, 57 insertions(+), 50 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a95e3e2..42ea3f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,10 +25,11 @@ its series' file in [changelog/](changelog/) when a newer one ships. ### Fixed - `PlanHLS` without a subtitle index no longer walks the file again for each - subtitle rendition: the cues come from the window walks, and on a local - source a subtitle request builds the windows the video then serves from. A - 1080p episode played with one subtitle read 213 % of what was served, 113 % - now (102 % without the subtitle); three subtitles cost what one does + subtitle rendition: the cues come from the window walks, and a subtitle + request builds the windows the video then serves from (over a network + mount, half of what was asked of the source before). A 1080p episode + played with one subtitle read 213 % of what was served, 113 % now (102 % + without the subtitle); three subtitles cost what one does (`docs/library.md`, HLS plan). - A window walk and a streamed segment no longer ask the disk to read ahead past the end of the file, and a remote source (`mkv.RangeHinter`) is no diff --git a/docs/library.md b/docs/library.md index 808ea77..73a5bc0 100644 --- a/docs/library.md +++ b/docs/library.md @@ -789,12 +789,16 @@ plan counts both outcomes (`SubtitleCueIndexed`, `SubtitleCueUnverified`); With neither, the subtitle renditions take their cues from the window walks: a walk reads every block of the clusters it covers, the subtitles' included, -so a cluster a walk read whole is not walked again for its subtitles. On a -local source whose segments are written from the source, a subtitle request -builds the window tables it lacks itself, and the video then serves from the -same walks: a viewer playing the video with a subtitle reads the file about -once (113 % of what was served over 100 segments of a real 1080p episode, 213 % -walking; three subtitles cost what one does). The tables run up to a minute +so a cluster a walk read whole is not walked again for its subtitles. When the +segments are written from the source, a subtitle request builds the window +tables it lacks itself, and the video then serves from the same walks: a viewer +playing the video with a subtitle reads a local file about once (113 % of what +was served over 100 segments of a real 1080p episode, 213 % walking; three +subtitles cost what one does). A network source keeps the segments its walks +read under the window budget, which a subtitle ahead of the video can outrun: +those are fetched again, and the source still gives about half what it did +(1.30 GB asked for 30 segments with three subtitles, 666 MB now, 333 MB without +them). The tables run up to a minute past the request, where the walk's strides stop. A window longer than a minute and the last window, whose walk runs to the end of the file, are not built for a subtitle; their clusters, any cluster no walk read whole and any past a diff --git a/mp4/hlsplan_subharvest.go b/mp4/hlsplan_subharvest.go index 51b71d2..9bdbb9e 100644 --- a/mp4/hlsplan_subharvest.go +++ b/mp4/hlsplan_subharvest.go @@ -251,10 +251,13 @@ func (h *subHarvest) harvested(start int64, sub int) (ms int64, known, whole boo return c.ms, true, true, c.next, blocks } -// prebuildsTables reports whether a subtitle cursor may build the window tables it needs: a local Matroska source -// the segments are written from, whose tables are structure only, so the video then serves from the very walk. -func (p *HLSPlan) prebuildsTables(ctx context.Context) bool { - return !p.mp4src && p.streams() && !p.networkSrc(ctx) +// prebuildsTables reports whether a subtitle cursor may build the window tables it needs: a Matroska source the +// segments are written from, so the video then serves from the very walk. A network source's walk keeps the segments +// under the window budget, which a cursor ahead of the video can outrun: those are copied again when asked for, and +// still the source gave half what it did walked for each subtitle (a 1080p episode over a network mount, 30 segments +// with 3 subtitles: 1.30 GB asked of it, 666 MB now; 333 MB without the subtitles). +func (p *HLSPlan) prebuildsTables(context.Context) bool { + return !p.mp4src && p.streams() } // harvestWindow builds the table of a window whose walk reads the cluster at off, one not built yet in this scan; diff --git a/mp4/hlsplan_subharvest_internal_test.go b/mp4/hlsplan_subharvest_internal_test.go index 683f1bb..33ad8f7 100644 --- a/mp4/hlsplan_subharvest_internal_test.go +++ b/mp4/hlsplan_subharvest_internal_test.go @@ -98,11 +98,8 @@ func TestSubtitleHarvestLeavesTheMediaAlone(t *testing.T) { ctx := context.Background() for _, build := range []func(testing.TB) string{buildSeekFixture, buildSubCursorFixture} { src := build(t) - for _, local := range []bool{false, true} { - o := Options{SegmentMs: 2000} - if local { - o.SourceAccess = SourceLocal - } + for _, access := range []SourceAccess{SourceAuto, SourceLocal, SourceNetwork} { + o := Options{SegmentMs: 2000, SourceAccess: access} plain, err := PlanHLS(ctx, src, o) if err != nil { t.Fatal(err) @@ -121,7 +118,7 @@ func TestSubtitleHarvestLeavesTheMediaAlone(t *testing.T) { want, _, werr := plain.Resource(ctx, plain.SegmentName(n)) got, _, gerr := harvested.Resource(ctx, harvested.SegmentName(n)) if werr != nil || gerr != nil || !bytes.Equal(got, want) { - t.Fatalf("segment %d differs (local %v): %v, %v", n, local, werr, gerr) + t.Fatalf("segment %d differs (access %v): %v, %v", n, access, werr, gerr) } } } diff --git a/mp4/hlsplan_subharvest_test.go b/mp4/hlsplan_subharvest_test.go index 53033ab..5de8c74 100644 --- a/mp4/hlsplan_subharvest_test.go +++ b/mp4/hlsplan_subharvest_test.go @@ -41,41 +41,43 @@ func TestPlanHLSSubtitleHarvestServesTheSameWebVTT(t *testing.T) { src := build(t) for orderName, order := range subOrders { for vName, video := range videoFirst { - t.Run(name+"/"+orderName+"/"+vName, func(t *testing.T) { - walked, err := mp4.PlanHLS(ctx, src, mp4.Options{SegmentMs: 2000}) - if err != nil { - t.Fatal(err) - } - mp4.DisableSubHarvestForTest(walked) - harvested, err := mp4.PlanHLS(ctx, src, mp4.Options{SegmentMs: 2000}) - if err != nil { - t.Fatal(err) - } - for _, res := range subNames(walked, order) { - var n int - if _, err := fmt.Sscanf(res[len("subX_"):], "%05d.vtt", &n); err == nil { - for _, v := range video(harvested, n) { - if v >= 0 && v < harvested.NumSegments() { - openAll(t, harvested, harvested.SegmentName(v)) + for _, access := range []mp4.SourceAccess{mp4.SourceLocal, mp4.SourceNetwork} { + t.Run(fmt.Sprintf("%s/%s/%s/%v", name, orderName, vName, access), func(t *testing.T) { + walked, err := mp4.PlanHLS(ctx, src, mp4.Options{SegmentMs: 2000}) + if err != nil { + t.Fatal(err) + } + mp4.DisableSubHarvestForTest(walked) + harvested, err := mp4.PlanHLS(ctx, src, mp4.Options{SegmentMs: 2000, SourceAccess: access}) + if err != nil { + t.Fatal(err) + } + for _, res := range subNames(walked, order) { + var n int + if _, err := fmt.Sscanf(res[len("subX_"):], "%05d.vtt", &n); err == nil { + for _, v := range video(harvested, n) { + if v >= 0 && v < harvested.NumSegments() { + openAll(t, harvested, harvested.SegmentName(v)) + } } } + want, _, werr := walked.Resource(ctx, res) + got, _, gerr := harvested.Resource(ctx, res) + if werr != nil || gerr != nil { + t.Fatalf("%s: walked %v, harvested %v", res, werr, gerr) + } + if !bytes.Equal(got, want) { + t.Fatalf("%s differs when harvested:\n%s\n--- walked:\n%s", res, got, want) + } } - want, _, werr := walked.Resource(ctx, res) - got, _, gerr := harvested.Resource(ctx, res) - if werr != nil || gerr != nil { - t.Fatalf("%s: walked %v, harvested %v", res, werr, gerr) + if st := harvested.Stats(); st.SubtitleHarvestedClusters == 0 { + t.Errorf("no cluster harvested: %+v", st) } - if !bytes.Equal(got, want) { - t.Fatalf("%s differs when harvested:\n%s\n--- walked:\n%s", res, got, want) + if st := walked.Stats(); st.SubtitleHarvestedClusters != 0 || st.SubtitleWalks == 0 { + t.Errorf("the reference harvested: %+v", st) } - } - if st := harvested.Stats(); st.SubtitleHarvestedClusters == 0 { - t.Errorf("no cluster harvested: %+v", st) - } - if st := walked.Stats(); st.SubtitleHarvestedClusters != 0 || st.SubtitleWalks == 0 { - t.Errorf("the reference harvested: %+v", st) - } - }) + }) + } } } } From 00bdc1bf1d6f642aa238f620803db4fc923f93cb Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 15:17:59 +0100 Subject: [PATCH 10/11] perf(hls): a subtitle builds no window behind its request, its own walk serves the other subtitles, and damage costs the harvest one cluster --- mp4/hlsplan_subharvest.go | 36 +++++++++--- mp4/hlsplan_subharvest_internal_test.go | 75 ++++++++++++++++++++++++- mp4/hlsplan_subharvest_test.go | 2 +- mp4/hlsplan_subtitle.go | 34 ++++++++++- mp4/hlsplan_walk.go | 4 +- 5 files changed, 136 insertions(+), 15 deletions(-) diff --git a/mp4/hlsplan_subharvest.go b/mp4/hlsplan_subharvest.go index 9bdbb9e..c3976db 100644 --- a/mp4/hlsplan_subharvest.go +++ b/mp4/hlsplan_subharvest.go @@ -56,6 +56,7 @@ type harvestRec struct { parts []*harvestCluster starts []int64 count int64 // the reader's ClusterCount at the last block observed + resume bool // a damaged region was passed over: the next block starts a record of its own broken bool } @@ -88,14 +89,16 @@ func (r *harvestRec) observe(pos reader.BlockPos, count int64, b *mkv.Block, sub passed := len(r.parts) > 0 && count != r.count && count != r.count+1 // a cluster holding no kept block lay between r.count = count n := len(r.parts) - if n == 0 || r.starts[n-1] != pos.ClusterStart { + if r.resume || n == 0 || r.starts[n-1] != pos.ClusterStart { ms, ok := r.p.clusterMs(pos.ClusterTS) if !ok || (n > 0 && pos.ClusterStart < r.starts[n-1]) { r.broken = true return } lo := pos.ClusterStart - if n > 0 { + if r.resume { + lo, r.resume = pos.Off, false // past the region: what precedes this block in its cluster was not read + } else if n > 0 { prev := r.parts[n-1] prev.spans[0][1] = math.MaxInt64 // read to its end: the reader went on to this cluster if !passed { @@ -127,9 +130,21 @@ func (r *harvestRec) observe(pos reader.BlockPos, count int64, b *mkv.Block, sub c.blocks = append(c.blocks, harvestBlock{off: pos.Off, frame: frame, sub: sub, cue: cue, ok: ok, recovered: recovered, err: err}) } +// skip drops the cluster a damaged region was passed over in: the walk's clusters before it stand, and the record +// resumes at the next block. +func (r *harvestRec) skip() { + if r == nil || r.broken { + return + } + if n := len(r.parts); n > 0 { + r.parts, r.starts = r.parts[:n-1], r.starts[:n-1] + } + r.resume = true +} + // end marks the walk's last cluster read to the source's clean end. func (r *harvestRec) end() { - if r == nil || r.broken || len(r.parts) == 0 { + if r == nil || r.broken || r.resume || len(r.parts) == 0 { // ending past a damaged region: its tail was not seen return } last := r.parts[len(r.parts)-1] @@ -260,12 +275,12 @@ func (p *HLSPlan) prebuildsTables(context.Context) bool { return !p.mp4src && p.streams() } -// harvestWindow builds the table of a window whose walk reads the cluster at off, one not built yet in this scan; -// it reports whether it built one. -func (p *HLSPlan) harvestWindow(ctx context.Context, off int64, tried map[int]bool) bool { +// harvestWindow builds the table of a window from first on whose walk reads the cluster at off, one not built yet in +// this scan; it reports whether it built one. +func (p *HLSPlan) harvestWindow(ctx context.Context, off int64, first int, tried map[int]bool) bool { k := sort.Search(min(len(p.offsets), p.segCount), func(k int) bool { return p.offsets[k] > off }) - 1 for _, n := range []int{k, k - 1} { // a walk seated past the cluster's start leaves its head to the previous window's - if n < 0 || tried[n] { + if n < first || tried[n] { continue } if n == p.segCount-1 { @@ -289,7 +304,10 @@ func (p *HLSPlan) harvestWindow(ctx context.Context, off int64, tried map[int]bo // what precedes it committed, and the walk serves from there. Caller holds subMu[i]. func (p *HLSPlan) extendCursorHarvested(ctx context.Context, i int, cur *subCursor, target, uptoMs int64) (served bool, err error) { st := &p.subScan[i] - build := p.prebuildsTables(ctx) + build := p.prebuildsTables(ctx) && uptoMs > 0 + // Only the request's own window and those after it, which the video plays: the margin behind a seek and the probe + // of the track's head are walked as before, a window built whole reading its overlap with the next as well. + first := sort.Search(len(p.bounds), func(k int) bool { return p.bounds[k] >= uptoMs }) - 1 tried := map[int]bool{} var took int64 defer func() { @@ -313,7 +331,7 @@ func (p *HLSPlan) extendCursorHarvested(ctx context.Context, i int, cur *subCurs break // the walk's StopBeforeClusterMs: the stride ends before this cluster } if !whole { - if build && p.harvestWindow(ctx, next, tried) { + if build && p.harvestWindow(ctx, next, max(first, 0), tried) { continue } cur.add(local...) diff --git a/mp4/hlsplan_subharvest_internal_test.go b/mp4/hlsplan_subharvest_internal_test.go index 33ad8f7..378a882 100644 --- a/mp4/hlsplan_subharvest_internal_test.go +++ b/mp4/hlsplan_subharvest_internal_test.go @@ -75,6 +75,11 @@ func TestSubtitleHarvestKeepsTheWalkStrides(t *testing.T) { if err != nil { t.Fatal(err) } + for n := 0; n < 100; n++ { // the video's first 200 s, read before: the subtitles are served from its walks + if _, err := harvested.Segment(ctx, n); err != nil { + t.Fatal(err) + } + } for _, res := range []string{"sub1_00019.vtt", "sub1_00097.vtt"} { want, _, werr := walked.Resource(ctx, res) got, _, gerr := harvested.Resource(ctx, res) @@ -154,10 +159,78 @@ func TestSubtitleHarvestBuildsNotTheLastWindow(t *testing.T) { t.Fatal(err) } last := plan.segCount - 1 - if plan.harvestWindow(ctx, plan.offsets[last], map[int]bool{last - 1: true}) { + if plan.harvestWindow(ctx, plan.offsets[last], 0, map[int]bool{last - 1: true}) { t.Error("the last window was built for a subtitle") } if n := plan.Stats().TableBuilds; n != 0 { t.Errorf("%d tables built", n) } } + +// A subtitle request builds no window before its own: the margin behind a seek and the probe of the track's head are +// windows the video does not play, walked once as before rather than built whole, overlap and all (a film's last +// minutes over a network mount: 218 MB asked of the source, 289 MB with the margin's windows built). +func TestSubtitleHarvestBuildsNoWindowBehindTheRequest(t *testing.T) { + ctx := context.Background() + plan, err := PlanHLS(ctx, buildSeekFixture(t), Options{SegmentMs: 2000, SourceAccess: SourceLocal}) + if err != nil { + t.Fatal(err) + } + n := plan.NumSegments() - 10 + if _, _, err := plan.Resource(ctx, fmt.Sprintf("sub1_%05d.vtt", n+1)); err != nil { + t.Fatal(err) + } + plan.tabMu.Lock() + defer plan.tabMu.Unlock() + for k := range plan.tables { + if k < n { + t.Errorf("window %d built for a subtitle of window %d", k, n) + } + } +} + +// A damaged region costs the harvest the cluster it lies in, not the walk's whole record: the subtitles are the +// walk's, and a second subtitle takes the clusters past the region from the first one's walk (a damaged episode: +// three subtitles after a seek walked the same 138 MB once each). +func TestSubtitleHarvestPastADamagedRegion(t *testing.T) { + ctx := context.Background() + clean := buildSeekFixture(t) + offs := clusterOffsets(t, clean) + mid := offs[len(offs)/2] + bad := zeroedSource(t, clean, mid+4<<10, mid+12<<10) + fs := &mkv.FS{Open: func(p string) (mkv.ReadSeekCloser, error) { return os.Open(p) }} // no window built for a subtitle + read := func(tracks int, harvest bool) (int64, map[string][]byte) { + plan, err := PlanHLS(ctx, bad, Options{SegmentMs: 2000, FS: fs}) + if err != nil { + t.Fatal(err) + } + plan.harvest.off = !harvest + out := map[string][]byte{} + n := plan.NumSegments() + for k := n/2 - 40; k < n/2+40; k++ { // a seek before the region, then through it + for s := 1; s <= tracks; s++ { + res := fmt.Sprintf("sub%d_%05d.vtt", s, k+1) + b, _, err := plan.Resource(ctx, res) + if err != nil { + t.Fatal(err) + } + out[res] = b + } + } + if plan.Stats().DamageSkips == 0 { + t.Fatal("no damage met: the fixture misses the case") + } + return plan.Stats().WalkReadBytes, out + } + _, want := read(2, false) + one, _ := read(1, true) + two, got := read(2, true) + for res, b := range want { + if !bytes.Equal(got[res], b) { + t.Fatalf("%s differs when harvested:\n%s\n--- walked:\n%s", res, got[res], b) + } + } + if two*10 > one*13 { + t.Errorf("two subtitles walked %d bytes, one %d: the second walked again past the region", two, one) + } +} diff --git a/mp4/hlsplan_subharvest_test.go b/mp4/hlsplan_subharvest_test.go index 5de8c74..959ac31 100644 --- a/mp4/hlsplan_subharvest_test.go +++ b/mp4/hlsplan_subharvest_test.go @@ -70,7 +70,7 @@ func TestPlanHLSSubtitleHarvestServesTheSameWebVTT(t *testing.T) { t.Fatalf("%s differs when harvested:\n%s\n--- walked:\n%s", res, got, want) } } - if st := harvested.Stats(); st.SubtitleHarvestedClusters == 0 { + if st := harvested.Stats(); st.SubtitleHarvestedClusters == 0 && orderName == "playback order" { // asked behind what was read, a subtitle walks t.Errorf("no cluster harvested: %+v", st) } if st := walked.Stats(); st.SubtitleHarvestedClusters != 0 || st.SubtitleWalks == 0 { diff --git a/mp4/hlsplan_subtitle.go b/mp4/hlsplan_subtitle.go index ec8eb1f..aa87641 100644 --- a/mp4/hlsplan_subtitle.go +++ b/mp4/hlsplan_subtitle.go @@ -265,7 +265,29 @@ func (p *HLSPlan) extendCursorLocked(ctx context.Context, i int, cur *subCursor, defer p.countWalk(&br)() p.tolerateDamage(br) br.SetTrackDefaultDurations(p.trackDurs) - br.KeepTracks(track.track.ID) + // The walk reads every subtitle track's blocks along with this one's, for the others' cursors (see subHarvest): + // three subtitles asked behind the video walk the clusters once, not once each. + // The media blocks come by their headers alone: they show where each cluster ends, which a cluster holds whole. + subOf := p.harvestTracks() + kept := []uint64{track.track.ID} + for id := range subOf { + if id != track.track.ID { + kept = append(kept, id) + } + } + if subOf != nil { + media := make([]uint64, 0, len(p.tracks)) + for _, pt := range p.tracks { + media = append(media, pt.ft.outTrack.mkv.ID) + } + kept = append(kept, media...) + br.SetHeaderOnly(true) + br.SetHeaderOnlyTracks(media...) + } + br.KeepTracks(kept...) + rec := p.newHarvestRec(subOf, past) + defer rec.commit() + skips := len(br.SkippedRanges()) var local []subtitle.Cue from := past for { @@ -289,9 +311,14 @@ func (p *HLSPlan) extendCursorLocked(ctx context.Context, i int, cur *subCursor, from = cur.next break } + if k := len(br.SkippedRanges()); k > skips { + skips = k + rec.skip() // a damaged region passed over: the cluster it lies in is left to the walks + } // Clean end (incl. a truncated/over-declared tail); all cues to this // point are collected, so finish cleanly. if p.walkEnd(err) { + rec.end() cur.add(local...) cur.done = true return nil @@ -299,6 +326,11 @@ func (p *HLSPlan) extendCursorLocked(ctx context.Context, i int, cur *subCursor, if err != nil { return st.keep(errf("read block: %w", err)) } + if si, ok := subOf[b.TrackNumber]; ok { + rec.observe(br.Pos(), br.ClusterCount(), &b, si) + } else { + rec.observe(br.Pos(), br.ClusterCount(), &b, -1) + } if b.TrackNumber != track.track.ID { continue } diff --git a/mp4/hlsplan_walk.go b/mp4/hlsplan_walk.go index 2bb8729..0dd3ed7 100644 --- a/mp4/hlsplan_walk.go +++ b/mp4/hlsplan_walk.go @@ -205,9 +205,7 @@ func (p *HLSPlan) walkWindow(ctx context.Context, n int, segStart, segEnd int64, } } skips, inPlace = k, none - if rec != nil { - rec.broken = true // a damaged region passed over: this walk harvests nothing - } + rec.skip() // a damaged region passed over: the cluster it lies in is left to the walks } if p.walkEnd(err) { // clean end, incl. a truncated/over-declared tail rec.end() From 9f2e44ee9b8046be5720ad0b0e63dc23108798b9 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Thu, 19 Nov 2026 15:27:37 +0100 Subject: [PATCH 11/11] perf(hls): a local source's subtitle builds the windows behind its request again, a network one does not --- mp4/hlsplan_subharvest.go | 15 +++++++++++---- mp4/hlsplan_subharvest_internal_test.go | 8 ++++---- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/mp4/hlsplan_subharvest.go b/mp4/hlsplan_subharvest.go index c3976db..cd36c99 100644 --- a/mp4/hlsplan_subharvest.go +++ b/mp4/hlsplan_subharvest.go @@ -304,10 +304,17 @@ func (p *HLSPlan) harvestWindow(ctx context.Context, off int64, first int, tried // what precedes it committed, and the walk serves from there. Caller holds subMu[i]. func (p *HLSPlan) extendCursorHarvested(ctx context.Context, i int, cur *subCursor, target, uptoMs int64) (served bool, err error) { st := &p.subScan[i] - build := p.prebuildsTables(ctx) && uptoMs > 0 - // Only the request's own window and those after it, which the video plays: the margin behind a seek and the probe - // of the track's head are walked as before, a window built whole reading its overlap with the next as well. - first := sort.Search(len(p.bounds), func(k int) bool { return p.bounds[k] >= uptoMs }) - 1 + // A network source builds only the request's own window and those after it, which the video plays: the margin + // behind a seek and the probe of the track's head are walked as before, a window built whole there reading its + // overlap and keeping segments nobody asks for (a film's last minutes: 218 MB asked of the source, 289 MB with + // them built). A local one builds them too: the window is a structure, and a viewer coming back to the start + // plays the very windows the probe built (a seek mid-film then back to the start: 208 % read walking them, 280 %). + behind := !p.networkSrc(ctx) + build := p.prebuildsTables(ctx) && (uptoMs > 0 || behind) + first := 0 + if !behind { + first = sort.Search(len(p.bounds), func(k int) bool { return p.bounds[k] >= uptoMs }) - 1 + } tried := map[int]bool{} var took int64 defer func() { diff --git a/mp4/hlsplan_subharvest_internal_test.go b/mp4/hlsplan_subharvest_internal_test.go index 378a882..ce735a0 100644 --- a/mp4/hlsplan_subharvest_internal_test.go +++ b/mp4/hlsplan_subharvest_internal_test.go @@ -167,12 +167,12 @@ func TestSubtitleHarvestBuildsNotTheLastWindow(t *testing.T) { } } -// A subtitle request builds no window before its own: the margin behind a seek and the probe of the track's head are -// windows the video does not play, walked once as before rather than built whole, overlap and all (a film's last -// minutes over a network mount: 218 MB asked of the source, 289 MB with the margin's windows built). +// On a network source, a subtitle request builds no window before its own: the margin behind a seek and the probe of +// the track's head are windows the video does not play, walked once as before rather than built whole, overlap and +// kept segments and all (a film's last minutes: 218 MB asked of the source, 289 MB with the margin's windows built). func TestSubtitleHarvestBuildsNoWindowBehindTheRequest(t *testing.T) { ctx := context.Background() - plan, err := PlanHLS(ctx, buildSeekFixture(t), Options{SegmentMs: 2000, SourceAccess: SourceLocal}) + plan, err := PlanHLS(ctx, buildSeekFixture(t), Options{SegmentMs: 2000, SourceAccess: SourceNetwork}) if err != nil { t.Fatal(err) }