@hraness/dawg 0.6.1 → 0.7.0

package/src/audio/effects/formant.ts

@@ -0,0 +1,263 @@
+/**
+ * Formant shift at constant pitch (0.7 `fx.formant`): the throat or gender
+ * knob. Per STFT frame the cepstral spectral envelope E is taken and each
+ * bin is scaled by E(k / a) / E(k), a = 2^(shift / 12), with its phase left
+ * untouched, then the frames overlap-add. The pitch never moves, so no
+ * phase vocoder is needed (Röbel and Rodet, "Efficient spectral envelope
+ * estimation and its application to pitch shifting and envelope
+ * preservation", DAFx 2005; Little AlterBoy and VocalSynth's formant knob).
+ *
+ * The lifter adapts to the voice: 0.75 periods of a 5-frame median
+ * autocorrelation f0, clamped to 1-2 ms, 1 ms when unvoiced. A fixed 2 ms
+ * lifter resolves single harmonics above about 500 Hz and makes high
+ * voices worse than no processing (design formant.md section 2).
+ *
+ * Frames sit at multiples of the hop in absolute track samples (an
+ * arranged window passes its origin as `seedSeconds`), and a window padded
+ * back by `FORMANT_PAD` samples and forward by one frame equals the same
+ * span of a full render bit for bit.
+ */
+import type { FxValues } from "../../../core/fx.ts";
+import type { Track } from "../../../core/score.ts";
+import { cepstralEnvelope, envelopeScratch } from "../dsp/envelope.ts";
+import { fftInPlace } from "../dsp/fft.ts";
+import { hann, HANN_SQUARED_OLA_QUARTER } from "../dsp/stft.ts";
+import { fxReader, type EffectContext } from "./common.ts";
+
+/** Per-bin gain clamp (24 dB), as shift.ts holds formants. */
+const MAX_GAIN = 10 ** (24 / 20);
+/** Lifter periods and clamps (design formant.md section 2). */
+const LIFTER_PERIODS = 0.75;
+const LIFTER_MIN_SECONDS = 0.001;
+const LIFTER_MAX_SECONDS = 0.002;
+/** Frames in the f0 median (this one and the four before it). */
+const F0_MEDIAN = 5;
+const F0_MIN_HZ = 60;
+const F0_MAX_HZ = 1500;
+/** Below this normalized autocorrelation a frame counts as unvoiced. */
+const VOICED = 0.45;
+/** The first peak within this fraction of the best is the period. */
+const FIRST_PEAK = 0.85;
+
+/** Frame length: 1024 at or below 24 kHz, 2048 above. */
+export function formantFrame(sampleRate: number): number {
+  return sampleRate > 24_000 ? 2048 : 1024;
+}
+
+/**
+ * Samples a window render must start before its first output sample (4
+ * hops for the f0 median plus one frame), and it renders one frame past
+ * its last.
+ */
+export function formantPad(sampleRate: number): number {
+  const n = formantFrame(sampleRate);
+  return n + 4 * (n / 4);
+}
+
+export type FormantShiftOptions = Readonly<{
+  /** Wet amount 0..1 (1: fully shifted). */
+  mix?: number | ((index: number) => number);
+  /** Absolute track sample of `x[0]`; frames anchor at hop multiples of it. */
+  origin?: number;
+}>;
+
+type Analysis = {
+  n: number;
+  hop: number;
+  win: Float64Array;
+  wac: Float64Array;
+  minLag: number;
+  maxLag: number;
+};
+
+const analyses = new Map<number, Analysis>();
+
+function analysisFor(sampleRate: number): Analysis {
+  let a = analyses.get(sampleRate);
+  if (a) return a;
+  const n = formantFrame(sampleRate);
+  const win = hann(n);
+  const minLag = Math.floor(sampleRate / F0_MAX_HZ);
+  const maxLag = Math.min(n / 2 - 1, Math.ceil(sampleRate / F0_MIN_HZ));
+  // The window's own autocorrelation, divided out so long lags are not
+  // biased down (Boersma 1993).
+  const wac = new Float64Array(maxLag + 1);
+  for (let t = 0; t <= maxLag; t += 1) {
+    let sum = 0;
+    for (let i = 0; i + t < n; i += 1) sum += win[i]! * win[i + t]!;
+    wac[t] = sum;
+  }
+  a = { n, hop: n / 4, win, wac, minLag, maxLag };
+  analyses.set(sampleRate, a);
+  return a;
+}
+
+/** One frame's f0 from its power spectrum (0: unvoiced). */
+function frameF0(
+  mag: Float64Array,
+  a: Analysis,
+  sampleRate: number,
+  re: Float64Array,
+  im: Float64Array,
+): number {
+  const { n, wac, minLag, maxLag } = a;
+  const half = n / 2;
+  for (let k = 0; k <= half; k += 1) {
+    re[k] = mag[k]! * mag[k]!;
+    im[k] = 0;
+    if (k > 0 && k < half) {
+      re[n - k] = re[k]!;
+      im[n - k] = 0;
+    }
+  }
+  fftInPlace(re, im, true);
+  const r0 = re[0]!;
+  if (r0 <= 1e-12) return 0;
+  const w0 = wac[0]! / r0;
+  for (let t = minLag - 1; t <= maxLag; t += 1) re[t] = (re[t]! * w0) / wac[t]!;
+  let best = 0;
+  for (let t = minLag; t <= maxLag; t += 1) best = Math.max(best, re[t]!);
+  if (best < VOICED) return 0;
+  for (let t = minLag + 1; t < maxLag; t += 1) {
+    const v = re[t]!;
+    if (v >= FIRST_PEAK * best && v >= re[t - 1]! && v >= re[t + 1]!) {
+      const l = re[t - 1]!;
+      const r = re[t + 1]!;
+      const d = l - 2 * v + r;
+      const offset = d < 0 ? (0.5 * (l - r)) / d : 0;
+      return sampleRate / (t + offset);
+    }
+  }
+  return 0;
+}
+
+/**
+ * Shift the formants of `x` by `shift` semitones (a number, or a function
+ * of the buffer index read once per hop) at constant pitch. Returns a new
+ * buffer; `shift` 0 everywhere returns a copy of `x`.
+ */
+export function formantShift(
+  x: Float64Array,
+  sampleRate: number,
+  shift: number | ((index: number) => number),
+  options: FormantShiftOptions = {},
+): Float64Array {
+  if (shift === 0) return Float64Array.from(x);
+  const a = analysisFor(sampleRate);
+  const { n, hop, win } = a;
+  const half = n / 2;
+  const origin = Math.round(options.origin ?? 0);
+  const out = new Float64Array(x.length);
+  const re = new Float64Array(n);
+  const im = new Float64Array(n);
+  const acRe = new Float64Array(n);
+  const acIm = new Float64Array(n);
+  const mag = new Float64Array(half + 1);
+  const env = new Float64Array(half + 1);
+  const scratch = envelopeScratch(n);
+  const history = new Float64Array(F0_MEDIAN);
+  const sorted = new Float64Array(F0_MEDIAN);
+  let frames = 0;
+  const ola = 1 / HANN_SQUARED_OLA_QUARTER;
+  const auto = typeof shift === "function";
+  // First frame: the latest hop multiple (absolute) whose frame still
+  // reaches x[0].
+  const firstAbs = Math.floor((origin - n + 1 + (hop - 1)) / hop) * hop;
+  for (let start = firstAbs - origin; start < x.length; start += hop) {
+    const st = auto ? shift(Math.max(0, start + half)) : shift;
+    for (let i = 0; i < n; i += 1) {
+      const j = start + i;
+      re[i] = j >= 0 && j < x.length ? x[j]! * win[i]! : 0;
+      im[i] = 0;
+    }
+    fftInPlace(re, im);
+    for (let k = 0; k <= half; k += 1) mag[k] = Math.hypot(re[k]!, im[k]!);
+    // Every frame joins the f0 history, so a window and the full render
+    // agree whatever the shift was.
+    history[frames % F0_MEDIAN] = frameF0(mag, a, sampleRate, acRe, acIm);
+    frames += 1;
+    if (st === 0) {
+      fftInPlace(re, im, true);
+    } else {
+      const m = Math.min(frames, F0_MEDIAN);
+      for (let i = 0; i < m; i += 1) sorted[i] = history[i]!;
+      for (let i = 1; i < m; i += 1)
+        for (let j = i; j > 0 && sorted[j - 1]! > sorted[j]!; j -= 1) {
+          const tmp = sorted[j]!;
+          sorted[j] = sorted[j - 1]!;
+          sorted[j - 1] = tmp;
+        }
+      const f0 = sorted[m >> 1]!;
+      const seconds =
+        f0 > 0
+          ? Math.min(
+              LIFTER_MAX_SECONDS,
+              Math.max(LIFTER_MIN_SECONDS, LIFTER_PERIODS / f0),
+            )
+          : LIFTER_MIN_SECONDS;
+      const lifter = Math.max(4, Math.round(seconds * sampleRate));
+      cepstralEnvelope(mag, n, lifter, env, scratch);
+      const ratio = 2 ** (-st / 12);
+      for (let k = 0; k <= half; k += 1) {
+        const source = k * ratio;
+        const i0 = Math.floor(source);
+        const f = source - i0;
+        const e =
+          i0 >= half
+            ? env[half]!
+            : env[i0]! + (env[Math.min(half, i0 + 1)]! - env[i0]!) * f;
+        const g = Math.min(
+          MAX_GAIN,
+          Math.max(1 / MAX_GAIN, e / Math.max(env[k]!, 1e-12)),
+        );
+        re[k] = re[k]! * g;
+        im[k] = im[k]! * g;
+        if (k > 0 && k < half) {
+          re[n - k] = re[k]!;
+          im[n - k] = -im[k]!;
+        }
+      }
+      fftInPlace(re, im, true);
+    }
+    for (let i = 0; i < n; i += 1) {
+      const j = start + i;
+      if (j >= 0 && j < x.length)
+        out[j] = out[j]! + (re[i]! / n) * win[i]! * ola;
+    }
+  }
+  const mix = options.mix ?? 1;
+  if (typeof mix === "function")
+    for (let i = 0; i < x.length; i += 1)
+      out[i] = x[i]! + (out[i]! - x[i]!) * mix(i);
+  else if (mix < 1)
+    for (let i = 0; i < x.length; i += 1)
+      out[i] = x[i]! + (out[i]! - x[i]!) * mix;
+  return out;
+}
+
+/** `fx.formant`: formant shift with mix, both automatable. */
+export function applyFormant(
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "formant", values, context);
+  const shift = read.param("shift");
+  const mix = read.param("mix");
+  if (!shift.automated && shift.fallback === 0) return;
+  if (!mix.automated && mix.fallback <= 0) return;
+  const origin = context.seedSeconds
+    ? Math.round(context.seedSeconds * context.sampleRate)
+    : 0;
+  const out = formantShift(
+    buffer,
+    context.sampleRate,
+    shift.automated ? (index) => shift.at(index) : shift.fallback,
+    {
+      origin,
+      mix: mix.automated ? (index) => mix.at(index) : mix.fallback,
+    },
+  );
+  buffer.set(out);
+}

