@libraz/libsonare 1.3.2 → 1.4.0

package/src/public_types.ts

@@ -367,6 +367,40 @@ export interface NoteStretchOptions {
   stretchRatio?: number;
 }
 
+/** How a `spectralEdit` region op modifies the masked bins. */
+export type SpectralEditMode = 'gain' | 'attenuate' | 'mute' | 'heal';
+
+/** Analysis/synthesis window used by `spectralEdit`. */
+export type SpectralEditWindow = 'hann' | 'hamming' | 'blackman' | 'rectangular';
+
+/** One time x frequency rectangle edit op for `spectralEdit`. */
+export interface SpectralRegionOp {
+  /** Region time start (input samples); clamped to [0, length]. Default 0. */
+  startSample?: number;
+  /** Region time end, exclusive (input samples); clamped to [0, length]. Default = signal length. */
+  endSample?: number;
+  /** Region frequency low edge in Hz; clamped to [0, nyquist]. Default 0. */
+  lowHz?: number;
+  /** Region frequency high edge in Hz; <=0 or >= nyquist means nyquist. Default 0. */
+  highHz?: number;
+  /** Linear gain in dB for 'gain'/'attenuate'; ignored by 'mute'/'heal'. Default 0. */
+  gainDb?: number;
+  /** Edit mode. Default 'gain'. */
+  mode?: SpectralEditMode;
+}
+
+/** STFT + heal parameters for `spectralEdit`. All fields are optional. */
+export interface SpectralEditOptions {
+  /** FFT size; must be a power of two (>= 2). Default 2048. */
+  nFft?: number;
+  /** Hop length; must satisfy 0 < hop <= nFft/2. Default 512. */
+  hopLength?: number;
+  /** Analysis + synthesis window. Default 'hann'. */
+  window?: SpectralEditWindow;
+  /** Neighbour frames each side used by 'heal' (>= 1). Default 2. */
+  healRadiusFrames?: number;
+}
+
 /**
  * Detected beat
  */
@@ -655,6 +689,24 @@ export type MasteringProcessorParams = Record<string, number | boolean>;
 
 export type PanMode = 'balance' | 'stereoPan' | 'stereo-pan' | 'dualPan' | 'dual-pan' | number;
 
