@libraz/libsonare 1.7.2 → 1.8.0

package/src/project_internal.ts

@@ -1,8 +1,19 @@
-import { resolveEnumOrdinal } from './codes';
-import { getSonareModule } from './module_state';
+import { projectAutomationCurveCode, resolveEnumOrdinal } from './codes';
 import type {
   BuiltinSynthBinding,
+  SampleDesc,
+  SampleZoneDesc,
+  Sf2InstrumentConfig,
+  Sf2ProgramStatus,
+  SynthEnumTables,
+  SynthPatch,
+} from './instrument_types';
+import { getSonareModule } from './module_state';
+import type {
+  AlignTakeToReferenceRequest,
+  AlignTakeToReferenceResult,
   ProjectAssistSidecar,
+  ProjectAutomationCurve,
   ProjectAutomationLaneDesc,
   ProjectAutomationPoint,
   ProjectAutomationTargetKind,
@@ -27,21 +38,87 @@ import type {
   ProjectNotePairValidation,
   ProjectSource,
   ProjectTempoCandidate,
+  ProjectTempoOptions,
   ProjectTempoSegment,
   ProjectTimeSignatureSegment,
   ProjectTrack,
   ProjectTrackKind,
   ProjectWarpMapDesc,
   ProjectWarpMode,
-  Sf2InstrumentConfig,
-  Sf2ProgramStatus,
-  SynthEnumTables,
-  SynthPatch,
+  TranscribeOptions,
+  TranscribeResult,
 } from './project_types';
+// A value import, and this module's one import cycle: sample_bank.ts reaches
+// back here for projectModule(). Both directions are read inside function
+// bodies only, never while a module body runs, which is what makes the cycle
+// safe. Reading SampleBank at module scope here breaks ONE import order and
+// leaves the other working, so the property is pinned by
+// tests/sample-bank-module-cycle.test.ts rather than left to review.
+import { SampleBank } from './sample_bank';
+import { assertNibble, assertU7, assertU32 } from './validation';
+
+/**
+ * A synth binding as the embind layer takes it: the public `sampleBank` handle
+ * has already been resolved to the id the native registry looks the bank up by,
+ * because an embind class instance cannot travel inside a plain JS object the
+ * C++ side reads field by field.
+ */
+export type NativeSynthBinding = Omit<SynthPatch, 'sampleBank'> & { sampleBankId?: number };
+
+// Embind handle for the C++ `SampleBankWasm` class, narrowed the same way as
+// `WasmProject` below: it is registered next to the project, so a build without
+// arrangement support has neither.
+export interface WasmSampleBank {
+  readonly id: number;
+  addSample: (data: Float32Array, desc: SampleDesc) => number;
+  addZone: (setIndex: number, zone: Omit<SampleZoneDesc, 'setIndex'>) => void;
+  sampleCount: () => number;
+  setCount: () => number;
+  delete: () => void;
+}
+
+/**
+ * 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.
+ *
+ * Shared by the offline bounce and the realtime engine so `sampleBank` means
+ * the same thing on both. It lives in this internal module rather than beside
+ * the class because it hands out an internal identity that no caller has a use
+ * for, and the entry point must not re-export it: a facade symbol with no C
+ * counterpart is an active parity finding.
+ *
+ * The cast is the only one of its kind: `released` is private, and TypeScript's
+ * private is a compile-time rule, so reading it once here beats widening the
+ * class with a method the parity tool would then read as a facade op.
+ */
+export function normalizeSynthInstrument(patch: unknown): NativeSynthBinding | string {
+  if (patch === null || typeof patch !== 'object') {
+    // A preset-name string — and, at runtime, anything else — reaches the
+    // embind layer unchanged, which is where such a value is validated.
+    return patch as NativeSynthBinding | string;
+  }
+  const { sampleBank, ...rest } = patch as SynthPatch;
+  if (!sampleBank) {
+    // Omitted, and at runtime an explicit null: both mean no bank, which a
+    // sample patch renders as silence.
+    return rest;
+  }
+  if (!(sampleBank instanceof SampleBank)) {
+    throw new TypeError('sampleBank must be a SampleBank instance');
+  }
+  if ((sampleBank as unknown as { released: boolean }).released) {
+    // The id outlives the handle, so without this the native registry would be
+    // the only thing that notices — and with a different error class than Node.
+    throw new TypeError('sampleBank is destroyed');
+  }
+  return { ...rest, sampleBankId: sampleBank.nativeId };
+}
 
-// Embind handle for the C++ `ProjectWasm` class. The generated `SonareModule`
-// type only gains `Project` / `projectAbiVersion` after a WASM rebuild, so the
-// module is cast through this shape here.
+// 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 {
   toJson: () => string;
   setSampleRate: (sampleRate: number) => void;
@@ -73,9 +150,9 @@ export interface WasmProject {
     events: ReadonlyArray<ProjectMidiEvent | readonly [number, number, number]>,
   ) => void;
   importSmf: (data: Uint8Array) => number;
-  exportSmf: () => Uint8Array;
+  exportSmf: () => Uint8Array<ArrayBuffer>;
   importClipFile: (data: Uint8Array) => number;
-  exportClipFile: () => Uint8Array;
+  exportClipFile: () => Uint8Array<ArrayBuffer>;
   setProgram: (clipId: number, program: number, bank: number) => void;
   setProgramOnChannel: (
     clipId: number,
@@ -89,12 +166,23 @@ export interface WasmProject {
   previewMidiFxCount: (clipId: number, configJson: string) => number;
   setMidiFx: (clipId: number, configJson: string) => void;
   validateMidiNotes: (clipId: number) => ProjectNotePairValidation;
-  analyzeTempo: (audio: Float32Array, sampleRate: number) => ProjectTempoCandidate[];
+  transcribeToClip: (
+    clipId: number,
+    samples: Float32Array,
+    sampleRate: number,
+    config: TranscribeOptions,
+  ) => number;
+  analyzeTempo: (
+    audio: Float32Array,
+    sampleRate: number,
+    options: ProjectTempoOptions | undefined,
+  ) => ProjectTempoCandidate[];
   autoTempo: (
     audio: Float32Array,
     sampleRate: number,
     candidateIndex: number,
     applyTimeSignatures: boolean,
+    options: ProjectTempoOptions | undefined,
   ) => number;
   snapToGrid: (ppq: number, strength: number, division: number) => number;
   compile: () => ProjectCompileResult;
@@ -104,7 +192,7 @@ export interface WasmProject {
     options: ProjectBounceOptions,
   ) => Float32Array;
   bounceWithSynthInstrument: (
-    bindings: SynthPatch | string | ReadonlyArray<SynthPatch | string> | undefined,
+    bindings: NativeSynthBinding | string | ReadonlyArray<NativeSynthBinding | string> | undefined,
     options: ProjectBounceOptions,
   ) => Float32Array;
   loadSoundFont: (data: Uint8Array) => void;
@@ -177,6 +265,8 @@ export interface WasmProject {
   clipCount: () => number;
   sourceCount: () => number;
   tempoSegmentCount: () => number;
+  tempoSegmentByIndex: (index: number) => ProjectTempoSegment;
+  timeSignatureByIndex: (index: number) => ProjectTimeSignatureSegment;
   timeSignatureCount: () => number;
   setTempoSegments: (segments: ReadonlyArray<ProjectTempoSegment>) => void;
   setTimeSignatures: (segments: ReadonlyArray<ProjectTimeSignatureSegment>) => void;
@@ -190,9 +280,14 @@ export interface ProjectModule {
     fromJson: (json: string) => WasmProject;
     fromJsonWithDiagnostics: (json: string) => { project: WasmProject; diagnostics: string };
   };
+  SampleBank: { new (): WasmSampleBank };
   projectAbiVersion: () => number;
   synthPresetNames: () => string[];
   synthPresetPatch: (name: string) => SynthPatch;
+  synthGsDrumKitName: (program: number) => string | null;
+  synthGsDrumKitIsVoicedApart: (program: number) => number;
+  synthGsVariationIsVoicedApart: (bank: number, program: number) => number;
+  controllerProfileNames: () => string[];
   _synthEnumTables: () => SynthEnumTables;
   _synthPatchRoundTrip: (patch: SynthPatch) => SynthPatch;
   midiGmInstrumentName: (program: number) => string | null;
@@ -237,6 +332,21 @@ export interface ProjectModule {
     group: number,
     ppq: number,
   ) => ProjectMidiEvent | null;
+  transcribe: (
+    samples: Float32Array,
+    sampleRate: number,
+    tempoBpm: number | undefined,
+    config: TranscribeOptions,
+  ) => TranscribeResult;
+  // Positional in the C ABI's own order minus the derived lengths and the out
+  // parameters. The request object is passed as `config` as well, the way
+  // `transcribe` passes its own: the reader only looks at the resolution keys.
+  alignTakeToReference: (
+    reference: Float32Array,
+    take: Float32Array,
+    sampleRate: number,
+    config: AlignTakeToReferenceRequest,
+  ) => AlignTakeToReferenceResult;
 }
 
 export function projectModule(): ProjectModule {
@@ -247,20 +357,6 @@ export function projectModule(): ProjectModule {
   return candidate as ProjectModule;
 }
 
-export function assertProjectU7(fnName: string, value: number, argName: string): number {
-  if (!Number.isInteger(value) || value < 0 || value > 127) {
-    throw new RangeError(`${fnName}: ${argName} must be an integer in [0, 127]`);
-  }
-  return value;
-}
-
-export function assertProjectNibble(fnName: string, value: number, argName: string): number {
-  if (!Number.isInteger(value) || value < 0 || value > 15) {
-    throw new RangeError(`${fnName}: ${argName} must be an integer in [0, 15]`);
-  }
-  return value;
-}
-
 export function projectMidi1Event(
   fnName: string,
   ppq: number,
@@ -273,10 +369,10 @@ export function projectMidi1Event(
   if (!Number.isFinite(ppq) || ppq < 0) {
     throw new RangeError(`${fnName}: ppq must be a non-negative finite number`);
   }
-  const g = assertProjectNibble(fnName, group, 'group');
-  const ch = assertProjectNibble(fnName, channel, 'channel');
-  const d1 = assertProjectU7(fnName, data1, 'data1');
-  const d2 = assertProjectU7(fnName, data2, 'data2');
+  const g = assertNibble(fnName, group, 'group');
+  const ch = assertNibble(fnName, channel, 'channel');
+  const d1 = assertU7(fnName, data1, 'data1');
+  const d2 = assertU7(fnName, data2, 'data2');
   // UMP MIDI-1.0 channel-voice word (message type 0x2). Canonical layout is
   // sonare::midi::make_midi1_* (C-ABI sonare_midi_*, which Python delegates to);
   // this hand-written copy is locked against those words by the golden vectors
@@ -285,12 +381,6 @@ export function projectMidi1Event(
   return { ppq, data0: word, data1: 0 };
 }
 
-export function assertProjectU32(fnName: string, value: number, argName: string): void {
-  if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
-    throw new RangeError(`${fnName}: ${argName} must be an integer in [0, 4294967295]`);
-  }
-}
-
 export function assertProjectMidiEvents(
   fnName: string,
   events: ReadonlyArray<ProjectMidiEvent | readonly [number, number, number]>,
@@ -307,8 +397,8 @@ export function assertProjectMidiEvents(
       if (!Number.isFinite(event[0]) || event[0] < 0) {
         throw new RangeError(`${fnName}: ${prefix}.ppq must be a non-negative finite number`);
       }
-      assertProjectU32(fnName, event[1], `${prefix}.data0`);
-      assertProjectU32(fnName, event[2], `${prefix}.data1`);
+      assertU32(fnName, event[1], `${prefix}.data0`);
+      assertU32(fnName, event[2], `${prefix}.data1`);
       return;
     }
     if (event === null || typeof event !== 'object') {
@@ -317,9 +407,9 @@ export function assertProjectMidiEvents(
     if (!Number.isFinite(event.ppq) || event.ppq < 0) {
       throw new RangeError(`${fnName}: ${prefix}.ppq must be a non-negative finite number`);
     }
-    assertProjectU32(fnName, event.data0, `${prefix}.data0`);
+    assertU32(fnName, event.data0, `${prefix}.data0`);
     if (event.data1 !== undefined) {
-      assertProjectU32(fnName, event.data1, `${prefix}.data1`);
+      assertU32(fnName, event.data1, `${prefix}.data1`);
     }
   });
 }
@@ -328,6 +418,23 @@ export function projectTrackKindValue(kind: ProjectTrackKind | undefined): numbe
   return resolveEnumOrdinal(kind ?? 'audio', { audio: 0, midi: 1, aux: 2 }, 'project track kind');
 }
 
+/**
+ * Resolve a breakpoint's curve spelling to its ordinal before it crosses into
+ * embind, and fold the `curveToNext` alias onto `curve`.
+ *
+ * Mirrors the Node facade's `projectAutomationPointValue`: resolving here means
+ * an unknown spelling is a `RangeError` from the same table both packages
+ * declare, rather than a curve one binding renders and the other rejects.
+ */
+export function projectAutomationPointValue(point: ProjectAutomationPoint): ProjectAutomationPoint {
+  const curve = projectAutomationCurveCode(point.curve ?? point.curveToNext);
+  return {
+    ...point,
+    curve: curve as ProjectAutomationCurve,
+    curveToNext: curve as ProjectAutomationCurve,
+  };
+}
+
 export function projectAutomationTargetKindValue(kind: ProjectAutomationTargetKind): number {
   return resolveEnumOrdinal(
     kind,
@@ -339,7 +446,7 @@ export function projectAutomationTargetKindValue(kind: ProjectAutomationTargetKi
 export function projectWarpModeValue(mode: ProjectWarpMode | undefined): number {
   return resolveEnumOrdinal(
     mode ?? 'off',
-    { off: 0, repitch: 1, 'tempo-sync': 2 },
+    { off: 0, repitch: 1, 'tempo-sync': 2, 'time-stretch': 3 },
     'project warp mode',
   );
 }

package/src/project_synth.ts

@@ -1,5 +1,5 @@
+import type { SynthEnumTables, SynthPatch } from './instrument_types';
 import { projectModule } from './project_internal';
-import type { SynthEnumTables, SynthPatch } from './project_types';
 
 /**
  * Runtime ABI version of the flat project POD layout exposed by this WASM
@@ -20,6 +20,72 @@ export function synthPresetNames(): string[] {
   return Array.from(projectModule().synthPresetNames());
 }
 
+/**
+ * GS rhythm-set name a rhythm part's `program` selects (`'Standard'`,
+ * `'Room'`, `'Jazz'`, ...), or `null` when the module's own tone map defines
+ * no set there.
+ *
+ * @remarks
+ * The answer is the module's own map, which is the newest one and reaches
+ * every set this build voices; a file selecting an older map reaches fewer.
+ */
+export function synthGsDrumKitName(program: number): string | null {
+  return projectModule().synthGsDrumKitName(program);
+}
+
+/**
+ * Whether the GS rhythm set at `program` is voiced apart from Standard: `true`
+ * when at least one drum note differs, `false` when the set renders exactly as
+ * Standard, `null` when no set sits at `program`.
+ *
+ * @remarks
+ * Derived by applying the set to every note's resolved patch and comparing, so
+ * the answer follows the voicing rather than a list that has to be kept in step
+ * with it. Four sets GS fills with one-shots share the Standard voicing
+ * deliberately, so a picker built from the set list alone offers four choices
+ * that change nothing — annotate or disable them with this.
+ *
+ * @example
+ * ```ts
+ * const kits = Array.from({ length: 128 }, (_, program) => ({ program, name: synthGsDrumKitName(program) }))
+ *   .filter((kit): kit is { program: number; name: string } => kit.name !== null)
+ *   .map((kit) => ({ ...kit, placeholder: synthGsDrumKitIsVoicedApart(kit.program) === false }));
+ * ```
+ */
+export function synthGsDrumKitIsVoicedApart(program: number): boolean | null {
+  const r = projectModule().synthGsDrumKitIsVoicedApart(program);
+  return r < 0 ? null : r === 1;
+}
+
+/**
+ * Whether melodic Bank Select `bank` on `program` is voiced apart from the
+ * capital tone: `true` when the bank has a patch of its own, `false` when it
+ * resolves to the capital, `null` when either argument is outside `[0, 127]` —
+ * both are seven-bit MIDI values, so `128` is out of range rather than the drum
+ * bank here.
+ *
+ * @remarks
+ * Resolving an unvoiced variation to its capital is what GS specifies, so a
+ * `false` is correct behaviour rather than a gap — but only this query
+ * separates it from a bank that is voiced, which otherwise takes rendering both
+ * and comparing. Accepts the GS Bank Select MSB and the GM2 LSB alike, since
+ * both address the same variation.
+ */
+export function synthGsVariationIsVoicedApart(bank: number, program: number): boolean | null {
+  const r = projectModule().synthGsVariationIsVoicedApart(bank, program);
+  return r < 0 ? null : r === 1;
+}
+
+/**
+ * Controller-profile preset names (`'gm'`, `'breath'`, `'breath-aftertouch'`,
+ * `'mpe'`). These are the names {@link RealtimeEngine.setControllerProfile}
+ * accepts; an unknown one throws rather than resolving to a default.
+ */
+export function controllerProfileNames(): string[] {
+  // Array.from re-roots embind's vector as a plain, structured-cloneable Array.
+  return Array.from(projectModule().controllerProfileNames());
+}
+
 /**
  * Fetch a named catalog preset as a {@link SynthPatch} (the preset name plus
  * the wrapper-section values), so hosts can inspect a preset and tweak fields