Decode PGS pictures to PNGs, not text. The zip’s pgs.sup holds two patterned images.
dotnet add package RecursiveAI.OneMediaRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneMedia.Captions; var cues = BitmapSubtitles.ReadSup( File.ReadAllBytes("pgs.sup")); int index = 0; foreach (var cue in cues.Cues) foreach (var image in cue.Images) File.WriteAllBytes($"cue-{++index}.png", SubtitleImagePng.Encode(image)); Console.WriteLine($"Wrote {index} PNGs");
Writes cue-1.png and cue-2.png with straight-alpha RGBA pixels.
Wrote 2 PNGsUnzip the example, then dotnet run.
Full program
using RecursiveAI.OneMedia.Captions; var cues = BitmapSubtitles.ReadSup(File.ReadAllBytes("pgs.sup")); int count = 0; foreach (var cue in cues.Cues) { foreach (var image in cue.Images) { string name = $"cue-{++count}.png"; File.WriteAllBytes(name, SubtitleImagePng.Encode(image)); int transparent = 0; for (int y = 0; y < image.Height; y++) for (int x = 0; x < image.Width; x++) if (image.Pixels[y * image.Stride + x * 4 + 3] == 0) transparent++; Console.WriteLine($"{name}: {image.Width}x{image.Height} at {image.X},{image.Y}"); Console.WriteLine($"Time: {cue.Start} to {cue.End}; transparent pixels: {transparent}"); } }
cue-1.png: 64x12 at 20,400 Time: 90000/90000 to 270000/90000; transparent pixels: 357 cue-2.png: 30x6 at 30,40 Time: 90000/90000 to 270000/90000; transparent pixels: 109
Malformed subtitle data produces typed defects where recovery is possible; exceeding allocation limits throws MediaLimitExceededException.
Variations
Override the palette conversion matrix
using RecursiveAI.OneMedia.Captions; var cues = BitmapSubtitles.ReadSup( File.ReadAllBytes("pgs.sup"), new BitmapSubtitleOptions { Matrix = YCbCrMatrix.Bt709 }); Console.WriteLine($"Cues: {cues.Cues.Count}");
Cues: 1Related recipes
The short answer
Read SUP bytes with BitmapSubtitles.ReadSup, iterate SubtitleDocument.Cues, and encode each item in cue.Images with SubtitleImagePng.Encode. The result is a PNG for each composed subtitle object, not recognized text. Keep the cue’s start and end times and the image’s X and Y position if you need to place it back onto a video canvas.
The supplied pgs.sup is a crafted test stream from the library’s MIT-licensed repository, not a subtitle ripped from a film. It shows two patterned objects in one display change, then clears them. The full program saves both and counts fully transparent pixels.
What is the difference between PGS and SRT subtitle files?
In OneMedia’s bitmap-subtitle model, PGS contains run-length-encoded pictures and palette entries. Decoding those instructions produces pixels. Text-subtitle workflows use strings instead. Choosing a PNG filename does not turn a picture into editable words.
One cue can contain more than one image. In the sample, both images share the interval from 1 to 3 seconds, but one sits at (20, 400) and the other at (30, 40). Their dimensions are 64×12 and 30×6. Save all images from each cue rather than assuming there is exactly one picture per timestamp.
The coordinates refer to the subtitle display canvas, not to the small image’s own origin. For this fixture the display is 720×480. The cropped second object has its own dimensions; neither PNG is a full video-sized frame. OneMedia does not scale the pictures or render them onto video.
How can I convert PGS subtitles to SRT files?
OneMedia does not perform OCR, so it cannot convert these bitmap cues into recognized subtitle strings. It can supply PNGs, times and positions to a separate recognition step. This recipe stops at that image boundary; the PNGs are the result you can inspect or pass to another tool.
Keep the timing attached to the cue rather than deriving it from numbered PNG filenames. A cue’s End normally comes from the next display change or clear command. Depending on the source, it can instead come from a container block duration or remain MediaTime.Unknown. Do not invent an end time from the PNG, which contains no cue timeline.
A PGS composition can also change only its palette while reusing earlier objects. That is another display change, not necessarily a newly encoded picture. The decoder exposes the resulting cues so that consumers can handle those updates without reading PGS segment instructions themselves.
How do I extract bitmap subtitles from an MKV file?
For a container track, use the documented BitmapSubtitles.ReadTrack(file, track) entry point with a supported bitmap-subtitle track. The entry-point table covers Matroska PGS, VobSub and DVB subtitle tracks, as well as the supported transport-stream paths. The PNG encoding loop is the same once you have the cue document. For standalone PGS, the byte-based SUP example above avoids needing a video file at all.
Preserve straight alpha when consuming the RGBA pixels. Each pixel has 8-bit red, green, blue and alpha components. A fully transparent pixel can still have nonzero color components; ignore its color when alpha is zero rather than treating it as an opaque background.
The variation overrides the YCbCr-to-RGB conversion matrix. By default PGS uses BT.709 for displays taller than 576 lines and BT.601 otherwise. DVD subtitles use the RGB palette from the index when available; an absent palette falls back to a gray ramp. Damaged run-length data is reported as typed defects, and allocation limits can stop decoding. These behaviors are described in the format notes.