@libraz/libsonare 1.7.2 → 1.8.1

package/dist/effects_percussive.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Percussive event editing: locating struck sounds in audio and rendering an
+ * edited set of them back.
+ */
+import type { PercussiveEvent, PercussiveEventInput } from './public_types';
+import type { ValidateOptions } from './validation';
+/**
+ * The separation a percussive event's signal is lifted out with. Extraction
+ * measures events against it and rendering has to repeat it, so both calls take
+ * the same four fields and a render must be given what the extraction was.
+ */
+export interface PercussiveSeparationOptions {
+    /**
+     * FFT size and hop the separation and the onset detector share. They cannot be
+     * set apart: an event measured on one framing and lifted out on another is not
+     * the same signal. Default 2048 and 512. The pair must overlap-add — `nFft`
+     * even and at least 2, `hopLength` no more than half of it — because the
+     * separation inverts an STFT. A negative value is rejected on its own, before
+     * the zero-is-default rule could swallow it.
+     */
+    nFft?: number;
+    /** Hop length in samples. Default 512. */
+    hopLength?: number;
+    /**
+     * Median filter lengths the separation runs, along time and along frequency. A
+     * longer harmonic kernel calls more of a sustained sound harmonic. Default 31;
+     * any other value must be odd and positive, so an even one is rejected rather
+     * than rounded. 1 is legal and degenerate rather than an error: a length-1
+     * median is the identity, so both components come back as the source.
+     */
+    hpssKernelHarmonic?: number;
+    /** Vertical median filter length, under the same rule. Default 31. */
+    hpssKernelPercussive?: number;
+}
+/** Canonical request form for {@link extractPercussiveEvents}. */
+export interface ExtractPercussiveEventsRequest extends PercussiveSeparationOptions, ValidateOptions {
+    samples: Float32Array | readonly number[];
+    /**
+     * Sample rate in Hz. Required: `maxEventMs` is converted to samples with this
+     * rate, so a wrong/omitted value caps the spans differently.
+     */
+    sampleRate: number;
+    /**
+     * Minimum frames between consecutive onsets. Default 1, and a whole number:
+     * 0 is how the default is spelled, so a fractional wait is refused rather
+     * than truncated onto it. Negative is rejected.
+     */
+    onsetWait?: number;
+    /**
+     * Offset added to the detector's adaptive threshold; raising it finds fewer,
+     * stronger hits and lowering it finds more. Default 0.06, so exactly zero is
+     * the one value not selectable here — a negative one is accepted and puts the
+     * threshold below the default, which is the direction a caller reaching for
+     * zero wanted anyway.
+     */
+    onsetDelta?: number;
+    /**
+     * Caps a span that no onset follows. It binds at the end of a phrase and at the
+     * end of the track; anywhere else the next onset closes the span first. Default
+     * 500 ms.
+     */
+    maxEventMs?: number;
+    /**
+     * Drops an event whose `percussiveRatio` falls below this; must be in `[0, 1]`.
+     * 0 is both the default and the meaningful "keep everything". Raising it is
+     * useful on material that is mostly drums and wrong on a dense mix, where it
+     * also drops real hits sitting over a loud sustain.
+     */
+    minPercussiveRatio?: number;
+}
+/** Canonical request form for {@link renderPercussiveEvents}. */
+export interface RenderPercussiveEventsRequest extends PercussiveSeparationOptions, ValidateOptions {
+    samples: Float32Array | readonly number[];
+    /**
+     * Sample rate in Hz. Required: `fadeMs` is converted to samples with this rate,
+     * so a wrong/omitted value changes the fade length.
+     */
+    sampleRate: number;
+    /** The events to render, with their edits. Source spans must not overlap. */
+    events: readonly PercussiveEventInput[];
+    /**
+     * Fade-out at the tail of each lifted span. Default 5 ms, so a zero-length
+     * fade is unreachable here rather than rejected — and a hard cut is not a thing
+     * to want anyway, because what the fade shapes is the signal being subtracted,
+     * so squaring it off leaves a step. There is deliberately
+     * no matching fade-in: a span opens in front of its transient, where the
+     * percussive component is near-silent, so cutting square there costs nothing
+     * and keeps a muted hit's attack from surviving inside a fade.
+     */
+    fadeMs?: number;
+}
+/**
+ * Extract editable percussive events from audio alone.
+ *
+ * Each event is a struck sound located in time: a span in source samples, its
+ * detector strength, the percussive peak over the span, the share of the span's
+ * energy the separation called percussive, and an identity
+ * {@link PercussiveEventEdit}. Edit the events and hand them to
+ * {@link renderPercussiveEvents} to apply the result — the source audio is never
+ * mutated, and a set whose edits are all identity renders back to the input bit
+ * for bit.
+ *
+ * Onsets are detected on the percussive component rather than on the source, so
+ * a harmonic attack is attenuated before the detector sees it instead of being
+ * filtered out afterwards. Each onset opens a span that the next one closes,
+ * capped by `maxEventMs` and never running past the end of the audio.
+ *
+ * Each onset is backtracked to the transient's start, which is not optional and
+ * is why there is no knob for it: peak-picking lands after the attack, and a span
+ * that opened there would report the next hit's peak and leave its own attack
+ * behind when muted.
+ *
+ * An event carries no pitch and is never associated with a {@link NoteObject} —
+ * a struck sound has no steady F0 to edit, so the two models are extracted by
+ * separate calls.
+ *
+ * @param request - Audio, its sample rate, and the separation, peak-picking and
+ *   span options
+ * @returns One {@link PercussiveEvent} per detected hit, in time order; an empty
+ *   array when nothing was detected
+ * @throws RangeError when the samples or sample rate fail the shared input checks
+ * @throws SonareError (`InvalidParameter`) on a kernel size that is not an
+ *   integer within the 32-bit range, a framing size that is negative or outside
+ *   that range, a framing that breaks constant overlap-add, an `onsetWait` that
+ *   is fractional, negative or non-finite, a negative or non-finite `onsetDelta`
+ *   / `maxEventMs`, or a `minPercussiveRatio` outside `[0, 1]`
+ *
+ * @example
+ * ```ts
+ * const events = extractPercussiveEvents({ samples, sampleRate });
+ * // Drop the second hit and push the third 10 ms late.
+ * events[1].edit.muted = true;
+ * events[2].edit.timeOffsetSamples = Math.round(0.01 * sampleRate);
+ * const edited = renderPercussiveEvents({ samples, sampleRate, events });
+ * ```
+ */
+export declare function extractPercussiveEvents(request: ExtractPercussiveEventsRequest): PercussiveEvent[];
+/**
+ * Render edited percussive events back over their source audio.
+ *
+ * Per event the lifted signal is the percussive component over
+ * `[onsetSample, offsetSample)` under the tail fade. It is subtracted where it
+ * sits and, unless the event is muted, added back at the shifted position scaled
+ * by the gain. Only that signal moves, so muting a hit leaves the harmonic
+ * content under it sounding and moving one does not drag its neighbours' sustain
+ * along.
+ *
+ * Each event's span and `edit` are read; `strength`, `peakAmplitude` and
+ * `percussiveRatio` are ignored, so an extracted event can be passed back as-is,
+ * or an event can be built by hand from the span alone. A set whose edits are all
+ * identity reproduces the input bit for bit and runs no separation at all.
+ *
+ * Pass the separation the events were extracted with: a different one lifts a
+ * different signal out of the span than the one the events describe. It is
+ * validated even when every edit is the identity and no separation runs, so an
+ * unusable framing is an error on every set rather than on some of them.
+ *
+ * Overlap is checked on the source spans only. Where `timeOffsetSamples` lands an
+ * event is not, so two moved events may be written over each other, and a shift
+ * that pushes the signal past either end is truncated there rather than wrapped.
+ *
+ * @param request - Source audio, the events to render, the separation and the
+ *   tail fade
+ * @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 SonareError (`InvalidParameter`) on an event whose span is empty,
+ *   reversed or outside the audio, overlapping source spans, a non-finite
+ *   `gainDb`, a kernel size that is not an integer within the 32-bit range, a
+ *   framing that breaks constant overlap-add, or a negative or non-finite
+ *   `fadeMs`
+ *
+ * @example
+ * ```ts
+ * const events = extractPercussiveEvents({ samples, sampleRate });
+ *
+ * // Lift the loudest hit by 3 dB and leave the rest untouched.
+ * const loudest = events.reduce((a, b) => (a.strength >= b.strength ? a : b));
+ * const edited = events.map((event) =>
+ *   event === loudest ? { ...event, edit: { ...event.edit, gainDb: 3 } } : event,
+ * );
+ * const rendered = renderPercussiveEvents({ samples, sampleRate, events: edited });
+ * ```
+ */
+export declare function renderPercussiveEvents(request: RenderPercussiveEventsRequest): Float32Array;
+//# sourceMappingURL=effects_percussive.d.ts.map

