@libraz/libsonare 1.5.4 → 1.6.0

package/src/opfs_clip_pages.ts

@@ -8,12 +8,20 @@ export interface OpfsClipPageProviderOptions {
   dataOffsetBytes?: number;
   worker?: Worker;
   terminateWorkerOnClose?: boolean;
+  /** Internal bridge hook used to mirror a supplied page into an AudioWorklet. */
+  onPageSupplied?: (pageIndex: number, channels: Float32Array[]) => void;
+  /** Internal bridge hook used to mirror an eviction into an AudioWorklet. */
+  onPageCleared?: (pageIndex: number) => void;
+  /** Internal bridge hook called after the local provider is destroyed. */
+  onClose?: () => void;
 }
 
 export interface OpfsClipPageProviderBinding {
   provider: ClipPageProvider;
   supplyPage(pageIndex: number): Promise<boolean>;
   supplyRequest(request: ClipPageRequest): Promise<boolean>;
+  /** Evict one resident page from every configured consumer. */
+  clearPage?(pageIndex: number): void;
   close(): void;
 }
 
@@ -116,7 +124,15 @@ self.onmessage = async (event) => {
 
 export function createOpfsClipPageWorker(): Worker {
   const blob = new Blob([opfsClipPageWorkerSource], { type: 'text/javascript' });
-  return new Worker(URL.createObjectURL(blob));
+  const url = URL.createObjectURL(blob);
+  try {
+    return new Worker(url);
+  } finally {
+    // Worker construction retains the script URL internally; keeping this
+    // object URL alive after construction leaks one browser registration per
+    // attach/close cycle.
+    URL.revokeObjectURL(url);
+  }
 }
 
 export function createOpfsClipPageProvider(
@@ -166,6 +182,7 @@ export function createOpfsClipPageProvider(
     }
     try {
       provider.supply(response.pageIndex, channels);
+      options.onPageSupplied?.(response.pageIndex, channels);
     } catch {
       entry.resolve(false);
       return;
@@ -218,6 +235,13 @@ export function createOpfsClipPageProvider(
     supplyRequest(request: ClipPageRequest) {
       return supplyPage(Math.floor(request.sample / options.pageFrames));
     },
+    clearPage(pageIndex: number) {
+      if (closed) {
+        return;
+      }
+      provider.clear(pageIndex);
+      options.onPageCleared?.(pageIndex);
+    },
     close() {
       if (closed) {
         return;
@@ -229,6 +253,7 @@ export function createOpfsClipPageProvider(
       }
       pending.clear();
       provider.destroy();
+      options.onClose?.();
       if (ownsWorker) {
         worker.terminate();
       }

package/src/project.ts

@@ -10,6 +10,9 @@ export type {
   BuiltinSynthBinding,
   BuiltinSynthConfig,
   BuiltinSynthWaveform,
+  ExternalSeparatedStem,
+  ExternalSeparatedStemImportRequest,
+  ExternalSeparatedStemImportResult,
   MidiCcLearnOptions,
   ProjectAssistSidecar,
   ProjectAutomationCurve,
@@ -17,6 +20,7 @@ export type {
   ProjectAutomationPoint,
   ProjectBounceOptions,
   ProjectChordSymbol,
+  ProjectClip,
   ProjectClipCompSegment,
   ProjectClipDesc,
   ProjectClipFade,
@@ -37,8 +41,10 @@ export type {
   ProjectMidiRouteConfig,
   ProjectMidiRouteResult,
   ProjectNotePairValidation,
+  ProjectSource,
   ProjectTempoSegment,
   ProjectTimeSignatureSegment,
+  ProjectTrack,
   ProjectTrackDesc,
   ProjectTrackKind,
   ProjectWarpAnchor,
@@ -59,6 +65,7 @@ export type {
   SynthPatch,
 } from './project_types';
 export {
+  BUILTIN_SYNTH_WAVEFORMS,
   EXPECTED_PROJECT_ABI_VERSION,
   MarkerKind,
   SYNTH_BODY_TYPES,

package/src/project_class.ts

@@ -9,12 +9,15 @@ import {
 } from './project_internal';
 import type {
   BuiltinSynthBinding,
+  ExternalSeparatedStemImportRequest,
+  ExternalSeparatedStemImportResult,
   MidiCcLearnOptions,
   ProjectAssistSidecar,
   ProjectAutomationLaneDesc,
   ProjectAutomationPoint,
   ProjectBounceOptions,
   ProjectChordSymbol,
+  ProjectClip,
   ProjectClipCompSegment,
   ProjectClipDesc,
   ProjectClipFade,
@@ -32,9 +35,11 @@ import type {
   ProjectMidiRouteConfig,
   ProjectMidiRouteResult,
   ProjectNotePairValidation,
+  ProjectSource,
   ProjectTempoCandidate,
   ProjectTempoSegment,
   ProjectTimeSignatureSegment,
+  ProjectTrack,
   ProjectTrackDesc,
   ProjectTrackKind,
   ProjectWarpMapDesc,
@@ -337,6 +342,19 @@ export class Project {
     return this.native.addClip(desc);
   }
 
+  /** Import host-separated PCM through the normal audio-track/clip path. */
+  importExternalStems(
+    request: ExternalSeparatedStemImportRequest,
+  ): ExternalSeparatedStemImportResult {
+    return this.native.importExternalStems({
+      ...request,
+      stems: request.stems.map((stem) => ({
+        ...stem,
+        layout: stem.layout === 'mono' ? 1 : stem.layout === 'stereo' ? 2 : stem.layout,
+      })),
+    });
+  }
+
   /** Split captured loop-recording audio into takes and add one clip. */
   addLoopRecordingTakes(desc: ProjectLoopRecordingDesc): ProjectLoopRecordingResult {
     return this.native.addLoopRecordingTakes(desc);
@@ -391,7 +409,11 @@ export class Project {
    * Route a track's MIDI to host-instrument `destinationId` (0 = default). The
    * compiler stamps every MIDI clip on the track with this id so the engine
    * dispatches its events to the instrument registered for that destination.
-   * Routes through an undoable edit command.
+   * Routes through an undoable edit command. Builtin, NativeSynth, and SF2
+   * instruments retain source-track provenance inside a shared destination
+   * voice pool. With only zero-latency instruments bound, live lanes and
+   * channel-strip bounces remain aligned. Configure one live lane per source
+   * track that needs strip processing.
    */
   setTrackMidiDestination(trackId: number, destinationId: number): void {
     this.native.setTrackMidiDestination(trackId, destinationId);
@@ -449,7 +471,11 @@ export class Project {
     this.native.setMidiEvents(clipId, events);
   }
 
-  /** Import an in-memory SMF buffer; returns the first added clip id. */
+  /**
+   * Import an in-memory SMF buffer; returns the first added clip id.
+   * Malformed or partially truncated tracks are rejected instead of installing
+   * a silently shortened clip.
+   */
   importSmf(data: Uint8Array): number {
     return this.native.importSmf(data);
   }
@@ -498,7 +524,10 @@ export class Project {
     this.native.setProgramOnChannel(clipId, group, channel, program, bank);
   }
 
-  /** Destructively bake a MIDI-FX chain into a clip's stored MIDI events. */
+  /**
+   * Destructively bake a MIDI-FX chain into all stored events. Large clips are
+   * drained without truncation; failure leaves the original clip unchanged.
+   */
   bakeMidiFx(clipId: number, configJson: string): void {
     this.native.bakeMidiFx(clipId, configJson);
   }
@@ -510,9 +539,9 @@ export class Project {
 
   /**
    * Pre-flight check for hanging / unmatched notes in a MIDI clip: reports
-   * whether every note-on has a matching note-off (FIFO per channel+note).
-   * Useful before bouncing to catch a stuck note. Throws if `clipId` is unknown
-   * or not a MIDI clip.
+   * whether every note-on in the exported half-open playback window has a
+   * matching note-off (FIFO per group+channel+note). Useful before bouncing to
+   * catch a stuck note. Throws if `clipId` is unknown or not a MIDI clip.
    */
   validateMidiNotes(clipId: number): ProjectNotePairValidation {
     return this.native.validateMidiNotes(clipId);
@@ -678,6 +707,21 @@ export class Project {
     this.native.setClipFade(clipId, fadeIn, fadeOut);
   }
 
+  /** Audio source ids that need decoded PCM after deserialization. */
+  unresolvedAudioSourceIds(): number[] {
+    return this.native.unresolvedAudioSourceIds();
+  }
+
+  /** Register decoded interleaved PCM for an existing audio source (undoable). */
+  setSourceAudio(
+    sourceId: number,
+    audio: Float32Array,
+    channels: number,
+    sampleRate: number,
+  ): void {
+    this.native.setSourceAudio(sourceId, audio, channels, sampleRate);
+  }
+
   /** 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);
@@ -732,7 +776,7 @@ export class Project {
     this.native.setTrackRoute(trackId, channelStripRef ?? '', outputTarget ?? '');
   }
 
-  /** Append an automation lane to a track; returns the lane index (undoable). */
+  /** 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,
@@ -740,17 +784,21 @@ export class Project {
     });
   }
 
-  /** Replace an existing automation lane in place (undoable). */
-  editAutomationLane(trackId: number, laneIndex: number, desc: ProjectAutomationLaneDesc): void {
-    this.native.editAutomationLane(trackId, laneIndex, {
+  /** Replace the lane identified by its stable target parameter id (undoable). */
+  editAutomationLane(
+    trackId: number,
+    targetParamId: number,
+    desc: ProjectAutomationLaneDesc,
+  ): void {
+    this.native.editAutomationLane(trackId, targetParamId, {
       targetParamId: desc.targetParamId,
       points: desc.points,
     });
   }
 
-  /** Remove an automation lane from a track (undoable). */
-  removeAutomationLane(trackId: number, laneIndex: number): void {
-    this.native.removeAutomationLane(trackId, laneIndex);
+  /** Remove the lane identified by its stable target parameter id (undoable). */
+  removeAutomationLane(trackId: number, targetParamId: number): void {
+    this.native.removeAutomationLane(trackId, targetParamId);
   }
 
   /** Replace the project's key annotation stream (undoable). */
@@ -834,6 +882,19 @@ export class Project {
     return this.native.markerByIndex(index);
   }
 
+  /** Read a stored project track by 0-based index. */
+  trackByIndex(index: number): ProjectTrack {
+    return this.native.trackByIndex(index);
+  }
+  /** Read a stored project clip by 0-based index. */
+  clipByIndex(index: number): ProjectClip {
+    return this.native.clipByIndex(index);
+  }
+  /** Read a stored project source by 0-based index. */
+  sourceByIndex(index: number): ProjectSource {
+    return this.native.sourceByIndex(index);
+  }
+
   /** Number of markers in the project. */
   markerCount(): number {
     return this.native.markerCount();

package/src/project_internal.ts

@@ -1,3 +1,4 @@
+import { resolveEnumOrdinal } from './codes';
 import { getSonareModule } from './module_state';
 import type {
   BuiltinSynthBinding,
@@ -5,6 +6,7 @@ import type {
   ProjectAutomationPoint,
   ProjectBounceOptions,
   ProjectChordSymbol,
+  ProjectClip,
   ProjectClipCompSegment,
   ProjectClipDesc,
   ProjectClipFade,
@@ -21,9 +23,11 @@ import type {
   ProjectMidiRouteConfig,
   ProjectMidiRouteResult,
   ProjectNotePairValidation,
+  ProjectSource,
   ProjectTempoCandidate,
   ProjectTempoSegment,
   ProjectTimeSignatureSegment,
+  ProjectTrack,
   ProjectTrackKind,
   ProjectWarpMapDesc,
   ProjectWarpMode,
@@ -41,6 +45,7 @@ export interface WasmProject {
   setSampleRate: (sampleRate: number) => void;
   addTrack: (desc: { kind?: number | string; name?: string }) => number;
   addClip: (desc: ProjectClipDesc) => number;
+  importExternalStems: (request: unknown) => { trackIds: number[]; clipIds: number[] };
   addLoopRecordingTakes: (desc: ProjectLoopRecordingDesc) => ProjectLoopRecordingResult;
   addMidiClip: (startPpq: number, lengthPpq: number) => ProjectMidiClipResult;
   splitClip: (clipId: number, splitPpq: number) => number;
@@ -108,6 +113,13 @@ export interface WasmProject {
   removeClip: (clipId: number) => void;
   setClipGain: (clipId: number, gain: number) => void;
   setClipFade: (clipId: number, fadeIn: ProjectClipFade, fadeOut: ProjectClipFade) => void;
+  unresolvedAudioSourceIds: () => number[];
+  setSourceAudio: (
+    sourceId: number,
+    audio: Float32Array,
+    channels: number,
+    sampleRate: number,
+  ) => void;
   setClipTakes: (
     clipId: number,
     takes: ReadonlyArray<ProjectClipTake>,
@@ -131,10 +143,10 @@ export interface WasmProject {
   ) => number;
   editAutomationLane: (
     trackId: number,
-    laneIndex: number,
+    targetParamId: number,
     desc: { targetParamId: number; points: ReadonlyArray<ProjectAutomationPoint> },
   ) => void;
-  removeAutomationLane: (trackId: number, laneIndex: number) => void;
+  removeAutomationLane: (trackId: number, targetParamId: number) => void;
   annotateKeys: (keys: ReadonlyArray<ProjectKeySegment>) => void;
   annotateChords: (chords: ReadonlyArray<ProjectChordSymbol>) => void;
   setAssistSidecar: (
@@ -154,6 +166,9 @@ export interface WasmProject {
   setMarker: (markerId: number, ppq: number, name: string) => number;
   setMarkerEx: (marker: ProjectMarker) => number;
   markerByIndex: (index: number) => ProjectMarker;
+  trackByIndex: (index: number) => ProjectTrack;
+  clipByIndex: (index: number) => ProjectClip;
+  sourceByIndex: (index: number) => ProjectSource;
   markerCount: () => number;
   trackCount: () => number;
   clipCount: () => number;
@@ -307,37 +322,17 @@ export function assertProjectMidiEvents(
 }
 
 export function projectTrackKindValue(kind: ProjectTrackKind | undefined): number {
-  if (kind === undefined || kind === 'audio') {
-    return 0;
-  }
-  if (kind === 'midi') {
-    return 1;
-  }
-  if (kind === 'aux') {
-    return 2;
-  }
-  return kind;
+  return resolveEnumOrdinal(kind ?? 'audio', { audio: 0, midi: 1, aux: 2 }, 'project track kind');
 }
 
 export function projectWarpModeValue(mode: ProjectWarpMode | undefined): number {
-  if (mode === undefined || mode === 'off') {
-    return 0;
-  }
-  if (mode === 'repitch') {
-    return 1;
-  }
-  if (mode === 'tempo-sync') {
-    return 2;
-  }
-  return mode;
+  return resolveEnumOrdinal(
+    mode ?? 'off',
+    { off: 0, repitch: 1, 'tempo-sync': 2 },
+    'project warp mode',
+  );
 }
 
 export function projectLoopModeValue(mode: ProjectLoopMode | undefined): number {
-  if (mode === undefined || mode === 'off') {
-    return 0;
-  }
-  if (mode === 'loop') {
-    return 1;
-  }
-  return mode;
+  return resolveEnumOrdinal(mode ?? 'off', { off: 0, loop: 1 }, 'project loop mode');
 }

package/src/project_types.ts

@@ -25,6 +25,29 @@ export interface ProjectBounceOptions {
   instrumentLatencySamples?: number;
 }
 
+/** One decoded output from a host-owned source-separation model. */
+export interface ExternalSeparatedStem {
+  name: string;
+  /** Optional host metadata; it does not change DSP. */
+  role?: string;
+  layout: 'mono' | 'stereo' | 1 | 2;
+  planarSamples: Float32Array[];
+  /** Absolute project-rate frame at which this stem begins. */
+  startFrame?: number;
+}
+
+/** Request for {@link Project.importExternalStems}. */
+export interface ExternalSeparatedStemImportRequest {
+  sampleRate: number;
+  stems: ExternalSeparatedStem[];
+}
+
+/** Ids of the normal tracks and clips created by the import. */
+export interface ExternalSeparatedStemImportResult {
+  trackIds: number[];
+  clipIds: number[];
+}
+
 /**
  * Marker kind ordinals. Mirrors `SonareMarkerKind` in `src/sonare_c_types.h`;
  * the values are part of the ABI and must not be renumbered.
@@ -53,17 +76,47 @@ export interface ProjectMarker {
   keyMinor?: boolean;
 }
 
+/** Read-only stored project track returned by {@link Project.trackByIndex}. */
+export interface ProjectTrack {
+  id: number;
+  kind: number;
+  midiDestinationId: number;
+  gain: number;
+  pan: number;
+  mute: boolean;
+  solo: boolean;
+  name: string;
+}
+
+/** Read-only stored project clip returned by {@link Project.clipByIndex}. */
+export interface ProjectClip {
+  id: number;
+  trackId: number;
+  sourceId: number;
+  sourceKind: number;
+  startPpq: number;
+  lengthPpq: number;
+  sourceOffsetPpq: number;
+  gain: number;
+  loopMode: number;
+  loopLengthPpq: number;
+}
+
+/** Read-only stored project source returned by {@link Project.sourceByIndex}. */
+export interface ProjectSource {
+  id: number;
+  kind: number;
+  channelCount: number;
+  storageHandleId: number;
+  sampleRateHint: number;
+  nameOrUri: string;
+}
+
+/** Names accepted by the minimal built-in oscillator synth. */
+export const BUILTIN_SYNTH_WAVEFORMS = ['sine', 'saw', 'sawtooth', 'square', 'triangle'] as const;
+
 /** Oscillator waveform for the built-in synth. */
-export type BuiltinSynthWaveform =
-  | 'sine'
-  | 'saw'
-  | 'sawtooth'
-  | 'square'
-  | 'triangle'
-  | 0
-  | 1
-  | 2
-  | 3;
+export type BuiltinSynthWaveform = (typeof BUILTIN_SYNTH_WAVEFORMS)[number] | 0 | 1 | 2 | 3;
 
 /**
  * Built-in synth patch + MIDI routing for
@@ -111,6 +164,8 @@ export interface Sf2InstrumentConfig {
   gain?: number;
   /** Max simultaneous voices (0 => 48, clamped to [1, 64]). */
   polyphony?: number;
+  /** Prefer dedicated physical models for covered melodic GM programs. Defaults to false; drums stay SF2-first. */
+  preferModelForModeledFamilies?: boolean;
 }
 
 /** Source backend a resolved MIDI program renders through. */
@@ -198,6 +253,7 @@ export const SYNTH_MOD_DESTINATIONS = [
 export interface SynthEnumTables {
   engineModes: string[];
   waveforms: string[];
+  builtinWaveforms: string[];
   filterModels: string[];
   filterOutputs: string[];
   bodyTypes: string[];
@@ -312,8 +368,11 @@ export type ProjectFadeCurve =
   | 'equal-power'
   | 'equal_power'
   | 'equalPower'
+  | 'equalpower'
   | 'exponential'
+  | 'exp'
   | 'logarithmic'
+  | 'log'
   | 0
   | 1
   | 2

package/src/public_types.ts

@@ -4,3 +4,71 @@ export * from './public_types_mixing';
 export * from './public_types_music';
 export * from './public_types_realtime';
 export * from './public_types_spectral';
+
+/** Runtime capabilities reported by the loaded libsonare build. */
+export interface SonareCapabilities {
+  version: string;
+  abi: {
+    project: number;
+    engine: number;
+  };
+  platform: string;
+  features: {
+    mastering: boolean;
+    mixing: boolean;
+    fx: boolean;
+    ffmpeg: boolean;
+  };
+  decode: {
+    builtin: string[];
+    ffmpeg: string[];
+  };
+  simd: string;
+  hardwareConcurrency: number;
+}
+
+/** One parameter descriptor in the cross-surface capability catalog. */
+export interface CapabilityCatalogParameter {
+  name: string;
+  id: number;
+  rtSafe: boolean;
+  type: 'boolean' | 'number';
+  min: number | null;
+  max: number | null;
+  default: boolean | number | null;
+  unit: string | null;
+}
+
+/** One named mastering processor and its host-facing capabilities. */
+export interface CapabilityCatalogProcessor {
+  id: string;
+  kind: 'realtime' | 'offline' | 'pair';
+  realtimeInsertable: boolean;
+  stereoOnly: boolean;
+  latencySamples: number;
+  tailSamples: number;
+  /** Coarse realtime work estimate, or null when the processor is not an insert. */
+  realtimeCost: 'low' | 'moderate' | 'high' | null;
+  channelPolicy: 'multichannel' | 'stereoPairOnly' | 'perChannel' | 'passthrough';
+  category: string;
+  params: CapabilityCatalogParameter[];
+}
+
+/** Built-in preset names grouped by feature family. */
+export interface CapabilityCatalogPresets {
+  mastering: string[];
+  synth: string[];
+  mixingScene: string[];
+  voiceChanger: string[];
+}
+
+/** Complete runtime catalog exposed by {@link capabilityCatalog}. */
+export interface CapabilityCatalog {
+  version: string;
+  abi: SonareCapabilities['abi'];
+  processors: CapabilityCatalogProcessor[];
+  presets: CapabilityCatalogPresets;
+}
+
+/** Synchronous progress callback for offline operations. Its return value is ignored. */
+export type ProgressCallback = (progress: number, stage: string) => void;

package/src/public_types_mastering.ts

@@ -138,6 +138,8 @@ export interface MasteringResult {
   inputLufs: number;
   outputLufs: number;
   appliedGainDb: number;
+  /** True when peak headroom prevented the requested LUFS target. */
+  loudnessTargetLimited?: boolean;
   latencySamples?: number;
 }
 
@@ -329,6 +331,7 @@ export interface MasteringChainConfig {
     monoMaker?: {
       enabled?: boolean;
       amount?: number;
+      frequencyHz?: number;
     };
   };
   maximizer?: {
@@ -391,6 +394,26 @@ export interface StageGainReduction {
   gainReductionDb: number;
 }
 
+/** Existing EBU R128 measurements captured before or after mastering. */
+export interface MasteringLoudnessSummary {
+  integratedLufs: number;
+  maxMomentaryLufs: number;
+  maxShortTermLufs: number;
+  truePeakDbtp: number;
+  loudnessRange: number;
+}
+
+/** Compact explanation of how an offline mastering chain changed a program. */
+export interface MasteringReport {
+  before: MasteringLoudnessSummary;
+  after: MasteringLoudnessSummary;
+  appliedGainDb: number;
+  maxGainReductionDb: number;
+  loudnessTargetLimited: boolean;
+  /** 32 logarithmically-spaced after-minus-before spectral energy deltas (dB). */
+  bandEnergyDeltaDb: Float32Array;
+}
+
 export interface MasteringChainResult {
   /** Latency-compensated offline output; no separate latency field is reported. */
   samples: Float32Array;
@@ -407,8 +430,11 @@ export interface MasteringChainResult {
   outputTruePeakDbtp: number;
   /** EBU Tech 3342 Loudness Range of the output (LU). */
   outputLra: number;
+  /** True when peak headroom prevented the requested LUFS target. */
+  loudnessTargetLimited: boolean;
   /** Per-stage gain reductions for the dynamics/maximizer stages (a subset of `stages`). */
   stageGainReductions: StageGainReduction[];
+  report: MasteringReport;
 }
 
 export interface MasteringChainStereoResult {
@@ -422,7 +448,9 @@ export interface MasteringChainStereoResult {
   /** See {@link MasteringChainResult} for field semantics. */
   outputTruePeakDbtp: number;
   outputLra: number;
+  loudnessTargetLimited: boolean;
   stageGainReductions: StageGainReduction[];
+  report: MasteringReport;
 }
 
 /**

package/src/public_types_mixing.ts

@@ -1,4 +1,11 @@
-export type PanMode = 'balance' | 'stereoPan' | 'stereo-pan' | 'dualPan' | 'dual-pan' | number;
+export type PanMode =
+  | 'balance'
+  | 'pan'
+  | 'stereoPan'
+  | 'stereo-pan'
+  | 'dualPan'
+  | 'dual-pan'
+  | number;
 
 /**
  * Surround pan position for a strip feeding a >2-channel bus. Phase 1 honors
@@ -77,7 +84,9 @@ export type AutomationCurve = 'linear' | 'exponential' | 'hold' | 's-curve';
 
 /**
  * Pan law applied when computing left/right gains from a pan position
- * (see {@link Mixer.setPanLaw}). Maps to the underlying integer code.
+ * (see {@link Mixer.setPanLaw}). On mono strips it changes the centre gain;
+ * on stereo Balance strips it changes only the far-channel taper, while centre
+ * remains unity. Maps to the underlying integer code.
  */
 export type PanLaw = 'const3dB' | 'const4.5dB' | 'const6dB' | 'linear0dB';