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: 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.
- **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.
- **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
36 changes: 35 additions & 1 deletion drafts/draft-lcurley-moq-hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,14 @@ normative:
date: false

informative:
moqepoch:
title: "MoQ Epoch Extension"
target: https://datatracker.ietf.org/doc/draft-lcurley-moq-epoch/
author:
-
ins: L. Curley
name: Luke Curley
date: false
h273:
title: "Coding-independent code points for video signal type identification"
target: https://www.itu.int/rec/T-REC-H.273
Expand Down Expand Up @@ -615,7 +623,7 @@ The `deflate` value is the group-scoped DEFLATE of {{compression}}.
A `snapshot` group covers a single value (plus any deltas), so its window spans that group alone; a `stream` group's frames compress against the earlier ones in the log.

### broadcast and track {#data-shared}
The `broadcast` and `track` fields carry the same meaning here as they do for a media rendition ({{field-broadcast}}, {{field-track}}).
The `broadcast`, `epoch`, and `track` fields carry the same meaning here as they do for a media rendition ({{field-broadcast}}, {{field-epoch}}, {{field-track}}).

### bitrate, jitter, and delay {#data-estimates}
The optional `bitrate` field is the track's maximum bitrate in bits per second.
Expand All @@ -639,6 +647,7 @@ Audio, video, and text renditions share the following fields, extending the WebC
~~~
type CommonExtensions = {
"broadcast": string | undefined,
"epoch": string | undefined,
"track": string | undefined,
"label": string | undefined,
"container": Container,
Expand Down Expand Up @@ -670,6 +679,27 @@ An absent MSF `namespace` inherits the catalog's broadcast.
Since each endpoint sees paths under its own connection root, a `namespace` equal to the catalog broadcast's path, or matching it on whole trailing segments, also names the catalog's broadcast; a gateway MUST NOT emit a different broadcast's `namespace` that matches so.
A gateway MUST preserve the namespace and track-name pair or refuse the rendition; it MUST NOT substitute the catalog's broadcast for an unrepresentable reference.

### epoch {#field-epoch}
The optional `epoch` field names the publisher instance of the broadcast a rendition references ({{field-broadcast}}), as the canonical text of its Epoch {{moql}}: a lowercase hyphenated UUIDv7.
Without `broadcast`, it names the instance of the catalog's own broadcast.
A consumer MUST reject a catalog containing any other `epoch` value.

A consumer reads each path a catalog instance references from the first broadcast it resolves there, so the catalog and its renditions never resolve one path independently across a replacement.
An absent `epoch` accepts that first broadcast, whichever instance it is.
A consumer that follows a referenced broadcast's announcements MAY move a rendition without `epoch` onto a restarted instance.

When `epoch` is present and the route that resolved the referenced broadcast carries an Epoch, the consumer MUST read the rendition only from that instance.
It MUST fail the rendition rather than fall back to another instance, including one that replaced it before or after resolution, and MUST NOT follow a restart onto another instance for it.
A later catalog update naming another Epoch for an already-resolved path MUST NOT replace the resolved broadcast; the renditions naming the other Epoch fail instead.
A new catalog instance resolves its references afresh.

A route without an Epoch, such as one over an older moq-lite version or MoQ Transport without the epoch extension {{moqepoch}}, cannot prove which instance it serves, so there `epoch` is best effort: the consumer reads the broadcast it resolved.
A consumer MUST NOT treat a catalog's `epoch` as evidence that a subscription may resume across routes.
A consumer that predates the field ignores it and does not gain its guarantee.

A publisher SHOULD set `epoch` only when it knows the instance it references, and MUST omit it for a broadcast produced on demand, which has no instance until a worker accepts the request.
MSF {{moqmsf}} has no field for an instance, so a gateway converting to MSF drops `epoch` and SHOULD report that it did; its readers accept the first instance they resolve.

### track {#field-track}
A rendition's key in its map is its ID, and by default also the name of its track.
The `track` field overrides the name, so that the ID can stay unique when the name cannot: two renditions referencing same-named tracks in different broadcasts ({{field-broadcast}}) need different IDs.
Expand Down Expand Up @@ -925,6 +955,7 @@ type ArchiveSchema = {
}>,
"timescale": number | undefined,
"replay": string | undefined,
"replayEpoch": string | undefined,
"store": string | undefined,
"version": number | undefined,
}
Expand Down Expand Up @@ -955,6 +986,8 @@ The `replay` field, if present, is a relative MoQ broadcast path ({{field-broadc
Absent, the timelines live on the catalog's own broadcast.
A wildcard replay path names no generation.

The `replayEpoch` field, if present, names the publisher instance of `replay`, with the meaning and rules of a rendition's `epoch` ({{field-epoch}}).

The `store` field, if present, is the object-store URL the recording objects ({{recording}}) live under.
Authorization for `replay` and `store` is external.

Expand Down Expand Up @@ -1360,6 +1393,7 @@ This document has no IANA actions.
- A data track marks a discontinuity with a group of one object with no bytes, since its empty payload is data. An object with no bytes on an audio or video track, or sharing its group, is malformed.
- Each archive timeline declares its own fixed nominal record duration, omitted for an untimed track; removed the broadcast-wide duration bound.
- Added the optional video `preference` field: a consumer selects automatically among the highest preference it can decode.
- Added an optional `epoch` beside every rendition and data track `broadcast` reference, and `replayEpoch` beside the archive's `replay` ({{field-epoch}}). A consumer reads each referenced path from the first broadcast it resolves for a catalog instance; a present `epoch` fails a rendition proven to resolve another instance, and is best effort over a route without an Epoch.
- Derived HLS and DASH exports hand disabled references to enabled renditions at the first record numbered past the advertised ones, keeping the record `sequence` as the HLS media sequence and starting a DASH period.
- Added optional `stats` and `echo` catalog sections, publisher/viewer snapshots keyed by rendition ID, and the `.echo` feedback broadcast convention.

Expand Down
6 changes: 5 additions & 1 deletion js/hang/src/catalog/archive.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import * as z from "@zod/mini";
import { nonzeroU53Schema, u53, u53Schema } from "./integers";
import { RelativeBroadcastSchema } from "./path";
import { EpochSchema, RelativeBroadcastSchema } from "./path";

/** The moq epoch (2020-01-01T00:00:00Z) in Unix-epoch milliseconds. */
export const MOQ_EPOCH_UNIX_MILLIS = 1_577_836_800_000;
Expand Down Expand Up @@ -40,6 +40,10 @@ export const ArchiveSchema = z.object({
// generation: compare this path and `store` to tell recordings apart.
replay: z.optional(RelativeBroadcastSchema),

// The publisher instance `replay` names, when known. Absent accepts whichever instance
// resolves first, as for a rendition's `epoch`.
replayEpoch: z.optional(EpochSchema),

// The object-store URL the recording objects live under, if the publisher exposes one.
store: z.optional(z.url()),

Expand Down
7 changes: 6 additions & 1 deletion js/hang/src/catalog/audio.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { compareName, compareNumber } from "./compare";
import { ContainerSchema } from "./container";
import { hexSchema } from "./hex";
import { u53Schema } from "./integers";
import { RelativeBroadcastSchema } from "./path";
import { EpochSchema, RelativeBroadcastSchema } from "./path";

// Backwards compatibility: old track schema
const TrackSchema = z.object({
Expand All @@ -15,6 +15,11 @@ const AudioConfigFields = z.object({
// relative to the broadcast that served this catalog (e.g. "./source").
// If unset, the track lives in the same broadcast as the catalog.
broadcast: z.optional(RelativeBroadcastSchema),
// The publisher instance the reference names, when known. Absent accepts whichever instance
// resolves first. An epoch-aware route proving another instance fails the entry; an epochless
// route cannot prove one, so there it is best effort. Without `broadcast`, it names the
// catalog's own instance.
epoch: z.optional(EpochSchema),
// The track's name in its broadcast, when it differs from this entry's ID (its key in the
// catalog). Absent means the ID is the track name. Resolve it with `track`.
track: z.optional(z.string()),
Expand Down
7 changes: 6 additions & 1 deletion js/hang/src/catalog/binary.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import * as z from "zod/mini";
import { CompressionSchema } from "./compression";
import { u53Schema } from "./integers";
import { ModeSchema } from "./mode";
import { RelativeBroadcastSchema } from "./path";
import { EpochSchema, RelativeBroadcastSchema } from "./path";

/**
* Schema for a single binary track: application data published as opaque payloads.
Expand All @@ -19,6 +19,11 @@ export const BinaryConfigSchema = z.looseObject({
// relative to the broadcast that served this catalog (e.g. "./source").
// If unset, the track lives in the same broadcast as the catalog.
broadcast: z.optional(RelativeBroadcastSchema),
// The publisher instance the reference names, when known. Absent accepts whichever instance
// resolves first. An epoch-aware route proving another instance fails the entry; an epochless
// route cannot prove one, so there it is best effort. Without `broadcast`, it names the
// catalog's own instance.
epoch: z.optional(EpochSchema),
// The track's name in its broadcast, when it differs from this entry's ID (its key in the
// catalog). Absent means the ID is the track name. Resolve it with `track`.
track: z.optional(z.string()),
Expand Down
7 changes: 6 additions & 1 deletion js/hang/src/catalog/json.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import * as z from "zod/mini";
import { CompressionSchema } from "./compression";
import { u53Schema } from "./integers";
import { ModeSchema } from "./mode";
import { RelativeBroadcastSchema } from "./path";
import { EpochSchema, RelativeBroadcastSchema } from "./path";

/**
* Schema for a single JSON track: application data published as a live JSON document or log.
Expand All @@ -18,6 +18,11 @@ export const JsonConfigSchema = z.looseObject({
// relative to the broadcast that served this catalog (e.g. "./source").
// If unset, the track lives in the same broadcast as the catalog.
broadcast: z.optional(RelativeBroadcastSchema),
// The publisher instance the reference names, when known. Absent accepts whichever instance
// resolves first. An epoch-aware route proving another instance fails the entry; an epochless
// route cannot prove one, so there it is best effort. Without `broadcast`, it names the
// catalog's own instance.
epoch: z.optional(EpochSchema),
// The track's name in its broadcast, when it differs from this entry's ID (its key in the
// catalog). Absent means the ID is the track name. Resolve it with `track`.
track: z.optional(z.string()),
Expand Down
27 changes: 26 additions & 1 deletion js/hang/src/catalog/path.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { Path } from "@moq/net";
import { Epoch, Path } from "@moq/net";
import * as z from "@zod/mini";

/**
Expand All @@ -18,3 +18,28 @@ export const RelativeBroadcastSchema: z.ZodMiniType<RelativeBroadcast, string> =
* out here so the catalog schemas' inferred types stay nameable from this package.
*/
export type RelativeBroadcast = string & { __brand: "Relative" };

function isEpoch(text: string): boolean {
try {
Epoch.parse(text);
return true;
} catch {
return false;
}
}

/**
* Zod schema for the publisher instance a catalog reference names: an entry's `epoch` beside its
* `broadcast`, or the archive's `replayEpoch`. A lowercase hyphenated UUIDv7, the same text MoQ
* routes carry; anything else refuses the catalog.
*/
export const EpochSchema: z.ZodMiniType<ReferenceEpoch, string> = z.pipe(
z.string().check(z.refine(isEpoch, "expected a lowercase hyphenated UUIDv7")),
z.transform((text) => text as ReferenceEpoch),
);

/**
* A validated reference epoch: the same brand as `Epoch.Valid` from `@moq/net`, spelled out here
* so the catalog schemas' inferred types stay nameable from this package.
*/
export type ReferenceEpoch = string & { readonly _brand: "epoch" };
45 changes: 44 additions & 1 deletion js/hang/src/catalog/root.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { expect, test } from "bun:test";
import * as z from "@zod/mini";
import { ARCHIVE_VERSION, ArchiveSchema } from "./archive.ts";
import { u53 } from "./integers.ts";
import type { RelativeBroadcast } from "./path.ts";
import type { ReferenceEpoch, RelativeBroadcast } from "./path.ts";
import { checkRenditions, DuplicateRendition, minVersion, RootSchema, UnsupportedVersion, VERSION } from "./root.ts";
import { track } from "./track.ts";

Expand Down Expand Up @@ -45,6 +45,49 @@ test("rendition broadcast reference is parsed and normalized", () => {
expect(parsed.video.renditions.video?.broadcast).toBe("source" as RelativeBroadcast);
});

// Mirrors Rust's `reference_epochs_roundtrip_in_every_section`.
test("every reference-bearing section carries an optional epoch", () => {
const EPOCH = "01890a5d-ac96-774b-bcce-b302099a8057" as ReferenceEpoch;
const catalog = (epoch: string) => ({
video: {
renditions: {
v: { broadcast: "./a", epoch, codec: "avc1.64001f", container: { kind: "legacy" } },
},
},
audio: {
renditions: {
a: {
broadcast: "./a",
epoch,
codec: "opus",
sampleRate: 48000,
numberOfChannels: 2,
container: { kind: "legacy" },
},
},
},
text: { renditions: { t: { broadcast: "./a", epoch, format: "vtt" } } },
json: { tracks: { j: { broadcast: "./a", epoch, mode: "snapshot" } } },
binary: { tracks: { b: { broadcast: "./a", epoch, mode: "snapshot" } } },
archive: { timelines: {}, replay: "./a", replayEpoch: epoch },
});

const parsed = RootSchema.parse(catalog(EPOCH));
if (!parsed.video || !("renditions" in parsed.video)) throw new Error("missing video section");
if (!parsed.audio || !("renditions" in parsed.audio)) throw new Error("missing audio section");
expect(parsed.video.renditions.v?.epoch).toBe(EPOCH);
expect(parsed.audio.renditions.a?.epoch).toBe(EPOCH);
expect(parsed.text?.renditions.t?.epoch).toBe(EPOCH);
expect(parsed.json?.tracks.j?.epoch).toBe(EPOCH);
expect(parsed.binary?.tracks.b?.epoch).toBe(EPOCH);
expect(parsed.archive?.replayEpoch).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"]) {
expect(RootSchema.safeParse(catalog(bad)).success).toBe(false);
}
});

test("rendition parent broadcast reference stays distinct from empty", () => {
const catalog = {
video: {
Expand Down
7 changes: 6 additions & 1 deletion js/hang/src/catalog/text.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import * as z from "zod/mini";
import { ContainerSchema } from "./container";
import { u53Schema } from "./integers";
import { RelativeBroadcastSchema } from "./path";
import { EpochSchema, RelativeBroadcastSchema } from "./path";

/**
* The cue serialization format of a text track, mirroring the Rust `TextFormat`.
Expand Down Expand Up @@ -35,6 +35,11 @@ export const TextConfigSchema = z.object({
// broadcast that served this catalog (e.g. "../source"). If unset, the track lives in the same
// broadcast as the catalog.
broadcast: z.optional(RelativeBroadcastSchema),
// The publisher instance the reference names, when known. Absent accepts whichever instance
// resolves first. An epoch-aware route proving another instance fails the entry; an epochless
// route cannot prove one, so there it is best effort. Without `broadcast`, it names the
// catalog's own instance.
epoch: z.optional(EpochSchema),
// The track's name in its broadcast, when it differs from this entry's ID (its key in the
// catalog). Absent means the ID is the track name. Resolve it with `track`.
track: z.optional(z.string()),
Expand Down
7 changes: 6 additions & 1 deletion js/hang/src/catalog/video.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ import { compareName, compareNumber } from "./compare";
import { ContainerSchema } from "./container";
import { hexSchema } from "./hex";
import { u8Schema, u53Schema } from "./integers";
import { RelativeBroadcastSchema } from "./path";
import { EpochSchema, RelativeBroadcastSchema } from "./path";

// Backwards compatibility: old track schema
const TrackSchema = z.object({
Expand Down Expand Up @@ -89,6 +89,11 @@ export const VideoConfigSchema = z.object({
// relative to the broadcast that served this catalog (e.g. "./source").
// If unset, the track lives in the same broadcast as the catalog.
broadcast: z.optional(RelativeBroadcastSchema),
// The publisher instance the reference names, when known. Absent accepts whichever instance
// resolves first. An epoch-aware route proving another instance fails the entry; an epochless
// route cannot prove one, so there it is best effort. Without `broadcast`, it names the
// catalog's own instance.
epoch: z.optional(EpochSchema),
// The track's name in its broadcast, when it differs from this entry's ID (its key in the
// catalog). Absent means the ID is the track name. Resolve it with `track`.
track: z.optional(z.string()),
Expand Down
2 changes: 2 additions & 0 deletions js/watch/src/audio/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ export type DecoderConfig = Pick<
/** The routing and decoder state whose changes require a replacement subscription. */
export type PlaybackIdentity = {
broadcast: Catalog.AudioConfig["broadcast"];
epoch: Catalog.AudioConfig["epoch"];
track: Catalog.AudioConfig["track"];
decoder: DecoderConfig;
};
Expand All @@ -39,6 +40,7 @@ export function decoderConfig(config: Catalog.AudioConfig): DecoderConfig {
export function playbackIdentity(config: Catalog.AudioConfig): PlaybackIdentity {
return {
broadcast: config.broadcast,
epoch: config.epoch,
track: config.track,
decoder: decoderConfig(config),
};
Expand Down
Loading
Loading