package/src/audio/engine.ts

@@ -16,6 +16,14 @@ import { levelOf, type SoundLevel } from "./preview.ts";
 import { DEFAULT_SAMPLE_RATE, RENDER_CHANNELS } from "./wav.ts";
 import { playbackTime } from "./arrange.ts";
 import { transportMapFor, type TransportMap } from "./clock.ts";
+import {
+  openNativePlayer,
+  probeNativeSink,
+  type AudioTiming,
+  type NativeProbe,
+  type PlayerClock,
+  type SinkLibrary,
+} from "./native.ts";
 
 /**
  * How dawgd (or a file-mode window) makes sound.
@@ -30,7 +38,8 @@ import { transportMapFor, type TransportMap } from "./clock.ts";
  *   s16le from stdin; tests use it to record the exact byte stream.
  * - `none` makes no sound; the transport clock still runs.
  */
-export type AudioBackend = "ffplay" | "sox" | "afplay" | "command" | "none";
+export type AudioBackend =
+  "native" | "ffplay" | "sox" | "afplay" | "command" | "none";
 
 export type AudioBackendInfo = Readonly<{
   backend: AudioBackend;
@@ -40,6 +49,10 @@ export type AudioBackendInfo = Readonly<{
   command?: readonly string[];
   /** Human-readable reason the backend was chosen. */
   detail: string;
+  /** The loaded sink, for the `native` backend. */
+  native?: SinkLibrary;
+  /** Why the native sink is not in use, when another backend was picked. */
+  nativeUnavailable?: string;
 }>;
 
 type Which = (binary: string) => string | null;
@@ -49,8 +62,17 @@ export type DetectOptions = Readonly<{
   which?: Which;
   platform?: NodeJS.Platform;
   sampleRate?: number;
+  /** Native sink probe; `false` skips it (tests). Default: the real one. */
+  native?: (() => NativeProbe) | false;
 }>;
 
+let cachedProbe: NativeProbe | undefined;
+/** The real probe, once per process (dlopen is not repeated). */
+function defaultNativeProbe(): NativeProbe {
+  cachedProbe ??= probeNativeSink();
+  return cachedProbe;
+}
+
 /** Streaming argv for the known stdin players. */
 export function streamingCommand(
   backend: "ffplay" | "sox",
@@ -99,8 +121,9 @@ export function streamingCommand(
 
 /**
  * Pick the audio backend. Order: DAWG_AUDIO=0 (none), DAWG_AUDIO_PLAYER
- * (explicit stdin command), DAWG_AUDIO_BACKEND (forced name), then ffplay,
- * sox `play`, and afplay (macOS) in that order.
+ * (explicit stdin command), DAWG_AUDIO_BACKEND (forced name), then the
+ * native sink, ffplay, sox `play`, and afplay (macOS) in that order. When
+ * the native sink cannot load, the fallback's detail says why.
  */
 export function detectAudioBackend(
   options: DetectOptions = {},
@@ -128,13 +151,40 @@ export function detectAudioBackend(
   }
   const forced = env.DAWG_AUDIO_BACKEND?.trim().toLowerCase();
   const candidates: AudioBackend[] =
+    forced === "native" ||
     forced === "ffplay" ||
     forced === "sox" ||
     forced === "afplay" ||
     forced === "none"
       ? [forced]
-      : ["ffplay", "sox", "afplay"];
+      : ["native", "ffplay", "sox", "afplay"];
+  let unavailable: string | undefined;
+  const why = (info: AudioBackendInfo): AudioBackendInfo =>
+    unavailable
+      ? {
+          ...info,
+          detail: `${info.detail} · native sink unavailable: ${unavailable}`,
+          nativeUnavailable: unavailable,
+        }
+      : info;
   for (const candidate of candidates) {
+    if (candidate === "native") {
+      if (options.native === false) continue;
+      const probe = options.native
+        ? options.native()
+        : env === process.env && options.platform === undefined
+          ? defaultNativeProbe()
+          : probeNativeSink({ env, platform });
+      if (probe.ok)
+        return {
+          backend: "native",
+          streaming: true,
+          native: probe.library,
+          detail: `native sink ${probe.detail} (device callback)`,
+        };
+      unavailable = probe.reason;
+      continue;
+    }
     if (candidate === "none")
       return {
         backend: "none",
@@ -144,26 +194,26 @@ export function detectAudioBackend(
     if (candidate === "ffplay" || candidate === "sox") {
       const binary = which(candidate === "ffplay" ? "ffplay" : "play");
       if (!binary) continue;
-      return {
+      return why({
         backend: candidate,
         streaming: true,
         command: streamingCommand(candidate, binary, sampleRate),
         detail: `${binary} (gapless stream)`,
-      };
+      });
     }
     const binary = platform === "darwin" ? which("afplay") : null;
     if (binary)
-      return {
+      return why({
         backend: "afplay",
         streaming: false,
         detail: `${binary} (re-render on edit; install ffmpeg or sox for gapless playback)`,
-      };
+      });
   }
-  return {
+  return why({
     backend: "none",
     streaming: false,
     detail: "no player found (install ffmpeg or sox)",
-  };
+  });
 }
 
 /** One status line for `dawg auth status` and the header. */
@@ -205,8 +255,21 @@ type PlayerProcess = {
   readonly stdin: Sink;
   readonly exited: Promise<number>;
   kill(): void;
+  /** Device-clocked players (the native sink) pace the pump themselves. */
+  readonly clock?: PlayerClock;
 };
 
+/** Play-mode lead on the native sink: the ring only covers pump jitter. */
+export const NATIVE_PLAY_LEAD_MS = 15;
+/** Pump interval on the native sink. */
+export const NATIVE_TICK_MS = 5;
+
+function envNumber(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === "") return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
+
 export type AudioEngineOptions = Readonly<{
   lockPath?: string;
   info?: AudioBackendInfo;
@@ -228,6 +291,12 @@ export type AudioEngineOptions = Readonly<{
   respawnMs?: number;
   /** Player lifecycle notices worth a status line. */
   onStatus?: (status: AudioStatus) => void;
+  /** Play-mode lead (default 60 ms; 15 ms on the native sink). */
+  playLeadMs?: number;
+  /** Native sink output device name (default: system default). */
+  device?: string;
+  /** Native sink device buffer frames (default 128; 0 = device default). */
+  bufferFrames?: number;
 }>;
 
 export type AudioStatus = Readonly<{
@@ -240,7 +309,13 @@ export type AudioStatus = Readonly<{
 const MAX_RESPAWNS = 3;
 /** A player that ran this long before dying resets the respawn budget. */
 const RESPAWN_RESET_MS = 10_000;
-/** Lead grows to this multiple of the last render time. */
+/**
+ * Default queue lead: the edit-to-audible floor while playing. 100 ms leaves
+ * 80 ms of slack over the 20 ms pump tick for main-thread stalls (a frame
+ * costs about 1 ms; play mode already runs at 60 ms).
+ */
+const DEFAULT_LEAD_MS = 100;
+/** Inline renders grow the lead to this multiple of the last render time. */
 const LEAD_RENDER_FACTOR = 1.5;
 
 type Loop = Readonly<{
@@ -334,8 +409,8 @@ type PlayRequest = {
  *
  * Timing: the engine is paced by the same monotonic clock as the transport.
  * Frame `n` of the stream belongs to wall time `start + n / rate`, and the
- * engine keeps a lead of audio queued ahead of now: at least `leadMs`, and
- * 1.5x the last render time when renders are slower than that. The device
+ * engine keeps a lead of audio queued ahead of now: `leadMs`, or 1.5x the
+ * last render time when renders run inline (no worker) and are slower. The device
  * plays the queue at its own rate, so what you hear trails the transport by
  * the player's fixed output latency and never accumulates drift from
  * re-renders. Renders run in a worker; an edit re-renders off-thread and
@@ -351,6 +426,8 @@ export class AudioEngine {
   private leadFrames: number;
   private readonly defaultLeadFrames: number;
   private readonly tickMs: number;
+  /** The lead play mode and auditions pin (see `setLeadMs`). */
+  public readonly playLeadMs: number;
   private readonly now: () => number;
   private readonly useTimer: boolean;
   private readonly spawnPlayer: (command: readonly string[]) => PlayerProcess;
@@ -401,17 +478,37 @@ export class AudioEngine {
       options.info ?? detectAudioBackend({ sampleRate: this.sampleRate });
     this.lock = new PlaybackLock(options.lockPath);
     this.leadFrames = Math.round(
-      ((options.leadMs ?? 200) * this.sampleRate) / 1000,
+      ((options.leadMs ?? DEFAULT_LEAD_MS) * this.sampleRate) / 1000,
     );
     this.defaultLeadFrames = this.leadFrames;
     this.fadeFrames = Math.max(
       1,
       Math.round(SWAP_FADE_SECONDS * this.sampleRate),
     );
-    this.tickMs = options.tickMs ?? 20;
+    const native =
+      this.info.backend === "native" ? this.info.native : undefined;
+    this.tickMs = options.tickMs ?? (native ? NATIVE_TICK_MS : 20);
+    this.playLeadMs =
+      options.playLeadMs ??
+      envNumber(process.env.DAWG_PLAY_LEAD_MS) ??
+      (native ? NATIVE_PLAY_LEAD_MS : 60);
     this.now = options.now ?? (() => performance.now());
     this.useTimer = options.timer ?? true;
-    this.spawnPlayer = options.spawn ?? spawnStdinPlayer;
+    const device = options.device ?? process.env.DAWG_AUDIO_DEVICE?.trim();
+    const bufferFrames =
+      options.bufferFrames ?? envNumber(process.env.DAWG_AUDIO_BUFFER) ?? 128;
+    this.spawnPlayer =
+      options.spawn ??
+      (native
+        ? () =>
+            openNativePlayer(native, {
+              rate: this.sampleRate,
+              channels: RENDER_CHANNELS,
+              ...(device ? { device } : {}),
+              bufferFrames,
+              now: this.now,
+            })
+        : spawnStdinPlayer);
     this.respawnMs = options.respawnMs ?? 250;
     this.onStatus = options.onStatus;
     this.renderer = new LoopRenderer({
@@ -452,6 +549,17 @@ export class AudioEngine {
         : Math.max(1, Math.round((ms * this.sampleRate) / 1000));
   }
 
+  /**
+   * A few words on how play mode sounds, for the play strip: the native
+   * sink, or the stdin player and why the sink is not in use.
+   */
+  public get audioNote(): string {
+    if (this.info.backend === "native") return "native sink";
+    return this.info.nativeUnavailable
+      ? `${this.info.backend} · no native sink`
+      : this.info.backend;
+  }
+
   /** Lead in milliseconds: how far ahead of now a new live voice sounds. */
   public get leadMs(): number {
     return (this.lead * 1000) / this.sampleRate;
@@ -619,14 +727,14 @@ export class AudioEngine {
 
   /** Frames kept queued ahead of the clock right now. */
   public get lead(): number {
-    // Play mode and auditions keep their short lead: renders run
-    // off-thread, so a slow render delays the swap, not the stream.
-    const adaptive =
-      (this.monitoring || this.leadPinned) && this.renderer.offThread
-        ? 0
-        : Math.round(
-            (LEAD_RENDER_FACTOR * this.lastRenderMs * this.sampleRate) / 1000,
-          );
+    // Off-thread renders never stall the pump: a slow render delays the
+    // swap, not the stream, so only inline renders grow the lead (every
+    // frame of lead is a frame of edit latency).
+    const adaptive = this.renderer.offThread
+      ? 0
+      : Math.round(
+          (LEAD_RENDER_FACTOR * this.lastRenderMs * this.sampleRate) / 1000,
+        );
     // The pump never queues more than a second, so the lead stays under it.
     return Math.min(
       Math.max(this.leadFrames, adaptive),
@@ -719,7 +827,18 @@ export class AudioEngine {
     );
   }
 
+  /**
+   * Stream timing on the native sink: the host time of the latest device
+   * callback, when a frame is heard, and the device latency. Undefined on
+   * the stdin players (their output latency is unknown).
+   */
+  public get timing(): AudioTiming | undefined {
+    return this.child?.clock?.timing();
+  }
+
   private queuedFrames(): number {
+    const clock = this.child?.clock;
+    if (clock) return clock.queuedFrames();
     const elapsed = Math.floor(
       ((this.now() - this.startMs) * this.sampleRate) / 1000,
     );
@@ -781,10 +900,21 @@ export class AudioEngine {
     const child = this.child;
     const loop = this.loop;
     if (!child || (!loop && !this.monitoring)) return;
-    const due =
-      Math.floor(((this.now() - this.startMs) * this.sampleRate) / 1000) +
-      this.lead;
-    let remaining = due - this.written;
+    let remaining: number;
+    if (child.clock) {
+      // Device-clocked: top the ring up to the lead. Frames the device
+      // played as silence (an underrun) are skipped so the loop stays on
+      // the transport's beat.
+      const slip = child.clock.slipFrames();
+      if (slip > 0 && loop) this.cursor = (this.cursor + slip) % loop.frames;
+      if (slip > 0) this.endFades();
+      remaining = this.lead - child.clock.queuedFrames();
+    } else {
+      const due =
+        Math.floor(((this.now() - this.startMs) * this.sampleRate) / 1000) +
+        this.lead;
+      remaining = due - this.written;
+    }
     if (remaining <= 0) return;
     // Never queue more than one second at once, e.g. after a stalled loop.
     if (remaining > this.sampleRate) {
@@ -864,6 +994,8 @@ export class AudioEngine {
 
   /** Wall time (monotonic ms) stream frame `frame` sounds at. */
   private frameMs(frame: number): number {
+    const clock = this.child?.clock;
+    if (clock) return clock.frameMs(frame);
     return this.startMs + (frame * 1000) / this.sampleRate;
   }
 

package/src/audio/fit.ts

@@ -53,7 +53,12 @@ const onsetCache = new Map<string, readonly number[]>();
 /** Background jobs by cache key, with the window they fit (one per window). */
 const pending = new Map<
   string,
-  { job: Generator<void, Float32Array>; window: string }
+  {
+    job: Generator<void, Float32Array>;
+    window: string;
+    /** Another stage's cache (0.7 autotune) takes the result instead. */
+    done?: (out: Float32Array) => void;
+  }
 >();
 let live = false;
 /** True when the current live render left a voice silent while fitting. */
@@ -191,6 +196,32 @@ export function shiftedBuffer(
   return out;
 }
 
+/** True inside `withLiveFit` (0.7: other stages defer long work too). */
+export function liveFitActive(): boolean {
+  return live;
+}
+
+/**
+ * Runs `job` between live blocks like a long fit and hands the result to
+ * `done` (the caller's own cache); `onFitReady` fires when it lands and
+ * the live render reports `fitting` until then (0.7 autotune).
+ */
+export function deferLiveJob<T>(
+  key: string,
+  job: () => Generator<void, T>,
+  done: (out: T) => void,
+): void {
+  missed = true;
+  if (pending.has(key)) return;
+  // The scheduler only steps the job and hands its value to `done`.
+  pending.set(key, {
+    job: job() as unknown as Generator<void, Float32Array>,
+    window: key,
+    done: done as unknown as (out: Float32Array) => void,
+  });
+  schedule();
+}
+
 function drain(job: Generator<void, Float32Array>): Float32Array {
   for (;;) {
     const step = job.next();
@@ -204,13 +235,14 @@ function schedule(): void {
     timer = undefined;
     const next = pending.entries().next();
     if (next.done) return;
-    const [key, { job }] = next.value;
+    const [key, { job, done }] = next.value;
     const until = performance.now() + 8;
     for (;;) {
       const step = job.next();
       if (step.done) {
         pending.delete(key);
-        remember(key, step.value);
+        if (done) done(step.value);
+        else remember(key, step.value);
         for (const listener of listeners) listener();
         break;
       }