Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,39 @@ 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 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
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
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).
- `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
35 windows, the last served as one 2.2 GB segment; 309 now).

## [0.69.0] - 2026-11-17

### Added
Expand Down
18 changes: 18 additions & 0 deletions docs/library.md
Original file line number Diff line number Diff line change
Expand Up @@ -787,6 +787,24 @@ 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. 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
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,
sizes and sync flags, so it costs nothing extra. A Matroska plan instead
Expand Down
29 changes: 20 additions & 9 deletions mkv/ops/audiodelay.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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 {
Expand All @@ -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
Expand Down
97 changes: 97 additions & 0 deletions mkv/ops/audiodelay_reads_test.go
Original file line number Diff line number Diff line change
@@ -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))
}
}
36 changes: 36 additions & 0 deletions mkv/ops/readgrowing.go
Original file line number Diff line number Diff line change
@@ -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
}
44 changes: 44 additions & 0 deletions mkv/ops/readgrowing_test.go
Original file line number Diff line number Diff line change
@@ -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))
}
}
16 changes: 7 additions & 9 deletions mkv/ops/reindex.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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)
}
Expand Down
7 changes: 2 additions & 5 deletions mkv/ops/retime.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
35 changes: 35 additions & 0 deletions mkv/reader/block_alloc_test.go
Original file line number Diff line number Diff line change
@@ -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))
}
})
}
}
Loading
Loading