@libraz/libsonare 1.8.0 → 1.8.2

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
@@ -532,7 +532,7 @@ export interface MidiCcLearnOptions {
   minValue?: number;
   /** Upper end of the mapped parameter range. Default `1`. */
   maxValue?: number;
-  /** Minimum normalized CC movement required to learn a binding. Default `0`. */
+  /** Activity threshold in 7-bit CC units (integer 0-127) a controller must move to be learned. Default `0`. */
   minMovement?: number;
 }
 
@@ -630,12 +630,14 @@ export interface TranscribeOptions {
    */
   referenceHz?: number;
   /**
-   * Monophonic tracker range in Hz. Defaults `65` and `2093`; both must be
-   * finite and positive, and `fmax` must exceed `fmin`. The polyphonic chain
-   * sets its own range and reads neither.
+   * F0 tracker range in Hz. Both paths use these bounds; the polyphonic path
+   * applies them to the salience estimator's F0 axis while its cent-spectrum
+   * bounds remain independent. When omitted, the monophonic defaults are `65`
+   * and `2093`, while the polyphonic defaults are `55` and `1760`. Explicit
+   * values must be finite and positive, and `fmax` must exceed `fmin`.
    */
   fmin?: number;
-  /** Upper end of the monophonic tracker range in Hz. Default `2093`. */
+  /** Upper end of the F0 tracker range in Hz; omitted defaults to `2093` mono or `1760` poly. */
   fmax?: number;
   /** Shortest span kept as a note, in milliseconds. Default `30`; must be positive. */
   minNoteMs?: number;
@@ -719,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

@@ -80,6 +80,7 @@ export const SOLO_PROCESSORS = [
   'effects.acoustic.roomMorph',
   'effects.delay.stereo',
   'effects.filter.vowel',
+  'effects.gsEfx',
   'effects.modulation.autoWah',
   'effects.modulation.chorus',
   'effects.modulation.ensemble',
@@ -131,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',
@@ -162,6 +165,9 @@ export type PairProcessor =
   | 'match.abSwitch'
   | 'match.abCrossfade';
 
+/** Pair processors with a stereo entry point. */
+export type StereoPairProcessor = 'match.abCrossfade';
+
 export type PairAnalysis =
   | 'match.referenceLoudness'
   | 'match.tonalBalance'
@@ -213,6 +219,23 @@ export interface LoudnessMatchResult {
   matchedTruePeakDbtp: number;
 }
 
+/** Stereo counterpart of {@link LoudnessMatchResult}. */
+export interface LoudnessMatchStereoResult {
+  /** The left source channel, gain-matched to the reference loudness. */
+  left: Float32Array;
+  /** The right source channel, gain-matched with the same gain as `left`. */
+  right: Float32Array;
+  sampleRate: number;
+  /** The reference program's BS.1770 integrated loudness. */
+  referenceLufs: number;
+  /** The stereo source program's loudness before the gain. */
+  sourceLufs: number;
+  /** One gain applied to both source channels, in dB. */
+  appliedGainDb: number;
+  /** Maximum true peak across the matched left and right channels, in dBTP. */
+  matchedTruePeakDbtp: number;
+}
+
 /**
  * Mastering loudness/true-peak processing result
  */

package/src/public_types_playback.ts

@@ -158,6 +158,7 @@ export interface PlaybackDiagnostics {
   loudness_gain_clamped: boolean;
   /** True when an `hrtf` was supplied to a speakers target, which ignores it. */
   hrtf_ignored: boolean;
+  /** Deepest last-block gain reduction across the main and LFE limiters, in dB (<= 0). */
   limiter_gain_reduction_db: number;
   non_finite_discards: number;
 }

package/src/public_types_spectral.ts

@@ -34,10 +34,10 @@ export interface PitchCorrectOptions extends ValidateOptions {
   retuneSpeedMs?: number;
   /** Corrections below this are bypassed to preserve vibrato (cents). Default 20. */
   vibratoThresholdCents?: number;
-  /** 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;
+  /** Per-frame voiced flags (truthy = voiced); when supplied, these take precedence over `voicedProb`. Omit or pass `null` to use `voicedProb`; with neither, all frames are treated as voiced. */
+  voiced?: VoicedFlags | null;
+  /** Per-frame voicing probability in `[0, 1]`; used only when `voiced` is omitted or `null`, and ignored when flags are supplied. */
+  voicedProb?: Float32Array | null;
 }
 
 /** Options for `noteStretch`. All fields are optional. */
@@ -68,7 +68,7 @@ export interface NoteExtractorOptions {
   referenceHz?: number;
   /**
    * Value of `voicedProb` at or above which a frame counts as voiced, in
-   * `[0, 1]`. Read only when `voiced` is omitted. Default 0.5.
+   * `[0, 1]`. Read only when `voiced` is omitted or `null`. Default 0.5.
    *
    * pYIN's `voicedProb` is a frame's voiced observation mass and rises with F0
    * for a fixed frame length, so this default silently drops low registers —

package/src/public_types_vocal_edit.ts

@@ -0,0 +1,289 @@
+/** Public value types for the monophonic vocal edit surface. */
+
+/** A uint64 value crossing the JavaScript boundary is decimal text. */
+export type VocalUint64 = string;
+
+export interface VocalRange {
+  startSample: number;
+  endSample: number;
+}
+
+export interface VocalStateToken {
+  sessionEpoch: VocalUint64;
+  revision: VocalUint64;
+  draftId: VocalUint64;
+  generation: VocalUint64;
+  requestId: VocalUint64;
+  profileId: number;
+}
+
+export interface VocalPitchPoint {
+  sourceSample: number;
+  midi: number;
+}
+
+export type VocalPitchTarget =
+  | { mode: 'none' }
+  | { mode: 'center'; midi: number }
+  | { mode: 'curve'; points: readonly VocalPitchPoint[] };
+
+export interface VocalPitchEdit {
+  target: VocalPitchTarget;
+  amount: number;
+  speedMs: number;
+  maxCorrectionSemitones: number;
+  transposeSemitones: number;
+  driftScale: number;
+  vibratoScale: number;
+}
+
+export type VocalFormantMode = 'preserve' | 'shift';
+
+export interface VocalFormantEdit {
+  mode: VocalFormantMode;
+  shiftSemitones: number;
+}
+
+export interface VocalNoteEdit {
+  pitch: VocalPitchEdit;
+  destinationStartSample: number;
+  destinationLengthSamples: number;
+  gainDb: number;
+  muted: boolean;
+  amplitudeEnvelope: readonly number[];
+  formant: VocalFormantEdit;
+}
+
+export interface VocalNote {
+  id: number;
+  sourceStartSample: number;
+  sourceEndSample: number;
+  analysisFrameStart: VocalUint64;
+  analysisFrameEnd: VocalUint64;
+  hasPitch: boolean;
+  medianHz: number;
+  centerMidi: number;
+  f0Stability: number;
+  amplitude: Float32Array;
+  edit: VocalNoteEdit;
+}
+
+export interface VocalTransition {
+  leftNoteId: number;
+  rightNoteId: number;
+  leftWindowSamples: number;
+  rightWindowSamples: number;
+  strength: number;
+  curve: 'smoothstep';
+}
+
+export interface VocalNotesResult {
+  notes: VocalNote[];
+  transitions: VocalTransition[];
+}
+
+export interface VocalAnalysis {
+  frameOriginSample: number;
+  samplesPerFrame: number;
+  frameLengthSamples: number;
+  f0Hz: Float32Array;
+  voiced: Uint8Array;
+  algorithmId: string;
+  algorithmVersion: number;
+  sourceLengthSamples: number;
+  sampleRate: number;
+  sourceSha256: string;
+  analysisSha256: string;
+  fminHz: number;
+  fmaxHz: number;
+  yinThreshold: number;
+  voicedThreshold: number;
+  centered: boolean;
+  segmentationThresholdCents: number;
+  minNoteMs: number;
+  referenceHz: number;
+}
+
+export interface VocalCapabilities {
+  apiVersion: number;
+  profileId: number;
+  monophonicOnly: true;
+  analysisCancellable: boolean;
+  minimumFormantShiftSemitones: number;
+  maximumFormantShiftSemitones: number;
+}
+
+export interface VocalHistory {
+  canUndo: boolean;
+  canRedo: boolean;
+}
+
+export type VocalHistoryState = VocalHistory;
+
+export interface VocalSessionLimits {
+  maxHistoryBytes?: VocalUint64;
+  maxCacheBytes?: VocalUint64;
+  maxUndoDepth?: number;
+  maxRenderJobs?: number;
+}
+
+export interface VocalAnalysisInput {
+  frameOriginSample: number;
+  samplesPerFrame: number;
+  frameLengthSamples: number;
+  f0Hz: Float32Array;
+  voiced: Uint8Array;
+  algorithmId?: string;
+  algorithmVersion?: number;
+  fminHz?: number;
+  fmaxHz?: number;
+  yinThreshold?: number;
+  voicedThreshold?: number;
+  centered?: boolean;
+  segmentationThresholdCents?: number;
+  minNoteMs?: number;
+  referenceHz?: number;
+}
+
+export interface VocalCreateOptions {
+  outputLengthSamples?: number;
+  edgeFadeMs?: number;
+  vibratoCutoffHz?: number;
+  segmentationThresholdCents?: number;
+  minNoteMs?: number;
+  frameLengthSamples?: number;
+  hopLengthSamples?: number;
+  fminHz?: number;
+  fmaxHz?: number;
+  yinThreshold?: number;
+  voicedThreshold?: number;
+  centered?: boolean;
+  referenceHz?: number;
+  limits?: VocalSessionLimits;
+  analysis?: VocalAnalysisInput;
+}
+
+export interface VocalCreateRequest extends VocalCreateOptions {
+  samples: Float32Array;
+  sampleRate: number;
+}
+
+export interface VocalRestoreRequest {
+  samples: Float32Array;
+  sampleRate: number;
+  state: Uint8Array;
+  /** Runtime limits; omitted fields take the same defaults as session creation. */
+  limits?: VocalSessionLimits;
+}
+
+export interface VocalSetEditOperation {
+  kind: 'setEdit';
+  noteId: number;
+  edit: VocalNoteEdit;
+}
+
+export interface VocalSetSourceSpanOperation {
+  kind: 'setSourceSpan';
+  noteId: number;
+  sourceStartSample: number;
+  sourceEndSample: number;
+  destinationStartSample: number;
+  destinationLengthSamples: number;
+}
+
+export interface VocalSplitOperation {
+  kind: 'split';
+  noteId: number;
+  sourceSample: number;
+}
+
+export interface VocalMergeOperation {
+  kind: 'merge';
+  noteIds: readonly number[];
+  policy?: 'preserve' | 'reset';
+}
+
+export interface VocalSetTransitionOperation {
+  kind: 'setTransition';
+  transition: VocalTransition;
+}
+
+export interface VocalRemoveTransitionOperation {
+  kind: 'removeTransition';
+  leftNoteId: number;
+  rightNoteId: number;
+}
+
+export interface VocalResetOperation {
+  kind: 'reset';
+  noteIds: readonly number[];
+}
+
+export type VocalEditOperation =
+  | VocalSetEditOperation
+  | VocalSetSourceSpanOperation
+  | VocalSplitOperation
+  | VocalMergeOperation
+  | VocalSetTransitionOperation
+  | VocalRemoveTransitionOperation
+  | VocalResetOperation;
+
+export interface VocalApplyRequest {
+  expectedGeneration: VocalUint64;
+  operations: readonly VocalEditOperation[];
+}
+
+export interface VocalIdChange {
+  operationIndex: number;
+  retiredId: number;
+  newIds: readonly number[];
+}
+
+export interface VocalEditResult {
+  token: VocalStateToken;
+  dirtyRanges: readonly VocalRange[];
+  idChanges: readonly VocalIdChange[];
+}
+
+export interface VocalPitchEvaluation {
+  sourceSamples: Float64Array;
+  measuredMidi: Float64Array;
+  targetMidi: Float64Array;
+  effectiveMidi: Float64Array;
+  voiced: Uint8Array;
+  hasTarget: Uint8Array;
+}
+
+export interface VocalRenderRequest {
+  /** Omit to render the complete destination output. */
+  range?: VocalRange;
+  requestId?: VocalUint64;
+  signal?: AbortSignal;
+}
+
+export interface VocalRenderResult {
+  samples: Float32Array;
+  startSample: number;
+  token: VocalStateToken;
+  processedRanges: readonly VocalRange[];
+  cacheHitUnits: VocalUint64;
+  dryPassedFrames: VocalUint64;
+  limitedCorrectionFrames: VocalUint64;
+}
+
+export interface VocalStateBytes {
+  data: Uint8Array;
+}
+
+export interface VocalJobProgress {
+  complete: boolean;
+}
+
+export interface VocalErrorShape {
+  readonly reason: number;
+  readonly field: string;
+  readonly expected: VocalUint64;
+  readonly actual: VocalUint64;
+  readonly expectedText: string;
+  readonly actualText: string;
+}

package/src/public_types_vocal_project.ts

@@ -0,0 +1,69 @@
+import type { VocalStateToken, VocalUint64 } from './public_types_vocal_edit';
+
+/** A full source render and persisted vocal session ready for Project apply. */
+export interface ProjectVocalEditApplyRequest {
+  clipId: number;
+  /** Zero selects the clip's base source; a non-zero id selects a take. */
+  takeId?: number;
+  expectedSourceId: number;
+  expectedSourceSampleRate: number;
+  expectedSourceSampleCount: number;
+  /** Canonical source digest as exactly 64 hexadecimal characters. */
+  expectedSourceSha256: string;
+  expectedClipLengthPpq: number;
+  expectedSourceOffsetPpq: number;
+  /** Full-source mono render. The v1 Project adapter requires startSample 0. */
+  renderedMono: Float32Array;
+  renderedSampleRate: number;
+  renderedStartSample?: number;
+  renderToken: VocalStateToken;
+  /** SVE1 state exported from the committed vocal edit session. */
+  sve1: Uint8Array;
+}
+
+export interface ProjectVocalEditApplyResult {
+  clipId: number;
+  takeId: number;
+  originalSourceId: number;
+  derivedSourceId: number;
+  committedRevision: VocalUint64;
+  profileId: number;
+  derivedSourceSha256: string;
+  sidecarKey: string;
+}
+
+export type ProjectVocalReason = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+
+export interface ProjectVocalEditDependency {
+  clipId: number;
+  takeId: number;
+  originalSourceId: number;
+  derivedSourceId: number;
+  sourceSampleRate: number;
+  profileId: number;
+  sourceSampleCount: number;
+  committedRevision: VocalUint64;
+  originalSourceSha256: string;
+  derivedSourceSha256: string;
+  originalPcmAvailable: boolean;
+  derivedPcmAvailable: boolean;
+  reason: ProjectVocalReason | number;
+  sidecarKey: string;
+}
+
+export interface ProjectVocalOriginalSource {
+  sourceId: number;
+  mono: Float32Array;
+  sampleRate: number;
+}
+
+/** Native status values from SonareProjectVocalRehydrateStatus. */
+export type ProjectVocalRehydrateStatus = 0 | 1 | 2;
+
+export interface ProjectVocalRehydrateItem {
+  clipId: number;
+  takeId: number;
+  derivedSourceId: number;
+  status: ProjectVocalRehydrateStatus;
+  reason: ProjectVocalReason | number;
+}