Aegisub/prs/prs_specs.txt

WARNING: THIS FILE IS HEAVILY OUTDATED!!!!!


Pre-Rendered Subtitles
----------------------

Specifications by Niels Martin Hansen
Modified and commented by Rodrigo Braz Monteiro


Introduction
------------

Pre-Rendered Subtitles (PRS) is a compact raster data format for subtitles
to be displayed into video files. It is designed to be simple, fast and small.

Compared to hardsubs, PRS has the following advantages:
- Most of the time, it is smaller (hardsubs often require 15 MB in a 24 minutes
  video clip, whereas PRS often requires as little as 3 MB).
- Can be disabled, for the viewers who preffer to watch the original content.
- You can have multiple tracks, for multi-language files.
- PRS subtitles are easier to replace, making the Quality Control process much
  faster.

Compared to softsubs, it has the following advantages:
- Decoding is much faster, which allows you to create every sort of advanced
  effects that can still be displayed in realtime.
- Decoding is much simpler, making it possible to port to a wide range of
  platforms.
- It is harder to "steal" the subtitles.
- Does not require the shipment of font files, which might be illegal.

Other advantages of the PRS format are:
- It allows effects that are not possible with any current subtitle format,
  such as different blending modes.
- It makes the task of hardsubbing a complex karaoke much faster.
- It ensures that the encoder will encode the subtitles exactly as the
  typesetter envisioned them.
- It allows conversion of video into subtitles, e.g. effects done in programs
  such as Adobe After Effects.


Overview
--------

PRS stores either full PNG images, partial PNG images (through a number of
blocks) or instructions to do simple modifications (translation, clearing)
to the current output.

PRS only uses 32 bit RGBA images.

The data format is binary, designed for integration into containers such as
Matroska.

PRS subtitle files can be generated by specialised software (rendering directly
to a PRS file or other container supporting PRS) or by a commandline program
taking a PRS definition file and a number of PNG images as input.
The PRS definition file is a text file describing the images to be displayed.

PRS subtitles are frame-based, that is, a PRS subtitle picture is linked to one
or more frame-numbers in the video.

All integers are 32 bit unsigned Little Endian unless otherwise specified.


PRS stand-alone file format
---------------------------

The file starts with a 32 bit magic number, formed by the ASCII string
"PRS".
The magic is followed by an integer specifying the length in bytes of the
subpicture stream name. The subpicture stream name follows immediately
after the length specifier, and is an UTF-8 encoded freeform string. (It may
contain embedded NUL characters, but this is discouraged. It is encouraged to
terminate the stream name with a NUL character.)

The header is followed by a number of image deifnitions and display commands.
Image definitions and display commands can be mixed in any way, as long as
no display command refers to an undefined image.
If an image identifier is defined twice, the later definition overrides any
earlier ones.

0x00	"PRS" (zero-terminated)
0x04	version number (32 bit unsigned)
0x08	stream name size (32 bit unsigned)
0x012	stream name string (this won't be writen if the size is 0)


Image Definition IMG

This defines an image data block. This image definition starts with the 32 bit
magic "IMG". This is followed by an integer image identifier, an integer
image byte size and the image data, encoded in the apropriate format.

0x00	"IMG" (zero-terminated)
0x04	block length (32 bit unsigned)
0x08	image identifier (32 bit unsigned)
0x0C	image format (32 bit unsigned; 1 = PNG, and the only supported format for now)
0x10	image data length (32 bit unsigned)
0x14	image data


Display Command DSP

This controls when and how images are displayed on the video.
Start and end frame numbers are both inclusive.

0x00	"DSP" (zero-terminated)
0x04	block length (32 bit unsigned)
0x08	start time in miliseconds (32 bit unsigned)
0x0C	end time in miliseconds (32 bit unsigned)
0x10	image identifier (32 bit unsigned)
0x1C	layer (16 bit signed)
0x14	x position (16 bit signed)
0x18	y position (16 bit signed)
0x1A	alpha multiplier (8 bit unsigned)
0x1B	blend mode (8 bit unsigned)

Alpha multiplier:
0x00 is "invisible", 0xFF is "fully visible". This value is multiplied onto
the alpha value of each pixel in the image to get the actual alpha value for
that pixel, that is: finalAlpha = pixelAlpha * globalAlpha / 255;

Blend modes:
  0	none (src*alpha + dest*(1-alpha))
  1	add (src*alpha + dest)
  2	subtract (dest - src*alpha);
  3	inverse subtract (src*alpha - dest) (is this it?)
  4	multiply (src*alpha * dst / 255)
Values are clipped before they are multiplied with alpha.

Layers:
If picture A's layer number is larger than picture B, picture A is displayed
on top of picture B. If two pictures have the same layer number, no order is
defined. (It's recommended to use the ordering of the display commands.)