@libraz/libsonare 1.8.0 → 1.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.8.0",
+  "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/_effects_common.ts

@@ -4,14 +4,44 @@
 
 import type { VoicedFlags } from './public_types';
 
-// The embind layer reads the companion voicing array as Float32Array. A flag is
-// a decision, not a magnitude: collapse to 1/0 on truthiness, which is the same
-// reduction the Node facade applies, so both surfaces agree on every accepted
-// input type.
-export function toVoicedFloat32(voiced: VoicedFlags): Float32Array {
+// The embind layer reads the companion voicing array as Float32Array. Keep the
+// public union a runtime contract before conversion: strings, Float64Arrays and
+// arbitrary array-like objects must not become flags through truthiness.
+// Same 1/0 reduction as the Node facade's toVoicedInt32.
+export function toVoicedFloat32(fnName: string, voiced: VoicedFlags): Float32Array {
+  if (
+    !(
+      voiced instanceof Int32Array ||
+      voiced instanceof Uint8Array ||
+      voiced instanceof Float32Array ||
+      Array.isArray(voiced)
+    )
+  ) {
+    throw new TypeError(
+      `${fnName}: voiced must be an Int32Array, Uint8Array, Float32Array, number[], or boolean[]`,
+    );
+  }
   const out = new Float32Array(voiced.length);
   for (let index = 0; index < voiced.length; index += 1) {
-    out[index] = voiced[index] ? 1 : 0;
+    const value = voiced[index];
+    if (typeof value !== 'number' && typeof value !== 'boolean') {
+      throw new TypeError(`${fnName}: voiced array entries must be numbers or booleans`);
+    }
+    out[index] = value ? 1 : 0;
   }
   return out;
 }
+
+export function assertPitchTrackLengths(
+  fnName: string,
+  f0Hz: Float32Array,
+  voiced?: VoicedFlags | null,
+  voicedProb?: Float32Array | null,
+): void {
+  if (voiced != null && voiced.length !== f0Hz.length) {
+    throw new RangeError(`${fnName}: voiced must have the same length as f0Hz`);
+  }
+  if (voiced == null && voicedProb != null && voicedProb.length !== f0Hz.length) {
+    throw new RangeError(`${fnName}: voicedProb must have the same length as f0Hz`);
+  }
+}

package/src/effects_mastering.ts

@@ -43,6 +43,7 @@ export {
 } from './mastering_chain';
 export type {
   MasteringAbMatchLoudnessRequest,
+  MasteringAbMatchLoudnessStereoRequest,
   MasteringAmpPresetCatalogEntry,
   MasteringAssistantParamsRequest,
   MasteringAssistantStereoParamsRequest,
@@ -53,6 +54,7 @@ export type {
   MasteringInsertTiming,
   MasteringPairAnalyzeRequest,
   MasteringPairProcessRequest,
+  MasteringPairProcessStereoRequest,
   MasteringProcessorCatalogEntry,
   MasteringProcessorCategory,
   MasteringProcessRequest,
@@ -67,6 +69,7 @@ export type {
 export {
   mastering,
   masteringAbMatchLoudness,
+  masteringAbMatchLoudnessStereo,
   masteringAmpPresetCatalog,
   masteringAssistantSuggest,
   masteringAssistantSuggestChain,
@@ -82,6 +85,7 @@ export {
   masteringPairAnalyze,
   masteringPairProcess,
   masteringPairProcessorNames,
+  masteringPairProcessStereo,
   masteringProcess,
   masteringProcessorCatalog,
   masteringProcessorNames,

package/src/effects_note_ops.ts

@@ -3,7 +3,7 @@
  * rendering an edited set back, and the split/merge operations over it.
  */
 
-import { toVoicedFloat32 } from './_effects_common';
+import { assertPitchTrackLengths, toVoicedFloat32 } from './_effects_common';
 import { getSonareModule } from './module_state';
 import type {
   NoteExtractorOptions,
@@ -19,7 +19,7 @@ import type {
   VoicedFlags,
 } from './public_types';
 import type { ValidateOptions } from './validation';
-import { assertSampleRate, assertSamples } from './validation';
+import { assertFiniteScalar, assertSampleRate, assertSamples } from './validation';
 
 function requireModule() {
   return getSonareModule();
@@ -35,13 +35,9 @@ function assertNoteTrack(
 ): Float32Array | undefined {
   assertSamples(fnName, request.samples, request.validate !== false);
   assertSampleRate(fnName, request.sampleRate);
-  if (request.voiced && request.voiced.length !== request.f0Hz.length) {
-    throw new RangeError(`${fnName}: voiced length must match f0Hz length`);
-  }
-  if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
-    throw new RangeError(`${fnName}: voicedProb length must match f0Hz length`);
-  }
-  return request.voiced ? toVoicedFloat32(request.voiced) : undefined;
+  const voicedF32 = request.voiced == null ? undefined : toVoicedFloat32(fnName, request.voiced);
+  assertPitchTrackLengths(fnName, request.f0Hz, request.voiced, request.voicedProb);
+  return voicedF32;
 }
 
 export interface NoteStretchRequest extends NoteStretchOptions, ValidateOptions {
@@ -73,10 +69,10 @@ export interface ExtractNotesRequest extends NoteExtractorOptions, ValidateOptio
   f0Hz: Float32Array;
   /** F0 frames per second. */
   frameRate: number;
-  /** Per-frame voiced flags (truthy = voiced). Takes precedence over `voicedProb`. */
-  voiced?: VoicedFlags;
-  /** Per-frame voicing probability in `[0, 1]`; read only when `voiced` is omitted. */
-  voicedProb?: Float32Array;
+  /** Per-frame voiced flags (truthy = voiced); takes precedence over `voicedProb` when supplied. Omit or pass `null` to use the probability array. */
+  voiced?: VoicedFlags | null;
+  /** Per-frame voicing probability in `[0, 1]`; read only when `voiced` is omitted or `null`. */
+  voicedProb?: Float32Array | null;
 }
 
 /** Canonical request form for {@link renderNotes}. */
@@ -97,12 +93,16 @@ export interface RenderNotesRequest extends ValidateOptions {
   /**
    * The F0 track the notes were extracted from. Required only by
    * `vibratoDepthChange` and `driftChange`, which act on the note's own pitch
-   * curve; every other edit ignores it. The curve is not carried on a
+   * curve, or when `voiced` is supplied; every other edit ignores it. The curve is not carried on a
    * {@link NoteObject} for the same reason it is not returned by
    * {@link extractNotes} — it is this array sliced by
    * `[frameStart, frameEnd)`, which the caller already holds.
+   * Positive finite values are candidates for pitch. Zero, negative and
+   * non-finite values carry no measurement.
    */
   f0Hz?: Float32Array;
+  /** Per-frame voiced flags for `f0Hz`; false suppresses a candidate and true cannot make an unusable F0 valid. */
+  voiced?: VoicedFlags | null;
   /** F0 frames per second. Required when `f0Hz` is given. */
   frameRate?: number;
   /**
@@ -120,9 +120,11 @@ export interface RenderNotesRequest extends ValidateOptions {
 export interface DecomposeNotePitchRequest {
   /**
    * The note's slice of the F0 track — `f0Hz.subarray(frameStart, frameEnd)`.
-   * Every value must be finite and non-negative; zero denotes an unvoiced frame.
+   * Positive finite values carry pitch; other values carry no measurement.
    */
   f0Hz: Float32Array;
+  /** Per-frame voiced flags matching `f0Hz`; false suppresses a candidate and true cannot make an unusable F0 valid. */
+  voiced?: VoicedFlags | null;
   /** F0 frames per second. */
   frameRate: number;
   /**
@@ -152,10 +154,10 @@ export interface NoteSetRequest extends NoteExtractorOptions, ValidateOptions {
   f0Hz: Float32Array;
   /** F0 frames per second. */
   frameRate: number;
-  /** Per-frame voiced flags (truthy = voiced). Takes precedence over `voicedProb`. */
-  voiced?: VoicedFlags;
-  /** Per-frame voicing probability in `[0, 1]`; read only when `voiced` is omitted. */
-  voicedProb?: Float32Array;
+  /** Per-frame voiced flags (truthy = voiced); takes precedence over `voicedProb` when supplied. Omit or pass `null` to use the probability array. */
+  voiced?: VoicedFlags | null;
+  /** Per-frame voicing probability in `[0, 1]`; read only when `voiced` is omitted or `null`. */
+  voicedProb?: Float32Array | null;
   /** The current note set. Each note's `[frameStart, frameEnd)` must be non-empty and inside the track. */
   notes: readonly NoteSetEntry[];
 }
@@ -285,8 +287,8 @@ export function noteMove(
  * `f0Hz` sliced by `[frameStart, frameEnd)`. The amplitude curve is measured
  * here, so it is, one entry per F0 frame over that note's span.
  *
- * Voicing comes from `voiced` (truthy = voiced). `voicedProb` is read only when
- * `voiced` is absent, and then a frame counts as voiced at or above
+ * Voicing comes from `voiced` (truthy = voiced) when it is supplied. `voicedProb`
+ * is read only when `voiced` is absent or `null`, and then a frame counts as voiced at or above
  * `voicedThreshold` (default 0.5). At least one of the two is required. Because
  * `voicedProb` from pYIN rises with F0 for a fixed frame length, prefer passing
  * a {@link PitchResult}'s `voicedFlag` through `voiced`.
@@ -294,10 +296,11 @@ export function noteMove(
  * @param request - Audio, F0 track, frame cadence and segmenter options
  * @returns One {@link NoteObject} per segmented note, in time order; an empty
  *   array when the track segments to nothing
- * @throws RangeError when `voiced` / `voicedProb` do not match `f0Hz` in length,
- *   or the samples/sample rate fail the shared input checks
+ * @throws RangeError when the selected voicing array differs from `f0Hz` in
+ *   length (`voiced`, or `voicedProb` when `voiced` is omitted or `null`), or the
+ *   samples/sample rate fail the shared input checks
  * @throws SonareError (`InvalidParameter`) on an empty `f0Hz`, a non-positive
- *   `frameRate`, a negative or non-finite `f0Hz` value, a `voicedProb` outside
+ *   `frameRate`, a `voicedProb` outside
  *   `[0, 1]`, or a negative option value
  *
  * @example
@@ -325,7 +328,7 @@ export function extractNotes(request: ExtractNotesRequest): NoteObject[] {
     request.samples,
     request.sampleRate,
     request.f0Hz,
-    request.voicedProb,
+    request.voiced == null ? (request.voicedProb ?? undefined) : undefined,
     voicedF32,
     request.frameRate,
     request,
@@ -354,7 +357,11 @@ export function extractNotes(request: ExtractNotesRequest): NoteObject[] {
  * @param request - Source audio, the notes to render, the cross-fade length, and
  *   the F0 track a vibrato or drift edit reads
  * @returns The rendered audio, the same length and sample rate as the input
- * @throws RangeError when the samples or sample rate fail the shared input checks
+ * @throws TypeError when `notes` is not an array, `f0Hz` is not a
+ *   `Float32Array`, or `voiced` is not a supported flag array
+ * @throws RangeError when `frameRate` is non-finite, `voiced` is supplied
+ *   without `f0Hz`, when its length differs from `f0Hz`, or when the samples or
+ *   sample rate fail shared checks
  * @throws SonareError (`InvalidParameter`) on a note whose span is empty,
  *   reversed or missing, overlapping source spans, a non-finite or non-positive
  *   edit field, a negative or non-finite envelope value, a negative `fadeMs` or
@@ -385,9 +392,28 @@ export function extractNotes(request: ExtractNotesRequest): NoteObject[] {
  * ```
  */
 export function renderNotes(request: RenderNotesRequest): Float32Array {
-  assertSamples('renderNotes', request.samples, request.validate !== false);
   assertSampleRate('renderNotes', request.sampleRate);
-  return requireModule().renderNotes(request.samples, request.sampleRate, request.notes, request);
+  if (!Array.isArray(request.notes)) {
+    throw new TypeError('renderNotes: notes must be an array');
+  }
+  const f0Hz = request.f0Hz;
+  if (f0Hz !== undefined && !(f0Hz instanceof Float32Array)) {
+    throw new TypeError('renderNotes: f0Hz must be a Float32Array');
+  }
+  if (f0Hz !== undefined) {
+    assertFiniteScalar('renderNotes', request.frameRate as number, 'frameRate');
+  }
+  const { voiced: publicVoiced, ...withoutVoiced } = request;
+  const voiced = publicVoiced == null ? undefined : toVoicedFloat32('renderNotes', publicVoiced);
+  if (publicVoiced != null && f0Hz === undefined) {
+    throw new RangeError('renderNotes: voiced requires f0Hz');
+  }
+  if (f0Hz !== undefined) {
+    assertPitchTrackLengths('renderNotes', f0Hz, publicVoiced);
+  }
+  assertSamples('renderNotes', request.samples, request.validate !== false);
+  const options = { ...withoutVoiced, voiced };
+  return requireModule().renderNotes(request.samples, request.sampleRate, request.notes, options);
 }
 
 /**
@@ -401,7 +427,10 @@ export function renderNotes(request: RenderNotesRequest): Float32Array {
  *
  * Frames whose F0 is unusable carry no measurement, so the curve is held at the
  * nearest usable neighbour across them. Both curves therefore have an entry
- * everywhere; a host marking the held ones reads them off `f0Hz`, which is exact.
+ * everywhere; when `voiced` is supplied, a host marking held frames should
+ * retain both the `f0Hz` and `voiced` arrays because a positive F0 can be
+ * explicitly suppressed. A false flag suppresses that frame and a true flag
+ * cannot make an unusable F0 valid.
  *
  * A note with no usable pitch is reported as a zero `centreHz` and two empty
  * curves rather than as an error — that is a measurement which came up empty,
@@ -410,9 +439,12 @@ export function renderNotes(request: RenderNotesRequest): Float32Array {
  * @param request - The note's slice of the F0 track, its cadence, its centre, and
  *   the cutoff
  * @returns The centre and the two curves, each one entry per frame of `f0Hz`
- * @throws SonareError (`InvalidParameter`) on an empty `f0Hz`, a negative or
- *   non-finite `f0Hz` value, a non-positive `frameRate`, a negative `medianHz`,
- *   or a negative `vibratoCutoffHz`
+ * @throws TypeError when `f0Hz` is not a `Float32Array` or `voiced` is not a
+ *   supported flag array
+ * @throws RangeError when `frameRate` is not finite or `voiced` differs in
+ *   length from `f0Hz`
+ * @throws SonareError (`InvalidParameter`) on an empty `f0Hz`, a non-positive
+ *   `frameRate`, a negative `medianHz`, or a negative `vibratoCutoffHz`
  *
  * @example
  * ```ts
@@ -425,8 +457,16 @@ export function renderNotes(request: RenderNotesRequest): Float32Array {
  * ```
  */
 export function decomposeNotePitch(request: DecomposeNotePitchRequest): PitchDecompositionResult {
+  if (!(request.f0Hz instanceof Float32Array)) {
+    throw new TypeError('decomposeNotePitch: f0Hz must be a Float32Array');
+  }
+  assertFiniteScalar('decomposeNotePitch', request.frameRate, 'frameRate');
+  const voiced =
+    request.voiced == null ? undefined : toVoicedFloat32('decomposeNotePitch', request.voiced);
+  assertPitchTrackLengths('decomposeNotePitch', request.f0Hz, request.voiced);
   return requireModule().decomposeNotePitch(
     request.f0Hz,
+    voiced,
     request.frameRate,
     request.medianHz,
     request.vibratoCutoffHz ?? 0,
@@ -438,22 +478,29 @@ export function decomposeNotePitch(request: DecomposeNotePitchRequest): PitchDec
  *
  * Both halves are re-derived from the audio and the track the way
  * {@link extractNotes} derives its own, rather than by patching the fields of
- * the note they replace. Both inherit the source note's edit, and its amplitude
- * envelope is cut at the same proportion so each half keeps its own part of it —
- * a note whose edit is the identity therefore still renders bit for bit after
- * being split.
+ * the note they replace. Both inherit the source note's edit, and the tail's
+ * `timeOffsetSamples` absorbs the duration change of the stretched head, so the
+ * halves occupy the destination timeline the unsplit note did; a note whose edit
+ * is the identity still renders bit for bit after being split. A half with no
+ * sample span at that boundary is omitted and the other keeps the edit
+ * unchanged. A one-entry envelope is a constant over the span, so both halves
+ * get that same entry; a longer one is resampled onto a grid that preserves the
+ * rendered gain at every integer source sample.
  *
  * Every note in the set, not just the two halves, has its spans, curves, medians
  * and stability re-derived from `samples` and the track, because a
  * {@link NoteSetEntry} carries no curves for this call to copy through. The
  * frame bounds are therefore what a note is identified by here, and the audio
  * and track must be the ones the set was extracted from or the whole set is
- * re-measured against something else.
+ * re-measured against something else. A set whose re-derived notes would
+ * include one with no sample span is rejected rather than shortened.
  *
  * @param request - The source, the current note set, and where to cut
- * @returns The whole new note set, one note longer than the one handed in
- * @throws RangeError when `voiced` / `voicedProb` do not match `f0Hz` in length,
- *   or the samples/sample rate fail the shared input checks
+ * @returns The whole new note set, one note longer than the one handed in, or
+ *   the same length when a half with no sample span is omitted
+ * @throws RangeError when the selected voicing array differs from `f0Hz` in
+ *   length (`voiced`, or `voicedProb` when `voiced` is omitted or `null`), or the
+ *   samples/sample rate fail the shared input checks
  * @throws SonareError (`InvalidParameter`) on an out-of-range `index`, a `frame`
  *   that is not strictly inside that note's own span, a note whose frame span is
  *   empty or runs past the track, or the track arguments {@link extractNotes}
@@ -480,7 +527,7 @@ export function splitNote(request: SplitNoteRequest): NoteObject[] {
     request.samples,
     request.sampleRate,
     request.f0Hz,
-    request.voicedProb,
+    request.voiced == null ? (request.voicedProb ?? undefined) : undefined,
     voicedF32,
     request.frameRate,
     request.notes,
@@ -507,8 +554,9 @@ export function splitNote(request: SplitNoteRequest): NoteObject[] {
  * @param request - The source, the current note set, and the run to join
  * @returns The whole new note set, `last - first` notes shorter than the one
  *   handed in
- * @throws RangeError when `voiced` / `voicedProb` do not match `f0Hz` in length,
- *   or the samples/sample rate fail the shared input checks
+ * @throws RangeError when the selected voicing array differs from `f0Hz` in
+ *   length (`voiced`, or `voicedProb` when `voiced` is omitted or `null`), or the
+ *   samples/sample rate fail the shared input checks
  * @throws SonareError (`InvalidParameter`) unless `first < last < notes.length`,
  *   on a note whose frame span is empty or runs past the track, or on the track
  *   arguments {@link extractNotes} itself rejects
@@ -534,7 +582,7 @@ export function mergeNotes(request: MergeNotesRequest): NoteObject[] {
     request.samples,
     request.sampleRate,
     request.f0Hz,
-    request.voicedProb,
+    request.voiced == null ? (request.voicedProb ?? undefined) : undefined,
     voicedF32,
     request.frameRate,
     request.notes,

package/src/effects_timepitch.ts

@@ -3,7 +3,7 @@
  * correction onto a target pitch.
  */
 
-import { toVoicedFloat32 } from './_effects_common';
+import { assertPitchTrackLengths, toVoicedFloat32 } from './_effects_common';
 import { resolveFftOptions } from './_fft_options';
 import { getSonareModule } from './module_state';
 import type { PitchCorrectOptions, VoicedFlags } from './public_types';
@@ -43,8 +43,8 @@ export interface PitchCorrectToMidiTimevaryingRequest extends ValidateOptions {
   targetMidi: number;
   sampleRate?: number;
   hopLength?: number;
-  voiced?: VoicedFlags;
-  voicedProb?: Float32Array;
+  voiced?: VoicedFlags | null;
+  voicedProb?: Float32Array | null;
 }
 
 export interface PitchCorrectTimevaryingRequest extends PitchCorrectOptions {
@@ -250,19 +250,23 @@ export function pitchCorrectToMidi(
  * Unlike {@link pitchCorrectToMidi} (a single constant transpose), this follows
  * the caller-supplied per-frame `f0Hz` contour and retunes every voiced frame
  * toward `targetMidi`, so vibrato/drift in the source is tracked rather than
- * flattened. `voiced` (truthy = voiced) and `voicedProb` ([0,1]) are optional;
- * omitting them treats every frame as voiced. An `f0Hz` NaN is accepted only
- * when the corresponding `voiced` entry is falsy, matching pYIN output. The
- * `voicedFlag` / `voicedProb` arrays of a {@link PitchResult} can be passed
- * through directly.
+ * flattened. When `voiced` is supplied (truthy = voiced), it takes precedence
+ * over `voicedProb`; omitting it or passing `null` uses the probability array.
+ * When both are omitted, every frame is treated as voiced. An `f0Hz` NaN is
+ * accepted only for a frame marked unvoiced, matching pYIN output. The
+ * `voicedFlag` / `voicedProb` arrays of a {@link PitchResult} can
+ * be passed through directly.
  *
  * @param samples - Audio samples (mono, float32)
  * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
  * @param targetMidi - Desired MIDI note number
  * @param sampleRate - Sample rate in Hz
- * @param hopLength - F0 hop in samples (frame i covers sample i*hopLength)
- * @param voiced - Optional per-frame voiced flags (truthy = voiced)
- * @param voicedProb - Optional per-frame voicing probability in [0, 1]
+ * @param hopLength - F0 frame-center spacing in samples. Frame i is centered at
+ *   sample i*hopLength; nearest-frame voicing switches halfway between centers.
+ * @param voiced - Optional per-frame voiced flags (truthy = voiced); takes
+ *   precedence over `voicedProb`.
+ * @param voicedProb - Optional per-frame voicing probability in [0, 1]; used
+ *   when `voiced` is omitted or `null`.
  * @returns Pitch-corrected audio
  */
 export function pitchCorrectToMidiTimevarying(
@@ -274,8 +278,8 @@ export function pitchCorrectToMidiTimevarying(
   targetMidi: number,
   sampleRate?: number,
   hopLength?: number,
-  voiced?: VoicedFlags,
-  voicedProb?: Float32Array,
+  voiced?: VoicedFlags | null,
+  voicedProb?: Float32Array | null,
   options?: ValidateOptions,
 ): Float32Array;
 export function pitchCorrectToMidiTimevarying(
@@ -284,8 +288,8 @@ export function pitchCorrectToMidiTimevarying(
   targetMidi?: number,
   sampleRate = 22050,
   hopLength = 512,
-  voiced?: VoicedFlags,
-  voicedProb?: Float32Array,
+  voiced?: VoicedFlags | null,
+  voicedProb?: Float32Array | null,
   options: ValidateOptions = {},
 ): Float32Array {
   const request: PitchCorrectToMidiTimevaryingRequest =
@@ -302,13 +306,16 @@ export function pitchCorrectToMidiTimevarying(
         }
       : samples;
   assertSamples('pitchCorrectToMidiTimevarying', request.samples, request.validate !== false);
-  if (request.voiced && request.voiced.length !== request.f0Hz.length) {
-    throw new RangeError('pitchCorrectToMidiTimevarying: voiced length must match f0Hz length');
-  }
-  if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
-    throw new RangeError('pitchCorrectToMidiTimevarying: voicedProb length must match f0Hz length');
-  }
-  const voicedF32 = request.voiced ? toVoicedFloat32(request.voiced) : undefined;
+  const voicedF32 =
+    request.voiced == null
+      ? undefined
+      : toVoicedFloat32('pitchCorrectToMidiTimevarying', request.voiced);
+  assertPitchTrackLengths(
+    'pitchCorrectToMidiTimevarying',
+    request.f0Hz,
+    request.voiced,
+    request.voicedProb,
+  );
   return requireModule().pitchCorrectToMidiTimevarying(
     request.samples,
     request.sampleRate ?? 22050,
@@ -316,7 +323,7 @@ export function pitchCorrectToMidiTimevarying(
     request.targetMidi,
     request.hopLength ?? 512,
     voicedF32,
-    request.voicedProb,
+    request.voiced == null ? (request.voicedProb ?? undefined) : undefined,
   );
 }
 
@@ -333,7 +340,8 @@ export function pitchCorrectToMidiTimevarying(
  * @param samples - Audio samples (mono, float32)
  * @param f0Hz - Per-frame measured F0 in Hz (one entry per analysis frame)
  * @param sampleRate - Sample rate in Hz
- * @param hopLength - F0 hop in samples (frame i covers sample i*hopLength)
+ * @param hopLength - F0 frame-center spacing in samples. Frame i is centered at
+ *   sample i*hopLength; nearest-frame voicing switches halfway between centers.
  * @param options - Target mode + retune knobs + optional voiced/voicedProb arrays
  * @returns Pitch-corrected audio
  */
@@ -357,15 +365,18 @@ export function pitchCorrectTimevarying(
       ? { samples, f0Hz: f0Hz as Float32Array, sampleRate, hopLength, ...options }
       : samples;
   assertSamples('pitchCorrectTimevarying', request.samples, request.validate !== false);
-  if (request.voiced && request.voiced.length !== request.f0Hz.length) {
-    throw new RangeError('pitchCorrectTimevarying: voiced length must match f0Hz length');
-  }
-  if (request.voicedProb && request.voicedProb.length !== request.f0Hz.length) {
-    throw new RangeError('pitchCorrectTimevarying: voicedProb length must match f0Hz length');
-  }
+  const voicedF32 =
+    request.voiced == null ? undefined : toVoicedFloat32('pitchCorrectTimevarying', request.voiced);
+  assertPitchTrackLengths(
+    'pitchCorrectTimevarying',
+    request.f0Hz,
+    request.voiced,
+    request.voicedProb,
+  );
   const nativeOptions = {
     ...request,
-    voiced: request.voiced ? toVoicedFloat32(request.voiced) : undefined,
+    voiced: voicedF32,
+    voicedProb: request.voiced == null ? (request.voicedProb ?? undefined) : undefined,
   };
   return requireModule().pitchCorrectTimevarying(
     request.samples,

package/src/feature_decompose.ts

@@ -233,7 +233,7 @@ export function decomposeWithInit(
 /** Options for {@link decomposeStems}. */
 export interface DecomposeStemsRequest {
   samples: Float32Array;
-  sampleRate: number;
+  sampleRate?: number;
   /** Number of NMF components (default 4). */
   nComponents?: number;
   /** STFT size (default 2048). */
@@ -278,7 +278,7 @@ export interface DecomposeStemsResult {
  * to the input.
  */
 export function decomposeStems(request: DecomposeStemsRequest): DecomposeStemsResult {
-  return requireModule().decomposeStems(request.samples, request.sampleRate, {
+  return requireModule().decomposeStems(request.samples, request.sampleRate ?? 22050, {
     nComponents: request.nComponents,
     nFft: request.nFft,
     hopLength: request.hopLength,