@libraz/libsonare 1.7.2 → 1.8.0

package/dist/stream_types.d.ts

@@ -0,0 +1,214 @@
+import type { ChordQuality, PitchClass } from './public_types';
+/**
+ * A detected chord change in the progression
+ */
+export interface ChordChange {
+    root: PitchClass;
+    quality: ChordQuality;
+    startTime: number;
+    confidence: number;
+}
+/**
+ * A chord detected at bar boundary (beat-synchronized)
+ */
+export interface BarChord {
+    /**
+     * Bar number, not the index of this entry in the array: bars with no
+     * confident chord are not recorded and the oldest entries are dropped at the
+     * history cap. Group bars by pattern position with this, never with the array
+     * index. In `votedPattern` it is the pattern position instead.
+     */
+    barIndex: number;
+    root: PitchClass;
+    quality: ChordQuality;
+    /**
+     * Start of the bar, on the same timeline as `StreamFrame.timestamp`
+     * (including a `sampleOffset` anchor). Consecutive bars are `barDuration`
+     * apart rather than snapped to the analysis frame grid. Unused in
+     * `votedPattern`.
+     */
+    startTime: number;
+    confidence: number;
+}
+/**
+ * Pattern score for known chord progressions
+ */
+export interface PatternScore {
+    name: string;
+    score: number;
+}
+/**
+ * Progressive estimation results for BPM, Key, and Chord
+ */
+export interface ProgressiveEstimate {
+    bpm: number;
+    bpmConfidence: number;
+    /**
+     * Tempo candidates the most recent BPM estimate chose from; 0 until an
+     * estimate has run. Same quantity as the batch analysis result's field of the
+     * same name.
+     */
+    bpmCandidateCount: number;
+    key: PitchClass;
+    keyMinor: boolean;
+    keyConfidence: number;
+    chordRoot: PitchClass;
+    chordQuality: ChordQuality;
+    chordConfidence: number;
+    chordStartTime: number;
+    chordProgression: ChordChange[];
+    barChordProgression: BarChord[];
+    currentBar: number;
+    barDuration: number;
+    votedPattern: BarChord[];
+    patternLength: number;
+    detectedPatternName: string;
+    detectedPatternScore: number;
+    allPatternScores: PatternScore[];
+    accumulatedSeconds: number;
+    usedFrames: number;
+    /**
+     * True when the key or BPM was re-estimated since the previous stats
+     * snapshot. One change sets it on exactly one snapshot however the caller
+     * chunks its input, and a call that produced no frame does not repeat it.
+     */
+    updated: boolean;
+}
+/**
+ * Statistics and current state of the analyzer
+ */
+export interface AnalyzerStats {
+    totalFrames: number;
+    totalSamples: number;
+    durationSeconds: number;
+    pendingFrames: number;
+    droppedOutputFrames: number;
+    droppedChordProgressionEntries: number;
+    droppedBarProgressionEntries: number;
+    /**
+     * Blocks in which a non-finite input sample was replaced before it could
+     * reach the analyzer's recursive state.
+     *
+     * Unlike the drop counts above, nothing is missing from the output: every
+     * estimate is produced as usual and simply stops describing the input, so
+     * this is the only report that the stream was degraded. The unit is one
+     * {@link StreamAnalyzer.process} call, never a sample, so a block carrying a
+     * thousand NaNs adds one. Cleared by {@link StreamAnalyzer.reset} alongside
+     * the drop counts, because that call rebuilds the timeline and the count
+     * describes a segment rather than the analyzer.
+     */
+    nonFiniteDiscardBlocks: number;
+    estimate: ProgressiveEstimate;
+}
+/**
+ * Frame buffer with analysis results
+ */
+export interface FrameBuffer {
+    nFrames: number;
+    /** Number of mel bands; flat `mel` is `[nFrames * nMels]` row-major. */
+    nMels: number;
+    /** Chroma stride: 12 when enabled, otherwise 0. */
+    nChroma: number;
+    /** MEL=1, CHROMA=2, ONSET=4, SPECTRAL=8. */
+    featureFlags: number;
+    timestamps: Float32Array;
+    /**
+     * Mel spectrogram in LINEAR power (not dB) — the raw per-frame mel energies.
+     * The quantized read paths (`readFramesU8` / `readFramesI16`) convert to dB
+     * before packing, so their `mel` is dB-scaled; this float buffer is not.
+     */
+    mel: Float32Array;
+    chroma: Float32Array;
+    onsetStrength: Float32Array;
+    rmsEnergy: Float32Array;
+    spectralCentroid: Float32Array;
+    spectralFlatness: Float32Array;
+    chordRoot: Int32Array;
+    chordQuality: Int32Array;
+    chordConfidence: Float32Array;
+}
+/**
+ * Quantization ranges for the uint8/int16 bandwidth-reduction read paths
+ * (`StreamAnalyzer.readFramesU8` / `readFramesI16`). Omitted fields fall back to
+ * the library defaults shown below; widen any range whose source values exceed
+ * the defaults, otherwise a louder/quieter stream saturates to the endpoints.
+ */
+export interface StreamQuantizeConfig {
+    /** dB floor for mel quantization (default -80). */
+    melDbMin?: number;
+    /** dB ceiling for mel quantization (default 0). */
+    melDbMax?: number;
+    /** Max expected onset strength (default 50). */
+    onsetMax?: number;
+    /** Max expected RMS energy (default 1). */
+    rmsMax?: number;
+    /** Max expected spectral centroid in Hz (default 11025). */
+    centroidMax?: number;
+}
+export interface StreamFramesU8 {
+    nFrames: number;
+    nMels: number;
+    nChroma: number;
+    /** MEL=1, CHROMA=2, ONSET=4, SPECTRAL=8. */
+    featureFlags: number;
+    timestamps: Float32Array;
+    /** Row-major `[nFrames * nMels]` mel in dB, quantized over `[melDbMin, melDbMax]`. */
+    mel: Uint8Array;
+    chroma: Uint8Array;
+    onsetStrength: Uint8Array;
+    rmsEnergy: Uint8Array;
+    spectralCentroid: Uint8Array;
+    spectralFlatness: Uint8Array;
+}
+export interface StreamFramesI16 {
+    nFrames: number;
+    nMels: number;
+    nChroma: number;
+    /** MEL=1, CHROMA=2, ONSET=4, SPECTRAL=8. */
+    featureFlags: number;
+    timestamps: Float32Array;
+    /** Row-major `[nFrames * nMels]` mel in dB, quantized over `[melDbMin, melDbMax]`. */
+    mel: Int16Array;
+    chroma: Int16Array;
+    onsetStrength: Int16Array;
+    rmsEnergy: Int16Array;
+    spectralCentroid: Int16Array;
+    spectralFlatness: Int16Array;
+}
+/**
+ * Configuration for StreamAnalyzer
+ *
+ * Omitted values are read from the native StreamConfig defaults via
+ * streamAnalyzerConfigDefault(), keeping the WASM wrapper in sync with core.
+ */
+export interface StreamConfig {
+    /** Sample rate in Hz. Optional for parity with the Node/Python bindings. */
+    sampleRate?: number;
+    nFft?: number;
+    hopLength?: number;
+    nMels?: number;
+    fmin?: number;
+    fmax?: number;
+    /** A4 tuning reference in Hz. Defaults to 440; must be within 220..880, the
+     *  same range `setTuningRefHz` accepts live. */
+    tuningRefHz?: number;
+    /** Unsupported: no read path surfaces per-frame magnitude spectra. */
+    computeMagnitude?: boolean;
+    computeMel?: boolean;
+    computeChroma?: boolean;
+    computeOnset?: boolean;
+    computeSpectral?: boolean;
+    emitEveryNFrames?: number;
+    magnitudeDownsample?: number;
+    /** Maximum unread frames; overflow drops the newly produced frame. */
+    maxPendingFrames?: number;
+    /** Maximum retained chord and bar progression entries; overflow drops oldest. */
+    maxProgressionEntries?: number;
+    keyUpdateIntervalSec?: number;
+    bpmUpdateIntervalSec?: number;
+    window?: number;
+    /** @deprecated Must be 0 (Float32). Use readFramesU8/readFramesI16 explicitly. */
+    outputFormat?: number;
+}
+export type StreamConfigDefaults = Required<StreamConfig>;
+//# sourceMappingURL=stream_types.d.ts.map

