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
2 changes: 2 additions & 0 deletions quest/m0/broadcast-epoch/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,9 @@ then. MoQ Pro's VOD `storage.json` moves from the same seed to its own epoch.
## Required

- [Restart](/quest/m0/broadcast-epoch/restart.md) - a replaced broadcast reaches announce consumers as an explicit Restart, subscriptions stay sticky, and new requests never join a replaced route's front
- [No stitch](/quest/m0/broadcast-epoch/no-stitch.md) - an epochless track ends on an upstream error instead of re-splicing onto whatever instance now wins upstream
- [Apps](/quest/m0/broadcast-epoch/apps.md) - moq-cli, the browser publish and watch components, and demo/web restart into a new epoch and reset on the switch
- [Export ts](/quest/m0/broadcast-epoch/export-ts.md) - `export ts` and SRT egress linger only for the same epoch, and switch to a replacement only with `--stitch`, as a full program switch
- [Publish catalog restart](/quest/m0/broadcast-epoch/publish-catalog-restart.md) - `@moq/publish` never reuses catalog group numbers under one name and epoch after a re-announce
- [Bindings](/quest/m0/broadcast-epoch/bindings.md) - moq-ffi and every wrapper expose the epoch and let a publisher announce one
- [moqsrc](/quest/m0/broadcast-epoch/moqsrc.md) - moqsrc switches to the new broadcast on a `Restart`, keeping its pads by rendition name
Expand Down
103 changes: 103 additions & 0 deletions quest/m0/broadcast-epoch/export-ts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# [M] TS export lingers within an epoch and stitches across one only on request

## Goal

`moq export ts` and moq-srt's egress never splice two broadcasts into one TS
stream unless asked:

- `--linger <dur>` waits up to that long for the *same* broadcast (the same
epoch) to come back after its route goes, and carries on with the same
stream.
- A replacement (a newer epoch, or another instance of an epochless route)
ends the export with an error that names `--stitch`. On an epochless route
every return is a replacement.
- `--stitch` opts in to following a replacement. The export is rebuilt on the
new broadcast with a full program switch: a new PMT from the new catalog, so tracks, codecs, and PIDs may
change, plus PCR and continuity discontinuities. Nothing from the old
broadcast survives except the output pipe or SRT connection, and the
PSI version numbers.

