Skip to content
2 changes: 1 addition & 1 deletion doc/concept/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ A few things the catalog can express beyond decoder config:
- **Preference.** A video rendition may carry a signed `preference`, default `0`. A player keeps only the highest preference it can decode, then picks by size and bitrate within it, as do the single-rendition egresses (RTMP play, WHEP, FLV, the transcoder's source). A publisher that adds its own H.264 copy of an H.265 source marks the copy `-1`, so only a viewer that can't decode H.265 pulls it. Picking a rendition by name still overrides it. The field is written only when nonzero.
- **Join interval.** The root `sync.interval` promises that every audio and video track starts a group at least that often outside a pause, such as a muted microphone sending nothing: the longest GOP any of them publishes. It is fixed for the broadcast, and the [HLS gateway](/bin/hls) numbers every rendition's segments on the grid it fixes, segments the smallest whole multiple of it at least a second long, from each group's first timestamp, so renditions share segment numbers. A publisher that knows its GOP declares it; Rust publishers (`moq-mux` and everything built on it) without one measure each track over its first second or group, whichever is longer, and `@moq/publish` declares its encoders' `join`. A broadcast without it gets no HLS playlists.
- **Clock.** The optional `sync.clock` maps PTS zero to wall time so every media track shares one fixed epoch after timescale conversion. Publish independent sources as sibling broadcasts under one prefix, such as `robot/front.hang` and `robot/rear.hang`; each broadcast's audio and video entries are renditions of that source. In one Rust publisher, pass the same `moq_mux::Clock` to each `catalog::Config::with_clock`; JS publishers on one page already share the page clock. Consumers discover the siblings by prefix and align their timestamps through the advertised wall mapping; `@moq/watch` plays one broadcast at a time.
- **Version.** The root `version` is the oldest moq-hang draft that reads the catalog correctly, written only when a field needs one newer than 03: a `track` that differs from its ID. Readers ignore fields they don't know, but refuse a `version` above their own with a typed "unsupported catalog version" error, so a player can say to upgrade instead of misreading the catalog. An additive field never raises it.
- **Version.** A `version` is the oldest moq-hang draft that reads what carries it correctly. Each rendition, data track, and include carries its own, written only when it uses a field newer than 03 that an older reader would misread: a `track` that differs from its ID. A reader skips an entry whose `version` is above its own and plays the rest, so a new-style rendition beside a compatibility one costs an older player only the new one, and the parsed catalog lists what was skipped so a player can say to upgrade. The root `version` is for a change to the root itself, which nothing in 04 makes: a reader refuses a catalog whose root `version` is above its own with a typed "unsupported catalog version" error. An additive field never raises either.
- **Extensions.** The root is a loose object. Applications add their own sections next to the ones hang defines, under a namespaced key such as `com.example.scte35`, optionally naming a track that carries the data. Every library exposes a way to write your section without clobbering the built-in ones, and readers ignore what they don't know. A section hang defines must have its shape: a `text`, `stats`, or any other built-in key holding something else refuses the whole catalog rather than reading as absent.

## Media reports
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/js/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ description: The media layer in TypeScript
The [hang media format](/concept/hang) as TypeScript types and codecs, shared
by [`@moq/watch`](/lib/js/watch) and [`@moq/publish`](/lib/js/publish).

- **Catalog**: zod schemas for the root, renditions, data tracks, and `sync`. The root is a loose object, so `z.extend(Catalog.RootSchema, { yourSection })` adds your own. `Catalog.watch(broadcast, { delay })` iterates validated catalog updates, each with the media timestamp it takes effect at: the newest only, or with a `delay`, every update a reader that far behind the live edge may still need. Parsing throws `Catalog.UnsupportedVersion` on a catalog that needs a newer moq-hang draft. `Catalog.Audio.ranked(renditions)` and `Catalog.Video.ranked(renditions)` order renditions best first, with enabled renditions ahead; `<moq-watch>` uses the video order.
- **Catalog**: zod schemas for the root, renditions, data tracks, includes, and `sync`. The root is a loose object, so `z.extend(Catalog.RootSchema, { yourSection })` adds your own. `Catalog.watch(broadcast, { delay })` iterates validated catalog updates, each with the media timestamp it takes effect at: the newest only, or with a `delay`, every update a reader that far behind the live edge may still need. Parsing throws `Catalog.UnsupportedVersion` on a catalog that needs a newer moq-hang draft; an entry that needs one is skipped instead, and `Catalog.skipped(root)` lists it. `Catalog.Audio.ranked(renditions)` and `Catalog.Video.ranked(renditions)` order renditions best first, with enabled renditions ahead; `<moq-watch>` uses the video order.
- **Containers**: `Container.Legacy` producer/consumer and separate `@moq/hang/cmaf` decoding. Import the CMAF module only when reading fMP4.
- **Utilities**: priority and latency math, a libav polyfill (Opus, plus AAC decoding) for runtimes without native WebCodecs audio, and the browser quirks the media packages work around.

Expand Down
2 changes: 1 addition & 1 deletion doc/lib/rs/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The [hang media format](/concept/hang) on top of `moq-net`: the catalog that
describes renditions with WebCodecs-style decoder configs, and the frame that
carries a timestamp with each payload.

- **Catalog.** `Catalog` types video, audio, and text renditions, the `json` and `binary` data tracks, and the `sync` section. Add your own sections through its type parameter, or read unknown ones as raw JSON. `Catalog::subscribe(&broadcast)` follows it live, yielding the newest update with the media timestamp it takes effect at; `catalog::Consumer::new(track, delay)` instead yields, in order, every update a reader playing `delay` behind the live edge may still need. Both fail with `Error::UnsupportedVersion` on a catalog that needs a newer moq-hang draft.
- **Catalog.** `Catalog` types video, audio, and text renditions, the `json` and `binary` data tracks, and the `sync` section. Add your own sections through its type parameter, or read unknown ones as raw JSON. `Catalog::subscribe(&broadcast)` follows it live, yielding the newest update with the media timestamp it takes effect at; `catalog::Consumer::new(track, delay)` instead yields, in order, every update a reader playing `delay` behind the live edge may still need. Both fail with `Error::UnsupportedVersion` on a catalog that needs a newer moq-hang draft; an entry that needs one is skipped instead and listed in `Catalog::skipped`.
- **Frames.** `container::Frame` encodes and decodes the `legacy` container, and `container::track_info` declares a media track. A rendition may instead declare `cmaf` or `loc`; an unknown container kind is kept rather than failing the catalog.
- **Codecs described**: H.264, H.265, VP8, VP9, AV1, AAC, Opus, PCM, FLAC, MP3, MP2, AC-3, E-AC-3.

Expand Down
22 changes: 15 additions & 7 deletions drafts/draft-lcurley-moq-hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,7 @@ type Catalog = {
"json": JsonTracks | undefined,
"binary": BinaryTracks | undefined,
"include": Record<string, {
"version": number | undefined,
"broadcast": string,
"instance": string | undefined,
}> | undefined,
Expand All @@ -149,18 +150,22 @@ For example, a chat entry should name a chat track, not carry individual chat me
This way catalog updates are rare and a client MAY choose to not subscribe.
The `json` and `binary` sections ({{data}}) are how a track like that is listed.

This specification defines audio, video, and text media tracks, an optional `sync` section ({{sync}}) holding the clock that maps content time to wall time and the interval a viewer can join on, the root `version` ({{catalog-version}}), the application data tracks in {{data}}, optional publisher statistics and solicited viewer feedback ({{media-stats}}), and whole broadcasts listed in `include` ({{include}}).
This specification defines audio, video, and text media tracks, an optional `sync` section ({{sync}}) holding the clock that maps content time to wall time and the interval a viewer can join on, the `version` of the catalog and of each entry ({{catalog-version}}), the application data tracks in {{data}}, optional publisher statistics and solicited viewer feedback ({{media-stats}}), and whole broadcasts listed in `include` ({{include}}).

## Version {#catalog-version}
The root `version` field is the oldest draft of this specification that reads the catalog correctly, by draft number: `4` needs a consumer of moq-hang-04 or later.
The `version` field is the oldest draft of this specification that reads what carries it correctly, by draft number: `4` needs a consumer of moq-hang-04 or later.
If absent, it is 3.
The root carries one for the whole catalog, and each entry of a map keyed by ID (an audio, video, or text rendition, a data track, or an include) carries one for itself.

A consumer MUST ignore fields it does not recognize.
A consumer MUST refuse a catalog whose `version` is above the draft it implements, or is not a non-negative integer, rather than read it; one that refuses SHOULD tell its user to upgrade.
A consumer MUST refuse a catalog whose root `version` is above the draft it implements, or any `version` that is not a non-negative integer, rather than read it; one that refuses SHOULD tell its user to upgrade.
A consumer MUST read an entry's `version` before the rest of the entry, and MUST skip an entry whose `version` is above the draft it implements: it reads the catalog as if that entry were absent, so the entry is never malformed.
One that skips an entry SHOULD tell its user that an upgrade would show more.

A publisher writes the highest draft whose fields the catalog uses that an older consumer would misread, and omits `version` while that is 3.
A change raises the version only when a consumer that ignored it would misread the catalog, never for a field it can safely ignore.
This draft needs `version` 4 only for a `track` ({{field-track}}) other than the entry's ID, which an older consumer subscribes to instead.
A publisher writes on each entry the highest draft whose fields the entry uses that an older consumer would misread, and on the root the highest such draft for the root's own fields, omitting each `version` while it is 3.
A field one entry carries raises only that entry's `version`, so an older consumer still plays the rest of the catalog, including a compatibility rendition beside the new one.
A change raises a version only when a consumer that ignored it would misread the catalog, never for a field it can safely ignore.
This draft writes no root `version`, and needs an entry `version` of 4 only for a `track` ({{field-track}}) other than the entry's ID, which an older consumer subscribes to instead.

Every other catalog change in this draft is safe to ignore: `enabled` ({{field-enabled}}) leaves an older consumer selecting a disabled rendition, which plays nothing; `sync` ({{sync}}) only offers the clock and join interval, which an older consumer goes without; `stats` and `echo` ({{media-stats}}) only offer optional tracks; `include` ({{include}}) only offers broadcasts to open on selection; video `reorder` leaves an older consumer inferring decode times from timestamps; `jitter`, `delay`, audio `warmup` ({{field-warmup}}), and the data track estimates are hints.

Expand Down Expand Up @@ -593,6 +598,7 @@ A consumer discovers these tracks the same way it discovers media, by reading th
### JSON {#json-tracks}
~~~
type JsonSchema = {
"version": number | undefined,
"mode": Mode,
"schema": string | undefined,
"broadcast": string | undefined,
Expand All @@ -610,6 +616,7 @@ It is descriptive: a consumer that does not recognize it MUST still be able to r
### Binary {#binary-tracks}
~~~
type BinarySchema = {
"version": number | undefined,
"mode": Mode,
"mime": string | undefined,
"broadcast": string | undefined,
Expand Down Expand Up @@ -682,6 +689,7 @@ Audio, video, and text renditions share the following fields, extending the WebC

~~~
type CommonExtensions = {
"version": number | undefined,
"broadcast": string | undefined,
"instance": string | undefined,
"track": string | undefined,
Expand Down Expand Up @@ -1085,7 +1093,7 @@ This document has no IANA actions.
- Replaced the root `archive` section and its per-track timelines with the root `sync` section ({{sync}}). Its `interval` is the longest group of any audio or video track, fixed for the broadcast, and the grid an edge numbers HLS and DASH segments on, each segment the smallest whole multiple of it at least a second long, from each group's first timestamp ({{hls}}); the root `clock` moved to `sync.clock`. Segment indexes, frame positions, `end`, `keyframe`, `timescale`, `replay`, `replayEpoch`, `store`, and `version` are gone.
- A reader refuses a JSON frame in which an object repeats a member name.
- A malformed audio or video rendition ({{malformed}}) refuses the catalog: a known codec string without valid parameters, a zero or out-of-range dimension, sample rate, or channel count, a bitrate or duration above 2^53 - 1, or a container without a string `kind`.
- Added the root `version` ({{catalog-version}}): the oldest draft that reads the catalog, which a consumer refuses when above its own. A `track` other than the entry's ID needs 4. Consumers MUST ignore unknown fields.
- Added `version` on the root and on each rendition, data track, and include ({{catalog-version}}): the oldest draft that reads it. A consumer refuses a catalog whose root `version` is above its own, and skips an entry whose `version` is. A `track` other than the entry's ID needs an entry `version` of 4. Consumers MUST ignore unknown fields.
- 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.
- Removed the Recording section: the store layout is a moq-archive format, documented with that crate, not part of this draft.
- Removed the viewer feedback `latency` field.
Expand Down
12 changes: 12 additions & 0 deletions js/hang/api/catalog.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -501,6 +501,16 @@ export const RootSchema: ZodMiniObject<{
}, $strip>>;
}, $loose>;

export interface Skipped {
audio: Record<string, number>;
binary: Record<string, number>;
include: Record<string, number>;
json: Record<string, number>;
text: Record<string, number>;
version: number;
video: Record<string, number>;
}

export type Stats = infer<typeof StatsSchema>;

export const StatsSchema: ZodMiniObject<{
Expand Down Expand Up @@ -825,6 +835,8 @@ export function modeSupported(mode: Mode): mode is KnownMode;

export const nonzeroU53Schema: $ZodBranded<ZodMiniNumber<number>, "u53", "out">;

export function skipped(root: Root): Skipped | undefined;

export function track(id: string, config: {
track?: string;
}): string;
Expand Down
9 changes: 7 additions & 2 deletions js/hang/src/catalog/parity.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { expect, test } from "bun:test";
import { checkRenditions, RootSchema } from "./root.ts";
import { checkRenditions, RootSchema, skipped } from "./root.ts";

interface Case {
name: string;
Expand All @@ -11,10 +11,12 @@ interface Case {
json?: string[];
binary?: string[];
include?: string[];
skipped?: Record<string, Record<string, number>>;
}

// The corpus rs/hang also loads: both languages accept the same catalogs and keep the same
// rendition, data track, and include IDs, so a divergence fails CI on whichever side drifts.
// rendition, data track, and include IDs, and skip the same newer entries, so a divergence fails CI
// on whichever side drifts.
const cases = (await Bun.file(
new URL("../../../../rs/hang/fixtures/catalog-parity.json", import.meta.url),
).json()) as Case[];
Expand All @@ -36,5 +38,8 @@ for (const c of cases) {
expect(ids(root.json?.tracks)).toEqual(c.json ?? []);
expect(ids(root.binary?.tracks)).toEqual(c.binary ?? []);
expect(ids(root.include)).toEqual(c.include ?? []);
const { version: _, ...sections } = skipped(root) ?? { version: 0 };
const nonempty = Object.entries(sections).filter(([, entries]) => Object.keys(entries).length > 0);
expect(Object.fromEntries(nonempty)).toEqual(c.skipped ?? {});
});
}
Loading