package/dist/stream_types.d.ts.map

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

package/dist/streaming_mixing.d.ts

@@ -0,0 +1,6 @@
+export type { MixerMeterSnapshot, MixerRealtimeBuffer, StripMeteringOptions } from './mixer';
+export { Mixer } from './mixer';
+export type { RealtimeVoiceChangerInterleavedBuffer, RealtimeVoiceChangerMonoBuffer, RealtimeVoiceChangerPlanarBuffer, } from './realtime_voice_changer';
+export { RealtimeVoiceChanger, realtimeVoiceChangerPresetJson, realtimeVoiceChangerPresetNames, validateRealtimeVoiceChangerPresetJson, } from './realtime_voice_changer';
+export { StreamingEqualizer, StreamingMasteringChain, StreamingRetune, } from './streaming_processors';
+//# sourceMappingURL=streaming_mixing.d.ts.map

package/dist/streaming_mixing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming_mixing.d.ts","sourceRoot":"","sources":["../src/streaming_mixing.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EACV,qCAAqC,EACrC,8BAA8B,EAC9B,gCAAgC,GACjC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,8BAA8B,EAC9B,+BAA+B,EAC/B,sCAAsC,GACvC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,GAChB,MAAM,wBAAwB,CAAC"}

package/dist/streaming_processors.d.ts

