@libraz/libsonare 1.8.1 → 1.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "type": "module",
   "packageManager": "yarn@4.18.0",
   "description": "Audio analysis, mastering, mixing, and MIDI synthesis in WebAssembly",
@@ -23,6 +23,10 @@
       "types": "./dist/worker.d.ts",
       "import": "./dist/worker.js"
     },
+    "./vocal-edit-worker": {
+      "types": "./dist/vocal_edit_worker.d.ts",
+      "import": "./dist/vocal_edit_worker.js"
+    },
     "./wasm": "./dist/sonare.wasm",
     "./schemas/realtime-voice-changer-preset.schema.json": "./dist/schemas/realtime-voice-changer-preset.schema.json",
     "./schemas/realtime-voice-changer-preset-pack.schema.json": "./dist/schemas/realtime-voice-changer-preset-pack.schema.json",
@@ -60,6 +64,7 @@
     "test:browser": "node scripts/audio-worklet-smoke.mjs",
     "test:browser:worker": "node scripts/offline-worker-smoke.mjs",
     "test:browser:boundary": "node scripts/boundary-smoke.mjs",
+    "test:browser:vocal-worker": "node scripts/vocal-edit-worker-smoke.mjs",
     "test:watch": "vitest",
     "prepublishOnly": "yarn clean && cp ../../LICENSE LICENSE && cp ../../NOTICE NOTICE && yarn build && yarn lint && yarn test && yarn test:types"
   },

package/src/index.ts

