Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
8fcf4eb
fix(ops): a bitmap subtitle block that reads but does not decode is l…
gravity-zero Nov 17, 2026
4aaa0ca
docs: a bitmap subtitle block that does not decode is lost alone, and…
gravity-zero Nov 17, 2026
c040665
docs(changelog): the undecodable bitmap subtitle block under Unreleased
gravity-zero Nov 17, 2026
9205209
feat(ops): the range OnSkip gets for a bitmap subtitle block that doe…
gravity-zero Nov 17, 2026
e6c347f
feat(cli): extract-subtitle names a subtitle block that does not deco…
gravity-zero Nov 17, 2026
19a8052
docs: DamagedRange.Err and the message extract-subtitle prints for a …
gravity-zero Nov 17, 2026
91c19fe
docs(changelog): DamagedRange.Err under Unreleased
gravity-zero Nov 17, 2026
44a545f
perf(subtitle): a DVB region and a PGS object keep their picture from…
gravity-zero Nov 17, 2026
7603be3
fix(ops): a bitmap cue whose block states a duration ends no later th…
gravity-zero Nov 17, 2026
ef84a1a
docs(library): bitmap pictures shared between display sets, and the t…
gravity-zero Nov 17, 2026
6f5841e
docs(changelog): kept bitmap pictures and the time-out bound under Un…
gravity-zero Nov 17, 2026
f3eb3b6
fix(mp4): a fragmented movie lasts until its latest track ends, its s…
gravity-zero Nov 17, 2026
e06ef72
docs(library): a fragmented source's duration is the end of its lates…
gravity-zero Nov 17, 2026
613a9ae
docs(changelog): the fragmented MP4 duration under Unreleased
gravity-zero Nov 17, 2026
29b1d0f
feat(ops): ForEachSubtitleBitmapFile gives a .sup or a .idx/.sub pair…
gravity-zero Nov 17, 2026
e00ec13
feat(cli): extract-subtitle writes a .sup or a .idx/.sub pair as PNGs…
gravity-zero Nov 17, 2026
d4deab6
docs: bitmap subtitle files beside the video as cues, in the library …
gravity-zero Nov 17, 2026
9a258d2
docs(changelog): ForEachSubtitleBitmapFile under Unreleased
gravity-zero Nov 17, 2026
3ce0c19
style(cli): name the -format pgs case of a .sup in extract-subtitle
gravity-zero Nov 17, 2026
042b268
docs(changelog): 0.69.0 dated 2026-11-17, 0.68.0 archived in changelo…
gravity-zero Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 41 additions & 13 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,47 @@ its series' file in [changelog/](changelog/) when a newer one ships.

## [Unreleased]

## [0.68.0] - 2026-11-17
## [0.69.0] - 2026-11-17

### 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.
- `ForEachSubtitleBitmapFile` (`matroska`, `mkv/ops`) gives a bitmap subtitle
file that sits beside a video - a PGS `.sup`, or a VobSub `.idx`/`.sub`
pair - as cues, timed and ended as `ForEachSubtitleBitmap` does a track's,
a unit that does not decode lost alone. `extract-subtitle` reads such a file
as `-format png`, `-t` picking a `.idx`'s language from 1.
- `DamagedRange.Err` (`mkv`, `matroska`): set on the range `Options.OnSkip`
gets for a bitmap subtitle block that was read but did not decode, to the
decoder's error; nil for a damaged region. `extract-subtitle` names such a
block on stderr by its time and that error, in a message of its own.

### Breaking

- Bytes written: `from-mp4` of a fragmented MP4 without `mehd` writes the
Matroska `Duration` the probe now reports, the end of the latest track - a
track ending where it starts plus what its samples last. A video track that
starts after zero (a composition offset, no edit list) and outlasts the
audio was left out, the duration being the longest sum of sample durations
(2.763 s for a file whose last frame ends at 2.803 s; the probe of 17 of
the 732 files of the public test corpora changes, none shortening). A
track's own duration does not change.
- `subtitle.DVBSubDecoder` and `subtitle.PGSDecoder` keep the picture of a
region or an object from one display set to the next, until its pixels or
its colours change: display sets that show the same picture now share one
image, as its placements within a set did, so a caller that wrote into a
returned image changes the next sets' too - treat the images as read-only.
A display set that only names an unchanged region again no longer reads it
through its colour table again (a 14-byte block made a 4096x4096 region be
rendered whole).