package/dist/effects_percussive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects_percussive.d.ts","sourceRoot":"","sources":["../src/effects_percussive.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAOpD;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,kEAAkE;AAClE,MAAM,WAAW,8BACf,SAAQ,2BAA2B,EACjC,eAAe;IACjB,OAAO,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,CAAC;IAC1C;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,iEAAiE;AACjE,MAAM,WAAW,6BACf,SAAQ,2BAA2B,EACjC,eAAe;IACjB,OAAO,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,CAAC;IAC1C;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACxC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,8BAA8B,GACtC,eAAe,EAAE,CAKnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,YAAY,CAU3F"}

package/dist/effects_separation.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Harmonic/percussive separation: the masked split and the two shortcuts
+ * that return a single component.
+ */
+import type { HpssResult } from './public_types';
+import type { ValidateOptions } from './validation';
+/** Canonical request form for HPSS. */
+export interface HpssRequest {
+    samples: Float32Array;
+    sampleRate?: number;
+    /**
+     * Horizontal median filter size, in STFT frames: a positive odd integer at
+     * most 524287. Default 31. The ceiling is 524288 and an even kernel is
+     * refused, so 524287 is the largest legal value.
+     */
+    kernelHarmonic?: number;
+    /** Vertical median filter size, in STFT bins, under the same rule. Default 31. */
+    kernelPercussive?: number;
+    nFft?: number;
+    hopLength?: number;
+    hardMask?: boolean;
+}
+export interface HarmonicRequest extends ValidateOptions {
+    samples: Float32Array;
+    sampleRate?: number;
+}
+export interface PercussiveRequest extends ValidateOptions {
+    samples: Float32Array;
+    sampleRate?: number;
+}
+/**
+ * Perform Harmonic-Percussive Source Separation (HPSS).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param kernelHarmonic - Horizontal median filter size in STFT frames; a
+ *   positive odd integer at most 524287 (default: 31)
+ * @param kernelPercussive - Vertical median filter size in STFT bins, under the
+ *   same rule (default: 31)
+ * @returns Separated harmonic and percussive components
+ * @throws SonareError (`InvalidParameter`) on a kernel that is not an integer
+ *   within the signed 32-bit range, or one the core rejects as even,
+ *   non-positive or above its ceiling
+ */
+export declare function hpss(request: HpssRequest): HpssResult;
+export declare function hpss(samples: Float32Array, sampleRate?: number, kernelHarmonic?: number, kernelPercussive?: number, nFft?: number, hopLength?: number, hardMask?: boolean): HpssResult;
+/**
+ * Extract harmonic component from audio.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @returns Harmonic component
+ */
+export declare function harmonic(request: HarmonicRequest): Float32Array;
+export declare function harmonic(samples: Float32Array, sampleRate?: number, options?: ValidateOptions): Float32Array;
+/**
+ * Extract percussive component from audio.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @returns Percussive component
+ */
+export declare function percussive(request: PercussiveRequest): Float32Array;
+export declare function percussive(samples: Float32Array, sampleRate?: number, options?: ValidateOptions): Float32Array;
+//# sourceMappingURL=effects_separation.d.ts.map

