@blockcast/mmt-render 0.1.0-main.02dfe3276f87

package/dist/audio/index.js

@@ -0,0 +1,592 @@
+// src/audio/audio-ring-buffer.ts
+var AudioRingBuffer = class {
+  #buffer;
+  #writeIndex = 0;
+  #readIndex = 0;
+  #stalled;
+  #startupFrames;
+  #resumeFrames;
+  #resumeFollowsStartup;
+  #hasStarted;
+  #capacityHeadroomFrames;
+  #timestampAnchors = [];
+  #diagEnabled;
+  #diagReads = 0;
+  #diagFillSum = 0;
+  #diagOverflowSamples = 0;
+  constructor(config) {
+    if (!Number.isInteger(config.channels) || config.channels <= 0) {
+      throw new Error("invalid channels");
+    }
+    if (!Number.isFinite(config.rate) || config.rate <= 0) {
+      throw new Error("invalid sample rate");
+    }
+    if (!Number.isFinite(config.latencyMs) || config.latencyMs <= 0) {
+      throw new Error("invalid latency");
+    }
+    const latencyFrames = Math.ceil(config.rate * (config.latencyMs / 1e3));
+    const startupFrames = config.startupFrames ?? latencyFrames;
+    const resumeFrames = config.resumeFrames ?? startupFrames;
+    const thresholdFrames = Math.max(startupFrames, resumeFrames);
+    const capacityFrames = config.capacityFrames ?? Math.max(latencyFrames, thresholdFrames);
+    if (!Number.isSafeInteger(startupFrames) || startupFrames <= 0) {
+      throw new Error("invalid startup frames");
+    }
+    if (!Number.isSafeInteger(resumeFrames) || resumeFrames <= 0) {
+      throw new Error("invalid resume frames");
+    }
+    if (!Number.isSafeInteger(capacityFrames) || capacityFrames < thresholdFrames) {
+      throw new Error("invalid capacity frames");
+    }
+    this.channels = config.channels;
+    this.rate = config.rate;
+    this.#startupFrames = startupFrames;
+    this.#resumeFrames = resumeFrames;
+    this.#resumeFollowsStartup = config.resumeFrames === void 0;
+    this.#hasStarted = config.startUnstalled ?? false;
+    this.#capacityHeadroomFrames = capacityFrames - thresholdFrames;
+    this.#stalled = !(config.startUnstalled ?? false);
+    this.#diagEnabled = config.diag ?? false;
+    this.#buffer = Array.from(
+      { length: config.channels },
+      () => new Float32Array(capacityFrames)
+    );
+  }
+  get stalled() {
+    return this.#stalled;
+  }
+  get startupFrames() {
+    return this.#startupFrames;
+  }
+  get capacity() {
+    return this.#buffer[0].length;
+  }
+  get length() {
+    return this.#writeIndex - this.#readIndex;
+  }
+  /** Timestamp of the next media sample after the PCM already emitted. */
+  get timestampUs() {
+    const anchor = this.#timestampAnchors[0];
+    if (!anchor || anchor.sampleIndex > this.#readIndex) return void 0;
+    return anchor.timestampUs + (this.#readIndex - anchor.sampleIndex) / this.rate * 1e6;
+  }
+  write(timestampUs, data) {
+    if (data.length !== this.channels) throw new Error("wrong channel count");
+    if (!Number.isFinite(timestampUs)) throw new Error("invalid timestamp");
+    const samples = data[0].length;
+    if (samples === 0) return;
+    if (data.some((channel) => channel.length !== samples)) {
+      throw new Error("mismatched channel lengths");
+    }
+    const start = this.#writeIndex;
+    const end = start + samples;
+    this.#timestampAnchors.push({ sampleIndex: start, timestampUs });
+    const overflow = end - this.#readIndex - this.capacity;
+    if (overflow > 0) {
+      this.#stalled = false;
+      this.#hasStarted = true;
+      this.#readIndex += overflow;
+      if (this.#diagEnabled) this.#diagOverflowSamples += overflow;
+      this.#pruneTimestampAnchors();
+    }
+    const refillFrames = this.#hasStarted ? this.#resumeFrames : this.#startupFrames;
+    if (this.#stalled && end - this.#readIndex >= refillFrames) {
+      this.#stalled = false;
+      this.#hasStarted = true;
+    }
+    for (let channel = 0; channel < this.channels; channel++) {
+      const src = data[channel];
+      const dst = this.#buffer[channel];
+      for (let i = 0; i < samples; i++) {
+        dst[(start + i) % dst.length] = src[i];
+      }
+    }
+    this.#writeIndex = end;
+  }
+  read(output) {
+    if (output.length !== this.channels) throw new Error("wrong channel count");
+    if (this.#stalled) return 0;
+    const available = this.length;
+    if (available === 0) {
+      this.#stalled = true;
+      return 0;
+    }
+    const requested = output[0].length;
+    const readSamples = Math.min(available, requested);
+    for (let channel = 0; channel < this.channels; channel++) {
+      const dst = output[channel];
+      const src = this.#buffer[channel];
+      for (let i = 0; i < readSamples; i++) {
+        dst[i] = src[(this.#readIndex + i) % src.length];
+      }
+      for (let i = readSamples; i < requested; i++) dst[i] = 0;
+    }
+    this.#readIndex += readSamples;
+    this.#pruneTimestampAnchors();
+    if (readSamples < requested) this.#stalled = true;
+    if (this.#diagEnabled) {
+      this.#diagReads++;
+      this.#diagFillSum += available;
+    }
+    return readSamples;
+  }
+  /** Clear queued PCM; optionally treat the next fill as post-start recovery. */
+  reset(startUnstalled = false, resumeAfterReset = false) {
+    this.#writeIndex = 0;
+    this.#readIndex = 0;
+    this.#stalled = !startUnstalled;
+    this.#hasStarted = startUnstalled || resumeAfterReset;
+    this.#timestampAnchors = [];
+    this.#diagReads = 0;
+    this.#diagFillSum = 0;
+    this.#diagOverflowSamples = 0;
+  }
+  /**
+   * Change the startup latency while preserving the configured storage
+   * headroom above its buffering thresholds. Active playout keeps draining
+   * retained PCM; a stalled buffer waits for its startup or resume threshold.
+   */
+  resize(latencyMs) {
+    if (!Number.isFinite(latencyMs) || latencyMs <= 0) {
+      throw new Error("invalid latency");
+    }
+    const newStartupFrames = Math.ceil(this.rate * (latencyMs / 1e3));
+    if (!Number.isSafeInteger(newStartupFrames) || newStartupFrames <= 0) {
+      throw new Error("invalid latency");
+    }
+    const newResumeFrames = this.#resumeFollowsStartup ? newStartupFrames : this.#resumeFrames;
+    const newCapacity = Math.max(newStartupFrames, newResumeFrames) + this.#capacityHeadroomFrames;
+    if (!Number.isSafeInteger(newCapacity) || newCapacity < Math.max(newStartupFrames, newResumeFrames)) {
+      throw new Error("invalid capacity frames");
+    }
+    const wasStalled = this.#stalled;
+    this.#startupFrames = newStartupFrames;
+    this.#resumeFrames = newResumeFrames;
+    if (newCapacity === this.capacity) {
+      if (wasStalled && this.length >= this.#refillFrames()) {
+        this.#stalled = false;
+        this.#hasStarted = true;
+      }
+      return;
+    }
+    const next = Array.from(
+      { length: this.channels },
+      () => new Float32Array(newCapacity)
+    );
+    const samplesToKeep = Math.min(this.length, newCapacity);
+    const copyStart = this.#writeIndex - samplesToKeep;
+    for (let channel = 0; channel < this.channels; channel++) {
+      const src = this.#buffer[channel];
+      const dst = next[channel];
+      for (let i = 0; i < samplesToKeep; i++) {
+        const sampleIndex = copyStart + i;
+        dst[sampleIndex % dst.length] = src[sampleIndex % src.length];
+      }
+    }
+    this.#buffer = next;
+    this.#readIndex = copyStart;
+    this.#pruneTimestampAnchors();
+    this.#stalled = samplesToKeep === 0 || wasStalled && samplesToKeep < this.#refillFrames();
+    if (!this.#stalled) this.#hasStarted = true;
+  }
+  getDiagAndReset() {
+    if (!this.#diagEnabled || this.#diagReads === 0) return null;
+    const result = {
+      reads: this.#diagReads,
+      avgFill: Math.round(this.#diagFillSum / this.#diagReads),
+      capacity: this.capacity,
+      skips: 0,
+      dups: 0,
+      overflowSamples: this.#diagOverflowSamples
+    };
+    this.#diagReads = 0;
+    this.#diagFillSum = 0;
+    this.#diagOverflowSamples = 0;
+    return result;
+  }
+  #pruneTimestampAnchors() {
+    let keep = 0;
+    while (keep + 1 < this.#timestampAnchors.length && this.#timestampAnchors[keep + 1].sampleIndex <= this.#readIndex) {
+      keep++;
+    }
+    if (keep > 0) this.#timestampAnchors.splice(0, keep);
+  }
+  #refillFrames() {
+    return this.#hasStarted ? this.#resumeFrames : this.#startupFrames;
+  }
+};
+
+// src/audio/audio-buffer-plan.ts
+function positive(value, label) {
+  if (!Number.isFinite(value) || value <= 0) throw new Error(`invalid ${label}`);
+  return value;
+}
+function deriveAudioBurstBufferPlan(input) {
+  const sampleRate = positive(input.sampleRate, "sample rate");
+  const chunkFrames = positive(input.chunkFrames, "audio chunk size");
+  const groupDurationMs = positive(input.groupDurationMs, "audio group duration");
+  if (!Number.isInteger(chunkFrames)) throw new Error("invalid audio chunk size");
+  const chunkDurationMs = 1e3 * chunkFrames / sampleRate;
+  const groupChunks = Math.max(1, Math.round(groupDurationMs / chunkDurationMs));
+  const deliveryWindowChunks = input.deliveryWindowMs === void 0 ? 0 : Math.max(
+    1,
+    Math.ceil(positive(input.deliveryWindowMs, "audio delivery window") / chunkDurationMs)
+  );
+  const deliveryChunks = Math.max(groupChunks, deliveryWindowChunks);
+  const deliveryFrames = deliveryChunks * chunkFrames;
+  const capacityFrames = deliveryFrames + deliveryFrames;
+  if (!Number.isSafeInteger(deliveryFrames) || !Number.isSafeInteger(capacityFrames)) {
+    throw new Error("audio buffer frame count exceeds safe integer range");
+  }
+  return {
+    startupFrames: deliveryFrames,
+    capacityFrames,
+    deliveryFrames
+  };
+}
+
+// src/audio/audio-render-pipeline.ts
+import { MmtpDecodePipeline } from "@blockcast/mmt-container/mmtp-decode-pipeline";
+
+// src/pacing/frame-pacer.ts
+var FrameCountPacer = class {
+  #frameCount = 0;
+  #anchorWallMs = 0;
+  #anchored = false;
+  constructor(opts) {
+    if (!(opts.frameDurationMs > 0)) {
+      throw new Error("frameDurationMs must be > 0");
+    }
+    this.frameDurationMs = opts.frameDurationMs;
+    this.thresholdMs = opts.mapper.pacingThresholdMs;
+    this.warmupFrames = Math.max(0, opts.warmupFrames ?? 0);
+  }
+  /** Call on every emitted decoded frame (AU or picture). Anchors on first call. */
+  notifyFrame() {
+    if (!this.#anchored) {
+      this.#anchorWallMs = now();
+      this.#anchored = true;
+    }
+    this.#frameCount++;
+  }
+  /**
+   * Compute sleep ms before reading the next MoQ object.
+   * Returns 0 when:
+   *   - pacing is disabled (NullBlockMapper → threshold=0)
+   *   - the anchor is not yet set
+   *   - still in warmup
+   *   - the caller reports a standing backlog (see `observedDelayMs`)
+   *   - decoder is not ahead of wall clock by more than threshold
+   * Otherwise returns aheadMs - thresholdMs/2 (leaves half the threshold as headroom).
+   *
+   * `observedDelayMs` is how far this frame is behind the producer's own clock,
+   * measured by the caller against a producer-supplied sending instant (for
+   * MMTP, the header send-wall timestamp). It is optional because the anchored
+   * rate below is blind to it: `#anchorWallMs` is the wall time of the FIRST
+   * frame read, so `aheadMs` measures consumption against the join instant and
+   * not against the producer. Once `aheadMs` reaches the threshold the loop
+   * consumes at exactly the source rate, and recovering latency present at join
+   * requires consuming FASTER than the source rate. So without this argument a
+   * consumer that joined a live stream mid-block keeps that join latency for the
+   * life of the subscription.
+   *
+   * A caller that can measure the real distance from the producer passes it and
+   * gets a drain: while the backlog exceeds the threshold there is nothing to
+   * pace against, so return 0 and let the transport set the rate. At the live
+   * edge the anchored-rate behavior below applies unchanged.
+   *
+   * Callers with no producer clock omit it and keep the pure ATSC3-style
+   * anchored pacing (see the class doc), where a first-frame anchor is correct
+   * because a broadcast push has no live edge to catch up to.
+   */
+  computeSleepMs(observedDelayMs) {
+    if (this.thresholdMs <= 0) return 0;
+    if (!this.#anchored) return 0;
+    if (this.#frameCount <= this.warmupFrames) return 0;
+    if (observedDelayMs !== void 0 && Number.isFinite(observedDelayMs) && observedDelayMs > this.thresholdMs) {
+      return 0;
+    }
+    const mediaMs = this.#frameCount * this.frameDurationMs;
+    const wallMs = now() - this.#anchorWallMs;
+    const aheadMs = mediaMs - wallMs;
+    if (aheadMs <= this.thresholdMs) return 0;
+    return aheadMs - this.thresholdMs / 2;
+  }
+  /** Reset anchor + counter. Call on source switch (MoQ ↔ multicast). */
+  reset() {
+    this.#frameCount = 0;
+    this.#anchorWallMs = 0;
+    this.#anchored = false;
+  }
+  get snapshot() {
+    const mediaMs = this.#frameCount * this.frameDurationMs;
+    const wallMs = this.#anchored ? now() - this.#anchorWallMs : 0;
+    return {
+      frameCount: this.#frameCount,
+      mediaMs,
+      wallMs,
+      aheadMs: mediaMs - wallMs,
+      thresholdMs: this.thresholdMs,
+      anchored: this.#anchored
+    };
+  }
+};
+function now() {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+
+// src/pacing/au-duration.ts
+function auDurationMsFromCodec(codec, sampleRate) {
+  if (!(sampleRate > 0)) throw new Error("sampleRate must be > 0");
+  if (codec.startsWith("opus") || codec.startsWith("Opus")) {
+    return 960 / sampleRate * 1e3;
+  }
+  if (codec.startsWith("mp4a") || codec.startsWith("AAC") || codec.startsWith("aac")) {
+    return 1024 / sampleRate * 1e3;
+  }
+  if (codec.startsWith("flac") || codec.startsWith("fLaC")) {
+    return 4096 / sampleRate * 1e3;
+  }
+  throw new Error(`unknown audio codec for AU duration derivation: ${codec}`);
+}
+
+// src/audio/worklet-url.ts
+function workletModuleUrl() {
+  const base = new URL("../worklet/render-worklet.js", import.meta.url);
+  return base.href;
+}
+var WORKLET_PROCESSOR_NAME = "mmt-render";
+
+// src/audio/audio-render-pipeline.ts
+var AudioRenderPipeline = class {
+  #context;
+  #pacer;
+  #mapper;
+  #codec;
+  #packetId;
+  #sampleRate;
+  #channels;
+  #description;
+  #latencyMs;
+  #startupFrames;
+  #startupThresholdFrames;
+  #capacityFrames;
+  #diag;
+  #warmupFrames;
+  #onState;
+  #onDiag;
+  #onError;
+  #reassemblyPolicy;
+  #decoder = null;
+  #pipeline = null;
+  #worklet = null;
+  #fecClient;
+  #closed = false;
+  #readyPromise = null;
+  #workletGeneration = 0;
+  #startupReleased = false;
+  constructor(opts) {
+    this.#context = opts.context;
+    this.#mapper = opts.mapper;
+    this.#codec = opts.codec;
+    this.#packetId = opts.packetId;
+    this.#sampleRate = opts.sampleRate;
+    this.#channels = opts.channels;
+    this.#description = opts.description;
+    this.#latencyMs = opts.latencyMs;
+    this.#startupFrames = opts.startupFrames;
+    this.#startupThresholdFrames = opts.startupFrames ?? Math.ceil(opts.sampleRate * (opts.latencyMs / 1e3));
+    this.#capacityFrames = opts.capacityFrames;
+    this.#diag = opts.diag ?? false;
+    this.#warmupFrames = opts.warmupFrames ?? 0;
+    this.#onState = opts.onState;
+    this.#onDiag = opts.onDiag;
+    this.#onError = opts.onError;
+    this.#fecClient = opts.fecClient;
+    this.#reassemblyPolicy = opts.reassemblyPolicy;
+    const auDurationMs = auDurationMsFromCodec(opts.codec, opts.sampleRate);
+    this.#pacer = new FrameCountPacer({
+      frameDurationMs: auDurationMs,
+      mapper: opts.mapper,
+      warmupFrames: this.#warmupFrames
+    });
+  }
+  /** Load worklet module + create decoder + pipeline. Call once. */
+  async ready() {
+    if (this.#readyPromise) return this.#readyPromise;
+    this.#readyPromise = this.#initialize();
+    return this.#readyPromise;
+  }
+  async #initialize() {
+    await this.#context.audioWorklet.addModule(workletModuleUrl());
+    const worklet = new AudioWorkletNode(this.#context, WORKLET_PROCESSOR_NAME, {
+      numberOfInputs: 0,
+      numberOfOutputs: 1,
+      outputChannelCount: [this.#channels]
+    });
+    const initMsg = {
+      type: "init",
+      generation: ++this.#workletGeneration,
+      channels: this.#channels,
+      rate: this.#sampleRate,
+      latencyMs: this.#latencyMs,
+      startupFrames: this.#startupFrames,
+      capacityFrames: this.#capacityFrames,
+      holdUntilStart: true,
+      diag: this.#diag
+    };
+    worklet.port.postMessage(initMsg);
+    worklet.port.onmessage = (ev) => {
+      const m = ev.data;
+      if (m.type === "state") {
+        if (m.generation !== this.#workletGeneration) return;
+        this.#onState?.({
+          timestampUs: m.timestamp,
+          stalled: m.stalled,
+          bufferedFrames: m.bufferedFrames,
+          writtenFrames: m.writtenFrames
+        });
+      } else if (m.type === "ringBufDiag") {
+        if (m.generation !== this.#workletGeneration) return;
+        this.#onDiag?.({
+          reads: m.reads,
+          avgFill: m.avgFill,
+          capacity: m.capacity,
+          skipsPerSec: m.skipsPerSec,
+          dupsPerSec: m.dupsPerSec,
+          overflowSamplesPerSec: m.overflowSamplesPerSec,
+          underflowSamplesPerSec: m.underflowSamplesPerSec
+        });
+      } else if (m.type === "writeAck") {
+        if (m.generation !== this.#workletGeneration || this.#startupReleased || m.bufferedFrames < this.#startupThresholdFrames) return;
+        this.#startupReleased = true;
+        const start = {
+          type: "start",
+          generation: this.#workletGeneration
+        };
+        worklet.port.postMessage(start);
+      }
+    };
+    this.#worklet = worklet;
+    const decoder = new AudioDecoder({
+      output: (data) => this.#onDecoded(data),
+      error: (err) => this.#onError?.(err)
+    });
+    const config = {
+      codec: this.#codec,
+      sampleRate: this.#sampleRate,
+      numberOfChannels: this.#channels,
+      ...this.#description ? { description: this.#description } : {}
+    };
+    decoder.configure(config);
+    this.#decoder = decoder;
+    const pipeline = new MmtpDecodePipeline();
+    pipeline.configure({
+      codec: this.#codec,
+      packetId: this.#packetId,
+      description: this.#description,
+      reorderWindow: 0,
+      // audio doesn't need reorder — AAC/Opus frames are self-contained
+      reassemblyPolicy: this.#reassemblyPolicy
+    });
+    if (this.#fecClient) pipeline.setFecClient(this.#fecClient);
+    pipeline.onFrame((codecData, meta) => {
+      if (!this.#decoder || this.#decoder.state !== "configured") return;
+      if (codecData.byteLength === 0) return;
+      this.#pacer.notifyFrame();
+      try {
+        this.#decoder.decode(new EncodedAudioChunk({
+          type: "key",
+          data: codecData,
+          timestamp: meta.timestamp
+        }));
+      } catch (err) {
+        this.#onError?.(err);
+      }
+    });
+    this.#pipeline = pipeline;
+  }
+  /** Feed one MoQ object (raw MMTP packet). */
+  feedMoqObject(packet) {
+    this.#pipeline?.feedMoqObject(packet);
+  }
+  /** ms to sleep before the next object read. 0 when not anchored / not ahead. */
+  paceSleepMs() {
+    return this.#pacer.computeSleepMs();
+  }
+  /** Pacer snapshot (for diagnostics / UI). */
+  get pacerSnapshot() {
+    return this.#pacer.snapshot;
+  }
+  /** Reset pacer on source switch (MoQ ↔ multicast). */
+  resetPacer() {
+    this.#pacer.reset();
+  }
+  /** Drop queued PCM and its timestamp epoch at an explicit source boundary. */
+  resetPlayout(startUnstalled = false) {
+    this.#pacer.reset();
+    this.#startupReleased = true;
+    const message = {
+      type: "reset",
+      generation: ++this.#workletGeneration,
+      startUnstalled
+    };
+    this.#worklet?.port.postMessage(message);
+  }
+  /** Node to connect to destination / gain. */
+  get rootNode() {
+    if (!this.#worklet) throw new Error("AudioRenderPipeline.ready() must resolve first");
+    return this.#worklet;
+  }
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    try {
+      this.#decoder?.close();
+    } catch {
+    }
+    try {
+      this.#pipeline?.dispose();
+    } catch {
+    }
+    try {
+      this.#worklet?.disconnect();
+    } catch {
+    }
+    this.#decoder = null;
+    this.#pipeline = null;
+    this.#worklet = null;
+  }
+  // ─── Private ─────────────────────────────────────────────────────
+  #onDecoded(sample) {
+    if (this.#closed || !this.#worklet) {
+      sample.close();
+      return;
+    }
+    const timestamp = sample.timestamp;
+    const channelData = [];
+    for (let ch = 0; ch < sample.numberOfChannels; ch++) {
+      const data = new Float32Array(sample.numberOfFrames);
+      sample.copyTo(data, { format: "f32-planar", planeIndex: ch });
+      channelData.push(data);
+    }
+    sample.close();
+    const msg = {
+      type: "data",
+      data: channelData,
+      timestamp
+    };
+    this.#worklet.port.postMessage(msg, channelData.map((d) => d.buffer));
+  }
+};
+export {
+  AudioRenderPipeline,
+  AudioRingBuffer,
+  WORKLET_PROCESSOR_NAME,
+  deriveAudioBurstBufferPlan,
+  workletModuleUrl
+};
+//# sourceMappingURL=index.js.map