@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/src/align.ts

@@ -0,0 +1,235 @@
+/**
+ * Shared group-alignment primitive for MMT over MoQ switching sets.
+ *
+ * Pure math — no MMT wire parsing, no CMCD, no I/O. Callers wire the output
+ * into their own drift-observation plumbing (see media-router.ts for the
+ * libmmt wiring).
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * Contract (integer-ticks form, authoritative):
+ *
+ *     groupId = ticks < 0  ?  0  :  floor(ticks / groupDurationTicks)
+ *
+ * Where `ticks` is a media timestamp expressed at the catalog's `timescale`
+ * (Hz), and `groupDurationTicks = groupDurationSec * timescale`.
+ *
+ * Integer math means there is no epsilon and no float rounding to reason
+ * about. The seconds-form wrapper `groupIdFor(Seconds, seconds)` exists for
+ * legacy callers but converts to ticks internally.
+ *
+ * Every sender/receiver that emits or consumes MoQ groups from an MMT or
+ * CMAF switching set MUST derive groupId from this formula so that base,
+ * delta, and repair tracks agree on the group boundary for a given media
+ * timestamp across languages and processes.
+ *
+ * Test vectors that exercise the contract live at
+ * `packages/container/test-vectors/align.json`; the Go and Rust siblings
+ * load the same fixture so cross-language agreement is executable, not
+ * prose. **Formula changes require updating the fixture AND all three
+ * sibling implementations in the same release** — divergence between
+ * sender/relay/receiver is worse than any formula change.
+ *
+ * Canonical implementations:
+ *   Go:   Blockcast/multicast `cmd/caddy/sender/group_align.go`
+ *         (commit 104eeff) — sender-side groupId stamping on egress.
+ *   Rust: moqtail/moqtail `apps/relay/src/server/abr.rs`
+ *         (commit 39accbf; experimental branch, may be rebased — rely
+ *         on the SHA, not the branch name) — relay-side check.
+ *   TS:   THIS FILE (libmmt) — consumed by moq-lib + moqtail-ts via
+ *         @blockcast/mmt-container.
+ * ──────────────────────────────────────────────────────────────────────────
+ */
+
+/**
+ * Branded seconds type. Construct only via `secondsFromTicks(ticks, timescale)`
+ * or `asSeconds(n)` (the latter exists solely for tests and bring-up). The
+ * brand prevents accidentally passing a raw tick count — or a Date.now()
+ * millisecond — to an API that expects a media-time in seconds.
+ */
+export type Seconds = number & { readonly __brand: 'Seconds' }
+
+/**
+ * Explicit conversion constructor: ticks at `timescale` Hz → Seconds.
+ *
+ * Call this at the wire/catalog boundary so the brand flows with the value
+ * through the rest of the system. Throws on non-finite inputs or
+ * non-positive timescale (CLAUDE.md §Architectural Principles: error on
+ * bad init).
+ */
+export function secondsFromTicks(ticks: number, timescale: number): Seconds {
+  if (!Number.isFinite(ticks)) {
+    throw new Error(`[align] secondsFromTicks: ticks must be finite, got ${ticks}`)
+  }
+  if (!Number.isFinite(timescale) || timescale <= 0) {
+    throw new Error(
+      `[align] secondsFromTicks: timescale must be positive and finite, got ${timescale}`,
+    )
+  }
+  return (ticks / timescale) as Seconds
+}
+
+/**
+ * Escape hatch for tests / bring-up code that holds a raw seconds number
+ * (e.g. a catalog field that ships as float seconds). Production code
+ * should prefer `secondsFromTicks` so the conversion site is explicit.
+ */
+export function asSeconds(n: number): Seconds {
+  if (!Number.isFinite(n)) {
+    throw new Error(`[align] asSeconds: value must be finite, got ${n}`)
+  }
+  return n as Seconds
+}
+
+/**
+ * Deterministic groupId from integer ticks. Authoritative form of the
+ * contract (see module docstring).
+ *
+ * @param ticks              — media presentation time in ticks (integer).
+ *                             Negative values clamp to group 0 (matches
+ *                             the Go sibling's base-clamp).
+ * @param groupDurationTicks — group duration in ticks (positive integer).
+ * @returns non-negative integer groupId.
+ *
+ * Throws on non-integer/non-finite inputs or non-positive duration. These
+ * are init-time errors, not packet-hot-path errors — callers ingesting
+ * wire data should validate once at catalog load, not once per packet.
+ */
+export function groupIdForTicks(ticks: number, groupDurationTicks: number): number {
+  if (!Number.isInteger(ticks)) {
+    throw new Error(
+      `[align] groupIdForTicks: ticks must be an integer, got ${ticks}`,
+    )
+  }
+  if (!Number.isInteger(groupDurationTicks) || groupDurationTicks <= 0) {
+    throw new Error(
+      `[align] groupIdForTicks: groupDurationTicks must be a positive integer, got ${groupDurationTicks}`,
+    )
+  }
+  if (ticks < 0) return 0
+  return Math.floor(ticks / groupDurationTicks)
+}
+
+/**
+ * Seconds-form wrapper around `groupIdForTicks`. Kept for backwards
+ * compatibility with existing callers that hold `Seconds` (or a raw
+ * `number` that semantically represents seconds).
+ *
+ * Internally converts to ticks using a synthetic 1e9 Hz timescale so the
+ * integer-math contract is the single source of truth. The `| number`
+ * branch of the parameter type is a migration ramp — new code should
+ * pass `Seconds` explicitly (via `secondsFromTicks` or `asSeconds`).
+ *
+ * @param mediaTimeSec     — finite number of seconds; negatives clamp to 0.
+ * @param groupDurationSec — positive finite seconds.
+ *
+ * @deprecated Use `groupIdForTicks(ticks, groupDurationTicks)` with
+ *   tick-space inputs from the catalog. The seconds wrapper rounds to the
+ *   nearest nanosecond and throws above ~104 days of media time; the
+ *   integer-ticks form has no rounding and a much wider safe range.
+ *
+ *   The rounding is not benign: when `groupDurationTicks / timescale` is not
+ *   ns-exact (33333@90k, 1001@30k, 1024@44.1k — all real catalog cadences)
+ *   the quantized duration under-counts and `expected` slips a whole group.
+ *   See the divergence fixture in `__tests__/align.test.ts`.
+ *
+ *   No non-test caller remains in this package: `MediaRouter` now takes
+ *   `GroupBoundaryTicks` (PCL-2211). Removal is tracked by BLO-21176.
+ */
+export function groupIdFor(
+  mediaTimeSec: Seconds | number,
+  groupDurationSec: number,
+): number {
+  if (!Number.isFinite(mediaTimeSec as number)) {
+    throw new Error(
+      `[align] groupIdFor: mediaTimeSec must be a finite number, got ${mediaTimeSec}`,
+    )
+  }
+  if (!Number.isFinite(groupDurationSec) || groupDurationSec <= 0) {
+    throw new Error(
+      `[align] groupIdFor: groupDurationSec must be a positive finite number, got ${groupDurationSec}`,
+    )
+  }
+  if ((mediaTimeSec as number) < 0) return 0
+  // 1e9 Hz keeps both operands inside Number.MAX_SAFE_INTEGER (2^53-1)
+  // for ~104 days of media time. Beyond that, Math.round returns a
+  // non-safe-integer float that Number.isInteger still accepts — throw
+  // explicitly so the caller picks a narrower timescale rather than
+  // silently quantizing.
+  const TS = 1_000_000_000
+  const ticks = Math.round((mediaTimeSec as number) * TS)
+  const durTicks = Math.round(groupDurationSec * TS)
+  if (durTicks <= 0) {
+    throw new Error(
+      `[align] groupIdFor: groupDurationSec=${groupDurationSec} rounds to <1 tick at 1e9 Hz; pass groupIdForTicks directly for sub-nanosecond durations`,
+    )
+  }
+  if (!Number.isSafeInteger(ticks)) {
+    throw new Error(
+      `[align] groupIdFor: mediaTimeSec=${mediaTimeSec} overflows safe-integer ticks at 1e9 Hz (>~104 days); use groupIdForTicks with a narrower timescale`,
+    )
+  }
+  return groupIdForTicks(ticks, durTicks)
+}
+
+/**
+ * Result of a drift check between expected and actual groupIds.
+ *
+ * Discriminated on `kind` so callers must handle both outcomes explicitly
+ * (the previous `{ drifted: boolean, deltaGroups: number }` shape let a
+ * drifted result slip through with a silent `if (result.drifted)` gate).
+ */
+export type DriftCheckResult =
+  | { readonly kind: 'aligned'; readonly deltaGroups: 0 }
+  | { readonly kind: 'drifted'; readonly deltaGroups: number }
+
+/**
+ * Compare a packet-stamped groupId against the formula-derived expectation.
+ *
+ * Pure observer — does not throw on drift, does not mutate anything.
+ * Callers decide how to react (e.g. bump a CMCD counter, log, ignore).
+ *
+ * @param expected — groupId as derived via `groupIdForTicks` or `groupIdFor`.
+ * @param actual   — groupId as stamped on the incoming packet/group.
+ */
+export function driftCheck(expected: number, actual: number): DriftCheckResult {
+  if (!Number.isInteger(expected) || !Number.isInteger(actual)) {
+    throw new Error(
+      `[align] driftCheck: both arguments must be integer groupIds, got expected=${expected} actual=${actual}`,
+    )
+  }
+  const deltaGroups = actual - expected
+  if (deltaGroups === 0) return { kind: 'aligned', deltaGroups: 0 }
+  return { kind: 'drifted', deltaGroups }
+}
+
+export type MmtpSubgroupKeyInput =
+  | { readonly kind: 'mpu-metadata' }
+  | {
+      readonly kind: 'timed'
+      readonly movieFragmentSequenceNumber: number
+      readonly sampleNumber: number
+    }
+  | { readonly kind: 'non-timed'; readonly itemId: number }
+
+/**
+ * Canonical, domain-separated key for MMTP payloads sharing one MoQ subgroup.
+ * This is a map/storage key, not the scalar MoQ subgroup ID. MPU metadata is
+ * carried in subgroup 0; media identity remains explicit and collision-free.
+ */
+export function subgroupKeyFor(input: MmtpSubgroupKeyInput): string {
+  if (input.kind === 'mpu-metadata') return 'metadata:0'
+
+  const values =
+    input.kind === 'timed'
+      ? [input.movieFragmentSequenceNumber, input.sampleNumber]
+      : [input.itemId]
+  for (const value of values) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff_ffff) {
+      throw new Error(`[align] subgroup key coordinates must be uint32, got ${value}`)
+    }
+  }
+
+  return input.kind === 'timed'
+    ? `timed:${input.movieFragmentSequenceNumber}:${input.sampleNumber}`
+    : `non-timed:${input.itemId}`
+}

