libfreemkv/docs/pgs.md

HDMV PGS subtitle parser (src/mux/codec/pgs.rs)

Module overview: why display sets need a synthesized duration

For Matroska output the parser collapses a display PCS / clear PCS pair into one block with BlockDuration set to clear_pts - display_pts. Without a duration, hardware players linger on the last bitmap until the next subtitle replaces it — which can be many seconds, and on a disc where the final subtitle has no follower, until end of file.

display_set_is_forced

The mux uses this to detect a forced-narrative track (every displayed subtitle forced) without relying on the disc's vendor label metadata, so forced subs are flagged FlagForced even on discs that carry no such blob.

demotable

Full rationale and measured track shapes:

• Promotion (0 → 1) needs no gate: it rests on positive evidence (every display set carried forced_on_flag). Demotion rests on an ABSENCE, and an absence is only meaningful if the flag is in use at all. Measured: discs exist on which NO track carries forced_on_flag; there, "this track has no forced display sets" is a fact about the authoring house, not about the track, and demoting on it would strip a correct forced label from every track on the disc.
• DEMOTE_MIN_DISPLAY_SETS: a track must have shown at least this many display sets before "none of them was forced" is allowed to contradict a vendor forced label. Absence is weak evidence on a handful of sets: a genuine forced-narrative track is SMALL (measured shape: tens of display sets for a whole feature), so a couple of unflagged sets is exactly what one looks like on a disc whose authoring never sets the flag.
• DEMOTE_MIN_DISPLAY_SHARE_DIVISOR: the track must also carry at least this fraction (1/N) of the display sets of the busiest subtitle track on the disc. Measured: a dedicated forced track carries a low-tens count of display sets for a whole feature, a full dialogue track carries one to two thousand — two orders of magnitude apart. A track sitting within a quarter of the busiest track's count is a full track, whatever its label says; a track at one percent of it is the forced-narrative track its label claims and must keep that label.
• A track that itself mixes forced and non-forced display sets is the stronger form of "flag in use": it shows the authoring house making that distinction deliberately. The shape test still applies to it — a SMALL track with a couple of flagged sets is a forced track whose authoring flagged some of its signs, and demoting it would be exactly the mistake the shape test exists to prevent.

See also docs/pgs-forced-probe.md for the info-time probe that reuses this same classifier.

Test notes

observed_stays_false_until_a_real_display_set_is_seen: observed() is the probe's "did I actually see any PGS content?" signal. When false the track's forced state is UNKNOWN and the probe leaves whatever flag the disc's own metadata supplied alone; when true, the probe overwrites that flag with its own verdict. A tracker that always claims to have observed something would let an unread or undecrypted subtitle track — where is_forced() is vacuously false — overwrite a correct vendor "forced" flag with "not forced".

a_mixed_track_corroborates_the_flag_itself: a track that itself mixes forced and non-forced display sets needs no corroboration from a sibling — the flag is demonstrably in use ON THIS TRACK. Models a busy track labelled forced that flags one or two of its hundred-odd display sets.

a_lone_segment_emitted_directly_still_carries_provenance: a lone non-PCS segment with a PTS is emitted straight through rather than accumulated, and it must still carry provenance. This path was missed on the first pass and showed up on a real disc as a subtitle track with no source offset — the one track out of forty that could not be placed by byte.