libfreemkv/docs/tsmux.md

tsmux — BD Transport Stream muxer (src/mux/tsmux.rs)

PES frames in, 192-byte BD-TS (Blu-ray transport stream) packets out. Each PES frame is wrapped in a PES header, split into TS packets, and prepended with the 4-byte TP_extra_header.

TsMuxer framing rules

PIDs in 0x1011..=0x101F are treated as video (length-prefixed NALUs in, Annex B out, with parameter-set prepend and RAI on keyframes); every other PID is carried as private_stream_1 (0xBD) audio/subtitle. All tracks share one PTS origin seeded from the first video frame, so audio/video PTS offsets are preserved.

video_codec field

Decides BOTH how the ES is framed and how its codec_private parameter-set record is parsed. One fact, one field: carrying NAL-ness separately from the codec is what let a track be treated as NAL video while its avcC record was handed to the hvcC parser.

• HEVC / H.264 arrive length-prefixed (MKV/PES NALU convention) and need Annex-B conversion; their parameter sets live in an hvcC / avcC record respectively, and the two layouts are NOT interchangeable.
• MPEG-2 and VC-1 are already plain start-code ES; running length_prefixed_to_annex_b over them mangles the frame into empty/garbage output while frame_count still increments, so the mux "succeeds" and silently produces a video-less file.

Defaults to Codec::Hevc — the prior, only behaviour — so a caller that never calls TsMuxer::set_video_codec is unaffected. Ignored for non-video tracks.

build_pes_header — PTS on continuations

ISO/IEC 13818-1 §2.4.3.7 puts the PTS in the header of the PES packet that contains the FIRST byte of the access unit; repeating it on the continuations makes each of them look like a new access unit at the same timestamp, so a demuxer re-reading the stream splits one display set into two blocks with identical timestamps. pts_90k is None for a CONTINUATION PES packet (one carrying the rest of an access unit too large for a single bounded-length private_stream_1 PES).

Test rationale

non_nal_video_es_passes_through_unconverted

A non-NAL codec must pass the ES through byte-for-byte: MPEG-2 and VC-1 are not NAL-based, so their ES already IS the wire format and length_prefixed_to_annex_b would mangle it. The payload is deliberately length-prefix SHAPED (a big-endian length followed by that many bytes) so a wrongly-applied conversion rewrites the leading four bytes into a 00 00 00 01 start code, making the two paths produce visibly different bytes — a payload the converter happened to leave alone would let a mutant pass. Mutation: delete the set_video_codec call, or make Mpeg2 report as NAL, and the emitted ES gains a start code -> this fails.

split_access_unit_carries_pts_only_on_the_first_pes

An oversized private_stream_1 access unit is split across several PES packets, and every one of them used to carry the SAME PTS (PTS_DTS_flags = 0b10) even though only the first holds the start of the AU. On read-back a demuxer treats each PUSI as a new access unit, so e.g. the second half of a full-screen PGS display set arrived as an independent segment at an identical timestamp — the display set was emitted as TWO blocks with the same timestamp instead of one.

annex_b_conversion_buffer_is_reused_across_frames

MEASURED: the Annex-B conversion buffer must be REUSED across video frames, not allocated per frame. Both the allocation's address and its capacity are unchanged after the second and third same-sized frames — if the conversion allocated a fresh Vec per frame (the old Vec::with_capacity(data.len() + 1024)), the buffer left on the muxer would be empty with zero capacity, and each frame would pay an allocate/first-touch/free cycle over the whole ~310 KB frame.