@libraz/libsonare 1.7.1 → 1.8.0

package/dist/repair_noise.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Broadband and tonal noise repair: denoise and dehum, with their detectors.
+ */
+import type { HumDetection, MasteringRepairDehumStereoResult, MasteringRepairDenoiseClassicalLinkedResult, MasteringRepairDenoiseClassicalStereoResult, NoiseDetection } from './public_types_repair';
+/** Algorithms accepted by `masteringRepairDenoiseClassical`. */
+export type DenoiseClassicalMode = 'logMmse' | 'mmseStsa' | 'spectralSubtraction';
+/** Noise PSD estimators accepted by `masteringRepairDenoiseClassical`. */
+export type DenoiseClassicalNoiseEstimator = 'quantile' | 'mcra' | 'imcra' | 'spp';
+/** Options for `masteringRepairDenoiseClassical`. */
+export interface DenoiseClassicalOptions {
+    mode?: DenoiseClassicalMode;
+    noiseEstimator?: DenoiseClassicalNoiseEstimator;
+    nFft?: number;
+    hopLength?: number;
+    ddAlpha?: number;
+    reductionDb?: number;
+    overSubtraction?: number;
+    spectralFloor?: number;
+    noiseEstimationQuantile?: number;
+    speechPresenceGain?: boolean;
+    gainSmoothing?: boolean;
+}
+export interface MasteringRepairDenoiseClassicalRequest extends DenoiseClassicalOptions {
+    samples: Float32Array;
+    sampleRate: number;
+}
+/** Request form of `masteringRepairDenoiseClassicalStereo`. */
+export interface MasteringRepairDenoiseClassicalStereoRequest extends DenoiseClassicalOptions {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+}
+/** Request form of `masteringRepairDenoiseClassicalLinked`. */
+export interface MasteringRepairDenoiseClassicalLinkedRequest extends DenoiseClassicalOptions {
+    /** At least one channel; all the same length. */
+    channels: Float32Array[];
+    sampleRate?: number;
+}
+/** Offline STFT-domain classical denoiser (LogMMSE / MMSE-STSA / SpectralSubtraction). */
+export declare function masteringRepairDenoiseClassical(request: MasteringRepairDenoiseClassicalRequest): Float32Array;
+export declare function masteringRepairDenoiseClassical(samples: Float32Array, sampleRate: number, options?: DenoiseClassicalOptions): Float32Array;
+/**
+ * Offline STFT-domain classical denoiser for a stereo pair, driven by one channel-linked
+ * gain mask.
+ *
+ * The mask is built from the channel-summed power and applied unchanged to both channels, so
+ * the pass cannot move an interchannel level or phase difference. That is also why the result
+ * carries a single `report` rather than one per channel: a pair would be two copies of one
+ * measurement and would read as though the two could differ.
+ *
+ * `report.detected` is therefore a *pair-level* measurement, and the only absolute one in the
+ * result. Its levels are dBFS on the channel-summed power, so two identical channels read
+ * `10*log10(2)` — about 3.01 dB — above the same material through
+ * {@link masteringRepairDenoiseClassical}. A stereo floor is comparable only against another
+ * stereo floor, never against a mono one.
+ *
+ * Needs at least `nFft` samples and REJECTS a shorter input, which is the opposite of
+ * {@link masteringRepairDereverbClassicalStereo} — that one pads.
+ *
+ * Which options are live depends on `mode`: `overSubtraction` and `spectralFloor` are read
+ * only by `spectralSubtraction`, and `speechPresenceGain` and `gainSmoothing` only by the
+ * other two, so at the default `logMmse` the first pair does nothing.
+ *
+ * @example
+ * ```ts
+ * const { left, right, report } = masteringRepairDenoiseClassicalStereo({
+ *   left: leftSamples,
+ *   right: rightSamples,
+ *   sampleRate: 48000,
+ *   reductionDb: 18,
+ * });
+ * console.log(report.detected.floorDbfs, report.meanReductionDb);
+ * ```
+ */
+export declare function masteringRepairDenoiseClassicalStereo(request: MasteringRepairDenoiseClassicalStereoRequest): MasteringRepairDenoiseClassicalStereoResult;
+export declare function masteringRepairDenoiseClassicalStereo(left: Float32Array, right: Float32Array, sampleRate: number, config?: DenoiseClassicalOptions): MasteringRepairDenoiseClassicalStereoResult;
+/**
+ * Offline STFT-domain classical denoiser for any number of channels, driven by one
+ * channel-linked gain mask.
+ *
+ * The N-channel form of {@link masteringRepairDenoiseClassicalStereo}, carrying the same
+ * guarantee over the whole set: the mask is built from the channel-summed power and applied
+ * unchanged to every channel, so no interchannel level or phase difference moves however many
+ * channels there are. One `report` for the set, and one output per input channel in input order.
+ *
+ * A single channel reproduces {@link masteringRepairDenoiseClassical} bit for bit, and two
+ * reproduce {@link masteringRepairDenoiseClassicalStereo} plane for plane — `channels[0]` is the
+ * left plane and `channels[1]` the right.
+ *
+ * `report.detected` carries absolute levels and they are the SET's: the floor is referred to the
+ * summed mean square of every channel, so N identical channels read `10*log10(N)` above
+ * one of them — about 3.01 dB at two channels and 4.77 dB at three. Compare a floor only against
+ * one measured over the same number of channels. Every other field of the report is a fraction
+ * and does not move with the channel count.
+ *
+ * Needs at least `nFft` samples and REJECTS a shorter input, which is the opposite of
+ * {@link masteringRepairDereverbClassicalLinked} — that one pads.
+ *
+ * @example
+ * ```ts
+ * const { channels, report } = masteringRepairDenoiseClassicalLinked({
+ *   channels: [frontLeft, frontRight, centre],
+ *   sampleRate: 48000,
+ *   reductionDb: 18,
+ * });
+ * console.log(channels.length, report.detected.floorDbfs);
+ * ```
+ */
+export declare function masteringRepairDenoiseClassicalLinked(request: MasteringRepairDenoiseClassicalLinkedRequest): MasteringRepairDenoiseClassicalLinkedResult;
+export declare function masteringRepairDenoiseClassicalLinked(channels: Float32Array[], sampleRate: number, config?: DenoiseClassicalOptions): MasteringRepairDenoiseClassicalLinkedResult;
+/**
+ * How `masteringRepairDehum` removes the harmonic series.
+ *
+ * `subtract` tracks each harmonic's amplitude and phase and subtracts the tone they describe,
+ * so material sitting at the same frequency but uncorrelated with the tracked series survives.
+ * `notch` cascades one RBJ notch per harmonic and removes everything inside each notch's
+ * bandwidth, hum or programme alike.
+ */
+export type DehumMode = 'subtract' | 'notch';
+/** Options for `masteringRepairDehum`. */
+export interface DehumOptions {
+    fundamentalHz?: number;
+    harmonics?: number;
+    q?: number;
+    adaptive?: boolean;
+    searchRangeHz?: number;
+    adaptation?: number;
+    frameSize?: number;
+    pllBandwidth?: number;
+    /** Defaults to `'subtract'`. */
+    mode?: DehumMode;
+}
+export interface MasteringRepairDehumRequest extends DehumOptions {
+    samples: Float32Array;
+    sampleRate: number;
+}
+/** Request form of `masteringRepairDehumStereo`. */
+export interface MasteringRepairDehumStereoRequest extends DehumOptions {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+}
+/** Offline mains-hum remover. */
+export declare function masteringRepairDehum(request: MasteringRepairDehumRequest): Float32Array;
+export declare function masteringRepairDehum(samples: Float32Array, sampleRate: number, options?: DehumOptions): Float32Array;
+/**
+ * Offline mains-hum remover for a stereo pair.
+ *
+ * With `adaptive` set, mains hum is one physical source, so the tracker reads the channel
+ * mean and both cascades follow the one frequency it finds: `appliedFundamentalHz` and
+ * `fundamentalDriftHz` come back identical in both reports by construction, while each
+ * report's `detected` still measures that channel's own input and each channel keeps its
+ * own filter state, so neither channel's transient rings through the other. With `adaptive`
+ * clear, which is the default, nothing is shared and the two channels are filtered
+ * independently at the configured frequency.
+ */
+export declare function masteringRepairDehumStereo(request: MasteringRepairDehumStereoRequest): MasteringRepairDehumStereoResult;
+export declare function masteringRepairDehumStereo(left: Float32Array, right: Float32Array, sampleRate: number, config?: DehumOptions): MasteringRepairDehumStereoResult;
+/** Request form of `masteringRepairDetectNoiseFloor`. */
+export interface MasteringRepairDetectNoiseFloorRequest extends DenoiseClassicalOptions {
+    samples: Float32Array;
+    sampleRate: number;
+}
+/** Request form of `masteringRepairNoiseBandBins`. */
+export interface MasteringRepairNoiseBandBinsRequest {
+    nFft?: number;
+    sampleRate?: number;
+}
+/** Request form of `masteringRepairDetectHum`. */
+export interface MasteringRepairDetectHumRequest extends DehumOptions {
+    samples: Float32Array;
+    sampleRate: number;
+}
+/**
+ * Measures the noise floor without denoising.
+ *
+ * Runs the STFT and the configured noise estimator — the two stages
+ * {@link masteringRepairDenoiseClassical} runs — and stops before the gain mask, which is why
+ * no attenuation figure appears here.
+ *
+ * Needs at least `nFft` samples and THROWS for a shorter buffer, the opposite of
+ * {@link masteringRepairDetectReverb}, which pads one.
+ *
+ * `floorDbfs` is an absolute level, so it is comparable only against another figure measured
+ * over the same channel count.
+ */
+export declare function masteringRepairDetectNoiseFloor(request: MasteringRepairDetectNoiseFloorRequest): NoiseDetection;
+export declare function masteringRepairDetectNoiseFloor(samples: Float32Array, sampleRate: number, options?: DenoiseClassicalOptions): NoiseDetection;
+/**
+ * Bin boundaries of the grid {@link masteringRepairDetectNoiseFloor} reports `bandFloorDbfs` on.
+ *
+ * Band `k` covers the one-sided STFT bins `[bins[k], bins[k + 1])`, and bin `b` sits at
+ * `b * sampleRate / nFft` Hz.
+ *
+ * The geometric band edges are rounded to bins, so a band narrower than the bin spacing comes
+ * out EMPTY — `bins[k] === bins[k + 1]` — and its `bandFloorDbfs[k]` reads as the floor
+ * sentinel because no bin landed in it, NOT because that region was quiet. Telling those two
+ * apart is what this grid is for, and the rounding cannot be recovered from the band count
+ * alone.
+ *
+ * Nothing but the analysis geometry decides the grid, so no denoise config is taken: one call
+ * describes every floor measured at that `nFft` and `sampleRate`, whatever mode or estimator
+ * produced it.
+ *
+ * @param nFft - STFT size the bins belong to; a positive power of two, the same rule
+ *   {@link masteringRepairDetectNoiseFloor} applies to its config, so every grid returned here
+ *   is one that entry can report on. Defaults to 1024.
+ * @param sampleRate - Sample rate the bins belong to, in Hz; positive. Defaults to 22050.
+ * @returns 33 bin indices, low to high — one more than the 32 bands: the first bin of every
+ *   band plus the one-past-the-end bin of the last, which is `nFft / 2 + 1`. Non-decreasing.
+ * @throws If `nFft` is not a positive power of two, or `sampleRate` is not positive.
+ *
+ * @example
+ * ```ts
+ * const bins = masteringRepairNoiseBandBins({ nFft: 1024, sampleRate: 48000 });
+ * const floor = masteringRepairDetectNoiseFloor({ samples, sampleRate: 48000, nFft: 1024 });
+ * floor.bandFloorDbfs.forEach((level, k) => {
+ *   if (bins[k] === bins[k + 1]) return; // empty band: `level` is the sentinel, not a measurement
+ *   console.log((bins[k] * 48000) / 1024, level);
+ * });
+ * ```
+ */
+export declare function masteringRepairNoiseBandBins(request?: MasteringRepairNoiseBandBinsRequest): Int32Array;
+export declare function masteringRepairNoiseBandBins(nFft?: number, sampleRate?: number): Int32Array;
+/**
+ * Measures hum without filtering.
+ *
+ * Always runs the estimation path, whatever `adaptive` says: the fixed path notches the
+ * configured frequency without ever looking for hum, so a detector following the flag would
+ * hand back its own input. `fundamentalProminence` is the winning candidate's projected energy
+ * over the median candidate, so `1.0` means no peak was found at all — it is not a lock flag.
+ *
+ * `harmonicDbfs` is measured at every `k*f0` the sample rate carries, not only the ones a
+ * cascade would notch; a `k*f0` at or past Nyquist reads the dB floor because nothing is there
+ * to measure.
+ */
+export declare function masteringRepairDetectHum(request: MasteringRepairDetectHumRequest): HumDetection;
+export declare function masteringRepairDetectHum(samples: Float32Array, sampleRate: number, options?: DehumOptions): HumDetection;
+//# sourceMappingURL=repair_noise.d.ts.map