@@ -546,6 +546,9 @@ export type {
   MidiCcLearnOptions,
   MpeDimension,
   NoteTracking,
+  PartRig,
+  PartRigInsert,
+  PartRigMode,
   ProjectAssistSidecar,
   ProjectAssistSidecarInput,
   ProjectAutomationCurve,
@@ -560,6 +563,7 @@ export type {
   ProjectClipFade,
   ProjectClipTake,
   ProjectCompileResult,
+  ProjectCompileTimelineResult,
   ProjectFadeCurve,
   ProjectKeySegment,
   ProjectLoopMode,
@@ -617,10 +621,13 @@ export {
   MarkerKind,
   MPE_DIMENSIONS,
   NOTE_TRACKINGS,
+  PART_RIG_ALL_PARTS,
+  PART_RIG_MODES,
   PROJECT_AUTOMATION_TARGET_OPAQUE,
   PROJECT_AUTOMATION_TARGET_TRACK_FADER_DB,
   PROJECT_AUTOMATION_TARGET_TRACK_PAN,
   Project,
+  ProjectTimeline,
   projectAbiVersion,
   SAMPLE_KEY_TRACKS,
   SAMPLE_LOOP_MODES,
@@ -835,6 +842,7 @@ export {
   PitchClass,
   SectionType,
 } from './public_types';
+export type * from './public_types_vocal_edit';
 export type {
   AnalyzeBpmRequest,
   AnalyzeDynamicsRequest,
@@ -959,6 +967,29 @@ export {
 export type { TranscribeRequest } from './transcribe';
 export { transcribe } from './transcribe';
 export type { ValidateOptions } from './validation';
+export {
+  createVocalEditSession,
+  restoreVocalEditSession,
+  VocalEditDraft,
+  VocalEditSession,
+  VocalRenderJob,
+  VocalRenderSnapshot,
+  vocalEditApiVersion,
+  vocalEditAvailable,
+} from './vocal_edit';
+export type {
+  VocalEditWorker,
+  VocalEditWorkerCallOptions,
+  VocalEditWorkerClientOptions,
+  VocalEditWorkerTransferOptions,
+} from './vocal_edit_worker_client';
+export {
+  VocalEditWorkerClient,
+  VocalEditWorkerSession,
+  VocalEditWorkerStaleResultError,
+  VocalEditWorkerTask,
+} from './vocal_edit_worker_client';
+export type * from './vocal_edit_worker_protocol';
 export type {
   BindWebMidiOptions,
   WebMidiBinding,
@@ -1154,3 +1185,5 @@ export function realtimeVoiceChangerPresetConfig(
 // ============================================================================
 
 export { PitchClass as Pitch } from './public_types';
+
+export type * from './public_types_vocal_project';

package/src/instrument_types.ts

@@ -228,6 +228,16 @@ export const CONTROLLER_AXES = [
  */
 export const ARTICULATIONS = ['poly', 'mono-retrigger', 'mono-legato'] as const;
 
+/**
+ * How a part's signal path is built. `'bank'` keeps whatever the instrument's
+ * own bank/program selection resolves to, `'none'` bypasses the rig stage, and
+ * `'chain'` replaces it with an explicit insert chain.
+ */
+export const PART_RIG_MODES = ['bank', 'none', 'chain'] as const;
+
+/** The `part` value that addresses a destination's default instead of one part (0-15). */
+export const PART_RIG_ALL_PARTS = 0xff;
+
 /** The three dimensions MPE carries per note ({@link RealtimeEngine.setControllerNoteTracking}). */
 export const MPE_DIMENSIONS = ['bend', 'pressure', 'timbre'] as const;
 
@@ -380,6 +390,23 @@ export type ControllerAxis = (typeof CONTROLLER_AXES)[number];
 /** Per-channel note-overlap rule ({@link RealtimeEngine.setArticulation}). */
 export type Articulation = (typeof ARTICULATIONS)[number];
 
+/** How a part's rig is built ({@link PART_RIG_MODES}). */
+export type PartRigMode = (typeof PART_RIG_MODES)[number];
+
+/** One stage of a `'chain'` part rig: a processor name and its parameters. */
+export interface PartRigInsert {
+  processor: string;
+  /** Processor parameters, as an object or an already-serialized JSON object string. */
+  params?: Record<string, unknown> | string;
+}
+
+/** A part rig as stored on a project ({@link Project.getPartRig}). */
+export interface PartRig {
+  mode: PartRigMode;
+  /** Present for `'chain'` only; `params` is the parsed parameter object. */
+  inserts?: { processor: string; params: Record<string, unknown> }[];
+}
+
 /** One per-note MPE dimension ({@link MPE_DIMENSIONS}). */
 export type MpeDimension = (typeof MPE_DIMENSIONS)[number];
 
@@ -582,9 +609,8 @@ export interface SynthPatch {
    * whose per-note kit patch replaces this whole section and never reads it.
    *
    * Also automatable under this same name through
-   * {@link RealtimeEngine.resolveInstrumentAutomationId}; it is one of the names
-   * that reaches a voice that is already sounding, rather than waiting for the
-   * next note.
+   * {@link RealtimeEngine.resolveInstrumentAutomationId}; it reaches
+   * already-sounding voices from the next processed block.
    */
   pitchOffsetCents?: number;
   ampAttackMs?: number;

package/src/mastering_core.ts

@@ -924,11 +924,12 @@ export function masteringAssistantSuggestChainStereo(
 /**
  * Mastering assistant profile of a stereo pair, as shared JSON.
  *
- * Only the `loudness` block is measured from the two channels: integrated LUFS
+ * The `loudness` block is measured from the two channels: integrated LUFS
  * and LRA come from the channel-summed program and the true peak is the larger
  * of the two. The spectral, dynamics and tempo fields describe shape and timing
  * rather than absolute level and are measured on the downmix, which keeps them
- * comparable with {@link masteringAudioProfile}.
+ * comparable with {@link masteringAudioProfile}. Defect detectors run on each
+ * channel and their results are aggregated.
  */
 export function masteringAudioProfileStereo(request: MasteringStereoParamsRequest): string {
   return requireModule().masteringAudioProfileStereo(

package/src/mixer.ts

@@ -504,8 +504,8 @@ export class Mixer {
   }
 
   /**
-   * Set a per-strip channel delay in samples. This changes the strip's reported
-   * latency; recompile to re-run latency compensation.
+   * Set a per-strip channel delay in samples, moving the strip later relative to
+   * the others. It is not latency: latency compensation does not undo it.
    */
   setChannelDelaySamples(stripIndex: number, delaySamples: number): void {
     this.mixer.setChannelDelaySamples(stripIndex, delaySamples);

package/src/project.ts

@@ -8,6 +8,9 @@ export type {
   ControllerInput,
   MpeDimension,
   NoteTracking,
+  PartRig,
+  PartRigInsert,
+  PartRigMode,
   SampleDesc,
   SampleDescLoopMode,
   SampleKeyTrack,
@@ -35,6 +38,8 @@ export {
   CONTROLLER_INPUTS,
   MPE_DIMENSIONS,
   NOTE_TRACKINGS,
+  PART_RIG_ALL_PARTS,
+  PART_RIG_MODES,
   SAMPLE_KEY_TRACKS,
   SAMPLE_LOOP_MODES,
   SYNTH_BODY_TYPES,
@@ -46,7 +51,7 @@ export {
   SYNTH_OSC_WAVEFORMS,
   SYNTH_RETRIGGERS,
 } from './instrument_types';
-export { Project } from './project_class';
+export { Project, ProjectTimeline } from './project_class';
 export {
   controllerProfileNames,
   projectAbiVersion,
@@ -79,6 +84,7 @@ export type {
   ProjectClipFade,
   ProjectClipTake,
   ProjectCompileResult,
+  ProjectCompileTimelineResult,
   ProjectDeserializeResult,
   ProjectDiagnostic,
   ProjectFadeCurve,
@@ -121,4 +127,5 @@ export {
   PROJECT_AUTOMATION_TARGET_TRACK_FADER_DB,
   PROJECT_AUTOMATION_TARGET_TRACK_PAN,
 } from './project_types';
+export type * from './public_types_vocal_project';
 export { SampleBank } from './sample_bank';

package/src/project_class.ts

@@ -1,5 +1,8 @@
 import type {
   BuiltinSynthBinding,
+  PartRig,
+  PartRigInsert,
+  PartRigMode,
   Sf2InstrumentConfig,
   Sf2ProgramStatus,
   SynthPatch,
@@ -7,6 +10,8 @@ import type {
 import {
   assertProjectMidiEvents,
   normalizeSynthInstrument,
+  partRigFromNative,
+  partRigInsertsJson,
   projectAutomationPointValue,
   projectAutomationTargetKindValue,
   projectLoopModeValue,
@@ -14,7 +19,10 @@ import {
   projectModule,
   projectTrackKindValue,
   projectWarpModeValue,
+  registerProjectTimeline,
+  unregisterProjectTimeline,
   type WasmProject,
+  type WasmProjectTimeline,
 } from './project_internal';
 import type {
   ExternalSeparatedStemImportRequest,
@@ -33,6 +41,7 @@ import type {
   ProjectClipFade,
   ProjectClipTake,
   ProjectCompileResult,
+  ProjectCompileTimelineResult,
   ProjectDeserializeResult,
   ProjectKeySegment,
   ProjectLoopMode,
@@ -60,6 +69,13 @@ import type {
   ProjectWarpMapDesc,
   ProjectWarpMode,
 } from './project_types';
+import type {
+  ProjectVocalEditApplyRequest,
+  ProjectVocalEditApplyResult,
+  ProjectVocalEditDependency,
+  ProjectVocalOriginalSource,
+  ProjectVocalRehydrateItem,
+} from './public_types_vocal_project';
 import {
   assertBoundedInteger,
   assertNibble,
@@ -67,6 +83,11 @@ import {
   assertSamples,
   assertU7,
 } from './validation';
+import {
+  projectApplyVocalEdit,
+  projectGetVocalEditDependencies,
+  projectRehydrateVocalEdits,
+} from './vocal_project';
 
 /**
  * Folds the positional and request call forms of `bakeMidiFx` into one shape,
@@ -171,6 +192,47 @@ function midi2Byte(fnName: string, value: number, argName: string): number {
   return value;
 }
 
+/**
+ * An immutable compiled snapshot of a {@link Project}, produced by
+ * {@link Project.compileTimeline} and installed into a stopped realtime engine
+ * with `RealtimeEngine.applyProjectTimeline`.
+ *
+ * An engine keeps its own reference after an apply, so {@link dispose} may be
+ * called right afterwards. The embind handle is not garbage-collected; release
+ * it when no further apply needs it.
+ */
+export class ProjectTimeline {
+  private native: WasmProjectTimeline | null;
+
+  /** @internal */
+  constructor(native: WasmProjectTimeline) {
+    this.native = native;
+    registerProjectTimeline(this, native);
+  }
+
+  /**
+   * Identity an engine names this timeline by, so no raw pointer crosses into JS.
+   *
+   * @internal
+   */
+  get nativeId(): number {
+    if (this.native === null) {
+      throw new TypeError('ProjectTimeline is disposed');
+    }
+    return this.native.id;
+  }
+
+  /** Release the underlying WASM object. Idempotent. */
+  dispose(): void {
+    if (this.native === null) {
+      return;
+    }
+    unregisterProjectTimeline(this);
+    this.native.delete();
+    this.native = null;
+  }
+}
+
 /**
  * Headless DAW project (control-thread-only arrangement model).
  *
@@ -199,7 +261,33 @@ function midi2Byte(fnName: string, value: number, argName: string): number {
  */
 export class Project {
   private native: WasmProject;
+
+  applyVocalEdit(request: ProjectVocalEditApplyRequest): ProjectVocalEditApplyResult {
+    return projectApplyVocalEdit(this.native, request);
+  }
+
+  getVocalEditDependencies(): ProjectVocalEditDependency[] {
+    return projectGetVocalEditDependencies(this.native);
+  }
+
+  rehydrateVocalEdits(
+    originals: readonly ProjectVocalOriginalSource[],
+    cancel?: () => boolean,
+  ): ProjectVocalRehydrateItem[] {
+    this.activeVocalRehydrateCalls += 1;
+    try {
+      return projectRehydrateVocalEdits(this.native, originals, cancel);
+    } finally {
+      this.activeVocalRehydrateCalls -= 1;
+      if (this.activeVocalRehydrateCalls === 0 && this.deleteRequested) {
+        this.native.delete();
+      }
+    }
+  }
+
   private released = false;
+  private deleteRequested = false;
+  private activeVocalRehydrateCalls = 0;
 
   constructor() {
     this.native = new (projectModule().Project)();
@@ -798,6 +886,34 @@ export class Project {
     this.native.setTrackGain(trackId, gain);
   }
 
+  /**
+   * Set the rig of one part (0-15), or of the destination's default when `part`
+   * is {@link PART_RIG_ALL_PARTS}, on MIDI destination `destinationId`, via an
+   * undoable edit. `'chain'` takes 1-8 `inserts` and is the only mode that does;
+   * a destination no track references is stored and read back all the same.
+   * Refused: a malformed insert document (invalid format), an out-of-range part,
+   * an unknown mode or processor, or inserts on a non-chain mode (invalid
+   * parameter), and an insert chain in a build without mastering.
+   */
+  setPartRig(
+    destinationId: number,
+    part: number,
+    mode: PartRigMode | number,
+    inserts?: PartRigInsert[],
+  ): void {
+    this.native.setPartRig(destinationId, part, mode, partRigInsertsJson(inserts));
+  }
+
+  /** The stored rig for `(destinationId, part)`, or null when none is stored. */
+  getPartRig(destinationId: number, part: number): PartRig | null {
+    return partRigFromNative(this.native.getPartRig(destinationId, part));
+  }
+
+  /** Remove the stored rig for `(destinationId, part)` via an undoable edit (no-op when absent). */
+  clearPartRig(destinationId: number, part: number): void {
+    this.native.clearPartRig(destinationId, part);
+  }
+
   /** Set a track's mute flag via an undoable edit (a muted track is silent). */
   setTrackMute(trackId: number, mute: boolean): void {
     this.native.setTrackMute(trackId, mute);
@@ -1059,6 +1175,17 @@ export class Project {
     return this.native.compile();
   }
 
+  /**
+   * Compile the project and keep the resulting timeline. The result is
+   * {@link compile}'s plus `timeline`: a {@link ProjectTimeline} to install with
+   * `RealtimeEngine.applyProjectTimeline`, or `null` when an error diagnostic
+   * means nothing compiled.
+   */
+  compileTimeline(): ProjectCompileTimelineResult {
+    const { timeline, ...result } = this.native.compileTimeline();
+    return { ...result, timeline: timeline === null ? null : new ProjectTimeline(timeline) };
+  }
+
   /**
    * Compile + render the project offline to interleaved float audio. MIDI
    * tracks render silently here (no instrument is bound) — use
@@ -1540,12 +1667,20 @@ export class Project {
     return this.native.lastBounceCompileResult();
   }
 
-  /** Release the underlying WASM object. Idempotent, as the Node facade is. */
+  /**
+   * Release the underlying WASM object. Idempotent, as the Node facade is.
+   * Called from a rehydrate cancel callback, the release happens when the
+   * outermost {@link rehydrateVocalEdits} call returns.
+   */
   delete(): void {
     if (this.released) {
       return;
     }
     this.released = true;
+    if (this.activeVocalRehydrateCalls !== 0) {
+      this.deleteRequested = true;
+      return;
+    }
     this.native.delete();
   }
 

package/src/project_internal.ts

@@ -1,6 +1,9 @@
 import { projectAutomationCurveCode, resolveEnumOrdinal } from './codes';
 import type {
   BuiltinSynthBinding,
+  PartRig,
+  PartRigInsert,
+  PartRigMode,
   SampleDesc,
   SampleZoneDesc,
   Sf2InstrumentConfig,
@@ -77,6 +80,38 @@ export interface WasmSampleBank {
   delete: () => void;
 }
 
+// Embind handle for the C++ `ProjectTimelineWasm` class. Registered next to the
+// project, so a build without arrangement support has neither.
+export interface WasmProjectTimeline {
+  readonly id: number;
+  delete: () => void;
+}
+
+const projectTimelineHandles = new WeakMap<object, WasmProjectTimeline>();
+
+/** Internal: registers the facade object whose identity may cross to the engine. */
+export function registerProjectTimeline(owner: object, native: WasmProjectTimeline): void {
+  projectTimelineHandles.set(owner, native);
+}
+
+/** Internal: removes a disposed facade from the identity registry. */
+export function unregisterProjectTimeline(owner: object): void {
+  projectTimelineHandles.delete(owner);
+}
+
+/** Internal: resolves only a timeline facade created by this module. */
+export function projectTimelineNativeId(owner: unknown): number | undefined {
+  if (owner === null || (typeof owner !== 'object' && typeof owner !== 'function')) {
+    return undefined;
+  }
+  return projectTimelineHandles.get(owner)?.id;
+}
+
+/** `compileTimeline` as the embind layer returns it, before the facade wraps the handle. */
+export type NativeProjectCompileTimelineResult = ProjectCompileResult & {
+  timeline: WasmProjectTimeline | null;
+};
+
 /**
  * Swaps a facade {@link SampleBank} in a synth patch descriptor for the id the
  * embind layer looks the native bank up by, leaving every other field alone.
@@ -114,12 +149,55 @@ export function normalizeSynthInstrument(patch: unknown): NativeSynthBinding | s
   return { ...rest, sampleBankId: sampleBank.nativeId };
 }
 
+/**
+ * Serializes a part rig's inserts into the JSON array the native layer reads
+ * (`params` always a JSON object string), or undefined when none were given.
+ */
+export function partRigInsertsJson(inserts: PartRigInsert[] | undefined): string | undefined {
+  if (inserts === undefined || inserts === null) {
+    return undefined;
+  }
+  if (!Array.isArray(inserts)) {
+    throw new TypeError('inserts must be an array');
+  }
+  return JSON.stringify(
+    inserts.map((insert) => {
+      const { processor, params } = insert;
+      return params === undefined
+        ? { processor }
+        : { processor, params: typeof params === 'string' ? params : JSON.stringify(params) };
+    }),
+  );
+}
+
+/** Reads a native `{ mode, insertsJson }` part rig back into the public shape. */
+export function partRigFromNative(
+  native: { mode: PartRig['mode']; insertsJson: string | null } | null,
+): PartRig | null {
+  if (native === null) {
+    return null;
+  }
+  if (native.insertsJson === null) {
+    return { mode: native.mode };
+  }
+  const inserts = (JSON.parse(native.insertsJson) as { processor: string; params: string }[]).map(
+    ({ processor, params }) => ({
+      processor,
+      params: JSON.parse(params) as Record<string, unknown>,
+    }),
+  );
+  return { mode: native.mode, inserts };
+}
+
 // Embind handle for the C++ `ProjectWasm` class. `SonareModule` describes the
 // raw module's free functions and does not carry bound-class handles, so the
 // module is narrowed through this shape here — which is also where the
 // arrangement surface is probed for, since a build without arrangement support
 // registers neither the class nor its free functions.
 export interface WasmProject {
+  applyVocalEdit: (request: unknown) => unknown;
+  getVocalEditDependencies: () => unknown;
+  rehydrateVocalEdits: (originals: unknown, cancel?: unknown) => unknown;
   toJson: () => string;
   setSampleRate: (sampleRate: number) => void;
   addTrack: (desc: { kind?: number | string; name?: string }) => number;
@@ -140,6 +218,17 @@ export interface WasmProject {
   setTrackMute: (trackId: number, mute: boolean) => void;
   setTrackSolo: (trackId: number, solo: boolean) => void;
   setTrackPan: (trackId: number, pan: number) => void;
+  setPartRig: (
+    destinationId: number,
+    part: number,
+    mode: PartRigMode | number,
+    insertsJson: string | undefined,
+  ) => void;
+  getPartRig: (
+    destinationId: number,
+    part: number,
+  ) => { mode: PartRigMode; insertsJson: string | null } | null;
+  clearPartRig: (destinationId: number, part: number) => void;
   undo: () => void;
   redo: () => void;
   clearHistory: () => void;
@@ -186,6 +275,7 @@ export interface WasmProject {
   ) => number;
   snapToGrid: (ppq: number, strength: number, division: number) => number;
   compile: () => ProjectCompileResult;
+  compileTimeline: () => NativeProjectCompileTimelineResult;
   bounce: (options: ProjectBounceOptions) => Float32Array;
   bounceWithBuiltinInstrument: (
     bindings: BuiltinSynthBinding | ReadonlyArray<BuiltinSynthBinding> | undefined,

package/src/project_types.ts

@@ -1,6 +1,6 @@
 // Type-only, so the erased import adds no runtime edge to the codes module.
 import type { PROJECT_AUTOMATION_CURVE_VALUES } from './codes';
-import type { Project } from './project_class';
+import type { Project, ProjectTimeline } from './project_class';
 
 // ============================================================================
 // Headless DAW Project
@@ -721,6 +721,16 @@ export interface ProjectCompileResult {
   diagnostics: ProjectDiagnostic[];
 }
 
+/** Result of {@link Project.compileTimeline}: the compile diagnostics plus the timeline they produced. */
+export interface ProjectCompileTimelineResult extends ProjectCompileResult {
+  /**
+   * The compiled timeline, or `null` when compilation produced none (an error
+   * diagnostic; read {@link ProjectCompileResult.diagnostics}). Release it with
+   * {@link ProjectTimeline.dispose}.
+   */
+  timeline: ProjectTimeline | null;
+}
+
 export interface ProjectDeserializeResult {
   project: Project;
   diagnostics: string;

package/src/public_types.ts

@@ -41,6 +41,7 @@ export interface SonareCapabilities {
     arrangement: boolean;
     acousticSim: boolean;
     pitchEditor: boolean;
+    vocalEdit: boolean;
     voiceChanger: boolean;
     /** True when the playback renderer (upmix, binaural, speaker output) is compiled in. */
     playback: boolean;

package/src/public_types_mastering.ts

@@ -132,9 +132,11 @@ export const SOLO_PROCESSORS = [
   'repair.trimSilence',
   'saturation.ampSim',
   'saturation.bitcrusher',
+  'saturation.distortion',
   'saturation.exciter',
   'saturation.hardClipper',
   'saturation.multibandExciter',
+  'saturation.overdrive',
   'saturation.softClipper',
   'saturation.tape',
   'saturation.transformer',