package/dist/effects_separation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects_separation.d.ts","sourceRoot":"","sources":["../src/effects_separation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAiBpD,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,CAAC;AACvD,wBAAgB,IAAI,CAClB,OAAO,EAAE,YAAY,EACrB,UAAU,CAAC,EAAE,MAAM,EACnB,cAAc,CAAC,EAAE,MAAM,EACvB,gBAAgB,CAAC,EAAE,MAAM,EACzB,IAAI,CAAC,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,OAAO,GACjB,UAAU,CAAC;AA8Bd;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,YAAY,CAAC;AACjE,wBAAgB,QAAQ,CACtB,OAAO,EAAE,YAAY,EACrB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,eAAe,GACxB,YAAY,CAAC;AAWhB;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,YAAY,CAAC;AACrE,wBAAgB,UAAU,CACxB,OAAO,EAAE,YAAY,EACrB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,eAAe,GACxB,YAAY,CAAC"}

package/dist/effects_spectral.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Region-based spectral editing: time x frequency rectangles applied over an
+ * STFT and resynthesized.
+ */
+import type { SpectralEditOptions, SpectralRegionOp } from './public_types';
+import type { ValidateOptions } from './validation';
+export interface SpectralEditRequest extends SpectralEditOptions, ValidateOptions {
+    samples: Float32Array;
+    sampleRate: number;
+    ops?: SpectralRegionOp[];
+}
+/**
+ * Apply region-based spectral edits (gain/attenuate/mute/heal) to mono audio.
+ *
+ * Each op is a time x frequency rectangle applied in array order over a single
+ * STFT buffer, so a later op observes the result of earlier ops. The output has
+ * the same length and sample rate as the input; an empty `ops` list is an
+ * identity transform (within the iSTFT's own tolerance).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param ops - Region edit ops applied in order ({@link SpectralRegionOp})
+ * @param options - STFT + heal configuration ({@link SpectralEditOptions})
+ * @returns Edited audio
+ */
+export declare function spectralEdit(request: SpectralEditRequest): Float32Array;
+export declare function spectralEdit(samples: Float32Array, sampleRate: number, ops?: SpectralRegionOp[], options?: SpectralEditOptions & ValidateOptions): Float32Array;
+//# sourceMappingURL=effects_spectral.d.ts.map

