Skip to content
27 changes: 13 additions & 14 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,19 @@ its series' file in [changelog/](changelog/) when a newer one ships.

## [Unreleased]

## [0.67.0] - 2026-11-17
## [0.68.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.
- `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.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ mkvgo <command> [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) |
Expand Down
18 changes: 18 additions & 0 deletions changelog/0.60-0.69.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
27 changes: 24 additions & 3 deletions cmd/mkvgo/commands/extract.go
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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
}
Expand All @@ -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")
Expand All @@ -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)
Expand Down Expand Up @@ -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)
})
Expand Down
63 changes: 63 additions & 0 deletions cmd/mkvgo/commands/extract_pgs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}
}
2 changes: 1 addition & 1 deletion cmd/mkvgo/commands/helpers.go
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ var CmdUsage = map[string]string{
"set-chapters": "mkvgo set-chapters <file.mkv|.mp4> -o <out> <chapters.txt> (OGM format: CHAPTER01=00:00:00.000 / CHAPTER01NAME=Intro)",
"extract-chapters": "mkvgo extract-chapters <file.mkv|.mp4> [-o <chapters.txt>] (OGM format, stdout by default)",
"remove-attachment": "mkvgo remove-attachment <file.mkv> -o <out.mkv> <attachmentID|name>",
"extract-subtitle": "mkvgo extract-subtitle <file.mkv|.mp4> -t <trackID> -o <out> [-format srt|ass|vtt|pgs (default: srt; pgs writes a directory of PNGs + cues.json)] [-index <index.mkvsix> (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 <file.mkv|.mp4> -t <trackID> -o <out> [-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 <index.mkvsix> (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 <file.mkv> -o <index.mkvsix> [-t 4,5 (default: every subtitle track)] [-from-cues] [--damage-bytes n]",
"split": "mkvgo split <file.mkv|.mp4> -o <dir> [-chapters | -range 0-5:00,5:00-0 | -every 6:00] [-pattern part_%03d.mkv|.mp4 ({title} = chapter title)]",
"join": "mkvgo join -o <out.mkv|.mp4> <file1> <file2> ... (all MKV/WebM or all MP4/MOV)",
Expand Down
12 changes: 7 additions & 5 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <file.mkv|.mp4> -t <trackID> -o <out> [-format srt|ass|vtt] [--damage-bytes <n>]
mkvgo extract-subtitle <file.mkv|.mp4> -t <trackID> -o <out> [-format srt|ass|vtt|png|pgs] [-index <index.mkvsix>] [--damage-bytes <n>]
```

| 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
Expand All @@ -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
Expand Down
68 changes: 59 additions & 9 deletions docs/library.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -1714,6 +1715,53 @@ 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. 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:

```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
Expand All @@ -1734,7 +1782,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
Expand Down Expand Up @@ -1906,14 +1954,16 @@ 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 <dir>` writes one PNG per cue plus a `cues.json` manifest, driven by the
streaming form.
png -o <dir>` 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

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
Expand Down
6 changes: 6 additions & 0 deletions docs/recipes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading
Loading