@@ -0,0 +1,335 @@
+import type { EqBand, EqMatchOptions, EqSpectrumSnapshot, EqStereoPlacement, StreamingEqualizerConfig, StreamingMasteringChainConfig, StreamingRetuneConfig } from './public_types';
+type EqPhaseMode = 'zero' | 'zero-latency' | 'zero_latency' | 'natural' | 'natural-phase' | 'natural_phase' | 'linear' | 'linear-phase' | 'linear_phase' | number;
+/**
+ * Block-by-block streaming variant of {@link masteringChain}.
+ *
+ * Maintains processor state across {@link processMono}/{@link processStereo}
+ * calls. Only ProcessorBase-backed stages are supported: `eq.tilt`,
+ * `dynamics.deesser`, `dynamics.transientShaper`, `dynamics.compressor`,
+ * `dynamics.multibandComp`, `saturation.tape`, `saturation.exciter`,
+ * `spectral.airBand`, `stereo.imager` (stereo only), `stereo.monoMaker`
+ * (stereo only), `maximizer.truePeakLimiter`. Configurations that enable ANY of
+ * the five whole-signal repair stages (`repair.declick`, `repair.declip`,
+ * `repair.decrackle`, `repair.dehum`, `repair.dereverb`) throw at construction.
+ *
+ * `repair.denoise` runs here, but only with a noise estimator that is recursive
+ * in time. Its default ranks every frame of the whole signal by energy, which a
+ * stream never reaches the end of, so it is refused by name rather than
+ * substituted; set `repair.denoise.noiseEstimator` to `1` (MCRA), `2` (IMCRA)
+ * or `3` (speech-presence probability). The two minimum-tracking estimators
+ * (`1` and `2`) seed their noise floor from the first frame they see and hold it
+ * for the half second their minimum window spans, so a stream opened in the
+ * middle of the programme is over-suppressed until it turns over; `3` tracks no
+ * minimum and is unaffected. Prefer `3` past that opening too: `1` and `2`
+ * over-report the floor for as long as the programme stays intermittent, and on
+ * a gated tone they leave the result below the untreated input.
+ *
+ * An enabled `loudness` stage also throws unless
+ * {@link StreamingMasteringChainConfig.loudnessStaticGainDb} supplies a
+ * precomputed normalization gain.
+ *
+ * Call {@link delete} (or use a `try/finally`) to release the underlying WASM
+ * object — the embind handle is not garbage-collected automatically.
+ *
+ * Reachable from the AudioWorklet realm through the `sonare/worklet` entry, but
+ * the realtime contract is the caller's to keep:
+ *
+ * - {@link prepare} builds the processors and allocates. Call it once from a
+ *   message handler, never from `AudioWorkletProcessor.process()`.
+ * - {@link processMono}/{@link processStereo} return fresh arrays. On the render
+ *   thread, reuse the returned reference for the block rather than retaining it.
+ * - An enabled `loudness` stage needs `loudnessStaticGainDb` measured offline,
+ *   because whole-signal integrated LUFS cannot be measured block by block. Pass
+ *   `loudnessStaticGainPeakDb` too and the static gain is clamped exactly as the
+ *   offline chain clamps it, so the live preview matches the render.
+ * - {@link flush} output starts {@link latencySamples} samples early; discard
+ *   that many leading samples when time alignment matters.
+ *
+ * The chain is a host-side stage, not an engine insert: it does not participate
+ * in the engine's PDC or bypass, so latency compensation against other engine
+ * outputs is also the caller's.
+ *
+ * @example
+ * ```typescript
+ * const chain = new StreamingMasteringChain({ eq: { tiltDb: 1.0 } });
+ * try {
+ *   chain.prepare(44100, 512, 1);
+ *   const out = chain.processMono(blockSamples);
+ * } finally {
+ *   chain.delete();
+ * }
+ * ```
+ */
+export declare class StreamingMasteringChain {
+    private chain;
+    private released;
+    constructor(config: StreamingMasteringChainConfig);
+    /**
+     * Initialize processors for the given sample rate and block layout.
+     *
+     * @param sampleRate - Sample rate in Hz
+     * @param maxBlockSize - Maximum block size per process call
+     * @param numChannels - 1 (mono) or 2 (stereo)
+     */
+    prepare(sampleRate: number, maxBlockSize: number, numChannels: number): void;
+    /**
+     * Process one mono block, returning the processed samples (same length).
+     */
+    processMono(samples: Float32Array): Float32Array;
+    /**
+     * Process one stereo block, returning the processed channels.
+     */
+    processStereo(left: Float32Array, right: Float32Array): {
+        left: Float32Array;
+        right: Float32Array;
+    };
+    /**
+     * Emit delayed audio and finite processor tails after the final mono block.
+     * Call until this returns an empty array. The initial `latencySamples()`
+     * samples of the concatenated stream are delayed and should be discarded for
+     * time-aligned output.
+     */
+    flushMono(): Float32Array;
+    /** Stereo counterpart of {@link flushMono}. */
+    flushStereo(): {
+        left: Float32Array;
+        right: Float32Array;
+    };
+    /** Reset all processor state without rebuilding. */
+    reset(): void;
+    /** Total reported latency in samples across all active processors. */
+    latencySamples(): number;
+    /** Ordered stage names that will run (e.g. `"eq.tilt"`). */
+    stageNames(): string[];
+    /**
+     * Samples a stage replaced with a finite in-domain one, keeping the output
+     * finite and in range.
+     *
+     * A non-finite sample supplied by the caller is rejected before any stage
+     * runs, so a replacement is always of a value a stage itself produced.
+     *
+     * Only the true-peak limiters replace anything, so with the maximizer's
+     * limiter and the loudness stage both disabled a zero here means no stage was
+     * able to replace anything rather than that nothing needed replacing.
+     *
+     * Cumulative over every block since {@link prepare}, and aggregated over the
+     * stages and channels, so it identifies neither which block nor which stage.
+     * Read it per block and compare against the previous reading to localize one.
+     *
+     * {@link prepare} rebuilds the stages and so clears it; {@link reset} does
+     * not, because it drops processor state without rebuilding.
+     *
+     * @example
+     * ```typescript
+     * chain.processMono(block);
+     * if (chain.nonFiniteSubstitutionCount() > previous) {
+     *   // the block just produced is not derived from `block` everywhere
+     * }
+     * ```
+     */
+    nonFiniteSubstitutionCount(): number;
+    /**
+     * Processing calls in which a stage discarded its own recursive state
+     * because a non-finite value had reached it.
+     *
+     * The companion to {@link nonFiniteSubstitutionCount}, and not the same
+     * measurement -- a caller who assumes they are will read one and think
+     * they have the other. That one counts SAMPLES a stage replaced and so
+     * sums across stages; a discard is a whole stage returning to its
+     * post-reset value and is counted once per call however many stages did
+     * it. A stage may run more than once per call, which is why this is a
+     * delta over the call and never a sum.
+     *
+     * Non-finite input is rejected before any stage runs, so what a stage
+     * discards is always state it produced itself -- a finite sample large
+     * enough to overflow inside a filter, most often. Unlike the substitution
+     * count every stage can contribute, so a zero here means no stage
+     * discarded rather than that none could.
+     *
+     * Both {@link processMono}/{@link processStereo} and
+     * {@link flushMono}/{@link flushStereo} count, since a flush drives the
+     * same stages. {@link prepare} rebuilds the stages and so clears it (as it
+     * does {@link nonFiniteSubstitutionCount}, so the two counters on one
+     * handle share an epoch); {@link reset} does not, because it drops
+     * processor state without rebuilding.
+     */
+    nonFiniteDiscardCount(): number;
+    /** Release the underlying WASM object. Idempotent, as the Node facade is. */
+    delete(): void;
+    /** Alias for {@link delete}, provided for cross-binding (Node) compatibility. */
+    destroy(): void;
+}
+/**
+ * Block-by-block streaming equalizer wrapping the unified C++
+ * `EqualizerProcessor` (up to 24 bands, RBJ/Vicanek biquads, dynamic EQ,
+ * linear-phase FIR, mid/side processing, and auto-gain).
+ *
+ * State is maintained across {@link processMono}/{@link processStereo} calls.
+ * Call {@link delete} (or use `try/finally`) to release the underlying WASM
+ * object — the embind handle is not garbage-collected automatically.
+ *
+ * @example
+ * ```typescript
+ * const eq = new StreamingEqualizer({ sampleRate: 48000, maxBlockSize: 512 });
+ * try {
+ *   eq.setBand(0, { type: 'HighShelf', frequencyHz: 8000, gainDb: 6, enabled: true });
+ *   const out = eq.processStereo(left, right);
+ *   const snapshot = eq.spectrum();
+ * } finally {
+ *   eq.delete();
+ * }
+ * ```
+ */
+export declare class StreamingEqualizer {
+    private eq;
+    private released;
+    constructor(config?: StreamingEqualizerConfig);
+    /**
+     * Configure the band at `index` (0..23). Omitted fields use C++ defaults.
+     */
+    setBand(index: number, band: EqBand): void;
+    /** Disable and reset every band. */
+    clear(): void;
+    /**
+     * Set the global phase mode: `'zero'` | `'natural'` | `'linear'` or 1/2/3.
+     */
+    setPhaseMode(mode: EqPhaseMode): void;
+    /** Enable or disable output auto-gain compensation. */
+    setAutoGain(enabled: boolean): void;
+    /** Set all-band EQ gain scale as a 0.0..2.0 multiplier. */
+    setGainScale(scale: number): void;
+    /** Set post-EQ output gain in dB. */
+    setOutputGainDb(gainDb: number): void;
+    /** Set post-EQ stereo balance in -1.0..1.0; mono input ignores pan. */
+    setOutputPan(pan: number): void;
+    /**
+     * Provide a mono external sidechain key for dynamic bands that opt into
+     * `external_sidechain`. The samples are copied into an owned buffer.
+     */
+    setSidechainMono(samples: Float32Array): void;
+    /**
+     * Provide a stereo external sidechain key. Both channels must match length.
+     */
+    setSidechainStereo(left: Float32Array, right: Float32Array): void;
+    /** Release any borrowed external sidechain buffers. */
+    clearSidechain(): void;
+    /** Auto-gain applied on the most recent block, in dB. */
+    lastAutoGainDb(): number;
+    /** Reported processing latency in samples (non-zero for linear-phase bands). */
+    latencySamples(): number;
+    /**
+     * Number of blocks in which the EQ discarded recursive state because a
+     * non-finite value had reached it.
+     *
+     * Advisory telemetry, and the only thing that separates a degraded EQ from
+     * a clean one. A discard returns the affected filter cells to their
+     * post-reset value, so the EQ recovers in silence and the output stays
+     * finite and in range while carrying samples unrelated to the input;
+     * nothing else reports that this happened.
+     *
+     * The count covers every IIR plane the band layout uses -- stereo, per
+     * channel, and mid/side -- together with the automatic output gain and the
+     * detector state the dynamic bands drive. Linear-phase bands are not
+     * included and have nothing to include: an FIR keeps no recursive state,
+     * so a non-finite sample leaves its history on its own.
+     *
+     * Unlike a mixer strip's meters, nothing here lags: this EQ has no meter of
+     * its own, so a discard is always attributed to the block that carried it.
+     *
+     * Cumulative since this handle was created and never cleared, so two
+     * readings bracket a span of audio. The unit is one processed block, never
+     * a channel or a plane.
+     */
+    nonFiniteDiscardCount(): number;
+    /**
+     * Process one mono block, returning the equalized samples (same length).
+     */
+    processMono(samples: Float32Array): Float32Array;
+    /**
+     * Process one stereo block, returning the equalized channels.
+     */
+    processStereo(left: Float32Array, right: Float32Array): {
+        left: Float32Array;
+        right: Float32Array;
+    };
+    /**
+     * The composite magnitude of the bands, in dB, at each requested frequency —
+     * the curve to draw over {@link spectrum}.
+     *
+     * Built from the same coefficient design, tilt expansion and cut-slope
+     * cascade the audio path uses, so it states what the equalizer does rather
+     * than what its settings look like, and it carries the output gain, the gain
+     * scale and whatever each dynamic band is applying at the moment of the call.
+     * Disabled, bypassed and — when anything is soloed — unsoloed bands drop out,
+     * and a soloed band is drawn as the band pass it is heard as.
+     *
+     * `placement` selects which signal path the curve is for. A band placed on
+     * `'Stereo'` is on every path; one placed elsewhere appears only on its own,
+     * a mid band having no per-channel magnitude to fold into a left or right
+     * curve. Frequencies are clamped to [0 Hz, Nyquist].
+     *
+     * @example
+     * ```ts
+     * const freqs = new Float32Array([100, 1000, 10000]);
+     * const db = eq.magnitudeResponse(freqs);
+     * ```
+     */
+    magnitudeResponse(frequenciesHz: Float32Array, placement?: EqStereoPlacement): Float32Array;
+    /**
+     * Read the latest pre/post spectrum snapshot for metering. `seq` increments
+     * each time a new snapshot is published.
+     */
+    spectrum(): EqSpectrumSnapshot;
+    /**
+     * Configure bands so the source spectrum matches the reference spectrum.
+     *
+     * @param source - Source audio (mono samples)
+     * @param reference - Reference audio (mono samples)
+     * @param options - `sampleRate` (default 48000) and `maxBands` (default 8)
+     */
+    match(source: Float32Array, reference: Float32Array, options?: EqMatchOptions): void;
+    /** Release the underlying WASM object. Idempotent, as the Node facade is. */
+    delete(): void;
+    /** Alias for {@link delete}, provided for cross-binding (Node) compatibility. */
+    destroy(): void;
+}
+/**
+ * Block-by-block mono voice retune / pitch shifter.
+ *
+ * State is maintained across {@link processMono} calls. Call {@link prepare}
+ * before processing, and call {@link delete} (or use `try/finally`) to release
+ * the underlying WASM object.
+ */
+export declare class StreamingRetune {
+    private retune;
+    private released;
+    constructor(config?: StreamingRetuneConfig);
+    /**
+     * Allocate and initialize native state for the given sample rate and maximum
+     * process block size.
+     */
+    prepare(sampleRate: number, maxBlockSize: number): void;
+    /** Reset delay, grain, and overlap-add state without changing config. */
+    reset(): void;
+    /**
+     * Update the live controls; omitted keys keep their current value. Changing
+     * `grainSize` takes effect after the next {@link prepare} call, and an
+     * omitted `grainSize` keeps whatever was last requested — including the `0`
+     * sentinel, so a re-{@link prepare} at another sample rate re-derives it.
+     */
+    setConfig(config: StreamingRetuneConfig): void;
+    /** The currently applied controls, with `grainSize` as the effective one. */
+    config(): Required<StreamingRetuneConfig>;
+    /** Resolved grain size in samples after {@link prepare}. */
+    grainSize(): number;
+    /** Fixed overlap-add latency in samples (one grain); 0 before prepare. */
+    latencySamples(): number;
+    /** Process one mono block, returning the shifted samples (same length). */
+    processMono(samples: Float32Array): Float32Array;
+    /** Release the underlying WASM object. Idempotent, as the Node facade is. */
+    delete(): void;
+    /** Alias for {@link delete}, provided for cross-binding (Node) compatibility. */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=streaming_processors.d.ts.map

package/dist/streaming_processors.d.ts.map

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

package/dist/transcribe.d.ts

@@ -0,0 +1,77 @@
+import type { TranscribeOptions, TranscribeResult } from './project_types';
+/**
+ * Canonical request form for {@link transcribe}.
+ *
+ * Deliberately does NOT extend `ValidateOptions`. That option's contract is
+ * that skipping the JS-side scan is safe because the native layer re-validates
+ * with an equivalent result -- and here it would not be equivalent: the
+ * transcription C ABI (`sonare_transcribe`) does re-validate the buffer,
+ * including a non-finite scan, but a rejection there surfaces as a
+ * `SonareError` `InvalidParameter`, not the `RangeError` this function
+ * documents and every other empty/non-finite/rate check on this surface
+ * raises. A `{ validate: false }` here would silently change the thrown error
+ * class instead of skipping a redundant check. The scan is also nearly free
+ * against this pipeline, which already reads every sample several times.
+ */
+export interface TranscribeRequest extends TranscribeOptions {
+    /** Mono source audio. Must be non-empty and all-finite. */
+    samples: Float32Array;
+    /** Sample rate of `samples` in Hz, `[8000, 384000]`. */
+    sampleRate: number;
+    /**
+     * Tempo the PPQ grid is built on, in BPM. **Omit to have it detected** from
+     * `samples`, which costs an onset/tempo pass; a detector that finds nothing
+     * usable falls back to 120 rather than failing the transcription.
+     *
+     * Supplying a tempo is not a claim about the audio — it is the coordinate
+     * system the events come back in. Twice the tempo is twice as many beats per
+     * second, so the same audio lands on twice the ppq.
+     */
+    tempoBpm?: number;
+}
+/**
+ * Transcribes mono audio into MIDI events on a constant-tempo grid.
+ *
+ * This joins parts that already exist rather than adding a detector: the note
+ * spans and their measured pitch and level come from the monophonic (pYIN) or
+ * polyphonic (multi-F0) chain, and the output is the flat
+ * {@link ProjectMidiEvent} shape {@link Project.setMidiEvents} takes, so
+ * nothing is left to convert.
+ *
+ * Finding no notes is not an error. Silence, and material the chain cannot
+ * resolve, come back with an empty `events` array and `noteCount` 0, and
+ * `tempoBpm` still reports the tempo that was used or detected.
+ *
+ * Three things are deliberately **not** done here, because the library already
+ * does each of them somewhere else and a second implementation would drift:
+ *
+ * - **Quantizing to a grid** — {@link Project.bakeMidiFx}'s `quantizePpq` /
+ *   `quantizeStrength`.
+ * - **Detecting and installing a tempo map** — {@link Project.autoTempo}. The
+ *   `tempoBpm` fallback here builds one constant-tempo grid for this call and
+ *   installs nothing; use {@link Project.transcribeToClip} to transcribe onto a
+ *   project's real map.
+ * - **Annotating key and chords** — {@link Project.annotateKeys} /
+ *   {@link Project.annotateChords}.
+ *
+ * The tuning reference is likewise not measured — see
+ * {@link TranscribeOptions.referenceHz}.
+ *
+ * @throws {RangeError} on empty `samples`, a non-finite sample, or a
+ *   `sampleRate` outside `[8000, 384000]`
+ * @throws {SonareError} `InvalidParameter` on an option outside its domain —
+ *   a non-negative `velocityFloorDb`, a `fixedVelocity` outside `[1, 127]`, a
+ *   `group` or `channel` outside `[0, 15]`, an `fmax` at or below `fmin`, or a
+ *   written `0` on any field but `group` and `channel` — or `NotSupported`
+ *   when the library was built without the pitch editor
+ *
+ * @example
+ * ```typescript
+ * const { events, noteCount, tempoBpm } = transcribe({ samples, sampleRate, tempoBpm: 120 });
+ * const project = new Project();
+ * const { clipId } = project.addMidiClip(0, 16); // 4 bars at 4/4, in quarter notes (PPQ)
+ * project.setMidiEvents(clipId, events);
+ * ```
+ */
+export declare function transcribe(request: TranscribeRequest): TranscribeResult;
+//# sourceMappingURL=transcribe.d.ts.map

package/dist/transcribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe.d.ts","sourceRoot":"","sources":["../src/transcribe.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAG3E;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,2DAA2D;IAC3D,OAAO,EAAE,YAAY,CAAC;IACtB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CASvE"}