package/dist/effects_spectral.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects_spectral.d.ts","sourceRoot":"","sources":["../src/effects_spectral.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAOpD,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB,EAAE,eAAe;IAC/E,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAAC;AACzE,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,GAAG,CAAC,EAAE,gBAAgB,EAAE,EACxB,OAAO,CAAC,EAAE,mBAAmB,GAAG,eAAe,GAC9C,YAAY,CAAC"}

package/dist/effects_timepitch.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Time and pitch transforms over a whole buffer: stretching, shifting, and
+ * correction onto a target pitch.
+ */
+import type { PitchCorrectOptions, VoicedFlags } from './public_types';
+import type { ValidateOptions } from './validation';
+export interface TimeStretchRequest extends ValidateOptions {
+    samples: Float32Array;
+    sampleRate?: number;
+    rate: number;
+    nFft?: number;
+    hopLength?: number;
+}
+export interface PitchShiftRequest extends ValidateOptions {
+    samples: Float32Array;
+    sampleRate?: number;
+    semitones: number;
+    nFft?: number;
+    hopLength?: number;
+}
+export interface PitchCorrectToMidiRequest extends ValidateOptions {
+    samples: Float32Array;
+    sampleRate?: number;
+    currentMidi?: number;
+    targetMidi?: number;
+}
+export interface PitchCorrectToMidiTimevaryingRequest extends ValidateOptions {
+    samples: Float32Array;
+    f0Hz: Float32Array;
+    targetMidi: number;
+    sampleRate?: number;
+    hopLength?: number;
+    voiced?: VoicedFlags | null;
+    voicedProb?: Float32Array | null;
+}
+export interface PitchCorrectTimevaryingRequest extends PitchCorrectOptions {
+    samples: Float32Array;
+    f0Hz: Float32Array;
+    sampleRate?: number;
+    hopLength?: number;
+}
+/**
+ * Time-stretch audio without changing pitch.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param rate - Time stretch rate (0.5 = double duration, 2.0 = half duration)
+ * @param nFft - FFT size: an even integer >= 2 (default 2048)
+ * @param hopLength - Hop in samples, in `(0, nFft / 2]` (default 512), so
+ *   frames overlap by at least half a window
+ * @returns Time-stretched audio
+ */
+export declare function timeStretch(request: TimeStretchRequest): Float32Array;
+export declare function timeStretch(samples: Float32Array, sampleRate: number, rate: number, options?: ValidateOptions): Float32Array;
+export declare function timeStretch(samples: Float32Array, sampleRate: number, rate: number, nFft?: number, hopLength?: number, options?: ValidateOptions): Float32Array;
+/**
+ * Pitch-shift audio without changing duration.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param semitones - Pitch shift in semitones (+12 = one octave up, -12 = one octave down)
+ * @param nFft - FFT size: an even integer >= 2 (default 2048)
+ * @param hopLength - Hop in samples, in `(0, nFft / 2]` (default 512), so
+ *   frames overlap by at least half a window
+ * @returns Pitch-shifted audio
+ */
+export declare function pitchShift(request: PitchShiftRequest): Float32Array;
+export declare function pitchShift(samples: Float32Array, sampleRate: number, semitones: number, options?: ValidateOptions): Float32Array;
+export declare function pitchShift(samples: Float32Array, sampleRate: number, semitones: number, nFft?: number, hopLength?: number, options?: ValidateOptions): Float32Array;
+/**
+ * Pitch-correct audio from a current MIDI note to a target MIDI note.
+ *
+ * Applies one constant, immediate transpose with no retune glide and preserves
+ * the input buffer length. The whole interval is applied however large it is:
+ * both endpoints are validated to [0, 127], so a two-octave move such as
+ * C3 -> C5 transposes by the full 24 semitones. Use
+ * {@link pitchCorrectToMidiTimevarying} for a caller-supplied pitch contour.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param currentMidi - Detected/current MIDI note number
+ * @param targetMidi - Desired MIDI note number
+ * @returns Pitch-corrected audio
+ */
+export declare function pitchCorrectToMidi(request: PitchCorrectToMidiRequest): Float32Array;
+export declare function pitchCorrectToMidi(samples: Float32Array, sampleRate?: number, currentMidi?: number, targetMidi?: number, options?: ValidateOptions): Float32Array;
+/**
+ * Contour-following ("time-varying") pitch correction toward a MIDI target.
+ *
+ * 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. 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 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 declare function pitchCorrectToMidiTimevarying(request: PitchCorrectToMidiTimevaryingRequest): Float32Array;
+export declare function pitchCorrectToMidiTimevarying(samples: Float32Array, f0Hz: Float32Array, targetMidi: number, sampleRate?: number, hopLength?: number, voiced?: VoicedFlags | null, voicedProb?: Float32Array | null, options?: ValidateOptions): Float32Array;
+/**
+ * Contour-following pitch correction toward a fixed MIDI note OR a musical
+ * scale, with tunable retune strength and vibrato preservation.
+ *
+ * Generalises {@link pitchCorrectToMidiTimevarying}: the same caller-supplied
+ * per-frame `f0Hz` contour drives correction, but `options.mode` selects between
+ * a fixed-MIDI target (`'midi'`, default) and scale quantisation (`'scale'`),
+ * and the retune knobs shape natural-vs-robotic correction. An `f0Hz` NaN is
+ * accepted only for a frame marked unvoiced.
+ *
+ * @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 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
+ */
+export declare function pitchCorrectTimevarying(request: PitchCorrectTimevaryingRequest): Float32Array;
+export declare function pitchCorrectTimevarying(samples: Float32Array, f0Hz: Float32Array, sampleRate?: number, hopLength?: number, options?: PitchCorrectOptions): Float32Array;
+//# sourceMappingURL=effects_timepitch.d.ts.map

