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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -335,8 +335,14 @@ On moq-lite 07, two processes that pass the same `--epoch` (a UUIDv7, such as
`uuidgen -7` prints) are one publisher: relays fail over between them
mid-group, so they must produce identical tracks with aligned groups. Each
derives its catalog clock from the epoch's wall time, so fed one stream they
publish the same clock and timestamps wherever each started, without reading
anything from the other; group numbering is not aligned yet. PTS zero is the
publish the same clock, timestamps, and media groups wherever each started,
without reading anything from the other; the catalog and timeline tracks are not
aligned yet. Every media track groups on that clock's one-second
grid: a group opens at the first place one may start in a second (a keyframe,
or any audio frame or data unit) and takes that second's number, later ones in
the second join it, and a second with none gets an empty group. A process
publishes nothing from the second it started in, and a source's timestamp break
publishes no break marker, only the jump. PTS zero is the
epoch's time, and for `ts` one 33-bit wrap before it. The wall mapping is
therefore off by the source clock's reading at the epoch's time: for a TS
program clock, anywhere within 13.25 hours. Each process picks a TS timestamp's
Expand Down
7 changes: 4 additions & 3 deletions doc/concept/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,9 +170,10 @@ service. The root `m2ts` section names the one track holding it:

Each frame is a run of whole 188-byte packets in input order, timestamped on
the multiplex's own PCR clock, which never steps back: a source whose clock
steps back is a new broadcast. `randomAccess` says whether every group begins
where a receiver can start decoding, and `muxRate` is the constant multiplex
rate in bits per second, absent for a variable-rate source. A player has
steps back is a new broadcast. `randomAccess` says whether every group of the
latest two-second window began where a receiver can start decoding, and
`muxRate` is that window's 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
[moq-cli](/bin/cli)); the encoding is in
[draft-lcurley-moq-mpegts](/draft/moq-mpegts).
Expand Down
3 changes: 2 additions & 1 deletion doc/setup/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ These land with the next breaking release.

