Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
ff10772
feat(subtitle): VobSub and DVB subtitle decoders, returning the PGS d…
gravity-zero Nov 16, 2026
7f62f6e
docs(library): the VobSub and DVB bitmap subtitle decoders
gravity-zero Nov 16, 2026
1a8dbe4
docs(changelog): the VobSub and DVB subtitle decoders under Unreleased
gravity-zero Nov 16, 2026
f835299
feat(subtitle): readers for the bitmap subtitles beside a video, a Vo…
gravity-zero Nov 16, 2026
4bafbaa
docs(library): the .idx/.sub and .sup readers
gravity-zero Nov 16, 2026
5010649
docs(changelog): the .idx/.sub and .sup readers under Unreleased
gravity-zero Nov 16, 2026
2ffd34e
style(subtitle): tagged switches where the bitmap decoders compared o…
gravity-zero Nov 16, 2026
414df0c
fix(subtitle): the DVB decoder reads a region once per display set, k…
gravity-zero Nov 16, 2026
fc67ed1
fix(subtitle): a whole VobSub unit never completes an incomplete one,…
gravity-zero Nov 16, 2026
78c4f45
fix(subtitle): the .sub reader takes the last bytes a ReaderAt return…
gravity-zero Nov 16, 2026
6e5fee6
docs(library): the time of a VobSub unit over several blocks, the DVB…
gravity-zero Nov 16, 2026
c566d15
docs(changelog): PGSDisplaySet.Timeout under Unreleased
gravity-zero Nov 16, 2026
f2f376e
fix(subtitle): VobSubDecoder.Continues tells ahead of Decode whether …
gravity-zero Nov 17, 2026
da90230
docs(subtitle): a DVB region placed several times shares its image, a…
gravity-zero Nov 17, 2026
873f8c0
docs(changelog): 0.67.0 dated 2026-11-17, 0.66.2 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
45 changes: 15 additions & 30 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,35 +9,20 @@ its series' file in [changelog/](changelog/) when a newer one ships.

## [Unreleased]

## [0.66.2] - 2026-11-10
## [0.67.0] - 2026-11-17

### Security
### Added

- `serve`, `PlanHLS`: a Matroska whose Segment declares more bytes than the
file holds (a forged size, a file cut short) no longer has a subtitle
request ask the kernel to read ahead over the declared size, one call per
chunk, with the rendition locked meanwhile (since 0.66.0).
- `edit-inplace`: a Tags, Chapters or Attachments element after the clusters
that declares more bytes than the file holds is voided up to the end of the
file; the edit wrote its declared size, from one allocation of that size.
- `demux`: an empty ALAC packet is refused by name (`--raw` keeps the stored
payloads); a few bytes of laced empty packets held 2 KiB of packet table
each (since 0.66.0).

### Fixed