+/**
+ * Surround pan position for a strip feeding a >2-channel bus. Phase 1 honors
+ * `azimuth`/`divergence`/`lfe`; `elevation`/`distance` are reserved. All fields
+ * are optional and default to a centered point source.
+ */
+export interface SurroundPan {
+  /** -180..180 deg, 0 = front-center, positive = right. */
+  azimuth?: number;
+  /** Reserved (no height beds in phase 1). */
+  elevation?: number;
+  /** 0 = point source, 1 = spread across the front. */
+  divergence?: number;
+  /** 0..1 scalar send into the LFE plane. */
+  lfe?: number;
+  /** Reserved (focus/spread), defaults to 1. */
+  distance?: number;
+}
+
 export interface MixOptions {
   inputTrimDb?: number | number[];
   faderDb?: number | number[];

package/src/realtime_engine.ts

@@ -1,5 +1,8 @@
+import { panLawCode, panModeCode, sendTimingCode } from './codes';
+import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
 import type { SynthPatch } from './project';
+import type { EqBand, PanLaw, PanMode, SendTiming } from './public_types';
 import type {
   WasmClipPageRequest,
   WasmEngineAutomationPoint,
@@ -12,10 +15,14 @@ import type {
   WasmEngineGraphSpec,
   WasmEngineMarker,
   WasmEngineMeterTelemetry,
+  WasmEngineMeterTelemetryWide,
   WasmEngineMetronomeConfig,
   WasmEngineParameterInfo,
   WasmEngineProcessWithMonitorResult,
+  WasmEngineScopeTelemetry,
   WasmEngineTelemetry,
+  WasmEngineTempoSegment,
+  WasmEngineTimeSignatureSegment,
   WasmEngineTransportState,
   WasmRealtimeEngine,
 } from './sonare.js';
@@ -34,7 +41,75 @@ export type EngineFreezeOptions = WasmEngineFreezeOptions;
 export type EngineFreezeResult = WasmEngineFreezeResult;
 export type EngineTelemetry = WasmEngineTelemetry;
 export type EngineMeterTelemetry = WasmEngineMeterTelemetry;
+export type EngineMeterTelemetryWide = WasmEngineMeterTelemetryWide;
+export type EngineScopeTelemetry = WasmEngineScopeTelemetry;
 export type EngineTransportState = WasmEngineTransportState;
+export type EngineTempoSegment = WasmEngineTempoSegment;
+export type EngineTimeSignatureSegment = WasmEngineTimeSignatureSegment;
+
+export interface EngineTrackSend {
+  busId: number;
+  levelDb?: number;
+  enabled?: boolean;
+  /**
+   * Pre/post-fader tap point. Defaults to post-fader when omitted, matching the
+   * historical lane-send behavior and the scene-JSON default.
+   */
+  sendTiming?: SendTiming | number;
+}
+
+export interface EngineTrackLane {
+  trackId: number;
+  sends?: EngineTrackSend[];
+  /**
+   * Bus the lane's post-fader output sums into instead of the master mix
+   * (group/folder routing); 0 or absent keeps the lane on the master mix.
+   */
+  outputBusId?: number;
+  /**
+   * Input channel layout of the source feeding this lane (`SonareChannelLayout`:
+   * 0 mono, 1 stereo, 2 5.1, 3 7.1). Absent defaults to stereo. Stored but inert
+   * until the surround DSP path lands.
+   */
+  sourceChannelLayout?: number;
+}
+
+export interface EngineBus {
+  busId: number;
+  gainDb?: number;
+  /**
+   * Channel layout of the bus (`SonareChannelLayout`: 0 mono, 1 stereo, 2 5.1,
+   * 3 7.1). A surround layout makes this a surround group bus: lanes routed to
+   * it are surround-panned and it sums into the master plane-by-plane. Defaults
+   * to stereo.
+   */
+  channelLayout?: number;
+}
+
+export interface EngineMidiEvent {
+  renderFrame: number;
+  word0?: number;
+  word1?: number;
+  word2?: number;
+  word3?: number;
+  wordCount?: number;
+  group?: number;
+  sysexHandle?: number;
+  data0?: number;
+  data1?: number;
+}
+
+export interface EngineMidiClipSchedule {
+  id?: number;
+  trackId?: number;
+  destinationId?: number;
+  startSample?: number;
+  startPpq?: number;
+  lengthSamples?: number;
+  loop?: boolean;
+  loopLengthSamples?: number;
+  events: EngineMidiEvent[];
+}
 
 export const EXPECTED_ENGINE_ABI_VERSION = 3;
 
@@ -75,91 +150,9 @@ export function engineCapabilities(): EngineCapabilities {
   };
 }
 
-// Methods added to the embind RealtimeEngine that the generated `sonare.js`
-// declarations only gain after a WASM rebuild. The native handle is cast to this
-// shape so the wrapper can reach them without a stale type error.
-interface WasmRealtimeEngineExt {
-  setBuiltinInstrument: (destinationId: number, config: object) => void;
-  setSynthInstrument: (destinationId: number, patch: object | string) => void;
-  loadSoundFont: (data: Uint8Array) => void;
-  setSf2Instrument: (destinationId: number, config: object) => void;
-  clearMidiInstrument: (destinationId: number) => void;
-  midiInstrumentCount: () => number;
-  bindMidiCc: (
-    channel: number,
-    controller: number,
-    paramId: number,
-    minValue: number,
-    maxValue: number,
-  ) => void;
-  clearMidiCcBindings: () => void;
-  midiCcBindingCount: () => number;
-  setMidiFx: (destinationId: number, configJson: string) => void;
-  clearMidiFx: (destinationId: number) => void;
-  setMidiInputSource: (destinationId: number) => void;
-  clearMidiInputSource: () => void;
-  midiInputPendingCount: () => number;
-  createClipPageProvider: (numChannels: number, numSamples: number, pageFrames: number) => number;
-  supplyClipPage: (providerId: number, pageIndex: number, channels: Float32Array[]) => void;
-  clearClipPage: (providerId: number, pageIndex: number) => void;
-  destroyClipPageProvider: (providerId: number) => void;
-  popClipPageRequest: () => ClipPageRequest | null;
-  pushMidiInputNoteOn: (
-    group: number,
-    channel: number,
-    note: number,
-    velocity: number,
-    portTimeSamples: number,
-  ) => void;
-  pushMidiInputNoteOff: (
-    group: number,
-    channel: number,
-    note: number,
-    velocity: number,
-    portTimeSamples: number,
-  ) => void;
-  pushMidiInputCc: (
-    group: number,
-    channel: number,
-    controller: number,
-    value: number,
-    portTimeSamples: number,
-  ) => void;
-  pushMidiNoteOn: (
-    destinationId: number,
-    group: number,
-    channel: number,
-    note: number,
-    velocity: number,
-    renderFrame: number,
-  ) => void;
-  pushMidiNoteOff: (
-    destinationId: number,
-    group: number,
-    channel: number,
-    note: number,
-    velocity: number,
-    renderFrame: number,
-  ) => void;
-  pushMidiCc: (
-    destinationId: number,
-    group: number,
-    channel: number,
-    controller: number,
-    value: number,
-    renderFrame: number,
-  ) => void;
-  pushMidiPanic: (renderFrame: number) => void;
-  clearParameters: () => void;
-}
-
 export class RealtimeEngine {
   private native: WasmRealtimeEngine;
 
-  private nativeExt(): WasmRealtimeEngineExt {
-    return this.native as unknown as WasmRealtimeEngineExt;
-  }
-
   constructor(
     sampleRate = 48000,
     maxBlockSize = 128,
@@ -200,11 +193,19 @@ export class RealtimeEngine {
     this.native.setParameterSmoothed(paramId, value, renderFrame);
   }
 
+  setSoloMute(laneIndex: number, solo: boolean, mute: boolean, renderFrame = -1): void {
+    this.native.setSoloMute(laneIndex, solo, mute, renderFrame);
+  }
+
+  setMidiClips(clips: readonly EngineMidiClipSchedule[]): void {
+    this.native.setMidiClips(clips);
+  }
+
   setBuiltinInstrument(
     config: { destinationId?: number } & Record<string, unknown> = {},
     destinationId = config.destinationId ?? 0,
   ): void {
-    this.nativeExt().setBuiltinInstrument(destinationId, config);
+    this.native.setBuiltinInstrument(destinationId, config);
   }
 
   /**
@@ -220,7 +221,7 @@ export class RealtimeEngine {
     patch: SynthPatch | string = {},
     destinationId = (typeof patch === 'object' ? patch.destinationId : undefined) ?? 0,
   ): void {
-    this.nativeExt().setSynthInstrument(destinationId, patch);
+    this.native.setSynthInstrument(destinationId, patch);
   }
 
   /**
@@ -230,7 +231,7 @@ export class RealtimeEngine {
    * not referenced afterwards. Replaces any previously loaded SoundFont.
    */
   loadSoundFont(data: Uint8Array): void {
-    this.nativeExt().loadSoundFont(data);
+    this.native.loadSoundFont(data);
   }
 
   /**
@@ -246,15 +247,15 @@ export class RealtimeEngine {
     config: { destinationId?: number; gain?: number; polyphony?: number } = {},
     destinationId = config.destinationId ?? 0,
   ): void {
-    this.nativeExt().setSf2Instrument(destinationId, config);
+    this.native.setSf2Instrument(destinationId, config);
   }
 
   clearMidiInstrument(destinationId = 0): void {
-    this.nativeExt().clearMidiInstrument(destinationId);
+    this.native.clearMidiInstrument(destinationId);
   }
 
   midiInstrumentCount(): number {
-    return this.nativeExt().midiInstrumentCount();
+    return this.native.midiInstrumentCount();
   }
 
   /**
@@ -268,7 +269,7 @@ export class RealtimeEngine {
     paramId: number,
     options: MidiCcBindOptions = {},
   ): void {
-    this.nativeExt().bindMidiCc(
+    this.native.bindMidiCc(
       channel,
       controller,
       paramId,
@@ -278,33 +279,33 @@ export class RealtimeEngine {
   }
 
   clearMidiCcBindings(): void {
-    this.nativeExt().clearMidiCcBindings();
+    this.native.clearMidiCcBindings();
   }
 
   midiCcBindingCount(): number {
-    return this.nativeExt().midiCcBindingCount();
+    return this.native.midiCcBindingCount();
   }
 
   /** Install/replace a live non-destructive MIDI-FX insert for one destination. */
   setMidiFx(destinationId: number, configJson: string): void {
-    this.nativeExt().setMidiFx(destinationId, configJson);
+    this.native.setMidiFx(destinationId, configJson);
   }
 
   clearMidiFx(destinationId = 0): void {
-    this.nativeExt().clearMidiFx(destinationId);
+    this.native.clearMidiFx(destinationId);
   }
 
   /** Enable the engine-owned live MIDI input source for a destination. */
   setMidiInputSource(destinationId = 0): void {
-    this.nativeExt().setMidiInputSource(destinationId);
+    this.native.setMidiInputSource(destinationId);
   }
 
   clearMidiInputSource(): void {
-    this.nativeExt().clearMidiInputSource();
+    this.native.clearMidiInputSource();
   }
 
   midiInputPendingCount(): number {
-    return this.nativeExt().midiInputPendingCount();
+    return this.native.midiInputPendingCount();
   }
 
   pushMidiInputNoteOn(
@@ -314,7 +315,7 @@ export class RealtimeEngine {
     velocity: number,
     portTimeSamples = 0,
   ): void {
-    this.nativeExt().pushMidiInputNoteOn(group, channel, note, velocity, portTimeSamples);
+    this.native.pushMidiInputNoteOn(group, channel, note, velocity, portTimeSamples);
   }
 
   pushMidiInputNoteOff(
@@ -324,7 +325,7 @@ export class RealtimeEngine {
     velocity = 0,
     portTimeSamples = 0,
   ): void {
-    this.nativeExt().pushMidiInputNoteOff(group, channel, note, velocity, portTimeSamples);
+    this.native.pushMidiInputNoteOff(group, channel, note, velocity, portTimeSamples);
   }
 
   pushMidiInputCc(
@@ -334,7 +335,7 @@ export class RealtimeEngine {
     value: number,
     portTimeSamples = 0,
   ): void {
-    this.nativeExt().pushMidiInputCc(group, channel, controller, value, portTimeSamples);
+    this.native.pushMidiInputCc(group, channel, controller, value, portTimeSamples);
   }
 
   pushMidiNoteOn(
@@ -345,7 +346,7 @@ export class RealtimeEngine {
     velocity: number,
     renderFrame = -1,
   ): void {
-    this.nativeExt().pushMidiNoteOn(destinationId, group, channel, note, velocity, renderFrame);
+    this.native.pushMidiNoteOn(destinationId, group, channel, note, velocity, renderFrame);
   }
 
   pushMidiNoteOff(
@@ -356,7 +357,7 @@ export class RealtimeEngine {
     velocity = 0,
     renderFrame = -1,
   ): void {
-    this.nativeExt().pushMidiNoteOff(destinationId, group, channel, note, velocity, renderFrame);
+    this.native.pushMidiNoteOff(destinationId, group, channel, note, velocity, renderFrame);
   }
 
   /**
@@ -373,7 +374,7 @@ export class RealtimeEngine {
     value: number,
     renderFrame = -1,
   ): void {
-    this.nativeExt().pushMidiCc(destinationId, group, channel, controller, value, renderFrame);
+    this.native.pushMidiCc(destinationId, group, channel, controller, value, renderFrame);
   }
 
   /**
@@ -381,7 +382,7 @@ export class RealtimeEngine {
    * `renderFrame` (-1 = immediate). Mirrors the C-ABI `pushMidiPanic`.
    */
   pushMidiPanic(renderFrame = -1): void {
-    this.nativeExt().pushMidiPanic(renderFrame);
+    this.native.pushMidiPanic(renderFrame);
   }
 
   /**
@@ -389,7 +390,7 @@ export class RealtimeEngine {
    * only; not realtime-safe. Mirrors the C-ABI `clearParameters`.
    */
   clearParameters(): void {
-    this.nativeExt().clearParameters();
+    this.native.clearParameters();
   }
 
   /** Read back the current transport state snapshot. */
@@ -409,6 +410,16 @@ export class RealtimeEngine {
     this.native.seekSample(timelineSample, renderFrame);
   }
 
+  /**
+   * Snaps every in-flight parameter ramp (engine-level smoothed params, mixer
+   * lane fader/pan/gate, bus gains) to its target value. Offline renders call
+   * this after a priming process() block so the first audible block renders at
+   * settled values instead of ramping in from defaults.
+   */
+  settleParameters(): void {
+    this.native.settleParameters();
+  }
+
   seekPpq(ppq: number, renderFrame = -1): void {
     this.native.seekPpq(ppq, renderFrame);
   }
@@ -417,10 +428,22 @@ export class RealtimeEngine {
     this.native.setTempo(bpm);
   }
 
+  setTempoSegments(segments: readonly EngineTempoSegment[]): void {
+    this.native.setTempoSegments([...segments]);
+  }
+
   setTimeSignature(numerator: number, denominator: number): void {
     this.native.setTimeSignature(numerator, denominator);
   }
 
+  setTimeSignatureSegments(segments: readonly EngineTimeSignatureSegment[]): void {
+    this.native.setTimeSignatureSegments([...segments]);
+  }
+
+  sampleAtPpq(ppq: number): number {
+    return Number(this.native.sampleAtPpq(ppq));
+  }
+
   setLoop(startPpq: number, endPpq: number, enabled = true): void {
     this.native.setLoop(startPpq, endPpq, enabled);
   }
@@ -513,29 +536,183 @@ export class RealtimeEngine {
     return this.native.clipCount();
   }
 
+  setTrackLanes(lanes: Array<number | EngineTrackLane>): void {
+    this.native.setTrackLanes(
+      lanes.map((lane) => {
+        if (typeof lane === 'number') {
+          return { trackId: lane };
+        }
+        if (!lane.sends) {
+          return lane;
+        }
+        // Normalize each send's pre/post tap point to the integer the native
+        // layer reads (defaults to post-fader when omitted).
+        return {
+          ...lane,
+          sends: lane.sends.map((send) => ({
+            ...send,
+            // Post-fader (0) is the default for an omitted sendTiming.
+            sendTiming: send.sendTiming === undefined ? 0 : sendTimingCode(send.sendTiming),
+          })),
+        };
+      }),
+    );
+  }
+
+  /**
+   * Keys one insert of a lane strip from another lane's post-strip audio
+   * (ducking/sidechainRouter inserts). sourceTrackId 0 removes the binding.
+   */
+  setLaneSidechain(trackId: number, insertIndex: number, sourceTrackId: number): void {
+    this.native.setLaneSidechain(trackId, insertIndex, sourceTrackId);
+  }
+
+  setTrackBuses(buses: EngineBus[]): void {
+    this.native.setTrackBuses(buses);
+  }
+
+  setBusStripJson(busId: number, sceneJson: string): void {
+    try {
+      JSON.parse(sceneJson);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'invalid bus strip JSON';
+      throw new SonareError(ErrorCode.InvalidFormat, 'InvalidFormat', message);
+    }
+    this.native.setBusStripJson(busId, sceneJson);
+  }
+
+  setTrackStripJson(trackId: number, sceneJson: string): void {
+    try {
+      JSON.parse(sceneJson);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'invalid track strip JSON';
+      throw new SonareError(ErrorCode.InvalidFormat, 'InvalidFormat', message);
+    }
+    this.native.setTrackStripJson(trackId, sceneJson);
+  }
+
+  setTrackStripEqBand(trackId: number, bandIndex: number, band: EqBand | string): void {
+    this.native.setTrackStripEqBandJson(
+      trackId,
+      bandIndex,
+      typeof band === 'string' ? band : JSON.stringify(band),
+    );
+  }
+
+  setTrackStripEqBandJson(trackId: number, bandIndex: number, bandJson: string): void {
+    this.native.setTrackStripEqBandJson(trackId, bandIndex, bandJson);
+  }
+
+  setTrackStripInsertBypassed(
+    trackId: number,
+    insertIndex: number,
+    bypassed: boolean,
+    resetOnBypass = false,
+  ): void {
+    this.native.setTrackStripInsertBypassed(trackId, insertIndex, bypassed, resetOnBypass);
+  }
+
+  setMasterStripJson(sceneJson: string): void {
+    try {
+      JSON.parse(sceneJson);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'invalid master strip JSON';
+      throw new SonareError(ErrorCode.InvalidFormat, 'InvalidFormat', message);
+    }
+    this.native.setMasterStripJson(sceneJson);
+  }
+
+  setMasterStripEqBand(bandIndex: number, band: EqBand | string): void {
+    this.native.setMasterStripEqBandJson(
+      bandIndex,
+      typeof band === 'string' ? band : JSON.stringify(band),
+    );
+  }
+
+  setMasterStripEqBandJson(bandIndex: number, bandJson: string): void {
+    this.native.setMasterStripEqBandJson(bandIndex, bandJson);
+  }
+
+  setMasterStripInsertBypassed(
+    insertIndex: number,
+    bypassed: boolean,
+    resetOnBypass = false,
+  ): void {
+    this.native.setMasterStripInsertBypassed(insertIndex, bypassed, resetOnBypass);
+  }
+
+  /**
+   * Changes one track-strip insert parameter in realtime, addressed by the
+   * processor's JSON-key parameter name (see {@link masteringInsertParamInfo}).
+   * Applied at the next block head via the engine command queue; safe during
+   * playback. Throws if the track, insert, or name is unknown, the param is not
+   * realtime-safe, or the command queue is full.
+   */
+  setTrackStripInsertParamByName(
+    trackId: number,
+    insertIndex: number,
+    paramName: string,
+    value: number,
+  ): void {
+    this.native.setTrackStripInsertParamByName(trackId, insertIndex, paramName, value);
+  }
+
+  /** Master-strip counterpart of {@link setTrackStripInsertParamByName}. */
+  setMasterStripInsertParamByName(insertIndex: number, paramName: string, value: number): void {
+    this.native.setMasterStripInsertParamByName(insertIndex, paramName, value);
+  }
+
+  /** Sets a track lane strip's pan position in realtime (glitch-free). */
+  setTrackStripPan(trackId: number, pan: number): void {
+    this.native.setTrackStripPan(trackId, pan);
+  }
+
+  /** Sets a track lane strip's pan law in realtime. */
+  setTrackStripPanLaw(trackId: number, panLaw: PanLaw | number): void {
+    this.native.setTrackStripPanLaw(trackId, panLawCode(panLaw));
+  }
+
+  /** Sets a track lane strip's pan mode in realtime. */
+  setTrackStripPanMode(trackId: number, panMode: PanMode | number): void {
+    this.native.setTrackStripPanMode(trackId, panModeCode(panMode));
+  }
+
+  /** Sets a track lane strip's dual-pan left/right positions in realtime. */
+  setTrackStripDualPan(trackId: number, leftPan: number, rightPan: number): void {
+    this.native.setTrackStripDualPan(trackId, leftPan, rightPan);
+  }
+
+  /**
+   * Sets a track lane strip's inter-channel alignment delay (whole samples).
+   * Adjusts strip latency, so PDC and reported graph latency are refreshed.
+   */
+  setTrackStripChannelDelaySamples(trackId: number, delaySamples: number): void {
+    this.native.setTrackStripChannelDelaySamples(trackId, delaySamples);
+  }
+
   createClipPageProvider(
     numChannels: number,
     numSamples: number,
     pageFrames: number,
   ): ClipPageProvider {
-    const id = this.nativeExt().createClipPageProvider(numChannels, numSamples, pageFrames);
+    const id = this.native.createClipPageProvider(numChannels, numSamples, pageFrames);
     return new ClipPageProvider(this, id);
   }
 
   supplyClipPage(providerId: number, pageIndex: number, channels: Float32Array[]): void {
-    this.nativeExt().supplyClipPage(providerId, pageIndex, channels);
+    this.native.supplyClipPage(providerId, pageIndex, channels);
   }
 
   clearClipPage(providerId: number, pageIndex: number): void {
-    this.nativeExt().clearClipPage(providerId, pageIndex);
+    this.native.clearClipPage(providerId, pageIndex);
   }
 
   destroyClipPageProvider(providerId: number): void {
-    this.nativeExt().destroyClipPageProvider(providerId);
+    this.native.destroyClipPageProvider(providerId);
   }
 
   popClipPageRequest(): ClipPageRequest | null {
-    return this.nativeExt().popClipPageRequest();
+    return this.native.popClipPageRequest();
   }
 
   setCaptureBuffer(numChannels: number, capacityFrames: number): void {
@@ -630,6 +807,33 @@ export class RealtimeEngine {
     return this.native.drainMeterTelemetry(maxRecords);
   }
 
+  /**
+   * Drains pending meter telemetry as per-plane (wide) records for a surround
+   * target. Use this for a surround mix target; {@link drainMeterTelemetry}
+   * stays the stereo fast path. The two share one queue — call only one per
+   * target. The live AudioWorklet path owns the queue via the stereo drain, so
+   * this wide drain is for an offline (non-worklet) engine instance; per-plane
+   * surround meters are not delivered over the live worklet meter ring.
+   */
+  drainMeterTelemetryWide(maxRecords = 1024): EngineMeterTelemetryWide[] {
+    return this.native.drainMeterTelemetryWide(maxRecords);
+  }
+
+  /**
+   * Enables per-target spectrum + vectorscope capture. @param intervalFrames is
+   * the minimum render-frame gap between snapshots (0 disables). @param bandCount
+   * is the FFT band resolution (1..64); changing it re-prepares the tap. Returns
+   * the band count actually applied.
+   */
+  configureScopeTelemetry(intervalFrames: number, bandCount: number): number {
+    return this.native.configureScopeTelemetry(intervalFrames, bandCount);
+  }
+
+  /** Drains pending spectrum + vectorscope snapshots (per mix target). */
+  drainScopeTelemetry(maxRecords = 1024): EngineScopeTelemetry[] {
+    return this.native.drainScopeTelemetry(maxRecords);
+  }
+
   destroy(): void {
     this.native.delete();
   }