package/src/audio-init-parser.ts

@@ -0,0 +1,189 @@
+/**
+ * Audio Init Data Parser — extract frame samples from a codec descriptor.
+ *
+ * Consumes the RAW codec configuration bytes (AudioSpecificConfig for AAC,
+ * OpusHead for Opus) — i.e. the catalog `description` field (hang
+ * `AudioConfig.description`), NOT the catalog `initData` field.
+ *
+ * Since BLO-9884 these are two distinct catalog fields: `initData` is a
+ * base64 ISOBMFF init segment (ftyp + moov) per draft-ietf-moq-cmsf-00 §3.1,
+ * while `description` carries the bare codec descriptor. Hang's `root.ts`
+ * parses a CMSF `initData` segment with `decodeInitSegment()` and routes the
+ * descriptor it recovers (`init.description`) into `description`; the bytes
+ * that reach this parser are therefore always the bare descriptor. Do NOT
+ * pass a ftyp+moov `initData` blob here — the ASC bit-reader would interpret
+ * the ftyp box size word as an audioObjectType and return a garbage frame
+ * count (the audio analogue of the "Failed to parse avcC" CMAF regression
+ * documented in root.ts).
+ *
+ * Supported codecs:
+ *   - AAC (mp4a.40.*): AudioSpecificConfig per ISO 14496-3 §1.6.2.1
+ *   - Opus: fixed 960 samples per RFC 6716 §2.1.4
+ *
+ * Reference: hang-mmt-fec/rs/moq-mux/src/import/aac.rs:AacConfig::parse()
+ */
+
+// ISO 14496-3 Table 1.14: samplingFrequencyIndex → Hz
+const AAC_SAMPLE_RATES = [
+  96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050,
+  16000, 12000, 11025, 8000, 7350,
+] as const
+
+/**
+ * AAC Audio Object Types that determine frame size.
+ * ISO 14496-3 Table 1.3:
+ *   1  = AAC-Main    → 1024 samples
+ *   2  = AAC-LC      → 1024 samples
+ *   3  = AAC-SSR     → 1024 samples
+ *   4  = AAC-LTP     → 1024 samples
+ *   5  = SBR         → 2048 samples (HE-AAC v1)
+ *   6  = AAC-Scalable → 1024 samples
+ *   23 = ER AAC-LD   → 512 samples
+ *   39 = ER AAC-ELD  → 480 samples
+ *   29 = PS          → 2048 samples (HE-AAC v2, implies SBR)
+ */
+function aacFrameSamplesForObjectType(objectType: number): number {
+  switch (objectType) {
+    case 5:  return 2048  // SBR (HE-AAC v1)
+    case 29: return 2048  // PS (HE-AAC v2, implies SBR)
+    case 23: return 512   // ER AAC-LD
+    case 39: return 480   // ER AAC-ELD
+    default: return 1024  // LC, Main, SSR, LTP, Scalable, etc.
+  }
+}
+
+/**
+ * Parse AAC AudioSpecificConfig (ASC) to extract frame samples.
+ *
+ * ASC is a bit-packed structure (ISO 14496-3 §1.6.2.1):
+ *   audioObjectType (5 bits, or 5+6 if ==31)
+ *   samplingFrequencyIndex (4 bits, explicit rate if ==0xf)
+ *   channelConfiguration (4 bits)
+ *   ... (SBR/PS extensions follow)
+ *
+ * The audioObjectType determines frame samples:
+ *   LC-AAC → 1024, HE-AAC(SBR) → 2048, AAC-LD → 512, AAC-ELD → 480
+ *
+ * @param asc - Raw AudioSpecificConfig bytes (NOT ADTS, NOT fMP4 esds box)
+ * @returns frame samples, or null if ASC is invalid/too short
+ */
+export function parseAacFrameSamples(asc: Uint8Array): number | null {
+  if (asc.length < 2) return null
+
+  // Bit reader
+  let bitPos = 0
+  const readBits = (n: number): number => {
+    let val = 0
+    for (let i = 0; i < n; i++) {
+      const byteIdx = (bitPos + i) >> 3
+      const bitIdx = 7 - ((bitPos + i) & 7)
+      if (byteIdx >= asc.length) return -1
+      val = (val << 1) | ((asc[byteIdx]! >> bitIdx) & 1)
+    }
+    bitPos += n
+    return val
+  }
+
+  // audioObjectType: 5 bits, extended to 5+6=11 bits if ==31
+  let objectType = readBits(5)
+  if (objectType === 31) {
+    objectType = 32 + readBits(6)
+  }
+  if (objectType < 0) return null
+
+  // samplingFrequencyIndex: 4 bits
+  const freqIndex = readBits(4)
+  if (freqIndex < 0) return null
+  if (freqIndex === 0xf) {
+    // Explicit 24-bit sample rate follows
+    readBits(24)
+  }
+
+  // channelConfiguration: 4 bits
+  readBits(4)
+
+  // Check for SBR/PS signaling (implicit in HE-AAC)
+  // If base objectType is AAC-LC and SBR extension is present, frame size doubles
+  if (objectType === 2 /* AAC-LC */ && asc.length >= 4) {
+    // Check for SBR extension: 11-bit sync word 0x2b7
+    const remaining = (asc.length * 8) - bitPos
+    if (remaining >= 11) {
+      const syncExt = readBits(11)
+      if (syncExt === 0x2b7) {
+        const extObjectType = readBits(5)
+        if (extObjectType === 5 /* SBR */ || extObjectType === 22 /* ER SBR */) {
+          return 2048 // SBR present → 2048 samples
+        }
+        if (extObjectType === 29 /* PS */) {
+          return 2048 // PS implies SBR → 2048 samples
+        }
+      }
+    }
+  }
+
+  return aacFrameSamplesForObjectType(objectType)
+}
+
+/**
+ * Parse AAC ASC to extract sample rate.
+ * Useful when catalog samplerate is missing but initData is available.
+ */
+export function parseAacSampleRate(asc: Uint8Array): number | null {
+  if (asc.length < 2) return null
+
+  let bitPos = 0
+  const readBits = (n: number): number => {
+    let val = 0
+    for (let i = 0; i < n; i++) {
+      const byteIdx = (bitPos + i) >> 3
+      const bitIdx = 7 - ((bitPos + i) & 7)
+      if (byteIdx >= asc.length) return -1
+      val = (val << 1) | ((asc[byteIdx]! >> bitIdx) & 1)
+    }
+    bitPos += n
+    return val
+  }
+
+  // Skip audioObjectType (5 or 11 bits)
+  let objectType = readBits(5)
+  if (objectType === 31) readBits(6)
+
+  const freqIndex = readBits(4)
+  if (freqIndex < 0) return null
+  if (freqIndex === 0xf) {
+    return readBits(24)
+  }
+  return AAC_SAMPLE_RATES[freqIndex] ?? null
+}
+
+/**
+ * Opus frame samples: 960 at 48kHz (20ms) per RFC 6716 §2.1.4.
+ *
+ * Opus supports variable frame sizes (2.5, 5, 10, 20, 40, 60, 80, 100, 120ms)
+ * but the frame size is per-packet (in the TOC byte), not in the init data.
+ * OpusHead (RFC 7845) carries sample_rate and channel_count only.
+ *
+ * 960 samples at 48kHz = 20ms is the normative default per RFC 6716.
+ */
+export function parseOpusFrameSamples(_opusHead?: Uint8Array): number {
+  return 960
+}
+
+/**
+ * Extract frame samples from a bare codec descriptor based on codec string.
+ *
+ * @param codec - Codec string from catalog (e.g., "mp4a.40.2", "opus")
+ * @param codecConfig - Raw codec descriptor bytes: AudioSpecificConfig for
+ *   AAC, OpusHead for Opus. This is the catalog `description` field, NOT the
+ *   catalog `initData` (ftyp+moov) field — see the file header.
+ * @returns frame samples, or null if codec unsupported or the descriptor is invalid
+ */
+export function frameSamplesFromInit(codec: string, codecConfig: Uint8Array): number | null {
+  if (codec.startsWith('mp4a')) {
+    return parseAacFrameSamples(codecConfig)
+  }
+  if (codec.startsWith('opus') || codec === 'Opus') {
+    return parseOpusFrameSamples(codecConfig)
+  }
+  return null
+}

