libpgs

A Rust library and CLI for extracting, encoding, and transforming PGS (Presentation Graphic Stream) subtitles from MKV and M2TS/TS containers.

Cue-based extraction

Most tools (ffmpeg, mkvextract) extract subtitle tracks by reading through the entire MKV file linearly — parsing every cluster and discarding the video/audio blocks they don't need. For a 40 GB Blu-ray remux where the PGS subtitle data is only a few megabytes, this means reading tens of gigabytes just to find the subtitle blocks.

libpgs takes a different approach for MKV files that contain a Cues index. It reads the Cues element to identify exactly which clusters hold subtitle data, then seeks directly to those locations — skipping everything else. It also uses CueRelativePosition for sub-cluster seeking when available, jumping straight to the relevant block within a cluster.

The result is that extraction I/O scales with the size of the subtitle data, not the size of the file. On a typical Blu-ray remux, libpgs reads less than 1% of the file — often under 0.1% — compared to the full file read required by conventional tools. This is especially noticeable on network-attached storage where seek latency matters, and for batch workflows that process many large files. You can verify the difference on your own files with libpgs bench.

When Cues are not present, libpgs falls back to a single-pass sequential scan.

Installation

Add to your project:

cargo add libpgs

Library usage

use libpgs::Extractor;

// Stream display sets one at a time
let extractor = Extractor::open("movie.mkv")?;
for result in extractor {
    let track_ds = result?;
    println!("Track {}: {} segments", track_ds.track_id, track_ds.display_set.segments.len());
}

// Extract only a specific time range (seeks directly, minimal I/O)
let extractor = Extractor::open("movie.mkv")?
    .with_time_range(Some(300_000.0), Some(600_000.0)); // 5:00 to 10:00
for result in extractor {
    let track_ds = result?;
    println!("Track {} @ {}ms", track_ds.track_id, track_ds.display_set.pts_ms);
}

// Or collect everything at once
let by_track = Extractor::open("movie.mkv")?.collect_by_track()?;
for track in &by_track {
    println!("{}: {} display sets", track.track.track_id, track.display_sets.len());
}

Encoding and round-trip

libpgs supports full round-trip workflows: extract display sets, modify them, and write the result back as a .sup file. You can also create PGS display sets from scratch.

use libpgs::pgs::*;

// Modify an extracted palette and write back
let mut extractor = Extractor::open("movie.mkv")?;
let track_ds = extractor.next().unwrap()?;
let mut ds = track_ds.display_set;

// Parse, modify, and update a palette segment in-place
for seg in &mut ds.segments {
    if let Some(mut pds) = seg.parse_pds() {
        for entry in &mut pds.entries {
            entry.luminance = entry.luminance.saturating_add(10); // brighten
        }
        seg.set_pds_payload(&pds);
    }
}
libpgs::write_sup_file(&[ds], "modified.sup".as_ref())?;

// Or build a display set from scratch
let ds = DisplaySetBuilder::new(90_000) // PTS in 90kHz ticks
    .pcs(PcsData {
        video_width: 1920,
        video_height: 1080,
        composition_number: 0,
        composition_state: CompositionState::EpochStart,
        palette_only: false,
        palette_id: 0,
        objects: vec![CompositionObject {
            object_id: 0, window_id: 0, x: 100, y: 900, crop: None,
        }],
    })
    .wds(WdsData {
        windows: vec![WindowDefinition { id: 0, x: 100, y: 900, width: 200, height: 30 }],
    })
    .palette(PdsData {
        id: 0, version: 0,
        entries: vec![
            PaletteEntry { id: 0, luminance: 16, cr: 128, cb: 128, alpha: 0 },
            PaletteEntry { id: 1, luminance: 235, cr: 128, cb: 128, alpha: 255 },
        ],
    })
    .object(ObjectBitmap {
        id: 0, version: 0, width: 200, height: 30,
        pixels: vec![1u8; 200 * 30], // palette index per pixel, row-major
    })
    .build()?;
libpgs::write_sup_file(&[ds], "output.sup".as_ref())?;

The DisplaySetBuilder handles RLE encoding automatically and fragments large bitmaps across multiple ODS segments as required by the PGS spec.

CLI