- `edit-inplace`: a second edit of a file whose Info or Tracks an earlier
edit had moved to the end of the Segment replaces them. It appended a
second copy behind the first, which a full read kept returning: the edit
reported success and was not seen (since 0.66.0). A file edited twice by
0.66.0 or 0.66.1 is repaired by `mkvgo edit` (full rewrite).
- `to-hls`, `serve` and the other HLS commands: an encrypted text subtitle
track is refused by name, or dropped with its reason under
`--skip-unsupported`, as `to-mp4` does; since 0.66.0 it was listed as a
WebVTT rendition built from its undecrypted bytes.
- `serve` on a remote source with a subtitle index: the scan asks for each
block it reads again, not for the whole minute of media ahead in one request
(since 0.66.0).
- Every command names `--strict`, `--skip-unsupported`, `--synthesize-index`
and `--no-iframes` in its refusals; all but `demux`, `to-mp4`, `from-mp4`
and `to-hls` printed the library's `Options` field names.
- `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.
33 changes: 33 additions & 0 deletions changelog/0.60-0.69.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,39 @@

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.66.2] - 2026-11-10

### Security

- `serve`, `PlanHLS`: a Matroska whose Segment declares more bytes than the
file holds (a forged size, a file cut short) no longer has a subtitle
request ask the kernel to read ahead over the declared size, one call per
chunk, with the rendition locked meanwhile (since 0.66.0).
- `edit-inplace`: a Tags, Chapters or Attachments element after the clusters
that declares more bytes than the file holds is voided up to the end of the
file; the edit wrote its declared size, from one allocation of that size.
- `demux`: an empty ALAC packet is refused by name (`--raw` keeps the stored
payloads); a few bytes of laced empty packets held 2 KiB of packet table
each (since 0.66.0).

### Fixed

- `edit-inplace`: a second edit of a file whose Info or Tracks an earlier
edit had moved to the end of the Segment replaces them. It appended a
second copy behind the first, which a full read kept returning: the edit
reported success and was not seen (since 0.66.0). A file edited twice by
0.66.0 or 0.66.1 is repaired by `mkvgo edit` (full rewrite).
- `to-hls`, `serve` and the other HLS commands: an encrypted text subtitle
track is refused by name, or dropped with its reason under
`--skip-unsupported`, as `to-mp4` does; since 0.66.0 it was listed as a
WebVTT rendition built from its undecrypted bytes.
- `serve` on a remote source with a subtitle index: the scan asks for each
block it reads again, not for the whole minute of media ahead in one request
(since 0.66.0).
- Every command names `--strict`, `--skip-unsupported`, `--synthesize-index`
and `--no-iframes` in its refusals; all but `demux`, `to-mp4`, `from-mp4`
and `to-hls` printed the library's `Options` field names.

## [0.66.1] - 2026-11-08

### Fixed
Expand Down
112 changes: 111 additions & 1 deletion docs/library.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ task-first starting point (CLI and Go side by side).
| `mkv/reader` | `github.com/gravity-zero/mkvgo/mkv/reader` | Parse MKV files into `Container` |
| `mkv/writer` | `github.com/gravity-zero/mkvgo/mkv/writer` | Write `Container` to MKV bytes |
| `mkv/ops` | `github.com/gravity-zero/mkvgo/mkv/ops` | High-level operations |
| `mkv/subtitle` | `github.com/gravity-zero/mkvgo/mkv/subtitle` | SRT/ASS parsing |
| `mkv/subtitle` | `github.com/gravity-zero/mkvgo/mkv/subtitle` | SRT/ASS parsing, PGS/VobSub/DVB bitmap decoding |
| `matroska` | `github.com/gravity-zero/mkvgo/matroska` | Facade -- re-exports everything |
| `ebml` | `github.com/gravity-zero/mkvgo/ebml` | Low-level EBML codec |

Expand Down Expand Up @@ -1909,6 +1909,116 @@ 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.

### 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
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
in straight-alpha `*image.NRGBA`, each with its position on the subtitle
plane (`ScreenW`/`ScreenH`), and a set with no object where the screen clears.

```go
// VobSub: a unit is one block, or several when a muxer cut it; it is dated by the block that starts it.
dec, err := subtitle.NewVobSubDecoder(track.CodecPrivate)
var unitTime int64
for each block of the track {
data, err := track.DecodePayload(block.Data) // a track stored compressed
if !dec.Continues(data) {
unitTime = block.Timecode
}
sets, err := dec.Decode(data)
for _, ds := range sets {
start := unitTime + ds.Delay.Milliseconds()
// ds.Objects: X, Y, Forced, Image; none = the screen clears at start
}
}

