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
37 changes: 28 additions & 9 deletions drafts/draft-lcurley-moq-hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,7 @@ type Catalog = {
"audio": AudioSchema | undefined,
"video": VideoSchema | undefined,
"archive": ArchiveSchema | undefined,
"clock": ClockSchema | undefined,
"text": TextSchema | undefined,
"json": JsonTracks | undefined,
"binary": BinaryTracks | undefined,
Expand All @@ -126,7 +127,27 @@ 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, plus an optional `archive` entry ({{archive-catalog}}) naming the timeline track ({{timeline}}) that indexes their segments, and the application data tracks in {{data}}.
This specification defines audio, video, and text media tracks, plus an optional `archive` entry ({{archive-catalog}}) naming the timeline track ({{timeline}}) that indexes their segments, an optional root `clock` entry ({{clock}}) mapping content time to wall time, and the application data tracks in {{data}}.

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

~~~
type ClockSchema = {
"wall": number,
"timescale": number | undefined,
}
~~~

The `wall` field is the wall-clock time of PTS zero, in `timescale` units since the moq epoch, 2020-01-01T00:00:00Z.
A consumer derives the wall-clock time of any media timestamp as `wall + pts` after converting that timestamp into this timescale, and Unix time by adding the epoch back (for HLS `EXT-X-PROGRAM-DATE-TIME` or DASH `availabilityStartTime`).
Every media track and the archive index refer to this one mapping after timescale conversion; there are no competing wall epochs.

The `timescale` field is the units per second for `wall`, defaulting to 1000000 (microseconds) when absent.
A zero `timescale` is invalid, as is a `wall` outside the JSON-safe integer range; both are refused rather than truncated.

The mapping is fixed for the broadcast and independent of `archive`: a live-only publisher exposes its clock without creating a segment index.
A discontinuity marker is a delivery event, not a new epoch, and a system-clock adjustment never retimes the mapping.

## Video
A video track contains the necessary information to decode a video stream.
Expand Down Expand Up @@ -423,7 +444,7 @@ A `snapshot` group covers a single value (plus any deltas), so its window spans

### broadcast and timeline {#data-shared}
The `broadcast` field carries the same meaning here as it does for a media rendition ({{field-broadcast}}).
The `timeline` field advertises a companion timeline track indexing this track's groups, with the same `track` / `timescale` / `durationMax` / `wall` fields as the catalog's root `archive` entry ({{archive-catalog}}).
The `timeline` field advertises a companion timeline track indexing this track's groups, with the same `track` / `timescale` / `durationMax` fields as the catalog's root `archive` entry ({{archive-catalog}}).

## Binary Fields {#binary}
A decoder config field carrying raw bytes, notably `description` (an `AllowSharedBufferSource` in WebCodecs), is carried in the catalog as a hex string ({{!RFC4648, Section 8}}).
Expand Down Expand Up @@ -593,14 +614,12 @@ type TimelineSchema = {
"track": string,
"timescale": number | undefined,
"durationMax": number | undefined,
"wall": number | undefined,
}

type ArchiveSchema = {
"track": string,
"timescale": number | undefined,
"durationMax": number | undefined,
"wall": number | undefined,
"replay": string | undefined,
"store": string | undefined,
"version": number | undefined,
Expand All @@ -609,12 +628,13 @@ type ArchiveSchema = {

The `track` field names the MoQ track carrying the segment records.
The name `timeline.z` is RECOMMENDED; a consumer MUST use the advertised name rather than assuming it.
A live publisher without a store advertises `archive` with the timeline fields (`track`, `timescale`, `durationMax`, `wall`) alone.
A live publisher without a store advertises `archive` with the timeline fields (`track`, `timescale`, `durationMax`) alone.
Every range the timeline advertises is FETCHable; with a store they are also durable.
There is no sibling `timeline` entry and no generation: a client that must tell recordings apart compares `replay` and `store`.

The `timescale` field is the units per second for the records' `pts` and `duration` values, and for `durationMax` and `wall`.
The `timescale` field is the units per second for the records' `pts` and `duration` values, and for `durationMax`.
If absent, it defaults to 1000 (milliseconds).
A zero `timescale` is invalid and MUST be refused.

The `durationMax` field, if present, is the declared upper bound on a segment's `duration`, in `timescale` units.
A publisher that controls its encoder knows its keyframe cadence up front, so a consumer can size buffers or write an HLS `EXT-X-TARGETDURATION` from the catalog alone, before observing a single segment.
Expand All @@ -624,9 +644,7 @@ A publisher that cannot honor that MUST omit the field rather than emit a record
The field is absent when the media decides the segmentation instead, which is the common case: a real-time encoder places keyframes on demand and a single GOP may be minutes long, and a publisher importing a source it does not control cannot promise anything about that source.
A consumer needing a bound then derives one from the records it has seen, raising it as longer segments arrive.

The `wall` field, if known, is the wall-clock time of `pts` 0: in `timescale` units, measured from the moq epoch, 2020-01-01T00:00:00Z.
A consumer derives the wall-clock time of any segment as `wall + pts`, and Unix time by adding the epoch back (for HLS `EXT-X-PROGRAM-DATE-TIME` or DASH `availabilityStartTime`).
The epoch is 2020 rather than 1970 so the value stays small, safely within a 53-bit integer even at fine timescales.
Wall-clock mapping is the catalog root `clock` ({{clock}}), not this section: a consumer derives the wall-clock time of any segment as `clock.wall + pts` after converting `pts` into the clock's timescale.

The `replay` field, if present, is a relative MoQ broadcast path ({{field-broadcast}}) the archive is served back from.
Absent, the timeline lives on the catalog's own broadcast.
Expand Down Expand Up @@ -1054,6 +1072,7 @@ A publisher MAY estimate an unknown final duration from the frame cadence, but M
- Required exclusive DVR restart recovery to remove unreferenced group objects left by interrupted expiration.
- Replaced the catalog root `timeline` field with `archive`, carrying the timeline track plus optional `replay`, `store`, and recording `version`.
- A marker group of one empty frame declares a discontinuity. Empty groups mean nothing. Timestamps only move forward; a group below the live edge is malformed. A delivered sequence hole is a playhead event unless contiguous within 1 ms.
- Replaced the archive timeline `wall` field with a root `clock` section (`wall` plus `timescale`): one fixed broadcast mapping every track and the archive index convert into, independent of any archive. Zero timescales and walls past the JSON-safe integer range are refused.

# Acknowledgments
{:numbered="false"}
Expand Down
4 changes: 2 additions & 2 deletions js/hang/src/catalog/archive.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ export const ARCHIVE_VERSION = 1;
* Discovers the broadcast's segment index and any durable archive.
*
* This is the catalog's one name for the segment index: a live publisher sets the
* timeline fields (`track`, `timescale`, `durationMax`, `wall`) alone, and a recording
* timeline fields (`track`, `timescale`, `durationMax`) alone, and a recording
* also names the replay broadcast and object store those ranges live under. Every
* advertised range is FETCHable; with a store they are durable. There is no sibling
* `timeline` entry.
* `timeline` entry. Wall-clock mapping lives at the catalog root (`clock`), not here.
*/
export const ArchiveSchema = z.extend(TimelineSchema, {
// The MoQ broadcast the archive is served back from, relative to this catalog, if any.
Expand Down
80 changes: 80 additions & 0 deletions js/hang/src/catalog/clock.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
import { expect, test } from "bun:test";
import { ClockSchema, MOQ_EPOCH_UNIX_MILLIS, u53, wallClockTime } from "./index.ts";
import { RootSchema } from "./root.ts";

// Mirrors rs/hang/fixtures/catalog-clock.json: the canonical new shape, a root clock plus an
// archive without a wall field. A reader maps archive timestamps through the root clock after
// timescale conversion.
const FIXTURE = {
video: {
renditions: {
video: { codec: "avc1.64001f", container: { kind: "legacy" } },
},
},
audio: {
renditions: {
audio: { codec: "opus", container: { kind: "legacy" }, sampleRate: 48000, numberOfChannels: 2 },
},
},
clock: { wall: 1_751_846_400_000_000, timescale: 1_000_000 },
archive: { track: "timeline.z", timescale: 1000, durationMax: 2000 },
};

test("timescale defaults to microseconds", () => {
const parsed = ClockSchema.parse({ wall: 1000 });
expect(parsed.timescale).toBe(u53(1_000_000));
});

test("a zero timescale is refused", () => {
expect(() => ClockSchema.parse({ wall: 0, timescale: 0 })).toThrow();
});

test("an explicit null timescale is refused", () => {
expect(() => ClockSchema.parse({ wall: 0, timescale: null })).toThrow();
});

test("a timescale past u32 is refused", () => {
expect(() => ClockSchema.parse({ wall: 0, timescale: 4_294_967_296 })).toThrow();
});

test("a wall past the JSON-safe integers is refused", () => {
expect(() => ClockSchema.parse({ wall: Number.MAX_SAFE_INTEGER + 1 })).toThrow();
});

test("wallClockTime converts across timescales", () => {
const clock = ClockSchema.parse({ wall: 1_000_000 });
const epoch = MOQ_EPOCH_UNIX_MILLIS + 1000;

// PTS zero is the wall epoch itself.
expect(wallClockTime(clock, 0, 1000).getTime()).toBe(epoch);

// One media second later, whatever timescale names it.
for (const [pts, scale] of [
[1000, 1000],
[48_000, 48_000],
[90_000, 90_000],
] as const) {
expect(wallClockTime(clock, pts, scale).getTime()).toBe(epoch + 1000);
}
});

test("wallClockTime refuses bad inputs", () => {
const clock = ClockSchema.parse({ wall: 0 });
expect(() => wallClockTime(clock, 0, 0)).toThrow();
// A zero timescale that slipped past parsing still refuses at conversion.
const bad = JSON.parse('{"wall":0,"timescale":0}');
expect(() => wallClockTime(bad, 0, 1000)).toThrow();
expect(() => wallClockTime(clock, Number.MAX_SAFE_INTEGER, 1)).toThrow();
});

test("the packaged shape maps archive timestamps through the root clock", () => {
const catalog = RootSchema.parse(FIXTURE);
if (!catalog.clock) throw new Error("fixture lost its clock");
if (!catalog.archive) throw new Error("fixture lost its archive");

// Archive PTS 2000 (ms) lands 2s after the wall epoch.
expect(wallClockTime(catalog.clock, 2000, catalog.archive.timescale).getTime()).toBe(
MOQ_EPOCH_UNIX_MILLIS + 1_751_846_402_000,
);
expect("wall" in catalog.archive).toBe(false);
});
53 changes: 53 additions & 0 deletions js/hang/src/catalog/clock.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
import * as z from "@zod/mini";
import { u53Schema } from "./integers";
import { MOQ_EPOCH_UNIX_MILLIS } from "./timeline";

/** Units per second for a catalog clock. Matches Rust `u32`; zero is refused. */
const clockTimescaleSchema = z.number().check(z.int(), z.positive(), z.lte(4_294_967_295));

/**
* The broadcast's one continuous clock, advertised at the catalog root.
*
* `wall` is the wall-clock time of PTS zero, in `timescale` units since the moq epoch
* ({@link MOQ_EPOCH_UNIX_MILLIS}, 2020-01-01). Every media track and the archive index refer
* to this one mapping after timescale conversion, so there are no competing wall epochs. The
* publisher fixes it once and never overwrites it: a discontinuity marker is a delivery event,
* not a new epoch, and a system-clock adjustment never retimes it. It is independent of the
* `archive` entry: a live-only publisher exposes its clock without creating a segment index.
*/
export const ClockSchema = z.object({
// The wall-clock time of PTS zero, in `timescale` units since the moq epoch. Must fit in a
// JSON-safe integer so browsers read back exactly what the publisher wrote.
wall: u53Schema,

// Units per second for `wall`. Defaults to 1_000_000 (microseconds), the broadcast clock's
// own timescale. Zero is refused: no timestamp can be expressed in it. Bounded to u32 so
// Rust and JS accept the same catalogs.
timescale: z._default(clockTimescaleSchema, 1_000_000),
});

/** The broadcast's one continuous clock. */
export type Clock = z.infer<typeof ClockSchema>;

/**
* The wall-clock time of `pts`, given in `ptsTimescale` units per second, under the broadcast's
* fixed clock mapping (`wall + pts` after conversion into the clock's timescale).
*
* Throws on a zero timescale, a non-integer or unsafe value, or a result outside the JSON-safe
* integer range, rather than truncating.
*/
export function wallClockTime(clock: Clock, pts: number, ptsTimescale: number): Date {
if (!Number.isSafeInteger(clock.wall)) throw new RangeError(`invalid wall clock: ${clock.wall}`);
if (!Number.isSafeInteger(clock.timescale) || clock.timescale <= 0 || clock.timescale > 4_294_967_295)
throw new RangeError(`invalid timescale: ${clock.timescale}`);
if (!Number.isSafeInteger(pts) || pts < 0) throw new RangeError(`invalid pts: ${pts}`);
if (!Number.isSafeInteger(ptsTimescale) || ptsTimescale <= 0)
throw new RangeError(`invalid timescale: ${ptsTimescale}`);

const units = Math.floor((pts * clock.timescale) / ptsTimescale);
const total = clock.wall + units;
if (!Number.isSafeInteger(total)) throw new RangeError(`invalid wall clock: ${total}`);

const unixMillis = MOQ_EPOCH_UNIX_MILLIS + Math.floor((total * 1000) / clock.timescale);
return new Date(unixMillis);
Comment thread
kixelated marked this conversation as resolved.
Resolved
}
5 changes: 3 additions & 2 deletions js/hang/src/catalog/index.ts
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
/**
* JSON catalog schema and types describing a broadcast's tracks: audio/video decoder configs for
* WebCodecs, container format, and rendition layout, the `archive` entry, plus the `json` and
* `binary` sections listing application data tracks that aren't media.
* WebCodecs, container format, and rendition layout, the `archive` entry and root `clock`,
* plus the `json` and `binary` sections listing application data tracks that aren't media.
*
* @module
*/

export * from "./archive";
export * from "./audio";
export * from "./binary";
export * from "./clock";
export * from "./compression";
export * from "./container";
export * from "./format";
Expand Down
5 changes: 5 additions & 0 deletions js/hang/src/catalog/integers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,11 @@ export const u53Schema = z.number().check(z.int(), z.nonnegative(), z.lte(Number
/** Branded unsigned integer up to JavaScript's MAX_SAFE_INTEGER (2^53 - 1). */
export type U53 = z.infer<typeof u53Schema>;

/**
* Branded type for nonzero 53-bit unsigned integers: a timescale, which zero cannot express.
*/
export const nonzeroU53Schema = z.number().check(z.int(), z.positive(), z.lte(Number.MAX_SAFE_INTEGER)).brand("u53");

/**
* Convenience function to create a u8 value
*/
Expand Down
11 changes: 11 additions & 0 deletions js/hang/src/catalog/root.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,17 @@ test("legacy zero jitter is absent for audio and video", () => {
expect(JSON.stringify(parsed)).not.toContain('"jitter"');
});

test("clock round-trips at the root", () => {
const parsed = RootSchema.parse({
clock: { wall: 1_751_846_400_000_000, timescale: 1_000_000 },
});
expect(parsed.clock).toMatchObject({ wall: 1_751_846_400_000_000, timescale: 1_000_000 });
});

test("clock stays off the wire when absent", () => {
expect(JSON.stringify(RootSchema.parse({}))).not.toContain('"clock"');
});

test("archive round-trips at the root", () => {
const parsed = RootSchema.parse({
archive: {
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 @@ -3,6 +3,7 @@ import * as z from "@zod/mini";
import { ArchiveSchema } from "./archive";
import { AudioSchema } from "./audio";
import { BinarySchema } from "./binary";
import { ClockSchema } from "./clock";
import { JsonSchema } from "./json";
import { section } from "./section";
import { TextSchema } from "./text";
Expand All @@ -12,8 +13,9 @@ import { VideoSchema } from "./video";
* The root catalog: the base sections every hang broadcast carries.
*
* The media sections are `video`, `audio`, and `text`, alongside the broadcast's `archive`
* (the segment index and any durable recording); `json` and `binary` list application data
* tracks that aren't media. A section is omitted when it holds no tracks.
* (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.
*
* 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
Expand All @@ -25,6 +27,9 @@ export const RootSchema = z.looseObject({
audio: z.optional(AudioSchema),
// The broadcast's segment index and any durable archive, if the publisher offers one.
archive: z.optional(ArchiveSchema),
// The broadcast's one continuous clock, if the publisher exposes one. Independent of
// `archive`: a live-only publisher exposes its mapping without creating a segment index.
clock: z.optional(ClockSchema),
// `text` is now a reserved media section, but a catalog that carried an unrelated `text` key
// before this existed must not fail to parse: fall back to `undefined` (dropping the section)
// rather than rejecting the whole catalog, so video/audio still play.
Expand Down
20 changes: 8 additions & 12 deletions js/hang/src/catalog/timeline.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
import * as z from "@zod/mini";
import { u53, u53Schema } from "./integers";
import { nonzeroU53Schema, u53, u53Schema } from "./integers";

/**
* The moq epoch (2020-01-01T00:00:00Z) in Unix-epoch milliseconds.
*
* Timeline {@link Timeline.wall} values are measured from here rather than the Unix epoch so the
* Broadcast {@link Clock} wall values are measured from here rather than the Unix epoch so the
* numbers stay small (safely within a 53-bit integer even at fine timescales); a consumer recovers
* Unix time by adding this back.
*/
Expand All @@ -17,14 +17,17 @@ export const MOQ_EPOCH_UNIX_MILLIS = 1_577_836_800_000;
*
* Lives inside the catalog's root {@link Archive} entry: there is one timeline per broadcast,
* because its whole point is that segments are aligned across the broadcast's tracks. A
* publisher that doesn't segment simply omits the archive entry.
* publisher that doesn't segment simply omits the archive entry. Wall-clock mapping is the
* catalog root {@link Clock}'s job, not this section's: every track and this index refer to
* that one mapping after timescale conversion.
*/
export const TimelineSchema = z.object({
// The name of the MoQ track carrying the broadcast's segment records.
track: z.string(),

// Units per second for the records' `pts` (and `wall`). Defaults to 1000 (milliseconds).
timescale: z._default(u53Schema, u53(1000)),
// Units per second for the records' `pts`. Defaults to 1000 (milliseconds). Zero is
// refused: no timestamp can be expressed in it.
timescale: z._default(nonzeroU53Schema, u53(1000)),

// The declared upper bound on a segment's duration, in `timescale` units, when the
// publisher can promise one. A publisher that controls its encoder knows its keyframe
Expand All @@ -34,13 +37,6 @@ export const TimelineSchema = z.object({
// import of a source the publisher doesn't control), and a consumer needing a bound then
// derives one from the records it has seen.
durationMax: z.optional(u53Schema),

// The wall-clock time of pts 0, in `timescale` units since the moq epoch
// ({@link MOQ_EPOCH_UNIX_MILLIS}, 2020-01-01), if known. A consumer derives any group's
// wall-clock time as `wall + pts`, and Unix time by adding the moq epoch back (for HLS
// EXT-X-PROGRAM-DATE-TIME / DASH availabilityStartTime). Measured from 2020 rather than 1970 so
// the value stays small and safely within a 53-bit integer even at fine timescales.
wall: z.optional(u53Schema),
});

/** A media track's companion timeline description. */
Expand Down
Loading
Loading