- **Data-track breaks are an object with no bytes** (#5815). A hang data
track (TS verbatim PES, sections, `m2ts`, text) marks a discontinuity with a
group of one empty object instead of a skipped group. Older consumers fail
group of one empty object instead of a skipped group. Publishers sharing an
`--epoch` mark none on any track: their timestamps jump. Older consumers fail
to decode it, so upgrade exporters and players before publishers.
- **Auth requests name `webtransport`** (#5293). Relays report a WebTransport
session as `webtransport` instead of `quic`, and older auth servers reject the
Expand Down
29 changes: 21 additions & 8 deletions drafts/draft-lcurley-moq-mpegts.md
Original file line number Diff line number Diff line change
Expand Up @@ -278,10 +278,10 @@ type M2ts = {
`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 of the latest window the section describes started at a random access point ({{m2ts-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.
`muxRate` follows {{field-mux-rate}}, measured over every packet of that window.

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.
Expand All @@ -302,27 +302,38 @@ 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;
- otherwise, the first PCR at least one second of PCR time after the group's start;
- the first PCR at or past a whole second of the PCR count ({{m2ts-timestamps}}), unless a random access point or a forward jump fell in the second before it, each counted at the PCR before it (its own, if its packet carries one);
- 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.
Before its first group, a publisher starts one at a second only once it has watched the whole second before it, the PMT of the clock's program read and a PCR seen, so it never cuts where a publisher running longer saw a random access point.
A flagged first PCR counts as a forward jump, since a publisher running longer counted that jump, or the one it retransmits, at the same PCR.

The section describes two-second windows of the PCR count, each holding the PCR intervals that start in it.
As the count passes each window, from the first that starts after the PCR the publisher's first group follows, the section takes that window's values; a window whose values match the last one's leaves the catalog unchanged.
An input that ends before its first such window takes `randomAccess` from every group it carried and `muxRate` from the window in progress.
For a window, `randomAccess` is true only if the PAT listed one program, its PMT declared at most one video stream, and the clock PID was that PMT's `PCR_PID` throughout it, and every group it started began at a `random_access_indicator`.
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.

Publishers that share an epoch and number each group by the second of the catalog clock it starts in, so that each publishes the same groups under the same sequences, differ from the rules above in four ways.
The grid lines are the catalog clock's whole seconds.
A group opens only at the first start in a second no group has taken, and later starts in that second join it, a flagged jump's included: such a group can contain a PCR discontinuity, and no discontinuity marker precedes the jump, which a consumer sees as the timestamps' step, or as a sequence hole ({{hang}}) when the jump skips whole seconds.
A second with no start gets an empty group.
A group that reaches the size bound ends the track with an error, since it cannot be split.

## Timestamps {#m2ts-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.

PCRs are unwrapped into a 64-bit count of 27 MHz ticks, and timestamps never decrease.
A step forward of at most half the 2^33 × 300 tick period adds to the count, across the wrap included, so a wrap is not a discontinuity.
A PCR with `discontinuity_indicator` set whose step is forward by that measure adds its step too, after the bytes before it are timed at the rate before it, and the group it starts MUST follow hang's discontinuity marker ({{hang}}).
Each PCR takes the number of 2^33 × 300 tick wraps that lands it nearest the current time on the catalog clock ({{hang}}), so the count runs on across the wrap, which is not a discontinuity, and a PCR more than half a wrap ahead of that time lands a wrap back.
A PCR with `discontinuity_indicator` set that lands at or past the one before it adds its step too, after the bytes before it are timed at the rate before it, and the group it starts MUST follow hang's discontinuity marker ({{hang}}), unless the publisher numbers groups by the second ({{m2ts-groups}}).
A PCR that steps backwards MUST end the track with an error, flagged or not: a flagged one is a restart, which is new content, so a publisher that carries on publishes it as a new broadcast.

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.
The count therefore depends only on the bytes and the catalog clock, so publishers of one input whose catalog clocks agree publish identical frames, group boundaries, and sections wherever each started, from the later one's first group on.

## Mapping onto MSFTS {#m2ts-msfts}
Stripping each frame's timestamp leaves an {{msfts}} object of whole source packets, and the groups carry over unchanged.
Expand Down Expand Up @@ -443,6 +454,8 @@ A broadcast demultiplexed from a DVB transport stream: video and audio described
- Added the `m2ts` section, a transport stream carried whole, with its mapping onto MSFTS; the comparison uses MSFTS's `mpeg2ts` names.
- Added the `pesPacket` record: each frame one whole PES packet, timestamped with its placement. A consumer that predates it drops the track rather than refusing the catalog.
- A flagged PCR jump on an `m2ts` track follows hang's discontinuity marker rather than a skipped group sequence.
- An `m2ts` track's fallback cut falls on whole seconds of a PCR count whose wraps follow the catalog clock, and `randomAccess` and `muxRate` describe the latest two-second window rather than the whole track, so publishers sharing a clock cut and describe the multiplex alike.
- Publishers sharing an epoch may number `m2ts` groups by the catalog clock's second, which lets a flagged PCR jump join a group without a discontinuity marker.

## draft-lcurley-moq-mpegts-00
{:numbered="false"}
Expand Down
1 change: 0 additions & 1 deletion quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@ ranked just below deterministic TS legs, which it requires.
- [Release execution](/quest/m2/release/README.md) - publication, installed-artifact proof, cleanup, and downstream adoption after m1
- [P2P](/quest/m2/p2p/README.md) - application-selected peer sessions use shared priorities, routing, and same-epoch handover
- [Epoch anchor](/quest/m2/epoch-anchor.md) - same-epoch importers each derive the catalog clock and timestamp era from the epoch and stay live, so they agree across a 33-bit wrap, a forward clock break, and a restart
- [Raw TS cuts on the epoch timeline](/quest/m2/ts-passthrough-epoch-cuts.md) - passthrough fallback cuts fall on the epoch's grid and the M2ts section derives from the epoch and content, so instances started apart publish identical groups and catalogs
- [Same-epoch importers](/quest/m2/hop-aligned-import.md) - importers sharing one `--epoch` and fed one stream publish identical groups and timestamps, so failover between a redundant pair survives
- [Hard-fork the binding generator](/quest/m2/uniffi-fork.md) - one moq-dev repo holds the chosen generator's core and every language backend, released under one tag and one pin
- [Benchmark trend site](/quest/m2/bench-site.md) - a GitHub Pages site charts the binding, Rust, and JS nightly benchmarks over time
Expand Down
6 changes: 2 additions & 4 deletions quest/m2/epoch-anchor.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,10 +80,8 @@ precondition.
`Clock::wall_clock` never enters it.
- Every catalog field an importer derives from its history rather than the
content at hand derives from the epoch and the content instead (maintainer,
superseding #5412's adoption from the live catalog). In TS passthrough that
is the M2ts section's `random_access` and recorded `mux_rate`, owned by
[raw TS cuts](/quest/m2/ts-passthrough-epoch-cuts.md); audit the other
importers for more.
superseding #5412's adoption from the live catalog). TS passthrough's M2ts
section already does; audit the other importers for more.
- A restart under the same epoch re-derives the same coordinate, including
after a total outage, so the epoch keeps naming one timeline and resuming
across the outage is a gap, not a stitch (maintainer, reversing #5412's
Expand Down
1 change: 0 additions & 1 deletion quest/m2/hop-aligned-import.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,6 @@ stopping and restarting; repeat it with `--passthrough`.
## Required

- [Epoch anchor](/quest/m2/epoch-anchor.md) - every importer derives one catalog clock and timestamp era from the epoch
- [Raw TS cuts on the epoch timeline](/quest/m2/ts-passthrough-epoch-cuts.md) - passthrough groups start where every instance cuts

## Related

Expand Down
67 changes: 0 additions & 67 deletions quest/m2/ts-passthrough-epoch-cuts.md

This file was deleted.

9 changes: 5 additions & 4 deletions rs/hang/src/catalog/m2ts.rs
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,18 @@ 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 one video stream,
/// so a subscriber can decode from the first object of any group.
/// Whether every group the publisher's latest two-second window started began 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 of them.
///
/// 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.
/// The rate the source's PCR paced the whole multiplex at over that window, in bits per
/// second, null packets included. Present only while the source holds a constant rate.
#[serde(default)]
pub mux_rate: Option<u64>,
}
Expand Down
3 changes: 2 additions & 1 deletion rs/moq-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -446,7 +446,8 @@ pub struct MoqSide {
/// then off by the source clock's reading at the epoch's time, which for a TS program
/// clock is anywhere within half a wrap. Near either end of that range, processes whose
/// clocks or delivery differ can place one timestamp a wrap apart, and redundant `flv`
/// imports stop matching at FLV's 49.7-day millisecond wrap.
/// imports stop matching at FLV's 49.7-day millisecond wrap. Groups are numbered by the
/// second of that clock they open in, so the publishers agree on those too.
#[usage(long, env = "MOQ_EPOCH", help_heading = "MoQ")]
pub epoch: Option<hang::moq_net::Epoch>,

Expand Down
Loading
Loading