// DVB: a block is a display set, shown at the block's time.
dvb := subtitle.NewDVBSubDecoder(track.CodecPrivate)
for each block of the track {
data, err := track.DecodePayload(block.Data)
sets, err := dvb.Decode(data)
for _, ds := range sets {
// ds.Objects at block.Timecode; none = the screen clears
}
}
```

What differs from PGS:

- **VobSub** reads its 16 colours and its plane size from the CodecPrivate (the
header of a `.idx` file); a track without them is refused, its pictures
having no colours. A block is one subpicture unit and gives one set, which
carries its own timing: `Delay` before the picture shows and `Duration`
until its stop command, zero when the unit has none (the block's duration or
the next block then ends it). `Forced` is the unit's forced-display command.
A unit a muxer spread over several blocks comes out with the block that
completes it, and its time is the first block's: `Continues`, asked ahead
of each `Decode`, tells whether the block is the rest of a unit or starts
one. A block that is a whole unit of its own never completes the one before,
which is dropped, and so starts one. A stop at
the date of the start gives an empty set. Colour and contrast changes
within a picture (command `0x07`) are not applied.
- **DVB** keeps regions, their pixels and the colour tables between blocks: a
display set sends only what changed, until a page composition declares a
mode change or an acquisition point. A set's objects are the regions on
screen, one picture each; a region the page places several times is read
once, its placements sharing the picture. The CodecPrivate names the
service's composition and ancillary pages, the segments of other pages being
ignored; with one too short to name them every page is decoded. 2, 4 and
8-bit pixels, map tables, the default colour tables and the display
definition (plane size, window) are read; character objects are not drawn.
`Forced`, `Delay` and `Duration` are never set: a set ends where the next
one begins. `Timeout` is the page's time-out, whole seconds after which a
set nothing replaced leaves the screen: a bound, not a duration.
- Both cut each picture down to its visible pixels, `X`, `Y` moving with the
cut, and leave a picture with no visible pixel out of its set: a region that
was only erased reads as a clear.

Both bound what a block can cost, as the PGS decoder does: a picture or a
region is at most 4096 pixels a side, a DVB block fills and draws at most four
such planes, an epoch's regions hold at most 16 MiB; past a bound, as on any
malformed block, `Decode` returns an error and the next block is decoded
normally. A DVB block refused part-way returns, with the error, the sets it
completed ahead of it and the one it was composing; bytes that are no segment,
or a pixel-data block of an undefined type, end what they are in without an
error.

### Bitmap subtitles beside the video: .idx/.sub and .sup

The same pictures also travel as files of their own: VobSub as a `.idx` and
a `.sub`, PGS as a `.sup`. Two readers turn them into what the decoders take,
one unit or display set at a time, so a whole file is never held.

```go
ix, err := subtitle.ParseVobSubIndex(idxFile) // the .idx: header, languages, times
dec, err := subtitle.NewVobSubDecoder(ix.Header)
err = ix.ForEachUnit(subFile, 0, func(timeMs int64, unit []byte) error {
sets, err := dec.Decode(unit) // as for a Matroska block
return err
})