package/src/audio-ring-buffer.ts

@@ -0,0 +1,120 @@
+/**
+ * AudioRingBuffer — plain FIFO audio buffer (no clock recovery).
+ *
+ * Source of truth for the audio buffer algorithm used in both moq-lib and
+ * moqtail AudioWorklet processors. AudioWorklet isolation requires the
+ * worklet copy to be self-contained (no imports), so changes here must be
+ * manually synced to:
+ *   - moqtail-private/apps/client-js/src/lib/audio-worklet-processor.js
+ *   - hang-mmt-fec/js/watch/src/audio/ring-buffer.ts (uses @moq/lite Time types)
+ *
+ * Rationale: FEC guarantees gap-free, ordered audio on multicast; MoQ
+ * delivers ordered audio without drops. The decoder output rate matches
+ * the AudioContext destination rate closely enough that skip/dup clock
+ * recovery is unnecessary and harmful — a single sample skip at 48 kHz is
+ * a ~21 µs phase glitch, and repeated skip/dup produces audible pitch
+ * wobble on pure tones (measured: 16 Hz offset + ±11 Hz spread on a 1 kHz
+ * test tone before this refactor).
+ */
+
+export interface AudioRingBufferConfig {
+  /** Number of audio channels */
+  channels: number;
+  /** Sample rate in Hz */
+  rate: number;
+  /** Buffer latency in milliseconds */
+  latencyMs: number;
+  /** Start in unstalled state (for source switching) */
+  startUnstalled?: boolean;
+}
+
+export class AudioRingBuffer {
+  readonly channels: number;
+  readonly rate: number;
+
+  #buffer: Float32Array[];
+  #writeIndex = 0;
+  #readIndex = 0;
+  #stalled: boolean;
+
+  constructor(config: AudioRingBufferConfig) {
+    this.channels = config.channels;
+    this.rate = config.rate;
+    this.#stalled = !(config.startUnstalled ?? false);
+
+    const samples = Math.ceil(config.rate * (config.latencyMs / 1000));
+    this.#buffer = [];
+    for (let i = 0; i < config.channels; i++) {
+      this.#buffer[i] = new Float32Array(samples);
+    }
+  }
+
+  get stalled(): boolean { return this.#stalled; }
+  get capacity(): number { return this.#buffer[0].length; }
+  get length(): number { return this.#writeIndex - this.#readIndex; }
+
+  /**
+   * Append decoded audio samples to the FIFO.
+   * Timestamp parameter retained for API compatibility but is ignored —
+   * FIFO is sequence-based, not time-based.
+   */
+  write(_timestampUs: number, data: Float32Array[]): void {
+    const samples = data[0].length;
+
+    const start = this.#writeIndex;
+    const end = start + samples;
+
+    // Overflow: discard oldest samples (protects against encoder/AudioContext
+    // clock drift when one runs faster than the other).
+    const overflow = end - this.#readIndex - this.#buffer[0].length;
+    if (overflow >= 0) {
+      this.#stalled = false;
+      this.#readIndex += overflow;
+    }
+
+    // Unstall at half capacity — enough prebuffer for bounded jitter.
+    if (this.#stalled && (end - this.#readIndex) >= Math.floor(this.#buffer[0].length / 2)) {
+      this.#stalled = false;
+    }
+
+    // Append samples sequentially
+    for (let ch = 0; ch < this.channels; ch++) {
+      const src = data[ch];
+      const dst = this.#buffer[ch];
+      for (let i = 0; i < samples; i++) {
+        dst[(start + i) % dst.length] = src[i];
+      }
+    }
+    this.#writeIndex = end;
+  }
+
+  /**
+   * Read samples into output buffers — plain FIFO, no clock recovery.
+   * FEC + MoQ delivery guarantees no gaps, so skip/dup is unnecessary.
+   * Underrun → zero-fill.
+   */
+  read(output: Float32Array[]): number {
+    if (this.#stalled) return 0;
+
+    const available = this.#writeIndex - this.#readIndex;
+    if (available === 0) return 0;
+
+    const requested = output[0].length;
+    const readSamples = Math.min(available, requested);
+
+    for (let ch = 0; ch < this.channels; ch++) {
+      const dst = output[ch];
+      const src = this.#buffer[ch];
+      for (let i = 0; i < readSamples; i++) {
+        dst[i] = src[(this.#readIndex + i) % src.length];
+      }
+      // Zero-fill remainder on underrun
+      for (let i = readSamples; i < requested; i++) {
+        dst[i] = 0;
+      }
+    }
+
+    this.#readIndex += readSamples;
+    return readSamples;
+  }
+}

package/src/authored-timing.ts

@@ -0,0 +1,63 @@
+/**
+ * Exact timing authored by an ISO-BMFF media fragment.
+ *
+ * `timestamp`/`duration` fields on the browser-facing APIs are converted to
+ * microseconds for legacy callers. This value remains in the media track's
+ * native timescale so consumers that own a CMAF/WebCodecs timeline do not
+ * have to reconstruct integer ticks from rounded wall-clock values.
+ */
+export interface AuthoredTiming {
+  /** Exact decode time in the media track's timescale. */
+  decodeTime: bigint
+  /** Exact presentation time in the media track's timescale, including CTS. */
+  presentationTime: bigint
+  /**
+   * Exact sample duration in the media track's timescale. This remains a
+   * number because ISO-BMFF stores sample_duration as an unsigned 32-bit
+   * field, whose full range is exactly representable by JavaScript numbers.
+   */
+  durationTicks: number
+  /** `mdhd` timescale for all values above. */
+  mediaTimescale: number
+}
+
+/** Convert authored media ticks to an integer target timescale without first
+ * narrowing the authored tick value to a wall-clock float. */
+export function scaleAuthoredTicks(
+  ticks: bigint,
+  mediaTimescale: number,
+  targetTimescale: number,
+): number | null {
+  if (!Number.isSafeInteger(mediaTimescale) || mediaTimescale <= 0 ||
+      !Number.isSafeInteger(targetTimescale) || targetTimescale <= 0) return null
+
+  const negative = ticks < 0n
+  const numerator = (negative ? -ticks : ticks) * BigInt(targetTimescale)
+  const denominator = BigInt(mediaTimescale)
+  const whole = numerator / denominator
+  const remainder = numerator % denominator
+  if (whole > BigInt(Number.MAX_SAFE_INTEGER)) return null
+  const value = Number(whole) + Number(remainder) / mediaTimescale
+  return Number.isFinite(value) ? (negative ? -value : value) : null
+}
+
+/** Convert exact authored presentation time and duration to an assembler's
+ * public timestamp scale. */
+export function scaleAuthoredTiming(
+  timing: AuthoredTiming,
+  targetTimescale: number,
+): { timestamp: number; duration: number } | null {
+  if (!Number.isSafeInteger(timing.durationTicks) || timing.durationTicks <= 0) return null
+  const timestamp = scaleAuthoredTicks(
+    timing.presentationTime,
+    timing.mediaTimescale,
+    targetTimescale,
+  )
+  const duration = scaleAuthoredTicks(
+    BigInt(timing.durationTicks),
+    timing.mediaTimescale,
+    targetTimescale,
+  )
+  if (timestamp === null || duration === null || duration <= 0) return null
+  return { timestamp, duration }
+}