feat(net): callable Time unit constructors + brand the Opus frameDuration knob (#1703)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: kixelated

js/hang/src/util/latency.ts

@@ -21,7 +21,7 @@ export class Latency {
 
 	signals = new Effect();
 
-	#combined = new Signal<Moq.Time.Milli>(0 as Moq.Time.Milli);
+	#combined = new Signal<Moq.Time.Milli>(Time.Milli(0));
 	readonly combined: Signal<Moq.Time.Milli> = this.#combined;
 
 	constructor(props: LatencyProps) {
@@ -45,7 +45,7 @@ export class Latency {
 		}
 		jitter ??= 0;
 
-		const latency = Time.Milli.add(jitter as Moq.Time.Milli, buffer);
+		const latency = Time.Milli.add(Time.Milli(jitter), buffer);
 		this.#combined.set(latency);
 	}
 

js/net/src/lite/subscriber.ts

@@ -6,7 +6,7 @@ import { Compression, decompress } from "../compression.ts";
 import { Group } from "../group.ts";
 import * as Path from "../path.ts";
 import { type Reader, Stream } from "../stream.ts";
-import type * as Time from "../time.ts";
+import * as Time from "../time.ts";
 import type { TrackProducer } from "../track.ts";
 import { error } from "../util/error.ts";
 import { withTimeout } from "../util/timeout.ts";
@@ -540,7 +540,7 @@ export class Subscriber {
 				if (!probe) break;
 				this.#recvBandwidth.set(probe.bitrate ?? undefined);
 				if (this.#rtt && probe.rtt !== undefined) {
-					this.#rtt.set(probe.rtt as Time.Milli);
+					this.#rtt.set(Time.Milli(probe.rtt));
 				}
 			}
 		} catch (err: unknown) {

js/net/src/time.ts

@@ -1,6 +1,8 @@
 export type Nano = number & { readonly _brand: "nano" };
 
-export const Nano = {
+// Calling `Nano(x)` brands a raw number as nanoseconds. The unit is the caller's assertion: no
+// conversion happens, so reach for `fromMicro`/`fromMilli`/`fromSecond` when the source has a unit.
+export const Nano = Object.assign((value: number): Nano => value as Nano, {
 	zero: 0 as Nano,
 	fromMicro: (us: Micro): Nano => (us * 1_000) as Nano,
 	fromMilli: (ms: Milli): Nano => (ms * 1_000_000) as Nano,
@@ -15,11 +17,13 @@ export const Nano = {
 	div: (a: Nano, b: number): Nano => (a / b) as Nano,
 	max: (a: Nano, b: Nano): Nano => Math.max(a, b) as Nano,
 	min: (a: Nano, b: Nano): Nano => Math.min(a, b) as Nano,
-} as const;
+});
 
 export type Micro = number & { readonly _brand: "micro" };
 
-export const Micro = {
+// Calling `Micro(x)` brands a raw number as microseconds. See the `Nano` note: this asserts the unit
+// rather than converting, so use `fromNano`/`fromMilli`/`fromSecond` to convert from another unit.
+export const Micro = Object.assign((value: number): Micro => value as Micro, {
 	zero: 0 as Micro,
 	fromNano: (ns: Nano): Micro => (ns / 1_000) as Micro,
 	fromMilli: (ms: Milli): Micro => (ms * 1_000) as Micro,
@@ -34,11 +38,13 @@ export const Micro = {
 	div: (a: Micro, b: number): Micro => (a / b) as Micro,
 	max: (a: Micro, b: Micro): Micro => Math.max(a, b) as Micro,
 	min: (a: Micro, b: Micro): Micro => Math.min(a, b) as Micro,
-} as const;
+});
 
 export type Milli = number & { readonly _brand: "milli" };
 
-export const Milli = {
+// Calling `Milli(x)` brands a raw number as milliseconds. See the `Nano` note: this asserts the unit
+// rather than converting, so use `fromNano`/`fromMicro`/`fromSecond` to convert from another unit.
+export const Milli = Object.assign((value: number): Milli => value as Milli, {
 	zero: 0 as Milli,
 	fromNano: (ns: Nano): Milli => (ns / 1_000_000) as Milli,
 	fromMicro: (us: Micro): Milli => (us / 1_000) as Milli,
@@ -53,11 +59,13 @@ export const Milli = {
 	div: (a: Milli, b: number): Milli => (a / b) as Milli,
 	max: (a: Milli, b: Milli): Milli => Math.max(a, b) as Milli,
 	min: (a: Milli, b: Milli): Milli => Math.min(a, b) as Milli,
-} as const;
+});
 
 export type Second = number & { readonly _brand: "second" };
 
-export const Second = {
+// Calling `Second(x)` brands a raw number as seconds. See the `Nano` note: this asserts the unit
+// rather than converting, so use `fromNano`/`fromMicro`/`fromMilli` to convert from another unit.
+export const Second = Object.assign((value: number): Second => value as Second, {
 	zero: 0 as Second,
 	fromNano: (ns: Nano): Second => (ns / 1_000_000_000) as Second,
 	fromMicro: (us: Micro): Second => (us / 1_000_000) as Second,
@@ -72,4 +80,4 @@ export const Second = {
 	div: (a: Second, b: number): Second => (a / b) as Second,
 	max: (a: Second, b: Second): Second => Math.max(a, b) as Second,
 	min: (a: Second, b: Second): Second => Math.min(a, b) as Second,
-} as const;
+});

js/publish/src/audio/encoder.ts

@@ -2,15 +2,15 @@ import * as Catalog from "@moq/hang/catalog";
 import * as Container from "@moq/hang/container";
 import * as Util from "@moq/hang/util";
 import type * as Moq from "@moq/net";
-import type { Time } from "@moq/net";
+import { Time } from "@moq/net";
 import { Effect, type Getter, Signal } from "@moq/signals";
 import type * as Capture from "./capture";
 import { type Kind, normalizeSource, type Source } from "./types";
 
 const GAIN_MIN = 0.001;
 const FADE_TIME = 0.2;
 const OPUS_BITRATE_PER_CHANNEL = 32_000;
-const OPUS_FRAME_DURATION_MS = 20;
+const OPUS_FRAME_DURATION = Time.Milli(20);
 const AAC_BITRATE_PER_CHANNEL = 64_000;
 const AAC_FRAME_SAMPLES = 1024; // AAC-LC encodes a fixed 1024 samples per frame.
 
@@ -42,7 +42,8 @@ export type OpusConfig = {
 	mime: "opus";
 
 	bitrate?: number; // bits/sec, defaults to channelCount * 32kbps
-	frameDuration?: number; // ms, Opus supports 2.5-60ms, defaults to 20ms (the real-time default)
+	// The type carries the unit (ms): build with Time.Milli(20). Opus supports 2.5-60ms, defaults to 20ms.
+	frameDuration?: Time.Milli;
 	complexity?: number; // 0-10, higher is better quality but more CPU
 	packetlossperc?: number; // 0-100, expected loss the encoder optimizes for
 	useinbandfec?: boolean; // in-band forward error correction
@@ -225,7 +226,7 @@ export class Encoder {
 			bitrate: Catalog.u53(codec.bitrate ?? captured.channelCount * OPUS_BITRATE_PER_CHANNEL),
 			container: { kind: "legacy" } as const,
 			// jitter doubles as the Opus frame duration; toEncoderConfig converts it to µs for WebCodecs.
-			jitter: Catalog.u53(codec.frameDuration ?? OPUS_FRAME_DURATION_MS),
+			jitter: Catalog.u53(codec.frameDuration ?? OPUS_FRAME_DURATION),
 		};
 	}
 
@@ -424,7 +425,7 @@ function toEncoderConfig(
 
 		// jitter carries the frame duration in ms; WebCodecs wants µs.
 		if (config.jitter !== undefined) {
-			opus.frameDuration = config.jitter * 1000;
+			opus.frameDuration = Time.Micro.fromMilli(Time.Milli(config.jitter));
 		}
 
 		if (Object.keys(opus).length > 0) {

js/publish/src/video/polyfill.ts

@@ -57,7 +57,7 @@ export function TrackProcessor(track: StreamTrack): ReadableStream<VideoFrame> {
 		async pull(controller) {
 			while (true) {
 				const now = Time.Milli.now();
-				if (Time.Milli.sub(now, last) < ((1000 / frameRate) as Time.Milli)) {
+				if (Time.Milli.sub(now, last) < Time.Milli(1000 / frameRate)) {
 					await new Promise((r) => requestAnimationFrame(r));
 					continue;
 				}

js/watch/src/audio/source.ts

@@ -1,5 +1,6 @@
 import type * as Catalog from "@moq/hang/catalog";
 import type * as Moq from "@moq/net";
+import { Time } from "@moq/net";
 import { Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Signal } from "@moq/signals";
 import type { Broadcast } from "../broadcast";
 
@@ -123,7 +124,7 @@ export class Source {
 		const codecJitter = selected.config.jitter ?? defaultAudioJitter(selected.config) ?? 0;
 		const overhead = Math.ceil((WORKLET_QUANTUM / selected.config.sampleRate) * 1000);
 		const jitter = codecJitter + overhead;
-		effect.set(this.#output.jitter, jitter as Moq.Time.Milli);
+		effect.set(this.#output.jitter, Time.Milli(jitter));
 	}
 
 	/**

js/watch/src/element.ts

@@ -224,7 +224,7 @@ export default class MoqWatch extends HTMLElement {
 
 	#setLatencyNumber(value: string | null) {
 		const parsed = value ? Number.parseFloat(value) : Number.NaN;
-		this.controls.latency.set((Number.isFinite(parsed) ? parsed : 100) as Time.Milli);
+		this.controls.latency.set(Moq.Time.Milli(Number.isFinite(parsed) ? parsed : 100));
 	}
 
 	attributeChangedCallback(name: Observed, oldValue: string | null, newValue: string | null) {
@@ -325,7 +325,7 @@ export default class MoqWatch extends HTMLElement {
 
 	/** @deprecated Use `latency = <number>` instead. */
 	set jitter(value: number) {
-		this.controls.latency.set(value as Time.Milli);
+		this.controls.latency.set(Moq.Time.Milli(value));
 	}
 
 	get catalogFormat(): CatalogFormat | undefined {

js/watch/src/sync.ts

@@ -5,8 +5,8 @@ import { Effect, type Getter, getter, type Inputs, type Readonlys, readonlys, Si
 /** Latency: `"real-time"` auto-computes jitter from RTT; a `Time.Milli` sets a fixed jitter. */
 export type Latency = "real-time" | Time.Milli;
 
-const MIN_JITTER = 20 as Time.Milli;
-const FALLBACK_JITTER = 100 as Time.Milli;
+const MIN_JITTER = Time.Milli(20);
+const FALLBACK_JITTER = Time.Milli(100);
 
 type SyncInput = {
 	// The latency setting: "real-time" auto-computes jitter from RTT, a number sets a fixed jitter.
@@ -94,7 +94,7 @@ export class Sync {
 			this.#minRtt = this.#minRtt !== undefined ? Math.min(this.#minRtt, rtt) : rtt;
 
 			// Buffer enough for a retransmit (1 RTT for ACK + retransmit).
-			const jitter = Math.max(MIN_JITTER, this.#minRtt * 1.25) as Time.Milli;
+			const jitter = Time.Milli(Math.max(MIN_JITTER, this.#minRtt * 1.25));
 			this.#output.jitter.set(jitter);
 			return;
 		}

js/watch/src/ui/components/buffer-control.ts

@@ -1,11 +1,11 @@
-import type { Moq } from "@moq/hang";
+import { Moq } from "@moq/hang";
 import type { Effect } from "@moq/signals";
 import type { BufferedRanges } from "../..";
 import type MoqWatch from "../../element";
 
-const MIN_RANGE = 0 as Moq.Time.Milli;
-const RANGE_STEP = 10 as Moq.Time.Milli;
-const DEFAULT_MAX = 4000 as Moq.Time.Milli;
+const MIN_RANGE = Moq.Time.Milli(0);
+const RANGE_STEP = Moq.Time.Milli(10);
+const DEFAULT_MAX = Moq.Time.Milli(4000);
 const LABEL_WIDTH = 48;
 
 function drawRanges(
@@ -41,8 +41,8 @@ function drawRanges(
 
 	for (let i = 0; i < ranges.length; i++) {
 		const range = ranges[i];
-		const startMs = (range.start - timestamp) as Moq.Time.Milli;
-		const endMs = (range.end - timestamp) as Moq.Time.Milli;
+		const startMs = Moq.Time.Milli(range.start - timestamp);
+		const endMs = Moq.Time.Milli(range.end - timestamp);
 		const visibleStart = Math.max(0, startMs);
 		const visibleEnd = Math.min(endMs, max);
 
@@ -139,8 +139,8 @@ export function bufferControl(parent: Effect, watch: MoqWatch, max: Moq.Time.Mil
 		const trackWidth = rect.width - LABEL_WIDTH;
 		const x = Math.max(0, Math.min(clientX - rect.left - LABEL_WIDTH, trackWidth));
 		const ms = (x / trackWidth) * max;
-		const snapped = (Math.round(ms / RANGE_STEP) * RANGE_STEP) as Moq.Time.Milli;
-		const clamped = Math.max(MIN_RANGE, Math.min(max, snapped)) as Moq.Time.Milli;
+		const snapped = Moq.Time.Milli(Math.round(ms / RANGE_STEP) * RANGE_STEP);
+		const clamped = Moq.Time.Milli(Math.max(MIN_RANGE, Math.min(max, snapped)));
 		watch.controls.latency.set(clamped);
 	};
 
@@ -169,18 +169,18 @@ export function bufferControl(parent: Effect, watch: MoqWatch, max: Moq.Time.Mil
 	});
 
 	parent.event(viz, "keydown", (e) => {
-		let delta = 0 as Moq.Time.Milli;
+		let delta = Moq.Time.Milli(0);
 		if (e.key === "ArrowRight" || e.key === "ArrowUp") {
 			delta = RANGE_STEP;
 		} else if (e.key === "ArrowLeft" || e.key === "ArrowDown") {
-			delta = -RANGE_STEP as Moq.Time.Milli;
+			delta = Moq.Time.Milli(-RANGE_STEP);
 		} else {
 			return;
 		}
 		e.preventDefault();
 		interact();
 		const current = watch.backend.output.jitter.peek();
-		const value = Math.max(MIN_RANGE, Math.min(max, current + delta)) as Moq.Time.Milli;
+		const value = Moq.Time.Milli(Math.max(MIN_RANGE, Math.min(max, current + delta)));
 		watch.controls.latency.set(value);
 	});
 

js/watch/src/ui/components/latency.ts

@@ -1,4 +1,4 @@
-import type { Moq } from "@moq/hang";
+import { Moq } from "@moq/hang";
 import type { Effect } from "@moq/signals";
 import * as DOM from "@moq/signals/dom";
 import type MoqWatch from "../../element";
@@ -25,7 +25,7 @@ export function latencyTab(parent: Effect, watch: MoqWatch): HTMLElement {
 	const buttons = PRESETS.map((preset) => {
 		const chip = DOM.create("button", { className: "chip", type: "button" }, preset.label);
 		parent.event(chip, "click", () => {
-			watch.controls.latency.set(preset.value === "real-time" ? "real-time" : (preset.value as Moq.Time.Milli));
+			watch.controls.latency.set(preset.value === "real-time" ? "real-time" : Moq.Time.Milli(preset.value));
 		});
 		chips.appendChild(chip);
 		return { preset, chip };