libpgs tracks <file>                                                        # List PGS tracks
libpgs extract <file> -o <out> [-t <id>] [--start T] [--end T]              # Extract to .sup
libpgs stream <file> [-t <id>] [--raw-payloads] [--start T] [--end T]       # Stream NDJSON to stdout
libpgs encode -o <output.sup>                                               # Encode NDJSON stdin to .sup
libpgs bench <file>                                                         # Benchmark I/O efficiency

Time-range filtering

Both extract and stream accept --start and --end timestamps to limit extraction to a specific time window:

libpgs extract movie.mkv -o out.sup --start 0:05:00          # From 5 minutes to end
libpgs stream movie.mkv --start 0:05:00 --end 0:10:00        # 5-minute window only

Timestamps accept HH:MM:SS.ms, MM:SS.ms, SS.ms, or plain seconds. When a time range is specified, libpgs seeks directly to the target byte offset — it does not read and discard data before the start point. For MKV files with a Cues index, seeking is exact. For M2TS files, seeking uses binary search refinement to converge on the correct position despite variable bitrate. SUP files use simple bitrate estimation.

If no display sets fall within the requested range, libpgs reports zero results with no error.

Streaming to external scripts

The stream command outputs newline-delimited JSON (NDJSON) to stdout, allowing any language to consume PGS data incrementally via a subprocess pipe. Display sets are flushed as soon as they are extracted — no temp files or waiting for the full file to be processed.

The first line is a track discovery message with all available metadata:

{"type":"tracks","tracks":[{"track_id":3,"language":"en","container":"Matroska","name":"English Subtitles","is_default":true,"is_forced":false,"display_set_count":1234,"indexed":true}]}

Each subsequent line is a display set with fully parsed segment data organized into semantic sections — composition, windows, palettes, and objects:

{"type":"display_set","track_id":3,"index":0,"pts":311580,"pts_ms":3462.0000,"composition":{"number":1,"state":"epoch_start","video_width":1920,"video_height":1080,"palette_only":false,"palette_id":0,"objects":[{"object_id":0,"window_id":0,"x":773,"y":108,"crop":null}]},"windows":[{"id":0,"x":773,"y":108,"width":377,"height":43}],"palettes":[{"id":0,"version":0,"entries":[{"id":0,"luminance":16,"cr":128,"cb":128,"alpha":0}]}],"objects":[{"id":0,"version":0,"sequence":"complete","data_length":8635,"width":377,"height":43,"bitmap":"<base64>"}]}

The index field is a 0-based per-track sequence number. Combined with display_set_count from the tracks header, consumers can calculate extraction progress. Pass --raw-payloads to include base64-encoded raw segment bytes alongside the parsed data.

See docs/NDJSON.md for the complete schema reference, field tables, cross-reference diagram, and usage examples.

Example Python consumer:

import subprocess
import json

proc = subprocess.Popen(
    ["libpgs", "stream", "movie.mkv", "--start", "0:05:00", "--end", "0:10:00"],
    stdout=subprocess.PIPE,
    text=True,
)

tracks = {}
for line in proc.stdout:
    msg = json.loads(line)
    if msg["type"] == "tracks":
        for t in msg["tracks"]:
            tracks[t["track_id"]] = t
            print(f"Track {t['track_id']}: {t.get('name') or t.get('language', '?')}"
                  f" ({'default' if t.get('is_default') else 'non-default'})")
    elif msg["type"] == "display_set":
        tid = msg["track_id"]
        total = tracks[tid].get("display_set_count")
        progress = f" ({msg['index']+1}/{total})" if total else ""
        comp = msg.get("composition") or {}
        n_objects = len(msg.get("objects", []))
        print(f"Track {tid} @ {msg['pts_ms']:.1f}ms — "
              f"{comp.get('state', '?')} {n_objects} objects{progress}")

Encoding from NDJSON

The encode command reads the same NDJSON format that stream produces, enabling full round-trip workflows:

# Extract, modify with an external script, and re-encode
libpgs stream movie.mkv | python modify.py | libpgs encode -o modified.sup

# Or pipe stream directly back to encode (identity round-trip)
libpgs stream movie.mkv | libpgs encode -o roundtrip.sup

The encode command reads from stdin and writes a .sup file. It accepts the pts field (90kHz integer ticks) as the primary timestamp; if absent, it falls back to pts_ms * 90. Track metadata lines ({"type":"tracks",...}) are silently skipped. If the input contains multiple track_id values, encode splits the output into separate files (<stem>_track<id>.sup).

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.