Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
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
5 changes: 5 additions & 0 deletions cpp/moq/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first.

## Unreleased

### A broadcast reference waits for its sibling's announcement (#6254)

Resolving a rendition's `broadcast` reference, through `BroadcastConsumer::resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced.
Where you skipped such a rendition on that error, bound the call yourself: cancel it.

### Priorities are signed (#6142)

`TrackInfo::priority`, `Subscription::priority`, and `FetchGroupOptions::priority` are `int8_t`, and `GroupRequest::priority()` returns one.
Expand Down
5 changes: 5 additions & 0 deletions dart/moq/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first.

## Unreleased

### A broadcast reference waits for its sibling's announcement (#6254)

Resolving a rendition's `broadcast` reference in the rendition-based subscribes and fetches now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced.
Where you skipped such a rendition on that error, bound the call yourself: add a `.timeout` to the future.

### JSON snapshot `deltaRatio` is `deltas`

`SnapshotConfig.deltaRatio` is replaced by `bool deltas` (default `true`).
Expand Down
6 changes: 6 additions & 0 deletions dart/moq_ffi/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.

## Unreleased

### A broadcast reference waits for its sibling's announcement (#6254)

Resolving a rendition's `broadcast` reference, through `MoqBroadcastConsumer.resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced.
Where you skipped such a rendition on that error, bound the call yourself: add a `.timeout` to the future.
Regenerate the bindings for the changed `resolve` checksum.

### Priorities are signed (#6142)

`MoqTrackInfo.priority`, `MoqSubscription.priority`, `MoqFetchGroupOptions.priority`, and `MoqGroupRequest.priority()` take `-128..=127`, higher first, and 0 is the unset midpoint.
Expand Down
2 changes: 1 addition & 1 deletion dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -19374,7 +19374,7 @@ void _checkApiChecksums() {
18633) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_resolve() != 33982) {
if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_resolve() != 42208) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqbroadcastconsumer_subscribe_track() !=
Expand Down
2 changes: 1 addition & 1 deletion doc/bin/gstreamer.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ rewound timestamps forward.

Pads are named by kind and appear as the catalog announces renditions:
`video_0`, `video_1`, `audio_0`. A rendition referencing another broadcast reads
that broadcast on the same connection. Link the pad you want by name; the terse
that broadcast on the same connection, waiting for it to be announced. Link the pad you want by name; the terse
`moqsrc ! decodebin3` form links only the first pad offered, which may be
audio. `moqsrc` follows the broadcast's announcements: when the publisher
restarts, it switches to the new broadcast on the same pads, kept by rendition
Expand Down
2 changes: 1 addition & 1 deletion doc/concept/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ decoder once per track.
A few things the catalog can express beyond decoder config:

