mirror of
https://github.com/freemkv/libfreemkv.git
synced 2026-10-07 18:13:10 +00:00
Matthew Jackson
6e14fc0c0c
Security - Remove the unsafe Vec::set_len over recycled sector buffers — UB reachable from safe code (GHSA-j8ww-f5fg-9pmh, low). Uses Vec::resize; pooling unchanged. CI / tooling - clippy on stable with the MSRV single-sourced from Cargo.toml; cargo-deny dependency-audit gate with first-party git sources allowed (#15); audience-based comment-guard (#17). Docs - README (keydb ownership, BD-J parser count), drive-access transport/reset notes, mux timeline module-doc links.
72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
# 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.
|