pgs := subtitle.NewPGSDecoder()
err = subtitle.ForEachSUPDisplaySet(supFile, func(timeMs int64, set []byte) error {
sets, err := pgs.Decode(set)
return err
})
```

`VobSubIndex.Streams` lists the languages of the pair (`Language`, `Name`,
`Index`) and, for each, the time and the position of every subpicture, the
`delay:` and `time offset:` lines applied. `ForEachUnit` reads the `.sub` (an
MPEG-2 program stream, through an `io.ReaderAt`) and gathers each unit from
the packets of its language; an index entry that points into the unit before
it, or at the end of the `.sub`, is passed over, and a unit the `.sub` holds
only in part is an error. `ForEachSUPDisplaySet` gives each display set at the
presentation time of its composition segment; a file cut inside a segment gives
the sets ahead of it, then an error, and one that ends between two segments
gives its last set as it stands.

---

## Editing MP4/MOV natively
Expand Down
Binary file added internal/testdata/dvbsub.mkv
Binary file not shown.
Binary file added internal/testdata/dvbsub_set13.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added internal/testdata/pgs_sub.sup
Binary file not shown.
Binary file added internal/testdata/pgs_sub_set0.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
62 changes: 62 additions & 0 deletions internal/testdata/vobsub.idx
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# VobSub index file, v7 (do not modify this line!)
#
# Generated by MPlayer dev-SVN-r25315
# See <URL:http://www.mplayerhq.hu/> for more information about MPlayer
# See <URL:http://vobsub.edensrising.com/> for more information about Vobsub
#
size: 720x480
palette: 0d00ee, ee450d, 101010, ebebeb, 0ce60b, ec14ed, ebff0b, 0d637e, a1a1a1, c5c5c5, 0e640c, 89db89, 0e0089, a2bdd4, ebcf0b, 7e127e
# ON: displays only forced subtitles, OFF: shows everything
forced subs: OFF

# Language index in use
langidx: 0

id: en, index: 0
timestamp: 00:02:12:499, filepos: 000000000
timestamp: 00:02:27:355, filepos: 000001000
timestamp: 00:03:00:797, filepos: 000002000
timestamp: 00:03:03:433, filepos: 000003000
timestamp: 00:03:05:919, filepos: 000004800
timestamp: 00:03:05:910, filepos: 000005000
timestamp: 00:03:08:663, filepos: 000005800
timestamp: 00:03:10:014, filepos: 000006800
timestamp: 00:03:19:724, filepos: 000007800
timestamp: 00:03:21:175, filepos: 000008800
timestamp: 00:03:22:819, filepos: 000009000
timestamp: 00:03:24:762, filepos: 00000a000
timestamp: 00:03:26:806, filepos: 00000b000
timestamp: 00:03:28:716, filepos: 00000c000
timestamp: 00:03:30:051, filepos: 00000d000
timestamp: 00:03:31:644, filepos: 00000e000
timestamp: 00:03:34:380, filepos: 00000f800
timestamp: 00:03:37:225, filepos: 000011000
timestamp: 00:03:39:652, filepos: 000012000
timestamp: 00:03:43:531, filepos: 000012800
timestamp: 00:03:47:510, filepos: 000013800
timestamp: 00:03:50:872, filepos: 000015000
timestamp: 00:03:53:124, filepos: 000016000
timestamp: 00:03:57:303, filepos: 000017800
timestamp: 00:04:00:106, filepos: 000019000
timestamp: 00:04:33:556, filepos: 00001a000
timestamp: 00:04:55:445, filepos: 00001b000
timestamp: 00:05:00:049, filepos: 00001b800
timestamp: 00:05:02:018, filepos: 00001c800
timestamp: 00:05:02:035, filepos: 00001d000
timestamp: 00:05:04:203, filepos: 00001d800
timestamp: 00:05:05:947, filepos: 00001e800
timestamp: 00:05:07:957, filepos: 00001f800
timestamp: 00:05:21:295, filepos: 000020800
timestamp: 00:05:23:356, filepos: 000021800
timestamp: 00:05:24:640, filepos: 000022800
timestamp: 00:05:27:193, filepos: 000023800
timestamp: 00:05:28:369, filepos: 000024800
timestamp: 00:05:28:361, filepos: 000025000
timestamp: 00:05:29:946, filepos: 000025800
timestamp: 00:05:31:230, filepos: 000026000
timestamp: 00:05:32:924, filepos: 000027000
timestamp: 00:05:42:600, filepos: 000028000
timestamp: 00:05:46:771, filepos: 000028800
timestamp: 00:05:57:640, filepos: 000029800
timestamp: 00:05:59:834, filepos: 00002a800
timestamp: 00:06:05:248, filepos: 00002b800
Binary file added internal/testdata/vobsub.mkv
Binary file not shown.
Binary file added internal/testdata/vobsub.sub
Binary file not shown.
Binary file added internal/testdata/vobsub_cue0.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
60 changes: 60 additions & 0 deletions mkv/subtitle/bitmap.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
package subtitle

// bitmap.go - what the bitmap subtitle decoders (PGS, VobSub, DVB) hand back: pictures and where they sit on the
// subtitle plane, in one shape whatever the codec.

import "image"

// BitmapDisplaySet is one decoded display set of any bitmap subtitle codec: the type PGSDisplaySet names, which the
// VobSub and DVB decoders return as well.
type BitmapDisplaySet = PGSDisplaySet

// BitmapObject is one picture of a BitmapDisplaySet: the type PGSObject names.
type BitmapObject = PGSObject

// trimTransparent cuts a picture down to the rectangle its visible pixels cover, and says where that rectangle
// starts in the original; nil when no pixel is visible.
func trimTransparent(img *image.NRGBA) (*image.NRGBA, image.Point) {
w, h := img.Rect.Dx(), img.Rect.Dy()
rowVisible := func(y int) bool {
row := img.Pix[y*img.Stride : y*img.Stride+4*w]
for i := 3; i < len(row); i += 4 {
if row[i] != 0 {
return true
}
}
return false
}
top, bottom := 0, h
for top < h && !rowVisible(top) {
top++
}
if top == h {
return nil, image.Point{}
}
for !rowVisible(bottom - 1) {
bottom--
}
left, right := w, 0
for y := top; y < bottom; y++ {
row := img.Pix[y*img.Stride : y*img.Stride+4*w]
for x := 0; x < left; x++ {
if row[4*x+3] != 0 {
left = x
}
}
for x := w - 1; x >= right; x-- {
if row[4*x+3] != 0 {
right = x + 1
}
}
}
if top == 0 && left == 0 && bottom == h && right == w {
return img, image.Point{}
}
out := image.NewNRGBA(image.Rect(0, 0, right-left, bottom-top))
for y := top; y < bottom; y++ {
copy(out.Pix[(y-top)*out.Stride:(y-top+1)*out.Stride], img.Pix[y*img.Stride+4*left:])
}
return out, image.Pt(left, top)
}
Loading
Loading