@libraz/libsonare 1.6.0 → 1.7.1

package/src/project_class.ts

@@ -1,5 +1,6 @@
 import {
   assertProjectMidiEvents,
+  projectAutomationTargetKindValue,
   projectLoopModeValue,
   projectMidi1Event,
   projectModule,
@@ -13,8 +14,10 @@ import type {
   ExternalSeparatedStemImportResult,
   MidiCcLearnOptions,
   ProjectAssistSidecar,
+  ProjectAssistSidecarInput,
   ProjectAutomationLaneDesc,
   ProjectAutomationPoint,
+  ProjectAutomationTargetKind,
   ProjectBounceOptions,
   ProjectChordSymbol,
   ProjectClip,
@@ -49,6 +52,41 @@ import type {
   SynthPatch,
 } from './project_types';
 
+function validateAssistSidecarUint32(value: unknown, field: string): number {
+  if (
+    typeof value !== 'number' ||
+    !Number.isSafeInteger(value) ||
+    value < 0 ||
+    value > 0xffff_ffff
+  ) {
+    throw new RangeError(`Project.setAssistSidecar: ${field} must be a uint32`);
+  }
+  return value;
+}
+
+function validateAssistSidecarPpq(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    throw new RangeError(
+      `Project.setAssistSidecar: ${field} must be a finite, non-negative number`,
+    );
+  }
+  return value;
+}
+
+function validateAssistSidecarPayload(value: unknown): Uint8Array {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError('Project.setAssistSidecar: payload must be a Uint8Array');
+  }
+  return value;
+}
+
+function validateAssistSidecarModuleId(value: unknown): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError('Project.setAssistSidecar: moduleId must be a non-empty string');
+  }
+  return value;
+}
+
 /**
  * Headless DAW project (control-thread-only arrangement model).
  *
@@ -82,6 +120,11 @@ export class Project {
     this.native = new (projectModule().Project)();
   }
 
+  /** Create a new empty project. */
+  static create(): Project {
+    return new Project();
+  }
+
   /** Pack a MIDI 1.0 note-on event accepted by {@link setMidiEvents}. */
   static midiNoteOn(
     ppq: number,
@@ -462,6 +505,19 @@ export class Project {
     this.native.setMaxUndoDepth(depth);
   }
 
+  /** Set the combined undo/redo history byte cap. Zero disables retention. */
+  setMaxHistoryBytes(bytes: number): void {
+    if (typeof bytes !== 'number') {
+      throw new TypeError('Project.setMaxHistoryBytes: bytes must be a number');
+    }
+    if (!Number.isFinite(bytes) || !Number.isInteger(bytes) || bytes < 0 || bytes > 0xffff_ffff) {
+      throw new RangeError(
+        'Project.setMaxHistoryBytes: bytes must be a finite integer in the uint32 range',
+      );
+    }
+    this.native.setMaxHistoryBytes(bytes);
+  }
+
   /** Replace a MIDI clip's entire event list. */
   setMidiEvents(
     clipId: number,
@@ -625,8 +681,11 @@ export class Project {
    * Karplus-Strong / modal / additive / percussion / extended-waveguide-piano
    * engines plus the realism layer). Pass a {@link SynthPatch}, a preset-name
    * string (`'saw-lead'` / `'va:saw-lead'`; see {@link synthPresetNames}), or
-   * an array of either; each object entry may carry a `destinationId` binding
-   * convenience (default 0), which is not part of the NativeSynth patch itself.
+   * an array of either; each object entry may carry `destinationId` (default
+   * 0) and `useGmPrograms` (default `false`) binding conveniences, neither of
+   * which is part of the NativeSynth patch itself. When enabled, MIDI program
+   * changes select the corresponding General MIDI voice while the patch remains
+   * the fallback.
    * Because the parameter defaults to `{}`, omission and explicit `undefined`
    * both create one default binding. Use an explicitly empty array `[]` (or
    * runtime `null`) for zero bindings. Unknown preset names throw.
@@ -722,6 +781,11 @@ export class Project {
     this.native.setSourceAudio(sourceId, audio, channels, sampleRate);
   }
 
+  /** Replace an audio source's metadata strings as one undoable edit. */
+  setAudioSourceMetadata(sourceId: number, contentHash: string, externalStemRole: string): void {
+    this.native.setAudioSourceMetadata(sourceId, contentHash, externalStemRole);
+  }
+
   /** Replace a clip's take list and active take id (undoable). */
   setClipTakes(clipId: number, takes: ReadonlyArray<ProjectClipTake>, activeTakeId = 0): void {
     this.native.setClipTakes(clipId, takes, activeTakeId);
@@ -778,10 +842,16 @@ export class Project {
 
   /** Append an automation lane; returns its stable target parameter id (undoable). */
   addAutomationLane(trackId: number, desc: ProjectAutomationLaneDesc): number {
-    return this.native.addAutomationLane(trackId, {
-      targetParamId: desc.targetParamId,
-      points: desc.points,
-    });
+    if (desc.targetParamId === 0) {
+      throw new RangeError('project automation lane targetParamId must be non-zero');
+    }
+    const nativeDesc: ProjectAutomationLaneDesc = { ...desc };
+    if (Object.keys(desc).includes('targetKind')) {
+      nativeDesc.targetKind = projectAutomationTargetKindValue(
+        desc.targetKind as ProjectAutomationTargetKind,
+      ) as ProjectAutomationTargetKind;
+    }
+    return this.native.addAutomationLane(trackId, nativeDesc);
   }
 
   /** Replace the lane identified by its stable target parameter id (undoable). */
@@ -790,10 +860,16 @@ export class Project {
     targetParamId: number,
     desc: ProjectAutomationLaneDesc,
   ): void {
-    this.native.editAutomationLane(trackId, targetParamId, {
-      targetParamId: desc.targetParamId,
-      points: desc.points,
-    });
+    if (desc.targetParamId === 0) {
+      throw new RangeError('project automation lane targetParamId must be non-zero');
+    }
+    const nativeDesc: ProjectAutomationLaneDesc = { ...desc };
+    if (Object.keys(desc).includes('targetKind')) {
+      nativeDesc.targetKind = projectAutomationTargetKindValue(
+        desc.targetKind as ProjectAutomationTargetKind,
+      ) as ProjectAutomationTargetKind;
+    }
+    this.native.editAutomationLane(trackId, targetParamId, nativeDesc);
   }
 
   /** Remove the lane identified by its stable target parameter id (undoable). */
@@ -811,7 +887,14 @@ export class Project {
     this.native.annotateChords(chords);
   }
 
-  /** Add or update an opaque assist sidecar by module id + target scope (undoable). */
+  /**
+   * Add or update an opaque assist sidecar via an undoable edit.
+   *
+   * The descriptor form is the canonical API and matches the Node binding;
+   * the positional form remains available for compatibility with the original
+   * WASM facade.
+   */
+  setAssistSidecar(sidecar: ProjectAssistSidecarInput): void;
   setAssistSidecar(
     moduleId: string,
     schemaVersion: number,
@@ -819,14 +902,52 @@ export class Project {
     regionStartPpq: number,
     regionEndPpq: number,
     payload: Uint8Array,
+  ): void;
+  setAssistSidecar(
+    sidecarOrModuleId: ProjectAssistSidecarInput | string,
+    schemaVersion?: number,
+    targetTrackId?: number,
+    regionStartPpq?: number,
+    regionEndPpq?: number,
+    payload?: Uint8Array,
   ): void {
+    if (typeof sidecarOrModuleId === 'string') {
+      if (
+        schemaVersion === undefined ||
+        targetTrackId === undefined ||
+        regionStartPpq === undefined ||
+        regionEndPpq === undefined ||
+        payload === undefined
+      ) {
+        throw new TypeError('Project.setAssistSidecar: positional form requires six arguments');
+      }
+      this.native.setAssistSidecar(
+        validateAssistSidecarModuleId(sidecarOrModuleId),
+        validateAssistSidecarUint32(schemaVersion, 'schemaVersion'),
+        validateAssistSidecarUint32(targetTrackId, 'targetTrackId'),
+        validateAssistSidecarPpq(regionStartPpq, 'regionStartPpq'),
+        validateAssistSidecarPpq(regionEndPpq, 'regionEndPpq'),
+        validateAssistSidecarPayload(payload),
+      );
+      return;
+    }
+
+    if (
+      sidecarOrModuleId === null ||
+      typeof sidecarOrModuleId !== 'object' ||
+      Array.isArray(sidecarOrModuleId)
+    ) {
+      throw new TypeError('Project.setAssistSidecar: expected a sidecar descriptor object');
+    }
+    const sidecar = sidecarOrModuleId;
+    const moduleId = validateAssistSidecarModuleId(sidecar.moduleId);
     this.native.setAssistSidecar(
       moduleId,
-      schemaVersion,
-      targetTrackId,
-      regionStartPpq,
-      regionEndPpq,
-      payload,
+      validateAssistSidecarUint32(sidecar.schemaVersion ?? 0, 'schemaVersion'),
+      validateAssistSidecarUint32(sidecar.targetTrackId ?? 0, 'targetTrackId'),
+      validateAssistSidecarPpq(sidecar.regionStartPpq ?? 0, 'regionStartPpq'),
+      validateAssistSidecarPpq(sidecar.regionEndPpq ?? 0, 'regionEndPpq'),
+      validateAssistSidecarPayload(sidecar.payload ?? new Uint8Array()),
     );
   }
 
@@ -840,6 +961,12 @@ export class Project {
     return this.native.getAssistSidecar(index);
   }
 
+  /** Read every stored assist sidecar in the same order as the index getter. */
+  assistSidecars(): ProjectAssistSidecar[] {
+    const count = this.assistSidecarCount();
+    return Array.from({ length: count }, (_, index) => this.getAssistSidecar(index));
+  }
+
   /** Set the project's clip-overlap policy (SonareProjectOverlapPolicy ordinal). */
   setOverlapPolicy(policy: number): void {
     this.native.setOverlapPolicy(policy);

package/src/project_internal.ts

@@ -3,7 +3,9 @@ import { getSonareModule } from './module_state';
 import type {
   BuiltinSynthBinding,
   ProjectAssistSidecar,
+  ProjectAutomationLaneDesc,
   ProjectAutomationPoint,
+  ProjectAutomationTargetKind,
   ProjectBounceOptions,
   ProjectChordSymbol,
   ProjectClip,
@@ -65,6 +67,7 @@ export interface WasmProject {
   redo: () => void;
   clearHistory: () => void;
   setMaxUndoDepth: (depth: number) => void;
+  setMaxHistoryBytes: (bytes: number) => void;
   setMidiEvents: (
     clipId: number,
     events: ReadonlyArray<ProjectMidiEvent | readonly [number, number, number]>,
@@ -120,6 +123,7 @@ export interface WasmProject {
     channels: number,
     sampleRate: number,
   ) => void;
+  setAudioSourceMetadata: (sourceId: number, contentHash: string, externalStemRole: string) => void;
   setClipTakes: (
     clipId: number,
     takes: ReadonlyArray<ProjectClipTake>,
@@ -137,14 +141,11 @@ export interface WasmProject {
   removeTrack: (trackId: number) => void;
   renameTrack: (trackId: number, name: string) => void;
   setTrackRoute: (trackId: number, channelStripRef: string, outputTarget: string) => void;
-  addAutomationLane: (
-    trackId: number,
-    desc: { targetParamId: number; points: ReadonlyArray<ProjectAutomationPoint> },
-  ) => number;
+  addAutomationLane: (trackId: number, desc: ProjectAutomationLaneDesc) => number;
   editAutomationLane: (
     trackId: number,
     targetParamId: number,
-    desc: { targetParamId: number; points: ReadonlyArray<ProjectAutomationPoint> },
+    desc: ProjectAutomationLaneDesc,
   ) => void;
   removeAutomationLane: (trackId: number, targetParamId: number) => void;
   annotateKeys: (keys: ReadonlyArray<ProjectKeySegment>) => void;
@@ -325,6 +326,14 @@ export function projectTrackKindValue(kind: ProjectTrackKind | undefined): numbe
   return resolveEnumOrdinal(kind ?? 'audio', { audio: 0, midi: 1, aux: 2 }, 'project track kind');
 }
 
+export function projectAutomationTargetKindValue(kind: ProjectAutomationTargetKind): number {
+  return resolveEnumOrdinal(
+    kind,
+    { opaque: 0, 'track-fader-db': 1, 'track-pan': 2 },
+    'project automation target kind',
+  );
+}
+
 export function projectWarpModeValue(mode: ProjectWarpMode | undefined): number {
   return resolveEnumOrdinal(
     mode ?? 'off',

package/src/project_types.ts

@@ -110,6 +110,10 @@ export interface ProjectSource {
   storageHandleId: number;
   sampleRateHint: number;
   nameOrUri: string;
+  /** Owning content hash for audio sources; empty for MIDI sources. */
+  contentHash: string;
+  /** External source-separation role for audio sources; empty for MIDI sources. */
+  externalStemRole: string;
 }
 
 /** Names accepted by the minimal built-in oscillator synth. */
@@ -296,12 +300,11 @@ export interface SynthModRouting {
  *
  * The patch starts from a BASE — the named `preset` (see
  * {@link synthPresetNames}; a `"va:"` routing prefix is accepted) or, when
- * `preset` is omitted, the default subtractive patch. Every numeric field then
- * uses "0 / omit => keep the base value" (non-zero values override, clamped to
- * their audible ranges) and the enum fields reserve `'default'` as keep. The
- * frozen C ABI has no per-field presence bits, so explicit zero numeric
- * overrides (for example `ampSustain: 0`) cannot be represented; they keep the
- * base value. A non-empty `modRoutings` REPLACES the base mod matrix.
+ * `preset` is omitted, the default subtractive patch. Omitting a numeric field
+ * keeps the base value; supplying one overrides it (clamped to its audible
+ * range), including an explicit `0` such as `stereoSpread: 0`. The enum fields
+ * reserve `'default'` as keep. A `modRoutings` array REPLACES the base mod
+ * matrix, and an empty array clears it, while omitting the key keeps it.
  *
  * Mode-specific deep parameters (FM operator stacks, modal mode tables,
  * drawbar registrations, kit pieces, piano strings) travel inside the named
@@ -314,6 +317,8 @@ export interface SynthPatch {
    * `(destination_id, patch)` bindings instead. Defaults to `0`.
    */
   destinationId?: number;
+  /** Resolve MIDI channels from incoming GM bank/program changes; defaults to false. */
+  useGmPrograms?: boolean;
   /** Base preset name (see {@link synthPresetNames}); omit for the init patch. */
   preset?: string;
   engineMode?: SynthEngineMode | number;
@@ -335,12 +340,10 @@ export interface SynthPatch {
   velToCutoffCents?: number;
   ampAttackMs?: number;
   ampDecayMs?: number;
-  /** 0 / omit keeps the base value; explicit zero sustain is not representable. */
   ampSustain?: number;
   ampReleaseMs?: number;
   filterAttackMs?: number;
   filterDecayMs?: number;
-  /** 0 / omit keeps the base value; explicit zero sustain is not representable. */
   filterSustain?: number;
   filterReleaseMs?: number;
   lfoRateHz?: number;
@@ -448,12 +451,34 @@ export interface ProjectAutomationPoint {
   curve?: ProjectAutomationCurve;
 }
 
+/**
+ * Persistent target classification for an automation lane.
+ *
+ * The numeric ordinals mirror `SonareAutomationTargetKind`; the string names
+ * are the public WASM spellings accepted by the project facade.
+ */
+export const AutomationTargetKind = {
+  opaque: 0,
+  trackFaderDb: 1,
+  trackPan: 2,
+} as const;
+
+/** Accepted automation target kind name or ABI ordinal. */
+export type ProjectAutomationTargetKind = 'opaque' | 'track-fader-db' | 'track-pan' | 0 | 1 | 2;
+
+/** Numeric aliases matching the C-ABI enum names. */
+export const PROJECT_AUTOMATION_TARGET_OPAQUE = AutomationTargetKind.opaque;
+export const PROJECT_AUTOMATION_TARGET_TRACK_FADER_DB = AutomationTargetKind.trackFaderDb;
+export const PROJECT_AUTOMATION_TARGET_TRACK_PAN = AutomationTargetKind.trackPan;
+
 /** Automation-lane descriptor for {@link Project.addAutomationLane}. */
 export interface ProjectAutomationLaneDesc {
-  /** Host-defined id of the parameter the lane drives. */
+  /** Host-defined, non-zero id of the parameter the lane drives (zero is reserved). */
   targetParamId: number;
   /** Breakpoints (stored verbatim). */
   points: ReadonlyArray<ProjectAutomationPoint>;
+  /** Optional persistent target classification; omission retains the legacy opaque route. */
+  targetKind?: ProjectAutomationTargetKind;
 }
 
 /** One tempo segment for {@link Project.setTempoSegments}. */
@@ -515,6 +540,22 @@ export interface ProjectChordSymbol {
   modulationBoundary?: boolean;
 }
 
+/** Descriptor accepted by {@link Project.setAssistSidecar}. */
+export interface ProjectAssistSidecarInput {
+  /** Non-empty module id key. */
+  moduleId: string;
+  /** Module-defined schema version. Defaults to `0`. */
+  schemaVersion?: number;
+  /** Target track id (`0` = project scope). Defaults to `0`. */
+  targetTrackId?: number;
+  /** Region start in PPQ. Defaults to `0`. */
+  regionStartPpq?: number;
+  /** Region end in PPQ. Defaults to `0`. */
+  regionEndPpq?: number;
+  /** Opaque module-owned payload bytes. Defaults to an empty payload. */
+  payload?: Uint8Array;
+}
+
 /** Assist sidecar snapshot returned by {@link Project.getAssistSidecar}. */
 export interface ProjectAssistSidecar {
   moduleId: string;

package/src/public_types_mastering.ts

@@ -352,6 +352,15 @@ export interface MasteringChainConfig {
     releaseMs?: number;
     applyGainAtInputRate?: boolean;
   };
+  /**
+   * Dot-notation spelling of any leaf above, e.g. `'loudness.targetLufs': -20`
+   * beside or instead of `loudness: { targetLufs: -20 }`. It is the form the C
+   * ABI carries parameters in, so a caller assembling overrides dynamically can
+   * emit it directly; the core validates the key and rejects an unknown one.
+   * The nested spelling is canonical — prefer it in hand-written code, where it
+   * is checked field by field while a dotted key is only checked at run time.
+   */
+  [flatKey: `${string}.${string}`]: number | boolean | undefined;
 }
 
 /**

package/src/public_types_mixing.ts

@@ -90,6 +90,22 @@ export type AutomationCurve = 'linear' | 'exponential' | 'hold' | 's-curve';
  */
 export type PanLaw = 'const3dB' | 'const4.5dB' | 'const6dB' | 'linear0dB';
 
+/** Accepted pan-law name aliases for mixer and realtime-engine inputs. */
+export type PanLawName =
+  | PanLaw
+  | 'const-3db'
+  | '-3db'
+  | 'const-4.5db'
+  | '-4.5db'
+  | 'const-6db'
+  | '-6db'
+  | 'linear-0db'
+  | 'linear'
+  | '0db';
+
+/** Pan-law name or raw C ABI ordinal. */
+export type PanLawInput = PanLawName | number;
+
 /**
  * Meter tap point for reading a strip's meter snapshot
  * (see {@link Mixer.meterTap} and {@link Mixer.stripMeter}).

package/src/public_types_realtime.ts

@@ -105,15 +105,33 @@ export type VoicePresetId =
   | 'robot-mascot'
   | 'dark-villain';
 
-export interface RealtimeVoiceChangerPreset {
+export type VoicePresetCategory =
+  | 'monitor'
+  | 'bright'
+  | 'soft'
+  | 'deep'
+  | 'robot'
+  | 'dark'
+  | 'custom';
+
+export interface RealtimeVoiceChangerPresetMetadata {
   schemaVersion: 1;
-  id?: string;
-  name?: string;
+  id: string;
+  name: string;
   description?: string;
-  macros?: Record<string, number>;
-  dsp?: Record<string, unknown>;
+  category: VoicePresetCategory;
 }
 
+export type RealtimeVoiceChangerPreset =
+  | (RealtimeVoiceChangerPresetMetadata & {
+      dsp: Record<string, unknown>;
+      macros?: never;
+    })
+  | (RealtimeVoiceChangerPresetMetadata & {
+      macros: Record<string, number>;
+      dsp?: never;
+    });
+
 export type RealtimeVoiceChangerConfigInput = VoicePresetId | RealtimeVoiceChangerPreset;
 
 /**

package/src/public_types_spectral.ts

@@ -1,5 +1,19 @@
 import type { ValidateOptions } from './validation';
 
+/**
+ * Per-frame voicing decision, one entry per `f0Hz` frame. A truthy or non-zero
+ * entry marks the frame voiced. The union covers what the analysis side hands
+ * back — `PitchResult.voicedFlag` is a `boolean[]` — as well as the typed and
+ * plain numeric arrays a caller may build directly, so a pitch track can be fed
+ * straight into pitch correction without a conversion step.
+ */
+export type VoicedFlags =
+  | Int32Array
+  | Uint8Array
+  | Float32Array
+  | readonly number[]
+  | readonly boolean[];
+
 /** Options for `pitchCorrectTimevarying`. All fields are optional. */
 export interface PitchCorrectOptions extends ValidateOptions {
   /** `'midi'` retunes toward `targetMidi`; `'scale'` snaps to the key. Default `'midi'`. */
@@ -20,8 +34,8 @@ export interface PitchCorrectOptions extends ValidateOptions {
   retuneSpeedMs?: number;
   /** Corrections below this are bypassed to preserve vibrato (cents). Default 20. */
   vibratoThresholdCents?: number;
-  /** Per-frame voiced flags (non-zero = voiced); omit to treat all frames as voiced. */
-  voiced?: Int32Array;
+  /** Per-frame voiced flags (truthy = voiced); omit to treat all frames as voiced. */
+  voiced?: VoicedFlags;
   /** Per-frame voicing probability in `[0, 1]`; omit to derive from `voiced`. */
   voicedProb?: Float32Array;
 }

package/src/quick_analysis.ts

@@ -29,7 +29,12 @@ import type {
 import { Mode, PitchClass } from './public_types';
 import type { ProgressCallback, WasmAcousticResult } from './sonare.js';
 import type { ValidateOptions } from './validation';
-import { assertNonNegativeInteger, assertSampleRate, assertSamples } from './validation';
+import {
+  assertFiniteScalar,
+  assertNonNegativeInteger,
+  assertSampleRate,
+  assertSamples,
+} from './validation';
 
 function requireModule() {
   return getSonareModule();
@@ -81,6 +86,7 @@ export interface ChordFunctionalAnalysisRequest extends DetectChordsRequest {
 /** Canonical request form for impulse-response analysis. */
 export interface AnalyzeImpulseResponseRequest extends SamplesRequest {
   nOctaveBands?: number;
+  minDecayDb?: number;
 }
 
 /** Canonical request form for acoustic analysis. */
@@ -435,23 +441,35 @@ export function analyzeImpulseResponse(
   samples: Float32Array,
   sampleRate?: number,
   nOctaveBands?: number,
+  minDecayDb?: number,
 ): AcousticResult;
 export function analyzeImpulseResponse(
   samples: Float32Array | AnalyzeImpulseResponseRequest,
   sampleRate = 48000,
   nOctaveBands = 6,
+  minDecayDb?: number,
 ): AcousticResult {
-  const request = samples instanceof Float32Array ? { samples, sampleRate, nOctaveBands } : samples;
+  const request =
+    samples instanceof Float32Array ? { samples, sampleRate, nOctaveBands, minDecayDb } : samples;
+  if (request.minDecayDb === null) {
+    throw new TypeError('analyzeImpulseResponse: minDecayDb must be a finite number');
+  }
+  const resolvedMinDecayDb = request.minDecayDb === undefined ? 30.0 : request.minDecayDb;
+  assertFiniteScalar('analyzeImpulseResponse', resolvedMinDecayDb, 'minDecayDb');
+  if (resolvedMinDecayDb <= 0) {
+    throw new RangeError('analyzeImpulseResponse: minDecayDb must be greater than zero');
+  }
   validateAnalysisInput(
     'analyzeImpulseResponse',
     request.samples,
     request.sampleRate ?? 48000,
     request,
   );
-  const result: WasmAcousticResult = requireModule().analyzeImpulseResponse(
+  const result: WasmAcousticResult = requireModule().analyzeImpulseResponseEx(
     request.samples,
     request.sampleRate ?? 48000,
     request.nOctaveBands ?? 6,
+    resolvedMinDecayDb,
   );
   return result;
 }

package/src/realtime_engine.ts

@@ -1,8 +1,8 @@
-import { panLawCode, panModeCode, sendTimingCode } from './codes';
+import { panLawCode, panModeCode, sendTimingCode, trackMonitorModeCode } from './codes';
 import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
 import type { ProjectMidiCcBinding, SynthPatch } from './project';
-import type { EqBand, PanLaw, PanMode, SendTiming } from './public_types';
+import type { EqBand, PanLawInput, PanMode, SendTiming } from './public_types';
 import type {
   WasmClipPageRequest,
   WasmEngineAutomationPoint,
@@ -78,6 +78,12 @@ export interface EngineTrackLane {
   sourceChannelLayout?: number;
 }
 
+/** Per-track cue/monitor tap mode: off, pre-fader listen, or after-fader listen. */
+export type EngineTrackMonitorMode = 'off' | 'pfl' | 'afl' | 0 | 1 | 2;
+
+/** Short alias for {@link EngineTrackMonitorMode}. */
+export type TrackMonitorMode = EngineTrackMonitorMode;
+
 export interface EngineBus {
   busId: number;
   gainDb?: number;
@@ -219,6 +225,11 @@ export class RealtimeEngine {
     this.native.setSoloMute(laneIndex, solo, mute, renderFrame);
   }
 
+  /** Queue a per-track PFL/AFL monitor tap mode change. */
+  setTrackMonitorMode(laneIndex: number, mode: EngineTrackMonitorMode, renderFrame = -1): void {
+    this.native.setTrackMonitorMode(laneIndex, trackMonitorModeCode(mode), renderFrame);
+  }
+
   setMidiClips(clips: readonly EngineMidiClipSchedule[]): void {
     this.native.setMidiClips(clips);
   }
@@ -831,7 +842,7 @@ export class RealtimeEngine {
   }
 
   /** Sets a track lane strip's pan law in realtime. */
-  setTrackStripPanLaw(trackId: number, panLaw: PanLaw | number): void {
+  setTrackStripPanLaw(trackId: number, panLaw: PanLawInput): void {
     this.native.setTrackStripPanLaw(trackId, panLawCode(panLaw));
   }