Non-goal: identical output across a replacement. Two legs that are
byte-identical within an epoch may differ after one (#5101).

## Plan

Decided 2026-10-09. Today `--linger` (#4504) waits for the ended broadcast to
close and the path to route again, then calls `ts::Export::resume()`. That
call clears the decode clocks, jitter buffer, and schedule, but keeps the old
PMT and PIDs and matches the returned tracks by name only, so a renamed codec
goes out under the old stream_type and continuity counters run on unflagged.
That is a splice of whatever returns, assuming the layout matches without
checking. It also keys on errors and the broadcast closing, so an old
publisher that stays alive holds the export on a replaced broadcast.

- Delete `Export::resume()` and its partial reset.
- Drive both flags from announcements, as players do: `Start`, `Restart`, and
`End` with their epochs. An export that fails while its broadcast is still
announced exits 1 without lingering, as today.
- Same epoch within `--linger`: `follow` continues the same stream.
It is the same content, so the existing skip handling covers the gap (late
frames drop, and a forward leap opens a new generation). Within an epoch,
moq-net already resumes across routes, so this only matters once every
route has gone.
- Without `--stitch`: subscriptions are sticky, so a `Restart` leaves the
export on the old broadcast until it ends. If the path then serves a
different instance, the export exits 1 with an error naming `--stitch`.
- With `--stitch`: on `Restart` (or `End` then `Start` with another
instance) `follow` it at once, which builds a fresh `Export`. Every PID's first packet carries
`discontinuity_indicator`, the PAT and PMT `version_number`s advance (the only
values handed from the old `Export`, since a version-caching demux such as
TSDuck's ignores a changed PAT under an unchanged version), and each
elementary stream starts at a keyframe. Rejected: continuing only when the layout is identical, and
deleting `--linger`. Exiting does not hide the switch from a receiver
downstream of `tsp`, it only drops the flags.
- moq-srt's egress (`rs/moq-srt/src/ts.rs`) gets the same two options and keeps
its SRT connection across a stitch. Its linger defaults to 0, like the CLI:
Comment on lines +54 to +55

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Report the SRT egress API needed for these options

The same options cannot be added to SRT egress solely as CLI flags: embedders use the exported moq_srt::Config, Server, and Subscribe::accept interfaces, none of which currently accepts a linger or stitch policy. The planned public API impact lists only the TS-export successor and CLI change, leaving library consumers no specified way to select this behavior; decide where this policy belongs and report that public surface.

AGENTS.md reference: AGENTS.md:L59-L60

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Addressed in 29769c7: decided that the policy lives on moq_srt::Config as linger: Duration (default 0) and stitch: bool (default false), mirrored as CLI flags. The Public API line reports it.

(Written by Claude Opus 5.5)

an `End` that nothing replaces within the linger closes the SRT stream, so
a finished broadcast never leaves a caller connected indefinitely.
- Decided: the SRT policy lives on `moq_srt::Config` as `linger: Duration`
(default 0) and `stitch: bool` (default false), mirrored as CLI flags.
- Decided: one successor operation, `ts::Export::follow(self, broadcast) ->
Export`, used by both callers. On the same epoch it continues the stream
with the same PSI. On another instance it does the full program switch,
carrying the PAT and PMT `version_number`s, both advanced. The caller calls
it for a replacement only under `--stitch`. Rejected: separate continue and
stitch methods, and a builder policy that has the export watch announces
itself.
- Decided: the TS output has no epoch. A re-import of an export is out of
scope.
- Fold in the stale wording from the marker audit: a marker group only
declares a pause or forward break, since rewinds are refused (#3711). Rename
`Consumer::restarts` / `ExportSource::restarts` for what they count, and fix
the comments that say the publisher restarted or rewound its timeline
(`rs/moq-mux/src/container/consumer.rs`, `rs/moq-srt/src/server.rs`).
- Tests, with mocked time:
- A same-epoch return within the linger continues the stream with no PSI
version change.
- A replacement without `--stitch` exits 1, and an old publisher that stays
alive keeps the export on it until it ends.
- With `--stitch`, a replacement with a different codec and track set
writes a new PMT version, flags every PID's first packet, starts each
stream at a keyframe, and writes nothing from the old broadcast after the
break.
- A stitch that keeps the transport-stream ID but moves the PMT PID
advances the PAT version.
- Update #4504's relay-backed CLI tests, and add the stitch case for SRT
egress, plus an unreplaced `End` closing the SRT stream at the linger.
- Docs: the `--linger` paragraph in `doc/bin/cli.md` (plus `--stitch`), any
restart behavior in `doc/bin/srt.md`, and every example invocation using
`--linger`.

Public API: breaking, `ts::Export::resume` is removed and `restarts()` is
renamed. New: `ts::Export::follow`, and `linger` and `stitch` on
`moq_srt::Config`. CLI: new `--stitch` on `export ts` and SRT egress, and `--linger`
no longer follows a replacement. Wire: none.

## Required

- [Restart](/quest/m0/broadcast-epoch/restart.md) - the announce event and epoch the export follows

## Related

- [No stitch](/quest/m0/broadcast-epoch/no-stitch.md) - stops moq-net hiding a replacement from the export
- [Two TS export legs](/quest/m2/ts-hitless.md) - identical output within one epoch
61 changes: 61 additions & 0 deletions quest/m0/broadcast-epoch/no-stitch.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# [M] An epochless track ends on an upstream error instead of re-splicing

## Goal

A delivered track whose front has no epoch ends with the upstream error
instead of re-subscribing. A re-subscribe through the same session can land on
a different instance one hop upstream. Only a front with an epoch re-splices
after an error, and its re-request carries that epoch, so it resumes the same
broadcast or fails. Consumers of an epochless broadcast recover on the announce
`Restart` (or `End` then `Start`), never on a silent re-splice.

## Plan

Found in #5052 (t0ms), decided 2026-10-09. On lite-06, a relay times out the
dead publisher's session and ends the downstream copy with `internal error`.
The downstream front takes `Front::track_ended`'s `Err(_) if delivered` arm
(`rs/moq-net/src/model/front.rs`), "normal failover", and `redispatch`es to
the same serving source, which is the relay session, about 2 ms later. The
relay resolves the epochless SUBSCRIBE to whatever wins the path now, the
replacement publisher, and the resume layer fetches the rest of the
in-flight group from it. The consumer sees no error and no restart. So two
epochless instances are stitched across a hop, against "routes without an
epoch never splice". #5087 does not change this: the redispatch arm is
untouched, and its held END/START reaches the downstream relay hundreds of ms
after the re-subscribe. In `moq export ts`, frames read before the death sat
in the decode hold through the silence and came out 13-26 s late, and the
export bailed on "missed a decode deadline".

- Decided: resume after an error only within an epoch. Rejected: a distinct
terminal error from the relay for "upstream instance gone" (a new wire
distinction every hop must classify), and accepting the stitch on lite-06.
- Accepted consequence: on lite-06, and on any epochless route, any upstream
track error now ends the track. The epoch README already accepts that
default sessions end subscriptions on failover instead of resuming them.
- Decided: no exporter-side guard. A unit due at or behind the TS schedule's
`next` still bails. Once the stitch is gone, a stale unit reaching the
schedule is a bug to fail loud on. The replaced broadcast's state is dropped
by [Export ts](/quest/m0/broadcast-epoch/export-ts.md).
- Fix the module docs that claim an epochless front is never swapped
(`front.rs` header, `origin.rs` around `pick`): today that holds only when
the replacement is in the front's own table.
- Tests, with mocked time: an epochless publisher behind a relay is replaced
(the old session times out, a new one is already announced) on lite-06 and
lite-07. The downstream track ends with the error and never fetches a
group from the replacement. A 1+1 pair sharing an epoch on lite-07 still
fails over with no error downstream. The same pair reaching the relay on
lite-06 ends the downstream track.
- After landing, ask t0ms to re-run both #5052 rigs. One rig-2 run exited
1.4 s after a mid-GOP join, before any failover, which the stitch does not
explain. If it reproduces, it is a separate issue.

Public API: none. Behavior: an epochless subscription now surfaces an
upstream error instead of healing. Wire: none.

## Required

- [Restart](/quest/m0/broadcast-epoch/restart.md) - reworks the same front and instance code, and supplies the `Restart` consumers recover on

## Closes

- [#5052](https://github.com/moq-dev/moq/issues/5052) - export ts bails after re-requesting onto a replacement publisher
7 changes: 6 additions & 1 deletion quest/m2/ts-hitless.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,14 @@

Two `moq export ts --sync` legs of one broadcast, joined at different
moments, emit packet-identical TS from their first common packet, across
skips and source drift, continuity counters included. A ST 2022-7 selector
skips and source drift, continuity counters included, within one epoch. A ST 2022-7 selector
can then switch between them hitlessly.

Non-goal: identity across a replaced broadcast. A leg ends on a replacement, or
starts a fresh stream with `--stitch` ([Export ts](/quest/m0/broadcast-epoch/export-ts.md)),
so legs may differ after one (#5101, maintainer 2026-10-09: byte-identical
output across restarts is not supported).

## Plan

Decided (2026-10-01), from t0ms's review of the fixed-delay export (#4645).
Expand Down
Loading