Skip to content
1 change: 1 addition & 0 deletions doc/concept/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ 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.
- **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.
- **Whole contributions.** A catalog can list relative broadcast references without fetching their catalogs. Explicit selection opens a contribution, which resolves like a rendition's reference, including its optional `epoch`. Its rendition names remain separate from the source. `@moq/watch` exposes this as a scoped child broadcast, and listing contributions alone never starts their media producers.
- **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.
- **Disabled renditions.** An audio or video rendition with `enabled: false` has no frames coming, and a player must not select it. Pausing a rendition in `@moq/publish` keeps it in the catalog this way rather than removing it, so a mute is a one-field update; a disabled video rendition encodes one black keyframe first, so a player that predates the field shows black instead of a frozen picture. The field is written only when false. The older video `stalled` field is no longer written, and readers ignore it.
Expand Down
17 changes: 17 additions & 0 deletions drafts/draft-lcurley-moq-hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,10 @@ The root of the catalog is a JSON document with the following schema:

~~~
type Catalog = {
"contributions": Record<string, {
"broadcast": string,
"epoch": string | undefined,
}> | undefined,
"audio": AudioSchema | undefined,
"video": VideoSchema | undefined,
"archive": ArchiveSchema | undefined,
Expand All @@ -144,6 +148,17 @@ The `json` and `binary` sections ({{data}}) are how a track like that is listed.

This specification defines audio, video, and text media tracks, plus an optional `archive` entry ({{archive-catalog}}) naming the timeline track ({{timeline}}) that indexes each track, an optional root `clock` entry ({{clock}}) mapping content time to wall time, and the application data tracks in {{data}}.

## Contributions {#contributions}
The optional `contributions` map names whole broadcasts whose catalogs describe their renditions.
Each entry MUST contain a string `broadcast`, resolved relative to this catalog's broadcast using {{field-broadcast}}, and MAY contain an `epoch` using {{field-epoch}}.
A malformed entry or a reference escaping the root MUST cause the catalog to be rejected.

Listing an entry MUST NOT subscribe to the contribution; a consumer opens its catalog only upon explicit selection.
A selected contribution resolves like a rendition's reference, under the same rules for `epoch` and restarts ({{field-epoch}}).
A contribution's rendition identifiers belong to that contribution and MUST NOT replace identifiers in the referring catalog.
An unavailable contribution does not invalidate the referring catalog.
References are not recursively expanded: each further contribution requires an explicit selection.

## Clock {#clock}
The catalog's root `clock` field is the broadcast's one continuous clock:

Expand Down Expand Up @@ -1168,6 +1183,8 @@ This document has no IANA actions.
- Specified conversion between relative broadcast references and MSF track namespaces without changing track identity, reading a namespace aligned with the catalog path's trailing segments as the catalog itself.

- Added optional audio and video `warmup` durations, rounded up to whole milliseconds, and allowed video groups to start at convergent random access pictures.
- Added optional whole-broadcast `contributions` with explicit lazy selection and scoped rendition identifiers.

- Defined encoder `jitter` as flush lateness above the rendition's own recent minimum, replacing fixed frame-duration hints; container batches retain media-span estimates.
- Timed CMAF samples from the frame timestamp, which is the fragment's earliest presentation time; `tfdt` is only relative within the fragment, and places the samples of an untimed frame. A timed CMAF track counts in its `mdhd` ticks.
- Allowed a DVR to delete timeline objects no checkpoint recovery needs, oldest first.
Expand Down
2 changes: 2 additions & 0 deletions js/hang/src/catalog/root.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ test("rendition broadcast reference is parsed and normalized", () => {
test("every reference-bearing section carries an optional epoch", () => {
const EPOCH = "01890a5d-ac96-774b-bcce-b302099a8057" as ReferenceEpoch;
const catalog = (epoch: string) => ({
contributions: { c: { broadcast: "./a", epoch } },
video: {
renditions: {
v: { broadcast: "./a", epoch, codec: "avc1.64001f", container: { kind: "legacy" } },
Expand Down Expand Up @@ -81,6 +82,7 @@ test("every reference-bearing section carries an optional epoch", () => {
expect(parsed.json?.tracks.j?.epoch).toBe(EPOCH);
expect(parsed.binary?.tracks.b?.epoch).toBe(EPOCH);
expect(parsed.archive?.replayEpoch).toBe(EPOCH);
expect(parsed.contributions?.c?.epoch).toBe(EPOCH);

// A malformed or noncanonical epoch refuses the catalog, as in Rust.
for (const bad of ["not-a-uuid", EPOCH.toUpperCase(), "01890a5d-ac96-474b-bcce-b302099a8057"]) {
Expand Down
9 changes: 7 additions & 2 deletions js/hang/src/catalog/root.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { BinarySchema } from "./binary";
import { ClockSchema } from "./clock";
import { TRACK } from "./format";
import { JsonSchema } from "./json";
import type { RelativeBroadcast } from "./path";
import { EpochSchema, type RelativeBroadcast, RelativeBroadcastSchema } from "./path";
import { PRIORITY } from "./priority";
import { section } from "./section";
import { TextSchema } from "./text";
Expand All @@ -20,14 +20,18 @@ import { VideoSchema } from "./video";
* The media sections are `video`, `audio`, and `text`, alongside the broadcast's `archive`
* (the segment index and any durable recording) and its `clock` (the one wall-clock mapping);
* `json` and `binary` list application data tracks that aren't media. A section is omitted
* when it holds no tracks.
* when it holds no tracks. `contributions` lists whole broadcasts without opening them.
*
* This is a *loose* object: unknown root sections pass through validation untouched, so an
* application can add its own sections (e.g. `scte35`) without modifying hang. A base consumer
* ignores the extra sections; an extended consumer validates them with its own schema, typically
* built via `z.extend(RootSchema, { ... })`.
*/
export const RootSchema = z.looseObject({
// Whole broadcasts are listed without opening their catalogs. IDs stay scoped to each broadcast.
contributions: z.optional(
z.record(z.string(), z.object({ broadcast: RelativeBroadcastSchema, epoch: z.optional(EpochSchema) })),
),
video: z.optional(VideoSchema),
audio: z.optional(AudioSchema),
// An incompatible archive disables seeking/recording, not the rest of the catalog.
Expand Down Expand Up @@ -108,6 +112,7 @@ export function checkResolvable(root: Root, base: Moq.Path.Valid): Root {
root.text?.renditions,
root.json?.tracks,
root.binary?.tracks,
root.contributions,
];
for (const section of sections) {
for (const { broadcast } of Object.values(section ?? {})) {
Expand Down
58 changes: 57 additions & 1 deletion js/watch/src/broadcast.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import * as Json from "@moq/json";
import * as Msf from "@moq/msf";
import type * as Moq from "@moq/net";
import { Error as NetError, Path, StreamCode } from "@moq/net";
import { Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals";
import { Derived, Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals";

import { toHang } from "./msf";

Expand Down Expand Up @@ -152,6 +152,10 @@ export class Broadcast {
// strands the filtered copy on the previous contents.
readonly #raw = new Signal<Catalog.Root | undefined>(undefined);

// Set only on a contribution: its broadcast resolves through the parent catalog's references,
// so the two never resolve one path independently.
readonly #resolve = new Signal<((effect: Effect) => Moq.Broadcast.Consumer | undefined) | undefined>(undefined);

#signals: Effect;

constructor(props?: Inputs<BroadcastInput>) {
Expand Down Expand Up @@ -244,6 +248,12 @@ export class Broadcast {
const enabled = effect.get(this.in.enabled);
if (!enabled) return;

const resolve = effect.get(this.#resolve);
if (resolve) {
effect.set(this.#out.active, resolve(effect), undefined);
return;
}

const origin = effect.get(this.in.origin);
if (!origin) return;

Expand Down Expand Up @@ -436,6 +446,52 @@ export class Broadcast {
return this.#requestBroadcast(effect, origin, target.path);
}

/**
* Select a whole contribution, opening its catalog only while the caller owns this effect.
* The child tracks the catalog entry and resolves like a rendition's reference (see
* `relativeBroadcast`): without an `epoch` it follows restarts, and with one it is offline
* while its broadcast proves another instance. An absent entry leaves the child disabled.
* Wire the returned broadcast into a media source inside a nested effect. Its rendition
* IDs stay local to that broadcast, so they never replace the parent catalog's IDs.
*
* ```ts
* effects.run((effect) => {
* const child = broadcast.contribution(effect, "extra");
* const source = new Video.Source({ broadcast: child, supported: Video.Decoder.supported });
* effect.cleanup(() => source.close());
* const decoder = new Video.Decoder({ source, sync });
* effect.cleanup(() => decoder.close());
* // Feed decoder.out.frame into your renderer.
* });
* ```
*/
contribution(effect: Effect, id: string): Broadcast {
// Each computed only notifies on a real change, so an update that leaves the child's path
// alone (such as a new `epoch`) never restarts its catalog.
const entry = effect.computed((run) => {
const contributions = run.get(this.out.catalog)?.contributions;
return contributions && Object.hasOwn(contributions, id) ? contributions[id] : undefined;
});
const name = effect.computed((run) => {
// An empty reference is present: it names the catalog's own broadcast.
const selected = run.get(entry);
return selected && Path.tryResolve(run.get(this.in.name), selected.broadcast);
});
const enabled = effect.computed((run) => run.get(entry) !== undefined);
const child = new Broadcast({
origin: this.in.origin,
name: new Derived([name], (name) => name ?? Path.empty()),
enabled: new Derived([enabled], (enabled) => enabled === true),
announced: this.in.announced,
});
child.#resolve.set((run) => {
const selected = run.get(entry);
return selected && this.relativeBroadcast(run, selected.broadcast, selected.epoch);
});
effect.cleanup(() => child.close());
return child;
}

close() {
this.#signals.close();
for (const entry of this.#references.values()) entry.request.close();
Expand Down
Loading
Loading