package/dist/effects_timepitch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects_timepitch.d.ts","sourceRoot":"","sources":["../src/effects_timepitch.ts"],"names":[],"mappings":"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"}

package/dist/effects_voice_change.d.ts

@@ -0,0 +1,53 @@
+import type { RealtimeVoiceChangerConfigInput } from './public_types';
+import type { ValidateOptions } from './validation';
+/** Options for {@link voiceChange}. All fields are optional. */
+export interface VoiceChangeOptions extends ValidateOptions {
+    /** Pitch shift in semitones (negative = down). Default 0. */
+    pitchSemitones?: number;
+    /** Formant scale factor (>1 brightens, <1 darkens). Default 1. */
+    formantFactor?: number;
+}
+/** Canonical request form for one-shot voice changing. */
+export interface VoiceChangeRequest extends VoiceChangeOptions {
+    samples: Float32Array;
+    sampleRate?: number;
+}
+/**
+ * Apply a voice change by shifting pitch and formants independently.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param options - Pitch/formant settings ({@link VoiceChangeOptions})
+ * @returns Voice-changed audio
+ */
+export declare function voiceChange(request: VoiceChangeRequest): Float32Array;
+export declare function voiceChange(samples: Float32Array, sampleRate?: number, options?: VoiceChangeOptions): Float32Array;
+/** Options for the offline {@link voiceChangeRealtime} convenience wrapper. */
+export interface VoiceChangeRealtimeOptions extends ValidateOptions {
+    /** Channel count (1 = mono, 2 = interleaved stereo). */
+    channels?: 1 | 2;
+    /** @deprecated The shared C-ABI renderer uses a fixed cross-surface block size. */
+    blockSize?: number;
+}
+/** Canonical request form for offline realtime voice changing. */
+export interface VoiceChangeRealtimeRequest extends VoiceChangeRealtimeOptions {
+    samples: Float32Array;
+    sampleRate?: number;
+    preset?: RealtimeVoiceChangerConfigInput;
+}
+/**
+ * Applies the realtime voice-changer chain to a whole buffer in one call.
+ *
+ * Uses the shared C-ABI renderer, so Python, Node, and WASM use the same
+ * fixed block size and latency compensation. For mono, `samples` is a plain
+ * buffer; for stereo, it is interleaved (L0,R0,L1,R1,...).
+ *
+ * @param samples - Audio samples (mono, or interleaved stereo when channels=2)
+ * @param sampleRate - Sample rate in Hz (default 48000, matching Python/Node)
+ * @param preset - Voice-changer preset id or full config object
+ * @param options - Channel count and block size ({@link VoiceChangeRealtimeOptions})
+ * @returns The processed buffer (same layout/length as the input).
+ */
+export declare function voiceChangeRealtime(request: VoiceChangeRealtimeRequest): Float32Array;
+export declare function voiceChangeRealtime(samples: Float32Array, sampleRate?: number, preset?: RealtimeVoiceChangerConfigInput, options?: VoiceChangeRealtimeOptions): Float32Array;
+//# sourceMappingURL=effects_voice_change.d.ts.map

