@libraz/libsonare 1.5.5 → 1.6.0

package/src/mastering_chain.ts

@@ -22,6 +22,7 @@ export interface MasteringChainRequest {
   sampleRate?: number;
   config?: MasteringChainConfig;
   onProgress?: ProgressCallback;
+  cancel?: () => boolean;
 }
 
 export interface MasteringChainStereoRequest {
@@ -30,6 +31,7 @@ export interface MasteringChainStereoRequest {
   sampleRate?: number;
   config?: MasteringChainConfig;
   onProgress?: ProgressCallback;
+  cancel?: () => boolean;
 }
 
 /** Canonical request form for one-shot preset mastering. */
@@ -39,6 +41,7 @@ export interface MasterAudioRequest {
   preset?: MasteringPreset;
   overrides?: MasteringChainConfig;
   onProgress?: ProgressCallback;
+  cancel?: () => boolean;
 }
 
 /** Canonical request form for one-shot stereo preset mastering. */
@@ -49,6 +52,7 @@ export interface MasterAudioStereoRequest {
   preset?: MasteringPreset;
   overrides?: MasteringChainConfig;
   onProgress?: ProgressCallback;
+  cancel?: () => boolean;
 }
 
 function masterAudioRequest(
@@ -114,12 +118,13 @@ export function masteringChain(
 ): MasteringChainResult {
   const request =
     samples instanceof Float32Array ? { samples, sampleRate, config, onProgress } : samples;
-  if (request.onProgress) {
+  if (request.onProgress || request.cancel) {
     return requireModule().masteringChainWithProgress(
       request.samples,
       request.sampleRate ?? 22050,
       canonicalChainConfig(request.config ?? {}),
-      request.onProgress,
+      request.onProgress ?? (() => {}),
+      request.cancel ?? (() => false),
     );
   }
   return requireModule().masteringChain(
@@ -162,13 +167,14 @@ export function masteringChainStereo(
   if (request.left.length !== request.right.length) {
     throw new Error('Stereo channel lengths must match.');
   }
-  if (request.onProgress) {
+  if (request.onProgress || request.cancel) {
     return requireModule().masteringChainStereoWithProgress(
       request.left,
       request.right,
       request.sampleRate ?? 22050,
       canonicalChainConfig(request.config ?? {}),
-      request.onProgress,
+      request.onProgress ?? (() => {}),
+      request.cancel ?? (() => false),
     );
   }
   return requireModule().masteringChainStereo(
@@ -213,6 +219,7 @@ export function masteringChainWithProgress(
     request.sampleRate ?? 22050,
     canonicalChainConfig(request.config ?? {}),
     request.onProgress,
+    request.cancel ?? (() => false),
   );
 }
 
@@ -259,6 +266,7 @@ export function masteringChainStereoWithProgress(
     request.sampleRate ?? 22050,
     canonicalChainConfig(request.config ?? {}),
     request.onProgress,
+    request.cancel ?? (() => false),
   );
 }
 
@@ -298,13 +306,14 @@ export function masterAudio(
 ): MasteringChainResult {
   const request = masterAudioRequest(samples, sampleRate, presetName, overrides, onProgress);
   const flat = flattenChainConfig(request.overrides ?? {});
-  if (request.onProgress) {
+  if (request.onProgress || request.cancel) {
     return requireModule().masterAudioWithProgress(
       request.preset ?? 'pop',
       request.samples,
       request.sampleRate ?? 22050,
       flat,
-      request.onProgress,
+      request.onProgress ?? (() => {}),
+      request.cancel ?? (() => false),
     );
   }
   return requireModule().masterAudio(
@@ -355,14 +364,15 @@ export function masterAudioStereo(
   if (request.left.length !== request.right.length) {
     throw new Error('Stereo channel lengths must match.');
   }
-  if (request.onProgress) {
+  if (request.onProgress || request.cancel) {
     return requireModule().masterAudioStereoWithProgress(
       request.preset ?? 'pop',
       request.left,
       request.right,
       request.sampleRate ?? 22050,
       flat,
-      request.onProgress,
+      request.onProgress ?? (() => {}),
+      request.cancel ?? (() => false),
     );
   }
   return requireModule().masterAudioStereo(
@@ -405,6 +415,7 @@ export function masterAudioWithProgress(
     request.sampleRate ?? 22050,
     flattenChainConfig(request.overrides ?? {}),
     request.onProgress,
+    request.cancel ?? (() => false),
   );
 }
 
@@ -451,5 +462,6 @@ export function masterAudioStereoWithProgress(
     request.sampleRate ?? 22050,
     flattenChainConfig(request.overrides ?? {}),
     request.onProgress,
+    request.cancel ?? (() => false),
   );
 }

package/src/mastering_core.ts

@@ -186,6 +186,9 @@ export type MasteringChannelPolicy =
   | 'perChannel'
   | 'passthrough';
 
+/** Coarse algorithmic work estimate for a realtime insert; not a benchmark. */
+export type MasteringRealtimeCost = 'low' | 'moderate' | 'high';
+
 /** One processor's realtime/offline/pair classification in the catalog. */
 export interface MasteringProcessorCatalogEntry {
   /** Processor id (the name used for scene inserts / named processors). */
@@ -210,6 +213,8 @@ export interface MasteringProcessorCatalogEntry {
    * offline, dry-only, and no-tail processors.
    */
   tailSamples: number;
+  /** Coarse realtime work estimate, or null when the processor is not an insert. */
+  realtimeCost: MasteringRealtimeCost | null;
   /**
    * How the mixer wraps the processor on a >2-channel (surround) bus insert:
    * "multichannel" (one full-buffer call) or "stereoPairOnly" (front L/R pair,

package/src/mastering_dynamics.ts

@@ -107,7 +107,13 @@ export function masteringDynamicsCompressor(
     typeof request.detector === 'string'
       ? COMPRESSOR_DETECTOR_MAP[request.detector]
       : request.detector;
-  const opts: Record<string, unknown> = { ...request };
+  // Preserve inherited option values as well as own properties. The embind
+  // boundary's hasProperty() intentionally follows the prototype chain, so a
+  // spread copy here would otherwise erase values before C++ can read them.
+  const opts: Record<string, unknown> = Object.assign(
+    Object.create(Object.getPrototypeOf(request)) as Record<string, unknown>,
+    request,
+  );
   if (detector !== undefined) {
     opts.detector = detector;
   }

package/src/metering.ts

@@ -1,3 +1,4 @@
+import { ErrorCode, SonareError } from './errors';
 import { getSonareModule } from './module_state';
 import type { ValidateOptions } from './validation';
 import { assertSamples } from './validation';
@@ -17,7 +18,11 @@ function assertOversampleFactor(fnName: string, factor: number): void {
     normalized > 16 ||
     (normalized & (normalized - 1)) !== 0
   ) {
-    throw new RangeError(`${fnName}: oversampleFactor must be 0 or a power of two from 1 to 16`);
+    throw new SonareError(
+      ErrorCode.InvalidParameter,
+      'InvalidParameter',
+      `${fnName}: oversampleFactor must be 0 or a power of two from 1 to 16`,
+    );
   }
 }
 

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);
@@ -685,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);
@@ -739,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,
@@ -747,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). */
@@ -841,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