package/dist/repair_noise.d.ts.map

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

package/dist/repair_trim.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Silence trimming, with the range detector it shares its geometry with.
+ */
+import type { MasteringRepairTrimSilenceStereoResult, TrimRange } from './public_types_repair';
+/** Trimming modes accepted by `masteringRepairTrimSilence`. */
+export type TrimSilenceMode = 'peak' | 'lufsGated';
+/** Options for `masteringRepairTrimSilence`. */
+export interface TrimSilenceOptions {
+    threshold?: number;
+    paddingSamples?: number;
+    mode?: TrimSilenceMode;
+    gateLufs?: number;
+    windowMs?: number;
+}
+export interface MasteringRepairTrimSilenceRequest extends TrimSilenceOptions {
+    samples: Float32Array;
+    sampleRate: number;
+}
+/** Request form of `masteringRepairTrimSilenceStereo`. */
+export interface MasteringRepairTrimSilenceStereoRequest extends TrimSilenceOptions {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+}
+/** Offline silence trimmer (peak threshold or LUFS-gated). */
+export declare function masteringRepairTrimSilence(request: MasteringRepairTrimSilenceRequest): Float32Array;
+export declare function masteringRepairTrimSilence(samples: Float32Array, sampleRate: number, options?: TrimSilenceOptions): Float32Array;
+/**
+ * Offline silence trimmer for a stereo pair, cutting both channels to one shared range.
+ *
+ * Each channel is scanned on its own and the two ranges are UNIONED, so the pair keeps
+ * whatever either channel calls signal and both outputs come back the same length. The scan
+ * never reads a downmix: `0.5 * (left + right)` halves material carried by one channel alone,
+ * which can drop it under the gate, and cancels an antiphase pair to exactly zero, which would
+ * read full-level audio in both channels as silence. Trimming is destructive, so the rule errs
+ * toward keeping.
+ *
+ * The only repair stereo entry that SHORTENS its input: `result.left.length` is the output
+ * length, and the input's says nothing about it. A pair in which neither channel carries signal
+ * returns two EMPTY arrays and succeeds — it does not throw and does not return null.
+ *
+ * `report.range` is the union that was applied to both channels. `leftRange` and `rightRange`
+ * are the per-channel scans it was formed from, so a caller can see which channel decided each
+ * edge; a channel carrying nothing reports an empty range and contributes nothing to the union.
+ * With nothing kept, `report.range` is `(inputLength, inputLength)`, so `removedHeadSamples` is
+ * the whole input and `removedTailSamples` is 0 — the two still sum to the input length and
+ * only the split between the ends is arbitrary.
+ *
+ * Which option is live depends on `mode`: `threshold` is read ONLY by `'peak'`, and `gateLufs`
+ * and `windowMs` ONLY by `'lufsGated'`. Changing an option the active mode does not read is
+ * silently inert rather than an error.
+ *
+ * That gated mode compares an UNWEIGHTED RMS over a window centred on each sample against
+ * `gateLufs`, so the figure it gates on is dBFS rather than a BS.1770 loudness, and `windowMs`
+ * sizes that window and does nothing else. The window is clipped at the buffer ends, so a
+ * sample near either edge is judged on a shorter one.
+ *
+ * `paddingSamples` widens the kept range in both directions and is clamped to the buffer, so it
+ * can never reach past either end; a pass that kept nothing is not padded. A NEGATIVE count is
+ * refused by name rather than absorbed into 0 or into the default — the underlying field is
+ * unsigned, and a negative one would arrive as an enormous count instead.
+ *
+ * @example
+ * ```ts
+ * const { left, right, report, leftRange, rightRange } = masteringRepairTrimSilenceStereo({
+ *   left: leftSamples,
+ *   right: rightSamples,
+ *   sampleRate: 48000,
+ *   mode: 'peak',
+ *   threshold: 0.01,
+ * });
+ * console.log(left.length, report.removedHeadSamples, leftRange.first, rightRange.first);
+ * ```
+ */
+export declare function masteringRepairTrimSilenceStereo(request: MasteringRepairTrimSilenceStereoRequest): MasteringRepairTrimSilenceStereoResult;
+export declare function masteringRepairTrimSilenceStereo(left: Float32Array, right: Float32Array, sampleRate: number, config?: TrimSilenceOptions): MasteringRepairTrimSilenceStereoResult;
+/** Request form of `masteringRepairDetectTrimRange`. */
+export interface MasteringRepairDetectTrimRangeRequest extends TrimSilenceOptions {
+    samples: Float32Array;
+    sampleRate: number;
+}
+/** Request form of `masteringRepairDetectTrimRangeStereo`. */
+export interface MasteringRepairDetectTrimRangeStereoRequest extends TrimSilenceOptions {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate?: number;
+}
+/**
+ * Measures the range {@link masteringRepairTrimSilence} would keep, without trimming.
+ *
+ * The padding `paddingSamples` asks for is already INSIDE the returned range, so this is the
+ * range the repair would cut to rather than the detected extent of the signal. A buffer with
+ * nothing above the threshold reports `(length, length)`.
+ *
+ * @example
+ * ```ts
+ * const range = masteringRepairDetectTrimRange({ samples, sampleRate: 48000, threshold: 0.01 });
+ * const keptSeconds = (range.lastExclusive - range.first) / 48000;
+ * ```
+ */
+export declare function masteringRepairDetectTrimRange(request: MasteringRepairDetectTrimRangeRequest): TrimRange;
+export declare function masteringRepairDetectTrimRange(samples: Float32Array, sampleRate: number, options?: TrimSilenceOptions): TrimRange;
+/**
+ * Measures the one range a stereo trim pass would cut both channels to.
+ *
+ * Each channel is scanned on its own and the two ranges are UNIONED, so the pair keeps whatever
+ * either channel calls signal. A channel with nothing above the threshold contributes NO EDGE
+ * rather than an edge at the buffer's end: the union of a silent channel and an active one is
+ * the active channel's range exactly, where a naive `min`/`max` would push `lastExclusive` out
+ * to the buffer end and keep the whole tail.
+ *
+ * A downmix is not read: summing to mono halves material carried by one channel alone and
+ * cancels an antiphase pair outright, either of which would read full-level audio as silence.
+ *
+ * @example
+ * ```ts
+ * const range = masteringRepairDetectTrimRangeStereo({ left, right, sampleRate: 48000 });
+ * console.log(range.first, range.lastExclusive);
+ * ```
+ */
+export declare function masteringRepairDetectTrimRangeStereo(request: MasteringRepairDetectTrimRangeStereoRequest): TrimRange;
+export declare function masteringRepairDetectTrimRangeStereo(left: Float32Array, right: Float32Array, sampleRate: number, config?: TrimSilenceOptions): TrimRange;
+//# sourceMappingURL=repair_trim.d.ts.map