package/dist/effects_voice_change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects_voice_change.d.ts","sourceRoot":"","sources":["../src/effects_voice_change.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAOpD,gEAAgE;AAChE,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,YAAY,CAAC;AACvE,wBAAgB,WAAW,CACzB,OAAO,EAAE,YAAY,EACrB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,YAAY,CAAC;AAgBhB,+EAA+E;AAC/E,MAAM,WAAW,0BAA2B,SAAQ,eAAe;IACjE,wDAAwD;IACxD,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACjB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kEAAkE;AAClE,MAAM,WAAW,0BAA2B,SAAQ,0BAA0B;IAC5E,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,+BAA+B,CAAC;CAC1C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,YAAY,CAAC;AACvF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,YAAY,EACrB,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,+BAA+B,EACxC,OAAO,CAAC,EAAE,0BAA0B,GACnC,YAAY,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Numeric error codes carried by a {@link SonareError}. Mirrors the C ABI
+ * `SonareError` enum (and the Node / Python surfaces), so the same failure
+ * reports the same numeric code on every binding.
+ */
+export declare enum ErrorCode {
+    Ok = 0,
+    FileNotFound = 1,
+    InvalidFormat = 2,
+    DecodeFailed = 3,
+    InvalidParameter = 4,
+    OutOfMemory = 5,
+    NotSupported = 6,
+    InvalidState = 7,
+    Cancelled = 8,
+    EncodeFailed = 9,
+    Unknown = 99
+}
+/**
+ * Error thrown by libsonare on a native (C++) failure. Carries a numeric
+ * {@link ErrorCode} `code` plus its canonical `codeName`, so callers can branch
+ * on the cause instead of matching message text.
+ *
+ * Narrow a caught value with {@link isSonareError} or with `instanceof`; both
+ * accept the same values. The Node package exports the same class under the
+ * same name.
+ */
+export declare class SonareError extends Error {
+    /** Numeric error code, equal to an {@link ErrorCode} value. */
+    readonly code: number;
+    /** Canonical name of `code`, e.g. `'InvalidParameter'`. */
+    readonly codeName: string;
+    constructor(code: number, codeName: string, message: string);
+    /**
+     * Brand-based `instanceof`: an error that carries the shape narrows here even
+     * when it is not literally an instance of this class. That is not a
+     * hypothetical — an error posted from the analysis worker arrives as a
+     * structured clone with its prototype gone, which a prototype-based
+     * `instanceof` would silently miss. Delegates to {@link isSonareError} so the
+     * two never disagree.
+     */
+    static [Symbol.hasInstance](value: unknown): value is SonareError;
+}
+/**
+ * Type guard: whether a caught value is a libsonare {@link SonareError}.
+ *
+ * Duck-typed on purpose: a value that crossed a worker boundary has lost its
+ * prototype, so a prototype check would miss it.
+ */
+export declare function isSonareError(value: unknown): value is SonareError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oBAAY,SAAS;IACnB,EAAE,IAAI;IACN,YAAY,IAAI;IAChB,aAAa,IAAI;IACjB,YAAY,IAAI;IAChB,gBAAgB,IAAI;IACpB,WAAW,IAAI;IACf,YAAY,IAAI;IAChB,YAAY,IAAI;IAChB,SAAS,IAAI;IACb,YAAY,IAAI;IAChB,OAAO,KAAK;CACb;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAO3D;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW;CAGlE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAMlE"}