---
title: "Extract PGS subtitles as PNG images in C#"
url: https://recursiveai.org/onemedia/cookbook/decode-bitmap-subtitles/
description: "Decode PGS bitmap subtitles to PNG images in C# with OneMedia. Keep cue times, positions and transparency with a tiny redistributable sample."
version: "1.0.2"
---

# Extract PGS subtitles as PNG images in C#

**OneMedia** is a free, open-source media library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneMedia) · [GitHub](https://github.com/recursive-ai-oss/onemedia-csharp) · [Docs](https://recursiveai.org/onemedia/docs/) · [Download example (.zip)](https://recursiveai.org/onemedia/cookbook/decode-bitmap-subtitles/decode-bitmap-subtitles.zip)

Decode PGS pictures to PNGs, not text. The zip’s `pgs.sup` holds two patterned images.

```shell
dotnet add package RecursiveAI.OneMedia
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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.

```text
Wrote 2 PNGs
```

Unzip [the example](https://recursiveai.org/onemedia/cookbook/decode-bitmap-subtitles/decode-bitmap-subtitles.zip), then `dotnet run`.

## Full program

```csharp
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}");
    }
}
```

```text
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

```csharp
using RecursiveAI.OneMedia.Captions;

var cues = BitmapSubtitles.ReadSup(
    File.ReadAllBytes("pgs.sup"),
    new BitmapSubtitleOptions { Matrix = YCbCrMatrix.Bt709 });
Console.WriteLine($"Cues: {cues.Cues.Count}");
```

```text
Cues: 1
```

## Related recipes

- [Extract text subtitles from MKV](https://recursiveai.org/onemedia/cookbook/extract-subtitles-from-mkv/)
- [List video tracks](https://recursiveai.org/onemedia/cookbook/list-video-tracks/)
- [Convert MKV to MP4](https://recursiveai.org/onemedia/cookbook/convert-mkv-to-mp4/)

---

## 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](https://recursiveai.org/onemedia/docs/bitmap-subtitles/), 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](https://recursiveai.org/onemedia/docs/bitmap-subtitles/#what-is-read) 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](https://recursiveai.org/onemedia/docs/bitmap-subtitles/#format-notes).