package/dist/repair_trim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair_trim.d.ts","sourceRoot":"","sources":["../src/repair_trim.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,sCAAsC,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAM/F,+DAA+D;AAC/D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,WAAW,CAAC;AAEnD,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iCAAkC,SAAQ,kBAAkB;IAC3E,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,0DAA0D;AAC1D,MAAM,WAAW,uCAAwC,SAAQ,kBAAkB;IACjF,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8DAA8D;AAC9D,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iCAAiC,GACzC,YAAY,CAAC;AAChB,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,YAAY,CAAC;AAahB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,uCAAuC,GAC/C,sCAAsC,CAAC;AAC1C,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,sCAAsC,CAAC;AAoB1C,wDAAwD;AACxD,MAAM,WAAW,qCAAsC,SAAQ,kBAAkB;IAC/E,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,8DAA8D;AAC9D,MAAM,WAAW,2CAA4C,SAAQ,kBAAkB;IACrF,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,qCAAqC,GAC7C,SAAS,CAAC;AACb,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,SAAS,CAAC;AAiBb;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,2CAA2C,GACnD,SAAS,CAAC;AACb,wBAAgB,oCAAoC,CAClD,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,SAAS,CAAC"}

package/dist/sample_bank.d.ts

@@ -0,0 +1,84 @@
+import type { SampleDesc, SampleZoneDesc } from './instrument_types';
+/**
+ * Host-supplied PCM for the sample synthesis engine: a bank of float samples
+ * plus key/velocity keymaps, bound alongside a {@link SynthPatch} whose
+ * `engineMode` is `'sample'`.
+ *
+ * {@link Project.loadSoundFont} is the other door into sampled playback — it
+ * parses a container and brings its own generator model. This one takes
+ * waveforms a host already has, described by nothing but a keymap, so playing
+ * them does not require authoring an SF2. Decoding is the caller's job, and
+ * WASM has no host filesystem: the bank takes mono float frames from memory.
+ *
+ * A bank is built on the control thread and then read as immutable data. Add
+ * every sample and zone BEFORE the bounce that binds it starts: the pool is
+ * contiguous and moves as it grows, so a sample added while something sounds
+ * invalidates the voices reading it.
+ *
+ * The embind handle is not garbage-collected, so release it with
+ * {@link SampleBank.delete} once every bounce that names it has finished.
+ *
+ * @example
+ * ```typescript
+ * const bank = new SampleBank();
+ * try {
+ *   const index = bank.addSample(pcm, { rootKey: 60, sourceRate: 44100 });
+ *   bank.addZone({ sampleIndex: index });  // the whole keyboard
+ *   const audio = project.bounceWithSynthInstrument(
+ *     { engineMode: 'sample', sampleSet: 0, sampleBank: bank },
+ *     { totalFrames: 24000 },
+ *   );
+ * } finally {
+ *   bank.delete();
+ * }
+ * ```
+ */
+export declare class SampleBank {
+    private readonly native;
+    private released;
+    /**
+     * Identity a binding names this bank by, so no raw pointer crosses into JS.
+     * Hosts pass the `SampleBank` itself as `sampleBank`.
+     *
+     * @internal
+     */
+    readonly nativeId: number;
+    /** Create an empty bank. */
+    constructor();
+    /**
+     * Copy mono float frames into the bank and return the new sample's index,
+     * which {@link SampleZoneDesc.sampleIndex} names. The frames are copied, so
+     * the array may be reused afterwards.
+     *
+     * Loop points are clamped inside the sample and a loop mode whose loop
+     * survives the clamp empty is dropped, so a malformed loop plays as an
+     * unlooped sample rather than as a wrap over nothing. An empty array, and a
+     * bank that would exceed 67,108,864 sample points, throw.
+     *
+     * A NaN or Inf frame, `fineTuneCents` or `sourceRate` throws too, and the
+     * bank is left unchanged. Such a value is unattributable once stored: the
+     * reader's interpolation spreads one bad frame across the whole sustain, and
+     * a bad tuning offset renders the voice silent with no error raised.
+     */
+    addSample(data: Float32Array, desc?: SampleDesc): number;
+    /**
+     * Append a key/velocity rectangle to a keymap set, creating any sets below
+     * it. A patch names a set; the first zone in it covering a note is the one
+     * that sounds.
+     *
+     * Every bound defaults on its own (see {@link SampleZoneDesc}), so an empty
+     * rectangle is the whole keyboard at every velocity and narrowing one axis
+     * leaves the other whole. A `sampleIndex` the bank does not have, an inverted
+     * key or velocity range, and a `setIndex` at or above 4096 all throw.
+     */
+    addZone(zone?: SampleZoneDesc): void;
+    /** Samples added so far. */
+    sampleCount(): number;
+    /** Keymap sets the bank has (one past the highest index used). */
+    setCount(): number;
+    /** Release the underlying WASM object. Idempotent, as the Node facade is. */
+    delete(): void;
+    /** Alias for {@link SampleBank.delete}, provided for cross-binding (Node) compatibility. */
+    destroy(): void;
+}
+//# sourceMappingURL=sample_bank.d.ts.map