- **Labels.** Any rendition may carry a human-readable `label` for a track picker. The map key stays the rendition's ID, so labels need not be unique and renaming one doesn't rename the track.
- **Renditions in another broadcast.** A rendition may point at a relative broadcast path, so a transcoder can publish a ladder that adds low rungs and references the source's original rendition without re-publishing its bytes. The path resolves against where the consumer found the catalog, so a reference that escapes above the root names nothing and the catalog is rejected. A consumer reads each referenced path from the first broadcast it resolves there. An optional `epoch` beside the path names the [publisher instance](/concept/moq-lite#publisher-epochs) it expects: a route proving another instance fails the rendition instead of falling back to it, while a route without an epoch (an older version) cannot prove one, so there it is best effort.
- **Renditions in another broadcast.** A rendition may point at a relative broadcast path, so a transcoder can publish a ladder that adds low rungs and references the source's original rendition without re-publishing its bytes. The path resolves against where the consumer found the catalog, so a reference that escapes above the root names nothing and the catalog is rejected. `@moq/watch` follows a referenced path's announcements like its own, restarting the rendition on each instance that serves it; every other reader, such as `moqsrc`, `moq play`, the exporters, and the bindings, waits for the first one announced and keeps it, and an exporter ends the rendition with it. An optional `epoch` beside the path names the [publisher instance](/concept/moq-lite#publisher-epochs) it expects: a route proving another instance ends the rendition instead of falling back to it, while a route without an epoch (an older version) cannot prove one, so there it is best effort.
- **Track names.** The map key is a rendition's ID and, by default, its track name. A rendition sets `track` only when the two must differ, such as two renditions of same-named tracks in different broadcasts, or a rendition whose media changed and so needs a new name; readers subscribe to `track` when present. An ID can't name both a video and an audio rendition.
- **Jitter.** A rendition can say how far its frames fell behind the media clock before the publisher flushed them, in whole milliseconds rounded up. Encoders report the spread of lateness above each rendition's own recent minimum, so a constant encoder delay is not jitter; container imports estimate batch spans without counting ingest delay. It describes the publisher, never the network, only grows over the life of a stream, and a player sizes its buffer to at least this much. A `0` is read as absent.
- **Delay.** A rendition can also say how far its frames reach the transport behind the broadcast's earliest rendition, measured the same way from each rendition's minimum lateness, so a video encoder running 200 ms behind audio advertises `delay: 200` on video. It follows the same rules as jitter. A player holds the largest `delay + jitter` among the renditions it subscribes to, and never subtracts one rendition's `delay` from another's.
Expand Down
6 changes: 6 additions & 0 deletions go/ffi/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.

## Unreleased

### A broadcast reference waits for its sibling's announcement (#6254)

Resolving a rendition's `broadcast` reference, through `MoqBroadcastConsumer.Resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced.
Where you skipped such a rendition on that error, bound the call yourself: pass a `ctx` with a deadline.
Regenerate the bindings for the changed `resolve` checksum.

### Priorities are signed (#6142)

`MoqTrackInfo.Priority`, `MoqSubscription.Priority`, `MoqFetchGroupOptions.Priority`, and `MoqGroupRequest.Priority()` are `int8`, higher first, and 0 is the unset midpoint.
Expand Down
5 changes: 5 additions & 0 deletions go/wrapper/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first.

## Unreleased

### A broadcast reference waits for its sibling's announcement (#6254)

Resolving a rendition's `broadcast` reference, through `BroadcastConsumer.Resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced.
Where you skipped such a rendition on that error, bound the call yourself: pass a `ctx` with a deadline.

### JSON snapshot `DeltaRatio` is `Deltas`

`json.SnapshotOptions.DeltaRatio *uint32` and `json.DefaultDeltaRatio` are replaced by `Deltas *bool` (nil enables deltas).
Expand Down
31 changes: 31 additions & 0 deletions js/watch/src/broadcast.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -410,6 +410,37 @@ describe("relativeBroadcast", () => {
}
});

it("drops a rendition from the catalog while its broadcast proves another epoch", async () => {
const owner = new Origin.Producer();
const main = publish(owner, Path.from("a/b"));
const [oldEpoch, newEpoch] = [Moq.Epoch.mint(), Moq.Epoch.mint()];
const old = owner.createBroadcast(Path.from("a/source"));
old.announce({ epoch: oldEpoch });
const named = { ...video("avc1.64001f", "./source"), epoch: oldEpoch } as Catalog.VideoConfig;
const source = new Broadcast({
origin: owner,
name: Path.from("a/b"),
enabled: true,
catalogFormat: "manual",
catalog: { video: { renditions: { plain: video("avc1.64001f", "./source"), named } } } as Catalog.Root,
});
try {
await settle();
expect(videoRenditions(source)).toEqual(["named", "plain"]);

const replacement = owner.createBroadcast(Path.from("a/source"));
replacement.announce({ epoch: newEpoch });
await withoutWarnings(settle);
expect(videoRenditions(source)).toEqual(["plain"]);
replacement.close();
} finally {
source.close();
old.close();
main.close();
owner.close();
}
});

