From e8fb88d4e2fc5f4bbbf9afe033273a958cd87ea2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 13 Sep 2026 15:46:59 -0700 Subject: [PATCH 1/4] claim quest/m1/broadcast-clock From 511b29b434a80669cacefe6356c8fec804e770c9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 13 Sep 2026 17:34:56 -0700 Subject: [PATCH 2/4] feat(hang)!: one continuous broadcast clock at the catalog root Replaces Archive.timeline.wall with clock: { wall, timescale } advertised at the catalog root, owned by the shared moq_mux::Clock. HLS program-date-time and DASH availabilityStartTime map through it after timescale conversion. --- drafts/draft-lcurley-moq-hang.md | 37 +- js/hang/src/catalog/archive.ts | 4 +- js/hang/src/catalog/clock.test.ts | 72 +++ js/hang/src/catalog/clock.ts | 49 ++ js/hang/src/catalog/index.ts | 5 +- js/hang/src/catalog/integers.ts | 5 + js/hang/src/catalog/root.test.ts | 11 + js/hang/src/catalog/root.ts | 9 +- js/hang/src/catalog/timeline.ts | 20 +- js/hang/src/container/timeline.test.ts | 18 +- js/hang/src/container/timeline.ts | 21 +- quest/m1/README.md | 1 - quest/m1/broadcast-clock.md | 64 --- quest/m1/merge-dev.md | 1 - ...l-clock-latency-target-for-synchronized.md | 1 - ...te-35-ad-cue-signaling-carried-opaquely.md | 2 - ...generated-media-timelines-to-wall-clock.md | 2 - quest/m2/emsg.md | 2 - quest/m2/flv-script.md | 2 - quest/m2/id3.md | 2 - quest/m2/metadata-association.md | 1 - quest/m2/publisher-clock.md | 1 - rs/hang/CHANGELOG.md | 4 + rs/hang/fixtures/catalog-clock.json | 24 + rs/hang/src/catalog/archive.rs | 7 +- rs/hang/src/catalog/clock.rs | 183 +++++++ rs/hang/src/catalog/mod.rs | 2 + rs/hang/src/catalog/root.rs | 53 ++- rs/hang/src/catalog/timeline.rs | 45 +- rs/hang/src/error.rs | 8 + rs/moq-hls/src/export/mod.rs | 114 ++++- rs/moq-hls/src/export/playlist.rs | 2 +- rs/moq-hls/src/export/rendition.rs | 30 +- rs/moq-hls/src/export/renditions.rs | 7 +- rs/moq-mux/CHANGELOG.md | 10 + rs/moq-mux/src/catalog/hang/ext.rs | 25 +- rs/moq-mux/src/catalog/producer.rs | 63 ++- rs/moq-mux/src/clock.rs | 445 +++++++++++++++++- rs/moq-mux/src/error.rs | 4 + rs/moq-mux/src/lib.rs | 2 +- rs/moq-mux/src/timeline.rs | 48 +- rs/moq-transcode/src/catalog.rs | 8 +- 42 files changed, 1170 insertions(+), 244 deletions(-) create mode 100644 js/hang/src/catalog/clock.test.ts create mode 100644 js/hang/src/catalog/clock.ts delete mode 100644 quest/m1/broadcast-clock.md create mode 100644 rs/hang/fixtures/catalog-clock.json create mode 100644 rs/hang/src/catalog/clock.rs diff --git a/drafts/draft-lcurley-moq-hang.md b/drafts/draft-lcurley-moq-hang.md index 873ddcc8459..f0458c23952 100644 --- a/drafts/draft-lcurley-moq-hang.md +++ b/drafts/draft-lcurley-moq-hang.md @@ -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, @@ -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. @@ -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}}). @@ -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, @@ -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. @@ -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. @@ -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"} diff --git a/js/hang/src/catalog/archive.ts b/js/hang/src/catalog/archive.ts index a309d781c38..f4d111c123d 100644 --- a/js/hang/src/catalog/archive.ts +++ b/js/hang/src/catalog/archive.ts @@ -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. diff --git a/js/hang/src/catalog/clock.test.ts b/js/hang/src/catalog/clock.test.ts new file mode 100644 index 00000000000..da0ab38ae31 --- /dev/null +++ b/js/hang/src/catalog/clock.test.ts @@ -0,0 +1,72 @@ +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("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); +}); diff --git a/js/hang/src/catalog/clock.ts b/js/hang/src/catalog/clock.ts new file mode 100644 index 00000000000..d5986282ae1 --- /dev/null +++ b/js/hang/src/catalog/clock.ts @@ -0,0 +1,49 @@ +import * as z from "@zod/mini"; +import { nonzeroU53Schema, u53, u53Schema } from "./integers"; +import { MOQ_EPOCH_UNIX_MILLIS } from "./timeline"; + +/** + * 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. + timescale: z._default(nonzeroU53Schema, u53(1_000_000)), +}); + +/** The broadcast's one continuous clock. */ +export type Clock = z.infer; + +/** + * 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) + 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); +} diff --git a/js/hang/src/catalog/index.ts b/js/hang/src/catalog/index.ts index b616b1e33e5..e5da47739cf 100644 --- a/js/hang/src/catalog/index.ts +++ b/js/hang/src/catalog/index.ts @@ -1,7 +1,7 @@ /** * 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 */ @@ -9,6 +9,7 @@ export * from "./archive"; export * from "./audio"; export * from "./binary"; +export * from "./clock"; export * from "./compression"; export * from "./container"; export * from "./format"; diff --git a/js/hang/src/catalog/integers.ts b/js/hang/src/catalog/integers.ts index fdce7fd886b..e85d87cc5f0 100644 --- a/js/hang/src/catalog/integers.ts +++ b/js/hang/src/catalog/integers.ts @@ -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; +/** + * 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 */ diff --git a/js/hang/src/catalog/root.test.ts b/js/hang/src/catalog/root.test.ts index af7d2be1b37..e422958bf47 100644 --- a/js/hang/src/catalog/root.test.ts +++ b/js/hang/src/catalog/root.test.ts @@ -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: { diff --git a/js/hang/src/catalog/root.ts b/js/hang/src/catalog/root.ts index 1b92f67dd12..1840edb0567 100644 --- a/js/hang/src/catalog/root.ts +++ b/js/hang/src/catalog/root.ts @@ -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"; @@ -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 @@ -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. diff --git a/js/hang/src/catalog/timeline.ts b/js/hang/src/catalog/timeline.ts index de2303b799e..47b3d7dc795 100644 --- a/js/hang/src/catalog/timeline.ts +++ b/js/hang/src/catalog/timeline.ts @@ -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. */ @@ -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 @@ -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. */ diff --git a/js/hang/src/container/timeline.test.ts b/js/hang/src/container/timeline.test.ts index 467c11b9ba5..cdc08fd5c30 100644 --- a/js/hang/src/container/timeline.test.ts +++ b/js/hang/src/container/timeline.test.ts @@ -2,7 +2,7 @@ import { expect, test } from "bun:test"; import * as Json from "@moq/json"; import type { Time } from "@moq/net"; import { Track } from "@moq/net"; -import { MOQ_EPOCH_UNIX_MILLIS, u53 } from "../catalog"; +import { u53 } from "../catalog"; import { Producer, type Record } from "./timeline.ts"; const us = (ms: number): Time.Micro => (ms * 1000) as Time.Micro; @@ -379,16 +379,12 @@ test("a non-keyframe range start is flagged", async () => { expect(out[1]?.tracks?.video0[0].keyframe).toBe(false); }); -test("the wall-clock anchor is advertised from the config", () => { - expect(capture().timeline.section().wall).toBeUndefined(); - - // The wire counts from the moq epoch, so pts 0 at exactly the epoch advertises 0. - const epoch = new Date(MOQ_EPOCH_UNIX_MILLIS); - expect(capture({ wall: epoch }).timeline.section().wall).toBe(u53(0)); - expect(capture({ wall: new Date(MOQ_EPOCH_UNIX_MILLIS + 1000) }).timeline.section().wall).toBe(u53(1000)); - - // A time before the epoch isn't representable, so it clamps rather than going negative. - expect(capture({ wall: new Date(0) }).timeline.section().wall).toBe(u53(0)); +test("the timeline section carries no wall anchor", () => { + // Wall mapping moved to the catalog root clock: the timeline section carries the track, + // timescale, and duration bound, and nothing else time-anchoring. + const section = capture().timeline.section(); + expect(section).toEqual({ track: "timeline.z", timescale: u53(1000), durationMax: undefined }); + expect("wall" in section).toBe(false); }); // Reservations nest like the catalog's, so the first batch to finish doesn't publish records diff --git a/js/hang/src/container/timeline.ts b/js/hang/src/container/timeline.ts index d71536cca1c..9ca9749ac77 100644 --- a/js/hang/src/container/timeline.ts +++ b/js/hang/src/container/timeline.ts @@ -18,7 +18,7 @@ import * as Json from "@moq/json"; import type * as Moq from "@moq/net"; import type { Time } from "@moq/net"; import type * as Catalog from "../catalog"; -import { MOQ_EPOCH_UNIX_MILLIS, u53 } from "../catalog"; +import { u53 } from "../catalog"; /** * A contiguous run of groups a track contributes to a segment, `start` through `end` @@ -94,18 +94,6 @@ export interface ProducerProps { * importing a source the publisher doesn't control. */ durationMax?: number; - - /** - * The wall-clock time of `pts` 0, advertised in the catalog when set. - * - * It anchors content time to an absolute clock, which is what an HLS - * EXT-X-PROGRAM-DATE-TIME or a DASH availabilityStartTime needs: `new Date()` for a live - * publisher whose timestamps start now, or the content's real start for a recording. - * - * Clamped to the moq epoch ({@link Catalog.MOQ_EPOCH_UNIX_MILLIS}, 2020), which the wire - * format measures from: an earlier time isn't representable. - */ - wall?: Date; } /** One enrolled track's report state. */ @@ -150,18 +138,12 @@ export class Producer { #reservers = 0; // A segment overran durationMax, so the timeline stopped publishing. #overrun?: Error; - // The wall-clock time of pts 0, in timescale units since the moq epoch (advertised in the section). - #wall?: number; /** Wrap an already-created MoQ track (named {@link DEFAULT_NAME} by convention). */ constructor(track: Moq.Track.Producer, props: ProducerProps = {}) { this.#trackName = track.name; this.#durationMinUs = (props.durationMin ?? DEFAULT_DURATION_MIN_MS) * 1000; this.#durationMaxUs = props.durationMax === undefined ? undefined : props.durationMax * 1000; - if (props.wall !== undefined) { - const unixMillis = Math.max(props.wall.getTime(), MOQ_EPOCH_UNIX_MILLIS); - this.#wall = Math.floor(((unixMillis - MOQ_EPOCH_UNIX_MILLIS) * DEFAULT_TIMESCALE) / 1000); - } this.#window = new Json.Window.Producer({ track, compression: true, @@ -262,7 +244,6 @@ export class Producer { track: this.#trackName, timescale: u53(DEFAULT_TIMESCALE), durationMax, - wall: this.#wall === undefined ? undefined : u53(this.#wall), }; } diff --git a/quest/m1/README.md b/quest/m1/README.md index 5ddcdcee7f6..d0df8be6c64 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -27,7 +27,6 @@ does not require it. - [Reserved codes](/quest/m1/lite-reserved-codes.md) - the four stream codes sent from the reserved range are registered in the draft's own range and round-trip in both languages - [Origin scope API](/quest/m1/api-origin-pattern-scopes.md) - typed scope grants preserve current prefixes and refuse unsupported patterns - [Cluster peer API](/quest/m1/api-cluster-peer-config.md) - typed peer configuration supports current symmetric policy -- [Broadcast clock](/quest/m1/broadcast-clock.md) - replace archive wall with one fixed catalog-root clock shared by every track - [Publisher finish borrows](/quest/m1/api-finish-borrow.md) - finish borrows the handle so abort can still run after a clean end - [Rate estimate names](/quest/m1/api-rate-estimate-names.md) - the send and receive estimates carry `estimated_*_rate` on the C ABI, every binding, and moqsink - [Announce names](/quest/m1/api-announce-names.md) - one name per announce, request, and origin config concept in Rust, JS, moq-ffi, and C diff --git a/quest/m1/broadcast-clock.md b/quest/m1/broadcast-clock.md deleted file mode 100644 index 263be694a4e..00000000000 --- a/quest/m1/broadcast-clock.md +++ /dev/null @@ -1,64 +0,0 @@ -# [L] One continuous broadcast clock at the catalog root - -## Goal - -The published catalog and clock API express one continuous broadcast clock: -wall time is a fixed epoch plus PTS converted from the track's timescale. -Existing archive readers and writers use this mapping before release; native -and browser publisher adoption is a separate M2 quest. Wall time is metadata -for applications, not a library playback synchronization source. - -## Plan - -Reuse the broadcast's existing `moq_mux::Clock`, shared through the catalog -producer. It advances from one monotonic Instant. Establish its corresponding -wall epoch once; sampling wall time when a delayed first frame arrives must -account for that frame's PTS rather than pretend it is timestamp zero. - -The current Hang timeline is a broadcast-wide segment index advertised under -Archive, and `timeline::Config.wall` already describes its fixed mapping. -There are no per-rendition timeline producers or `set_wall` methods to wire. -Provide the functional shared clock owner and explicit media-timescale -conversion here. Native capture, CLI imports, and `js/publish` adoption belong -to the publisher integration quest; GStreamer has its own adapter quest. - -The clock contract supports translating a reset source onto its existing -mapping, including real idle gaps. Exercise that operation with synthetic -sources here; each publisher adapter wires its restart detection in M2. Preserve permitted B-frame -reordering within a group. A discontinuity marker signals a delivery/playhead -event, not a new wall epoch. Do not overwrite wall, introduce per-record -anchors, or retime retained records after a system-clock adjustment. Refuse a -source that cannot be mapped consistently within that broadcast. - -Advertise the fixed broadcast clock at the Hang catalog root, independently -of Archive. A live-only publisher must not create an archive timeline just to -expose its clock. Every media track and any archive index refer to that one -mapping after timescale conversion; there must not be competing wall epochs. -The root shape is `clock: { wall, timescale }`: `wall` is PTS zero in clock -timescale units since the existing MoQ epoch, 2020-01-01T00:00:00Z. Each media -track and the archive index keep their own timescales; conversion into this -one clock is explicit. Validate nonzero timescales and JSON-safe integer -bounds rather than truncating. - -Replace the old Archive.timeline.wall field on dev. Update Rust/JS catalog -models, publishers, readers, HLS wall-time mapping, fixtures, documentation, -and the Hang draft in the same PR. Do not retain two independently editable -wall fields or ship a compatibility alias. Existing `timeline::Config.wall` -plumbing must migrate to the same broadcast clock owner. Report the published -API break and wire/catalog migration in the PR; do not bump package versions. -Use a packaged catalog-reader fixture to verify the new shape and wire the -clock tests into CI. - -Clock-owner and catalog fixtures cover delayed first timestamps, multiple -track timescales, reset translation with an idle gap, preserved archive records, -numeric bounds, and wall-clock adjustment without retiming. Test the existing -archive/HLS migration end to end. Full capture and publisher restart fixtures -belong to the M2 integration; do not claim those adapters are already wired. - -## Related - -- [Publisher clocks](/quest/m2/publisher-clock.md) - adopts the clock contract across native capture, CLI import, and browser publication - -- [GStreamer wall clock](/quest/m2/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md) - selects one trusted clock mapping for every pad -- [Browser wall access](/quest/m2/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md) - exposes the same broadcast clock to applications -- [Cross-track correlation](/quest/m3/teleop/correlation.md) - applications compare clocks they know are synchronized diff --git a/quest/m1/merge-dev.md b/quest/m1/merge-dev.md index 17b7481f432..ea4fdb9b67b 100644 --- a/quest/m1/merge-dev.md +++ b/quest/m1/merge-dev.md @@ -55,7 +55,6 @@ additive quest that builds on dev-only code start on main afterwards from - [Deprecated sweep](/quest/m1/deprecated-sweep.md) - the breaking release removes what it deprecates - [Origin scope API](/quest/m1/api-origin-pattern-scopes.md) - typed scope grants preserve current prefixes and refuse unsupported patterns - [Cluster peer API](/quest/m1/api-cluster-peer-config.md) - typed peer configuration supports current symmetric policy -- [Broadcast clock](/quest/m1/broadcast-clock.md) - the root clock replaces the published archive wall field on dev before release - [m0](/quest/m0/README.md) - every release blocker lands or is punted before the merge ## Closes diff --git a/quest/m2/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md b/quest/m2/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md index fa7980782bc..879dfcd0cb7 100644 --- a/quest/m2/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md +++ b/quest/m2/2278-watch-absolute-wall-clock-latency-target-for-synchronized.md @@ -32,7 +32,6 @@ a live-only broadcast with no archive timeline. - [Merge dev](/quest/m1/merge-dev.md) - the required M1 APIs must be available on main before this implementation starts -- [Broadcast clock](/quest/m1/broadcast-clock.md) - the catalog shape and shared clock owner - [Publisher clocks](/quest/m2/publisher-clock.md) - built-in publishers populate the mapping applications read ## Closes diff --git a/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md b/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md index d0bd37286dc..4976e22fee2 100644 --- a/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md +++ b/quest/m2/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md @@ -45,8 +45,6 @@ be in it the day it ships. Cross-package sync: `rs/hang`, `js/hang`, - [Merge dev](/quest/m1/merge-dev.md) - the required M1 APIs must be available on main before this implementation starts -- [Broadcast clock](/quest/m1/broadcast-clock.md) - event times use the landed shared clock contract - - [Metadata association contract](/quest/m2/metadata-association.md) - settles the shared framing and missing-data semantics before this section adopts them ## Closes diff --git a/quest/m2/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md b/quest/m2/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md index e4f89ee6327..de02f57034e 100644 --- a/quest/m2/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md +++ b/quest/m2/3021-moq-gst-anchor-generated-media-timelines-to-wall-clock.md @@ -36,8 +36,6 @@ correction is introduced here. Run the GStreamer CI and smoke-full lanes. - [Merge dev](/quest/m1/merge-dev.md) - the required M1 APIs must be available on main before this implementation starts -- [Continuous broadcast clock](/quest/m1/broadcast-clock.md) - fixes the shared epoch and catalog exposure before this adapter supplies clock observations - ## Closes - [#3021](https://github.com/moq-dev/moq/issues/3021) - close this issue when the quest finishes diff --git a/quest/m2/emsg.md b/quest/m2/emsg.md index d81ecbaa849..035c311ae3e 100644 --- a/quest/m2/emsg.md +++ b/quest/m2/emsg.md @@ -36,8 +36,6 @@ byte-identical. - [Merge dev](/quest/m1/merge-dev.md) - the required M1 APIs must be available on main before this implementation starts -- [Broadcast clock](/quest/m1/broadcast-clock.md) - event times use the landed shared clock contract - - [Metadata association contract](/quest/m2/metadata-association.md) - settles the shared framing and missing-data semantics before this section adopts them ## Related diff --git a/quest/m2/flv-script.md b/quest/m2/flv-script.md index aa6d2a7a3a1..bcf67fee4e6 100644 --- a/quest/m2/flv-script.md +++ b/quest/m2/flv-script.md @@ -33,8 +33,6 @@ media tag, and a byte-identical round trip. - [Merge dev](/quest/m1/merge-dev.md) - the required M1 APIs must be available on main before this implementation starts -- [Broadcast clock](/quest/m1/broadcast-clock.md) - event times use the landed shared clock contract - - [Metadata association contract](/quest/m2/metadata-association.md) - settles the shared framing and missing-data semantics before this section adopts them ## Related diff --git a/quest/m2/id3.md b/quest/m2/id3.md index 80824f47069..ca99afeca13 100644 --- a/quest/m2/id3.md +++ b/quest/m2/id3.md @@ -42,8 +42,6 @@ generic. - [Merge dev](/quest/m1/merge-dev.md) - the required M1 APIs must be available on main before this implementation starts -- [Broadcast clock](/quest/m1/broadcast-clock.md) - event times use the landed shared clock contract - - [Metadata association contract](/quest/m2/metadata-association.md) - settles the shared framing and missing-data semantics before this section adopts them ## Related diff --git a/quest/m2/metadata-association.md b/quest/m2/metadata-association.md index ff925f1a74d..a02a3833686 100644 --- a/quest/m2/metadata-association.md +++ b/quest/m2/metadata-association.md @@ -47,5 +47,4 @@ Any eventual wire-format change belongs in the matching Hang draft. ## Related -- [Broadcast clock](/quest/m1/broadcast-clock.md) - one continuous clock, independent of archives - [SEI evaluation](/quest/m3/sei/README.md) - a separate decision about extracting codec metadata diff --git a/quest/m2/publisher-clock.md b/quest/m2/publisher-clock.md index 870b6c0b050..c96e85cd1d4 100644 --- a/quest/m2/publisher-clock.md +++ b/quest/m2/publisher-clock.md @@ -29,7 +29,6 @@ catalog representation. GStreamer's clock observation remains its own quest. - [Merge dev](/quest/m1/merge-dev.md) - the required M1 APIs must be available on main before this implementation starts -- [Broadcast clock](/quest/m1/broadcast-clock.md) - functional owner and catalog contract - [Publisher discontinuity](/quest/m2/js-publish-discontinuity.md) - use the settled browser restart-marker path ## Related diff --git a/rs/hang/CHANGELOG.md b/rs/hang/CHANGELOG.md index 9935612a0e8..1f6795b07bd 100644 --- a/rs/hang/CHANGELOG.md +++ b/rs/hang/CHANGELOG.md @@ -12,6 +12,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - [**breaking**] Replace the catalog root `timeline` entry with `archive`. The flattened timeline fields (`track`, `timescale`, `durationMax`, `wall`) stay; optional `replay`, `store`, and `version` advertise a durable recording. +- [**breaking**] Replace the archive timeline `wall` field with a root `clock` + section (`{wall, timescale}`). Wall time is one fixed broadcast mapping: PTS zero in the + clock timescale since the moq epoch, with every track and the archive index converting + into it. Zero timescales and wall values past the JSON-safe integer range are refused. ### Added diff --git a/rs/hang/fixtures/catalog-clock.json b/rs/hang/fixtures/catalog-clock.json new file mode 100644 index 00000000000..1db86f67f8f --- /dev/null +++ b/rs/hang/fixtures/catalog-clock.json @@ -0,0 +1,24 @@ +{ + "video": { + "renditions": { + "video": { + "codec": "avc1.64001f", + "codedWidth": 1280, + "codedHeight": 720, + "container": { "kind": "legacy" } + } + } + }, + "audio": { + "renditions": { + "audio": { + "codec": "opus", + "sampleRate": 48000, + "numberOfChannels": 2, + "container": { "kind": "legacy" } + } + } + }, + "clock": { "wall": 1751846400000000, "timescale": 1000000 }, + "archive": { "track": "timeline.z", "timescale": 1000, "durationMax": 2000 } +} diff --git a/rs/hang/src/catalog/archive.rs b/rs/hang/src/catalog/archive.rs index 21a848184f7..44501781a94 100644 --- a/rs/hang/src/catalog/archive.rs +++ b/rs/hang/src/catalog/archive.rs @@ -16,9 +16,10 @@ use super::Timeline; #[serde(rename_all = "camelCase")] #[non_exhaustive] pub struct Archive { - /// The timeline track: its name, timescale, optional duration bound, and wall-clock - /// anchor. Flattened on the wire so a live publisher's `archive` is those fields - /// alone. + /// The timeline track: its name, timescale, and optional duration bound. Flattened on + /// the wire so a live publisher's `archive` is those fields alone. Wall-clock mapping lives + /// at the catalog root ([`Clock`](super::Clock)), not here: there is one broadcast clock, and + /// this index refers to it after timescale conversion. #[serde(flatten)] pub timeline: Timeline, diff --git a/rs/hang/src/catalog/clock.rs b/rs/hang/src/catalog/clock.rs new file mode 100644 index 00000000000..382d848b15a --- /dev/null +++ b/rs/hang/src/catalog/clock.rs @@ -0,0 +1,183 @@ +use serde::{Deserialize, Deserializer, Serialize}; + +use super::MOQ_EPOCH_UNIX_MILLIS; +use crate::Result; + +/// The largest integer JSON preserves exactly (2^53 - 1). +/// +/// Catalog wall values must fit here so browser consumers read the same number the publisher +/// wrote. Anything larger is refused rather than truncated. +pub const MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991; + +/// Deserialize a wall value, refusing anything outside the JSON-safe integer range. +pub(crate) fn deserialize_wall<'de, D>(deserializer: D) -> std::result::Result +where + D: Deserializer<'de>, +{ + let value = u64::deserialize(deserializer)?; + if value > MAX_SAFE_INTEGER { + return Err(serde::de::Error::custom(format!("invalid wall clock: {value}"))); + } + Ok(value) +} + +/// The broadcast's one continuous clock, advertised at the catalog root. +/// +/// `wall` is the wall-clock time of PTS zero, in [`timescale`](Self::timescale) units since the +/// moq epoch ([`MOQ_EPOCH_UNIX_MILLIS`], 2020-01-01). 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 moq epoch back (an absolute clock for HLS +/// `EXT-X-PROGRAM-DATE-TIME` / DASH `availabilityStartTime`). +/// +/// There is one mapping per broadcast: every media track and the archive index refer to it 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 +/// [`Archive`](super::Archive): a live-only publisher exposes its clock without creating a +/// segment index. +/// +/// Measured from 2020 rather than 1970 so the value stays small and safely within a 53-bit +/// integer even at fine timescales. +#[serde_with::skip_serializing_none] +#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct Clock { + /// The wall-clock time of PTS zero, in [`timescale`](Self::timescale) units since the moq + /// epoch. Must fit in a JSON-safe integer. + #[serde(deserialize_with = "deserialize_wall")] + pub wall: u64, + + /// Units per second for [`wall`](Self::wall). Defaults to 1,000,000 (microseconds), the + /// broadcast clock's own timescale. + #[serde( + default = "Clock::default_timescale", + deserialize_with = "deserialize_timescale_or_default" + )] + pub timescale: u32, +} + +pub(crate) fn deserialize_timescale_or_default<'de, D>(deserializer: D) -> std::result::Result +where + D: Deserializer<'de>, +{ + let value = Option::::deserialize(deserializer)?.unwrap_or_else(Clock::default_timescale); + if value == 0 { + return Err(serde::de::Error::custom("invalid timescale: 0")); + } + Ok(value) +} + +impl Clock { + /// The default timescale (1,000,000, i.e. microseconds) for a clock section that omits the + /// field. Matches the broadcast clock's own timescale. + pub fn default_timescale() -> u32 { + 1_000_000 + } + + /// A clock section with this `wall` at the default microsecond timescale. + /// + /// Errors on a wall outside the JSON-safe integer range, since a browser would read a + /// different number than the publisher wrote. + pub fn new(wall: u64) -> Result { + Self::with_timescale(wall, Self::default_timescale()) + } + + /// A clock section with this `wall` and `timescale`. + /// + /// Errors on a zero timescale or a wall outside the JSON-safe integer range, rather than + /// publishing a mapping no consumer can convert or read back exactly. + pub fn with_timescale(wall: u64, timescale: u32) -> Result { + if timescale == 0 { + return Err(crate::Error::InvalidTimescale(0)); + } + if wall > MAX_SAFE_INTEGER { + return Err(crate::Error::InvalidWall(wall)); + } + Ok(Self { wall, timescale }) + } + + /// The wall-clock time of `pts`, given in `pts_timescale` units per second. + /// + /// Converts `pts` into this clock's timescale explicitly, then applies the fixed mapping + /// `wall + pts`. Refuses a zero `pts_timescale`, an out-of-range result, or a timestamp the + /// timescales cannot represent, rather than truncating. + pub fn wall_clock(&self, pts: u64, pts_timescale: u32) -> Result { + if self.timescale == 0 { + return Err(crate::Error::InvalidTimescale(0)); + } + if pts_timescale == 0 { + return Err(crate::Error::InvalidTimescale(0)); + } + let scale = moq_net::Timescale::new(self.timescale as u64)?; + let pts = moq_net::Timestamp::new(pts, moq_net::Timescale::new(pts_timescale as u64)?)?; + let units = pts.as_scale(scale); + + let total = self.wall as u128 + units; + if total > MAX_SAFE_INTEGER as u128 { + return Err(crate::Error::InvalidWall(total as u64)); + } + + let unix_millis = MOQ_EPOCH_UNIX_MILLIS as u128 + total * 1000 / scale.as_u64() as u128; + let unix_millis = + u64::try_from(unix_millis).map_err(|_| crate::Error::TimestampOverflow(moq_net::TimeOverflow))?; + Ok(std::time::UNIX_EPOCH + std::time::Duration::from_millis(unix_millis)) + } +} + +#[cfg(test)] +mod test { + use super::*; + + #[test] + fn defaults_timescale_to_micros() { + let decoded: Clock = serde_json::from_str(r#"{"wall":1000}"#).unwrap(); + assert_eq!(decoded.timescale, 1_000_000); + assert_eq!( + serde_json::to_string(&decoded).unwrap(), + r#"{"wall":1000,"timescale":1000000}"# + ); + } + + #[test] + fn roundtrip() { + let clock = Clock { + wall: 175_184_640_000_000, + timescale: 1000, + }; + let json = serde_json::to_string(&clock).unwrap(); + assert_eq!(json, r#"{"wall":175184640000000,"timescale":1000}"#); + assert_eq!(serde_json::from_str::(&json).unwrap(), clock); + } + + #[test] + fn zero_timescale_is_refused() { + serde_json::from_str::(r#"{"wall":0,"timescale":0}"#).expect_err("a zero timescale must not decode"); + } + + #[test] + fn wall_beyond_json_safe_integers_is_refused() { + serde_json::from_str::(r#"{"wall":9007199254740992}"#).expect_err("a wall past 2^53-1 must not decode"); + assert!(Clock::new(MAX_SAFE_INTEGER + 1).is_err()); + } + + #[test] + fn wall_clock_converts_across_timescales() { + // PTS zero is the wall epoch itself. + let clock = Clock::new(1_000_000).unwrap(); + let epoch = std::time::UNIX_EPOCH + std::time::Duration::from_millis(MOQ_EPOCH_UNIX_MILLIS + 1_000); + assert_eq!(clock.wall_clock(0, 1000).unwrap(), epoch); + + // One media second later, whatever timescale names it. + let second = std::time::UNIX_EPOCH + std::time::Duration::from_millis(MOQ_EPOCH_UNIX_MILLIS + 2_000); + assert_eq!(clock.wall_clock(1000, 1000).unwrap(), second); + assert_eq!(clock.wall_clock(48_000, 48_000).unwrap(), second); + assert_eq!(clock.wall_clock(90_000, 90_000).unwrap(), second); + } + + #[test] + fn wall_clock_refuses_a_zero_pts_timescale() { + let clock = Clock::new(0).unwrap(); + assert!(clock.wall_clock(0, 0).is_err()); + } +} diff --git a/rs/hang/src/catalog/mod.rs b/rs/hang/src/catalog/mod.rs index 615ccb53886..5650ceb8b82 100644 --- a/rs/hang/src/catalog/mod.rs +++ b/rs/hang/src/catalog/mod.rs @@ -8,6 +8,7 @@ mod archive; mod audio; mod binary; +mod clock; mod compression; mod container; mod hex; @@ -24,6 +25,7 @@ mod video; pub use archive::*; pub use audio::*; pub use binary::*; +pub use clock::*; pub use compression::*; pub use container::*; pub use json::*; diff --git a/rs/hang/src/catalog/root.rs b/rs/hang/src/catalog/root.rs index cd524533ce5..5eff54a1b8c 100644 --- a/rs/hang/src/catalog/root.rs +++ b/rs/hang/src/catalog/root.rs @@ -6,7 +6,8 @@ use serde::{Deserialize, Serialize}; /// A catalog track, created by a broadcaster to describe the tracks available in a broadcast. /// /// The base catalog carries the media sections (`video`, `audio`, `text`), the optional -/// `archive` (the segment index and any durable recording), and the data sections +/// `archive` (the segment index and any durable recording), the optional `clock` (the +/// broadcast's one wall-clock mapping), and the data sections /// (`json`, `binary`) for application tracks that aren't media. /// Applications extend it with their own root sections (e.g. `scte35`) by flattening /// this struct into their own with `#[serde(flatten)]`. The catalog does not deny unknown fields, @@ -41,6 +42,16 @@ pub struct Catalog { /// See [`Archive`](crate::catalog::Archive) and the [`timeline`](crate::timeline) module. pub archive: Option, + /// The broadcast's one continuous clock, if the publisher exposes one. + /// + /// `wall` is the wall-clock time of PTS zero in `timescale` units since the moq epoch + /// (2020-01-01); every media track and the archive index refer to this mapping after + /// timescale conversion. Independent of [`archive`](Self::archive): a live-only publisher + /// exposes its clock without creating a segment index. See + /// [`Clock`](crate::catalog::Clock). + #[serde(default, skip_serializing_if = "Option::is_none")] + pub clock: Option, + /// Text (caption/subtitle) track information with multiple renditions. /// /// Contains a map of text track renditions that the viewer can choose from @@ -553,6 +564,46 @@ mod test { assert_eq!(output, r#"{"video":{"renditions":{}},"audio":{"renditions":{}}}"#); } + #[test] + fn clock_roundtrips_at_the_root() { + let clock = crate::catalog::Clock::new(1_751_846_400_000_000).unwrap(); + let catalog = Catalog { + clock: Some(clock), + ..Default::default() + }; + + let json = catalog.to_json().expect("failed to encode"); + assert!(json.contains(r#""clock":{"wall":1751846400000000"#), "{json}"); + assert_eq!(Catalog::from_str(&json).expect("failed to decode").clock, Some(clock)); + } + + #[test] + fn clock_stays_off_the_wire_when_absent() { + // A catalog without a clock serializes exactly as before the section existed. + let output = Catalog::default().to_json().expect("failed to encode"); + assert_eq!(output, r#"{"video":{"renditions":{}},"audio":{"renditions":{}}}"#); + } + + #[test] + fn packaged_clock_fixture_decodes() { + // The canonical new shape: the root clock plus an archive without a wall field. + // A reader maps archive timestamps through the root clock after timescale conversion. + let json = include_str!("../../fixtures/catalog-clock.json"); + let catalog = Catalog::from_str(json).expect("the packaged fixture must decode"); + + let clock = catalog.clock.expect("the fixture carries a root clock"); + assert_eq!(clock.timescale, 1_000_000); + + let archive = catalog.archive.expect("the fixture carries an archive"); + assert_eq!(archive.track, "timeline.z"); + assert_eq!(archive.timescale, 1000); + + // Archive PTS 2000 (ms) lands 2s after the wall epoch, whatever the track timescale. + let expected = std::time::UNIX_EPOCH + + std::time::Duration::from_millis(crate::catalog::MOQ_EPOCH_UNIX_MILLIS + 1_751_846_402_000); + assert_eq!(clock.wall_clock(2000, archive.timescale).unwrap(), expected); + } + #[test] fn archive_roundtrips_at_the_root() { let mut archive = crate::catalog::Archive::new("timeline.z"); diff --git a/rs/hang/src/catalog/timeline.rs b/rs/hang/src/catalog/timeline.rs index c048761ad50..3eb8f8f7a06 100644 --- a/rs/hang/src/catalog/timeline.rs +++ b/rs/hang/src/catalog/timeline.rs @@ -2,7 +2,7 @@ use serde::{Deserialize, Serialize}; /// The moq epoch (2020-01-01T00:00:00Z) in Unix-epoch milliseconds. /// -/// Timeline [`wall`](Timeline::wall) values are measured from here rather than the Unix epoch so +/// Timeline [`wall`](crate::catalog::Clock::wall) values are measured from here rather than the Unix epoch so /// the numbers stay small (and safely within a 53-bit integer even at fine timescales); a /// consumer recovers Unix time by adding this back. pub const MOQ_EPOCH_UNIX_MILLIS: u64 = 1_577_836_800_000; @@ -17,7 +17,9 @@ pub const MOQ_EPOCH_UNIX_MILLIS: u64 = 1_577_836_800_000; /// The section lives inside the catalog's root [`Archive`](crate::catalog::Archive) (flattened /// on the wire): 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. +/// simply omits the archive entry. Wall-clock mapping is the catalog root +/// [`Clock`](crate::catalog::Clock)'s job, not this section's: every track and this index +/// refer to that one mapping after timescale conversion. #[serde_with::skip_serializing_none] #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] #[serde(rename_all = "camelCase")] @@ -27,9 +29,12 @@ pub struct Timeline { /// ([`timeline::DEFAULT_NAME`](crate::timeline::DEFAULT_NAME) by convention). pub track: String, - /// Units per second for the timeline's `pts` and [`wall`](Self::wall). Defaults to 1000 - /// (milliseconds). - #[serde(default = "Timeline::default_timescale")] + /// Units per second for the timeline's `pts`. Defaults to 1000 + /// (milliseconds). Zero is refused: no timestamp can be expressed in it. + #[serde( + default = "Timeline::default_timescale", + deserialize_with = "super::deserialize_timescale_or_default" + )] pub timescale: u32, /// The declared upper bound on a segment's duration, in [`timescale`](Self::timescale) @@ -44,15 +49,6 @@ pub struct Timeline { /// GOP can be minutes long) and for a publisher importing a source it doesn't control. A /// consumer needing a bound then derives one from the records it has seen. pub duration_max: Option, - - /// The wall-clock time of `pts` 0, in [`timescale`](Self::timescale) units since the moq - /// epoch ([`MOQ_EPOCH_UNIX_MILLIS`], 2020-01-01), if known. A consumer derives the wall-clock - /// time of any group as `wall + pts`, and Unix time by adding the moq epoch back (an absolute - /// clock 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. - pub wall: Option, } impl Timeline { @@ -63,15 +59,13 @@ impl Timeline { } /// A timeline section naming `track`, at the default millisecond timescale, with no - /// declared duration bound and no wall-clock anchor. Set - /// [`timescale`](Self::timescale) / [`duration_max`](Self::duration_max) / - /// [`wall`](Self::wall) afterward. + /// declared duration bound. Set [`timescale`](Self::timescale) / + /// [`duration_max`](Self::duration_max) afterward. pub fn new(track: impl Into) -> Self { Self { track: track.into(), timescale: Self::default_timescale(), duration_max: None, - wall: None, } } } @@ -87,7 +81,6 @@ mod test { assert_eq!(decoded.track, "timeline.z"); assert_eq!(decoded.timescale, 1000); assert_eq!(decoded.duration_max, Some(2000)); - assert_eq!(decoded.wall, None); } #[test] @@ -102,15 +95,17 @@ mod test { } #[test] - fn roundtrip_with_wall() { + fn zero_timescale_is_refused() { + serde_json::from_str::(r#"{"track":"timeline.z","timescale":0}"#) + .expect_err("a zero timescale must not decode"); + } + + #[test] + fn roundtrip() { let mut timeline = Timeline::new("timeline.z"); timeline.duration_max = Some(2000); - timeline.wall = Some(1_751_846_400_000); let json = serde_json::to_string(&timeline).unwrap(); - assert_eq!( - json, - r#"{"track":"timeline.z","timescale":1000,"durationMax":2000,"wall":1751846400000}"# - ); + assert_eq!(json, r#"{"track":"timeline.z","timescale":1000,"durationMax":2000}"#); assert_eq!(serde_json::from_str::(&json).unwrap(), timeline); } } diff --git a/rs/hang/src/error.rs b/rs/hang/src/error.rs index bd6527309ce..dfdfd033ea2 100644 --- a/rs/hang/src/error.rs +++ b/rs/hang/src/error.rs @@ -53,6 +53,14 @@ pub enum Error { #[error("duplicate track: {0}")] Duplicate(String), + /// A catalog timescale is zero, so no timestamp can be expressed in it. + #[error("invalid timescale: {0}")] + InvalidTimescale(u32), + + /// A catalog wall-clock value is outside the JSON-safe integer range. + #[error("invalid wall clock: {0}")] + InvalidWall(u64), + /// The shared video rotation is not a finite number. #[error("video rotation must be finite")] InvalidVideoRotation, diff --git a/rs/moq-hls/src/export/mod.rs b/rs/moq-hls/src/export/mod.rs index 290c8691d48..3d4dc3756fa 100644 --- a/rs/moq-hls/src/export/mod.rs +++ b/rs/moq-hls/src/export/mod.rs @@ -187,7 +187,7 @@ impl Broadcaster { let mut audio = Vec::new(); let mut availability_start = None; for rendition in self.renditions.snapshot() { - // Every rendition shares the catalog's one timeline section, so any of them can + // Every rendition shares the catalog's one root clock, so any of them can // supply the declared wall anchor. if availability_start.is_none() { availability_start = rendition.wall_clock(moq_net::Timestamp::ZERO); @@ -809,7 +809,7 @@ mod tests { assert!(manifest.contains(" type=\"dynamic\""), "live broadcast is dynamic"); assert!( manifest.contains(" availabilityStartTime=\""), - "pts 0 is anchored even without a catalog wall clock" + "pts 0 is anchored by the catalog root clock" ); assert!(manifest.contains("id=\"video/video0\"")); assert!(manifest.contains("id=\"audio/audio0\"")); @@ -837,6 +837,116 @@ mod tests { drop((video, audio, video_registration, audio_registration, broadcast)); } + // The clock migration end to end: the catalog root clock (not the archive section) times + // EXT-X-PROGRAM-DATE-TIME and the DASH availabilityStartTime, converting the timeline + // timescale into the clock's. + #[tokio::test] + async fn root_clock_times_playlists_and_manifest() { + use std::time::{SystemTime, UNIX_EPOCH}; + + let origin = produce_origin(); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + broadcast.announce(Default::default()).expect("publish allowed"); + settle().await; + + // PTS zero at exactly the moq epoch, so every timestamp maps to a fixed string. + let wall = UNIX_EPOCH + Duration::from_millis(hang::catalog::MOQ_EPOCH_UNIX_MILLIS); + let config = moq_mux::catalog::Config::default() + .with_clock(moq_mux::Clock::with_wall(wall).expect("a representable wall")); + let mut catalog = moq_mux::catalog::Producer::with_config(&mut broadcast, config).unwrap(); + + let reserved = catalog.reserve(); + let mut registration = reserved.video("video0").unwrap(); + registration.set(video_config()).unwrap(); + drop(reserved); + + let track = broadcast.create_track("video0", None).unwrap(); + let mut media = catalog + .media_producer( + track, + moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Data), + ) + .unwrap(); + media.write(frame(0, true)).unwrap(); + media.write(frame(2_000_000, true)).unwrap(); + media.write(frame(4_000_000, true)).unwrap(); // live edge + + let source = moq_mux::Source::new(origin.consume(), "live"); + let broadcaster = Broadcaster::new(source, Config::default()).await.unwrap(); + let _ = tokio::time::timeout(Duration::from_secs(5), broadcaster.ready()).await; + let rendition = broadcaster.rendition(Kind::Video, "video0").expect("video discovered"); + let _ = tokio::time::timeout(Duration::from_secs(5), rendition.playable()).await; + + // The timeline section carries no wall field anymore; the root clock names the epoch. + let snapshot = rendition.playlist(); + assert_eq!( + snapshot.program_date_time, + Some(SystemTime::UNIX_EPOCH + Duration::from_millis(hang::catalog::MOQ_EPOCH_UNIX_MILLIS)) + ); + let playlist = rendition.media_playlist(None).expect("playlist renders"); + assert!( + playlist.contains("#EXT-X-PROGRAM-DATE-TIME:2020-01-01T00:00:00.000Z\n"), + "pts 0 maps through the root clock: {playlist}" + ); + + let manifest = broadcaster.manifest(None).expect("manifest renders once playable"); + assert!( + manifest.contains(" availabilityStartTime=\"2020-01-01T00:00:00.000Z\""), + "the manifest anchors at the root clock: {manifest}" + ); + + drop((media, registration, broadcast)); + } + + // Without a catalog clock the DASH manifest still anchors, estimating pts 0 from the first + // record's arrival, and playlists simply omit EXT-X-PROGRAM-DATE-TIME. + #[tokio::test] + async fn manifest_falls_back_to_arrival_anchor_without_a_clock() { + let origin = produce_origin(); + let mut broadcast = origin.create_broadcast("live").expect("publish allowed"); + broadcast.announce(Default::default()).expect("publish allowed"); + settle().await; + let mut catalog = moq_mux::catalog::Producer::new(&mut broadcast).unwrap(); + + let reserved = catalog.reserve(); + // Stage the clock's removal before the first snapshot publishes, so no consumer ever + // sees a clock on this broadcast. + catalog.modify().unwrap().clock = None; + let mut registration = reserved.video("video0").unwrap(); + registration.set(video_config()).unwrap(); + drop(reserved); + assert_eq!(catalog.snapshot().clock, None); + + let track = broadcast.create_track("video0", None).unwrap(); + let mut media = catalog + .media_producer( + track, + moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Data), + ) + .unwrap(); + media.write(frame(0, true)).unwrap(); + media.write(frame(2_000_000, true)).unwrap(); + media.write(frame(4_000_000, true)).unwrap(); // live edge + + let source = moq_mux::Source::new(origin.consume(), "live"); + let broadcaster = Broadcaster::new(source, Config::default()).await.unwrap(); + let _ = tokio::time::timeout(Duration::from_secs(5), broadcaster.ready()).await; + let rendition = broadcaster.rendition(Kind::Video, "video0").expect("video discovered"); + let _ = tokio::time::timeout(Duration::from_secs(5), rendition.playable()).await; + + assert_eq!(rendition.playlist().program_date_time, None); + let playlist = rendition.media_playlist(None).expect("playlist renders"); + assert!(!playlist.contains("PROGRAM-DATE-TIME"), "{playlist}"); + + let manifest = broadcaster.manifest(None).expect("manifest renders once playable"); + assert!( + manifest.contains(" availabilityStartTime=\""), + "pts 0 is anchored even without a catalog clock" + ); + + drop((media, registration, broadcast)); + } + // A finished broadcast renders a static presentation, offset to its first listed segment. #[tokio::test] async fn dash_manifest_turns_static_when_finished() { diff --git a/rs/moq-hls/src/export/playlist.rs b/rs/moq-hls/src/export/playlist.rs index 4044daeaea6..362cfafc433 100644 --- a/rs/moq-hls/src/export/playlist.rs +++ b/rs/moq-hls/src/export/playlist.rs @@ -27,7 +27,7 @@ pub(crate) struct Snapshot { /// Whether the broadcast ended (`EXT-X-ENDLIST`). pub finished: bool, /// Wall-clock time of the first listed segment (`EXT-X-PROGRAM-DATE-TIME`), when the - /// timeline advertises a wall-clock anchor. + /// catalog advertises its root broadcast clock. pub program_date_time: Option, } diff --git a/rs/moq-hls/src/export/rendition.rs b/rs/moq-hls/src/export/rendition.rs index e850cc2f802..64b9f7b9f48 100644 --- a/rs/moq-hls/src/export/rendition.rs +++ b/rs/moq-hls/src/export/rendition.rs @@ -6,7 +6,7 @@ use std::task::Poll; use std::time::{Duration, SystemTime}; use bytes::Bytes; -use hang::catalog::{AudioConfig, MOQ_EPOCH_UNIX_MILLIS, Timeline, VideoConfig}; +use hang::catalog::{AudioConfig, Clock, Timeline, VideoConfig}; use moq_mux::container::fmp4::Muxer; use moq_mux::timeline::Entry; @@ -199,8 +199,11 @@ pub struct Rendition { pub codec: String, config: Config, - /// The catalog's root archive timeline: the timescale and wall anchor timings decode with. + /// The catalog's root archive timeline: the timescale timings decode with. section: Timeline, + /// The catalog's root broadcast clock: the wall anchor timings map through, after + /// timescale conversion. Absent when the publisher exposes none. + clock: Option, /// This rendition's window over the broadcast timeline, fed by the catalog watcher's /// fan-out. live: Arc, @@ -252,7 +255,8 @@ impl Rendition { *self.bitrate.read().expect("bitrate lock poisoned") } - /// Build a video rendition over the broadcast's timeline `section`. + /// Build a video rendition over the broadcast's timeline `section`, timed by the + /// catalog root `clock`. /// /// Fails when the config's `broadcast` reference escapes above the origin root: it names no /// broadcast, so there would be no media to serve. @@ -261,6 +265,7 @@ impl Rendition { config: &VideoConfig, upstream: &Upstream, section: Timeline, + clock: Option, ) -> moq_mux::Result { Ok(Self { name, @@ -271,19 +276,21 @@ impl Rendition { codec: config.codec.to_string(), config: Config::Video(config.clone()), section, + clock, live: Arc::new(segments::Producer::new()), media: Media::bind(upstream, config.broadcast.as_ref())?, init: tokio::sync::Mutex::new(None), }) } - /// Build an audio rendition over the broadcast's timeline `section`, failing like - /// [`video`](Self::video). + /// Build an audio rendition over the broadcast's timeline `section`, timed by the catalog + /// root `clock`, failing like [`video`](Self::video). pub(crate) fn audio( name: String, config: &AudioConfig, upstream: &Upstream, section: Timeline, + clock: Option, ) -> moq_mux::Result { Ok(Self { name, @@ -294,6 +301,7 @@ impl Rendition { codec: config.codec.to_string(), config: Config::Audio(config.clone()), section, + clock, live: Arc::new(segments::Producer::new()), media: Media::bind(upstream, config.broadcast.as_ref())?, init: tokio::sync::Mutex::new(None), @@ -495,13 +503,13 @@ impl Rendition { moq_net::Timescale::new((self.section.timescale as u64).max(1)).expect("clamped nonzero timescale") } - /// The wall-clock time of a media timestamp, when the timeline advertises an anchor. + /// The wall-clock time of a media timestamp, when the catalog advertises its broadcast + /// clock. Converts the timeline-timescale timestamp into the clock's timescale and applies + /// the root mapping; an unrepresentable result maps to no time rather than a truncated one. pub(crate) fn wall_clock(&self, pts: moq_net::Timestamp) -> Option { - let wall = self.section.wall?; - let timescale = moq_net::Timescale::new(u64::from(self.section.timescale)).ok()?; - let units = u128::from(wall) + pts.as_scale(timescale); - let unix_ms = u128::from(MOQ_EPOCH_UNIX_MILLIS) + units * 1000 / u128::from(timescale.as_u64()); - Some(SystemTime::UNIX_EPOCH + Duration::from_millis(u64::try_from(unix_ms).ok()?)) + let clock = self.clock.as_ref()?; + let scale = u32::try_from(pts.scale().as_u64()).ok()?; + clock.wall_clock(pts.value(), scale).ok() } fn muxer(&self) -> Result { diff --git a/rs/moq-hls/src/export/renditions.rs b/rs/moq-hls/src/export/renditions.rs index bfd08d44ad2..cbb66a68ac1 100644 --- a/rs/moq-hls/src/export/renditions.rs +++ b/rs/moq-hls/src/export/renditions.rs @@ -55,7 +55,7 @@ struct Feed { closed: bool, /// The estimated wall-clock time of timeline `pts` 0, anchored when the first record /// arrived (assuming its segment had just ended). The DASH manifest's - /// `availabilityStartTime` falls back to this when the catalog declares no `wall`; set + /// `availabilityStartTime` falls back to this when the catalog declares no `clock`; set /// once so reloads see a stable presentation, and reset with the window when the /// timeline restarts. anchor: Option, @@ -325,6 +325,7 @@ impl Producer { return; }; let section = archive.timeline; + let clock = catalog.clock; let Ok(mut current) = self.state.write() else { return; @@ -363,7 +364,7 @@ impl Producer { rendition.refresh(video.bitrate); continue; } - let rendition = match Rendition::video(name.clone(), video, upstream, section.clone()) { + let rendition = match Rendition::video(name.clone(), video, upstream, section.clone(), clock) { Ok(rendition) => Arc::new(rendition), Err(err) => { tracing::warn!(rendition = name, %err, "ignoring unservable video rendition"); @@ -379,7 +380,7 @@ impl Producer { rendition.refresh(audio.bitrate); continue; } - let rendition = match Rendition::audio(name.clone(), audio, upstream, section.clone()) { + let rendition = match Rendition::audio(name.clone(), audio, upstream, section.clone(), clock) { Ok(rendition) => Arc::new(rendition), Err(err) => { tracing::warn!(rendition = name, %err, "ignoring unservable audio rendition"); diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index 1581468f8d6..291684bbc9c 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -15,6 +15,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 unchanged and leaves the tracks open on failure. - [**breaking**] Advertise the broadcast timeline through `catalog.archive` (`hang::catalog::Archive`). `timeline::Producer::section` returns `Archive`. +- [**breaking**] Replace `timeline::Config::wall` with the broadcast `Clock`'s fixed wall + mapping, advertised at the catalog root as `clock: { wall, timescale }` independently of + any archive. `catalog::Config::with_clock` names the content's real start for an import; + `catalog::Producer::clock` shares the epoch. Zero timescales and walls past the JSON-safe + integer range are refused. - `import::ContainerStream::new` takes a bare `ContainerFormat` instead of a `ContainerInit`. It only ever read the format, so the init's leading bytes were accepted and dropped. A stream recovers its own framing, so push everything through `decode` instead. @@ -36,6 +41,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Propagate rendition labels through single-track media imports. +- `Clock::with_wall` / `Clock::new_at` for imports and synthetic sources, `Clock::source` + translating a source's own zero onto the broadcast mapping (first frame anchors live, a + reset re-anchors forward preserving the idle gap, in-group B-frame reordering survives), + and `Error::UnmappableTimestamp` refusing a mapping that would move backwards past the + broadcast's start or out of range. - `From for catalog::VideoHint`, a total conversion for a caller that already has a whole rendition. Replaces the per-field copy in `moq-video`, which dropped the label. diff --git a/rs/moq-mux/src/catalog/hang/ext.rs b/rs/moq-mux/src/catalog/hang/ext.rs index f100346c008..79d927b87cb 100644 --- a/rs/moq-mux/src/catalog/hang/ext.rs +++ b/rs/moq-mux/src/catalog/hang/ext.rs @@ -42,8 +42,8 @@ impl CatalogExt for () {} /// cross. Publish/consume a [`Catalog`] and use [`set`](Self::set)/[`get`](Self::get). /// The default extension stays `()` (unknown sections dropped); opt into `Extra` explicitly. /// -/// `video`, `audio`, `text`, `archive`, `json`, `binary`, and the retired `timeline` key are -/// reserved, so [`set`](Self::set) rejects them to keep the wire JSON free of duplicate keys. +/// `video`, `audio`, `text`, `archive`, `clock`, `json`, `binary`, and the retired `timeline` +/// key are reserved, so [`set`](Self::set) rejects them to keep the wire JSON free of duplicate keys. #[derive(Serialize, Deserialize, Clone, Default, Debug, PartialEq)] #[serde(transparent)] pub struct Extra(serde_json::Map); @@ -72,8 +72,8 @@ impl Extra { } /// Set (or replace) a section. Errors if `name` collides with a reserved member of either - /// catalog: hang's base sections (`video`/`audio`/`text`/`archive`/`json`/`binary`), the - /// retired `timeline` key that the wire format forbids beside `archive`, or a root member + /// catalog: hang's base sections (`video`/`audio`/`text`/`archive`/`clock`/`json`/`binary`), + /// the retired `timeline` key that the wire format forbids beside `archive`, or a root member /// MSF defines ([`moq_msf::reserved_root`]). /// /// The same sections ride both catalog tracks, so a name reserved on either is refused on @@ -83,7 +83,7 @@ impl Extra { let name = name.into(); if matches!( name.as_str(), - "video" | "audio" | "text" | "archive" | "json" | "binary" | "timeline" + "video" | "audio" | "text" | "archive" | "clock" | "json" | "binary" | "timeline" ) || moq_msf::reserved_root(&name) { return Err(crate::Error::ReservedSection(name)); @@ -99,8 +99,8 @@ impl Extra { } /// The base sections plus an application extension `E` (defaulting to `()` for none), serialized -/// as a flat union: the `video`/`audio`/`text` media sections, the shared `archive`, the -/// `json`/`binary` data sections, and the extension's sections share one JSON object on the wire. +/// as a flat union: the `video`/`audio`/`text` media sections, the shared `archive` and `clock`, +/// the `json`/`binary` data sections, and the extension's sections share one JSON object on the wire. /// /// The data sections (`json`/`binary`) carry application tracks that aren't media. Every base /// section is a direct field (`catalog.video`), and the catalog derefs to the extension so its @@ -124,6 +124,13 @@ pub struct Catalog { #[serde(default, skip_serializing_if = "Option::is_none")] pub archive: Option, + /// The broadcast's one continuous clock, if the publisher exposes one. + /// + /// Independent of [`archive`](Self::archive): a live-only publisher exposes its mapping + /// without creating a segment index. See [`hang::catalog::Clock`]. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub clock: Option, + /// Caption/subtitle renditions. Omitted from the wire when empty, so a broadcast without /// captions stays byte-identical to before this section existed. /// @@ -333,6 +340,10 @@ mod test { .set_section("timeline", serde_json::json!({})), Err(crate::Error::ReservedSection(_)) )); + assert!(matches!( + producer.modify().unwrap().set_section("clock", serde_json::json!({})), + Err(crate::Error::ReservedSection(_)) + )); // Nor can a member MSF defines: the same sections ride the MSF track, where a // collision would serialize as a duplicate JSON key rather than an error. diff --git a/rs/moq-mux/src/catalog/producer.rs b/rs/moq-mux/src/catalog/producer.rs index e1013bac744..e410e724df8 100644 --- a/rs/moq-mux/src/catalog/producer.rs +++ b/rs/moq-mux/src/catalog/producer.rs @@ -163,8 +163,11 @@ pub struct Producer { current: Arc>>, /// Shared wall clock for the broadcast's tracks. Every importer on this catalog - /// gets a clone (a `Copy` of the same epoch), so timestamps they synthesize when + /// gets a copy (the same epoch), so timestamps they synthesize when /// a caller has none land on one timeline and audio/video stay in sync. + /// + /// It also owns the broadcast's wall mapping, published at the catalog root as + /// `clock: { wall, timescale }` independently of any archive timeline. clock: crate::Clock, /// The broadcast's timeline: the shared boundary list every enrolled track's groups map @@ -207,6 +210,7 @@ pub struct Config { catalog: Catalog, max_age: Option, bandwidth: moq_net::bandwidth::Allocator, + clock: crate::Clock, } impl Default for Config<()> { @@ -215,6 +219,7 @@ impl Default for Config<()> { catalog: Catalog::default(), max_age: None, bandwidth: moq_net::bandwidth::Allocator::unlimited(), + clock: crate::Clock::new(), } } } @@ -228,9 +233,20 @@ impl Config { catalog, max_age: self.max_age, bandwidth: self.bandwidth, + clock: self.clock, } } + /// Publish with this broadcast clock instead of a fresh one. + /// + /// The clock's wall mapping is advertised at the catalog root, so pass a clock whose PTS + /// zero names the content's real start when importing a recording; live publishers use the + /// default. The mapping is fixed for the broadcast and never overwritten. + pub fn with_clock(mut self, clock: crate::Clock) -> Self { + self.clock = clock; + self + } + /// Override how long the media tracks minted under this catalog keep a non-latest group /// fetchable, replacing hang's default. `None` keeps it. /// @@ -310,6 +326,12 @@ impl Producer { last_sequence: None, })); + // The broadcast clock is advertised at the catalog root from the first snapshot, + // independently of any archive timeline: a live-only publisher exposes its mapping + // without creating a segment index. + let mut catalog = config.catalog; + catalog.clock = Some(config.clock.section()); + // The contents are `Send + Sync` natively; on wasm moq-net's handles are // `Rc`-backed, so clippy sees a pointlessly atomic `Arc`. Keeping one type for // both targets is worth the unused atomics on the single-threaded one. @@ -323,12 +345,12 @@ impl Producer { catalog_timeline, }, current: Arc::new(Mutex::new(State { - catalog: config.catalog, + catalog, owned: BTreeSet::new(), reservations: Reservations::default(), closed: None, })), - clock: crate::Clock::new(), + clock: config.clock, timeline, max_age: config.max_age, bandwidth: config.bandwidth, @@ -390,6 +412,16 @@ impl Producer { take(&self.current).catalog.clone() } + /// The broadcast's shared clock: the epoch importers stamp against and the wall mapping + /// advertised at the catalog root. + /// + /// Copies share the epoch, so handing them to concurrent producers keeps every track on + /// one timeline. Translate a source with its own zero through + /// [`Clock::source`](crate::Clock::source). + pub fn clock(&self) -> crate::Clock { + self.clock + } + /// Pace the broadcast's timeline with `config` instead of the default. /// /// Call it before any track enrolls (the timeline's own track doesn't exist until then, so @@ -1077,7 +1109,6 @@ mod test { // A broadcast that never segments never advertises an archive. assert_eq!(catalog.snapshot().archive, None); - let _recorder = catalog.enroll("video0").unwrap(); assert_eq!( catalog.snapshot().archive, @@ -1086,6 +1117,30 @@ mod test { ); } + #[test] + fn clock_is_advertised_without_an_archive() { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = Producer::new(&mut broadcast).unwrap(); + + // A live-only broadcast exposes its clock without creating a segment index. + let snapshot = catalog.snapshot(); + assert_eq!(snapshot.archive, None); + assert_eq!(snapshot.clock, Some(catalog.clock().section())); + } + + #[test] + fn with_clock_names_the_contents_real_start() { + use std::time::{Duration, SystemTime}; + + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let wall = SystemTime::UNIX_EPOCH + Duration::from_millis(hang::catalog::MOQ_EPOCH_UNIX_MILLIS + 60_000); + let config = Config::default().with_clock(crate::Clock::with_wall(wall).expect("a representable wall")); + let catalog = Producer::with_config(&mut broadcast, config).unwrap(); + + // A recording import advertises the content's start, not the construction instant. + assert_eq!(catalog.snapshot().clock.map(|clock| clock.wall), Some(60_000_000)); + } + fn h264_config() -> VideoConfig { let mut config = VideoConfig::new(H264 { profile: 0x64, diff --git a/rs/moq-mux/src/clock.rs b/rs/moq-mux/src/clock.rs index 51a8c6e531b..bf349b441dd 100644 --- a/rs/moq-mux/src/clock.rs +++ b/rs/moq-mux/src/clock.rs @@ -1,24 +1,88 @@ -//! A shared clock for aligning concurrently-produced tracks. +//! The broadcast's shared clock: one monotonic epoch plus its fixed wall mapping. +//! +//! Create one [`Clock`] per broadcast and hand copies to every producer: because they share an +//! epoch, frames captured at the same instant get the same timestamp, keeping concurrently +//! produced tracks (e.g. audio and video capture on separate threads) in sync. It is `Copy`, so +//! handing it out is cheap. +//! +//! The clock also owns the broadcast's wall mapping, advertised at the catalog root as +//! `clock: { wall, timescale }`: `wall` is the wall-clock time of PTS zero in +//! [`Clock::TIMESCALE`] units since the moq epoch (2020-01-01). A consumer derives any +//! timestamp's wall time as `wall + pts` after converting it into this timescale. The mapping +//! is fixed at construction and never overwritten: a discontinuity marker is a delivery event, +//! not a new epoch, and a system-clock adjustment never retimes it. +//! +//! A source with its own zero (a file, a restarted encoder) is translated onto the mapping with +//! [`SourceMap`]: the first frame anchors onto the live edge, and a reset re-anchors forward, +//! preserving the real idle gap measured on this monotonic clock. -use std::time::Instant; +use std::time::{Duration, Instant, SystemTime}; + +use hang::catalog::{MAX_SAFE_INTEGER, MOQ_EPOCH_UNIX_MILLIS}; + +/// The wall-clock time of PTS zero, in [`Clock::TIMESCALE`] units since the moq epoch. +fn wall_units(wall: SystemTime) -> crate::Result { + let unix_micros = wall + .duration_since(SystemTime::UNIX_EPOCH) + .map(|d| d.as_micros()) + .unwrap_or(0); + // A clock before 2020 (an unsynced peer) saturates at the epoch: the wire cannot name it. + let moq_micros = unix_micros.saturating_sub(MOQ_EPOCH_UNIX_MILLIS as u128 * 1000); + let wall = u64::try_from(moq_micros).unwrap_or(u64::MAX); + if wall > MAX_SAFE_INTEGER { + return Err(hang::Error::InvalidWall(wall).into()); + } + Ok(wall) +} /// A monotonic clock for stamping media frames so that tracks produced /// concurrently, e.g. an audio and a video capture running on separate /// threads, land on a single timeline. /// -/// Create one [`Clock`] and sample it ([`micros`](Self::micros)) from each -/// producer: because they share an epoch, frames captured at the same instant -/// get the same timestamp, keeping the tracks in sync. It is `Copy`, so it's -/// cheap to hand to several producers. +/// Copies share the epoch and the fixed wall mapping, so handing them to several producers keeps +/// the broadcast on one clock. The wall mapping is established at construction: sampling it when +/// a delayed first frame arrives would pretend that frame is timestamp zero, so the epoch is +/// pinned up front and that frame's PTS converts into the mapping instead. #[derive(Clone, Copy, Debug)] pub struct Clock { epoch: Instant, + wall: u64, } impl Clock { - /// Start a clock anchored at the current instant. + /// Units per second for the broadcast clock: microseconds. + /// + /// Matches the hang container timescale, so media timestamps convert without loss, and fine + /// enough that the wall value stays within the JSON-safe integer range until the year 2255. + pub const TIMESCALE: moq_net::Timescale = moq_net::Timescale::MICRO; + + /// Start a clock anchored at the current instant, with PTS zero at the current wall time. pub fn new() -> Self { - Self { epoch: Instant::now() } + Self::new_at(Instant::now(), SystemTime::now()) + .expect("the current wall time is representable as a broadcast clock") + } + + /// Start a clock anchored at the current instant, with PTS zero at `wall`. + /// + /// For an import whose content carries its own start (a recording): the media keeps its + /// relative spacing and that start names the wall epoch. Refuses a wall outside the + /// JSON-safe integer range rather than publishing a number browsers misread. + pub fn with_wall(wall: SystemTime) -> crate::Result { + Ok(Self { + epoch: Instant::now(), + wall: wall_units(wall)?, + }) + } + + /// Start a clock at an explicit monotonic epoch and wall time. + /// + /// The deterministic constructor: synthetic sources and fixtures pin both ends instead of + /// sampling. Refuses an unrepresentable wall like [`with_wall`](Self::with_wall). + pub fn new_at(epoch: Instant, wall: SystemTime) -> crate::Result { + Ok(Self { + epoch, + wall: wall_units(wall)?, + }) } /// Microseconds elapsed since the clock's epoch. @@ -26,6 +90,41 @@ impl Clock { // u128 -> u64 truncation is unreachable: u64 microseconds is ~584,000 years. self.epoch.elapsed().as_micros() as u64 } + + /// Units per second for [`wall`](Self::wall): [`TIMESCALE`](Self::TIMESCALE). + pub fn timescale(&self) -> moq_net::Timescale { + Self::TIMESCALE + } + + /// The wall-clock time of PTS zero, in [`TIMESCALE`](Self::TIMESCALE) units since the moq epoch. + pub fn wall(&self) -> u64 { + self.wall + } + + /// The catalog root section advertising this clock: `clock: { wall, timescale }`. + pub fn section(&self) -> hang::catalog::Clock { + hang::catalog::Clock::with_timescale(self.wall, Self::TIMESCALE.as_u64() as u32) + .expect("a constructed clock is always representable") + } + + /// The wall-clock time of `pts` under this broadcast's fixed mapping. + /// + /// Pure in the stored epoch: a system-clock adjustment after construction changes nothing. + /// Refuses an unrepresentable result rather than truncating it. + pub fn wall_clock(&self, pts: moq_net::Timestamp) -> crate::Result { + let scale = u32::try_from(pts.scale().as_u64()) + .map_err(|_| crate::Error::UnmappableTimestamp(format!("timescale {} exceeds u32", pts.scale())))?; + self.section() + .wall_clock(pts.value(), scale) + .map_err(crate::Error::from) + } + + /// Translate a source with its own zero onto this broadcast's mapping. + /// + /// Each adapter owns one per source; see [`SourceMap`]. The mapping itself is untouched. + pub fn source(&self) -> SourceMap { + SourceMap::new(*self) + } } impl Default for Clock { @@ -33,3 +132,333 @@ impl Default for Clock { Self::new() } } + +/// Translates one source's timestamps onto the broadcast clock. +/// +/// A source numbers from its own zero (a file starts at its first PTS, an encoder restarts at +/// zero), while the broadcast numbers from the shared epoch. The first frame anchors onto the +/// live edge, preserving the source's spacing from there on; a reset re-anchors forward, +/// preserving the real idle gap measured on the broadcast's monotonic clock. Backwards steps +/// within [`MAX_REORDER`](Self::MAX_REORDER) keep their offset, so permitted B-frame reordering +/// inside a group survives verbatim. +/// +/// The broadcast wall mapping is never touched: translating a reset is not a new epoch, and a +/// discontinuity marker the adapter emits alongside is a delivery event the playhead reacts to, +/// not a clock the catalog republishes. Retained records keep their timestamps. +/// +/// Each publisher adapter owns one per source and wires its own restart detection to +/// [`reset`](Self::reset); the automatic path only separates reordering from resets by size. +pub struct SourceMap { + clock: Clock, + /// Broadcast micros minus source micros; `None` until the first frame anchors it. + offset: Option, + last_source: Option, + last_broadcast: Option, + /// `clock.micros()` when the last frame was translated: the idle gap's start. + last_arrival: Option, +} + +impl SourceMap { + /// The largest backwards source step still treated as permitted in-group reordering + /// (B-frames present out of decode order) rather than a source reset. + /// + /// A larger backwards step re-anchors the source forward instead. Adapters that detect a + /// restart out of band re-anchor explicitly with [`reset`](Self::reset); this bound only + /// separates the two for the automatic path. + pub const MAX_REORDER: Duration = Duration::from_millis(500); + + /// A translator onto `clock`, unanchored until the first frame. + pub fn new(clock: Clock) -> Self { + Self { + clock, + offset: None, + last_source: None, + last_broadcast: None, + last_arrival: None, + } + } + + /// The broadcast clock this source translates onto. + pub fn clock(&self) -> Clock { + self.clock + } + + /// Translate `pts` onto the broadcast clock, sampling the arrival time. + pub fn translate(&mut self, pts: moq_net::Timestamp) -> crate::Result { + self.translate_at(pts, self.clock.micros()) + } + + /// Translate `pts` onto the broadcast clock, arriving at monotonic `now` micros. + /// + /// The deterministic core behind [`translate`](Self::translate): synthetic sources pin the + /// arrival instants instead of sampling them. + pub fn translate_at(&mut self, pts: moq_net::Timestamp, now: u64) -> crate::Result { + let src = pts.as_micros(); + + let broadcast = match self.offset { + Some(offset) => { + let mapped = src as i128 + offset; + if mapped < 0 { + return Err(crate::Error::UnmappableTimestamp(format!( + "{pts:?} lands before the broadcast began" + ))); + } + let mapped = mapped as u64; + match self.last_broadcast { + Some(last) if mapped < last && last - mapped > Self::MAX_REORDER.as_micros() as u64 => { + // A source reset: re-anchor forward, counting the downtime as content. + self.reanchor(src, now)? + } + // Forward, steady, or reordered within a group: the offset stands. + _ => mapped, + } + } + // The first frame is live now; the source keeps its spacing from there. Rebasing by + // the frame's own PTS (rather than pretending it is timestamp zero) is what keeps a + // delayed first frame honest. + None => { + self.offset = Some(now as i128 - src as i128); + now + } + }; + + self.last_source = Some(src); + self.last_broadcast = Some(broadcast); + self.last_arrival = Some(now); + moq_net::Timestamp::from_micros(broadcast).map_err(crate::Error::from) + } + + /// Re-anchor after an explicitly detected source restart, preserving the idle gap. + /// + /// The adapter path for a restart it observes out of band (an encoder reload, a file loop): + /// the next frame continues after everything published so far plus the downtime since the + /// previous frame, instead of rewinding the broadcast. + pub fn reset(&mut self, pts: moq_net::Timestamp) -> crate::Result { + self.reset_at(pts, self.clock.micros()) + } + + /// [`reset`](Self::reset) with an explicit arrival instant, for synthetic sources. + pub fn reset_at(&mut self, pts: moq_net::Timestamp, now: u64) -> crate::Result { + let src = pts.as_micros(); + let broadcast = self.reanchor(src, now)?; + self.last_source = Some(src); + self.last_broadcast = Some(broadcast); + self.last_arrival = Some(now); + moq_net::Timestamp::from_micros(broadcast).map_err(crate::Error::from) + } + + /// Move the offset so `src` continues after the last broadcast plus the idle gap since the + /// previous arrival. Returns the rebased broadcast micros. + fn reanchor(&mut self, src: u128, now: u64) -> crate::Result { + let base = match (self.last_broadcast, self.last_arrival) { + (Some(last), Some(arrival)) => last as u128 + now.saturating_sub(arrival) as u128, + // Unanchored: the reset frame itself is live now. + _ => now as u128, + }; + self.offset = Some(base as i128 - src as i128); + let broadcast = + u64::try_from(base).map_err(|_| crate::Error::UnmappableTimestamp(format!("{base} is out of range")))?; + // Refuse a mapping that contradicts the range instead of publishing it. + moq_net::Timestamp::from_micros(broadcast)?; + Ok(broadcast) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn epoch() -> Instant { + Instant::now() + } + + fn moq_epoch() -> SystemTime { + SystemTime::UNIX_EPOCH + Duration::from_millis(MOQ_EPOCH_UNIX_MILLIS) + } + + fn us(v: u64) -> moq_net::Timestamp { + moq_net::Timestamp::from_micros(v).unwrap() + } + + #[test] + fn copies_share_one_epoch() { + let clock = Clock::new(); + let shared = clock; + assert_eq!(clock.micros(), shared.micros()); + assert_eq!(clock.wall(), shared.wall()); + } + + #[test] + fn section_advertises_wall_in_clock_timescale() { + // PTS zero at exactly the moq epoch advertises 0. + let clock = Clock::new_at(epoch(), moq_epoch()).unwrap(); + assert_eq!(clock.section().wall, 0); + assert_eq!(clock.wall(), 0); + assert_eq!(clock.section().timescale, Clock::TIMESCALE.as_u64() as u32); + + // A second later is a second's worth of clock units. + let clock = Clock::new_at(epoch(), moq_epoch() + Duration::from_secs(1)).unwrap(); + assert_eq!(clock.wall(), 1_000_000); + } + + #[test] + fn unrepresentable_walls_are_refused() { + // One micro past the JSON-safe integer range: browsers would read a different number. + let past_safe = MOQ_EPOCH_UNIX_MILLIS * 1000 + MAX_SAFE_INTEGER + 1; + let far = SystemTime::UNIX_EPOCH + Duration::from_micros(past_safe); + assert!(Clock::with_wall(far).is_err()); + assert!(Clock::new_at(epoch(), far).is_err()); + } + + #[test] + fn delayed_first_frame_anchors_live() { + let clock = Clock::new_at(epoch(), moq_epoch()).unwrap(); + let mut source = clock.source(); + + // The source's first frame already carries 5s of PTS; it is live now, not now + 5s. + let first = source.translate_at(us(5_000_000), 100_000).unwrap(); + assert_eq!(first.as_micros(), 100_000); + + // Spacing survives: a second later on the source is a second later on the broadcast. + let second = source.translate_at(us(6_000_000), 1_100_000).unwrap(); + assert_eq!(second.as_micros(), 1_100_000); + + // And the wall mapping accounts for the PTS: broadcast 100ms is wall + 100ms. + assert_eq!( + clock.wall_clock(first).unwrap(), + moq_epoch() + Duration::from_micros(100_000) + ); + } + + #[test] + fn multiple_timescales_share_one_mapping() { + let clock = Clock::new_at(epoch(), moq_epoch()).unwrap(); + + // Two sources, 90kHz video and 48kHz audio, anchored at the same arrival instant. + let mut video = clock.source(); + let mut audio = clock.source(); + let v = video + .translate_at( + moq_net::Timestamp::new(180_000, moq_net::Timescale::new(90_000).unwrap()).unwrap(), + 1_000_000, + ) + .unwrap(); + let a = audio + .translate_at( + moq_net::Timestamp::new(96_000, moq_net::Timescale::new(48_000).unwrap()).unwrap(), + 1_000_000, + ) + .unwrap(); + + // Both said "2s of content, live now": one broadcast instant, one wall time. + assert_eq!(v.as_micros(), 1_000_000); + assert_eq!(a.as_micros(), 1_000_000); + assert_eq!(clock.wall_clock(v).unwrap(), clock.wall_clock(a).unwrap()); + + // A media second later is a broadcast second later on both. + let v2 = video + .translate_at( + moq_net::Timestamp::new(270_000, moq_net::Timescale::new(90_000).unwrap()).unwrap(), + 2_000_000, + ) + .unwrap(); + let a2 = audio + .translate_at( + moq_net::Timestamp::new(144_000, moq_net::Timescale::new(48_000).unwrap()).unwrap(), + 2_000_000, + ) + .unwrap(); + assert_eq!(v2.as_micros(), 2_000_000); + assert_eq!(a2.as_micros(), 2_000_000); + } + + #[test] + fn reset_translation_preserves_the_idle_gap() { + let clock = Clock::new_at(epoch(), moq_epoch()).unwrap(); + let mut source = clock.source(); + + assert_eq!(source.translate_at(us(0), 1_000_000).unwrap().as_micros(), 1_000_000); + assert_eq!( + source.translate_at(us(2_000_000), 3_000_000).unwrap().as_micros(), + 3_000_000 + ); + + // The encoder restarts at zero 5s later: the broadcast continues after the gap, and the + // wall epoch is untouched. + let wall_before = clock.wall(); + let resumed = source.translate_at(us(0), 8_000_000).unwrap(); + assert_eq!(resumed.as_micros(), 8_000_000); + assert_eq!(clock.wall(), wall_before); + + // Spacing resumes from the new anchor. + let next = source.translate_at(us(1_000_000), 9_000_000).unwrap(); + assert_eq!(next.as_micros(), 9_000_000); + } + + #[test] + fn explicit_reset_marks_a_detected_restart() { + let clock = Clock::new_at(epoch(), moq_epoch()).unwrap(); + let mut source = clock.source(); + + assert_eq!(source.translate_at(us(0), 1_000_000).unwrap().as_micros(), 1_000_000); + // The adapter saw the restart out of band and re-anchors, even though the PTS did not + // move backwards. + let resumed = source.reset_at(us(0), 4_000_000).unwrap(); + assert_eq!(resumed.as_micros(), 4_000_000); + } + + #[test] + fn bframe_reordering_within_a_group_survives() { + let clock = Clock::new_at(epoch(), moq_epoch()).unwrap(); + let mut source = clock.source(); + + assert_eq!(source.translate_at(us(0), 1_000_000).unwrap().as_micros(), 1_000_000); + assert_eq!( + source.translate_at(us(40_000), 1_040_000).unwrap().as_micros(), + 1_040_000 + ); + // A 20ms present-before-decode step back is reordering, not a reset: the offset stands. + let reordered = source.translate_at(us(20_000), 1_040_000).unwrap(); + assert_eq!(reordered.as_micros(), 1_020_000); + // And the broadcast continues from the reordered frontier. + let next = source.translate_at(us(80_000), 1_080_000).unwrap(); + assert_eq!(next.as_micros(), 1_080_000); + } + + #[test] + fn mapping_before_the_broadcast_began_is_refused() { + let clock = Clock::new_at(epoch(), moq_epoch()).unwrap(); + let mut source = clock.source(); + + // The first frame carries 100ms of PTS but arrives 50ms in: the offset is negative. + assert_eq!(source.translate_at(us(100_000), 50_000).unwrap().as_micros(), 50_000); + // A small step back stays within reorder tolerance but lands before broadcast zero. + assert!(matches!( + source.translate_at(us(0), 50_000), + Err(crate::Error::UnmappableTimestamp(_)) + )); + } + + #[test] + fn wall_mapping_survives_a_system_clock_adjustment() { + let clock = Clock::new_at(epoch(), moq_epoch()).unwrap(); + let before = clock.wall_clock(us(2_000_000)).unwrap(); + + // The mapping is a stored epoch, not a sampled clock: reading it again (after whatever + // the system clock did in between) changes nothing, and retained records map identically. + assert_eq!(clock.wall_clock(us(2_000_000)).unwrap(), before); + assert_eq!( + before, + moq_epoch() + Duration::from_secs(2), + "archive records keep their wall times" + ); + } + + #[test] + fn wall_clock_validates_bounds() { + let clock = Clock::new_at(epoch(), moq_epoch()).unwrap(); + // The largest representable broadcast timestamp still maps. + let max = moq_net::Timestamp::from_micros((1u64 << 62) - 1).unwrap(); + assert!(clock.wall_clock(max).is_err(), "past the JSON-safe range is refused"); + } +} diff --git a/rs/moq-mux/src/error.rs b/rs/moq-mux/src/error.rs index 0995e9bbcee..bd51e0bb0c2 100644 --- a/rs/moq-mux/src/error.rs +++ b/rs/moq-mux/src/error.rs @@ -206,6 +206,10 @@ pub enum Error { #[error("invalid timeline timescale: {0}")] InvalidTimescale(u32), + /// A source timestamp cannot be mapped onto the broadcast clock: it would land before the + /// broadcast began or outside the representable range. + #[error("timestamp cannot be mapped onto the broadcast clock: {0}")] + UnmappableTimestamp(String), /// Tried to set an application catalog section whose name collides with a /// reserved media section (`video`/`audio`). #[error("reserved catalog section: {0}")] diff --git a/rs/moq-mux/src/lib.rs b/rs/moq-mux/src/lib.rs index 331cf27ffe1..29d5d95f85e 100644 --- a/rs/moq-mux/src/lib.rs +++ b/rs/moq-mux/src/lib.rs @@ -37,7 +37,7 @@ pub mod select; mod source; pub mod timeline; -pub use clock::Clock; +pub use clock::{Clock, SourceMap}; pub use error::*; pub use pace::Pacer; pub use source::{Binding, Source}; diff --git a/rs/moq-mux/src/timeline.rs b/rs/moq-mux/src/timeline.rs index 95d31bef234..23122fb984d 100644 --- a/rs/moq-mux/src/timeline.rs +++ b/rs/moq-mux/src/timeline.rs @@ -53,7 +53,7 @@ use std::collections::{BTreeMap, BTreeSet, VecDeque}; use std::ops::Deref; use std::sync::{Arc, Mutex}; use std::task::Poll; -use std::time::{Duration, SystemTime}; +use std::time::Duration; use hang::catalog::{Archive, Timeline}; use hang::timeline::{DEFAULT_NAME, Range, Record, RecordExt}; @@ -91,18 +91,6 @@ pub struct Config { /// catalog. Leave it `None` when the media decides, which is the common case for real-time /// and for anything importing a source it doesn't control. pub duration_max: Option, - - /// The wall-clock time of `pts` 0, advertised in the catalog when set. - /// - /// It anchors content time to an absolute clock, which is what an HLS - /// `EXT-X-PROGRAM-DATE-TIME` or a DASH `availabilityStartTime` needs. A publisher stamping - /// timestamps from [`catalog::Producer::timestamp`](crate::catalog::Producer::timestamp) has - /// its `pts` 0 at construction, so `Some(SystemTime::now())` is the live answer; a recording - /// or an import passes the content's real start instead. - /// - /// Clamped to the moq epoch ([`MOQ_EPOCH_UNIX_MILLIS`](hang::catalog::MOQ_EPOCH_UNIX_MILLIS), - /// 2020), which the wire format measures from: an earlier time isn't representable. - pub wall: Option, } impl Default for Config { @@ -110,7 +98,6 @@ impl Default for Config { Self { duration_min: DEFAULT_DURATION_MIN, duration_max: None, - wall: None, } } } @@ -449,20 +436,13 @@ impl State { } /// The catalog section advertising this timeline. + /// + /// Carries the track name, timescale, and duration bound. Wall-clock mapping is the + /// catalog root clock's job ([`Clock`](crate::Clock)), not this section's. fn section(&self) -> Timeline { let mut section = Timeline::new(DEFAULT_NAME); section.timescale = self.timescale.as_u64() as u32; section.duration_max = self.config.duration_max.map(|max| self.units(max)); - section.wall = self.config.wall.map(|wall| { - // The wire measures from the moq epoch rather than the Unix one, so the value stays - // small enough for a 53-bit integer even at fine timescales. - let unix_millis = wall - .duration_since(SystemTime::UNIX_EPOCH) - .unwrap_or_default() - .as_millis(); - let moq_millis = unix_millis.saturating_sub(hang::catalog::MOQ_EPOCH_UNIX_MILLIS as u128); - (moq_millis * self.timescale.as_u64() as u128 / 1000) as u64 - }); section } } @@ -1905,26 +1885,14 @@ mod test { } #[tokio::test] - async fn section_advertises_track_and_wall() { + async fn section_advertises_track_without_wall() { + // Wall mapping moved to the catalog root clock: the timeline section carries the track, + // timescale, and duration bound, and nothing else time-anchoring. let (_broadcast, timeline) = setup(); let section = timeline.section(); assert_eq!(section.track, DEFAULT_NAME); assert_eq!(section.timescale, 1000); - assert_eq!(section.wall, None); - - // The wire counts from the moq epoch, so pts 0 at exactly the epoch advertises 0. - let (_broadcast, timeline) = setup_with(Config { - wall: Some(SystemTime::UNIX_EPOCH + Duration::from_millis(hang::catalog::MOQ_EPOCH_UNIX_MILLIS)), - ..Default::default() - }); - assert_eq!(timeline.section().wall, Some(0)); - - // A second later is a second's worth of timescale units. - let (_broadcast, timeline) = setup_with(Config { - wall: Some(SystemTime::UNIX_EPOCH + Duration::from_millis(hang::catalog::MOQ_EPOCH_UNIX_MILLIS + 1_000)), - ..Default::default() - }); - assert_eq!(timeline.section().wall, Some(1_000)); + assert_eq!(section.duration_max, None); } // Clones nest like the catalog's, so the first batch to finish doesn't publish records the diff --git a/rs/moq-transcode/src/catalog.rs b/rs/moq-transcode/src/catalog.rs index 9d957dd4eeb..81b4fea034b 100644 --- a/rs/moq-transcode/src/catalog.rs +++ b/rs/moq-transcode/src/catalog.rs @@ -225,8 +225,11 @@ pub(crate) fn populate( out.video = Video::default(); out.audio = hang::catalog::Audio::default(); // A derivative does not synthesize its own archive: keep the child's, including a - // live-only timeline, so replay/store discovery survives composition. + // live-only timeline, so replay/store discovery survives composition. The clock goes with + // it: the derivative republishes the child's timeline, so its timestamps only mean + // something under the child's wall mapping. out.archive = source.archive.clone(); + out.clock = source.clock; // Display metadata applies to the rungs too (same picture, smaller). out.video.display = source.video.display.clone(); @@ -548,9 +551,12 @@ mod tests { archive.replay = Some(PathRelativeOwned::from("./recordings/clip".to_string())); archive.version = Some(hang::catalog::Archive::VERSION); child.archive = Some(archive.clone()); + let clock = hang::catalog::Clock::new(1_751_846_400_000_000).unwrap(); + child.clock = Some(clock); let mut out = moq_mux::catalog::hang::Catalog::<()>::default(); populate(&mut out, &child, &[], None).unwrap(); assert_eq!(out.archive, Some(archive), "a derivative keeps the child's archive"); + assert_eq!(out.clock, Some(clock), "a derivative keeps the child's clock"); } } From 8ebc50ebb93c8d9b4fedaaccfda554c10542ea47 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 04:54:08 -0700 Subject: [PATCH 3/4] fix(hang): share the advertised clock and refuse unrepresentable inputs Capture stamps from the catalog's advertised clock so HLS/DASH wall times match the root mapping. Reject wall times before the moq epoch and explicit null timescales instead of substituting defaults. Co-Authored-By: grok-4.6 --- js/hang/src/catalog/clock.test.ts | 4 ++++ rs/hang/CHANGELOG.md | 3 ++- rs/hang/src/catalog/clock.rs | 12 ++++++++++-- rs/hang/src/catalog/timeline.rs | 6 ++++++ rs/moq-cli/src/publish.rs | 12 ++++++------ rs/moq-mux/CHANGELOG.md | 4 ++-- rs/moq-mux/src/clock.rs | 21 +++++++++++++++------ 7 files changed, 45 insertions(+), 17 deletions(-) diff --git a/js/hang/src/catalog/clock.test.ts b/js/hang/src/catalog/clock.test.ts index da0ab38ae31..795bc8297d8 100644 --- a/js/hang/src/catalog/clock.test.ts +++ b/js/hang/src/catalog/clock.test.ts @@ -29,6 +29,10 @@ 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 wall past the JSON-safe integers is refused", () => { expect(() => ClockSchema.parse({ wall: Number.MAX_SAFE_INTEGER + 1 })).toThrow(); }); diff --git a/rs/hang/CHANGELOG.md b/rs/hang/CHANGELOG.md index 1f6795b07bd..3dfe8b3044b 100644 --- a/rs/hang/CHANGELOG.md +++ b/rs/hang/CHANGELOG.md @@ -15,7 +15,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - [**breaking**] Replace the archive timeline `wall` field with a root `clock` section (`{wall, timescale}`). Wall time is one fixed broadcast mapping: PTS zero in the clock timescale since the moq epoch, with every track and the archive index converting - into it. Zero timescales and wall values past the JSON-safe integer range are refused. + into it. Zero timescales, explicit null timescales, and wall values past the JSON-safe integer + range are refused. ### Added diff --git a/rs/hang/src/catalog/clock.rs b/rs/hang/src/catalog/clock.rs index 382d848b15a..bfcf99b2591 100644 --- a/rs/hang/src/catalog/clock.rs +++ b/rs/hang/src/catalog/clock.rs @@ -49,7 +49,8 @@ pub struct Clock { pub wall: u64, /// Units per second for [`wall`](Self::wall). Defaults to 1,000,000 (microseconds), the - /// broadcast clock's own timescale. + /// broadcast clock's own timescale. An omitted field takes that default; an explicit + /// null is refused. #[serde( default = "Clock::default_timescale", deserialize_with = "deserialize_timescale_or_default" @@ -61,7 +62,8 @@ pub(crate) fn deserialize_timescale_or_default<'de, D>(deserializer: D) -> std:: where D: Deserializer<'de>, { - let value = Option::::deserialize(deserializer)?.unwrap_or_else(Clock::default_timescale); + // A missing field uses the serde `default`; an explicit null is not a number and is refused. + let value = u32::deserialize(deserializer)?; if value == 0 { return Err(serde::de::Error::custom("invalid timescale: 0")); } @@ -155,6 +157,12 @@ mod test { serde_json::from_str::(r#"{"wall":0,"timescale":0}"#).expect_err("a zero timescale must not decode"); } + #[test] + fn explicit_null_timescale_is_refused() { + serde_json::from_str::(r#"{"wall":0,"timescale":null}"#) + .expect_err("an explicit null timescale must not decode as the default"); + } + #[test] fn wall_beyond_json_safe_integers_is_refused() { serde_json::from_str::(r#"{"wall":9007199254740992}"#).expect_err("a wall past 2^53-1 must not decode"); diff --git a/rs/hang/src/catalog/timeline.rs b/rs/hang/src/catalog/timeline.rs index 3eb8f8f7a06..bcb6e951460 100644 --- a/rs/hang/src/catalog/timeline.rs +++ b/rs/hang/src/catalog/timeline.rs @@ -100,6 +100,12 @@ mod test { .expect_err("a zero timescale must not decode"); } + #[test] + fn explicit_null_timescale_is_refused() { + serde_json::from_str::(r#"{"track":"timeline.z","timescale":null}"#) + .expect_err("an explicit null timescale must not decode as the default"); + } + #[test] fn roundtrip() { let mut timeline = Timeline::new("timeline.z"); diff --git a/rs/moq-cli/src/publish.rs b/rs/moq-cli/src/publish.rs index dee9b7d9ca7..50e5ccb66e0 100644 --- a/rs/moq-cli/src/publish.rs +++ b/rs/moq-cli/src/publish.rs @@ -381,13 +381,13 @@ impl Publish { #[cfg(feature = "capture")] Source::Capture { catalog, video, audio } => { // Each enabled medium publishes its own track onto the shared - // broadcast + catalog. A single shared clock keeps the audio and - // video timelines aligned even though the devices open at - // different times. Video encodes on demand (camera opens only - // while subscribed). Both run on this task rather than a spawn: - // on macOS the audio future holds ObjC handles across an await, + // broadcast + catalog. Frames are stamped from the catalog's + // advertised clock so HLS/DASH wall times match the mapping on + // the wire. Video encodes on demand (camera opens only while + // subscribed). Both run on this task rather than a spawn: on + // macOS the audio future holds ObjC handles across an await, // so it is `!Send`. - let clock = moq_mux::Clock::new(); + let clock = catalog.clock(); let video_fut = { let broadcast = self.broadcast.clone(); let catalog = catalog.clone(); diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index 291684bbc9c..08cbdad305c 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -18,8 +18,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - [**breaking**] Replace `timeline::Config::wall` with the broadcast `Clock`'s fixed wall mapping, advertised at the catalog root as `clock: { wall, timescale }` independently of any archive. `catalog::Config::with_clock` names the content's real start for an import; - `catalog::Producer::clock` shares the epoch. Zero timescales and walls past the JSON-safe - integer range are refused. + `catalog::Producer::clock` shares the epoch. Zero timescales, walls before the moq epoch, + and walls past the JSON-safe integer range are refused. - `import::ContainerStream::new` takes a bare `ContainerFormat` instead of a `ContainerInit`. It only ever read the format, so the init's leading bytes were accepted and dropped. A stream recovers its own framing, so push everything through `decode` instead. diff --git a/rs/moq-mux/src/clock.rs b/rs/moq-mux/src/clock.rs index bf349b441dd..5f0fff91d21 100644 --- a/rs/moq-mux/src/clock.rs +++ b/rs/moq-mux/src/clock.rs @@ -25,10 +25,13 @@ fn wall_units(wall: SystemTime) -> crate::Result { let unix_micros = wall .duration_since(SystemTime::UNIX_EPOCH) .map(|d| d.as_micros()) - .unwrap_or(0); - // A clock before 2020 (an unsynced peer) saturates at the epoch: the wire cannot name it. - let moq_micros = unix_micros.saturating_sub(MOQ_EPOCH_UNIX_MILLIS as u128 * 1000); - let wall = u64::try_from(moq_micros).unwrap_or(u64::MAX); + .map_err(|_| hang::Error::InvalidWall(0))?; + let moq_epoch_micros = MOQ_EPOCH_UNIX_MILLIS as u128 * 1000; + // A time before 2020 cannot be named on the wire; refuse it rather than advertise 2020. + if unix_micros < moq_epoch_micros { + return Err(hang::Error::InvalidWall(0).into()); + } + let wall = u64::try_from(unix_micros - moq_epoch_micros).unwrap_or(u64::MAX); if wall > MAX_SAFE_INTEGER { return Err(hang::Error::InvalidWall(wall).into()); } @@ -65,8 +68,8 @@ impl Clock { /// Start a clock anchored at the current instant, with PTS zero at `wall`. /// /// For an import whose content carries its own start (a recording): the media keeps its - /// relative spacing and that start names the wall epoch. Refuses a wall outside the - /// JSON-safe integer range rather than publishing a number browsers misread. + /// relative spacing and that start names the wall epoch. Refuses a wall before the moq + /// epoch or outside the JSON-safe integer range rather than publishing a fabricated mapping. pub fn with_wall(wall: SystemTime) -> crate::Result { Ok(Self { epoch: Instant::now(), @@ -308,6 +311,12 @@ mod tests { let far = SystemTime::UNIX_EPOCH + Duration::from_micros(past_safe); assert!(Clock::with_wall(far).is_err()); assert!(Clock::new_at(epoch(), far).is_err()); + + // Before 2020 cannot be named on the wire; saturating to the epoch would lie. + assert!(Clock::with_wall(SystemTime::UNIX_EPOCH).is_err()); + assert!(Clock::new_at(epoch(), SystemTime::UNIX_EPOCH).is_err()); + assert!(Clock::with_wall(moq_epoch() - Duration::from_micros(1)).is_err()); + assert_eq!(Clock::new_at(epoch(), moq_epoch()).unwrap().wall(), 0); } #[test] From c15b6cc157376899faf3a428c7b313507131a36b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 17 Sep 2026 05:27:49 -0700 Subject: [PATCH 4/4] fix(hang): refuse wrapping clock maps and u32-only timescales SourceMap rejects a mapped timestamp above u64 microseconds instead of wrapping. The JS clock schema matches Rust's u32 timescale bound. Co-Authored-By: grok-4.6 --- js/hang/src/catalog/clock.test.ts | 4 ++++ js/hang/src/catalog/clock.ts | 12 ++++++++---- rs/moq-mux/src/clock.rs | 18 +++++++++++++++++- 3 files changed, 29 insertions(+), 5 deletions(-) diff --git a/js/hang/src/catalog/clock.test.ts b/js/hang/src/catalog/clock.test.ts index 795bc8297d8..d010f1a4f26 100644 --- a/js/hang/src/catalog/clock.test.ts +++ b/js/hang/src/catalog/clock.test.ts @@ -33,6 +33,10 @@ 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(); }); diff --git a/js/hang/src/catalog/clock.ts b/js/hang/src/catalog/clock.ts index d5986282ae1..ba2125b9f8e 100644 --- a/js/hang/src/catalog/clock.ts +++ b/js/hang/src/catalog/clock.ts @@ -1,7 +1,10 @@ import * as z from "@zod/mini"; -import { nonzeroU53Schema, u53, u53Schema } from "./integers"; +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. * @@ -18,8 +21,9 @@ export const ClockSchema = z.object({ 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. - timescale: z._default(nonzeroU53Schema, u53(1_000_000)), + // 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. */ @@ -34,7 +38,7 @@ export type Clock = z.infer; */ 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) + 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) diff --git a/rs/moq-mux/src/clock.rs b/rs/moq-mux/src/clock.rs index 5f0fff91d21..8a572f5a4ca 100644 --- a/rs/moq-mux/src/clock.rs +++ b/rs/moq-mux/src/clock.rs @@ -206,7 +206,9 @@ impl SourceMap { "{pts:?} lands before the broadcast began" ))); } - let mapped = mapped as u64; + let mapped = u64::try_from(mapped).map_err(|_| { + crate::Error::UnmappableTimestamp(format!("{pts:?} lands outside the representable range")) + })?; match self.last_broadcast { Some(last) if mapped < last && last - mapped > Self::MAX_REORDER.as_micros() as u64 => { // A source reset: re-anchor forward, counting the downtime as content. @@ -434,6 +436,20 @@ mod tests { assert_eq!(next.as_micros(), 1_080_000); } + #[test] + fn mapping_past_u64_micros_is_refused() { + let clock = Clock::new_at(epoch(), moq_epoch()).unwrap(); + let mut source = clock.source(); + + assert_eq!(source.translate_at(us(0), 0).unwrap().as_micros(), 0); + // A seconds-scale timestamp whose microsecond mapping exceeds u64::MAX. + let huge = moq_net::Timestamp::from_secs(u64::MAX / 1_000_000 + 2).unwrap(); + assert!(matches!( + source.translate_at(huge, 0), + Err(crate::Error::UnmappableTimestamp(_)) + )); + } + #[test] fn mapping_before_the_broadcast_began_is_refused() { let clock = Clock::new_at(epoch(), moq_epoch()).unwrap();