package/dist/sample_bank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample_bank.d.ts","sourceRoot":"","sources":["../src/sample_bank.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,4BAA4B;;IAM5B;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM;IAI5D;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI,GAAE,cAAmB,GAAG,IAAI;IAKxC,4BAA4B;IAC5B,WAAW,IAAI,MAAM;IAIrB,kEAAkE;IAClE,QAAQ,IAAI,MAAM;IAIlB,6EAA6E;IAC7E,MAAM,IAAI,IAAI;IAQd,4FAA4F;IAC5F,OAAO,IAAI,IAAI;CAGhB"}

package/dist/scale.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Snap a MIDI value to the nearest pitch class enabled by `modeMask`.
+ *
+ * `modeMask` is a 12-bit mask. For natural C major use `0b101010110101`.
+ * `referenceMidi` defaults to A4 (69) when passed as 0.
+ */
+export declare function scaleQuantizeMidi(root: number, modeMask: number, midi: number, referenceMidi?: number): number;
+export declare function scaleCorrectionSemitones(root: number, modeMask: number, midi: number, referenceMidi?: number): number;
+export declare function scalePitchClassEnabled(root: number, modeMask: number, pitchClass: number): boolean;
+//# sourceMappingURL=scale.d.ts.map

package/dist/scale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scale.d.ts","sourceRoot":"","sources":["../src/scale.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,aAAa,SAAI,GAChB,MAAM,CAIR;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,aAAa,SAAI,GAChB,MAAM,CAIR;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAET"}