diff --git a/doc/bin/ts.md b/doc/bin/ts.md index e0c8bf27b6b..1d0357d5e8a 100644 --- a/doc/bin/ts.md +++ b/doc/bin/ts.md @@ -24,7 +24,7 @@ moq ... --broadcast event.hang export ts --passthrough > out.ts | | Semantic | Passthrough (`--passthrough`) | | --- | --- | --- | -| On the wire | One track per elementary stream, plus the PSI and SI the import keeps, in the [`mpegts`](/draft/moq-mpegts) catalog section | One [`m2ts`](/concept/hang#transport-streams) track of whole 188-byte packets | +| On the wire | One track per elementary stream, plus the PSI and SI the import keeps, in the [`mpegts`](/draft/moq-mpegts) catalog section | One [passthrough](/concept/hang#transport-streams) track of whole 188-byte packets, named in the same section | | Output | A rebuilt TS: same media, programs, descriptors and kept SI; new packetization, PCR and table cadence | The source's packets, byte for byte, from the first group on | | Browsers and `moq play` | Watch the video and AAC or Opus audio; MP2, AC-3 and E-AC-3 play only where the player has a decoder for them, which `moq play` does not | Have nothing to decode | | A relay | Drops and prioritizes per track | Caches and drops whole runs of packets | diff --git a/doc/concept/hang.md b/doc/concept/hang.md index ecfb5abadd3..20a36293aa4 100644 --- a/doc/concept/hang.md +++ b/doc/concept/hang.md @@ -157,11 +157,15 @@ Name the section with a namespaced key such as A broadcast can carry an MPEG transport stream whole instead of demultiplexed into renditions, for what demultiplexing cannot carry, such as a scrambled -service. The root `m2ts` section names the one track holding it: +service. The `mpegts` section's `passthrough` member names the one track holding +it: ```json { - "m2ts": { "track": "0.m2ts", "randomAccess": true, "muxRate": 2499999 } + "mpegts": { + "muxRate": 2499999, + "passthrough": { "track": "0.m2ts", "randomAccess": true } + } } ``` @@ -171,7 +175,8 @@ steps back is a new broadcast. `randomAccess` says whether every published group began where a receiver can start decoding, and `muxRate` is the measured constant multiplex rate in bits per second, absent for a variable-rate source. A player has nothing to decode here. `moq import ts --passthrough` writes this -section (see [MPEG-TS](/bin/ts#passthrough-mode)); the encoding is in +member (see [MPEG-TS](/bin/ts#passthrough-mode)); the section, which also +describes a demultiplexed stream, is in [draft-lcurley-moq-mpegts](/draft/moq-mpegts). ## Container diff --git a/doc/setup/upgrade.md b/doc/setup/upgrade.md index 98f0948fb9c..2b9d44ef4ad 100644 --- a/doc/setup/upgrade.md +++ b/doc/setup/upgrade.md @@ -54,7 +54,7 @@ These land with the next breaking release. upgrade that offers no `qmux-NN` subprotocol with 400 instead of falling back to the legacy `webtransport` format, so upgrade such clients before relays. - **Data-track breaks are an object with no bytes** (#5815). A hang data - track (TS private PES, sections, `m2ts`, text) marks a discontinuity with a + track (TS private PES, sections, passthrough, 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 diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index a9137e7f738..645fab0dd10 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -35,6 +35,7 @@ normative: date: false informative: + moqmpegts: I-D.lcurley-moq-mpegts h273: title: "Coding-independent code points for video signal type identification" target: https://www.itu.int/rec/T-REC-H.273 @@ -999,57 +1000,8 @@ An edge that joins partway through a segment lists nothing before the first segm A rendition's segments after its timestamps go back start a discontinuity on that rendition alone; `EXT-X-PROGRAM-DATE-TIME` lets players resynchronize across renditions. -# MPEG-TS Service Information {#mpegts-si} -A broadcast imported from an MPEG-TS multiplex can carry the multiplex's standalone service-information tables (ISO/IEC 13818-1 program-specific information and ETSI EN 300 468 DVB SI: SDT, NIT, BAT, EIT, and any table the publisher does not recognize) so an exporter can re-emit them byte-for-byte. -The sections are opaque: nothing in this mechanism parses a table, so an unrecognized long-form table round-trips exactly like a known one. -Short-form tables, recognized or not, are carried with latest-value semantics instead (see below): the short-form tables broadcast systems define are clocks and stuffing, and a hypothetical multi-section static one would collapse to its most recent section. - -The tables are state, not events: a transport stream retransmits them continuously only because a TS receiver can tune in at any moment, so the repetition rate is a property of the unreliable transport, not of the data. -Here each table rides a dedicated snapshot track, delivered once at join and republished on change, per the root catalog's guidance that dynamic content is delegated to other tracks. -Consumers that are not TS exporters never pay for it. - -## Catalog Section {#mpegts-si-catalog} -The catalog's `mpegts` section maps each carried table to its track under an `si` field, keyed by the PID the sections ride on and then by `table_id`: - -~~~ -type Mpegts = { - // ... other MPEG-TS carriage fields ... - "si": { [pid: string]: { [tableId: string]: SiEntry } } | undefined, -} - -type SiEntry = { - "track": string, - "interval": number | undefined, -} -~~~ - -Both keys are written in decimal, since JSON object keys are strings. -`table_id` is byte 0 of generic section syntax, so the key is no less generic than the PID; which table_id ranges mean what is a DVB convention that appears nowhere in the schema. - -* `track`: the name of the snapshot track carrying this table's sections, on the same broadcast as the catalog. -* `interval`: how often an exporter MUST re-emit the sections at most, in milliseconds. A hint carrying the table's own repetition requirement (for DVB, the ETSI TS 101 211 maxima). When absent, an exporter SHOULD fall back to a fast cadence of its own choosing, so an unknown table degrades to a safe rate rather than being dropped. - -Entries are added when a table is first observed, which is acquisition-time traffic; steady-state table revisions touch only the named track, never the catalog. - -## Track Format {#mpegts-si-track} -An SI track is binary, without the media container framing ({{container}}). - -Each frame is one sub-table: its complete current sections, concatenated verbatim in `section_number` order, each including its header and CRC. -Sections are self-delimiting via `section_length`, so the frame needs no framing of its own. -A sub-table's identity is its generic section header (`table_id`, `table_id_extension`) extended by the documented disambiguators for two DVB table families: `original_network_id` (bytes 8..10) for SDT other (`table_id` 0x46), and `transport_stream_id` plus `original_network_id` (bytes 8..12) for EIT (0x4E..0x6F), whose generic identities are only unique within one network or transport stream. - -Each group is a snapshot: reading its frames in order yields the table's complete current state, where a later frame replaces an earlier one with the same sub-table identity. -A joiner reads only the newest group and is current; older groups never need to be fetched. -A writer MAY append a frame to an open group to revise one sub-table incrementally; a writer that only ever cuts complete groups is trivially conformant. - -A publisher MUST NOT mix versions within a sub-table's frame: sections of one version are buffered until the generation is judged complete and committed atomically. -Completeness is contiguity (all of `0..=last_section_number` present) or one observed full transmission cycle, whichever comes first: some tables number their sections sparsely (DVB EIT schedule skips unused numbers per segment), so a repeated section within the pending generation proves the cycle wrapped and the set is complete as transmitted. -A section lost before the cycle wraps is indistinguishable from a legitimately skipped number, so a committed set can transiently omit it until the next cycle re-supplies it; no section-counting receiver can do better. -A publisher SHOULD carry only sections whose `current_next_indicator` is set. - -A section without a long-form header (short-form syntax: TDT/TOT and similar) has no extension, version, or numbering, so its table is a single latest-value slot: each arrival replaces the last, and a byte-identical repetition is not a change. -This is what makes a time table proxyable: each tick republishes a small snapshot, a joiner reads the newest, and staleness is bounded by the source's own repetition interval plus path latency, the same bound a receiver of the original multiplex has. -Carrying the source's time rather than synthesizing one keeps the clock consistent with the EPG (event times are expressed on the source's clock) and preserves TOT's local-time-offset descriptors, which are operator policy a re-multiplexer cannot invent. +# MPEG-TS {#mpegts} +A broadcast imported from an MPEG-TS multiplex MAY carry the `mpegts` root section {{moqmpegts}}: what demultiplexing loses, such as each track's PID and descriptors, the program identity, and the service information tables, or else the one track carrying the multiplex whole. # Rooms @@ -1105,6 +1057,7 @@ This document has no IANA actions. - A data track marks a discontinuity with a group of one object with no bytes, since its empty payload is data. An object with no bytes on an audio or video track, or sharing its group, is malformed. - Removed the Recording section: the store layout is a moq-archive format, documented with that crate, not part of this draft. - Removed the viewer feedback `latency` field. +- Removed the MPEG-TS Service Information section: {{moqmpegts}} defines the `mpegts` root section. - Added the optional video `preference` field: a consumer selects automatically among the highest preference it can decode. - Added the optional video `reorder` field: the most frames that can precede one in decode order and follow it in presentation, fixed for the track once declared. A consumer that authors decode times derives them from it and the current group alone, refusing deeper reordering; without it, a consumer infers them from timestamps. - Added an optional `instance` beside every rendition and data track `broadcast` reference ({{field-instance}}). A consumer reads each referenced path from the first broadcast it resolves for a catalog instance; a present `instance` fails a rendition that resolves another stream, and is best effort against an Instance a receiver minted. diff --git a/drafts/draft-lcurley-moq-mpegts.md b/drafts/draft-lcurley-moq-mpegts.md index e5a1c299197..c6327a43924 100644 --- a/drafts/draft-lcurley-moq-mpegts.md +++ b/drafts/draft-lcurley-moq-mpegts.md @@ -50,7 +50,7 @@ informative: This document defines the `mpegts` catalog section, which records what demultiplexing an MPEG-2 Transport Stream {{mpeg2}} into a MoQ broadcast would otherwise lose: each track's PID and PMT descriptors, the program identity, the service information tables, and a carriage record for every elementary stream the publisher did not decode. It is a root member of either the hang catalog {{hang}} or the MSF catalog {{msf}}, so a subscriber that ignores it still plays the broadcast and one that reads it can rebuild the source multiplex. -It also defines the `m2ts` section of the hang catalog, which names a track carrying the transport stream whole, and maps that track onto MSFTS {{msfts}}. +The same section can instead name one track carrying the transport stream whole, which this document maps onto MSFTS {{msfts}}. --- note_Note_to_Readers @@ -69,7 +69,7 @@ A **verbatim** track carries an elementary stream the publisher did not decode, # Introduction {#introduction} A transport stream reaches MoQ in one of two shapes. -A publisher can leave the multiplex intact and carry the packet stream as opaque payload, which is what {{msfts}} specifies for MSF and the `m2ts` section ({{m2ts}}) describes in a hang catalog. +A publisher can leave the multiplex intact and carry the packet stream as opaque payload, which is what {{msfts}} specifies for MSF and the section's `passthrough` member ({{passthrough}}) describes. Or it can demultiplex, which is what most of this document addresses: each elementary stream becomes its own MoQ track with a codec description, so a relay can drop and prioritize per track and a subscriber can decode without a transport-stream parser ({{comparison}}). Demultiplexing loses everything that is not media: the PID layout, the PMT descriptors, the program identity, the service information, and any stream the publisher has no decoder for. @@ -79,7 +79,7 @@ It defines no packaging and no container: decoded media keeps the container its # Comparison with mpeg2ts Packaging {#comparison} {{msfts}} carries the transport stream as it arrives: each object is a run of whole 188- or 192-byte packets, and the receiver demultiplexes as it always has. -The `m2ts` section ({{m2ts}}) carries the same shape in a hang catalog: one track per multiplex, with a timestamp before each object's packets. +A `passthrough` track ({{passthrough}}) carries the same shape: one track per multiplex, with a timestamp before each object's packets. This document takes the stream apart at the publisher and discards the packetization layer, because MoQ already provides what it was there for: - **Packet framing** interleaves elementary streams onto one serial pipe. MoQ delivers each track separately. @@ -104,7 +104,7 @@ A track is one shape or the other, and a broadcast may carry either. # The mpegts Section {#section} -A publisher that demultiplexed a transport stream SHOULD add an `mpegts` root member to its catalog ({{carriage}}): +A publisher that demultiplexed a transport stream SHOULD add an `mpegts` root member to its catalog ({{carriage}}), and one that carries a transport stream whole MUST: ~~~ type Mpegts = { @@ -113,6 +113,7 @@ type Mpegts = { "program": Program | undefined, "si": Map | undefined, "muxRate": number | undefined, + "passthrough": Passthrough | undefined, } ~~~ @@ -161,7 +162,7 @@ type Program = { They are the only service-layer fields this document parses; everything else about the program stays inside the opaque `si` tables. A PAT that moves the PMT to another PID changes `pmtPid` in place. -A publisher MUST include `program` when the broadcast came from a transport stream, and omit it otherwise. +A publisher MUST include `program` when it demultiplexed a transport stream, and omit it otherwise. A publisher MUST NOT change `transportStreamId` or `programNumber` in place: the carried `si` describes that service, so a source whose PAT names another ends the broadcast. ## si {#field-si} @@ -274,55 +275,53 @@ A verbatim or whole-PES track has no codec, dimensions, or decoder configuration Nothing there declares a container, so its frames use hang's `legacy` container ({{hang}}): a varint microsecond timestamp followed by the payload. -# The m2ts Section {#m2ts} -A publisher that carries a transport stream whole, without demultiplexing it, names its track in an `m2ts` root member of the hang catalog ({{carriage-hang}}): +# Passthrough {#passthrough} +A publisher that carries a transport stream whole, without demultiplexing it, names its track in the section's `passthrough` member: ~~~ -type M2ts = { +type Passthrough = { "track": TrackName, "randomAccess": boolean, - "muxRate": number | undefined, } ~~~ `track` names the one track carrying the multiplex, in the same broadcast as the catalog. A second multiplex is a second broadcast. -`randomAccess` says that every group starts at a random access point ({{m2ts-groups}}). +`randomAccess` says that every group starts at a random access point ({{passthrough-groups}}). A publisher MUST write it, and a consumer MUST read an absent `randomAccess` as false. -`muxRate` follows {{field-mux-rate}}, measured over every packet of the track. - -The section records no program, PID, descriptor, or table: they all reach the consumer inside the packets, as the publisher received them. -A track named here MUST NOT also be described as a rendition or in an `mpegts` section. +The section's `muxRate` ({{field-mux-rate}}) is the rate of every packet of the track. +Nothing else is recorded for it: the program, PIDs, descriptors, and tables reach the consumer inside the packets, as the publisher received them. +A publisher MUST NOT also describe the track as a rendition, in `tracks`, or in `si`, and a consumer MUST refuse a section whose `tracks` or `si` names the `passthrough` track. -## Objects {#m2ts-objects} -Each frame is a run of whole 188-byte packets in the order the publisher received them, in hang's `legacy` container ({{hang}}) with the timestamp of {{m2ts-timestamps}}. +## Objects {#passthrough-objects} +Each frame is a run of whole 188-byte packets in the order the publisher received them, in hang's `legacy` container ({{hang}}) with the timestamp of {{passthrough-timestamps}}. A publisher MUST refuse a source of 192- or 204-byte packets rather than reframe it, since removing the extra bytes would change the stream. The multiplex is paced on one clock PID: the `PCR_PID` in the PMT of the first program the PAT lists, unless the publisher is configured with another. A frame runs from one packet carrying a PCR on the clock PID up to the next, and is also cut wherever a group starts. -A publisher publishes nothing until it has read the PAT, the PMT of the clock's program, and a PCR, and its first group then waits for the next group start ({{m2ts-groups}}). +A publisher publishes nothing until it has read the PAT, the PMT of the clock's program, and a PCR, and its first group then waits for the next group start ({{passthrough-groups}}). It drops the bytes before that group, and any bytes off the 188-byte packet grid, and they are outside the track's identity with its input. From the first group on, the frames of consecutive groups concatenate to the input: a publisher MUST NOT drop, reorder, or modify a packet after that point. -## Groups {#m2ts-groups} +## Groups {#passthrough-groups} A group starts at: - a packet with `random_access_indicator` set on the video PID of the clock's program (the first PID its PMT declares with a video `stream_type`), or on the clock PID when that program has no video; -- a PCR on the clock PID with `discontinuity_indicator` set that steps forward ({{m2ts-timestamps}}), since a group MUST NOT contain a PCR discontinuity; +- a PCR on the clock PID with `discontinuity_indicator` set that steps forward ({{passthrough-timestamps}}), since a group MUST NOT contain a PCR discontinuity; - otherwise, the first PCR at least one second of PCR time after the group's start; - the frame that would take a group past a size bound the publisher chooses below what a relay caches of one group; frames are never split to meet it. `randomAccess` is true only while the PAT lists one program, its PMT declares at most one video stream, and the clock PID is that PMT's `PCR_PID`, and only if every group so far has started at a `random_access_indicator`. -The first group that starts any other way, or that carries packets while that layout does not hold, republishes the section with `randomAccess` false for the rest of the track. +The first group that starts any other way, or that carries packets while that layout does not hold, republishes the catalog with `randomAccess` false for the rest of the track. With more programs or video streams the random access points can stagger, so a group start is not one for all of them. Both indicators sit in the adaptation field, which TS-level scrambling leaves in the clear, so a scrambled multiplex groups like its clear twin. A publisher parses the PAT and the PMT and nothing else past the adaptation field. -## Timestamps {#m2ts-timestamps} +## Timestamps {#passthrough-timestamps} A frame's timestamp is the PCR time of its first byte, in microseconds rounded down. A PCR gives the time of the byte holding the last bit of its `program_clock_reference_base` ({{mpeg2}}), ten bytes into its packet. A byte between two PCRs is placed at the rate between them; a byte past the last PCR of a timebase takes the rate of the interval before it, and one before the first PCR of a timebase takes the rate of the interval after it. @@ -334,9 +333,9 @@ A PCR that steps backwards MUST end the track with an error, flagged or not: a f The timeline depends only on the bytes since the publisher's first PCR, so two publishers that start at the same packet of one input publish identical frames. -## Mapping onto MSFTS {#m2ts-msfts} +## Mapping onto MSFTS {#passthrough-msfts} Stripping each frame's timestamp leaves an {{msfts}} object of whole source packets, and the groups carry over unchanged. -An MSF catalog does not list the `m2ts` track itself, whose frames hold more than packets; a converter that republishes the stripped objects describes its track as follows: +An MSF catalog names the `passthrough` track only in its `mpegts` section, since the track's frames hold more than packets; a converter that republishes the stripped objects describes its track as follows: | MSFTS track field | Value | |:--------|:--------| @@ -344,11 +343,11 @@ An MSF catalog does not list the `m2ts` track itself, whose frames hold more tha | `mpeg2tsMode` | `unmodified-program` when the PAT lists one program, otherwise `unmodified-multiplex` | | `mpeg2tsPacketSize` | 188 | | `mpeg2tsRandomAccess` | `randomAccess` | -| `mpeg2tsMuxRate` | `muxRate`, in `unmodified-program` mode only | +| `mpeg2tsMuxRate` | the section's `muxRate`, in `unmodified-program` mode only | | `mpeg2tsProgramNumber`, `mpeg2tsPcrPid`, `mpeg2tsScte35Pid` | read from the PAT and the PMT in the packets, where {{msfts}} permits them in the mode | | `mpeg2tsTimestampMode`, `mpeg2tsEsPid`, `mpeg2tsSiPids` | absent | -{{msfts}} asks for the PAT and the PMT in `initDataList` when random access is true; the `m2ts` section does not carry them, so a converter takes them from the packets. +{{msfts}} asks for the PAT and the PMT in `initDataList` when random access is true; the `mpegts` section does not carry them for a passthrough, so a converter takes them from the packets. # Carriage {#carriage} @@ -356,16 +355,15 @@ The section is the same JSON in either catalog format. ## hang {#carriage-hang} A root member named `mpegts`, alongside `video` and `audio` ({{hang}}). -The `m2ts` section ({{m2ts}}) is a root member of the hang catalog only. hang carries a decoder config's raw bytes as hex while every binary field here is base64; the alphabets overlap, so the encoding cannot be detected and is stated per field above. ## MSF {#carriage-msf} A root member named `mpegts`, alongside `tracks` ({{msf}}). A publisher MUST NOT name a section after a member MSF itself defines. -The keys of the section's own `tracks` member are MSF track names; a decoded track also has an MSF track object, a verbatim track does not. +The keys of the section's own `tracks` member are MSF track names; a decoded track also has an MSF track object, a verbatim or `passthrough` track does not. -This document defines no packaging value; {{msfts}} defines `mpeg2ts` for the passthrough shape ({{comparison}}), and {{m2ts-msfts}} maps an `m2ts` track onto it. +This document defines no packaging value; {{msfts}} defines `mpeg2ts` for the passthrough shape ({{comparison}}), and {{passthrough-msfts}} maps a `passthrough` track onto it. # Rebuilding a Transport Stream {#rebuild} @@ -389,7 +387,7 @@ A consumer MUST NOT derive one that contradicts a recorded descriptor. # Security Considerations Every binary field here is re-emitted without inspection, by a publisher that never parsed it and a relay that never looked, so a consumer MUST treat all of it as untrusted input. -The same holds for every packet of an `m2ts` track, which the publisher forwards as it received them. +The same holds for every packet of a `passthrough` track, which the publisher forwards as it received them. Nothing bounds the number of entries in the section, nor the size of an SI track: a publisher controls both, and an EPG is large by nature. A consumer MUST bound what it accepts of each, and MUST reject a catalog it cannot bound rather than truncate it into a stream that silently differs from what was described. @@ -453,14 +451,14 @@ A broadcast demultiplexed from a DVB transport stream: video and audio described {:numbered="false"} - Programs without media anchor on PCR, preserving its era across the wrap; rebuilding supports audio clocks and a dedicated PCR-only PID for data-only programs. -- Added the `m2ts` section, a transport stream carried whole, with its mapping onto MSFTS; the comparison uses MSFTS's `mpeg2ts` names. +- Added the `passthrough` member, naming a track that carries the transport stream whole, with its mapping onto MSFTS; the section's `muxRate` is that track's rate. The comparison uses MSFTS's `mpeg2ts` names. - Section-framed `verbatim` timestamps use PCR-derived placement at the first section byte, as whole PES do, rather than a video presentation time. - 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. - MPEG-1/2 video and LATM AAC are named among `pesPacket` streams, and the DSM-CC types 0x0A to 0x0D among section-framed `verbatim` ones. A rebuilt PAT lists the network entry when the NIT is carried. - MPEG-1/2 video `pesPacket` frames group from one sequence header to the next, rather than one PES per group. -- A flagged PCR jump on an `m2ts` track follows hang's discontinuity marker rather than a skipped group sequence. -- An `m2ts` track unwraps PCRs from its history, clamps extrapolated object times at a forward discontinuity, and cuts a fallback group after one second. `randomAccess` covers every published group; `muxRate` follows the measured source rate. +- A flagged PCR jump on a `passthrough` track follows hang's discontinuity marker rather than a skipped group sequence. +- A `passthrough` track unwraps PCRs from its history, clamps extrapolated object times at a forward discontinuity, and cuts a fallback group after one second. `randomAccess` covers every published group; `muxRate` follows the measured source rate. - A `tracks` entry is never changed in place: a stream the PMT revises continues under a new name, and one it drops leaves the section. `programDescriptors` follows the PMT; `program`'s `transportStreamId` and `programNumber` do not change. - A consumer rebuilding a stream follows the catalog's revisions at the next PMT `version_number`, and carries a stream only while a PMT lists it. - `pmtPid` follows a PAT that moves the PMT, and a consumer rebuilding a stream moves the PMT behind a PAT at the next `version_number`. diff --git a/js/hang/src/catalog/root.ts b/js/hang/src/catalog/root.ts index 7aec67165d0..586806368b0 100644 --- a/js/hang/src/catalog/root.ts +++ b/js/hang/src/catalog/root.ts @@ -44,7 +44,9 @@ const RootVersionSchema = VersionSchema.check( * ignores the extra sections; an extended consumer validates them with its own schema, typically * built via `z.extend(RootSchema, { ... })`. An application names its own sections with a * namespaced key (`com.example.telemetry`): every section defined here must have its shape when - * present, or parsing refuses the whole catalog, the same as Rust. + * present, or parsing refuses the whole catalog, the same as Rust. The `mpegts` section + * (draft-lcurley-moq-mpegts), including a transport stream carried whole, is such an extension: + * nothing in JS reads it yet. * * The root `version` is the oldest moq-hang draft that reads the catalog correctly, absent while * that is 3, and parsing throws {@link UnsupportedVersion} when it is above {@link VERSION}. Each diff --git a/quest/m0/test-flakes-3/pcm-five-one.md b/quest/m0/test-flakes-3/pcm-five-one.md new file mode 100644 index 00000000000..8b21e8b5b75 --- /dev/null +++ b/quest/m0/test-flakes-3/pcm-five-one.md @@ -0,0 +1,19 @@ +# [S] moq-audio's 5.1 PCM round trip reads its frame under load + +## Goal + +`moq-audio`'s `roundtrip::pcm_five_one_reads_back_at_any_layout` reads one +decoded frame per output layout on every run, instead of sometimes finding +the consumer ended first. + +## Plan + +Seen 2026-11-16 in a loaded `just check` on the branch of the hang-04 +MPEG-TS passthrough change, which touches no audio code: `next_frame` returned +`None` at `rs/moq-audio/tests/integration/roundtrip.rs:239`, and three runs of +the test alone passed. The test finishes the producer right after creating the +consumers, so a consumer may see the end before its first frame. Reproduce +under load, find whether the decode consumer drops frames written before it +subscribed or the end overtakes them, and fix that cause. + +Public API: none. Wire: none. diff --git a/quest/m2/README.md b/quest/m2/README.md index 0f9f33471a8..c2b1300c5d4 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -43,7 +43,7 @@ removal, a rename, or a wire, catalog, or format change that is free until ([moq-dev/moq#8947](https://github.com/moq-dev/moq/pull/8947)); its [finished format](/quest/m3/e2ee-format.md) follows in m3. - **Catalog, drafts, and formats.** [hang-04](/quest/m2/hang04/README.md) - (the `sync` section, a version per entry, no video `warmup`, `m2ts` under + (the `sync` section, a version per entry, no video `warmup`, the TS passthrough under `mpegts`, one strict rule); [declared ends](/quest/m2/time-addressing/consumers.md), back from m3. - **Native media and gateways.** [Upstream str0m](https://github.com/moq-dev/moq/pull/8963), which reverses the diff --git a/quest/m2/hang04/README.md b/quest/m2/hang04/README.md index 29cb1af0c77..e7f5b031c92 100644 --- a/quest/m2/hang04/README.md +++ b/quest/m2/hang04/README.md @@ -1,4 +1,4 @@ -# hang-04 freezes a catalog worth keeping +# [S] hang-04 freezes a catalog worth keeping ## Goal @@ -28,8 +28,7 @@ The children land in any order. Every root section already reads under the hang draft's one rule (a root member the draft defines has its shape, or the catalog is refused), so -the `sync` section and -[the MPEG-TS section](/quest/m2/hang04/m2ts.md) are born strict. +the `sync` section and the MPEG-TS section are born strict. What the audit judged and kept, so nobody reopens it without new evidence: `include`, `track` apart from the ID, `instance` on references, `enabled`, diff --git a/quest/m2/hang04/m2ts.md b/quest/m2/hang04/m2ts.md deleted file mode 100644 index aa61dd1f59c..00000000000 --- a/quest/m2/hang04/m2ts.md +++ /dev/null @@ -1,66 +0,0 @@ -# [M] A transport stream carried whole is listed under the mpegts section - -## Goal - -The hang catalog has one MPEG-TS section. The track that carries a -transport stream whole (today the root `m2ts` section) is listed inside -`mpegts`, beside the description of a demultiplexed stream, and the section -has one `muxRate`. `hang::Catalog` has no MPEG-TS field, so the Rust and JS -core catalogs hold the same sections, and the MPEG-TS draft and the hang -draft agree on where the section is defined. - -## Plan - -Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): - -- ✅ `m2ts` nests under `mpegts` with one `muxRate` (rejected: keep the - root key and add it to `js/hang` and the hang draft's root schema; keep - as is). - -Facts found by the audit: - -- `m2ts` ([moq-dev/moq#5003](https://github.com/moq-dev/moq/pull/5003)) is - a typed field of the core catalog (`rs/hang/src/catalog/root.rs`, - `rs/hang/src/catalog/m2ts.rs`), while its sibling `mpegts` is a moq-mux - extension section (`Mpegts` and `Ext` in - `rs/moq-mux/src/container/ts/catalog.rs`). Both are specified in - `drafts/draft-lcurley-moq-mpegts.md`, neither in the hang draft's root - schema. -- `js/hang` parses neither (`grep -rn 'm2ts\|mpegts' js/hang/src/catalog` - is empty), so the two core catalogs disagree about a root member. -- Both sections carry `muxRate` (`M2ts::mux_rate`, `Mpegts::mux_rate`), and - a track may appear in only one of them. -- The names do not say which is which, and `.m2ts` usually means 192-byte - Blu-ray packets, which the section refuses. -- Users of `M2ts`: `rs/moq-mux/src/container/ts/{passthrough,release}.rs`, - `rs/moq-mux/src/catalog/producer.rs`, `rs/moq-mux/src/import/format.rs`, - and `rs/moq-cli/src/{args,publish,subscribe}.rs`. - -Recommendations for the PR: - -- Shape: `mpegts.passthrough: { track, randomAccess }`, with the rate in - the section's existing `muxRate`. Pick the member name in the PR; - `passthrough` matches `moq import ts --passthrough` and the module. -- `M2ts` leaves `hang` for `moq_mux::container::ts` beside `Mpegts`. Check - first why `rs/moq-mux/src/catalog/producer.rs` reads it from the base - catalog and not the extension: that is the one thing that could make the - move cost more than a rename. -- JS gets no MPEG-TS schema: nothing in JS reads a transport stream, and - with the root member gone Rust and JS agree on the core catalog. Say so - where `js/hang`'s root schema lists its sections. (This reads the - decision's "in Rust, JS, and the draft" as parity of the core catalog; a - typed `mpegts` schema in `@moq/hang` waits for a JS reader.) -- Drafts: the MPEG-TS draft's `m2ts` section becomes a member of its - `mpegts` section, with one `muxRate` definition, and its MSFTS mapping - follows. The hang draft's "MPEG-TS Service Information" section, 51 - lines that repeat the MPEG-TS draft's `si` and SI track sections, is - replaced by a pointer. -- An older main build that wrote a root `m2ts` is unpublished, so no reader - keeps the old key. - -Tests: the passthrough round trip (`passthrough_test.rs`, `release_test.rs`) -reads the track from the nested member; a catalog with both a demultiplexed -description and a passthrough track is refused if they name the same track. - -Public API: breaking. Rust `hang::catalog::M2ts` and `Catalog::m2ts` move to -moq-mux. Wire: the unpublished `m2ts` root section of the catalog. diff --git a/quest/m2/ts-passthrough-splice.md b/quest/m2/ts-passthrough-splice.md index 456e6b9bcd3..0f5acfa58fe 100644 --- a/quest/m2/ts-passthrough-splice.md +++ b/quest/m2/ts-passthrough-splice.md @@ -65,7 +65,3 @@ existing reader handles the result. ## Closes - [#8911](https://github.com/moq-dev/moq/issues/8911) - `import ts --passthrough` ends at an unflagged clock step back - -## Related - -- [A transport stream carried whole is listed under the mpegts section](/quest/m2/hang04/m2ts.md) - also edits the passthrough import and release diff --git a/rs/hang/src/catalog/m2ts.rs b/rs/hang/src/catalog/m2ts.rs deleted file mode 100644 index 10b9c2480cb..00000000000 --- a/rs/hang/src/catalog/m2ts.rs +++ /dev/null @@ -1,86 +0,0 @@ -use serde::{Deserialize, Serialize}; - -/// A transport stream carried whole, as one track of verbatim packets. -/// -/// The track's frames are runs of whole 188-byte packets in source order, each in the -/// [`Legacy`](crate::catalog::Container::Legacy) container with the PCR time of its first byte. -/// Nothing about the multiplex is described here because all of it stays in-band: the PAT, PMT, -/// and SI ride the track as authored, scrambled payloads included. A demultiplexed broadcast -/// describes each elementary stream as a rendition instead; a track is one shape or the other. -/// -/// Marked `#[non_exhaustive]` so additional optional fields can be added without bumping the major -/// version. External callers build one with [`M2ts::new`] and assign the fields they need. -#[serde_with::serde_as] -#[serde_with::skip_serializing_none] -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)] -#[serde(rename_all = "camelCase")] -#[non_exhaustive] -pub struct M2ts { - /// The track carrying the packets, published in the same broadcast as the catalog. - pub track: String, - - /// Whether every group starts at a random access point of the multiplex's video stream, or of - /// its clock PID when it has none, so a subscriber can decode from the first object of any. - /// - /// Only ever true for a single program with at most one video stream: programs or video - /// streams sharing a clock can stagger their GOPs, leaving no packet that starts all of them. - /// Always written; a reader treats it as false when absent. - #[serde(default)] - pub random_access: bool, - - /// The rate the source's PCR paced the whole multiplex at, in bits per second, null packets - /// included. Present only while the source holds a constant rate. - #[serde(default)] - #[serde_as(as = "crate::catalog::NotNull")] - pub mux_rate: Option, -} - -impl M2ts { - /// A section naming `track`, with no random access promised and no rate recorded. - pub fn new(track: impl Into) -> Self { - Self { - track: track.into(), - random_access: false, - mux_rate: None, - } - } -} - -#[cfg(test)] -mod test { - use super::*; - - #[test] - fn roundtrip() { - let mut section = M2ts::new("0.m2ts"); - section.random_access = true; - section.mux_rate = Some(2_499_999); - - let json = serde_json::to_string(§ion).unwrap(); - assert_eq!(json, r#"{"track":"0.m2ts","randomAccess":true,"muxRate":2499999}"#); - assert_eq!(serde_json::from_str::(&json).unwrap(), section); - } - - #[test] - fn random_access_is_always_written_and_mux_rate_only_when_known() { - let json = serde_json::to_string(&M2ts::new("0.m2ts")).unwrap(); - assert_eq!(json, r#"{"track":"0.m2ts","randomAccess":false}"#); - } - - #[test] - fn absent_random_access_reads_as_false() { - let section: M2ts = serde_json::from_str(r#"{"track":"0.m2ts"}"#).unwrap(); - assert_eq!(section, M2ts::new("0.m2ts")); - } - - #[test] - fn unknown_fields_are_ignored() { - let section: M2ts = serde_json::from_str(r#"{"track":"0.m2ts","packetSize":188}"#).unwrap(); - assert_eq!(section.track, "0.m2ts"); - } - - #[test] - fn a_section_without_a_track_is_refused() { - serde_json::from_str::(r#"{"randomAccess":true}"#).expect_err("a section must name its track"); - } -} diff --git a/rs/hang/src/catalog/mod.rs b/rs/hang/src/catalog/mod.rs index 6109638a380..568098c5aa4 100644 --- a/rs/hang/src/catalog/mod.rs +++ b/rs/hang/src/catalog/mod.rs @@ -14,7 +14,6 @@ mod echo; mod hex; mod include; mod json; -mod m2ts; mod millis; mod mode; mod priority; @@ -34,7 +33,6 @@ pub use container::*; pub use echo::*; pub use include::*; pub use json::*; -pub use m2ts::*; pub use mode::*; pub use priority::*; pub use reference::*; diff --git a/rs/hang/src/catalog/root.rs b/rs/hang/src/catalog/root.rs index 908d563cd46..97d9601d1f0 100644 --- a/rs/hang/src/catalog/root.rs +++ b/rs/hang/src/catalog/root.rs @@ -11,11 +11,11 @@ use serde::{Deserialize, Serialize}; /// /// The base catalog carries the media sections (`video`, `audio`, `text`), the optional `sync` /// section (the broadcast's one wall-clock mapping and join interval), the data sections -/// (`json`, `binary`) for application tracks that aren't media, and the optional `m2ts` (a -/// transport stream carried whole), plus `stats` naming the publisher's media snapshot track and -/// `echo` soliciting viewer feedback under a relative broadcast prefix, and `include` naming -/// whole broadcasts for explicit selection. -/// Applications extend it with their own root sections (e.g. `com.example.scte35`) through `E`. The catalog +/// (`json`, `binary`) for application tracks that aren't media, plus `stats` naming the +/// publisher's media snapshot track, `echo` soliciting viewer feedback under a relative broadcast +/// prefix, and `include` naming whole broadcasts for explicit selection. +/// Applications extend it with their own root sections (e.g. `com.example.scte35`, or moq-mux's +/// `mpegts`) through `E`. The catalog /// does not deny unknown fields, so a base consumer ignores the extra sections and an extended /// catalog stays wire-compatible. See the `extension_roundtrip` test. /// @@ -66,10 +66,6 @@ pub struct Catalog { /// Omitted from the wire when empty, so a media-only catalog is unchanged. pub binary: Binary, - /// A transport stream carried whole rather than demultiplexed: the one track holding its - /// packets, verbatim. See [`M2ts`](crate::catalog::M2ts). Omitted from the wire when absent. - pub m2ts: Option, - /// The publisher's optional media snapshot track. pub stats: Option, @@ -148,9 +144,6 @@ struct Wire { )] binary: Binary, - #[serde(default, deserialize_with = "crate::catalog::deserialize_some")] - m2ts: Option, - #[serde(default, deserialize_with = "crate::catalog::deserialize_some")] stats: Option, @@ -199,7 +192,6 @@ impl From> for Catalog { text, json, binary, - m2ts, stats, echo, include, @@ -213,7 +205,6 @@ impl From> for Catalog { text, json, binary, - m2ts, stats, echo, include, @@ -1162,32 +1153,6 @@ mod test { assert_eq!(catalog.to_json().unwrap(), plain.to_json().unwrap()); } - /// A section with the wrong shape refuses the catalog rather than reading as absent. The shared - /// parity fixture holds the cases for every section both languages read; `m2ts` is Rust's alone. - #[test] - fn a_mis_shaped_m2ts_refuses_the_catalog() { - for value in ["null", "5", r#""0.m2ts""#, r#"["0.m2ts"]"#, "{}", r#"{"track":5}"#] { - Catalog::<()>::from_str(&format!(r#"{{"m2ts":{value}}}"#)).expect_err(value); - } - } - - #[test] - fn m2ts_roundtrips_at_the_root() { - let mut m2ts = crate::catalog::M2ts::new("0.m2ts"); - m2ts.random_access = true; - let catalog = Catalog::<()> { - m2ts: Some(m2ts.clone()), - ..Default::default() - }; - - let json = catalog.to_json().expect("failed to encode"); - assert_eq!(json, r#"{"m2ts":{"track":"0.m2ts","randomAccess":true}}"#); - assert_eq!( - Catalog::<()>::from_str(&json).expect("failed to decode").m2ts, - Some(m2ts) - ); - } - #[test] fn packaged_clock_fixture_decodes() { // The canonical shape: the clock and join interval under `sync`. A reader maps media diff --git a/rs/libmoq/src/publish.rs b/rs/libmoq/src/publish.rs index d4bf6e8ab95..e26462bd9e4 100644 --- a/rs/libmoq/src/publish.rs +++ b/rs/libmoq/src/publish.rs @@ -816,7 +816,7 @@ impl Publish { /// Insert or replace a top-level application catalog section by name. /// /// `value` is any JSON document. Errors if `name` is a HANG root (`video`, `audio`, `sync`, `text`, - /// `json`, `binary`, `stats`, `echo`, `include`, `m2ts`, or the retired `archive`, `clock`, + /// `json`, `binary`, `stats`, `echo`, `include`, or the retired `archive`, `clock`, /// `media`, and `timeline`) or an MSF root (`version`, /// `generatedAt`, `isComplete`, `tracks`, or `initDataList`). The catalog is republished /// automatically. diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index bbe2960e929..5233f7f0da3 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -957,7 +957,7 @@ pub struct TsImport { pub program: Option, /// Publish the multiplex whole instead of demultiplexing it: every 188-byte packet verbatim, - /// on one track the catalog's `m2ts` section names. Scrambled streams, private PIDs, and the + /// on one track the catalog's `mpegts` section names. Scrambled streams, private PIDs, and the /// PSI and SI ride through as authored. Bytes before the first group are dropped. #[usage(long, conflicts = "--program")] pub passthrough: bool, @@ -1215,7 +1215,7 @@ pub struct ContainerSink { pub stitch: bool, pub fragment_duration: Option, pub mux_rate: Option, - /// Write the `m2ts` passthrough track back out (`ts` only). + /// Write the passthrough track back out (`ts` only). pub passthrough: bool, /// The file a recording writes (`mp4` only); the rest write to stdout. pub output: Option, diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index 240cac02219..88d42cb24c0 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -305,6 +305,8 @@ fn suggest_program(err: ts::Error) -> anyhow::Error { /// The catalog a stdin decoder publishes into. enum PublishCatalog { Media(Box), + /// `import ts --passthrough`'s, with the `mpegts` extension that names its track. + Passthrough(Box>), /// A TS import's: each instance's or program's, with the `mpegts` extension, finished by /// [`ts::Republish::finish`] or [`ts::Programs::finish`]. Ts, @@ -314,6 +316,7 @@ impl PublishCatalog { fn abort(self, err: moq_net::Error) { match self { Self::Media(catalog) => catalog.abort(err), + Self::Passthrough(catalog) => catalog.abort(err), Self::Ts => {} } } @@ -322,6 +325,7 @@ impl PublishCatalog { fn finish(&mut self) -> anyhow::Result<()> { match self { Self::Media(catalog) => catalog.finish()?, + Self::Passthrough(catalog) => catalog.finish()?, Self::Ts => {} } Ok(()) @@ -422,6 +426,22 @@ impl Publish { !matches!(format, PublishFormat::Ts { .. }), "a TS import publishes through an origin, which republishes it as its source changes" ); + if let PublishFormat::TsPassthrough { pcr_pid } = *format { + // Nothing about the multiplex is described beyond the track that carries it, which the + // `mpegts` section names. + let config = config.with_catalog(hang::Catalog::::default()); + let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config)?; + let mut passthrough = ts::Passthrough::new(broadcast.clone(), catalog.timebase().reserve())?; + if let Some(pid) = pcr_pid { + passthrough = passthrough.with_pcr_pid(pid); + } + let decoder = PublishDecoder::TsPassthrough(Box::new(passthrough)); + return Ok(Self::decode( + broadcast, + decoder, + PublishCatalog::Passthrough(Box::new(catalog)), + )); + } let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config)?; let decoder = match format { PublishFormat::Avc3 => { @@ -438,17 +458,7 @@ impl Publish { let fmp4 = fmp4::Import::new(broadcast.clone(), timebase.reserve()).with_cmaf(*cmaf); PublishDecoder::Fmp4(Box::new(fmp4)) } - PublishFormat::Ts { .. } => unreachable!("refused above"), - // The `m2ts` section is in the base catalog: nothing about the multiplex is described - // beyond the track that carries it. - PublishFormat::TsPassthrough { pcr_pid } => { - let timebase = catalog.timebase(); - let mut passthrough = ts::Passthrough::new(broadcast.clone(), timebase.reserve())?; - if let Some(pid) = pcr_pid { - passthrough = passthrough.with_pcr_pid(*pid); - } - PublishDecoder::TsPassthrough(Box::new(passthrough)) - } + PublishFormat::Ts { .. } | PublishFormat::TsPassthrough { .. } => unreachable!("handled above"), // FLV's 32-bit milliseconds wrap after 49 days, which its importer does not follow, // so it takes no era. PublishFormat::Flv => { @@ -458,18 +468,24 @@ impl Publish { } }; - Ok(Self { - source: Source::Stream { - decoder, - catalog: PublishCatalog::Media(Box::new(catalog)), - }, + Ok(Self::decode( + broadcast, + decoder, + PublishCatalog::Media(Box::new(catalog)), + )) + } + + /// A publisher feeding `decoder` from stdin into `broadcast`, described by `catalog`. + fn decode(broadcast: moq_net::broadcast::Producer, decoder: PublishDecoder, catalog: PublishCatalog) -> Self { + Self { + source: Source::Stream { decoder, catalog }, broadcast: Some(broadcast), route: None, announce: false, report: None, linger: moq_mux::Linger::DEFAULT, sections: Sections::default(), - }) + } } /// Build a publisher decoding `format` from stdin into a new broadcast at `name` on @@ -593,6 +609,9 @@ impl Publish { (_, PublishCatalog::Media(catalog), Some(broadcast)) => { crate::report::Stats::new(broadcast, catalog, connection)? } + (_, PublishCatalog::Passthrough(catalog), Some(broadcast)) => { + crate::report::Stats::new(broadcast, catalog, connection)? + } (PublishDecoder::Ts(republish), _, _) => { self.sections.report = Some(connection.clone()); report(republish, connection)? @@ -615,6 +634,7 @@ impl Publish { match &mut self.source { Source::Stream { decoder, catalog } => match (decoder, catalog) { (_, PublishCatalog::Media(catalog)) => catalog.mutate(|catalog| catalog.echo = Some(echo))?, + (_, PublishCatalog::Passthrough(catalog)) => catalog.mutate(|catalog| catalog.echo = Some(echo))?, (PublishDecoder::Ts(republish), _) => { self.sections.echo = Some(echo.clone()); republish @@ -1791,7 +1811,7 @@ pub(crate) mod tests { ); } - /// `moq import ts --passthrough` publishes no renditions, only the `m2ts` section naming one + /// `moq import ts --passthrough` publishes no renditions, only the `mpegts` section naming one /// track, and that track reads back as the input from its first group on. #[tokio::test(start_paused = true)] async fn ts_passthrough_publishes_the_multiplex_on_one_track() { @@ -1819,7 +1839,7 @@ pub(crate) mod tests { } let _decoder = decoder.finish().unwrap(); - let catalog = hang::catalog::Catalog::<()>::subscribe(&consumer) + let catalog = hang::catalog::Catalog::::subscribe(&consumer) .await .unwrap() .next() @@ -1828,11 +1848,11 @@ pub(crate) mod tests { .expect("a catalog") .value; assert!(catalog.video.renditions.is_empty() && catalog.audio.renditions.is_empty()); - let m2ts = catalog.m2ts.expect("the m2ts section"); - assert!(m2ts.random_access); + let passthrough = catalog.ext.mpegts.passthrough.expect("the passthrough track"); + assert!(passthrough.random_access); let mut track = consumer - .track(&m2ts.track) + .track(&passthrough.track) .unwrap() .subscribe( moq_net::track::Subscription::default() @@ -1956,14 +1976,14 @@ pub(crate) mod tests { .unwrap() .unwrap() .unwrap(); - let mut catalogs = hang::catalog::Catalog::<()>::subscribe(&consumer).await.unwrap(); + let mut catalogs = hang::catalog::Catalog::::subscribe(&consumer).await.unwrap(); let catalog = kio::clock::timeout(WAIT, catalogs.next()) .await .unwrap() .unwrap() .expect("a catalog") .value; - let name = catalog.m2ts.expect("the m2ts section").track; + let name = catalog.ext.mpegts.passthrough.expect("the passthrough track").track; // Subscribe and take the first group, so a read starts behind anything decoded // afterwards: an IETF subscription joins the publisher's current group when its @@ -2409,11 +2429,11 @@ pub(crate) mod tests { let event = announced.next().await.expect("origin closed"); assert!(matches!(event, moq_net::announce::Event::Present(_)), "{event:?}"); let broadcast = consumer.request("demo", None).await.unwrap(); - let mut catalogs = hang::catalog::Catalog::<()>::subscribe(&broadcast).await.unwrap(); + let mut catalogs = hang::catalog::Catalog::::subscribe(&broadcast).await.unwrap(); let catalog = catalogs.next().await.unwrap().expect("a catalog").value; - // A passthrough carries the multiplex on one track, named by its m2ts section. - let name = match catalog.m2ts { - Some(m2ts) => m2ts.track, + // A passthrough carries the multiplex on one track, named in the mpegts section. + let name = match catalog.ext.mpegts.passthrough { + Some(passthrough) => passthrough.track, None => catalog.video.renditions.keys().next().expect("a video rendition").clone(), }; broadcast.track(&name).unwrap().subscribe(None).await diff --git a/rs/moq-cli/src/subscribe.rs b/rs/moq-cli/src/subscribe.rs index 961a8f585c6..a2879083ab1 100644 --- a/rs/moq-cli/src/subscribe.rs +++ b/rs/moq-cli/src/subscribe.rs @@ -222,7 +222,7 @@ pub struct SubscribeArgs { /// overriding the catalog's recorded multiplex rate. pub mux_rate: Option, - /// Write the `m2ts` passthrough track back out instead of muxing the media (TS only). + /// Write the passthrough track back out instead of muxing the media (TS only). pub passthrough: bool, /// The file to record to (MP4 only); the other formats write to stdout. @@ -567,7 +567,7 @@ impl Subscribe { } } - /// Write the multiplex the broadcast's `m2ts` track carries, each run of packets as its + /// Write the multiplex the broadcast's passthrough track carries, each run of packets as its /// time on the source's PCR comes round. async fn run_ts_passthrough(self) -> anyhow::Result<()> { let mut stdout = tokio::io::stdout(); diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 19c26efe8f8..084c4d840e6 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -871,7 +871,7 @@ impl MoqMediaCatalogProducer { /// /// `json` is any JSON document. Errors with [`MoqError::Json`] if it doesn't parse, or with /// the reserved-section error if `name` is a HANG root (`video`, `audio`, `sync`, `text`, `json`, - /// `binary`, `stats`, `echo`, `include`, `m2ts`, or the retired `archive`, `clock`, `media`, + /// `binary`, `stats`, `echo`, `include`, or the retired `archive`, `clock`, `media`, /// and `timeline`) or an MSF root (`version`, `generatedAt`, `isComplete`, `tracks`, or /// `initDataList`). pub fn set_section(&self, name: String, json: String) -> Result<(), MoqError> { diff --git a/rs/moq-mux/src/catalog/hang/ext.rs b/rs/moq-mux/src/catalog/hang/ext.rs index f1cc7cdd18c..fd6b6fa7624 100644 --- a/rs/moq-mux/src/catalog/hang/ext.rs +++ b/rs/moq-mux/src/catalog/hang/ext.rs @@ -40,7 +40,7 @@ impl CatalogExt for () {} /// The default extension stays `()` (unknown sections dropped); opt into `Extra` explicitly. /// /// `version`, `video`, `audio`, `sync`, `text`, `archive`, `clock`, `media`, `json`, `binary`, -/// `stats`, `echo`, `include`, `m2ts`, and the retired `timeline` key are reserved, so decoding and +/// `stats`, `echo`, `include`, and the retired `timeline` key are reserved, so decoding and /// [`set`](Self::set) reject them to keep the wire JSON free of duplicate or retired keys. The /// exceptions are a root `clock` and `media`, which each held the clock before `sync`: an older /// publisher's is dropped on decode, so its media still plays. @@ -73,7 +73,7 @@ fn reserved(name: &str) -> bool { | "json" | "binary" | "stats" | "echo" | "include" - | "m2ts" | "timeline" + | "timeline" ) || moq_msf::reserved_root(name) } @@ -100,7 +100,7 @@ impl Extra { /// Set (or replace) a section. Errors if `name` collides with a reserved member of either /// catalog: hang's root `version` and base sections - /// (`video`/`audio`/`sync`/`text`/`archive`/`clock`/`media`/`json`/`binary`/`stats`/`echo`/`include`/`m2ts`), + /// (`video`/`audio`/`sync`/`text`/`archive`/`clock`/`media`/`json`/`binary`/`stats`/`echo`/`include`), /// the retired `timeline` key that the wire format forbids beside `archive`, or a root member /// MSF defines ([`moq_msf::reserved_root`]). /// @@ -238,7 +238,7 @@ mod test { .set_section("timeline", serde_json::json!({})), Err(crate::Error::ReservedSection(_)) )); - for name in ["sync", "media", "clock", "stats", "echo", "include", "m2ts"] { + for name in ["sync", "media", "clock", "stats", "echo", "include"] { assert!( matches!( producer.modify().unwrap().set_section(name, serde_json::json!({})), diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index f19163dfe57..9ecd387fa38 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -86,7 +86,6 @@ impl State { || !catalog.text.renditions.is_empty() || !catalog.json.tracks.is_empty() || !catalog.binary.tracks.is_empty() - || catalog.m2ts.is_some() || self.ext_tracks.is_some_and(|lists| lists(&mut catalog.ext)) || self.owned.iter().any(|((ty, _), &listed)| listed && !base.contains(ty)) } @@ -967,7 +966,7 @@ impl Producer { } /// What each media track minted under this catalog has written, keyed by its catalog key: the - /// rendition ID, or the track name for an `m2ts` or verbatim `mpegts` track. + /// rendition ID, or the track name for a passthrough or verbatim `mpegts` track. /// /// Counters are cumulative for the life of the catalog, so a track that ended keeps its final /// counts and a later track under the same key continues them, until 1,024 keys are held: then @@ -1285,7 +1284,7 @@ impl Guard<'_, Extra> { /// Set (or replace) a top-level application catalog section, republished on drop. /// /// Errors if `name` is a HANG root (`video`, `audio`, `sync`, `text`, `json`, `binary`, - /// `stats`, `echo`, `include`, `m2ts`, or the retired `archive`, `clock`, `media`, and `timeline`) or an + /// `stats`, `echo`, `include`, or the retired `archive`, `clock`, `media`, and `timeline`) or an /// MSF root (`version`, `generatedAt`, `isComplete`, `tracks`, or `initDataList`). pub fn set_section(&mut self, name: impl Into, value: serde_json::Value) -> crate::Result<()> { self.state.catalog.ext.set(name, value)?; @@ -2846,26 +2845,6 @@ mod test { assert!(snapshot.ext.get("mpegts").is_some()); } - /// A passthrough lists its multiplex as `m2ts`, not as a rendition, and that is a track. - #[test] - fn m2ts_counts_as_a_servable_track() { - let mut broadcast = moq_net::broadcast::Info::new().produce(); - let mut catalog = Producer::new(&mut broadcast, Config::default()).unwrap(); - let mut consumer: Consumer = Consumer::new(catalog.outputs.hang_track.consume()); - let waiter = kio::Waiter::noop(); - - let reserved = catalog.reserve(); - catalog - .mutate(|catalog| catalog.m2ts = Some(hang::catalog::M2ts::new("input.m2ts"))) - .unwrap(); - drop(reserved); - let snapshot = match consumer.poll_next(&waiter) { - Poll::Ready(Ok(Some(c))) => c, - other => panic!("expected the passthrough catalog, got {other:?}"), - }; - assert_eq!(snapshot.m2ts.unwrap().track, "input.m2ts"); - } - /// A metadata edit after the last reservation released is still an initial publish, so it waits /// for a track too. #[test] diff --git a/rs/moq-mux/src/container/fmp4/import_test.rs b/rs/moq-mux/src/container/fmp4/import_test.rs index 08dffbec410..73dede8aba7 100644 --- a/rs/moq-mux/src/container/fmp4/import_test.rs +++ b/rs/moq-mux/src/container/fmp4/import_test.rs @@ -2904,7 +2904,12 @@ async fn a_moov_with_nothing_selected_releases_its_reservation() { assert!(clocks.drain().is_empty(), "nothing servable is published"); catalog - .mutate(|catalog| catalog.m2ts = Some(hang::catalog::M2ts::new("input.m2ts"))) + .mutate(|catalog| { + catalog.json.tracks.insert( + "input.json".to_string(), + hang::catalog::JsonConfig::new(hang::catalog::Mode::Snapshot), + ); + }) .unwrap(); assert_eq!(clocks.drain().len(), 1, "no reservation still gates the catalog"); } diff --git a/rs/moq-mux/src/container/ts/catalog.rs b/rs/moq-mux/src/container/ts/catalog.rs index b72691befe7..7036202e9a6 100644 --- a/rs/moq-mux/src/container/ts/catalog.rs +++ b/rs/moq-mux/src/container/ts/catalog.rs @@ -9,7 +9,8 @@ //! Demuxed media tracks keep their codec config in the base `video`/`audio` //! sections; only their MPEG-TS identity lands here. A constant-rate source also //! records its multiplex rate ([`Mpegts::mux_rate`]), so export can pad the rebuilt -//! stream back to it. +//! stream back to it. A multiplex carried whole instead names its one track in +//! [`Mpegts::passthrough`]. //! //! The section is specified by `drafts/draft-lcurley-moq-mpegts.md` and rides the //! root of either catalog: the hang track alongside `video`/`audio`, and the MSF @@ -79,10 +80,11 @@ pub(super) fn si_interval(table_id: u8) -> Option { /// The `mpegts` catalog section. /// /// Omitted from the catalog when empty, so a broadcast that needs none of it stays -/// byte-identical to one without the extension. -#[serde_as] +/// byte-identical to one without the extension. Reading refuses a section that names its +/// [`passthrough`](Self::passthrough) track in [`tracks`](Self::tracks) or [`si`](Self::si) too. +// `remote = "Self"` derives inherent (de)serializers, which the trait impls below wrap. #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] -#[serde(rename_all = "camelCase")] +#[serde(remote = "Self", rename_all = "camelCase")] #[non_exhaustive] pub struct Mpegts { /// Per-track MPEG-TS info, keyed by MoQ track name. Media tracks record their @@ -138,6 +140,32 @@ pub struct Mpegts { /// leaves it absent. Export pads its output with null packets to this rate. #[serde(default, skip_serializing_if = "Option::is_none")] pub mux_rate: Option, + + /// The track carrying the multiplex whole, when a [`Passthrough`](super::Passthrough) + /// publishes it rather than demultiplexing it. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub passthrough: Option, +} + +impl Serialize for Mpegts { + fn serialize(&self, serializer: S) -> Result { + Mpegts::serialize(self, serializer) + } +} + +impl<'de> Deserialize<'de> for Mpegts { + fn deserialize>(deserializer: D) -> Result { + let mpegts = Mpegts::deserialize(deserializer)?; + if let Some(passthrough) = &mpegts.passthrough + && mpegts.names(&passthrough.track) + { + return Err(serde::de::Error::custom(format!( + "the passthrough track `{}` is also described as a demultiplexed one", + passthrough.track + ))); + } + Ok(mpegts) + } } impl Mpegts { @@ -148,19 +176,67 @@ impl Mpegts { && self.program.is_none() && self.si.is_empty() && self.mux_rate.is_none() + && self.passthrough.is_none() } - /// Whether the section lists a track it carries itself: an undecoded stream or an SI table. + /// Whether the section lists a track it carries itself: an undecoded stream, an SI table, or + /// the passthrough. pub(crate) fn has_track(&self) -> bool { - self.tracks - .values() - .any(|track| track.verbatim.is_some() || track.pes_packet.is_some()) + self.passthrough.is_some() + || self + .tracks + .values() + .any(|track| track.verbatim.is_some() || track.pes_packet.is_some()) || self .si .values() .flat_map(BTreeMap::values) .any(|entry| !entry.track.is_empty()) } + + /// Whether `tracks` or `si` names `track`. + fn names(&self, track: &str) -> bool { + self.tracks.contains_key(track) + || self + .si + .values() + .flat_map(BTreeMap::values) + .any(|entry| entry.track == track) + } +} + +/// A transport stream carried whole, as one track of verbatim packets. +/// +/// The track's frames are runs of whole 188-byte packets in source order, each in the legacy +/// container with the PCR time of its first byte. Nothing else about the multiplex is described +/// for it, because all of it stays in-band: the PAT, PMT, and SI ride the track as authored, +/// scrambled payloads included. The section's [`mux_rate`](Mpegts::mux_rate) is measured over +/// every packet of the track. +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct PassthroughTrack { + /// The track carrying the packets, published in the same broadcast as the catalog. + pub track: String, + + /// Whether every group starts at a random access point of the multiplex's video stream, or of + /// its clock PID when it has none, so a subscriber can decode from the first object of any. + /// + /// Only ever true for a single program with at most one video stream: programs or video + /// streams sharing a clock can stagger their GOPs, leaving no packet that starts all of them. + /// Always written; a reader treats it as false when absent. + #[serde(default)] + pub random_access: bool, +} + +impl PassthroughTrack { + /// A passthrough on `track`, with no random access promised. + pub fn new(track: impl Into) -> Self { + Self { + track: track.into(), + random_access: false, + } + } } /// Program identity, from the PAT. @@ -478,6 +554,52 @@ mod test { assert_eq!(serde_json::to_string(&Ext::default()).unwrap(), "{}"); } + #[test] + fn passthrough_roundtrip() { + let mut passthrough = PassthroughTrack::new("0.m2ts"); + passthrough.random_access = true; + let mpegts = Mpegts { + passthrough: Some(passthrough), + mux_rate: Some(2_499_999), + ..Default::default() + }; + + let json = serde_json::to_string(&Ext { mpegts: mpegts.clone() }).unwrap(); + assert_eq!( + json, + r#"{"mpegts":{"muxRate":2499999,"passthrough":{"track":"0.m2ts","randomAccess":true}}}"# + ); + assert_eq!(serde_json::from_str::(&json).unwrap().mpegts, mpegts); + + // `randomAccess` is always written, and read as false when absent. + let json = serde_json::to_string(&PassthroughTrack::new("0.m2ts")).unwrap(); + assert_eq!(json, r#"{"track":"0.m2ts","randomAccess":false}"#); + let read: PassthroughTrack = serde_json::from_str(r#"{"track":"0.m2ts"}"#).unwrap(); + assert_eq!(read, PassthroughTrack::new("0.m2ts")); + serde_json::from_str::(r#"{"randomAccess":true}"#) + .expect_err("a passthrough names its track"); + } + + /// A track is carried whole or demultiplexed, never both, while the two lanes of one source can + /// share the section. + #[test] + fn a_passthrough_track_described_as_demultiplexed_is_refused() { + let passthrough = r#""passthrough":{"track":"0.m2ts","randomAccess":true}"#; + for other in [ + r#""tracks":{"0.m2ts":{"pid":256}}"#, + r#""si":{"17":{"66":{"track":"0.m2ts"}}}"#, + ] { + let json = format!("{{{passthrough},{other}}}"); + serde_json::from_str::(&json).expect_err(&json); + } + + let json = format!( + r#"{{{passthrough},"tracks":{{"0.avc3":{{"pid":256}}}},"program":{{"transportStreamId":1,"programNumber":1,"pmtPid":4096}}}}"# + ); + let mpegts: Mpegts = serde_json::from_str(&json).unwrap(); + assert_eq!(mpegts.passthrough.unwrap().track, "0.m2ts"); + } + #[test] fn section_roundtrip() { let mut mpegts = Mpegts::default(); diff --git a/rs/moq-mux/src/container/ts/mod.rs b/rs/moq-mux/src/container/ts/mod.rs index 217cdec4ce1..d76bfda732b 100644 --- a/rs/moq-mux/src/container/ts/mod.rs +++ b/rs/moq-mux/src/container/ts/mod.rs @@ -19,7 +19,7 @@ //! only the newest group. //! //! [`Passthrough`] is the other shape: it publishes the multiplex whole, every packet -//! verbatim on one track named by the hang catalog's `m2ts` section, for what +//! verbatim on one track named by [`Mpegts::passthrough`], for what //! demultiplexing cannot carry (TS-level scrambling, PSI and SI as authored), and //! [`Release`] writes that track back out on a fixed delay. @@ -47,7 +47,9 @@ mod unclaimed; // they read as `ts::Catalog`, `ts::Mpegts`, ... instead of stuttering under `catalog`. mod catalog; -pub use catalog::{Catalog, Descriptor, Ext, Framing, Mpegts, PesPacket, Program, SiEntry, Track, Verbatim}; +pub use catalog::{ + Catalog, Descriptor, Ext, Framing, Mpegts, PassthroughTrack, PesPacket, Program, SiEntry, Track, Verbatim, +}; pub use error::Error; pub use export::Export; pub use follower::Follower; diff --git a/rs/moq-mux/src/container/ts/passthrough.rs b/rs/moq-mux/src/container/ts/passthrough.rs index 9f4b182bfbc..04a03d37898 100644 --- a/rs/moq-mux/src/container/ts/passthrough.rs +++ b/rs/moq-mux/src/container/ts/passthrough.rs @@ -56,10 +56,11 @@ const VIDEO_STREAM_TYPES: &[u8] = &[ /// Publishes a transport stream verbatim, as one track of whole 188-byte packets. /// -/// Every packet goes out in input order, on the track the catalog's [`m2ts`](hang::catalog::M2ts) -/// section names. It reads the PAT and PMT to find the program clock and the video stream, and -/// reads nothing else past an adaptation field, so a scrambled multiplex groups and paces exactly -/// like its clear twin. +/// Every packet goes out in input order, on the track the catalog's `mpegts` section names in +/// [`passthrough`](super::Mpegts::passthrough), with the multiplex rate in its +/// [`mux_rate`](super::Mpegts::mux_rate). It reads the PAT and PMT to find the program clock and +/// the video stream, and reads nothing else past an adaptation field, so a scrambled multiplex +/// groups and paces exactly like its clear twin. /// /// # Objects and groups /// @@ -77,7 +78,7 @@ const VIDEO_STREAM_TYPES: &[u8] = &[ /// split to meet the bound. /// /// Only the first of these makes a group a random access point, so any other start publishes -/// [`random_access`](hang::catalog::M2ts::random_access) false from then on, as does any group +/// [`random_access`](super::PassthroughTrack::random_access) false from then on, as does any group /// carried while the layout allows no random access (more than one program or video stream). A /// group the PCR discontinuity starts is behind a break even when it is also a random access /// point. @@ -106,7 +107,10 @@ const VIDEO_STREAM_TYPES: &[u8] = &[ /// needs a new broadcast. The timeline therefore depends only on the bytes since the importer's /// first PCR and its shift, and two importers of one feed started at the same packet each placing /// its own catalog's clock publish identical objects. -pub struct Passthrough { +/// +/// The catalog's extension must carry the `mpegts` section ([`Catalog`](super::Catalog)), such as +/// [`Ext`](super::Ext): [`new`](Self::new) refuses one that does not. +pub struct Passthrough { catalog: crate::catalog::Producer, /// Held until the first group is written, so the first catalog already names the track with /// its final `randomAccess`. @@ -158,17 +162,24 @@ pub struct Passthrough { mux_rate: Meter, } -/// Owns the `m2ts` catalog section once written, removing it however the track ends, as the +/// Owns the passthrough's catalog entry once written, removing it however the track ends, as the /// demultiplexed lane's catalog entries are. -struct Section { +struct Section { catalog: crate::catalog::Producer, - written: hang::catalog::M2ts, + written: Written, +} + +/// What a passthrough last wrote into the `mpegts` section. +#[derive(Clone, PartialEq)] +struct Written { + track: super::PassthroughTrack, + mux_rate: Option, } /// A passthrough that [finished](Passthrough::finish): its track has ended, and it can still be /// read or aborted, but it takes no more input. /// -/// Dropping it releases the track and removes the catalog's `m2ts` section. +/// Dropping it releases the track and removes it from the catalog's `mpegts` section. /// /// ```compile_fail,E0599 /// # fn cannot_decode(mut passthrough: moq_mux::container::ts::passthrough::Finished) { @@ -176,11 +187,11 @@ struct Section { /// # } /// ``` #[must_use = "dropping it releases the track and its catalog section"] -pub struct Finished { +pub struct Finished { passthrough: Passthrough, } -impl Finished { +impl Finished { /// The name of the track carrying the packets. pub fn track(&self) -> &str { self.passthrough.track() @@ -193,10 +204,16 @@ impl Finished { } } -impl Drop for Section { +impl Drop for Section { fn drop(&mut self) { - // A closed catalog has nothing left to remove it from. - let _ = self.catalog.mutate(|catalog| catalog.m2ts = None); + // A closed catalog has nothing left to remove it from. The rate stays: it is the + // multiplex's, which a demultiplexing importer of the same source may also write, and + // that importer leaves it in place when it ends too. + let _ = self.catalog.mutate(|catalog| { + if let Some(mpegts) = catalog.ext.mpegts_mut() { + mpegts.passthrough = None; + } + }); } } @@ -271,11 +288,22 @@ struct Group { objects: usize, } -impl Passthrough { +impl Passthrough { /// A passthrough importer publishing one track on `broadcast`, listed in the catalog behind /// `reserved`. + /// + /// Fails with [`NoMpegtsSection`](crate::Error::NoMpegtsSection) when the catalog's extension + /// carries no `mpegts` section to list the track in. pub fn new(broadcast: moq_net::broadcast::Producer, reserved: crate::catalog::Reserved) -> crate::Result { let catalog = reserved.producer(); + let mut snapshot = catalog.snapshot(); + let Some(mpegts) = snapshot.ext.mpegts_mut() else { + return Err(crate::Error::NoMpegtsSection); + }; + // A rate the catalog already records measured this multiplex; the meter confirms, + // replaces, or clears it. + let measured = mpegts.mux_rate; + catalog.count_ext_tracks(|ext: &mut E| ext.mpegts_mut().is_some_and(|mpegts| mpegts.has_track())); let track = broadcast.unique_track(".m2ts", catalog.track_info(hang::catalog::PRIORITY.video))?; let media = catalog.media_raw( track, @@ -306,7 +334,7 @@ impl Passthrough { written: 0, groups: Groups::Waiting(None), all_random_access: true, - mux_rate: Meter::default(), + mux_rate: Meter::measured(measured), }) } @@ -340,7 +368,7 @@ impl Passthrough { /// [`Finished`] passthrough. /// /// No later PCR will arrive, so the objects since the last one are timed at the rate of the - /// interval before it. The catalog keeps the `m2ts` section until the [`Finished`] passthrough + /// interval before it. The catalog keeps listing the track until the [`Finished`] passthrough /// drops. /// /// A finish that fails ends the track with an error, so it can't be retried. @@ -669,24 +697,40 @@ impl Passthrough { Ok(()) } - /// Write the section to the catalog if it changed. Nothing is written before the first group. + /// Write the track and rate to the catalog if they changed. Nothing is written before the first + /// group. fn record(&mut self) -> crate::Result<()> { if matches!(self.groups, Groups::Waiting(_)) && self.section.is_none() { return Ok(()); } - let mut section = hang::catalog::M2ts::new(self.media.name()); - section.random_access = self.single && self.all_random_access; - section.mux_rate = self.mux_rate.published(); - if self.section.as_ref().is_some_and(|written| written.written == section) { + let mut track = super::PassthroughTrack::new(self.media.name()); + track.random_access = self.single && self.all_random_access; + let written = Written { + track, + mux_rate: self.mux_rate.published(), + }; + if self.section.as_ref().is_some_and(|section| section.written == written) { return Ok(()); } - self.catalog.mutate(|catalog| catalog.m2ts = Some(section.clone()))?; + // The demultiplexing lane of the same source may record the rate too, so write it only + // when this meter's own value changes: one that has measured nothing leaves it alone. + let rate_changed = self.section.as_ref().and_then(|section| section.written.mux_rate) != written.mux_rate; + let update = written.clone(); + self.catalog.mutate(|catalog| { + // `new` checked the section exists, and an extension keeps it for its life. + if let Some(mpegts) = catalog.ext.mpegts_mut() { + mpegts.passthrough = Some(update.track); + if rate_changed { + mpegts.mux_rate = update.mux_rate; + } + } + })?; match &mut self.section { - Some(written) => written.written = section, + Some(section) => section.written = written, None => { self.section = Some(Section { catalog: self.catalog.clone(), - written: section, + written, }) } } diff --git a/rs/moq-mux/src/container/ts/passthrough_test.rs b/rs/moq-mux/src/container/ts/passthrough_test.rs index ffe15ab644d..e68c192f48f 100644 --- a/rs/moq-mux/src/container/ts/passthrough_test.rs +++ b/rs/moq-mux/src/container/ts/passthrough_test.rs @@ -11,6 +11,7 @@ use bytes::Bytes; use super::fixture::{ACCESS, Flags, MS, Mux, WRAP, paced, program}; use super::passthrough::{GROUP_BYTES_MAX, GROUP_OBJECTS_MAX, Passthrough}; +use super::{Ext, PassthroughTrack}; /// A delay budget no test timeline comes close to, so the reader sees every group. const RECORDING_MAX_DELAY: Duration = Duration::from_secs(30); @@ -27,7 +28,7 @@ struct Object { } struct Imported { - catalog: hang::catalog::Catalog, + catalog: hang::catalog::Catalog, objects: Vec, /// The start of each break marker: a group of one object with no bytes. markers: Vec, @@ -46,8 +47,13 @@ impl Imported { bytes } - fn section(&self) -> &hang::catalog::M2ts { - self.catalog.m2ts.as_ref().expect("an m2ts section") + fn section(&self) -> &PassthroughTrack { + self.catalog + .ext + .mpegts + .passthrough + .as_ref() + .expect("a passthrough track") } /// Each group's objects. @@ -63,17 +69,22 @@ impl Imported { } } +/// A catalog carrying the `mpegts` section a passthrough lists its track in. +fn config() -> crate::catalog::Config { + crate::catalog::Config::default().with_catalog(hang::catalog::Catalog::::default()) +} + /// Import `data` in chunks of `chunk` bytes and read back every object. async fn import(data: &[u8], chunk: usize, pcr_pid: Option) -> crate::Result { let mut broadcast = moq_net::broadcast::Info::new().produce(); - let catalog = crate::catalog::Producer::new(&mut broadcast, Default::default())?; + let catalog = crate::catalog::Producer::new(&mut broadcast, config())?; import_onto(broadcast, catalog, data, chunk, pcr_pid).await } /// [`import`] onto an existing `catalog` of `broadcast`. async fn import_onto( broadcast: moq_net::broadcast::Producer, - catalog: crate::catalog::Producer, + catalog: crate::catalog::Producer, data: &[u8], chunk: usize, pcr_pid: Option, @@ -257,7 +268,7 @@ async fn objects_do_not_depend_on_how_the_input_is_chunked() { for chunk in [7, 188, 1316, 65_536] { let chunked = import(KYRION_H264, chunk, None).await.unwrap(); assert_eq!(chunked.objects, whole.objects, "chunks of {chunk}"); - assert_eq!(chunked.catalog.m2ts, whole.catalog.m2ts, "chunks of {chunk}"); + assert_eq!(chunked.catalog.ext, whole.catalog.ext, "chunks of {chunk}"); } } @@ -271,7 +282,7 @@ async fn leading_junk_does_not_hide_the_grid() { for chunk in [7, 188, 1316, 65_536, data.len()] { let imported = import(&data, chunk, None).await.unwrap(); assert_eq!(imported.objects, clean.objects, "chunks of {chunk}"); - assert_eq!(imported.catalog.m2ts, clean.catalog.m2ts, "chunks of {chunk}"); + assert_eq!(imported.catalog.ext, clean.catalog.ext, "chunks of {chunk}"); } } @@ -316,7 +327,7 @@ async fn a_scrambled_twin_groups_and_paces_the_same() { .collect::>() }; assert_eq!(shape(&twin), shape(&clear)); - assert_eq!(twin.catalog.m2ts, clear.catalog.m2ts); + assert_eq!(twin.catalog.ext, clear.catalog.ext); } #[tokio::test(start_paused = true)] @@ -513,23 +524,37 @@ async fn objects_after_the_last_pcr_extrapolate_its_rate() { } } +/// A catalog without the `mpegts` section has nowhere to list the track. +#[test] +fn a_catalog_without_the_section_is_refused() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = crate::catalog::Producer::new(&mut broadcast, Default::default()).unwrap(); + assert!( + Passthrough::new(broadcast, catalog.reserve()).is_err(), + "a catalog without the mpegts section must be refused" + ); +} + /// The section describes the track for as long as the importer lives, however the track ends. #[tokio::test(start_paused = true)] async fn the_section_goes_with_the_importer() { for abort in [false, true] { let mut broadcast = moq_net::broadcast::Info::new().produce(); - let catalog = crate::catalog::Producer::new(&mut broadcast, Default::default()).unwrap(); + let catalog = crate::catalog::Producer::new(&mut broadcast, config()).unwrap(); let mut passthrough = Passthrough::new(broadcast.clone(), catalog.reserve()).unwrap(); passthrough.decode(KYRION_H264).unwrap(); - assert!(catalog.snapshot().m2ts.is_some(), "abort {abort}"); + assert!(catalog.snapshot().ext.mpegts.passthrough.is_some(), "abort {abort}"); if abort { passthrough.abort(moq_net::Error::Cancel); } else { let passthrough = passthrough.finish().unwrap(); - assert!(catalog.snapshot().m2ts.is_some(), "a finished track is still described"); + assert!( + catalog.snapshot().ext.mpegts.passthrough.is_some(), + "a finished track is still described" + ); drop(passthrough); } - assert!(catalog.snapshot().m2ts.is_none(), "abort {abort}"); + assert!(catalog.snapshot().ext.mpegts.passthrough.is_none(), "abort {abort}"); } } @@ -619,7 +644,7 @@ async fn an_import_shifts_onto_a_clock_already_in_use() { let verbatim = import(&data, data.len(), None).await.unwrap(); let mut broadcast = moq_net::broadcast::Info::new().produce(); - let catalog = crate::catalog::Producer::new(&mut broadcast, Default::default()).unwrap(); + let catalog = crate::catalog::Producer::new(&mut broadcast, config()).unwrap(); let clock = catalog.clock(); let fixed = catalog.snapshot().sync.clock; tokio::time::advance(Duration::from_secs(5)).await; @@ -830,11 +855,53 @@ async fn a_192_or_204_byte_source_is_refused() { async fn a_cbr_source_records_its_mux_rate() { let data = include_bytes!("test_data/bbb_cbr.ts"); let imported = import(data, data.len(), None).await.unwrap(); - let rate = imported.section().mux_rate.expect("a CBR source records its mux rate"); + let rate = imported + .catalog + .ext + .mpegts + .mux_rate + .expect("a CBR source records its mux rate"); assert!(rate.abs_diff(400_000) * 1000 <= 400_000, "{rate}"); assert_suffix(data, &imported); } +/// The demultiplexing lane of the same source may record the rate first; a passthrough that has +/// measured none keeps it. +#[tokio::test(start_paused = true)] +async fn a_passthrough_without_a_rate_keeps_the_recorded_one() { + let mut mux = Mux::default(); + program(&mut mux, 0x100); + paced(&mut mux, 0x100, 0, 50, 10, 4); + let data = mux.bytes(); + let alone = import(&data, data.len(), None).await.unwrap(); + assert_eq!(alone.catalog.ext.mpegts.mux_rate, None, "too short to measure"); + assert!(!alone.objects.is_empty()); + + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, config()).unwrap(); + catalog + .mutate(|catalog| catalog.ext.mpegts.mux_rate = Some(400_000)) + .unwrap(); + let imported = import_onto(broadcast, catalog, &data, data.len(), None).await.unwrap(); + assert!(imported.catalog.ext.mpegts.passthrough.is_some()); + assert_eq!(imported.catalog.ext.mpegts.mux_rate, Some(400_000)); +} + +/// A rate recorded before the passthrough started is one it measures again, and a variable-rate +/// multiplex clears it. +#[tokio::test(start_paused = true)] +async fn a_vbr_passthrough_clears_a_recorded_rate() { + let data = include_bytes!("test_data/scte35/bbb5s.ts"); + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, config()).unwrap(); + catalog + .mutate(|catalog| catalog.ext.mpegts.mux_rate = Some(400_000)) + .unwrap(); + let imported = import_onto(broadcast, catalog, data, data.len(), None).await.unwrap(); + assert_eq!(imported.catalog.ext.mpegts.mux_rate, None); + assert_suffix(data, &imported); +} + #[tokio::test(start_paused = true)] async fn an_overriding_clock_paces_on_its_own_pcrs() { let mut mux = Mux::default(); diff --git a/rs/moq-mux/src/container/ts/release.rs b/rs/moq-mux/src/container/ts/release.rs index 8f7c18d0360..1d27b30dde8 100644 --- a/rs/moq-mux/src/container/ts/release.rs +++ b/rs/moq-mux/src/container/ts/release.rs @@ -11,12 +11,13 @@ use super::export; #[cfg(feature = "async")] use crate::catalog::CatalogFormat; use crate::catalog::Stream; +use crate::catalog::hang::Catalog; use crate::container::consumer::Event; use crate::container::{ExportSource, Frame}; use crate::jitter::{self, Arrival, Push}; -/// Writes the multiplex a broadcast's [`m2ts`](hang::catalog::M2ts) track carries back out -/// byte-identical, each object a fixed delay after its PCR time, like an SRT receiver. +/// Writes the multiplex a broadcast's [passthrough track](super::Mpegts::passthrough) carries +/// back out byte-identical, each object a fixed delay after its PCR time, like an SRT receiver. /// /// The [importer](super::Passthrough) stamps each object, the packets from one PCR to the /// next, with the PCR time of its first byte on the catalog clock. The release holds every @@ -29,8 +30,8 @@ use crate::jitter::{self, Arrival, Push}; /// wait it out; the bytes carry the jump. pub struct Release { source: crate::Source, - catalog: Option>, - /// The `m2ts` track, once a catalog names it. + catalog: Option>, + /// The passthrough track, once a catalog names it. track: Option<(String, ExportSource)>, /// When the track was subscribed. Nothing it delivers reached the release before then, /// however long the cache held it. @@ -44,16 +45,12 @@ pub struct Release { } impl Release { - /// Subscribe to the catalog of `source`, waiting for the `m2ts` section that names its track. + /// Subscribe to the catalog of `source`, in either format, waiting for the `mpegts` section to + /// name its passthrough track. /// /// Each object is written `delay` after its PCR time; late objects are dropped. - /// - /// Fails for [`CatalogFormat::Msf`], which has no `m2ts` section. #[cfg(feature = "async")] pub async fn new(source: crate::Source, catalog_format: CatalogFormat, delay: Duration) -> crate::Result { - if catalog_format == CatalogFormat::Msf { - return Err(unsupported!("the MSF catalog has no `m2ts` passthrough track; read the hang catalog").into()); - } let mut subscribing = crate::catalog::Subscribing::new(&source.broadcast(), catalog_format); let catalog = kio::wait(|waiter| subscribing.poll_ok(waiter)).await?; let mut jitter = jitter::Buffer::new(delay); @@ -186,30 +183,32 @@ impl Release { } } - /// Subscribe to the track the catalog's `m2ts` section names, the first time it names one. - fn update_catalog(&mut self, catalog: &crate::catalog::hang::Catalog<()>) -> crate::Result<()> { - let Some(m2ts) = &catalog.m2ts else { + /// Subscribe to the passthrough track the catalog names, the first time it names one. + fn update_catalog(&mut self, catalog: &Catalog) -> crate::Result<()> { + let Some(passthrough) = &catalog.ext.mpegts.passthrough else { if self.track.is_none() && !(catalog.video.renditions.is_empty() && catalog.audio.renditions.is_empty()) { - return Err(unsupported!( - "the broadcast is demultiplexed, with no `m2ts` passthrough track to release" - ) - .into()); + return Err( + unsupported!("the broadcast is demultiplexed, with no passthrough track to release").into(), + ); } return Ok(()); }; match &self.track { None => { - let source = ExportSource::for_stream(&self.source, &m2ts.track, export::subscribed(self.delay))?; + let source = + ExportSource::for_stream(&self.source, &passthrough.track, export::subscribed(self.delay))?; let source = export::skipping(source, self.delay); let source = match self.replay { true => source, false => source.live(), }; - self.track = Some((m2ts.track.clone(), source)); + self.track = Some((passthrough.track.clone(), source)); self.subscribed = kio::clock::now(); } - Some((name, _)) if *name != m2ts.track => { - return Err(unsupported!("the `m2ts` track moved from `{name}` to `{}`", m2ts.track).into()); + Some((name, _)) if *name != passthrough.track => { + return Err( + unsupported!("the passthrough track moved from `{name}` to `{}`", passthrough.track).into(), + ); } Some(_) => {} } diff --git a/rs/moq-mux/src/container/ts/release_test.rs b/rs/moq-mux/src/container/ts/release_test.rs index 9ad5c650e97..03cb4cdef03 100644 --- a/rs/moq-mux/src/container/ts/release_test.rs +++ b/rs/moq-mux/src/container/ts/release_test.rs @@ -10,7 +10,7 @@ use bytes::Bytes; use kio::clock::Instant; use super::oracle::{Admitted, Loss, Object}; -use super::{Passthrough, Release, fixture}; +use super::{Ext, Passthrough, PassthroughTrack, Release, fixture}; use crate::catalog::CatalogFormat; use crate::container::Frame; @@ -28,15 +28,20 @@ const TOLERANCE: Duration = Duration::from_millis(1); /// A capture imported whole, with what keeps its broadcast up. struct Imported { _passthrough: crate::container::ts::passthrough::Finished, - _catalog: crate::catalog::Producer, + _catalog: crate::catalog::Producer, _broadcast: moq_net::broadcast::Producer, consumer: moq_net::broadcast::Consumer, objects: Vec, } +/// A catalog carrying the `mpegts` section a passthrough lists its track in. +fn config() -> crate::catalog::Config { + crate::catalog::Config::default().with_catalog(hang::catalog::Catalog::::default()) +} + async fn import(data: &[u8]) -> Imported { let mut broadcast = moq_net::broadcast::Info::new().produce(); - let catalog = crate::catalog::Producer::new(&mut broadcast, Default::default()).unwrap(); + let catalog = crate::catalog::Producer::new(&mut broadcast, config()).unwrap(); let consumer = broadcast.consume(); let mut passthrough = Passthrough::new(broadcast.clone(), catalog.reserve()).unwrap(); let name = passthrough.track().to_string(); @@ -100,7 +105,7 @@ fn skips(objects: &[Object]) -> Vec> { .collect() } -/// Republish `objects` on a new broadcast's `m2ts` track, in the groups they were published in, +/// Republish `objects` on a new broadcast's passthrough track, in the groups they were published in, /// each once `at` says it is due after the start and not before the one ahead of it, as a relay /// delivering them would, skipping the starts between them as the importer did. fn republish(objects: Vec, at: impl Fn(usize, &Object) -> Duration + Send + 'static) -> Republished { @@ -120,13 +125,13 @@ fn republish_cut( ) -> Republished { let cut = cut.to_vec(); let mut broadcast = moq_net::broadcast::Info::new().produce(); - let mut catalog = crate::catalog::Producer::new(&mut broadcast, Default::default()).unwrap(); + let mut catalog = crate::catalog::Producer::new(&mut broadcast, config()).unwrap(); let track = broadcast .unique_track(".m2ts", catalog.track_info(hang::catalog::PRIORITY.video)) .unwrap(); let name = track.name().to_string(); catalog - .mutate(|catalog| catalog.m2ts = Some(hang::catalog::M2ts::new(name))) + .mutate(|catalog| catalog.ext.mpegts.passthrough = Some(PassthroughTrack::new(name))) .unwrap(); let consumer = broadcast.consume(); let start = Instant::now(); @@ -227,19 +232,21 @@ fn payloads(released: &[(Instant, Frame)]) -> Vec { bytes(released.iter().map(|(_, frame)| &frame.payload)) } +/// Either catalog names the track: the `mpegts` section rides both. #[tokio::test(start_paused = true)] async fn a_capture_is_released_byte_identical_on_its_own_pcr() { - for data in [KYRION, KYRION_H264] { + for (data, format) in [ + (KYRION, CatalogFormat::Hang), + (KYRION_H264, CatalogFormat::Hang), + (KYRION, CatalogFormat::Msf), + ] { let imported = import(data).await; let source = crate::source::announced(&imported.consumer).await; - let release = Release::new(source, CatalogFormat::Hang, RECORDING) - .await - .unwrap() - .with_replay(); + let release = Release::new(source, format, RECORDING).await.unwrap().with_replay(); let (released, release) = drain(release).await; let admitted = Admitted::new(data, &imported.objects); - assert_eq!(admitted.grade(&released, TOLERANCE), Loss::default()); + assert_eq!(admitted.grade(&released, TOLERANCE), Loss::default(), "{format:?}"); assert_eq!(release.dropped(), 0); } } @@ -494,17 +501,6 @@ fn pids(data: &[u8]) -> std::collections::BTreeSet { .collect() } -/// The MSF catalog never names the `m2ts` track, so a release reading it would wait forever. -#[tokio::test(start_paused = true)] -async fn an_msf_catalog_is_refused() { - let imported = import(KYRION).await; - let source = crate::source::announced(&imported.consumer).await; - let Err(err) = Release::new(source, CatalogFormat::Msf, std::time::Duration::ZERO).await else { - panic!("a release reading the MSF catalog must fail"); - }; - assert!(err.to_string().contains("MSF"), "{err}"); -} - /// Objects received while a sink stalls stay in the source and retain their arrival bound. #[tokio::test(start_paused = true)] async fn a_backlog_stays_in_the_source_until_due() { diff --git a/rs/moq-mux/src/error.rs b/rs/moq-mux/src/error.rs index 0b7337c53cb..1030d345182 100644 --- a/rs/moq-mux/src/error.rs +++ b/rs/moq-mux/src/error.rs @@ -248,6 +248,11 @@ pub enum Error { #[error("capture time is outside the broadcast clock")] InvalidCapture, + /// A transport stream passthrough's catalog extension carries no `mpegts` section to list its + /// track in. + #[error("a passthrough lists its track in the `mpegts` section, which the catalog extension does not carry")] + NoMpegtsSection, + /// A transport stream passthrough was fed packets other than 188 bytes. /// /// A 192-byte source (BDAV M2TS, a four-byte timestamp before each packet) or a 204-byte one diff --git a/rs/moq-mux/src/import/format.rs b/rs/moq-mux/src/import/format.rs index d94fa39d091..a0a0cedbc5a 100644 --- a/rs/moq-mux/src/import/format.rs +++ b/rs/moq-mux/src/import/format.rs @@ -136,8 +136,7 @@ impl FromStr for Format { "fmp4" | "cmaf" => Format::Container(ContainerFormat::Fmp4), "mkv" | "webm" | "matroska" => Format::Container(ContainerFormat::Mkv), - // Not `m2ts`: that names the catalog section carrying a multiplex whole, and BDAV's - // 192-byte packets besides. + // Not `m2ts`, which names BDAV's 192-byte packets rather than 188-byte TS. "ts" | "mpegts" | "mpeg2ts" => Format::Container(ContainerFormat::Ts), "flv" => Format::Container(ContainerFormat::Flv),