Skip to content

feat(mux): export whole-PES tracks at their placement - #5832

Merged
kixelated merged 3 commits into
mainfrom
quest/m1/ts-reliability/pes-export
Oct 17, 2026
Merged

kixelated merged 3 commits into
mainfrom
quest/m1/ts-reliability/pes-export

Conversation

@kixelated

@kixelated kixelated commented Oct 17, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

The TS importer is moving private PES (teletext, DVB subtitles, DVB AC-3, KLV, unknown private types) to one whole PES packet per frame, timestamped with its placement on the program clock (#5718, decided in the ts-reliability epic). Export has to read that before the importer writes it, so main never publishes a catalog its exporter can't read. This completes quest/m1/ts-reliability/pes-export.md.

Approach

  • Catalog. A new optional pesPacket: { streamType } member on an mpegts.tracks entry, beside verbatim. Old exporters ignore the entry; they don't refuse the catalog.
  • Mux. The frame is packetized byte for byte on the track's PID. TS packets are laid out by hand, with adaptation-field stuffing, because the mpeg2ts writer rebuilds the PES header. The frame's timestamp is an arrival time, so it gets its own path, Schedule::push_placed:
    • The unit is released no earlier than the slot that reaches its placement.
    • At a multiplex rate, the PES's first byte waits for the first position at or past the placement, with its TS header just before it.
    • Unpadded, it waits for the first slot whose PCR is at or past the placement.
    • It has no send-ahead and never fails on a missed deadline.
  • Buffer model. On a PID the T-STD models, the decoder buffer reads the PTS from the header. For DVB AC-3, the model walks the sync frames and removes each one at its own decode time, without splitting the PES. Only each frame, not the whole PES, has to fit the buffer.
  • Tune-in. A placed PES is compared with the keyframe's departure through their jitter-buffer keys (release time plus delay), not through its PTS. Data placed beside the keyframe now survives.
  • Refusal. These fail the export:
    • a frame that isn't exactly one well-formed PES (start code, matching PES_packet_length, complete optional header where the stream_id has one; a zero length only on a video stream_id or on 0xFD with a video stream type such as VC-1);
    • an entry naming both verbatim and pesPacket;
    • a verbatim or pesPacket entry whose track is also a media rendition.
  • The draft is updated: Track type, the ignore rule, PesPacket in {{verbatim}}, {{rebuild}}, changelog -01.

Tests (export_test.rs, export.rs unit tests, catalog.rs):

  • byte-for-byte output for PTS 0 versus no PTS, distinct PTS and DTS, every optional field plus stuffing, data_alignment_indicator clear, private_stream_2 and padding, and sizes around one packet;
  • first-byte position, padded and unpadded (fails without the gate);
  • tune-in before, beside and after the keyframe, in the slot of its placement (fails under the PTS rule);
  • each refusal;
  • a multi-frame DVB AC-3 PES kept whole;
  • PES parser, PTS unwrap and AC-3 removal unit tests.

just check passes locally (3253 moq-mux/workspace tests).

Impact

  • moq_mux::container::ts::Track gains pes_packet: Option<PesPacket>; new export ts::PesPacket { stream_type } with PesPacket::new. Both are #[non_exhaustive].
  • Catalog wire: optional mpegts.tracks.*.pesPacket.streamType. Backwards compatible: older consumers ignore the entry, so they drop the track.
  • Behavior: export now refuses a verbatim entry that is also a media rendition (the draft already forbade it).
  • No JS change: nothing in js/ interprets the mpegts section.

Decisions

Settled by the maintainer:

  1. Missed deadlines on placed PES. A placed PES never fails the export for a missed decode deadline. It keeps only its placement and the decoder buffer's admission, because the source chose its timing and a multi-frame DVB AC-3 PES can legitimately finish after its first frame decodes. Per-frame deadlines can come later if strict T-STD grading needs them.
  2. Malformed frame. A frame that isn't one well-formed PES fails the whole export (fail loud). Malformed sections are still dropped with a warning today; making them fail the same way is a follow-up.
  3. Tune-in precision. The keyframe's departure is its release time, read from its jitter-buffer key, not its laid-out position. Under contention a PES can go out a few packets ahead of the keyframe's first packet, which is accepted.
  4. doc/lib/rs/moq-mux.md. Unchanged. Nothing a user does changes until the importer writes pesPacket, and pes-import owns those lines.

Alternatives

  • Reusing Track::push/Schedule::push_frames with a decode deadline at the placement. That sends the PES a slot early, as an unbounded PID's units go, and fails padded output on the deadline.
  • A framing value instead of a member. The epic rejected it: published exporters would refuse the whole catalog.

Follow-ups

  • pes-import: write pesPacket, delete Framing::Pes and the AC-3 repack. Now unblocked.
  • section-placement: sections can reuse Schedule::push_placed and the key-based tune-in rule.
  • Make malformed sections fail the export like malformed PES (decision 2).
  • Unpadded placement can land up to one 25 ms slot late, since unpadded slots don't time packets; a padded output places to the packet.

(written by Claude Opus 5.5)

🤖 Generated with Claude Code

@kixelated

Copy link
Copy Markdown
Collaborator Author

Quest outcome: implemented quest/m1/ts-reliability/pes-export.md and deleted the quest file and its references. Local just check and just drafts check pass. The new regression tests (placement position and tune-in) fail when the fix is disabled. Left as a draft for the four open decisions in the description: missed-deadline exemption, what a malformed frame fails, tune-in precision, and the doc line. None of them needs performance numbers.

(written by Claude Opus 5.5)

@kixelated
kixelated marked this pull request as ready for review October 17, 2026 03:24
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 17, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-17T03:26:48.043138Z 6f08019 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 1 minute.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 353becb4-ea0c-479e-9482-8df2edaa995f
📥 Commits

Reviewing files that changed from the base of the PR and between a1cec51 and 8ce97fa.

📒 Files selected for processing: 11
  • drafts/draft-lcurley-moq-mpegts.md
  • quest/m1/ts-reliability/README.md
  • quest/m1/ts-reliability/pes-export.md
  • quest/m1/ts-reliability/pes-import.md
  • quest/m1/ts-reliability/section-placement.md
  • rs/moq-mux/src/container/ts/catalog.rs
  • rs/moq-mux/src/container/ts/export.rs
  • rs/moq-mux/src/container/ts/export_test.rs
  • rs/moq-mux/src/container/ts/import.rs
  • rs/moq-mux/src/container/ts/mod.rs
  • rs/moq-mux/src/container/ts/schedule.rs
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6f0801934d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-mux/src/container/ts/export.rs Outdated
Comment on lines +2963 to +2965
let pts = (pts_dts & 0b10 != 0).then(|| {
let b = &fields[..5];
u64::from((b[0] >> 1) & 7) << 30

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reject malformed PES clock fields

Reject PTS/DTS fields whose 4-bit prefixes or mandatory marker bits are invalid. Currently any five bytes are decoded whenever PTS_DTS_flags announces a timestamp, so a frame with cleared marker bits or a PTS-only field lacking the 0010 prefix passes validation, is emitted unchanged, and may be rejected or mis-timed downstream despite the new format requiring consumers to refuse malformed PES packets. The DTS field in the 11 form needs the same validation.

AGENTS.md reference: AGENTS.md:L17-L18

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 2ccb457: each PTS/DTS field now needs its prefix ('0010' alone, '0011' with '0001' for the DTS) and all three marker bits, with unit tests for both fields.

(written by Claude Opus 5.5)

kixelated and others added 3 commits October 16, 2026 21:17
Add the `pesPacket` member to an `mpegts.tracks` entry: each frame is one
whole PES packet, written unchanged and sent no earlier than its
timestamp, the source's placement. Tune-in compares that placement with
the keyframe's departure rather than its PTS. A malformed frame, or an
entry naming both carriages or also described as a rendition, fails the
export.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated force-pushed the quest/m1/ts-reliability/pes-export branch from 2ccb457 to 8ce97fa Compare October 17, 2026 04:26
@kixelated

Copy link
Copy Markdown
Collaborator Author

Merge status: not merged yet. This needs a maintainer call.

TS validation isn't a required check. I recommend merging, and fixing the MP2 start hole as its own quest rather than rerunning until it goes green.

(written by Claude Opus 5.5)

@kixelated

Copy link
Copy Markdown
Collaborator Author

Root cause of the TS validation failure ("TS full multiplex at its own rate", one missing MP2 frame at the start of the capture), confirmed by the maintainer: the TS export subscribes at the live edge with a zero max_delay, so the relay skips burst groups before the export sees them. It is unrelated to this PR, which only adds the pesPacket path. #5854 fixes it. TS validation isn't a required check, so this goes ahead.

Summary: export reads pesPacket tracks and writes each frame unchanged, sent no earlier than its placement. Settled decisions:

  • Placed PES don't fail on missed deadlines.
  • A malformed PES fails the export; sections should match in a follow-up.
  • Tune-in compares jitter-buffer keys.
  • No doc change until the importer writes pesPacket.

Codex's clock-field finding is fixed.

(written by Claude Opus 5.5)

@kixelated
kixelated added this pull request to the merge queue Oct 17, 2026
Merged via the queue into main with commit 9c4514a Oct 17, 2026
9 of 11 checks passed
@kixelated
kixelated deleted the quest/m1/ts-reliability/pes-export branch October 17, 2026 08:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant