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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

44 changes: 15 additions & 29 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,10 +85,9 @@ to the wall time the first frame arrived. A timeline that rewinds, such as a
restarted encoder or a looping file wrapping to the top, ends the import with
an error; run it again to publish anew. A flagged MPEG-TS discontinuity that
jumps forward continues the broadcast and is declared on the exported clock.
MPEG-TS timestamps run on across their 33-bit wrap (every 26.5 hours), each
taking the wrap that lands it nearest the clock, so media that gets more than
13.25 hours ahead of it (a jump that far, or a long file read faster than real
time) reads as a rewind.
MPEG-TS timestamps follow their source history across the 33-bit wrap
(every 26.5 hours), including files imported faster than real time and flagged
jumps, so a jump of more than half a wrap (13.25 hours) can read as a rewind.

MPEG-TS import carries H.264/H.265 and AAC/MP2/AC-3/E-AC-3/Opus, and passes
SCTE-35 and every other stream it does not decode (KLV, subtitles, DVB AC-3)
Expand Down Expand Up @@ -342,31 +341,18 @@ there, so a host whose clock runs behind the old run's waits for it to close.
Other versions carry no epoch, so a restart from another session is the newest
route at an equal cost, or a better one.

On a version that carries epochs, 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
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
wrap from its own clock, so near either end of that range, processes whose host
clocks or delivery differ by more than the distance left can put one timestamp
in adjacent wraps, 26.5 hours apart, and one later reads its media as a rewind.
FLV's millisecond timestamps are not unwrapped, so redundant `flv` imports stop
matching at its 49.7-day wrap: the incumbent rewinds and exits, and one started
after it publishes timestamps near zero. A host whose clock reads before the
epoch's time cannot place an `fmp4`, `flv`, or `hls` import on it, and exits 1.
Only `import fmp4`, `flv`, `hls`, and `ts` (one program, or `--passthrough`)
accept it. The RTMP, SRT, RTSP, and WHIP ingests
and `import ts --program all` refuse it because they mint their own, and `import
avc3`, `capture`, `rtc --connect`, `archive`, and `transcode` because their
timestamps or bytes come from the instance rather than the input. Each that
accepts it announces once its catalog names a servable track, so a standby
started ahead of its feed is never asked for tracks it cannot serve yet. Input
that ends before then, such as an empty input or a PMT or header that
configures no track, exits 1 without announcing.
Each independent importer publishes its own epoch, even when two importers read
one stream and publish one path. On a version that carries epochs, the newest
importer wins new requests. If it leaves, a still-live older importer wins again
as a restart. Players following announcements and `moq export ts --stitch`
follow those restarts; other consumers end. `--stitch` also switches as soon as a newer
importer starts, even while the current importer remains healthy. Each switch
marks a program discontinuity, so redundant ingest does not promise hitless
output.

An importer announces once its catalog names a servable track. Input that ends
before then, such as an empty input or a header that configures no track,
exits 1 without announcing.

## Cluster

Expand Down
7 changes: 4 additions & 3 deletions doc/bin/relay/cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,10 @@ re-request on a restart, and a relay drops its copy of the old instance,
including every path beneath a prefix claim when one of them moves to another
worker.

Failover routes must carry copies of the same broadcast: a source whose track
differs in timescale, retention, publisher priority, or group order is refused
for that track.
Failover routes must carry copies of one publisher's broadcast. Independent
importers use distinct epochs and switch as a restart, even when fed one stream.
A source whose track differs in timescale, retention, publisher priority, or
group order is refused for that track.

A route whose original publisher (its first hop) changes under the same epoch is
updated in place on both wire protocols, so the broadcast never briefly vanishes
Expand Down
11 changes: 5 additions & 6 deletions doc/concept/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,12 +170,11 @@ 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 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
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 [moq-cli](/bin/cli)); the encoding is in
[draft-lcurley-moq-mpegts](/draft/moq-mpegts).

## Container
Expand Down
7 changes: 4 additions & 3 deletions doc/concept/moq-lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,9 +118,10 @@ ignores the end and start may keep cached objects of the old run under the same
names, so an end and a start is not a cache flush.

`moq` and `moqsink` mint a fresh epoch per run, kept across reconnects, and the
RTMP, SRT, and WHIP ingests mint one per connection. Replicas share one by
passing the same [`moq --epoch`](/bin/cli#publisher-runs), which only the importers that derive their tracks from the input accept, except under [encryption](/concept/hang#encryption). See [Clustering](/bin/relay/cluster) for how a
relay uses this.
RTMP, SRT, and WHIP ingests mint one per connection. Independent importers use
distinct epochs, even when fed one stream. Only replicas of one publisher's
bytes share its epoch, such as one publisher announced through multiple relays. See [Clustering](/bin/relay/cluster) for
how a relay uses this.

### Multiple CDNs

Expand Down
2 changes: 1 addition & 1 deletion drafts/draft-lcurley-moq-e2ee.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ The lowercase hyphenated text of a UUID version 7 with the RFC variant ({{RFC956
Noncanonical text and other UUID versions or variants MUST be refused (`identity`).
Each instance of a broadcast MUST mint an epoch that no other instance under the same credential has used or will use.
Two instances MUST NOT share an epoch: they would derive the same keys and collide on nonces.
An encrypting core MUST mint its producing epoch internally and MUST NOT accept an explicit or shared epoch for production.
An encrypting core MUST mint its producing epoch internally.
Binding a discovered epoch MUST yield a consume-only generation.
Clones of a producing generation MUST share permanent track claims so reopening a physical track cannot reset its nonce counters.
Its leading 48-bit timestamp makes epochs sort by creation time and its random bits make collisions negligible.
Expand Down
22 changes: 9 additions & 13 deletions drafts/draft-lcurley-moq-mpegts.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,10 +281,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 of the latest window the section describes started at a random access point ({{m2ts-groups}}).
`randomAccess` says that every group starts 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 that window.
`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.
Expand All @@ -305,15 +305,11 @@ 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;
- 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);
- 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.

Before its first group, a publisher starts one at a second only once it has watched from a PCR before the second before it, with the PMT of the clock's program read, so it never cuts where a publisher running longer saw a random access point or a jump (the first PCR it saw may carry a flag it missed).

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`.
`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.
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.
Expand All @@ -325,11 +321,11 @@ A PCR gives the time of the byte holding the last bit of its `program_clock_refe
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.
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}}).
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}}).
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 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.
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}
Stripping each frame's timestamp leaves an {{msfts}} object of whole source packets, and the groups carry over unchanged.
Expand Down Expand Up @@ -452,7 +448,7 @@ A broadcast demultiplexed from a DVB transport stream: video and audio described
- Added the `pesPacket` record: each frame one whole PES packet, timestamped with its placement. A consumer that predates it drops the track rather than refusing the catalog.
- `verbatim` carries sections only, breaking -00: `framing` is required and `"section"` its only value, and `streamId` is gone. A consumer refuses a -00 catalog with `"pes"` framing or a `verbatim` record without `framing`. A publisher carries an undecoded PES stream as `pesPacket`, and refuses one it cannot carry unaltered.
- A flagged PCR jump on an `m2ts` track follows hang's discontinuity marker rather than a skipped group sequence.
- An `m2ts` track's fallback cut falls on whole seconds of a PCR count whose wraps follow the catalog clock, and `randomAccess` and `muxRate` describe the latest two-second window rather than the whole track, so publishers sharing a clock cut and describe the multiplex alike.
- 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.

## draft-lcurley-moq-mpegts-00
{:numbered="false"}
Expand Down
1 change: 0 additions & 1 deletion quest/m0/broadcast-epoch/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,6 @@ End+Start. The child quests own their focused regressions.
## Required

- [Catalog references](/quest/m0/broadcast-epoch/catalog-references.md) - announcement followers restart replaced siblings; other readers retain pins, with optional epochs and legacy best effort
- [Distinct importer epochs](/quest/m0/broadcast-epoch/distinct-importer-epochs.md) - `moq --epoch` never ships, a redundant importer pair fails over as a marked restart, and the shared-epoch alignment code is reverted

## Related

Expand Down
88 changes: 0 additions & 88 deletions quest/m0/broadcast-epoch/distinct-importer-epochs.md

This file was deleted.

Loading
Loading