### Fixed

- A bitmap cue whose block states a duration ends no later than its DVB
page's time-out; the block's duration won.
- `ForEachSubtitleBitmap`, `ForEachSubtitlePGS`, their `From` forms and
`extract-subtitle -format png|pgs`: a block that reads but does not decode
no longer fails the whole track. It is lost alone, the cue on screen ending
at its time, and reported through `Options.OnSkip` (`DamagedRange.Err`
says why); the rest of the track is delivered. `Options.DamageBytes`
negative (`--damage-bytes -1`) still fails the read on it. A PGS track with
such a block failed since PGS extraction exists.
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 a bitmap track (PGS, VobSub, DVB) → 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, or a `.sup`/`.idx`+`.sub` → PNGs + manifest |
| | `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
17 changes: 17 additions & 0 deletions changelog/0.60-0.69.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,23 @@

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.68.0] - 2026-11-17

### 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
Expand Down
56 changes: 54 additions & 2 deletions cmd/mkvgo/commands/extract.go
Original file line number Diff line number Diff line change
Expand Up @@ -46,13 +46,12 @@ func CmdExtractAttachment(args []string) {

func CmdExtractSubtitle(args []string) {
usage := CmdUsage["extract-subtitle"]
if len(args) < 5 {
if len(args) < 3 {
FatalUsage("usage: " + usage)
}
var outPath, format, indexPath string
var trackID uint64
var damageBytes int64
format = "srt"

fl := newFlags("extract-subtitle")
fl.String(&outPath, "-o")
Expand All @@ -67,6 +66,13 @@ func CmdExtractSubtitle(args []string) {
}, "-t")
fl.String(&format, "-format")
source, _ := fl.ParseSource(args, usage)
if isBitmapSubtitleFile(source) {
extractBitmapSubtitleFile(source, outPath, format, indexPath, trackID, damageBytes, usage)
return
}
if format == "" {
format = "srt"
}
if outPath == "" || trackID == 0 {
FatalUsage("usage: " + usage)
}
Expand Down Expand Up @@ -198,6 +204,43 @@ type pgsCueManifest struct {
File string `json:"file"`
}

// isBitmapSubtitleFile reports a subtitle file that sits beside a video: a PGS .sup, a VobSub .idx or .sub.
func isBitmapSubtitleFile(path string) bool {
switch strings.ToLower(filepath.Ext(path)) {
case ".sup", ".idx", ".sub":
return true
}
return false
}

// extractBitmapSubtitleFile writes the cues of a .sup or a .idx/.sub pair as PNGs and a manifest. -t picks the
// language of a .idx by its position in it, from 1; a .sup holds one.
func extractBitmapSubtitleFile(source, outPath, format, indexPath string, stream uint64, damageBytes int64, usage string) {
if outPath == "" {
FatalUsage("usage: " + usage)
}
pgsOfSup := format == "pgs" && strings.EqualFold(filepath.Ext(source), ".sup")
if format != "" && format != "png" && !pgsOfSup {
FatalUsage(fmt.Sprintf("%s holds bitmap subtitles: -format png writes them, -format %s does not apply", filepath.Base(source), format))
}
if indexPath != "" {
FatalUsage("-index applies to a subtitle track of an MKV/WebM, not to a subtitle file beside the video")
}
if stream == 0 {
stream = 1
}
guardOutput(outPath, source)
opts := subtitleReadOptions(damageBytes)
opts.SyncOutput = SyncOutput
n, err := writePGSDir(outPath, func(fn func(matroska.BitmapCue) error) error {
return matroska.ForEachSubtitleBitmapFile(cliCtx, source, int(stream-1), fn, opts)
})
if err != nil {
FatalErr(err)
}
fmt.Printf("extracted %d bitmap cue(s) from %s (stream %d) → %s\n", n, source, stream, outPath)
}

// writePGSDir writes one PNG per cue into outDir plus a cues.json manifest. It
// drives the streaming extractor, so a two-hour track costs one picture of
// memory rather than the whole track's worth.
Expand Down Expand Up @@ -333,6 +376,15 @@ func subtitleIndexFromCues(source string, trackIDs []uint64, opts ...matroska.Op
func subtitleReadOptions(damageBytes int64) matroska.Options {
return matroska.Options{DamageBytes: damageBytes, OnSkip: func(r matroska.DamagedRange) {
noteDamage()
if r.Err != nil && r.StartOffset < 0 { // a unit of a file beside the video: no byte range there
fmt.Fprintf(os.Stderr, "lost the subtitle at %d ms, which does not decode: %v\n", r.ApproxStartMs, r.Err)
return
}
if r.Err != nil { // a block that was read: its time and what its decoder said
fmt.Fprintf(os.Stderr, "lost the subtitle block at %d ms (bytes %d to %d), which does not decode: %v\n",
r.ApproxStartMs, r.StartOffset, r.EndOffset, r.Err)
return
}
fmt.Fprintf(os.Stderr, "skipped a damaged region at bytes %d to %d (about %d to %d ms): the subtitles in it are lost\n",
r.StartOffset, r.EndOffset, r.ApproxStartMs, r.ApproxEndMs)
}}
Expand Down
78 changes: 78 additions & 0 deletions cmd/mkvgo/commands/extract_pgs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -231,3 +231,81 @@ func TestCmdExtractSubtitle_PNGWritesAVobSubTrack(t *testing.T) {
}
}
}

// On stderr a block that does not decode is named by its time and its error, in words of its own: a region the read
// jumped over keeps the message it had.
func TestCmdExtractSubtitle_NamesABlockThatDoesNotDecode(t *testing.T) {
data, err := os.ReadFile("../../../internal/testdata/vobsub.mkv")
if err != nil {
t.Fatal(err)
}
clear(data[len(data)/2 : len(data)/2+4096])
src := filepath.Join(t.TempDir(), "zeroed.mkv")
if err := os.WriteFile(src, data, 0o644); err != nil {
t.Fatal(err)
}
var out string
errOut := stderrOf(t, func() {
out = capture(t, func() {
commands.CmdExtractSubtitle([]string{src, "-t", "1", "-o", filepath.Join(t.TempDir(), "subs"), "-format", "png"})
})
})
if !strings.Contains(out, "extracted 41 bitmap cue(s)") {
t.Errorf("stdout = %q, want 41 cues", out)
}
lines := strings.Split(strings.TrimSpace(errOut), "\n")
if len(lines) != 2 {
t.Fatalf("stderr holds %d line(s), want the region and the block:\n%s", len(lines), errOut)
}
// The block sits ahead of the zeroed bytes it runs into: it is read, then the region is jumped over.
want := "lost the subtitle block at 230872 ms (bytes "
if !strings.HasPrefix(lines[0], want) || !strings.HasSuffix(lines[0], "), which does not decode: VobSub: the control sequence at byte 2979 names byte 0 as the next one, which is not after it") {
t.Errorf("the block is announced as %q, want its time and the decoder's error", lines[0])
}
if !strings.HasPrefix(lines[1], "skipped a damaged region at bytes ") || strings.Contains(lines[1], "decode") {
t.Errorf("the region is announced as %q", lines[1])
}
}

// A .sup or a .idx/.sub pair beside the video is read as -format png without one, -t picking a .idx's language from
// 1; a unit that does not decode is named on stderr by its time and its error.
func TestCmdExtractSubtitle_BitmapFileBesideTheVideo(t *testing.T) {
dir := t.TempDir()
out := capture(t, func() {
commands.CmdExtractSubtitle([]string{"../../../internal/testdata/pgs_sub.sup", "-o", filepath.Join(dir, "sup")})
})
if !strings.Contains(out, "extracted 2 bitmap cue(s) from ../../../internal/testdata/pgs_sub.sup (stream 1)") {
t.Errorf("stdout = %q, want the two display sets of the .sup", out)
}
sub, err := os.ReadFile("../../../internal/testdata/vobsub.sub")
if err != nil {
t.Fatal(err)
}
idx, err := os.ReadFile("../../../internal/testdata/vobsub.idx")
if err != nil {
t.Fatal(err)
}
// The unit of the first entry, at 132499 ms, its control sequences placed inside its header.
unit := 14 + int(sub[13]&7) + 6 + 3 + int(sub[14+int(sub[13]&7)+8]) + 1
sub[unit+2], sub[unit+3] = 0, 2
for name, data := range map[string][]byte{"film.idx": idx, "film.sub": sub} {
if err := os.WriteFile(filepath.Join(dir, name), data, 0o644); err != nil {
t.Fatal(err)
}
}
errOut := stderrOf(t, func() {
out = capture(t, func() {
commands.CmdExtractSubtitle([]string{filepath.Join(dir, "film.sub"), "-t", "1", "-o", filepath.Join(dir, "vob"), "-format", "png"})
})
})
if !strings.Contains(out, "extracted 42 bitmap cue(s)") {
t.Errorf("stdout = %q, want 42 cues", out)
}
if want := "lost the subtitle at 132499 ms, which does not decode: VobSub: the subpicture places its control sequences at byte 2"; !strings.HasPrefix(strings.TrimSpace(errOut), want) {
t.Errorf("stderr = %q, want it to start with %q", errOut, want)
}
blob, err := os.ReadFile(filepath.Join(dir, "vob", "cues.json"))
if err != nil || !strings.Contains(string(blob), `"start_ms": 147355`) {
t.Errorf("the manifest does not hold the second cue: %v", err)
}
}
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|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)]",
"extract-subtitle": "mkvgo extract-subtitle <file.mkv|.mp4|.sup|.idx|.sub> -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; a .sup or a .idx/.sub pair beside the video is read as png, -t picking a .idx's language from 1)] [-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
8 changes: 5 additions & 3 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -439,10 +439,10 @@ mkvgo remove-attachment video.mkv -o out.mkv 2

### extract-subtitle

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.
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. A bitmap subtitle file that sits beside the video - a PGS `.sup`, or a VobSub pair named by its `.idx` or its `.sub` - is written the same way, `-format png` being its only format and its default; `-t` picks the language of a `.idx` by its position in it, from 1 (default 1).

```
mkvgo extract-subtitle <file.mkv|.mp4> -t <trackID> -o <out> [-format srt|ass|vtt|png|pgs] [-index <index.mkvsix>] [--damage-bytes <n>]
mkvgo extract-subtitle <file.mkv|.mp4|.sup|.idx|.sub> -t <trackID> -o <out> [-format srt|ass|vtt|png|pgs] [-index <index.mkvsix>] [--damage-bytes <n>]
```

| Flag | Description |
Expand All @@ -451,7 +451,7 @@ mkvgo extract-subtitle <file.mkv|.mp4> -t <trackID> -o <out> [-format srt|ass|vt
| `-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 |
| `--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 `png` and `pgs`, a block that reads but does not decode is lost too, and named on stderr by its time and its decoding error (`lost the subtitle block at <ms> ms (bytes <from> to <to>), which does not decode: <error>`; for a file beside the video, `lost the subtitle at <ms> ms, which does not decode: <error>`). With `--exit-damaged`, an extraction that passed over a region exits 3. `-1` refuses any damage. Default 64 MiB |

```bash
mkvgo extract-subtitle video.mkv -t 3 -o subs.srt
Expand All @@ -461,6 +461,8 @@ 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
mkvgo extract-subtitle dvdrip.idx -t 2 -o subs/ # the second language of a .idx/.sub pair
mkvgo extract-subtitle movie.sup -o subs/
```

### subtitle-index
Expand Down
Loading
Loading