it("uses the catalog's own broadcast when the reference is absent, empty, or self", async () => {
const { source, owner } = broadcast("a/b");
const effect = new Effect();
Expand Down
32 changes: 24 additions & 8 deletions js/watch/src/broadcast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,28 @@ import { toHang } from "./msf";

type ReferencedRendition = {
broadcast?: Path.Relative;
epoch?: Catalog.ReferenceEpoch;
};

// Whether a rendition's reference names something this consumer can play.
type Usable = (rel: Path.Relative | undefined, epoch: Moq.Epoch.Valid | undefined) => boolean;

// Either the catalog's own broadcast, or a sibling to consume by path.
type RelativeTarget = { local: true } | { local: false; path: Moq.Path.Valid };

function filterRenditions<T extends ReferencedRendition>(
renditions: Record<string, T>,
usable: (rel: Path.Relative | undefined) => boolean,
usable: Usable,
): Record<string, T> {
return Object.fromEntries(Object.entries(renditions).filter(([, config]) => usable(config.broadcast)));
return Object.fromEntries(
Object.entries(renditions).filter(([, config]) => usable(config.broadcast, config.epoch)),
);
}

// Whether `active` is proven to be another instance than `epoch` names. An epochless route cannot
// prove its instance, so only a known mismatch counts.
function provesOther(active: Moq.Broadcast.Consumer | undefined, epoch: Moq.Epoch.Valid | undefined): boolean {
return epoch !== undefined && active?.epoch !== undefined && active.epoch !== epoch;
}

// Whether an announced route covers `path`, until closed. Hidden routes count: a service claim
Expand Down Expand Up @@ -47,7 +59,7 @@ function watchCovered(origin: Moq.Origin.Table, path: Moq.Path.Valid): { covered

// Every section carrying a `broadcast` reference must be listed here, same as `Catalog.checkResolvable`;
// one left out silently exempts its tracks from the reachability filter.
function filterCatalog(catalog: Catalog.Root, usable: (rel: Path.Relative | undefined) => boolean): Catalog.Root {
function filterCatalog(catalog: Catalog.Root, usable: Usable): Catalog.Root {
return {
...catalog,
video: catalog.video
Expand Down Expand Up @@ -182,12 +194,16 @@ export class Broadcast {
}

// Publish the catalog minus every rendition this consumer cannot use: one naming a
// broadcast that isn't announced to us. Selecting one of those would render nothing,
// since `relativeBroadcast` resolves it to no broadcast at all. Reruns as announcements
// arrive, so a rendition appears once its broadcast does.
// broadcast that isn't announced to us, or one whose broadcast proves another epoch than it
// names. Selecting one of those would render nothing, since `relativeBroadcast` resolves it to
// no broadcast at all. Reruns as announcements arrive, so a rendition appears once its
// broadcast does. Only a rendition naming an epoch resolves its broadcast here, sharing the
// request playback uses.
#runFiltered(effect: Effect): void {
const raw = effect.get(this.#raw);
const usable = (rel: Path.Relative | undefined) => this.#relativeTarget(effect, rel) !== undefined;
const usable: Usable = (rel, epoch) =>
this.#relativeTarget(effect, rel) !== undefined &&
(epoch === undefined || !provesOther(this.#relativeActive(effect, rel), epoch));
effect.set(this.#out.catalog, raw ? filterCatalog(raw, usable) : undefined);
}

Expand Down Expand Up @@ -448,7 +464,7 @@ export class Broadcast {
epoch?: Moq.Epoch.Valid,
): Moq.Broadcast.Consumer | undefined {
const active = this.#relativeActive(effect, rel);
if (!active || epoch === undefined || active.epoch === undefined || active.epoch === epoch) return active;
if (!active || !provesOther(active, epoch)) return active;
console.warn("ignoring rendition: its broadcast serves another epoch", active.path, active.epoch, epoch);
return undefined;
}
Expand Down
6 changes: 6 additions & 0 deletions kt/moq-ffi/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.

## Unreleased

### A broadcast reference waits for its sibling's announcement (#6254)

Resolving a rendition's `broadcast` reference, through `MoqBroadcastConsumer.resolve` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced.
Where you skipped such a rendition on that error, bound the call yourself: cancel the coroutine or wrap it in `withTimeout`.
Regenerate the bindings for the changed `resolve` checksum.

### A client asks only about what it watches (#6165)

On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announcedBroadcast()`, instead of under its whole scope at connect.
Expand Down
5 changes: 5 additions & 0 deletions kt/moq/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first.

## Unreleased

### A broadcast reference waits for its sibling's announcement (#6254)

Resolving a rendition's `broadcast` reference in the rendition-based subscribes and fetches now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced.
Where you skipped such a rendition on that error, bound the call yourself: cancel the coroutine or wrap it in `withTimeout`.

### JSON snapshot `deltaRatio` is `deltas`

`SnapshotConfig.deltaRatio: UInt` is replaced by `deltas: Boolean` (default `true`).
Expand Down
6 changes: 6 additions & 0 deletions py/moq-ffi/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ How to update your code for each breaking change, newest first.

## Unreleased

### A broadcast reference waits for its sibling's announcement (#6254)

Resolving a rendition's `broadcast` reference, through `MoqBroadcastConsumer.resolve()` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced.
Where you skipped such a rendition on that error, bound the call yourself: cancel the task or wrap it in `asyncio.wait_for`.
Regenerate the bindings for the changed `resolve` checksum.

### A client asks only about what it watches (#6165)

On moq-lite, a client session asks its relay for announcements only under paths something watches, through `announced()` or `announced_broadcast()`, instead of under its whole scope at connect.
Expand Down
5 changes: 5 additions & 0 deletions py/moq-rs/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ How to update your code for each breaking change, newest first.

## Unreleased

### A broadcast reference waits for its sibling's announcement (#6254)

Resolving a rendition's `broadcast` reference, through `BroadcastConsumer.resolve()` and the rendition-based subscribes and fetches, now waits for a sibling nothing announces yet instead of failing as unroutable, so a late sibling plays once it is announced.
Where you skipped such a rendition on that error, bound the call yourself: cancel the task or wrap it in `asyncio.wait_for`.

### JSON snapshot `delta_ratio` is `deltas`

`SnapshotProducer(delta_ratio=...)` is replaced by `deltas: bool = True`.
Expand Down
7 changes: 3 additions & 4 deletions quest/m0/broadcast-epoch/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,8 @@ Decided:
for the catalog instance's lifetime. Optional reference epochs constrain
resolution on epoch-aware transports and remain best effort on epochless
transports. Following never turns a replacement into seamless resume. The
schemas, shared resolution, and compatibility documentation landed;
[reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md)
owns the native readers that follow announcements.
schemas, shared resolution, compatibility documentation, and `moq_mux::follow`
landed; `moqsrc` following siblings with it remains.
- Every first-party publisher that can restart mints its own: the apps,
moq-boy, the ingest gateways, moqsink, OBS, and the bindings. Players
(`moq play`, `@moq/watch`, demo/web) follow the announce `Restart`. moq-stats mints one per
Expand Down Expand Up @@ -126,4 +125,4 @@ End+Start. The child quests own their focused regressions.

## Required

- [Reference announcements](/quest/m0/broadcast-epoch/reference-announcements.md) - native readers restart a replaced referenced sibling on its announcements, never past a named epoch
- [moqsrc sibling follow](/quest/m0/broadcast-epoch/moqsrc-sibling-follow.md) - moqsrc restarts a referenced sibling's rendition on each instance its announcements hand out, never past a named epoch
41 changes: 41 additions & 0 deletions quest/m0/broadcast-epoch/moqsrc-sibling-follow.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# [M] moqsrc follows referenced broadcasts' announcements

## Goal

`moqsrc` follows a catalog-referenced sibling's announcements the way
`@moq/watch` does: each rendition reads the instance `moq_mux::Source::follow`
hands out, idles its pad (no EOS) while the sibling is offline, and restarts on
the same pad when another instance serves it. A reference that names an
`epoch` never plays another instance. Until this lands, `moqsrc` waits for a
sibling's first announcement and keeps that instance, like every other
non-following reader.

## Plan

Split from the reference announcements work (maintainer, 2026-10-22), which
landed `moq_mux::follow` and the waiting `Source::bind`. The moqsrc half drew a
new state-machine finding every review round, so it gets its own design pass.

- Start binds the rendition; End idles its pad; another instance restarts the
stream on the same pad with a fresh stream-start, caps, and a segment.
- Renditions reading one sibling instance share that instance's timeline,
whenever each starts on it, including one still subscribing when a
replacement takes over.
- A sibling track that finishes while its instance stays up idles the pad and
keeps following; a finished record names the instance that served it, so a
reshape (disable and enable, an epoch handoff) still plays the next one.
- A rendition the catalog delists drains the instance it reads, then ends its
pad and follows no later instance.
- A pump that has returned but is still in `active` must not swallow a relist:
a relist arriving before the pump is joined matches its shape and starts
nothing, for an idle delisted sibling and for a delisted catalog rendition
whose track ends just before the relist. Cover both cases.

Weigh a simpler state model (one task per sibling instance owning its
renditions, or reconciling after each pump exits) before patching each case.

Public API: none (moqsrc behavior). Wire: none.

## Related

- [Sink restart follow](/quest/m1/sink-restart-follow.md) - moves moqsrc's own broadcast follow onto `follow::Instances`
Loading
Loading