@libraz/libsonare 1.7.2 → 1.8.0

package/src/mastering_dynamics.ts

@@ -72,8 +72,17 @@ export interface MasteringDynamicsTransientShaperRequest extends TransientShaper
   sampleRate: number;
 }
 
-/** Result envelope returned by offline mastering dynamics processors. */
-export interface DynamicsResult {
+/**
+ * Result envelope returned by offline mastering dynamics processors.
+ *
+ * Named for what it is rather than for the module it lives in. {@link
+ * DynamicsResult} is the *analysis* shape on every binding, so having that one
+ * identifier mean two disjoint field lists across the Node and WASM packages
+ * made a shared TypeScript module type-check against one and fail against the
+ * other — with the identifier resolving either way, so only the member list
+ * gave it away.
+ */
+export interface DynamicsProcessorResult {
   samples: Float32Array;
   latencySamples: number;
 }
@@ -87,17 +96,17 @@ const COMPRESSOR_DETECTOR_MAP: Record<CompressorDetector, number> = {
 /** Offline feed-forward compressor (soft knee, optional auto-makeup / sidechain HPF). */
 export function masteringDynamicsCompressor(
   request: MasteringDynamicsCompressorRequest,
-): DynamicsResult;
+): DynamicsProcessorResult;
 export function masteringDynamicsCompressor(
   samples: Float32Array,
   sampleRate: number,
   options?: CompressorOptions,
-): DynamicsResult;
+): DynamicsProcessorResult;
 export function masteringDynamicsCompressor(
   samples: Float32Array | MasteringDynamicsCompressorRequest,
   sampleRate?: number,
   options: CompressorOptions = {},
-): DynamicsResult {
+): DynamicsProcessorResult {
   const request =
     samples instanceof Float32Array
       ? { samples, sampleRate: sampleRate as number, ...options }
@@ -121,17 +130,19 @@ export function masteringDynamicsCompressor(
 }
 
 /** Offline noise gate (hysteresis, hold, optional key HPF). */
-export function masteringDynamicsGate(request: MasteringDynamicsGateRequest): DynamicsResult;
+export function masteringDynamicsGate(
+  request: MasteringDynamicsGateRequest,
+): DynamicsProcessorResult;
 export function masteringDynamicsGate(
   samples: Float32Array,
   sampleRate: number,
   options?: GateOptions,
-): DynamicsResult;
+): DynamicsProcessorResult;
 export function masteringDynamicsGate(
   samples: Float32Array | MasteringDynamicsGateRequest,
   sampleRate?: number,
   options: GateOptions = {},
-): DynamicsResult {
+): DynamicsProcessorResult {
   const request =
     samples instanceof Float32Array
       ? { samples, sampleRate: sampleRate as number, ...options }
@@ -143,17 +154,17 @@ export function masteringDynamicsGate(
 /** Offline transient shaper (envelope-difference attack/sustain control). */
 export function masteringDynamicsTransientShaper(
   request: MasteringDynamicsTransientShaperRequest,
-): DynamicsResult;
+): DynamicsProcessorResult;
 export function masteringDynamicsTransientShaper(
   samples: Float32Array,
   sampleRate: number,
   options?: TransientShaperOptions,
-): DynamicsResult;
+): DynamicsProcessorResult;
 export function masteringDynamicsTransientShaper(
   samples: Float32Array | MasteringDynamicsTransientShaperRequest,
   sampleRate?: number,
   options: TransientShaperOptions = {},
-): DynamicsResult {
+): DynamicsProcessorResult {
   const request =
     samples instanceof Float32Array
       ? { samples, sampleRate: sampleRate as number, ...options }

package/src/metering.ts

@@ -1,7 +1,18 @@
 import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
 import type { ValidateOptions } from './validation';
-import { assertSamples } from './validation';
+import {
+  assertInterleavedSamples,
+  assertNonNegativeInteger,
+  assertPositiveInteger,
+  assertSamples,
+  assertSamplesInWindow,
+} from './validation';
+
+// The FFT size the library falls back to when `nFft` is 0 or omitted. Mirrored
+// here so the windowed pre-scan covers exactly the span the call will read; a
+// test pins it against the `nFft` the library reports back for a 0 request.
+const DEFAULT_SPECTRUM_N_FFT = 2048;
 
 /**
  * Validates a true-peak oversample factor: `0` (meaning "use the default 4") or
@@ -267,9 +278,7 @@ export function meteringDetectClipping(
   const request = samples instanceof Float32Array ? { samples, sampleRate, ...options } : samples;
   assertSamples('meteringDetectClipping', request.samples, request.validate !== false);
   const minRegionSamples = request.minRegionSamples ?? 1;
-  if (!Number.isInteger(minRegionSamples) || minRegionSamples < 0) {
-    throw new RangeError('meteringDetectClipping: minRegionSamples must be a non-negative integer');
-  }
+  assertNonNegativeInteger('meteringDetectClipping', minRegionSamples, 'minRegionSamples');
   return requireModule().meteringDetectClipping(
     request.samples,
     request.sampleRate ?? 22050,
@@ -447,10 +456,14 @@ export function meteringStereoCorrelation(
 }
 
 /**
- * Side / mid energy ratio in `[0, +Infinity)`: 0 = pure mono, ~1 = wide stereo,
- * larger = increasingly decorrelated / out-of-phase. The value is unbounded and
- * returns `Infinity` when the mid channel is silent (a mono-collapsed / fully
- * out-of-phase signal).
+ * Stereo width as `sqrt(side_energy / mid_energy)` in `[0, +Infinity)`: the
+ * side/mid RMS *amplitude* ratio, not the energy ratio. 0 = pure mono, ~1 =
+ * wide stereo, larger = increasingly decorrelated / out-of-phase. The value is
+ * unbounded and returns `Infinity` when the mid channel is silent (a
+ * mono-collapsed / fully out-of-phase signal).
+ *
+ * Convert to dB with `20 * Math.log10(value)`; `10 * Math.log10` would
+ * understate the true energy ratio by half.
  */
 export function meteringStereoWidth(request: MeteringStereoRequest): number;
 export function meteringStereoWidth(
@@ -651,6 +664,12 @@ export function meteringSpectrum(
  * `nFft`-length FFT), for spectrum-analyzer "moment" snapshots that must not be
  * time-averaged like {@link meteringSpectrum}. The analysis frame spans
  * `[frameOffset, frameOffset + nFft)`; samples past the end are zero-padded.
+ *
+ * The frame is also the only span validated: a non-finite sample inside it is
+ * rejected, while one outside it neither reaches the FFT nor refuses the call.
+ * The emptiness and `sampleRate` checks still cover the whole buffer. Cost per
+ * call is therefore set by `nFft` rather than by the length of the buffer, so an
+ * analyzer may poll a long recording frame by frame.
  */
 export function meteringSpectrumFrame(request: MeteringSpectrumFrameRequest): SpectrumReport;
 export function meteringSpectrumFrame(
@@ -667,7 +686,14 @@ export function meteringSpectrumFrame(
 ): SpectrumReport {
   const request =
     samples instanceof Float32Array ? { samples, sampleRate, frameOffset, ...options } : samples;
-  assertSamples('meteringSpectrumFrame', request.samples, request.validate !== false);
+  const nFft = request.nFft ?? 0;
+  assertSamplesInWindow(
+    'meteringSpectrumFrame',
+    request.samples,
+    request.validate !== false,
+    request.frameOffset ?? 0,
+    nFft > 0 ? nFft : DEFAULT_SPECTRUM_N_FFT,
+  );
   return requireModule().meteringSpectrumFrame(
     request.samples,
     request.sampleRate ?? 22050,
@@ -676,7 +702,14 @@ export function meteringSpectrumFrame(
   );
 }
 
-/** Compute per-channel min/max waveform buckets from interleaved audio. */
+/**
+ * Compute per-channel min/max waveform buckets from interleaved audio.
+ *
+ * A non-finite sample is rejected rather than skipped, and `{ validate: false }`
+ * does not change that — it only skips the JS pre-scan that names the offending
+ * index. A bucket whose samples are not finite has no min/max to report, and the
+ * `0`/`0` it would otherwise carry is what a waveform display draws as silence.
+ */
 export function waveformPeaks(request: WaveformPeaksRequest): WaveformPeaksReport;
 export function waveformPeaks(
   samples: Float32Array,
@@ -692,18 +725,23 @@ export function waveformPeaks(
     samples instanceof Float32Array
       ? { samples, channels: channels as number, ...options }
       : samples;
-  assertSamples('waveformPeaks', request.samples, request.validate !== false);
-  if (request.channels <= 0 || request.samples.length % request.channels !== 0) {
-    throw new RangeError('waveformPeaks: samples length must be a multiple of channels');
-  }
+  assertInterleavedSamples(
+    'waveformPeaks',
+    request.samples,
+    request.channels,
+    request.validate !== false,
+  );
   const samplesPerBucket = request.samplesPerBucket ?? 512;
-  if (samplesPerBucket <= 0) {
-    throw new RangeError('waveformPeaks: samplesPerBucket must be > 0');
-  }
+  assertPositiveInteger('waveformPeaks', samplesPerBucket, 'samplesPerBucket');
   return requireModule().waveformPeaks(request.samples, request.channels, samplesPerBucket);
 }
 
-/** Compute waveform peak buckets for several zoom levels. */
+/**
+ * Compute waveform peak buckets for several zoom levels.
+ *
+ * Shares {@link waveformPeaks}' bucket kernel, so a non-finite sample is
+ * rejected here on the same rule.
+ */
 export function waveformPeakPyramid(request: WaveformPeakPyramidRequest): WaveformPeaksReport[];
 export function waveformPeakPyramid(
   samples: Float32Array,
@@ -719,13 +757,18 @@ export function waveformPeakPyramid(
     samples instanceof Float32Array
       ? { samples, channels: channels as number, ...options }
       : samples;
-  assertSamples('waveformPeakPyramid', request.samples, request.validate !== false);
-  if (request.channels <= 0 || request.samples.length % request.channels !== 0) {
-    throw new RangeError('waveformPeakPyramid: samples length must be a multiple of channels');
-  }
+  assertInterleavedSamples(
+    'waveformPeakPyramid',
+    request.samples,
+    request.channels,
+    request.validate !== false,
+  );
   const levels = request.samplesPerBucketLevels ?? [512, 1024, 2048, 4096];
-  if (levels.length === 0 || levels.some((level) => level <= 0)) {
-    throw new RangeError('waveformPeakPyramid: samplesPerBucketLevels must be non-empty and > 0');
+  if (levels.length === 0) {
+    throw new RangeError('waveformPeakPyramid: samplesPerBucketLevels must not be empty');
   }
+  levels.forEach((level, index) => {
+    assertPositiveInteger('waveformPeakPyramid', level, `samplesPerBucketLevels[${index}]`);
+  });
   return requireModule().waveformPeakPyramid(request.samples, request.channels, levels);
 }

package/src/mixer.ts

@@ -18,6 +18,49 @@ import type {
   SurroundPan,
 } from './public_types';
 
+/**
+ * One master-output meter reading. All dB fields are finite and floored at
+ * -120; `truePeakDb*` is an inter-sample peak from the ITU-R BS.1770-4
+ * polyphase reconstruction at 4x, not a sample peak. That reconstruction is a
+ * streaming measurement: its centered stencil needs a few future samples a
+ * realtime path does not have, so each block's last samples read marginally low
+ * (about 0.1 dB across 64..8192-sample blocks on a near-Nyquist tone, always
+ * under-reading). Use `meteringTruePeakDb` over the whole signal for an exact
+ * dBTP number.
+ */
+export interface MixerMeterSnapshot {
+  peakDbL: number;
+  peakDbR: number;
+  rmsDbL: number;
+  rmsDbR: number;
+  correlation: number;
+  truePeakDbL: number;
+  truePeakDbR: number;
+}
+
+/**
+ * Meter configuration for a strip added with {@link Mixer.addStrip}.
+ *
+ * The field names and defaults are the scene document's `strips[].metering`
+ * object, so a strip added imperatively and one declared in a scene describe the
+ * same thing. A strip's meters size their buffers when the strip is built, so
+ * this is the only place the configuration can be chosen — there is no setter.
+ * A full meter costs about 646 KB at 48 kHz and a strip carries two of them.
+ */
+export interface StripMeteringOptions {
+  /** Both meters; `false` drops them (about 145 KB for the strip instead of 1.4 MB). Default `true`. */
+  enabled?: boolean;
+  /** LUFS measurement; `false` takes one meter to about 83 KB. Default `true`. */
+  lufs?: boolean;
+  /** Inter-sample (true) peak measurement. Default `true`. */
+  truePeak?: boolean;
+  /**
+   * Requested true-peak oversampling factor in `[0, 16]`; the meter resolves it
+   * to the nearest of 2x / 4x / 8x. `0` selects the library default (4x).
+   */
+  truePeakOversample?: number;
+}
+
 export interface MixerRealtimeBuffer {
   leftInputs: Float32Array[];
   rightInputs: Float32Array[];
@@ -45,7 +88,7 @@ export interface MixerRealtimeBuffer {
  *
  * @example
  * ```typescript
- * const mixer = Mixer.fromSceneJson(mixingScenePresetJson('basicStereo'), 48000, 512);
+ * const mixer = Mixer.fromSceneJson(mixingScenePresetJson('vocalReverbSend'), 48000, 512);
  * try {
  *   const out = mixer.processStereo([stripL], [stripR]);
  * } finally {
@@ -55,6 +98,7 @@ export interface MixerRealtimeBuffer {
  */
 export class Mixer {
   private mixer: import('./sonare.js').WasmMixer;
+  private released = false;
   private readonly blockSize: number;
 
   private constructor(mixer: import('./sonare.js').WasmMixer, blockSize: number) {
@@ -65,6 +109,13 @@ export class Mixer {
   /**
    * Build a mixer from a scene JSON string.
    *
+   * A strip's meters are sized when the strip is built, so this is where their
+   * configuration is chosen: an optional `metering` object on the strip
+   * (`enabled` / `lufs` / `truePeak` / `truePeakOversample`) selects it, and
+   * leaving it out keeps the full default (LUFS + true peak at 4x, about 1.4 MB
+   * per strip at 48 kHz). `{"enabled": false}` drops both meters for a strip
+   * whose snapshots are never read.
+   *
    * @param json - Scene JSON (strips, buses, sends, connections, inserts)
    * @param sampleRate - Sample rate in Hz (default: 48000)
    * @param blockSize - Maximum block size per {@link processStereo} call (default: 512)
@@ -185,6 +236,60 @@ export class Mixer {
     };
   }
 
+  /**
+   * Turn the master-output meter on or off.
+   *
+   * While on, every {@link MixerRealtimeBuffer.process} call meters the stereo
+   * master it just produced, so a caller reads {@link meterSnapshot} instead of
+   * copying the output and measuring it again. `truePeakDb*` is an inter-sample
+   * peak taken after oversampling (ITU-R BS.1770-4 Annex 2 requires at least
+   * 4x), which is a different and higher quantity than the sample peak.
+   *
+   * Enabling resets the meter, so a reading never mixes in audio from a period
+   * when metering was off.
+   *
+   * @param enabled - Whether to meter the master output.
+   * @param truePeakOversample - 0 (= 4x) or a power of two in [1, 16].
+   */
+  configureMeter(enabled: boolean, truePeakOversample = 4): void {
+    this.mixer.configureMeter(enabled, truePeakOversample);
+  }
+
+  /**
+   * Latest master-output meter reading, describing the most recently metered
+   * block. All dB fields are finite and floored at -120.
+   *
+   * @throws When the meter has never been enabled.
+   */
+  meterSnapshot(): MixerMeterSnapshot {
+    return this.mixer.meterSnapshot();
+  }
+
+  /**
+   * Latch the latest meter reading into the mixer's internal scratch so
+   * {@link meterScratchValue} can read it back one number at a time.
+   *
+   * This is the allocation-free form of {@link meterSnapshot}, for an audio
+   * render callback that must not create a JS object per interval. It returns
+   * `false` instead of throwing when the meter has never been enabled.
+   *
+   * @returns Whether a reading was latched.
+   */
+  latchMeterSnapshot(): boolean {
+    return this.mixer.latchMeterSnapshot();
+  }
+
+  /**
+   * Read one field of the snapshot latched by {@link latchMeterSnapshot}.
+   *
+   * @param field - `0` peakDbL, `1` peakDbR, `2` rmsDbL, `3` rmsDbR,
+   *   `4` correlation, `5` truePeakDbL, `6` truePeakDbR. Any other index
+   *   reads `0`.
+   */
+  meterScratchValue(field: number): number {
+    return this.mixer.meterScratchValue(field);
+  }
+
   /** Number of strips in the mixer (e.g. strips loaded from the scene). */
   stripCount(): number {
     return this.mixer.stripCount();
@@ -232,6 +337,18 @@ export class Mixer {
     return index < 0 ? null : index;
   }
 
+  /**
+   * Add a channel strip to the mixer topology. `metering` configures the strip's
+   * pre/post taps; omitting it keeps the full default (LUFS + true peak at 4x,
+   * about 1.4 MB per strip at 48 kHz). Marks the routing graph dirty; call
+   * {@link compile} (or {@link processStereo}) to rebuild.
+   *
+   * @throws If the id is already taken, or `truePeakOversample` is outside `[0, 16]`
+   */
+  addStrip(id: string, metering: StripMeteringOptions = {}): void {
+    this.mixer.addStrip(id, metering);
+  }
+
   /**
    * Add a bus to the mixer topology. `role` is one of `'master'`, `'aux'`, or
    * `'submix'` (defaults to `'aux'`). Marks the routing graph dirty; call
@@ -310,6 +427,31 @@ export class Mixer {
     this.mixer.setWidth(stripIndex, width);
   }
 
+  /**
+   * Snap the strip's input-trim, fader, pan and width smoothers to the values
+   * already set on it, so the next processed block opens at those values
+   * instead of gliding to them over the smoothing window (~5 ms).
+   *
+   * Call it after configuring a strip and before rendering a finite buffer: a
+   * strip is smoothed for a live fader, and an offline render that does not
+   * settle carries that glide as a level and image sweep across the head of
+   * its output. Unlike a reset it clears nothing — automation, meters and
+   * insert state are untouched.
+   *
+   * @param stripIndex - Strip index in `[0, stripCount())`
+   *
+   * @example
+   * ```typescript
+   * mixer.setFaderDb(0, -3);
+   * mixer.setPan(0, 0.3);
+   * mixer.settle(0);
+   * const { left, right } = mixer.processStereo([dryLeft], [dryRight]);
+   * ```
+   */
+  settle(stripIndex: number): void {
+    this.mixer.settle(stripIndex);
+  }
+
   /** Set the strip's mute state. */
   setMuted(stripIndex: number, muted: boolean): void {
     this.mixer.setMuted(stripIndex, muted);
@@ -361,7 +503,10 @@ export class Mixer {
 
   /**
    * Set the strip's surround pan position, used when it feeds a >2-channel bus.
-   * Stored on the scene; inert until the surround DSP path applies it.
+   *
+   * Applied when the engine's track mixer renders this strip's lane into a
+   * destination with more than two channels. This stereo-only mixer's own
+   * block entry points ignore it.
    */
   setSurroundPan(stripIndex: number, pan: SurroundPan): void {
     this.mixer.setSurroundPan(stripIndex, pan);
@@ -440,6 +585,61 @@ export class Mixer {
     return this.mixer.busMeter(busId);
   }
 
+  /**
+   * Number of blocks in which the strip discarded recursive state because a
+   * non-finite value had reached it.
+   *
+   * Advisory telemetry, and the only thing that separates a degraded strip
+   * from a clean one. A discard returns the affected state to its
+   * post-reset value, so the strip recovers in silence and the output stays
+   * finite and in range while carrying samples unrelated to the input;
+   * nothing else reports that this happened.
+   *
+   * The count covers the strip's own state, its EQ, every insert it owns and
+   * both of its meters. None of those is separately addressable here, so a
+   * discard inside one is observable only through this number -- and a
+   * meter that loses its loudness window then reports the floor, which is
+   * exactly what a genuinely silent strip reports, so nothing else
+   * distinguishes the two.
+   *
+   * A meter's own discard lags by one block: it checks its loudness state at
+   * the top of a block, before consuming that block's samples, so the block
+   * that corrupts it is not the block the count moves on -- read this again
+   * after one more block has processed. The EQ and inserts have no such lag;
+   * they discard at the end of their own process, in the same block that
+   * carried the poison.
+   *
+   * Cumulative since the strip was created and never cleared, so two
+   * readings bracket a span of audio. The unit is one processed block, never
+   * a channel, so a stereo block that discards on both channels adds one and
+   * the number does not depend on a dimension the caller did not choose.
+   *
+   * @param stripIndex - Strip index in `[0, stripCount())`
+   */
+  stripNonFiniteDiscardCount(stripIndex: number): number {
+    return this.mixer.stripNonFiniteDiscardCount(stripIndex);
+  }
+
+  /**
+   * Number of blocks in which a bus discarded recursive state because a
+   * non-finite value had reached it. Same contract as
+   * {@link stripNonFiniteDiscardCount}, for a bus: covers every insert the
+   * bus owns and its meter, neither separately addressable, so a discard
+   * inside one is observable only here. Cumulative across graph recompiles
+   * -- the count lives with the bus, not the compiled node, so an unrelated
+   * edit elsewhere in the mixer does not reset it.
+   *
+   * A bus's DSP record is created by the first {@link compile}. Throws for a
+   * bus that has been declared with {@link addBus} but never compiled --
+   * reading zero there would read as clean, and it is not. Also throws for
+   * an unknown bus id.
+   *
+   * @param busId - Bus id, as passed to {@link addBus} or declared in scene JSON
+   */
+  busNonFiniteDiscardCount(busId: string): number {
+    return this.mixer.busNonFiniteDiscardCount(busId);
+  }
+
   /**
    * Schedule sample-accurate fader automation on a strip.
    *
@@ -519,6 +719,11 @@ export class Mixer {
   /**
    * Read up to `maxPoints` of a strip's most recent goniometer samples
    * (oldest to newest).
+   *
+   * `maxPoints` must be a finite non-negative integer; anything else throws an
+   * `InvalidParameter` error. It is a request rather than an allocation size —
+   * a value beyond the strip's goniometer ring simply returns every point the
+   * ring holds.
    */
   readGoniometerLatest(stripIndex: number, maxPoints: number): GoniometerPoint[] {
     return this.mixer.readGoniometerLatest(stripIndex, maxPoints);
@@ -559,8 +764,12 @@ export class Mixer {
     return this.mixer.drainTailStereo(numSamples);
   }
 
-  /** Release the underlying WASM object. Safe to call only once. */
+  /** Release the underlying WASM object. Idempotent, as the Node facade is. */
   delete(): void {
+    if (this.released) {
+      return;
+    }
+    this.released = true;
     this.mixer.delete();
   }
 

package/src/mixing_assistant.ts

@@ -0,0 +1,138 @@
+import { getSonareModule } from './module_state';
+import type { MixAssistantOptions, MixAssistantResult, MixAssistantTrack } from './public_types';
+import { assertSampleRate } from './validation';
+
+function requireModule() {
+  return getSonareModule();
+}
+
+/** Inputs for the {@link suggestMixScene} / {@link suggestMixSceneJson} facades. */
+export interface SuggestMixSceneRequest {
+  /** Tracks to mix, in the order their profiles are reported. */
+  tracks: MixAssistantTrack[];
+  /**
+   * Shared sample rate in Hz for every track. Required: every band edge,
+   * high-pass corner, sibilance band and alignment lag is derived from it, so a
+   * guessed rate would silently misread 44.1 kHz material by 8.8% and report
+   * `channelDelaySamples` and `durationSec` wrong with it.
+   */
+  sampleRate: number;
+  /** Assistant tunables; every field falls back to the core default. */
+  options?: MixAssistantOptions;
+}
+
+/** The four parallel arrays the embind entry points take. */
+interface PlanarTracks {
+  left: Float32Array[];
+  right: (Float32Array | null)[];
+  ids: string[];
+  names: (string | null)[];
+}
+
+/**
+ * Splits the request's track list into the planar per-track arrays the binding
+ * takes, rejecting the shapes that would otherwise reach the analysis as a
+ * missing buffer or a nameless strip.
+ */
+function planarTracks(tracks: MixAssistantTrack[]): PlanarTracks {
+  if (!Array.isArray(tracks)) {
+    throw new Error('tracks must be an array.');
+  }
+  const left: Float32Array[] = [];
+  const right: (Float32Array | null)[] = [];
+  const ids: string[] = [];
+  const names: (string | null)[] = [];
+  for (let index = 0; index < tracks.length; index++) {
+    const track = tracks[index];
+    if (track === null || typeof track !== 'object') {
+      throw new Error(`tracks[${index}] must be an object.`);
+    }
+    if (typeof track.id !== 'string' || track.id.length === 0) {
+      throw new Error(`tracks[${index}].id must be a non-empty string.`);
+    }
+    if (!(track.left instanceof Float32Array)) {
+      throw new Error(`tracks[${index}].left must be a Float32Array.`);
+    }
+    if (track.right !== undefined && !(track.right instanceof Float32Array)) {
+      throw new Error(`tracks[${index}].right must be a Float32Array when present.`);
+    }
+    left.push(track.left);
+    right.push(track.right ?? null);
+    ids.push(track.id);
+    names.push(track.name ?? null);
+  }
+  return { left, right, ids, names };
+}
+
+function suggestJson(fnName: string, request: SuggestMixSceneRequest, sceneOnly: boolean): string {
+  // Required, not defaulted: this surface used to invent 48000, which read
+  // 44.1 kHz material 8.8% off across every band edge and every lag without
+  // saying so. Node and Python both demand it, and a request ported from either
+  // must not change behaviour by arriving here.
+  assertSampleRate(fnName, request.sampleRate);
+  const { left, right, ids, names } = planarTracks(request.tracks);
+  const sampleRate = request.sampleRate;
+  const params = (request.options ?? {}) as Record<string, number | boolean>;
+  const module = requireModule();
+  return sceneOnly
+    ? module.mixingAssistantSuggestSceneJson(left, right, ids, names, sampleRate, params)
+    : module.mixingAssistantSuggest(left, right, ids, names, sampleRate, params);
+}
+
+/**
+ * Analyze a set of tracks and suggest a mixer scene.
+ *
+ * Offline only: the pipeline runs an STFT per track and evaluates every track
+ * pair, so it is measured in milliseconds per track and must never be called
+ * from an audio callback.
+ *
+ * The assistant suggests, it does not apply. Nothing is processed and no audio
+ * is returned; realizing the suggestion means handing the scene to
+ * {@link Mixer.fromSceneJson} as an explicit second step, for which
+ * {@link suggestMixSceneJson} returns the scene already serialized.
+ *
+ * Degenerate input is not an error: no tracks, all-silent tracks or tracks too
+ * short to measure yield an empty scene and an empty `explanation`.
+ *
+ * @param request - Tracks, shared sample rate and assistant options
+ * @returns The suggested scene, per-track profiles, cross-track measurements
+ *   and the explanation behind each change
+ */
+export function suggestMixScene(request: SuggestMixSceneRequest): MixAssistantResult {
+  return JSON.parse(suggestJson('suggestMixScene', request, false)) as MixAssistantResult;
+}
+
+/**
+ * Suggest a mixer scene and return only the scene, as JSON.
+ *
+ * The same analysis as {@link suggestMixScene}, serialized in the schema
+ * {@link Mixer.fromSceneJson} reads, so a caller that only wants to apply the
+ * suggestion neither digs the scene out of the fuller result nor re-serializes
+ * it.
+ *
+ * @param request - Tracks, shared sample rate and assistant options
+ * @returns Scene JSON string
+ */
+export function suggestMixSceneJson(request: SuggestMixSceneRequest): string {
+  return suggestJson('suggestMixSceneJson', request, true);
+}
+
+/**
+ * Source-class identifiers the assistant can report, in enum order.
+ *
+ * The index of a name in this list is the value
+ * {@link mixSourceClassFromName} resolves it to.
+ */
+export function mixSourceClassNames(): string[] {
+  return Array.from(requireModule().mixingAssistantSourceClassNames());
+}
+
+/**
+ * Resolve a source-class identifier to its index in {@link mixSourceClassNames}.
+ *
+ * @param name - Source-class identifier, e.g. `"kick"`
+ * @returns The index, or -1 when the name is unknown
+ */
+export function mixSourceClassFromName(name: string): number {
+  return requireModule().mixingAssistantSourceClassFromName(name);
+}

package/src/mixing_oneshot.ts

@@ -32,11 +32,16 @@ export interface MixStereoRequest extends MixOptions {
  * One-shot stereo mix of multiple strips through the routing graph + master bus.
  *
  * Each returned per-strip meter reflects only this single one-shot block. The
- * integrating-meter fields (`momentaryLufs`, `shortTermLufs`, `integratedLufs`
- * and the true-peak fields) require sustained streaming to populate; on a short
- * one-shot mix they read the -120 dB floor sentinel. Drive a streaming
- * {@link Mixer} block-by-block if you need meaningful loudness/true-peak
- * readings.
+ * LUFS fields (`momentaryLufs`, `shortTermLufs`, `integratedLufs`) are
+ * integrators whose windows that block does not fill, so they read the -120 dB
+ * floor sentinel; drive a streaming {@link Mixer} block-by-block if you need
+ * meaningful loudness.
+ *
+ * The true-peak fields are not integrators and need no streaming: each is a
+ * max-hold over the block just processed and is valid from the first one,
+ * flooring only on silence. This facade mixes the whole input as a single block,
+ * which is the whole-signal case, so the block-edge under-read documented on
+ * `MixMeterSnapshot.truePeakDbL` does not apply to the reading here.
  *
  * @param leftChannels - Per-strip left input buffers (all the same length)
  * @param rightChannels - Per-strip right input buffers (all the same length)