From 10a58f7caf2c473ee8af7da09b948f8b25a1186b Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Tue, 17 Nov 2026 16:56:43 +0100 Subject: [PATCH 1/7] feat(ops): ForEachSubtitleBitmap gives a PGS, VobSub or DVB track as cues and ForEachSubtitleBlock the blocks of any subtitle track, walked or served from an index, every subtitle read on one path --- matroska/matroska.go | 40 ++++ mkv/ops/pgs_composite_test.go | 4 +- mkv/ops/pgs_fuzz_test.go | 39 ++- mkv/ops/subbitmap.go | 231 ++++++++++++++++++ mkv/ops/subbitmap_test.go | 433 ++++++++++++++++++++++++++++++++++ mkv/ops/subblocks.go | 231 ++++++++++++++++++ mkv/ops/subindex.go | 119 +--------- mkv/ops/subpgs.go | 298 +---------------------- mkv/ops/subtitle.go | 110 ++++----- 9 files changed, 1039 insertions(+), 466 deletions(-) create mode 100644 mkv/ops/subbitmap.go create mode 100644 mkv/ops/subbitmap_test.go create mode 100644 mkv/ops/subblocks.go diff --git a/matroska/matroska.go b/matroska/matroska.go index 8963d71a..f6a674b2 100644 --- a/matroska/matroska.go +++ b/matroska/matroska.go @@ -1165,6 +1165,46 @@ func ForEachSubtitlePGSFrom(ctx context.Context, srcPath string, trackID uint64, return ops.ForEachSubtitlePGSFrom(ctx, srcPath, trackID, ix, fn, opts...) } +// BitmapCue is one decoded bitmap subtitle of any codec: the type PGSCue names. See ops.BitmapCue. +type BitmapCue = ops.BitmapCue + +// ForEachSubtitleBitmap calls fn with each cue of a bitmap subtitle track - PGS, VobSub or DVB, decoded by its +// codec - walking the source once, one cue's picture alive at a time. See ops.ForEachSubtitleBitmap. +func ForEachSubtitleBitmap(ctx context.Context, srcPath string, trackID uint64, fn func(BitmapCue) error, opts ...Options) error { + if err := oneopt.Check(opts); err != nil { + return err + } + return ops.ForEachSubtitleBitmap(ctx, srcPath, trackID, fn, opts...) +} + +// ForEachSubtitleBitmapFrom is ForEachSubtitleBitmap served from a prebuilt index. See ops.ForEachSubtitleBitmapFrom. +func ForEachSubtitleBitmapFrom(ctx context.Context, srcPath string, trackID uint64, ix *SubtitleIndex, fn func(BitmapCue) error, opts ...Options) error { + if err := oneopt.Check(opts); err != nil { + return err + } + return ops.ForEachSubtitleBitmapFrom(ctx, srcPath, trackID, ix, fn, opts...) +} + +// SubtitleBlock is one block of a subtitle track, its payload as the codec reads it. See ops.SubtitleBlock. +type SubtitleBlock = ops.SubtitleBlock + +// ForEachSubtitleBlock calls fn with each block of a subtitle track, whatever its codec, walking the source once. +// See ops.ForEachSubtitleBlock. +func ForEachSubtitleBlock(ctx context.Context, srcPath string, trackID uint64, fn func(SubtitleBlock) error, opts ...Options) error { + if err := oneopt.Check(opts); err != nil { + return err + } + return ops.ForEachSubtitleBlock(ctx, srcPath, trackID, fn, opts...) +} + +// ForEachSubtitleBlockFrom is ForEachSubtitleBlock served from a prebuilt index. See ops.ForEachSubtitleBlockFrom. +func ForEachSubtitleBlockFrom(ctx context.Context, srcPath string, trackID uint64, ix *SubtitleIndex, fn func(SubtitleBlock) error, opts ...Options) error { + if err := oneopt.Check(opts); err != nil { + return err + } + return ops.ForEachSubtitleBlockFrom(ctx, srcPath, trackID, ix, fn, opts...) +} + // SubtitleFileToWebVTT converts an external subtitle sidecar (.srt/.ass/.ssa/.vtt) // to WebVTT, written to w. See subtitle.FileToWebVTT. func SubtitleFileToWebVTT(srcPath string, w io.Writer) error { diff --git a/mkv/ops/pgs_composite_test.go b/mkv/ops/pgs_composite_test.go index 9b504fe4..11e223b2 100644 --- a/mkv/ops/pgs_composite_test.go +++ b/mkv/ops/pgs_composite_test.go @@ -12,11 +12,11 @@ import ( func TestPGSCompositeIsBounded(t *testing.T) { dot := image.NewNRGBA(image.Rect(0, 0, 1, 1)) ds := &subtitle.PGSDisplaySet{ScreenW: 1920, ScreenH: 1080, Objects: []subtitle.PGSObject{{X: 0, Y: 0, Image: dot}, {X: 4097, Y: 0, Image: dot}}} - if _, err := flattenPGSDisplaySet(ds, 0); err == nil { + if _, err := flattenDisplaySet(ds, 0, "PGS"); err == nil { t.Error("objects 4098 pixels apart were composited onto one picture") } ds.Objects[1].X = 1900 - if cue, err := flattenPGSDisplaySet(ds, 0); err != nil || cue.Image.Bounds().Dx() != 1901 { + if cue, err := flattenDisplaySet(ds, 0, "PGS"); err != nil || cue.Image.Bounds().Dx() != 1901 { t.Errorf("two lines on a 1080p plane: %v", err) } } diff --git a/mkv/ops/pgs_fuzz_test.go b/mkv/ops/pgs_fuzz_test.go index 9cff26dc..4a15454a 100644 --- a/mkv/ops/pgs_fuzz_test.go +++ b/mkv/ops/pgs_fuzz_test.go @@ -15,7 +15,10 @@ func FuzzPGSAssembler(f *testing.F) { f.Fuzz(func(t *testing.T, first, second []byte, durMs int64) { costguard.Fuzz(t, len(first)+len(second), func() { var cues []PGSCue - a := newPGSAssembler(func(c PGSCue) error { cues = append(cues, c); return nil }, &mkv.Track{Codec: "S_HDMV/PGS"}) + a, err := newBitmapAssembler(func(c PGSCue) error { cues = append(cues, c); return nil }, &mkv.Track{Codec: "pgs"}) + if err != nil { + t.Fatal(err) + } if a.block(1000, durMs%5000, first) != nil || a.block(2000, 0, second) != nil { return } @@ -27,3 +30,37 @@ func FuzzPGSAssembler(f *testing.F) { }) }) } + +// FuzzBitmapAssembler: two VobSub or DVB blocks of any bytes, with a region lost between them or not, decode and +// flatten to cues or an error, never a panic, and every cue ends after it starts. +func FuzzBitmapAssembler(f *testing.F) { + f.Add(false, []byte{0x00, 0x08, 0x00, 0x04, 0x00, 0x00, 0x00, 0x04}, []byte{0x00, 0x0a}, int64(0), false) + f.Add(true, []byte{0x0f, 0x10, 0x00, 0x01, 0x00, 0x02, 0x0f, 0x20, 0x0f, 0x80, 0x00, 0x01, 0x00, 0x00}, []byte{0x0f, 0x80, 0x00, 0x01, 0x00, 0x00}, int64(40), true) + f.Fuzz(func(t *testing.T, dvb bool, first, second []byte, durMs int64, lost bool) { + costguard.Fuzz(t, len(first)+len(second), func() { + track := &mkv.Track{Codec: "vobsub", CodecPrivate: []byte("size: 720x576\npalette: 000000, ff0000, 00ff00, 0000ff, ffffff, 101010, 202020, 303030, 404040, 505050, 606060, 707070, 808080, 909090, a0a0a0, b0b0b0\n")} + if dvb { + track = &mkv.Track{Codec: "dvbsub"} + } + var cues []BitmapCue + a, err := newBitmapAssembler(func(c BitmapCue) error { cues = append(cues, c); return nil }, track) + if err != nil { + t.Fatal(err) + } + if a.block(1000, durMs%5000, first) != nil { + return + } + if lost && a.lost(1500) != nil { + return + } + if a.block(2000, 0, second) != nil || a.finish() != nil { + return + } + for _, c := range cues { + if c.EndMs <= c.StartMs { + t.Fatalf("cue %d..%d ms ends before it starts", c.StartMs, c.EndMs) + } + } + }) + }) +} diff --git a/mkv/ops/subbitmap.go b/mkv/ops/subbitmap.go new file mode 100644 index 00000000..e21c5f6c --- /dev/null +++ b/mkv/ops/subbitmap.go @@ -0,0 +1,231 @@ +package ops + +// subbitmap.go - bitmap subtitle tracks as timed pictures, whatever the codec: PGS (Blu-ray), VobSub (DVD) and DVB +// (broadcast) each decode to display sets (mkv/subtitle), and the rules that turn display sets into cues are the +// same for the three. The blocks come from the read of subblocks.go, walked or served from a SubtitleIndex. + +import ( + "context" + "fmt" + "image" + "image/draw" + + "github.com/gravity-zero/mkvgo/internal/oneopt" + "github.com/gravity-zero/mkvgo/mkv" + "github.com/gravity-zero/mkvgo/mkv/subtitle" +) + +// BitmapCue is one bitmap subtitle of any codec: the type PGSCue names. +type BitmapCue = PGSCue + +// ForEachSubtitleBitmap walks srcPath once and calls fn with each cue of the bitmap subtitle track trackID, in +// presentation order: a PGS, VobSub or DVB track, decoded by its codec. Only one cue's picture is alive at a time, +// so a whole track is written out in bounded memory. An error from fn stops the walk and is returned as is. +// +// A cue starts where its display set takes effect and ends, in this order: where the stream says (a VobSub stop +// command), at the duration the muxer wrote for its block, or where the next display set begins - no later than a +// DVB page's time-out, and 3 s after its start for a last cue nothing closes. A display set of several pictures is +// one cue, composited on the smallest rectangle that holds them. +func ForEachSubtitleBitmap(ctx context.Context, srcPath string, trackID uint64, fn func(BitmapCue) error, opts ...mkv.Options) error { + if err := oneopt.Check(opts); err != nil { + return err + } + return walkSubtitleBlocks(ctx, srcPath, trackID, bitmapCues(fn, nil), opts) +} + +// ForEachSubtitleBitmapFrom is ForEachSubtitleBitmap served from a prebuilt index, under the checks of +// ForEachSubtitleBlockFrom. The index is read from its first entry: the state of a bitmap codec spans blocks, and a +// cue decoded from the middle of a track could draw on pictures that were never read. +func ForEachSubtitleBitmapFrom(ctx context.Context, srcPath string, trackID uint64, ix *SubtitleIndex, fn func(BitmapCue) error, opts ...mkv.Options) error { + if err := oneopt.Check(opts); err != nil { + return err + } + return indexedSubtitleBlocks(ctx, srcPath, trackID, ix, bitmapCues(fn, nil), opts) +} + +// bitmapDecoder is what the three codecs' decoders share. +type bitmapDecoder interface { + Decode(block []byte) ([]subtitle.BitmapDisplaySet, error) + Reset() +} + +// newBitmapDecoder picks the decoder of a subtitle track's codec, and the name its errors go by. +func newBitmapDecoder(t *mkv.Track) (bitmapDecoder, string, error) { + switch t.Codec { + case "pgs": + return subtitle.NewPGSDecoder(), "PGS", nil + case "vobsub": + d, err := subtitle.NewVobSubDecoder(t.CodecPrivate) + return d, "VobSub", err + case "dvbsub": + return subtitle.NewDVBSubDecoder(t.CodecPrivate), "DVB subtitle", nil + } + if isTextSubtitle(t.Codec) { + return nil, "", fmt.Errorf("subtitle track %d codec %q is text, not bitmaps - extract it as WebVTT instead", t.ID, t.Codec) + } + return nil, "", fmt.Errorf("subtitle track %d codec %q is not a bitmap subtitle this reads (PGS, VobSub, DVB)", t.ID, t.Codec) +} + +// bitmapCues is the sink that decodes a bitmap track's blocks into cues; check, when set, refuses the track first. +func bitmapCues(fn func(BitmapCue) error, check func(*mkv.Track) error) subtitleSink { + var asm *bitmapAssembler + return subtitleSink{ + accept: func(_ *mkv.Container, t *mkv.Track) error { + if check != nil { + if err := check(t); err != nil { + return err + } + } + a, err := newBitmapAssembler(fn, t) + asm = a + return err + }, + block: func(blk mkv.Block) error { return asm.block(blk.Timecode, blk.Duration, blk.Data) }, + lost: func(fromMs int64) error { return asm.lost(fromMs) }, + end: func() error { return asm.finish() }, + } +} + +// bitmapAssembler turns the stream of decoded display sets into timed cues. A cue's end is often not in its own +// block: it is the time of the next display set, which is normally an empty one meaning "clear the screen". So a +// cue is held open until the block that ends it arrives, and emitted then - one cue of latency, never the whole +// track. +type bitmapAssembler struct { + dec bitmapDecoder + name string + emit func(BitmapCue) error + track *mkv.Track + open *BitmapCue + latest int64 // when the open cue ends at the latest: its page's time-out, 0 for none + unitMs int64 // the time of the block that started the unit being decoded +} + +func newBitmapAssembler(fn func(BitmapCue) error, t *mkv.Track) (*bitmapAssembler, error) { + dec, name, err := newBitmapDecoder(t) + if err != nil { + return nil, err + } + return &bitmapAssembler{dec: dec, name: name, emit: fn, track: t}, nil +} + +func (a *bitmapAssembler) block(timeMs, durMs int64, data []byte) error { + data, err := decompressSubtitleBlock(a.track, data) + if err != nil { + return fmt.Errorf("subtitle block at %d ms: %w", timeMs, err) + } + // A unit spread over several blocks (VobSub) is dated by the first of them. + if c, ok := a.dec.(interface{ Continues([]byte) bool }); !ok || !c.Continues(data) { + a.unitMs = timeMs + } + sets, err := a.dec.Decode(data) + if err != nil { + return fmt.Errorf("subtitle block at %d ms: %w", timeMs, err) + } + for i := range sets { + ds := &sets[i] + start := a.unitMs + ds.Delay.Milliseconds() + // Whatever is on screen ends where this display set begins, whether the new one clears the screen or + // replaces it. + if err := a.closeAt(start); err != nil { + return err + } + if ds.Clear() { + continue + } + cue, err := flattenDisplaySet(ds, start, a.name) + if err != nil { + return fmt.Errorf("subtitle block at %d ms: %w", timeMs, err) + } + // The stream's own end, then the muxer's, are known now: emit and hold nothing. + switch { + case ds.Duration > 0: + cue.EndMs = start + ds.Duration.Milliseconds() + case durMs > 0: + cue.EndMs = timeMs + durMs + } + if cue.EndMs > cue.StartMs { + if err := a.emit(cue); err != nil { + return err + } + continue + } + a.open, a.latest = &cue, 0 + if ds.Timeout > 0 { + a.latest = start + ds.Timeout.Milliseconds() + } + } + return nil +} + +// closeAt ends the open cue at t, or at its time-out when that comes first. A t that does not move the clock +// forward (two display sets inside one block) would make a zero-length cue, so the default duration is used +// instead - the same fallback the text path applies. +func (a *bitmapAssembler) closeAt(t int64) error { + if a.open == nil { + return nil + } + cue := *a.open + a.open = nil + cue.EndMs = t + if a.latest > 0 && cue.EndMs > a.latest { + cue.EndMs = a.latest + } + if cue.EndMs <= cue.StartMs { + cue.EndMs = cue.StartMs + defaultSubDurationMs + } + return a.emit(cue) +} + +// lost ends the cue on screen where a region the read just passed over begins, and forgets the state it cut. +func (a *bitmapAssembler) lost(fromMs int64) error { + a.dec.Reset() + return a.closeAt(fromMs) +} + +// finish flushes a cue the track never closed - a last subtitle with no trailing "clear" display set, which is +// common enough not to be an error. +func (a *bitmapAssembler) finish() error { + if a.open == nil { + return nil + } + cue := *a.open + a.open = nil + cue.EndMs = cue.StartMs + defaultSubDurationMs + if a.latest > 0 && a.latest < cue.EndMs { + cue.EndMs = a.latest + } + return a.emit(cue) +} + +// flattenDisplaySet reduces a display set to the one picture a cue holds. Most sets carry a single object and are +// handed over untouched; a set with several (a disc that puts a top and a bottom line in two windows, a broadcast +// with one region a line) is composited onto the smallest rectangle covering them, so X, Y stays a real screen +// position rather than becoming meaningless. +func flattenDisplaySet(ds *subtitle.BitmapDisplaySet, startMs int64, name string) (BitmapCue, error) { + cue := BitmapCue{StartMs: startMs, ScreenW: ds.ScreenW, ScreenH: ds.ScreenH} + if len(ds.Objects) == 1 { + o := ds.Objects[0] + cue.X, cue.Y, cue.Forced, cue.Image = o.X, o.Y, o.Forced, o.Image + return cue, nil + } + var union image.Rectangle + for _, o := range ds.Objects { + r := o.Image.Bounds().Add(image.Pt(o.X, o.Y)) + union = union.Union(r) + cue.Forced = cue.Forced || o.Forced + } + if union.Dx() > bitmapMaxPlane || union.Dy() > bitmapMaxPlane { + return cue, fmt.Errorf("%s: a display set spreads its objects over %dx%d pixels, past the %d a subtitle plane holds: the track is damaged or forged", name, union.Dx(), union.Dy(), bitmapMaxPlane) + } + out := image.NewNRGBA(image.Rect(0, 0, union.Dx(), union.Dy())) + for _, o := range ds.Objects { + at := image.Pt(o.X-union.Min.X, o.Y-union.Min.Y) + draw.Draw(out, image.Rectangle{Min: at, Max: at.Add(o.Image.Bounds().Size())}, o.Image, image.Point{}, draw.Over) + } + cue.X, cue.Y, cue.Image = union.Min.X, union.Min.Y, out + return cue, nil +} + +// bitmapMaxPlane bounds the picture several objects are composited onto, as the formats bound each object: placed +// far apart by a forged composition, two dots would otherwise ask for a picture of gigabytes. +const bitmapMaxPlane = 4096 diff --git a/mkv/ops/subbitmap_test.go b/mkv/ops/subbitmap_test.go new file mode 100644 index 00000000..b9d4dbef --- /dev/null +++ b/mkv/ops/subbitmap_test.go @@ -0,0 +1,433 @@ +package ops + +import ( + "bytes" + "context" + "errors" + "image" + "strings" + "testing" + "time" + + "github.com/gravity-zero/mkvgo/mkv" + "github.com/gravity-zero/mkvgo/mkv/subtitle" +) + +// Real tracks: a DVD's VobSub and a broadcast's DVB subtitles, the samples of mkv/subtitle. +const ( + vobsubSampleMKV = "../../internal/testdata/vobsub.mkv" + dvbsubSampleMKV = "../../internal/testdata/dvbsub.mkv" +) + +type readBlock struct { + timeMs, durMs int64 + data []byte + lost bool +} + +func collectBlocks(t *testing.T, read func(fn func(SubtitleBlock) error) error) []readBlock { + t.Helper() + var out []readBlock + if err := read(func(b SubtitleBlock) error { + out = append(out, readBlock{b.TimeMs, b.DurationMs, append([]byte(nil), b.Data...), b.Lost}) + return nil + }); err != nil { + t.Fatal(err) + } + return out +} + +func sameBlocks(t *testing.T, got, want []readBlock, what string) { + t.Helper() + if len(got) != len(want) { + t.Fatalf("%s: %d blocks, want %d", what, len(got), len(want)) + } + for i := range want { + g, w := got[i], want[i] + if g.timeMs != w.timeMs || g.durMs != w.durMs || g.lost != w.lost || !bytes.Equal(g.data, w.data) { + t.Fatalf("%s: block %d = %d ms, %d ms long, %d bytes, lost=%v; want %d ms, %d ms, %d bytes, lost=%v", + what, i, g.timeMs, g.durMs, len(g.data), g.lost, w.timeMs, w.durMs, len(w.data), w.lost) + } + } +} + +// The blocks of a track come out the same walked and served from an index, whatever the codec. +func TestForEachSubtitleBlock_WalkAndIndexAgree(t *testing.T) { + ctx := context.Background() + for _, tc := range []struct { + path string + blocks int + firstMs int64 + firstLen int + lastMs int64 + }{ + {vobsubSampleMKV, 46, 132499, 2238, 359834}, + {dvbsubSampleMKV, 46, 0, 14, 31880}, + } { + walked := collectBlocks(t, func(fn func(SubtitleBlock) error) error { + return ForEachSubtitleBlock(ctx, tc.path, 1, fn) + }) + if len(walked) != tc.blocks || walked[0].timeMs != tc.firstMs || len(walked[0].data) != tc.firstLen || walked[len(walked)-1].timeMs != tc.lastMs { + t.Fatalf("%s: %d blocks, the first at %d ms of %d bytes, the last at %d ms; want %d, %d ms, %d bytes, %d ms", + tc.path, len(walked), walked[0].timeMs, len(walked[0].data), walked[len(walked)-1].timeMs, tc.blocks, tc.firstMs, tc.firstLen, tc.lastMs) + } + ix, err := BuildSubtitleIndex(ctx, tc.path, nil) + if err != nil { + t.Fatal(err) + } + indexed := collectBlocks(t, func(fn func(SubtitleBlock) error) error { + return ForEachSubtitleBlockFrom(ctx, tc.path, 1, ix, fn) + }) + sameBlocks(t, indexed, walked, tc.path+" from its index") + } +} + +// A track stored compressed is handed decoded, with the duration its blocks carry. +func TestForEachSubtitleBlock_DecodesACompressedTrack(t *testing.T) { + ctx := context.Background() + tr := mkv.Track{ID: 1, Type: mkv.SubtitleTrack, Codec: "pgs", Language: "fre", Compression: mkv.CompressionZlib} + show, clear := pgsShow(10, 100, 900, true), pgsClear() + path := buildCompressedSubMKV(t, t.TempDir(), "zlib.mkv", tr, [][]byte{show, clear}) + want := []readBlock{{0, 900, show, false}, {1000, 900, clear, false}} + sameBlocks(t, collectBlocks(t, func(fn func(SubtitleBlock) error) error { + return ForEachSubtitleBlock(ctx, path, 1, fn) + }), want, "walk") + ix, err := BuildSubtitleIndex(ctx, path, nil) + if err != nil { + t.Fatal(err) + } + sameBlocks(t, collectBlocks(t, func(fn func(SubtitleBlock) error) error { + return ForEachSubtitleBlockFrom(ctx, path, 1, ix, fn) + }), want, "index") +} + +func TestForEachSubtitleBlock_Refusals(t *testing.T) { + ctx := context.Background() + path := buildPGSFixture(t, t.TempDir()) + none := func(SubtitleBlock) error { return nil } + all, err := BuildSubtitleIndex(ctx, path, nil) + if err != nil { + t.Fatal(err) + } + text, err := BuildSubtitleIndex(ctx, path, []uint64{3}) + if err != nil { + t.Fatal(err) + } + stale, err := BuildSubtitleIndex(ctx, path, nil) + if err != nil { + t.Fatal(err) + } + stale.fileSize++ + for name, tc := range map[string]struct { + err error + is error + want string + }{ + "walk: a video track": {ForEachSubtitleBlock(ctx, path, 1, none), nil, "subtitle track 1 not found"}, + "walk: no such track": {ForEachSubtitleBlock(ctx, path, 9, none), nil, "subtitle track 9 not found"}, + "index: a video track": {ForEachSubtitleBlockFrom(ctx, path, 1, all, none), nil, "subtitle track 1 not found"}, + "index: nil": {ForEachSubtitleBlockFrom(ctx, path, 2, nil, none), nil, "nil subtitle index"}, + "index: another file": {ForEachSubtitleBlockFrom(ctx, path, 2, stale, none), ErrIndexStale, "built for"}, + "index: track not covered": {ForEachSubtitleBlockFrom(ctx, path, 2, text, none), ErrTrackNotIndexed, "track 2"}, + } { + if tc.err == nil || !strings.Contains(tc.err.Error(), tc.want) || (tc.is != nil && !errors.Is(tc.err, tc.is)) { + t.Errorf("%s: err = %v, want one naming %q", name, tc.err, tc.want) + } + } + stop := errors.New("stop") + calls := 0 + halt := func(SubtitleBlock) error { calls++; return stop } + if err := ForEachSubtitleBlock(ctx, path, 2, halt); err != stop || calls != 1 { + t.Errorf("walk: err = %v after %d calls, want the callback's own after one", err, calls) + } + calls = 0 + if err := ForEachSubtitleBlockFrom(ctx, path, 2, all, halt); err != stop || calls != 1 { + t.Errorf("index: err = %v after %d calls, want the callback's own after one", err, calls) + } +} + +// A damaged region the read passes over comes as one Lost call, between the blocks on either side of it. A walk +// knows the region starts past the 3 s cluster; an index of the clean file seats on the 4 s cluster and finds it +// zeroed, then on the 5 s cluster's block, which lies past the zeroed bytes. +func TestForEachSubtitleBlock_LostRegion(t *testing.T) { + ctx := context.Background() + clean, bad, clusters := damagedSubtitleSource(t) + ix, err := BuildSubtitleIndex(ctx, clean, nil) + if err != nil { + t.Fatal(err) + } + for _, tc := range []struct { + name string + read func(fn func(SubtitleBlock) error, o mkv.Options) error + lostMs, nextMs int64 + }{ + {"walk", func(fn func(SubtitleBlock) error, o mkv.Options) error { + return ForEachSubtitleBlock(ctx, bad, 3, fn, o) + }, 3000, 6200}, + {"index", func(fn func(SubtitleBlock) error, o mkv.Options) error { + return ForEachSubtitleBlockFrom(ctx, bad, 3, ix, fn, o) + }, 4000, 5200}, + } { + var skips []mkv.DamagedRange + var times []int64 + lostAt, lost := -1, 0 + err := tc.read(func(b SubtitleBlock) error { + if !b.Lost { + times = append(times, b.TimeMs) + return nil + } + lost++ + lostAt = len(times) + if b.Data != nil || b.TimeMs != tc.lostMs { + t.Errorf("%s: the Lost call carries %d bytes at %d ms, want none at %d ms", tc.name, len(b.Data), b.TimeMs, tc.lostMs) + } + return nil + }, onSkipInto(&skips)) + if err != nil { + t.Fatalf("%s: %v", tc.name, err) + } + if len(skips) != 1 || skips[0].EndOffset != clusters[6] || skips[0].ApproxStartMs != tc.lostMs { + t.Errorf("%s: OnSkip got %+v, want once a region from %d ms ending at byte %d", tc.name, skips, tc.lostMs, clusters[6]) + } + if lost != 1 || lostAt != 4 || times[3] != 3200 || times[4] != tc.nextMs { + t.Errorf("%s: %d Lost call(s), after %d blocks, blocks at %v; want one after the block at 3200 ms, the next at %d ms", tc.name, lost, lostAt, times, tc.nextMs) + } + } +} + +type cueShape struct { + startMs, endMs int64 + x, y, w, h int +} + +func shapeOf(c BitmapCue) cueShape { + return cueShape{c.StartMs, c.EndMs, c.X, c.Y, c.Image.Bounds().Dx(), c.Image.Bounds().Dy()} +} + +func collectCues(t *testing.T, read func(fn func(BitmapCue) error) error) []BitmapCue { + t.Helper() + var out []BitmapCue + if err := read(func(c BitmapCue) error { out = append(out, c); return nil }); err != nil { + t.Fatal(err) + } + return out +} + +func sameCues(t *testing.T, got, want []BitmapCue, what string) { + t.Helper() + if len(got) != len(want) { + t.Fatalf("%s: %d cues, want %d", what, len(got), len(want)) + } + for i := range want { + g, w := got[i], want[i] + if shapeOf(g) != shapeOf(w) || g.ScreenW != w.ScreenW || g.ScreenH != w.ScreenH || g.Forced != w.Forced || !bytes.Equal(g.Image.Pix, w.Image.Pix) { + t.Fatalf("%s: cue %d = %+v, want %+v, or its pixels differ", what, i, shapeOf(g), shapeOf(w)) + } + } +} + +// A DVD's VobSub track as cues: each dated by the block that starts its unit, ended by its own stop command. +func TestForEachSubtitleBitmap_VobSub(t *testing.T) { + ctx := context.Background() + cues := collectCues(t, func(fn func(BitmapCue) error) error { return ForEachSubtitleBitmap(ctx, vobsubSampleMKV, 1, fn) }) + if len(cues) != 43 { + t.Fatalf("%d cues, want 43", len(cues)) + } + for i, want := range map[int]cueShape{ + 0: {132499, 132499 + 4960, 259, 379, 200, 24}, + 4: {185919, 185919 + 2696, 234, 340, 250, 63}, + 27: {302018, 302018 + 1524, 236, 379, 247, 30}, // a unit over two blocks, the second at 302035 ms + 42: {359834, 359834 + 1262, 232, 379, 254, 24}, + } { + if got := shapeOf(cues[i]); got != want { + t.Errorf("cue %d = %+v, want %+v", i, got, want) + } + } + for i, c := range cues { + if c.ScreenW != 720 || c.ScreenH != 480 || c.Forced || c.EndMs <= c.StartMs { + t.Errorf("cue %d: plane %dx%d, forced=%v, %d..%d ms", i, c.ScreenW, c.ScreenH, c.Forced, c.StartMs, c.EndMs) + } + } + ix, err := BuildSubtitleIndex(ctx, vobsubSampleMKV, nil) + if err != nil { + t.Fatal(err) + } + sameCues(t, collectCues(t, func(fn func(BitmapCue) error) error { + return ForEachSubtitleBitmapFrom(ctx, vobsubSampleMKV, 1, ix, fn) + }), cues, "from the index") +} + +// A broadcast's DVB track as cues: each display set ends where the next begins, two regions are one picture. +func TestForEachSubtitleBitmap_DVB(t *testing.T) { + ctx := context.Background() + cues := collectCues(t, func(fn func(BitmapCue) error) error { return ForEachSubtitleBitmap(ctx, dvbsubSampleMKV, 1, fn) }) + if len(cues) != 36 { + t.Fatalf("%d cues, want 36", len(cues)) + } + for i, want := range map[int]cueShape{ + 0: {15600, 15760, 78, 416, 88, 36}, + 6: {17760, 17980, 78, 380, 406, 72}, // two regions, one above the other + 35: {29360, 31040, 78, 380, 460, 72}, // ended by the empty display set that follows + } { + if got := shapeOf(cues[i]); got != want { + t.Errorf("cue %d = %+v, want %+v", i, got, want) + } + } + for i, c := range cues { + if c.ScreenW != 720 || c.ScreenH != 576 || c.Forced { + t.Errorf("cue %d: plane %dx%d, forced=%v", i, c.ScreenW, c.ScreenH, c.Forced) + } + if i > 0 && c.StartMs != cues[i-1].EndMs { + t.Errorf("cue %d starts at %d ms, the one before ends at %d", i, c.StartMs, cues[i-1].EndMs) + } + } + ix, err := BuildSubtitleIndex(ctx, dvbsubSampleMKV, nil) + if err != nil { + t.Fatal(err) + } + sameCues(t, collectCues(t, func(fn func(BitmapCue) error) error { + return ForEachSubtitleBitmapFrom(ctx, dvbsubSampleMKV, 1, ix, fn) + }), cues, "from the index") +} + +// The codec-neutral read gives a PGS track the cues the PGS read gives it. +func TestForEachSubtitleBitmap_PGS(t *testing.T) { + ctx := context.Background() + path := buildPGSFixture(t, t.TempDir()) + checkPGSCues(t, collectCues(t, func(fn func(BitmapCue) error) error { return ForEachSubtitleBitmap(ctx, path, 2, fn) }), "walk") + ix, err := BuildSubtitleIndex(ctx, path, nil) + if err != nil { + t.Fatal(err) + } + checkPGSCues(t, collectCues(t, func(fn func(BitmapCue) error) error { + return ForEachSubtitleBitmapFrom(ctx, path, 2, ix, fn) + }), "index") +} + +func TestForEachSubtitleBitmap_Refusals(t *testing.T) { + ctx := context.Background() + dir := t.TempDir() + path := buildPGSFixture(t, dir) + other := buildMinimalMKV(t, dir, "other.mkv", []mkv.Track{subtitleTrack(1, "S_KATE"), subtitleTrack(2, "vobsub")}, + []mkv.Block{{TrackNumber: 1, Timecode: 0, Data: []byte("x")}}, 1000) + none := func(BitmapCue) error { return nil } + for name, tc := range map[string]struct { + err error + want string + }{ + "a text track": {ForEachSubtitleBitmap(ctx, path, 3, none), "codec \"srt\" is text, not bitmaps - extract it as WebVTT instead"}, + "a codec without decoder": {ForEachSubtitleBitmap(ctx, other, 1, none), "is not a bitmap subtitle this reads (PGS, VobSub, DVB)"}, + "VobSub without its header": {ForEachSubtitleBitmap(ctx, other, 2, none), "lacks the size: or palette: line"}, + "a video track": {ForEachSubtitleBitmap(ctx, path, 1, none), "subtitle track 1 not found"}, + "the PGS read on VobSub": {ForEachSubtitlePGS(ctx, vobsubSampleMKV, 1, none), "codec \"vobsub\" is not PGS (S_HDMV/PGS)"}, + "index: nil": {ForEachSubtitleBitmapFrom(ctx, path, 2, nil, none), "nil subtitle index"}, + } { + if tc.err == nil || !strings.Contains(tc.err.Error(), tc.want) { + t.Errorf("%s: err = %v, want one naming %q", name, tc.err, tc.want) + } + } +} + +// scriptedDecoder hands the assembler the display sets a test wrote for each block, by the block's first byte. +type scriptedDecoder struct { + sets map[byte][]subtitle.BitmapDisplaySet + continues map[byte]bool + resets int +} + +func (d *scriptedDecoder) Decode(block []byte) ([]subtitle.BitmapDisplaySet, error) { + return d.sets[block[0]], nil +} +func (d *scriptedDecoder) Reset() { d.resets++ } +func (d *scriptedDecoder) Continues(block []byte) bool { return d.continues[block[0]] } + +func shownSet(x int, more subtitle.BitmapDisplaySet) subtitle.BitmapDisplaySet { + more.ScreenW, more.ScreenH = 720, 576 + more.Objects = []subtitle.BitmapObject{{X: x, Y: 10, Image: image.NewNRGBA(image.Rect(0, 0, 2, 2))}} + return more +} + +// The rules that end a cue, on display sets written by hand: the stream's own duration, then the block's, then the +// next display set, no later than the page's time-out. +func TestBitmapAssembler_CueEnds(t *testing.T) { + clear := subtitle.BitmapDisplaySet{ScreenW: 720, ScreenH: 576} + dec := &scriptedDecoder{ + sets: map[byte][]subtitle.BitmapDisplaySet{ + 'a': {shownSet(1, subtitle.BitmapDisplaySet{Delay: 100 * time.Millisecond, Duration: 2 * time.Second})}, + 'b': {shownSet(2, subtitle.BitmapDisplaySet{})}, + 'c': {shownSet(3, subtitle.BitmapDisplaySet{Timeout: 5 * time.Second})}, + 'd': {clear}, + 'e': nil, // the first part of a unit + 'f': {shownSet(4, subtitle.BitmapDisplaySet{})}, + 'g': {shownSet(5, subtitle.BitmapDisplaySet{Timeout: 2 * time.Second})}, + }, + continues: map[byte]bool{'f': true}, + } + var got []cueShape + a := &bitmapAssembler{dec: dec, name: "test", track: &mkv.Track{}, emit: func(c BitmapCue) error { + got = append(got, cueShape{startMs: c.StartMs, endMs: c.EndMs, x: c.X}) + return nil + }} + for _, b := range []struct { + timeMs, durMs int64 + data string + }{ + {1000, 9000, "a"}, // its own duration wins over the block's: 1100..3100 + {4000, 700, "b"}, // the block's duration: 4000..4700 + {5000, 0, "b"}, // open, ended by the next display set: 5000..6000 + {6000, 0, "c"}, // open, the next set comes after its time-out: 6000..11000 + {20000, 0, "d"}, // a clear + {30000, 500, "e"}, // starts a unit + {30040, 0, "f"}, // completes it: dated 30000, ended by the next set at 31000 + {31000, 0, "g"}, // never closed: its time-out, shorter than the default: 31000..33000 + } { + if err := a.block(b.timeMs, b.durMs, []byte(b.data)); err != nil { + t.Fatal(err) + } + } + if err := a.finish(); err != nil { + t.Fatal(err) + } + want := []cueShape{ + {startMs: 1100, endMs: 3100, x: 1}, + {startMs: 4000, endMs: 4700, x: 2}, + {startMs: 5000, endMs: 6000, x: 2}, + {startMs: 6000, endMs: 11000, x: 3}, + {startMs: 30000, endMs: 31000, x: 4}, + {startMs: 31000, endMs: 33000, x: 5}, + } + if len(got) != len(want) { + t.Fatalf("%d cues %+v, want %d", len(got), got, len(want)) + } + for i := range want { + if got[i] != want[i] { + t.Errorf("cue %d = %+v, want %+v", i, got[i], want[i]) + } + } +} + +// A region the read passed over ends the cue on screen where it starts and resets the decoder. +func TestBitmapAssembler_LostRegion(t *testing.T) { + dec := &scriptedDecoder{sets: map[byte][]subtitle.BitmapDisplaySet{'b': {shownSet(2, subtitle.BitmapDisplaySet{})}}} + var got []cueShape + a := &bitmapAssembler{dec: dec, name: "test", track: &mkv.Track{}, emit: func(c BitmapCue) error { + got = append(got, cueShape{startMs: c.StartMs, endMs: c.EndMs}) + return nil + }} + if err := a.block(1000, 0, []byte("b")); err != nil { + t.Fatal(err) + } + if err := a.lost(1800); err != nil { + t.Fatal(err) + } + if err := a.block(9000, 0, []byte("b")); err != nil { + t.Fatal(err) + } + if err := a.finish(); err != nil { + t.Fatal(err) + } + want := []cueShape{{startMs: 1000, endMs: 1800}, {startMs: 9000, endMs: 9000 + defaultSubDurationMs}} + if dec.resets != 1 || len(got) != 2 || got[0] != want[0] || got[1] != want[1] { + t.Errorf("%d reset(s), cues %+v; want one reset and %+v", dec.resets, got, want) + } +} diff --git a/mkv/ops/subblocks.go b/mkv/ops/subblocks.go new file mode 100644 index 00000000..e38774cf --- /dev/null +++ b/mkv/ops/subblocks.go @@ -0,0 +1,231 @@ +package ops + +// subblocks.go - the one read every subtitle extractor is built on: the blocks of one subtitle track, in file +// order, by walking the file or by seeking where a SubtitleIndex says they are. What a consumer makes of a block +// (text, a picture) is its own; where the block is, whether the index still describes the file, and what a damaged +// region costs are decided here, once. + +import ( + "context" + "fmt" + "io" + + "github.com/gravity-zero/mkvgo/internal/oneopt" + "github.com/gravity-zero/mkvgo/mkv" + "github.com/gravity-zero/mkvgo/mkv/reader" +) + +// SubtitleBlock is one block of a subtitle track: its time, the duration the muxer wrote for it (0 for none) and +// its payload as the codec reads it, a track stored compressed already decoded. Data is valid until the callback +// returns. +// +// A call with Lost set carries no block: the read passed over a damaged region that starts at TimeMs (-1 when the +// region has no time of its own), the blocks in it being lost. A decoder that keeps state between blocks resets on +// it, and a cue still on screen ends there. +type SubtitleBlock struct { + TimeMs int64 + DurationMs int64 + Data []byte + Additions []mkv.BlockAddition + Lost bool +} + +// ForEachSubtitleBlock walks srcPath once and calls fn with each block of the subtitle track trackID, whatever its +// codec, in file order. A damaged region within Options.DamageBytes is passed over, reported through OnSkip and to +// fn as a Lost call; a larger one fails the read. An error from fn stops the walk and is returned as is. +func ForEachSubtitleBlock(ctx context.Context, srcPath string, trackID uint64, fn func(SubtitleBlock) error, opts ...mkv.Options) error { + if err := oneopt.Check(opts); err != nil { + return err + } + return walkSubtitleBlocks(ctx, srcPath, trackID, decodedBlocks(fn), opts) +} + +// ForEachSubtitleBlockFrom is ForEachSubtitleBlock served from a prebuilt index: it seeks straight to each recorded +// block and reads nothing else of the file. The index must describe srcPath (size, Segment UID, timecode scale) and +// every block read must carry the track and the time the index recorded, or ErrIndexStale is returned; a track the +// index does not cover is ErrTrackNotIndexed. The blocks are served from the first: a codec whose state spans +// blocks needs them all. +func ForEachSubtitleBlockFrom(ctx context.Context, srcPath string, trackID uint64, ix *SubtitleIndex, fn func(SubtitleBlock) error, opts ...mkv.Options) error { + if err := oneopt.Check(opts); err != nil { + return err + } + return indexedSubtitleBlocks(ctx, srcPath, trackID, ix, decodedBlocks(fn), opts) +} + +// subtitleSink is what a consumer of a track's blocks gives the read. +type subtitleSink struct { + // accept sees the container and the track before any block is read, and refuses a track it cannot serve. + accept func(c *mkv.Container, t *mkv.Track) error + // block takes a block as stored: its payload is not decompressed. + block func(blk mkv.Block) error + // lost is told a damaged region the read passed over starts at fromMs. + lost func(fromMs int64) error + // end, when set, is called once the last block is read: a consumer holding something back gives it then. + end func() error +} + +// finish calls the sink's end. +func (s subtitleSink) finish() error { + if s.end == nil { + return nil + } + return s.end() +} + +// decodedBlocks is the sink of the public reads: any subtitle track, payloads decompressed. +func decodedBlocks(fn func(SubtitleBlock) error) subtitleSink { + var track *mkv.Track + return subtitleSink{ + accept: func(_ *mkv.Container, t *mkv.Track) error { + track = t + return nil + }, + block: func(blk mkv.Block) error { + data, err := decompressSubtitleBlock(track, blk.Data) + if err != nil { + return fmt.Errorf("subtitle block at %d ms: %w", blk.Timecode, err) + } + return fn(SubtitleBlock{TimeMs: blk.Timecode, DurationMs: blk.Duration, Data: data, Additions: blk.Additions}) + }, + lost: func(fromMs int64) error { return fn(SubtitleBlock{TimeMs: fromMs, Lost: true}) }, + } +} + +// acceptSubtitleTrack finds the subtitle track trackID and shows it to the sink. +func acceptSubtitleTrack(c *mkv.Container, trackID uint64, sink subtitleSink) error { + t := subtitleTrackByID(c, trackID) + if t == nil || t.Type != mkv.SubtitleTrack { + return fmt.Errorf("subtitle track %d not found", trackID) + } + return sink.accept(c, t) +} + +// tellLost reports to the sink the regions the read passed over since the last call. +func tellLost(dmg *subtitleDamage, sink subtitleSink) error { + fromMs, ok := dmg.skipped() + if !ok { + return nil + } + return sink.lost(fromMs) +} + +// walkSubtitleBlocks reads the track's blocks by walking the whole file. +func walkSubtitleBlocks(ctx context.Context, srcPath string, trackID uint64, sink subtitleSink, opts []mkv.Options) error { + fs := mkv.FSFrom(opts) + c, err := reader.OpenWithFS(ctx, srcPath, fs, reader.WithoutAttachmentData()) + if err != nil { + return err + } + if err := acceptSubtitleTrack(c, trackID, sink); err != nil { + return err + } + f, err := fs.DoOpen(srcPath) + if err != nil { + return err + } + defer f.Close() + br, err := reader.NewBlockReader(f, c.Info.TimecodeScale) + if err != nil { + return err + } + br.KeepTracks(trackID) // the reader skips the other tracks' payloads unread + dmg := tolerateSubtitleDamage(br, opts) + for { + if err := ctx.Err(); err != nil { + return err + } + blk, err := br.Next() + if err != nil && err != io.EOF { + return err + } + if lerr := tellLost(dmg, sink); lerr != nil { + return lerr + } + if err == io.EOF { + return sink.finish() + } + if err := sink.block(blk); err != nil { + return err + } + } +} + +// indexedSubtitleBlocks reads the track's blocks where ix recorded them. +func indexedSubtitleBlocks(ctx context.Context, srcPath string, trackID uint64, ix *SubtitleIndex, sink subtitleSink, opts []mkv.Options) error { + if ix == nil { + return fmt.Errorf("nil subtitle index") + } + fs := mkv.FSFrom(opts) + c, err := reader.OpenMetaWithFS(ctx, srcPath, fs) + if err != nil { + return err + } + st, err := fs.DoStat(srcPath) + if err != nil { + return err + } + if err := ix.checkAgainst(c, st.Size()); err != nil { + return err + } + if err := acceptSubtitleTrack(c, trackID, sink); err != nil { + return err + } + entries, ok := ix.entries[trackID] + if !ok { + return fmt.Errorf("%w: track %d", ErrTrackNotIndexed, trackID) + } + f, err := fs.DoOpen(srcPath) + if err != nil { + return err + } + defer f.Close() + + var br *reader.BlockReader + var dmg *subtitleDamage + for i := range entries { + if err := ctx.Err(); err != nil { + return err + } + e := &entries[i] + if br == nil { + // The first position seats the reader and the rest re-seat it: one read window for the whole track. + br, err = reader.NewBlockReaderFrom(f, ix.tcScale, e.pos) + if err != nil { + return err + } + br.KeepTracks(trackID) + // A reader seated mid-file never passes over Tracks: without the strides a laced block's frames would + // all carry the block's time, and the result would differ from the walk's. + br.SetTrackDefaultDurations(reader.TrackDefaultDurations(c.Tracks)) + dmg = tolerateSubtitleDamage(br, opts) + } else if err := br.SeekTo(e.pos); err != nil { + return err + } + // One entry, e.frames frames: a laced block gives its whole lace without a new seek. + for k := int64(0); k < e.frames; k++ { + blk, err := br.Next() + if dmg.pending() && (k > 0 || seatZeroed(f, e.pos.Off)) { // the entry lies in a damaged region: its blocks are lost + if err := tellLost(dmg, sink); err != nil { + return err + } + break + } + if err != nil { + return fmt.Errorf("%w: reading the block at offset %d: %w", ErrIndexStale, e.pos.Off, err) + } + if blk.TrackNumber != trackID { + return fmt.Errorf("%w: offset %d holds track %d, the index recorded track %d", + ErrIndexStale, e.pos.Off, blk.TrackNumber, trackID) + } + // Only the first frame carries the recorded time; the rest are strided by the track's DefaultDuration. + if k == 0 && blk.Timecode != e.timeMs { + return fmt.Errorf("%w: offset %d holds track %d at %d ms, the index recorded %d ms", + ErrIndexStale, e.pos.Off, trackID, blk.Timecode, e.timeMs) + } + if err := sink.block(blk); err != nil { + return err + } + } + } + return sink.finish() +} diff --git a/mkv/ops/subindex.go b/mkv/ops/subindex.go index 87b0770b..a7c90692 100644 --- a/mkv/ops/subindex.go +++ b/mkv/ops/subindex.go @@ -26,7 +26,6 @@ import ( "github.com/gravity-zero/mkvgo/internal/oneopt" "github.com/gravity-zero/mkvgo/mkv" "github.com/gravity-zero/mkvgo/mkv/reader" - "github.com/gravity-zero/mkvgo/mkv/subtitle" ) // ErrIndexStale is returned when an index does not describe the file it is @@ -274,107 +273,11 @@ func ExtractSubtitleWebVTTFrom(ctx context.Context, srcPath string, trackID uint if err := oneopt.Check(opts); err != nil { return err } - if ix == nil { - return fmt.Errorf("nil subtitle index") - } - fs := mkv.FSFrom(opts) - c, err := reader.OpenMetaWithFS(ctx, srcPath, fs) - if err != nil { + vtt := &webVTTCues{} + if err := indexedSubtitleBlocks(ctx, srcPath, trackID, ix, vtt.sink(), opts); err != nil { return err } - st, err := fs.DoStat(srcPath) - if err != nil { - return err - } - if err := ix.checkAgainst(c, st.Size()); err != nil { - return err - } - - codec, err := textSubtitleCodec(c, trackID) - if err != nil { - return err - } - track := subtitleTrackByID(c, trackID) - entries, ok := ix.entries[trackID] - if !ok { - return fmt.Errorf("%w: track %d", ErrTrackNotIndexed, trackID) - } - - f, err := fs.DoOpen(srcPath) - if err != nil { - return err - } - defer f.Close() - - var br *reader.BlockReader - var dmg *subtitleDamage - cues := make([]subtitle.Cue, 0, len(entries)) - for i := range entries { - if err := ctx.Err(); err != nil { - return err - } - e := &entries[i] - if br == nil { - // The first position seats the reader; the rest re-seat it, so the - // read window is allocated once for the whole track. - br, err = reader.NewBlockReaderFrom(f, ix.tcScale, e.pos) - if err != nil { - return err - } - br.KeepTracks(trackID) - // A mid-file reader never walks over the Tracks element, so it - // cannot pick the per-frame strides up on its own: without them a - // laced block's frames would all carry the block timecode, and the - // output would differ from the walking extractor's. - br.SetTrackDefaultDurations(reader.TrackDefaultDurations(c.Tracks)) - dmg = tolerateSubtitleDamage(br, opts) - } else if err := br.SeekTo(e.pos); err != nil { - return err - } - // One entry, e.frames frames: an unlaced block takes exactly one turn - // here, a laced one takes its whole lace without re-seeking. - for k := int64(0); k < e.frames; k++ { - blk, err := br.Next() - if dmg.pending() && (k > 0 || seatZeroed(f, e.pos.Off)) { // the entry lies in a damaged region: its cues are lost - fromMs, ok := dmg.skipped() - closeOpenCue(cues, fromMs, ok) - break - } - if err != nil { - return fmt.Errorf("%w: reading the block at offset %d: %w", ErrIndexStale, e.pos.Off, err) - } - if blk.TrackNumber != trackID { - return fmt.Errorf("%w: offset %d holds track %d, the index recorded track %d", - ErrIndexStale, e.pos.Off, blk.TrackNumber, trackID) - } - // Only the block's first frame carries the recorded timecode; the - // rest are strided by the track's DefaultDuration, which a mid-file - // reader cannot know - so they are not checked against the index. - if k == 0 && blk.Timecode != e.timeMs { - return fmt.Errorf("%w: offset %d holds track %d at %d ms, the index recorded %d ms", - ErrIndexStale, e.pos.Off, trackID, blk.Timecode, e.timeMs) - } - payload, err := decompressSubtitleBlock(track, blk.Data) - if err != nil { - return err - } - text := decodeSubtitleCue(codec, payload) - if text == "" { - continue - } - end := int64(0) - if blk.Duration > 0 { - end = blk.Timecode + blk.Duration - } - cue := subtitle.Cue{StartMs: blk.Timecode, EndMs: end, Text: text} - if codec == "webvtt" { - cue.Settings, _ = subtitle.WebVTTAddition(blk.Additions) - } - cues = append(cues, cue) - } - } - subtitle.SettleCueEnds(cues, c.DurationMs) - return subtitle.WriteWebVTT(w, cues) + return vtt.write(w) } // checkAgainst rejects an index built from a different file. The size and the @@ -393,22 +296,6 @@ func (ix *SubtitleIndex) checkAgainst(c *mkv.Container, size int64) error { return nil } -// textSubtitleCodec resolves the codec of a track that must exist, be a -// subtitle track, and be convertible to WebVTT - the same checks -// ExtractSubtitleWebVTT makes before it reads anything. -func textSubtitleCodec(c *mkv.Container, trackID uint64) (string, error) { - for _, t := range c.Tracks { - if t.ID != trackID || t.Type != mkv.SubtitleTrack { - continue - } - if !isTextSubtitle(t.Codec) { - return "", fmt.Errorf("subtitle track %d codec %q is not text (cannot convert to WebVTT)", trackID, t.Codec) - } - return t.Codec, nil - } - return "", fmt.Errorf("subtitle track %d not found", trackID) -} - // MarshalBinary encodes the index. Positions and timecodes are monotonic per // track, so each field is stored as a zigzag varint of its delta from the // previous entry - a 10 331-block index over eight tracks comes to ~150 KiB diff --git a/mkv/ops/subpgs.go b/mkv/ops/subpgs.go index 1d584a9f..238934c2 100644 --- a/mkv/ops/subpgs.go +++ b/mkv/ops/subpgs.go @@ -11,13 +11,9 @@ import ( "context" "fmt" "image" - "image/draw" - "io" "github.com/gravity-zero/mkvgo/internal/oneopt" "github.com/gravity-zero/mkvgo/mkv" - "github.com/gravity-zero/mkvgo/mkv/reader" - "github.com/gravity-zero/mkvgo/mkv/subtitle" ) // PGSCue is one bitmap subtitle: when it is shown, where on the subtitle plane, @@ -52,9 +48,6 @@ type PGSCue struct { // 1.7 GB of decoded NRGBA - more than mkvgo's whole budget. Use // ForEachSubtitlePGS unless the track is known to be short. func ExtractSubtitlePGS(ctx context.Context, srcPath string, trackID uint64, opts ...mkv.Options) ([]PGSCue, error) { - if err := oneopt.Check(opts); err != nil { - return nil, err - } var cues []PGSCue err := ForEachSubtitlePGS(ctx, srcPath, trackID, func(c PGSCue) error { cues = append(cues, c) @@ -66,71 +59,20 @@ func ExtractSubtitlePGS(ctx context.Context, srcPath string, trackID uint64, opt return cues, nil } -// ForEachSubtitlePGS walks srcPath once and calls fn with each decoded cue, in -// presentation order. Only one cue's picture is alive at a time, so a whole -// track can be written out in bounded memory. An error from fn stops the walk -// and is returned as is. +// ForEachSubtitlePGS is ForEachSubtitleBitmap for a track that must be PGS: any other codec is refused by name. func ForEachSubtitlePGS(ctx context.Context, srcPath string, trackID uint64, fn func(PGSCue) error, opts ...mkv.Options) error { if err := oneopt.Check(opts); err != nil { return err } - fs := mkv.FSFrom(opts) - c, err := reader.OpenWithFS(ctx, srcPath, fs, reader.WithoutAttachmentData()) - if err != nil { - return err - } - if err := checkPGSTrack(c, trackID); err != nil { - return err - } - - f, err := fs.DoOpen(srcPath) - if err != nil { - return err - } - defer f.Close() - br, err := reader.NewBlockReader(f, c.Info.TimecodeScale) - if err != nil { - return err - } - br.KeepTracks(trackID) // reader-side filter, as in ExtractSubtitleWebVTT - dmg := tolerateSubtitleDamage(br, opts) - - asm := newPGSAssembler(fn, subtitleTrackByID(c, trackID)) - for { - if err := ctx.Err(); err != nil { - return err - } - blk, err := br.Next() - if err == io.EOF { - if err := asm.afterDamage(dmg); err != nil { - return err - } - break - } - if err != nil { - return err - } - if err := asm.afterDamage(dmg); err != nil { - return err - } - if err := asm.block(blk.Timecode, blk.Duration, blk.Data); err != nil { - return err - } - } - return asm.finish() + return walkSubtitleBlocks(ctx, srcPath, trackID, bitmapCues(fn, checkPGSTrack), opts) } // ExtractSubtitlePGSFrom is ExtractSubtitlePGS served from a prebuilt index: -// instead of walking the file it seeks straight to each recorded block. The same -// staleness checks as ExtractSubtitleWebVTTFrom apply, and for the same reason - -// a stale position would decode whatever bytes happen to sit there. +// instead of walking the file it seeks straight to each recorded block. // // MEMORY: as ExtractSubtitlePGS - see ForEachSubtitlePGSFrom for the bounded // form. func ExtractSubtitlePGSFrom(ctx context.Context, srcPath string, trackID uint64, ix *SubtitleIndex, opts ...mkv.Options) ([]PGSCue, error) { - if err := oneopt.Check(opts); err != nil { - return nil, err - } var cues []PGSCue err := ForEachSubtitlePGSFrom(ctx, srcPath, trackID, ix, func(c PGSCue) error { cues = append(cues, c) @@ -142,238 +84,22 @@ func ExtractSubtitlePGSFrom(ctx context.Context, srcPath string, trackID uint64, return cues, nil } -// ForEachSubtitlePGSFrom serves one PGS track from a prebuilt SubtitleIndex, -// calling fn with each decoded cue in presentation order. -// -// The index is read from its first entry onwards, never from the middle: PGS -// state (palettes, objects) spans display sets within an epoch, so a cue decoded -// from a mid-track start could reference pictures that were never read. +// ForEachSubtitlePGSFrom is ForEachSubtitleBitmapFrom for a track that must be PGS. func ForEachSubtitlePGSFrom(ctx context.Context, srcPath string, trackID uint64, ix *SubtitleIndex, fn func(PGSCue) error, opts ...mkv.Options) error { if err := oneopt.Check(opts); err != nil { return err } - if ix == nil { - return fmt.Errorf("nil subtitle index") - } - fs := mkv.FSFrom(opts) - c, err := reader.OpenMetaWithFS(ctx, srcPath, fs) - if err != nil { - return err - } - st, err := fs.DoStat(srcPath) - if err != nil { - return err - } - if err := ix.checkAgainst(c, st.Size()); err != nil { - return err - } - if err := checkPGSTrack(c, trackID); err != nil { - return err - } - entries, ok := ix.entries[trackID] - if !ok { - return fmt.Errorf("%w: track %d", ErrTrackNotIndexed, trackID) - } - - f, err := fs.DoOpen(srcPath) - if err != nil { - return err - } - defer f.Close() - - asm := newPGSAssembler(fn, subtitleTrackByID(c, trackID)) - var br *reader.BlockReader - var dmg *subtitleDamage - for i := range entries { - if err := ctx.Err(); err != nil { - return err - } - e := &entries[i] - if br == nil { - // The first position seats the reader; the rest re-seat it, so the - // read window is allocated once for the whole track. - br, err = reader.NewBlockReaderFrom(f, ix.tcScale, e.pos) - if err != nil { - return err - } - br.KeepTracks(trackID) - // A mid-file reader never walks over the Tracks element, so it - // cannot pick the per-frame strides up on its own. - br.SetTrackDefaultDurations(reader.TrackDefaultDurations(c.Tracks)) - dmg = tolerateSubtitleDamage(br, opts) - } else if err := br.SeekTo(e.pos); err != nil { - return err - } - for k := int64(0); k < e.frames; k++ { - blk, err := br.Next() - if dmg.pending() && (k > 0 || seatZeroed(f, e.pos.Off)) { // the entry lies in a damaged region: its cues are lost - if err := asm.afterDamage(dmg); err != nil { - return err - } - break - } - if err != nil { - return fmt.Errorf("%w: reading the block at offset %d: %w", ErrIndexStale, e.pos.Off, err) - } - if blk.TrackNumber != trackID { - return fmt.Errorf("%w: offset %d holds track %d, the index recorded track %d", - ErrIndexStale, e.pos.Off, blk.TrackNumber, trackID) - } - // Only the block's first frame carries the recorded timecode; the - // rest are strided by the track's DefaultDuration, which a mid-file - // reader cannot know - so they are not checked against the index. - if k == 0 && blk.Timecode != e.timeMs { - return fmt.Errorf("%w: offset %d holds track %d at %d ms, the index recorded %d ms", - ErrIndexStale, e.pos.Off, trackID, blk.Timecode, e.timeMs) - } - if err := asm.block(blk.Timecode, blk.Duration, blk.Data); err != nil { - return err - } - } - } - return asm.finish() -} - -// checkPGSTrack resolves a track that must exist, be a subtitle track, and carry -// PGS. The message names the codec it did find, because the caller's next move -// differs by codec: a text track goes to ExtractSubtitleWebVTT instead. -func checkPGSTrack(c *mkv.Container, trackID uint64) error { - for _, t := range c.Tracks { - if t.ID != trackID || t.Type != mkv.SubtitleTrack { - continue - } - if t.Codec != "pgs" { - if isTextSubtitle(t.Codec) { - return fmt.Errorf("subtitle track %d codec %q is text, not PGS bitmaps - extract it as WebVTT instead", trackID, t.Codec) - } - return fmt.Errorf("subtitle track %d codec %q is not PGS (S_HDMV/PGS)", trackID, t.Codec) - } - return nil - } - return fmt.Errorf("subtitle track %d not found", trackID) -} - -// pgsAssembler turns the stream of decoded display sets into timed cues. A PGS -// cue's END time is not in its own block: it is the timecode of the next display -// set, which is normally an empty composition meaning "clear the screen". So a -// cue is held open until the block that ends it arrives, and emitted then - one -// cue of latency, never the whole track. -type pgsAssembler struct { - dec *subtitle.PGSDecoder - emit func(PGSCue) error - track *mkv.Track - open *PGSCue -} - -func newPGSAssembler(fn func(PGSCue) error, t *mkv.Track) *pgsAssembler { - return &pgsAssembler{dec: subtitle.NewPGSDecoder(), emit: fn, track: t} -} - -func (a *pgsAssembler) block(timeMs, durMs int64, data []byte) error { - data, err := decompressSubtitleBlock(a.track, data) - if err != nil { - return fmt.Errorf("subtitle block at %d ms: %w", timeMs, err) - } - sets, err := a.dec.Decode(data) - if err != nil { - return fmt.Errorf("subtitle block at %d ms: %w", timeMs, err) - } - for i := range sets { - ds := &sets[i] - // Whatever is on screen ends where this display set begins, whether the - // new one clears the screen or replaces it. - if err := a.closeAt(timeMs); err != nil { - return err - } - if ds.Clear() { - continue - } - cue, err := flattenPGSDisplaySet(ds, timeMs) - if err != nil { - return fmt.Errorf("subtitle block at %d ms: %w", timeMs, err) - } - if durMs > 0 { - // A muxer that wrote a BlockDuration knows the end better than the - // next block's timecode does: emit immediately and hold nothing. - cue.EndMs = timeMs + durMs - if err := a.emit(cue); err != nil { - return err - } - continue - } - a.open = &cue - } - return nil + return indexedSubtitleBlocks(ctx, srcPath, trackID, ix, bitmapCues(fn, checkPGSTrack), opts) } -// closeAt ends the open cue at t. A t that does not move the clock forward (two -// display sets inside one block) would make a zero-length cue, so the default -// duration is used instead - the same fallback the text path applies. -func (a *pgsAssembler) closeAt(t int64) error { - if a.open == nil { +// checkPGSTrack refuses a subtitle track that is not PGS. The message names the codec it did find, because the +// caller's next move differs by codec: a text track goes to ExtractSubtitleWebVTT instead. +func checkPGSTrack(t *mkv.Track) error { + if t.Codec == "pgs" { return nil } - cue := *a.open - a.open = nil - cue.EndMs = t - if cue.EndMs <= cue.StartMs { - cue.EndMs = cue.StartMs + defaultSubDurationMs + if isTextSubtitle(t.Codec) { + return fmt.Errorf("subtitle track %d codec %q is text, not PGS bitmaps - extract it as WebVTT instead", t.ID, t.Codec) } - return a.emit(cue) + return fmt.Errorf("subtitle track %d codec %q is not PGS (S_HDMV/PGS)", t.ID, t.Codec) } - -// afterDamage ends the cue on screen where a region the walk just passed over begins, and forgets the epoch it cut. -func (a *pgsAssembler) afterDamage(d *subtitleDamage) error { - fromMs, ok := d.skipped() - if !ok { - return nil - } - a.dec.Reset() - return a.closeAt(fromMs) -} - -// finish flushes a cue the track never closed - a last subtitle with no trailing -// "clear" display set, which is common enough not to be an error. -func (a *pgsAssembler) finish() error { - if a.open == nil { - return nil - } - cue := *a.open - a.open = nil - cue.EndMs = cue.StartMs + defaultSubDurationMs - return a.emit(cue) -} - -// flattenPGSDisplaySet reduces a display set to the one picture a PGSCue holds. -// Most sets carry a single object and are handed over untouched; a set with -// several (a disc that puts a top and a bottom line in two windows) is composited -// onto the smallest rectangle covering them, so X, Y stays a real screen position -// rather than becoming meaningless. -func flattenPGSDisplaySet(ds *subtitle.PGSDisplaySet, startMs int64) (PGSCue, error) { - cue := PGSCue{StartMs: startMs, ScreenW: ds.ScreenW, ScreenH: ds.ScreenH} - if len(ds.Objects) == 1 { - o := ds.Objects[0] - cue.X, cue.Y, cue.Forced, cue.Image = o.X, o.Y, o.Forced, o.Image - return cue, nil - } - var union image.Rectangle - for _, o := range ds.Objects { - r := o.Image.Bounds().Add(image.Pt(o.X, o.Y)) - union = union.Union(r) - cue.Forced = cue.Forced || o.Forced - } - if union.Dx() > pgsMaxPlane || union.Dy() > pgsMaxPlane { - return cue, fmt.Errorf("PGS: a display set spreads its objects over %dx%d pixels, past the %d a subtitle plane holds: the track is damaged or forged", union.Dx(), union.Dy(), pgsMaxPlane) - } - out := image.NewNRGBA(image.Rect(0, 0, union.Dx(), union.Dy())) - for _, o := range ds.Objects { - at := image.Pt(o.X-union.Min.X, o.Y-union.Min.Y) - draw.Draw(out, image.Rectangle{Min: at, Max: at.Add(o.Image.Bounds().Size())}, o.Image, image.Point{}, draw.Over) - } - cue.X, cue.Y, cue.Image = union.Min.X, union.Min.Y, out - return cue, nil -} - -// pgsMaxPlane bounds the picture several objects are composited onto, as the format bounds each object: placed -// far apart by a forged composition, two dots would otherwise ask for a picture of gigabytes. -const pgsMaxPlane = 4096 diff --git a/mkv/ops/subtitle.go b/mkv/ops/subtitle.go index 1d00d500..da96bd10 100644 --- a/mkv/ops/subtitle.go +++ b/mkv/ops/subtitle.go @@ -227,78 +227,66 @@ func verifiedCueIndex(ctx context.Context, srcPath string, trackID uint64, opts // extractSubtitleWebVTTWalk is ExtractSubtitleWebVTT walking the whole file. func extractSubtitleWebVTTWalk(ctx context.Context, srcPath string, trackID uint64, w io.Writer, opts ...mkv.Options) error { - fs := mkv.FSFrom(opts) - c, err := reader.OpenWithFS(ctx, srcPath, fs, reader.WithoutAttachmentData()) - if err != nil { + vtt := &webVTTCues{} + if err := walkSubtitleBlocks(ctx, srcPath, trackID, vtt.sink(), opts); err != nil { return err } - - var track *mkv.Track - for i := range c.Tracks { - if c.Tracks[i].ID == trackID && c.Tracks[i].Type == mkv.SubtitleTrack { - track = &c.Tracks[i] - break - } - } - if track == nil { - return fmt.Errorf("subtitle track %d not found", trackID) + if err := vtt.write(w); err != nil { + return err } - codec := track.Codec - if !isTextSubtitle(codec) { - return fmt.Errorf("subtitle track %d codec %q is not text (cannot convert to WebVTT)", trackID, codec) + return truncatedSource(srcPath, mkv.FSFrom(opts), vtt.cues) +} + +// webVTTCues gathers a text subtitle track's blocks as WebVTT cues. +type webVTTCues struct { + c *mkv.Container + track *mkv.Track + cues []subtitle.Cue +} + +// sink reads a track that must be text; a cue left open by a damaged region ends where the region starts. +func (v *webVTTCues) sink() subtitleSink { + return subtitleSink{ + accept: func(c *mkv.Container, t *mkv.Track) error { + if !isTextSubtitle(t.Codec) { + return fmt.Errorf("subtitle track %d codec %q is not text (cannot convert to WebVTT)", t.ID, t.Codec) + } + v.c, v.track = c, t + return nil + }, + block: v.block, + lost: func(fromMs int64) error { + closeOpenCue(v.cues, fromMs, true) + return nil + }, } +} - f, err := fs.DoOpen(srcPath) +func (v *webVTTCues) block(blk mkv.Block) error { + payload, err := decompressSubtitleBlock(v.track, blk.Data) if err != nil { return err } - defer f.Close() - br, err := reader.NewBlockReader(f, c.Info.TimecodeScale) - if err != nil { - return err + text := decodeSubtitleCue(v.track.Codec, payload) + if text == "" { + return nil } - br.KeepTracks(trackID) // reader-side filter, as in ExtractSubtitle - dmg := tolerateSubtitleDamage(br, opts) - - var cues []subtitle.Cue - for { - if ctx.Err() != nil { - return ctx.Err() - } - blk, err := br.Next() - if err == io.EOF { - fromMs, ok := dmg.skipped() - closeOpenCue(cues, fromMs, ok) - break - } - if err != nil { - return err - } - fromMs, ok := dmg.skipped() - closeOpenCue(cues, fromMs, ok) - payload, err := decompressSubtitleBlock(track, blk.Data) - if err != nil { - return err - } - text := decodeSubtitleCue(codec, payload) - if text == "" { - continue - } - end := int64(0) - if blk.Duration > 0 { - end = blk.Timecode + blk.Duration - } - cue := subtitle.Cue{StartMs: blk.Timecode, EndMs: end, Text: text} - if codec == "webvtt" { - cue.Settings, _ = subtitle.WebVTTAddition(blk.Additions) - } - cues = append(cues, cue) + end := int64(0) + if blk.Duration > 0 { + end = blk.Timecode + blk.Duration } - subtitle.SettleCueEnds(cues, c.DurationMs) - if err := subtitle.WriteWebVTT(w, cues); err != nil { - return err + cue := subtitle.Cue{StartMs: blk.Timecode, EndMs: end, Text: text} + if v.track.Codec == "webvtt" { + cue.Settings, _ = subtitle.WebVTTAddition(blk.Additions) } - return truncatedSource(srcPath, fs, cues) + v.cues = append(v.cues, cue) + return nil +} + +// write settles the ends the blocks did not state and writes the cues. +func (v *webVTTCues) write(w io.Writer) error { + subtitle.SettleCueEnds(v.cues, v.c.DurationMs) + return subtitle.WriteWebVTT(w, v.cues) } // ErrSourceTruncated reports a source that stops before the end its Segment declares (a download not finished): From 748cfd3f608c2a3c2c18b611e10a4277d5c33caa Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Tue, 17 Nov 2026 16:56:45 +0100 Subject: [PATCH 2/7] feat(cli): extract-subtitle -format png writes any bitmap track, PGS, VobSub or DVB, as PNGs and a manifest --- cmd/mkvgo/commands/extract.go | 27 +++++++++-- cmd/mkvgo/commands/extract_pgs_test.go | 63 ++++++++++++++++++++++++++ cmd/mkvgo/commands/helpers.go | 2 +- 3 files changed, 88 insertions(+), 4 deletions(-) diff --git a/cmd/mkvgo/commands/extract.go b/cmd/mkvgo/commands/extract.go index c486a203..e57852b8 100644 --- a/cmd/mkvgo/commands/extract.go +++ b/cmd/mkvgo/commands/extract.go @@ -75,8 +75,8 @@ func CmdExtractSubtitle(args []string) { opts.SyncOutput = SyncOutput if indexPath != "" { - if format != "vtt" && format != "pgs" { - FatalUsage("-index applies to -format vtt and -format pgs only") + if format != "vtt" && format != "pgs" && format != "png" { + FatalUsage("-index applies to -format vtt, -format png and -format pgs only") } if isMP4Content(source) { Fatal("-index applies to MKV/WebM only: an MP4 already carries its own sample table") @@ -89,6 +89,10 @@ func CmdExtractSubtitle(args []string) { fmt.Printf("extracted %d PGS cue(s) from subtitle track %d (from %s) → %s\n", n, trackID, indexPath, outPath) return } + if format == "png" { + fmt.Printf("extracted %d bitmap cue(s) from subtitle track %d (from %s) → %s\n", n, trackID, indexPath, outPath) + return + } fmt.Printf("extracted subtitle track %d (vtt, from %s) → %s\n", trackID, indexPath, outPath) return } @@ -109,6 +113,18 @@ func CmdExtractSubtitle(args []string) { fmt.Printf("extracted %d PGS cue(s) from subtitle track %d → %s\n", n, trackID, outPath) return } + case "png": + if isMP4Content(source) { + Fatal("bitmap subtitles are read from Matroska: -format png applies to MKV/WebM only") + } + var n int + n, err = writePGSDir(outPath, func(fn func(matroska.BitmapCue) error) error { + return matroska.ForEachSubtitleBitmap(cliCtx, source, trackID, fn, opts) + }) + if err == nil { + fmt.Printf("extracted %d bitmap cue(s) from subtitle track %d → %s\n", n, trackID, outPath) + return + } case "srt": if isMP4Content(source) { Fatal("MP4 subtitle extraction supports only -format vtt") @@ -120,7 +136,7 @@ func CmdExtractSubtitle(args []string) { } err = matroska.ExtractASS(cliCtx, source, trackID, outPath, opts) default: - FatalUsage(fmt.Sprintf("unknown format %q (supported: srt, ass, vtt, pgs)", format)) + FatalUsage(fmt.Sprintf("unknown format %q (supported: srt, ass, vtt, png, pgs)", format)) } if err != nil { FatalErr(err) @@ -156,6 +172,11 @@ func extractFromIndex(source string, trackID uint64, format, indexPath, outPath return matroska.ForEachSubtitlePGSFrom(cliCtx, source, trackID, &ix, fn, opts) }) } + if format == "png" { + return writePGSDir(outPath, func(fn func(matroska.BitmapCue) error) error { + return matroska.ForEachSubtitleBitmapFrom(cliCtx, source, trackID, &ix, fn, opts) + }) + } return 0, writeFileFrom(outPath, func(out io.Writer) error { return matroska.ExtractSubtitleWebVTTFrom(cliCtx, source, trackID, &ix, out, opts) }) diff --git a/cmd/mkvgo/commands/extract_pgs_test.go b/cmd/mkvgo/commands/extract_pgs_test.go index 2ea41826..a98381da 100644 --- a/cmd/mkvgo/commands/extract_pgs_test.go +++ b/cmd/mkvgo/commands/extract_pgs_test.go @@ -168,3 +168,66 @@ func TestCmdExtractSubtitle_PGSIndexRejectsSRT(t *testing.T) { } var _ = matroska.PGSCue{} // the facade type the CLI is the parity partner of + +// -format png reads any bitmap track by its codec: a DVD's VobSub comes out as the same PNGs and manifest, walked +// and served from a subtitle index. +func TestCmdExtractSubtitle_PNGWritesAVobSubTrack(t *testing.T) { + src := "../../../internal/testdata/vobsub.mkv" + dir := t.TempDir() + walked := filepath.Join(dir, "walked") + out := capture(t, func() { + commands.CmdExtractSubtitle([]string{src, "-t", "1", "-o", walked, "-format", "png"}) + }) + if !strings.Contains(out, "extracted 43 bitmap cue(s)") { + t.Errorf("stdout = %q, want the cue count", out) + } + index := filepath.Join(dir, "subs.mkvsix") + capture(t, func() { commands.CmdSubtitleIndex([]string{src, "-o", index}) }) + indexed := filepath.Join(dir, "indexed") + out = capture(t, func() { + commands.CmdExtractSubtitle([]string{src, "-t", "1", "-o", indexed, "-format", "png", "-index", index}) + }) + if !strings.Contains(out, "extracted 43 bitmap cue(s)") || !strings.Contains(out, "from "+index) { + t.Errorf("stdout = %q, want the cue count and the index", out) + } + + type cue struct { + StartMs int64 `json:"start_ms"` + EndMs int64 `json:"end_ms"` + X int `json:"x"` + Y int `json:"y"` + ScreenW int `json:"screen_w"` + ScreenH int `json:"screen_h"` + File string `json:"file"` + } + read := func(d string) (cues []cue) { + blob, err := os.ReadFile(filepath.Join(d, "cues.json")) + if err != nil { + t.Fatal(err) + } + if err := json.Unmarshal(blob, &cues); err != nil { + t.Fatal(err) + } + return cues + } + cues := read(walked) + if len(cues) != 43 || cues[0] != (cue{132499, 137459, 259, 379, 720, 480, "00000.png"}) { + t.Fatalf("%d cues, the first %+v", len(cues), cues[0]) + } + f, err := os.Open(filepath.Join(walked, cues[0].File)) + if err != nil { + t.Fatal(err) + } + defer f.Close() + img, err := png.Decode(f) + if err != nil || img.Bounds().Dx() != 200 || img.Bounds().Dy() != 24 { + t.Errorf("the first picture: %v, err %v; want 200x24", img.Bounds(), err) + } + for i, c := range read(indexed) { + a, errA := os.ReadFile(filepath.Join(walked, c.File)) + b, errB := os.ReadFile(filepath.Join(indexed, c.File)) + if c != cues[i] || errA != nil || errB != nil || string(a) != string(b) { + t.Fatalf("cue %d served from the index differs from the walk", i) + } + } +} diff --git a/cmd/mkvgo/commands/helpers.go b/cmd/mkvgo/commands/helpers.go index ef80316c..cfee9bc8 100644 --- a/cmd/mkvgo/commands/helpers.go +++ b/cmd/mkvgo/commands/helpers.go @@ -113,7 +113,7 @@ var CmdUsage = map[string]string{ "set-chapters": "mkvgo set-chapters -o (OGM format: CHAPTER01=00:00:00.000 / CHAPTER01NAME=Intro)", "extract-chapters": "mkvgo extract-chapters [-o ] (OGM format, stdout by default)", "remove-attachment": "mkvgo remove-attachment -o ", - "extract-subtitle": "mkvgo extract-subtitle -t -o [-format srt|ass|vtt|pgs (default: srt; pgs writes a directory of PNGs + cues.json)] [-index (vtt/pgs, MKV only)] [--damage-bytes n (MKV: pass over a damaged region within n bytes, its cues lost; default 64 MiB)]", + "extract-subtitle": "mkvgo extract-subtitle -t -o [-format srt|ass|vtt|png|pgs (default: srt; png writes a bitmap track - PGS, VobSub, DVB - as a directory of PNGs + cues.json, pgs the same for a PGS track only)] [-index (vtt/png/pgs, MKV only)] [--damage-bytes n (MKV: pass over a damaged region within n bytes, its cues lost; default 64 MiB)]", "subtitle-index": "mkvgo subtitle-index -o [-t 4,5 (default: every subtitle track)] [-from-cues] [--damage-bytes n]", "split": "mkvgo split -o [-chapters | -range 0-5:00,5:00-0 | -every 6:00] [-pattern part_%03d.mkv|.mp4 ({title} = chapter title)]", "join": "mkvgo join -o ... (all MKV/WebM or all MP4/MOV)", From 0f9f5eb8b987c1a503bd71ead77e9db98e84f1c2 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Tue, 17 Nov 2026 16:56:46 +0100 Subject: [PATCH 3/7] docs: bitmap subtitles as cues whatever the codec, the subtitle block read, extract-subtitle -format png --- docs/cli.md | 12 ++++++---- docs/library.md | 62 +++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 62 insertions(+), 12 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 873e1bfa..8ad75006 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -439,18 +439,18 @@ mkvgo remove-attachment video.mkv -o out.mkv 2 ### extract-subtitle -Extract an embedded text subtitle track as SRT, ASS or WebVTT. SRT/ASS apply to MKV/WebM; WebVTT (`-format vtt`) also works on MP4 (tx3g/wvtt). +Extract an embedded text subtitle track as SRT, ASS or WebVTT, or a bitmap one as pictures. SRT/ASS apply to MKV/WebM; WebVTT (`-format vtt`) also works on MP4 (tx3g/wvtt). `-format png` reads a bitmap track of an MKV/WebM (PGS, VobSub or DVB, by its codec) and writes into the directory `-o` one PNG per cue and a `cues.json` manifest: for each cue its file, `start_ms`, `end_ms`, its position `x`, `y` on the subtitle plane `screen_w` x `screen_h`, and `forced`. `-format pgs` is the same for a PGS track, any other codec refused. ``` -mkvgo extract-subtitle -t -o [-format srt|ass|vtt] [--damage-bytes ] +mkvgo extract-subtitle -t -o [-format srt|ass|vtt|png|pgs] [-index ] [--damage-bytes ] ``` | Flag | Description | |---|---| | `-t` | Track ID to extract (required) | -| `-o` | Output file path (required) | -| `-format` | Output format: `srt` (default), `ass`, or `vtt` | -| `-index` | Serve from a `subtitle-index` file instead of walking the source (`-format vtt`, MKV/WebM only) | +| `-o` | Output file path, or directory for `png` and `pgs` (required) | +| `-format` | Output format: `srt` (default), `ass`, `vtt`, `png` or `pgs` | +| `-index` | Serve from a `subtitle-index` file instead of walking the source (`-format vtt`, `png` and `pgs`, MKV/WebM only) | | `--damage-bytes` | How far past an unreadable element the read looks for the next Cluster (MKV/WebM). A damaged region within it is passed over, its cues lost and named on stderr; a longer one fails the extraction. With `--exit-damaged`, an extraction that passed over a region exits 3. `-1` refuses any damage. Default 64 MiB | ```bash @@ -459,6 +459,8 @@ mkvgo extract-subtitle video.mkv -t 3 -o subs.ass -format ass mkvgo extract-subtitle video.mkv -t 3 -o subs.vtt -format vtt mkvgo extract-subtitle movie.mp4 -t 3 -o subs.vtt -format vtt mkvgo extract-subtitle video.mkv -t 3 -o subs.vtt -format vtt -index video.mkvsix +mkvgo extract-subtitle dvdrip.mkv -t 4 -o subs/ -format png +mkvgo extract-subtitle dvdrip.mkv -t 4 -o subs/ -format png -index dvdrip.mkvsix ``` ### subtitle-index diff --git a/docs/library.md b/docs/library.md index 5050fb1e..db309d7a 100644 --- a/docs/library.md +++ b/docs/library.md @@ -1620,14 +1620,15 @@ A Matroska track whose blocks the source's own Cues all name - their count match #### A damaged region Every Matroska subtitle read - `ExtractSubtitle`, `ExtractASS`, -`ExtractSubtitleWebVTT`, `ForEachSubtitlePGS`, their `From` forms, -`BuildSubtitleIndex` and `SubtitleIndex.Resolve` - passes over a damaged region +`ExtractSubtitleWebVTT`, `ForEachSubtitleBitmap`, `ForEachSubtitlePGS`, +`ForEachSubtitleBlock`, their `From` forms, `BuildSubtitleIndex` and +`SubtitleIndex.Resolve` - passes over a damaged region (a zeroed stretch, bytes a download never received) when the next Cluster lies within `Options.DamageBytes` of it, 64 MiB by default (`mkv.DefaultDamageBytes`), as the on-demand HLS windows do. The cues inside the region are lost and the -rest of the track is delivered; a PGS cue the region left on screen ends with -the default duration (or at the start of the cluster the region begins in) -instead of lasting until the next cue past it. Each region is reported once +rest of the track is delivered; a bitmap cue the region left on screen ends +with the default duration (or at the start of the cluster the region begins +in) instead of lasting until the next cue past it. Each region is reported once through `Options.OnSkip`, with its byte range and the timestamps of the clusters around it. A longer region fails the read with `reader.ErrDamagedRegion`, and a negative `DamageBytes` refuses any damage. @@ -1714,6 +1715,52 @@ the choice is only about what the store carries; a caller that only ever serves WebVTT can name the text tracks and skip the rest. `Tracks()`, `Blocks(id)` and `SourceSize()` report what an index covers. CLI: `mkvgo subtitle-index`. +### Bitmap subtitles as cues, whatever the codec + +A bitmap subtitle track - PGS on a Blu-ray rip, VobSub on a DVD rip, DVB on a +broadcast capture - comes out as timed pictures through one call, which picks +the decoder from the track's codec: + +```go +// Walking the file: +err := matroska.ForEachSubtitleBitmap(ctx, "movie.mkv", trackID, func(c matroska.BitmapCue) error { + return png.Encode(w, c.Image) // c.StartMs, c.EndMs, c.X, c.Y, c.ScreenW, c.ScreenH, c.Forced +}) + +// Served from a SubtitleIndex: a seek per block instead of a pass over the file. +err = matroska.ForEachSubtitleBitmapFrom(ctx, "movie.mkv", trackID, ix, fn) +``` + +`BitmapCue` is the type `PGSCue` names. One cue's picture is alive at a time. +A cue starts where its display set takes effect and ends, in this order: where +the stream says (a VobSub stop command), at the duration the muxer wrote for +its block, or where the next display set begins - no later than a DVB page's +time-out, and 3 s after its start for a last cue nothing closes. A display set +of several pictures (two PGS windows, two DVB regions) is one cue, composited +on the smallest rectangle that holds them. A text track is refused by name, as +is a bitmap codec without a decoder here. `ForEachSubtitlePGS` and its +siblings below are the same read for a track that must be PGS. + +The read under it is exported for a consumer that decodes on its own: + +```go +err := matroska.ForEachSubtitleBlockFrom(ctx, "movie.mkv", trackID, ix, func(b matroska.SubtitleBlock) error { + if b.Lost { // a damaged region was passed over, from b.TimeMs: reset a stateful decoder + return nil + } + // b.TimeMs, b.DurationMs, b.Data: the payload as the codec reads it, a compressed track decoded + return nil +}) +``` + +`ForEachSubtitleBlock` walks the file and `ForEachSubtitleBlockFrom` seeks +where the index recorded each block, for a subtitle track of any codec. Served +from an index, the read checks that the index describes the file (size, +Segment UID, timecode scale) and that every block carries the track and the +time recorded, or returns `ErrIndexStale`; a track the index does not cover is +`ErrTrackNotIndexed`. The blocks are always served from the first: a bitmap +codec's state spans blocks. + ### Bitmap subtitles: PGS Blu-ray rips carry their subtitles as `S_HDMV/PGS`: not text, but a stream of @@ -1734,7 +1781,7 @@ err = matroska.ForEachSubtitlePGSFrom(ctx, "movie.mkv", trackID, ix, func(c matr **The index needs nothing new.** `BuildSubtitleIndex` selects tracks by TYPE and never by codec, so an index built by any release since the feature landed -already holds the PGS track's blocks: serving one costs a seek, not a rebuild, +already holds a bitmap track's blocks, PGS, VobSub or DVB: serving one costs a seek, not a rebuild, and the wire format is unchanged. **Which entry point.** The index is not the answer to every extraction, and it @@ -1913,7 +1960,8 @@ streaming form. DVD rips carry `S_VOBSUB` and broadcast captures `S_DVBSUB`: pictures again, in two more codecs. `subtitle.VobSubDecoder` and `subtitle.DVBSubDecoder` are -block-level decoders with the shape of `subtitle.PGSDecoder`: built from the +block-level decoders with the shape of `subtitle.PGSDecoder`, the ones +`ForEachSubtitleBitmap` drives, for a caller with its own read loop: built from the track's CodecPrivate, fed the track's blocks in file order, `Reset` when the read skips blocks. Both return `[]subtitle.BitmapDisplaySet`, which is the type `PGSDisplaySet` names, so one consumer serves the three codecs: pictures From 81f8e9bebcba8c590a4f41e6948031ed75385d59 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Tue, 17 Nov 2026 16:56:48 +0100 Subject: [PATCH 4/7] docs(changelog): the codec-neutral bitmap cues, the subtitle block read and -format png under Unreleased --- CHANGELOG.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 82dffe5a..d3e952de 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,21 @@ its series' file in [changelog/](changelog/) when a newer one ships. ## [Unreleased] +### Added + +- `ForEachSubtitleBitmap` and `ForEachSubtitleBitmapFrom` (`matroska`, + `mkv/ops`) give a bitmap subtitle track as timed pictures whatever its codec, + PGS, VobSub or DVB, walking the file or served from a `SubtitleIndex`; + `BitmapCue` is the type `PGSCue` names. `ForEachSubtitlePGS` and its + siblings are unchanged. +- `ForEachSubtitleBlock` and `ForEachSubtitleBlockFrom` give the blocks of a + subtitle track of any codec (`SubtitleBlock`: time, duration, decoded + payload), walked or served from an index under the checks of the other + indexed reads, a damaged region passed over as a `Lost` call. +- `extract-subtitle -format png` writes any bitmap track (PGS, VobSub, DVB) as + PNGs and a `cues.json` manifest, with `-index` too; `-format pgs` is + unchanged. + ## [0.67.0] - 2026-11-17 ### Added From 9e414463deee80645522504acad646c48f826f85 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Tue, 17 Nov 2026 16:57:30 +0100 Subject: [PATCH 5/7] fix(ops): ExtractSubtitlePGS and ExtractSubtitlePGSFrom check their options first again --- mkv/ops/subpgs.go | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/mkv/ops/subpgs.go b/mkv/ops/subpgs.go index 238934c2..9b4a31e0 100644 --- a/mkv/ops/subpgs.go +++ b/mkv/ops/subpgs.go @@ -48,6 +48,9 @@ type PGSCue struct { // 1.7 GB of decoded NRGBA - more than mkvgo's whole budget. Use // ForEachSubtitlePGS unless the track is known to be short. func ExtractSubtitlePGS(ctx context.Context, srcPath string, trackID uint64, opts ...mkv.Options) ([]PGSCue, error) { + if err := oneopt.Check(opts); err != nil { + return nil, err + } var cues []PGSCue err := ForEachSubtitlePGS(ctx, srcPath, trackID, func(c PGSCue) error { cues = append(cues, c) @@ -73,6 +76,9 @@ func ForEachSubtitlePGS(ctx context.Context, srcPath string, trackID uint64, fn // MEMORY: as ExtractSubtitlePGS - see ForEachSubtitlePGSFrom for the bounded // form. func ExtractSubtitlePGSFrom(ctx context.Context, srcPath string, trackID uint64, ix *SubtitleIndex, opts ...mkv.Options) ([]PGSCue, error) { + if err := oneopt.Check(opts); err != nil { + return nil, err + } var cues []PGSCue err := ForEachSubtitlePGSFrom(ctx, srcPath, trackID, ix, func(c PGSCue) error { cues = append(cues, c) From be27a14620af023a20c79a1f6e750e12fa6a6bc9 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Tue, 17 Nov 2026 17:42:27 +0100 Subject: [PATCH 6/7] docs: README, recipes and library name extract-subtitle -format png for the three bitmap codecs --- README.md | 2 +- docs/library.md | 8 +++++--- docs/recipes.md | 6 ++++++ 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7a4d5498..2a9b142f 100644 --- a/README.md +++ b/README.md @@ -189,7 +189,7 @@ mkvgo [options] # global: -json, -f/--force, --version | | `playability` · `ladder` | Direct-play verdict per client target / recommended ABR rungs capped at the source | | | `ingest` | One-call serving plan for a file: direct-play, remux to HLS, or transcode | | **Extract** | `demux` | Extract tracks to raw streams (MKV/WebM or MP4) | -| | `extract-subtitle` · `to-vtt` | Subtitle track → SRT/ASS/WebVTT, or PGS bitmaps → PNGs + manifest; external sidecar → WebVTT | +| | `extract-subtitle` · `to-vtt` | Subtitle track → SRT/ASS/WebVTT, or a bitmap track (PGS, VobSub, DVB) → PNGs + manifest; external sidecar → WebVTT | | | `extract-attachment` · `add-attachment` · `remove-attachment` | Manage attachments (MIME sniffed) | | | `extract-frame` | Keyframe nearest a time, decoder-ready - thumbnail/storyboard pipelines | | | `extract-frames` | Keyframe-only Matroska stream (every N seconds or at given times) | diff --git a/docs/library.md b/docs/library.md index db309d7a..28d10464 100644 --- a/docs/library.md +++ b/docs/library.md @@ -1739,7 +1739,8 @@ time-out, and 3 s after its start for a last cue nothing closes. A display set of several pictures (two PGS windows, two DVB regions) is one cue, composited on the smallest rectangle that holds them. A text track is refused by name, as is a bitmap codec without a decoder here. `ForEachSubtitlePGS` and its -siblings below are the same read for a track that must be PGS. +siblings below are the same read for a track that must be PGS. CLI: `mkvgo +extract-subtitle -format png`, with `-index` for the indexed form. The read under it is exported for a consumer that decodes on its own: @@ -1953,8 +1954,9 @@ The decoder was written from the format description; mkvgo is MIT and links no third-party subtitle decoder. Out of scope by design: no OCR, no sprite sheet, no WebVTT rendering - which player-side packaging a bitmap track gets is the consumer's decision, not an extractor's. CLI: `mkvgo extract-subtitle -format -pgs -o ` writes one PNG per cue plus a `cues.json` manifest, driven by the -streaming form. +png -o ` writes one PNG per cue plus a `cues.json` manifest for a bitmap +track of any of the three codecs, driven by the streaming form; `-format pgs` +does the same for a track that must be PGS. ### Bitmap subtitles: VobSub and DVB diff --git a/docs/recipes.md b/docs/recipes.md index 8c870c68..01c8e236 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -131,10 +131,16 @@ c, _ := matroska.OpenMeta(ctx, "video.mkv", matroska.WithInBandColourFallback()) mkvgo extract-subtitle video.mkv -t 3 -o subs.srt # text → SRT mkvgo extract-subtitle video.mkv -t 3 -o subs.ass -format ass # styled → ASS mkvgo extract-subtitle video.mkv -t 3 -o subs.vtt -format vtt # → WebVTT +mkvgo extract-subtitle video.mkv -t 4 -o subs/ -format png # bitmap (PGS, VobSub, DVB) → PNGs + cues.json ``` ```go err := matroska.ExtractSubtitle(ctx, "video.mkv", 3, "subs.srt") + +// A bitmap track, whatever its codec: one timed picture per cue. +err = matroska.ForEachSubtitleBitmap(ctx, "video.mkv", 4, func(c matroska.BitmapCue) error { + return save(c.Image, c.StartMs, c.EndMs, c.X, c.Y) +}) ``` ## Convert MKV ↔ MP4 (no re-encode) From 9a8d2e32c4be3f191a9dc3dffdddf4ece67dc4c5 Mon Sep 17 00:00:00 2001 From: gravity-zero Date: Tue, 17 Nov 2026 17:42:29 +0100 Subject: [PATCH 7/7] docs(changelog): 0.68.0 dated 2026-11-17, 0.67.0 archived in changelog/0.60-0.69.md --- CHANGELOG.md | 20 ++------------------ changelog/0.60-0.69.md | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d3e952de..e3065d4f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ its series' file in [changelog/](changelog/) when a newer one ships. ## [Unreleased] +## [0.68.0] - 2026-11-17 + ### Added - `ForEachSubtitleBitmap` and `ForEachSubtitleBitmapFrom` (`matroska`, @@ -23,21 +25,3 @@ its series' file in [changelog/](changelog/) when a newer one ships. - `extract-subtitle -format png` writes any bitmap track (PGS, VobSub, DVB) as PNGs and a `cues.json` manifest, with `-index` too; `-format pgs` is unchanged. - -## [0.67.0] - 2026-11-17 - -### Added - -- `subtitle.VobSubDecoder` and `subtitle.DVBSubDecoder` decode the bitmap - subtitles of DVD rips (`S_VOBSUB`) and of broadcast captures (`S_DVBSUB`) - block by block, as `subtitle.PGSDecoder` does PGS. Both return the PGS - decoder's display sets (`subtitle.BitmapDisplaySet`, the same type): each - picture in straight-alpha NRGBA with its position on the subtitle plane, an - empty set where the screen clears. -- `subtitle.ParseVobSubIndex` with `VobSubIndex.ForEachUnit`, and - `subtitle.ForEachSUPDisplaySet`, read the bitmap subtitles that sit beside a - video: a VobSub `.idx`/`.sub` pair and a PGS `.sup`, one unit or display set - at a time, each with its time, in the form the decoders take. -- `subtitle.PGSDisplaySet` gains `Delay` and `Duration`, which a VobSub unit's - start and stop commands set, and `Timeout`, a DVB page's time-out; each is - zero where the codec has no such thing. diff --git a/changelog/0.60-0.69.md b/changelog/0.60-0.69.md index be5a53ea..b3791e44 100644 --- a/changelog/0.60-0.69.md +++ b/changelog/0.60-0.69.md @@ -2,6 +2,24 @@ Archived entries of mkvgo 0.60.x to 0.69.x, as they were published; a version moves here once a newer one ships. The current versions are in [CHANGELOG.md](../CHANGELOG.md). +## [0.67.0] - 2026-11-17 + +### Added + +- `subtitle.VobSubDecoder` and `subtitle.DVBSubDecoder` decode the bitmap + subtitles of DVD rips (`S_VOBSUB`) and of broadcast captures (`S_DVBSUB`) + block by block, as `subtitle.PGSDecoder` does PGS. Both return the PGS + decoder's display sets (`subtitle.BitmapDisplaySet`, the same type): each + picture in straight-alpha NRGBA with its position on the subtitle plane, an + empty set where the screen clears. +- `subtitle.ParseVobSubIndex` with `VobSubIndex.ForEachUnit`, and + `subtitle.ForEachSUPDisplaySet`, read the bitmap subtitles that sit beside a + video: a VobSub `.idx`/`.sub` pair and a PGS `.sup`, one unit or display set + at a time, each with its time, in the form the decoders take. +- `subtitle.PGSDisplaySet` gains `Delay` and `Duration`, which a VobSub unit's + start and stop commands set, and `Timeout`, a DVB page's time-out; each is + zero where the codec has no such thing. + ## [0.66.2] - 2026-11-10 ### Security