Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .github/workflows/ts.yml
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,15 @@ jobs:
MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs
shell: bash -leo pipefail {0}

# KLV and DVB AC-3 the importer carries as whole PES: each PES comes back byte-equal
# outside its PTS and DTS, at its source placement, and the AC-3 passes the T-STD model.
- name: TS private PES
if: ${{ !cancelled() }}
run: nix develop --command just test ts --klv --strict
env:
MOQ_TEST_RUNS: ${{ runner.temp }}/moq-test-runs
shell: bash -leo pipefail {0}

# `import/export ts --passthrough`: from its first packet the capture is the source's
# packets in place, and every compliance check grades it as it grades that interval of
# the source. The generated clip fails the T-STD model on its own; the capture must too.
Expand Down
11 changes: 9 additions & 2 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,15 @@ taking the wrap that lands it nearest the clock, so media that gets more than
time) reads as a rewind.

MPEG-TS import carries H.264/H.265 and AAC/MP2/AC-3/E-AC-3, and passes SCTE-35
and subtitle PIDs through as tracks. SCTE-35 cues wait for a media timestamp;
input ending or declaring a clock break before that timestamp is refused.
and every other stream it does not decode (KLV, subtitles, DVB AC-3) through as
tracks. Each such PES goes through whole, at its place on the program clock
(PCR); one before the first PCR is dropped. A stream it cannot carry unaltered
is refused with a warning: any in a program with no PCR, and one whose PES carry
an ESCR, pack header or TREF, are scrambled, leave a non-video PES unbounded,
or have a malformed header.
SCTE-35 cues and private PES wait for a media timestamp; input ending or
declaring a clock break before that timestamp is refused, so a program of data
alone fails.
PES and untimed section staging share a bounded budget, so a source that never
supplies a PES boundary or clock fails rather than retaining bytes indefinitely.
It takes one program: a multi-program
Expand Down
4 changes: 2 additions & 2 deletions doc/lib/rs/moq-mux.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ back. This is what `moq import` / `export` and the gateways are built on.
| Format | Import | Export | Notes |
| --- | --- | --- | --- |
| fMP4 / CMAF | yes | yes | Audio/video passthrough as `cmaf` or repackaged as `legacy`; `wvtt` subtitles import as timed WebVTT text and `stpp` TTML (IMSC timing profile) as `ttml` documents on the broadcast clock, preserving source language and label when present; other subtitle codecs are skipped. |
| MPEG-TS | yes | yes | H.264/H.265; AAC, MP2, AC-3, E-AC-3, Opus up to 7.1; SCTE-35 and subtitle PIDs as tracks; service tables round-trip. |
| MPEG-TS | yes | yes | H.264/H.265; AAC, MP2, AC-3, E-AC-3, Opus up to 7.1; SCTE-35 sections and every other undecoded PES stream (KLV, subtitles, DVB AC-3) as tracks; service tables round-trip. |
| FLV / RTMP | yes | yes | Legacy H.264 + AAC + MP3, plus enhanced-RTMP HEVC, AV1, VP9, Opus, AC-3, E-AC-3, and multitrack. |
| Matroska / WebM | yes | yes | Timed SRT and WebVTT subtitles import as WebVTT text renditions, preserving source language and label when present; other subtitle codecs are skipped. |
| Annex-B (H.264, H.265) | yes | yes | Parameter sets extracted to the catalog or re-injected per keyframe. |
Expand All @@ -28,7 +28,7 @@ A `catalog::Timebase` gives renditions on one timestamp base one shared shift. A
timeline that rewinds ends the import. fMP4 export fixes its track
set at the init segment, so a new rendition or a changed configuration ends the
export. The [CLI page](/bin/cli#import) covers these and the MPEG-TS specifics:
one program per broadcast, damaged packets, and feed checks.
one program per broadcast, private PES, damaged packets, and feed checks.

Exporters take a catalog stream alongside the source. Choose its encoding and
rendition selection before exporting; the same stream shape drives every container.
Expand Down
2 changes: 1 addition & 1 deletion doc/setup/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ ignored; its guide says what replaces it.
These land with the next breaking release.

- **Data-track breaks are an object with no bytes** (#5815). A hang data
track (TS verbatim PES, sections, `m2ts`, text) marks a discontinuity with a
track (TS private PES, sections, `m2ts`, text) marks a discontinuity with a
group of one empty object instead of a skipped group. Older consumers fail
to decode it, so upgrade exporters and players before publishers.
- **Auth requests name `webtransport`** (#5293). Relays report a WebTransport
Expand Down
35 changes: 19 additions & 16 deletions drafts/draft-lcurley-moq-mpegts.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ What remains is media in a codec-neutral catalog, plus the signaling a demultipl
| | mpeg2ts packaging | mpegts section |
|:--------|:--------|:--------|
| MoQ track | one per program or multiplex | one per elementary stream |
| Object payload | whole source packets | one media frame, or one verbatim PES payload, PES packet, or section |
| Object payload | whole source packets | one media frame, PES packet, or section |
| Packaging | `mpeg2ts` | none defined; media keeps its own |
| Catalog | `mpeg2ts*` members on each track | one `mpegts` root member |
| Relay | caches and drops whole objects | drops and prioritizes per elementary stream |
Expand Down Expand Up @@ -222,44 +222,46 @@ Descriptors are never parsed, so a consumer MUST re-emit a list in order and MUS


# Verbatim Tracks {#verbatim}
An elementary stream the publisher does not decode rides its own MoQ track, byte-for-byte:
An elementary stream the publisher does not decode rides its own MoQ track, byte-for-byte.
A stream of sections is described by a `verbatim` record:

~~~
type Verbatim = {
"streamType": number,
"framing": "pes" | "section",
"streamId": number | undefined,
"framing": "section",
}
~~~

`streamType` is the PMT `stream_type` to re-announce: 0x86 for SCTE-35 {{scte35}}, 0x06 for private PES, 0x05 for private sections.
`streamType` is the PMT `stream_type` to re-announce: 0x86 for SCTE-35 {{scte35}}, 0x05 for private sections.

`framing` says how the payload is framed, defaulting to `"pes"`.
With `"pes"` each frame is one complete PES payload, timestamped with its PTS, or 0 if it carried none.
With `"section"` each frame is one complete section, header and CRC included, timestamped with the media time it arrived at.
A consumer MUST refuse a catalog that names a `framing` it does not recognize, rather than guess.

`streamId` is the original PES `stream_id`, for example 0xBD (`private_stream_1`) for teletext, DVB subtitles, and DVB AC-3.
It applies only to `"pes"` framing.
A publisher SHOULD record it, since strict demultiplexers reject a relabeled PES; a consumer with none falls back to `private_stream_1`.
`framing` is required, and `"section"` is its only value: each frame is one complete section, header and CRC included, timestamped with the media time it arrived at.
A consumer MUST refuse a catalog whose `verbatim` record names any other `framing` or none, rather than guess; in particular it MUST NOT read the `"pes"` framing of draft -00, or a record without `framing`, as sections.

Each frame MUST be a keyframe in its own group: a verbatim payload is all-or-nothing.

A track can instead carry each PES whole, header included:
A stream of PES packets is described by a `pesPacket` record, and carries each PES whole, header included:

~~~
type PesPacket = {
"streamType": number,
}
~~~

`streamType` is the PMT `stream_type` to re-announce, as for `Verbatim`.
`streamType` is the PMT `stream_type` to re-announce, as for `Verbatim`: 0x06 for private data such as asynchronous KLV, teletext, DVB subtitles and DVB AC-3, 0x15 for synchronous metadata.
Each frame MUST be exactly one PES packet, from its start code through its payload, with a `PES_packet_length` that matches the frame, or zero only where {{mpeg2}} lets a video stream leave it unbounded.
The `stream_id`, the PTS and DTS when present, and every other header field ride in the frame, with the PTS and DTS on the catalog clock; a PES without a PTS carries none.
The frame's timestamp is the packet's placement: the program clock at its first byte, on the same timeline.
Each frame MUST be a keyframe in its own group, as for `verbatim`.
A consumer MUST refuse a frame that is not one well-formed PES packet.
The record is a member beside `verbatim` rather than a `framing` value, so a consumer that predates it ignores the track instead of refusing the catalog.

A publisher demultiplexing a transport stream places each PES by the PCRs of its program ({{mpeg2}} Section 2.4.2.2): its first byte is interpolated between the reference bytes of the PCRs either side of it, and one past its timebase's last PCR is extrapolated from that timebase's last two.
A timebase ends at a PCR discontinuity, and at a PMT that moves the `PCR_PID`.
Each PCR takes the 2^33 multiple of its base that lands it nearest the media's PTS, and the placement moves onto the catalog clock by the same shift as the media, so a PES's timestamp depends only on the input and that shift.
A PES before the first PCR the publisher reads, or past a lone one, has nothing to place it and is dropped.
The publisher moves each PTS and DTS by the media's shift modulo 2^33, keeping their prefix and marker bits, and leaves every other byte as received; the PES CRC covers the previous packet's data bytes, not its header, so it stays valid.
It MUST refuse to carry a stream rather than alter it: one in a program with no PCR, and one whose PES carry a clock the shift does not reach (an ESCR, a `pack_header_field`, or a TREF), PES-level scrambling, a zero `PES_packet_length` on a stream that is not video, or a header whose flagged optional fields overrun its `PES_header_data_length`, which a consumer refuses.

A verbatim or whole-PES track has no codec, dimensions, or decoder configuration, so a publisher MUST NOT describe it as a media rendition and MUST describe it only by its `tracks` entry, and a consumer MUST refuse a catalog that describes one as both.
Nothing there declares a container, so its frames use hang's `legacy` container ({{hang}}): a varint microsecond timestamp followed by the payload.

Expand Down Expand Up @@ -369,7 +371,7 @@ A consumer rebuilding a transport stream:
- MUST put the PMT on `program.pmtPid` and build the PAT and PMT from `program`.
- MUST re-emit each track's `descriptors` as its ES-level descriptors, and `programDescriptors` as the PMT's `program_info`.
- MUST re-emit each `si` entry's sections byte-for-byte on that entry's PID, reading them from its track ({{si-track}}), at least as often as its `interval` when declared.
- MUST repacketize each verbatim track per its `framing` and `streamType`, using `streamId` when recorded.
- MUST packetize each `verbatim` frame as one section on its track's PID.
- MUST packetize each `pesPacket` frame unchanged on its track's PID, its first byte going out no earlier than the frame's timestamp, and SHOULD send it as close to that as the multiplex allows.
- SHOULD pad the output with null packets to `muxRate` when present, so the rebuilt stream is constant-rate again; a source that exceeds the rate is passed through rather than delayed or dropped.

Expand Down Expand Up @@ -446,6 +448,7 @@ A broadcast demultiplexed from a DVB transport stream: video and audio described

- Added the `m2ts` section, a transport stream carried whole, with its mapping onto MSFTS; the comparison uses MSFTS's `mpeg2ts` names.
- Added the `pesPacket` record: each frame one whole PES packet, timestamped with its placement. A consumer that predates it drops the track rather than refusing the catalog.
- `verbatim` carries sections only, breaking -00: `framing` is required and `"section"` its only value, and `streamId` is gone. A consumer refuses a -00 catalog with `"pes"` framing or a `verbatim` record without `framing`. A publisher carries an undecoded PES stream as `pesPacket`, and refuses one it cannot carry unaltered.
- A flagged PCR jump on an `m2ts` track follows hang's discontinuity marker rather than a skipped group sequence.
- An `m2ts` track's fallback cut falls on whole seconds of a PCR count whose wraps follow the catalog clock, and `randomAccess` and `muxRate` describe the latest two-second window rather than the whole track, so publishers sharing a clock cut and describe the multiplex alike.

Expand Down
1 change: 0 additions & 1 deletion quest/m1/ts-reliability/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,6 @@ remain with their current quests.

- [Deterministic grading](/quest/m1/ts-reliability/grader-determinism.md) - the same input gets the same start and the same verdict
- [Plan: semantic fidelity](/quest/m1/ts-reliability/fidelity.md) - explicit profiles and PMT lifecycle contracts produce implementation quests
- [Whole-PES import](/quest/m1/ts-reliability/pes-import.md) - private PES travels whole at its source placement, a missing PTS stays missing, and the `pes` framing is deleted
- [Section placement](/quest/m1/ts-reliability/section-placement.md) - sections share the PCR placement clock instead of the video PTS
- [Sequence holes get a time budget](/quest/m1/ts-reliability/hole-budget.md) - a hole gives up on max(wall, pts), so a break marker behind it on a paused track is delivered
- [AUD first](/quest/m1/ts-reliability/aud-first.md) - a keyframe's access unit delimiter stays ahead of the re-injected parameter sets
Expand Down
6 changes: 2 additions & 4 deletions quest/m1/ts-reliability/fidelity.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,8 @@ Audit findings to reproduce and scope:
- Section export requires video, leaving audio-only programs with sections
unsupported. Keep opaque SCTE-35 fidelity separate from the later typed
browser cue API; basic carriage should not depend on that API existing.
- Private PES loses optional header semantics today; the
[whole-PES quests](/quest/m1/ts-reliability/pes-import.md) carry it
byte-exact.
- Private PES rides whole as a `pesPacket` track, byte-exact outside its
rebased PTS and DTS ([draft](/drafts/draft-lcurley-moq-mpegts.md)).

The maintainer decides whether a supported profile handles live PMT changes
in place with fresh track identities, replaces the broadcast, or initially
Expand All @@ -52,6 +51,5 @@ section/PES bytes only where the settled contract actually promises that.

## Related

- [Whole-PES import](/quest/m1/ts-reliability/pes-import.md) - private PES keeps its header bytes and source placement
- [Automated validation](/test/ts/README.md) - profile declarations link to executable evidence
- [Typed SCTE-35](/quest/m3/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - application cue APIs follow basic opaque carriage
Loading
Loading