@libraz/libsonare 1.0.4 → 1.1.0

package/dist/index.d.ts

@@ -1,32 +1,7 @@
-/**
- * sonare - Audio Analysis Library
- *
- * @example
- * ```typescript
- * import { init, detectBpm, detectKey, analyze } from '@libraz/sonare';
- *
- * await init();
- *
- * // Detect BPM from audio samples
- * const bpm = detectBpm(samples, sampleRate);
- *
- * // Detect musical key
- * const key = detectKey(samples, sampleRate);
- *
- * // Full analysis
- * const result = analyze(samples, sampleRate);
- * ```
- */
-/**
- * Progress callback for analysis progress reporting.
- * @param progress - Progress value (0.0 to 1.0)
- * @param stage - Current analysis stage name
- */
-export type ProgressCallback = (progress: number, stage: string) => void;
 /**
  * Pitch class enum (C=0, C#=1, ..., B=11)
  */
-export declare const PitchClass: {
+declare const PitchClass: {
     readonly C: 0;
     readonly Cs: 1;
     readonly D: 2;
@@ -40,19 +15,19 @@ export declare const PitchClass: {
     readonly As: 10;
     readonly B: 11;
 };
-export type PitchClass = (typeof PitchClass)[keyof typeof PitchClass];
+type PitchClass = (typeof PitchClass)[keyof typeof PitchClass];
 /**
  * Musical mode
  */
-export declare const Mode: {
+declare const Mode: {
     readonly Major: 0;
     readonly Minor: 1;
 };
-export type Mode = (typeof Mode)[keyof typeof Mode];
+type Mode = (typeof Mode)[keyof typeof Mode];
 /**
  * Chord quality
  */
-export declare const ChordQuality: {
+declare const ChordQuality: {
     readonly Major: 0;
     readonly Minor: 1;
     readonly Diminished: 2;
@@ -63,11 +38,11 @@ export declare const ChordQuality: {
     readonly Sus2: 7;
     readonly Sus4: 8;
 };
-export type ChordQuality = (typeof ChordQuality)[keyof typeof ChordQuality];
+type ChordQuality = (typeof ChordQuality)[keyof typeof ChordQuality];
 /**
  * Section type
  */
-export declare const SectionType: {
+declare const SectionType: {
     readonly Intro: 0;
     readonly Verse: 1;
     readonly PreChorus: 2;
@@ -76,11 +51,11 @@ export declare const SectionType: {
     readonly Instrumental: 5;
     readonly Outro: 6;
 };
-export type SectionType = (typeof SectionType)[keyof typeof SectionType];
+type SectionType = (typeof SectionType)[keyof typeof SectionType];
 /**
  * Detected musical key
  */
-export interface Key {
+interface Key {
     root: PitchClass;
     mode: Mode;
     confidence: number;
@@ -90,14 +65,14 @@ export interface Key {
 /**
  * Detected beat
  */
-export interface Beat {
+interface Beat {
     time: number;
     strength: number;
 }
 /**
  * Detected chord
  */
-export interface Chord {
+interface Chord {
     root: PitchClass;
     quality: ChordQuality;
     start: number;
@@ -108,7 +83,7 @@ export interface Chord {
 /**
  * Detected section
  */
-export interface Section {
+interface Section {
     type: SectionType;
     start: number;
     end: number;
@@ -119,7 +94,7 @@ export interface Section {
 /**
  * Timbre characteristics
  */
-export interface Timbre {
+interface Timbre {
     brightness: number;
     warmth: number;
     density: number;
@@ -129,7 +104,7 @@ export interface Timbre {
 /**
  * Dynamics characteristics
  */
-export interface Dynamics {
+interface Dynamics {
     dynamicRangeDb: number;
     loudnessRangeDb: number;
     crestFactor: number;
@@ -138,7 +113,7 @@ export interface Dynamics {
 /**
  * Time signature
  */
-export interface TimeSignature {
+interface TimeSignature {
     numerator: number;
     denominator: number;
     confidence: number;
@@ -146,7 +121,7 @@ export interface TimeSignature {
 /**
  * Rhythm features
  */
-export interface RhythmFeatures {
+interface RhythmFeatures {
     syncopation: number;
     grooveType: string;
     patternRegularity: number;
@@ -154,7 +129,7 @@ export interface RhythmFeatures {
 /**
  * Complete analysis result
  */
-export interface AnalysisResult {
+interface AnalysisResult {
     bpm: number;
     bpmConfidence: number;
     key: Key;
@@ -171,15 +146,182 @@ export interface AnalysisResult {
 /**
  * HPSS (Harmonic-Percussive Source Separation) result
  */
-export interface HpssResult {
+interface HpssResult {
     harmonic: Float32Array;
     percussive: Float32Array;
     sampleRate: number;
 }
+/**
+ * Mastering loudness/true-peak processing result
+ */
+interface MasteringResult {
+    samples: Float32Array;
+    sampleRate: number;
+    inputLufs: number;
+    outputLufs: number;
+    appliedGainDb: number;
+    latencySamples?: number;
+}
+type MasteringProcessorParams = Record<string, number | boolean>;
+interface MasteringChainConfig {
+    repair?: {
+        denoise?: boolean;
+        nFft?: number;
+        hopLength?: number;
+        ddAlpha?: number;
+        gainFloor?: number;
+        declick?: {
+            threshold?: number;
+            neighborRatio?: number;
+            maxClickSamples?: number;
+            lpcOrder?: number;
+            residualRatio?: number;
+        };
+        dereverb?: {
+            threshold?: number;
+            attenuation?: number;
+            nFft?: number;
+            hopLength?: number;
+            t60Sec?: number;
+            lateDelayMs?: number;
+            overSubtraction?: number;
+            spectralFloor?: number;
+            wpeEnabled?: boolean;
+            wpeIterations?: number;
+            wpeTaps?: number;
+            wpeStrength?: number;
+        };
+    };
+    eq?: {
+        tiltDb?: number;
+        pivotHz?: number;
+    };
+    dynamics?: {
+        compressor?: {
+            thresholdDb?: number;
+            ratio?: number;
+            attackMs?: number;
+            releaseMs?: number;
+            kneeDb?: number;
+            makeupGainDb?: number;
+            autoMakeup?: boolean;
+        };
+        deesser?: {
+            frequencyHz?: number;
+            thresholdDb?: number;
+            ratio?: number;
+            attackMs?: number;
+            releaseMs?: number;
+            rangeDb?: number;
+        };
+        transientShaper?: {
+            attackGainDb?: number;
+            sustainGainDb?: number;
+            fastAttackMs?: number;
+            fastReleaseMs?: number;
+            slowAttackMs?: number;
+            slowReleaseMs?: number;
+            sensitivity?: number;
+            maxGainDb?: number;
+            gainSmoothingMs?: number;
+            lookaheadMs?: number;
+        };
+        multibandComp?: {
+            lowCutoffHz?: number;
+            highCutoffHz?: number;
+            lowThresholdDb?: number;
+            lowRatio?: number;
+            lowAttackMs?: number;
+            lowReleaseMs?: number;
+            midThresholdDb?: number;
+            midRatio?: number;
+            midAttackMs?: number;
+            midReleaseMs?: number;
+            highThresholdDb?: number;
+            highRatio?: number;
+            highAttackMs?: number;
+            highReleaseMs?: number;
+        };
+    };
+    saturation?: {
+        tape?: {
+            driveDb?: number;
+            saturation?: number;
+            hysteresis?: number;
+            outputGainDb?: number;
+            speedIps?: number;
+            headBumpDb?: number;
+            bias?: number;
+            gapLoss?: number;
+        };
+        exciter?: {
+            frequencyHz?: number;
+            driveDb?: number;
+            amount?: number;
+            q?: number;
+            evenOddMix?: number;
+        };
+    };
+    spectral?: {
+        airBand?: {
+            amount?: number;
+            shelfFrequencyHz?: number;
+            dynamicThresholdDb?: number;
+            dynamicRangeDb?: number;
+        };
+    };
+    stereo?: {
+        imager?: {
+            width?: number;
+            outputGainDb?: number;
+            decorrelationAmount?: number;
+            preserveEnergy?: boolean;
+        };
+        monoMaker?: {
+            amount?: number;
+        };
+    };
+    maximizer?: {
+        truePeakLimiter?: {
+            ceilingDb?: number;
+            lookaheadMs?: number;
+            releaseMs?: number;
+            oversampleFactor?: number;
+            applyGainAtInputRate?: boolean;
+        };
+    };
+    loudness?: {
+        targetLufs?: number;
+        ceilingDb?: number;
+        truePeakOversample?: number;
+    };
+}
+interface MasteringChainResult extends MasteringResult {
+    stages: string[];
+}
+interface MasteringStereoChainResult {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate: number;
+    inputLufs: number;
+    outputLufs: number;
+    appliedGainDb: number;
+    stages: string[];
+    latencySamples?: number;
+}
+interface MasteringStereoResult {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate: number;
+    inputLufs: number;
+    outputLufs: number;
+    appliedGainDb: number;
+    latencySamples: number;
+}
 /**
  * STFT (Short-Time Fourier Transform) result
  */
-export interface StftResult {
+interface StftResult {
     nBins: number;
     nFrames: number;
     nFft: number;
@@ -191,7 +333,7 @@ export interface StftResult {
 /**
  * Mel spectrogram result
  */
-export interface MelSpectrogramResult {
+interface MelSpectrogramResult {
     nMels: number;
     nFrames: number;
     sampleRate: number;
@@ -202,7 +344,7 @@ export interface MelSpectrogramResult {
 /**
  * MFCC result
  */
-export interface MfccResult {
+interface MfccResult {
     nMfcc: number;
     nFrames: number;
     coefficients: Float32Array;
@@ -210,7 +352,7 @@ export interface MfccResult {
 /**
  * Chroma features result
  */
-export interface ChromaResult {
+interface ChromaResult {
     nChroma: number;
     nFrames: number;
     sampleRate: number;
@@ -221,7 +363,7 @@ export interface ChromaResult {
 /**
  * Pitch detection result
  */
-export interface PitchResult {
+interface PitchResult {
     f0: Float32Array;
     voicedProb: Float32Array;
     voicedFlag: boolean[];
@@ -229,6 +371,134 @@ export interface PitchResult {
     medianF0: number;
     meanF0: number;
 }
+
+/**
+ * A detected chord change in the progression
+ */
+interface ChordChange {
+    root: PitchClass;
+    quality: ChordQuality;
+    startTime: number;
+    confidence: number;
+}
+/**
+ * A chord detected at bar boundary (beat-synchronized)
+ */
+interface BarChord {
+    barIndex: number;
+    root: PitchClass;
+    quality: ChordQuality;
+    startTime: number;
+    confidence: number;
+}
+/**
+ * Pattern score for known chord progressions
+ */
+interface PatternScore {
+    name: string;
+    score: number;
+}
+/**
+ * Progressive estimation results for BPM, Key, and Chord
+ */
+interface ProgressiveEstimate {
+    bpm: number;
+    bpmConfidence: number;
+    bpmCandidateCount: number;
+    key: PitchClass;
+    keyMinor: boolean;
+    keyConfidence: number;
+    chordRoot: PitchClass;
+    chordQuality: ChordQuality;
+    chordConfidence: number;
+    chordProgression: ChordChange[];
+    barChordProgression: BarChord[];
+    currentBar: number;
+    barDuration: number;
+    votedPattern: BarChord[];
+    patternLength: number;
+    detectedPatternName: string;
+    detectedPatternScore: number;
+    allPatternScores: PatternScore[];
+    accumulatedSeconds: number;
+    usedFrames: number;
+    updated: boolean;
+}
+/**
+ * Statistics and current state of the analyzer
+ */
+interface AnalyzerStats {
+    totalFrames: number;
+    totalSamples: number;
+    durationSeconds: number;
+    estimate: ProgressiveEstimate;
+}
+/**
+ * Frame buffer with analysis results
+ */
+interface FrameBuffer {
+    nFrames: number;
+    timestamps: Float32Array;
+    mel: Float32Array;
+    chroma: Float32Array;
+    onsetStrength: Float32Array;
+    rmsEnergy: Float32Array;
+    spectralCentroid: Float32Array;
+    spectralFlatness: Float32Array;
+    chordRoot: Int32Array;
+    chordQuality: Int32Array;
+    chordConfidence: Float32Array;
+}
+/**
+ * Configuration for StreamAnalyzer
+ */
+interface StreamConfig {
+    sampleRate: number;
+    nFft?: number;
+    hopLength?: number;
+    nMels?: number;
+    computeMel?: boolean;
+    computeChroma?: boolean;
+    computeOnset?: boolean;
+    emitEveryNFrames?: number;
+}
+
+type ProgressCallback = (progress: number, stage: string) => void;
+interface WasmTrimResult {
+    audio: Float32Array;
+    startSample: number;
+    endSample: number;
+}
+interface WasmFrameResult {
+    nFrames: number;
+    frames: Float32Array;
+}
+interface WasmTempogramResult {
+    nFrames: number;
+    winLength: number;
+    data: Float32Array;
+}
+
+/**
+ * sonare - Audio Analysis Library
+ *
+ * @example
+ * ```typescript
+ * import { init, detectBpm, detectKey, analyze } from '@libraz/sonare';
+ *
+ * await init();
+ *
+ * // Detect BPM from audio samples
+ * const bpm = detectBpm(samples, sampleRate);
+ *
+ * // Detect musical key
+ * const key = detectKey(samples, sampleRate);
+ *
+ * // Full analysis
+ * const result = analyze(samples, sampleRate);
+ * ```
+ */
+
 /**
  * Initialize the WASM module.
  * Must be called before using any analysis functions.
@@ -236,17 +506,17 @@ export interface PitchResult {
  * @param options - Optional module configuration
  * @returns Promise that resolves when initialization is complete
  */
-export declare function init(options?: {
+declare function init(options?: {
     locateFile?: (path: string, prefix: string) => string;
 }): Promise<void>;
 /**
  * Check if the module is initialized.
  */
-export declare function isInitialized(): boolean;
+declare function isInitialized(): boolean;
 /**
  * Get the library version.
  */
-export declare function version(): string;
+declare function version(): string;
 /**
  * Detect BPM from audio samples.
  *
@@ -254,7 +524,7 @@ export declare function version(): string;
  * @param sampleRate - Sample rate in Hz
  * @returns Detected BPM
  */
-export declare function detectBpm(samples: Float32Array, sampleRate: number): number;
+declare function detectBpm(samples: Float32Array, sampleRate: number): number;
 /**
  * Detect musical key from audio samples.
  *
@@ -262,7 +532,7 @@ export declare function detectBpm(samples: Float32Array, sampleRate: number): nu
  * @param sampleRate - Sample rate in Hz
  * @returns Detected key
  */
-export declare function detectKey(samples: Float32Array, sampleRate: number): Key;
+declare function detectKey(samples: Float32Array, sampleRate: number): Key;
 /**
  * Detect onset times from audio samples.
  *
@@ -270,7 +540,7 @@ export declare function detectKey(samples: Float32Array, sampleRate: number): Ke
  * @param sampleRate - Sample rate in Hz
  * @returns Array of onset times in seconds
  */
-export declare function detectOnsets(samples: Float32Array, sampleRate: number): Float32Array;
+declare function detectOnsets(samples: Float32Array, sampleRate: number): Float32Array;
 /**
  * Detect beat times from audio samples.
  *
@@ -278,7 +548,7 @@ export declare function detectOnsets(samples: Float32Array, sampleRate: number):
  * @param sampleRate - Sample rate in Hz
  * @returns Array of beat times in seconds
  */
-export declare function detectBeats(samples: Float32Array, sampleRate: number): Float32Array;
+declare function detectBeats(samples: Float32Array, sampleRate: number): Float32Array;
 /**
  * Perform complete music analysis.
  *
@@ -286,7 +556,7 @@ export declare function detectBeats(samples: Float32Array, sampleRate: number):
  * @param sampleRate - Sample rate in Hz
  * @returns Complete analysis result
  */
-export declare function analyze(samples: Float32Array, sampleRate: number): AnalysisResult;
+declare function analyze(samples: Float32Array, sampleRate: number): AnalysisResult;
 /**
  * Perform complete music analysis with progress reporting.
  *
@@ -295,7 +565,7 @@ export declare function analyze(samples: Float32Array, sampleRate: number): Anal
  * @param onProgress - Progress callback (progress: 0-1, stage: string)
  * @returns Complete analysis result
  */
-export declare function analyzeWithProgress(samples: Float32Array, sampleRate: number, onProgress: ProgressCallback): AnalysisResult;
+declare function analyzeWithProgress(samples: Float32Array, sampleRate: number, onProgress: ProgressCallback): AnalysisResult;
 /**
  * Perform Harmonic-Percussive Source Separation (HPSS).
  *
@@ -305,7 +575,7 @@ export declare function analyzeWithProgress(samples: Float32Array, sampleRate: n
  * @param kernelPercussive - Vertical median filter size for percussive (default: 31)
  * @returns Separated harmonic and percussive components
  */
-export declare function hpss(samples: Float32Array, sampleRate: number, kernelHarmonic?: number, kernelPercussive?: number): HpssResult;
+declare function hpss(samples: Float32Array, sampleRate: number, kernelHarmonic?: number, kernelPercussive?: number): HpssResult;
 /**
  * Extract harmonic component from audio.
  *
@@ -313,7 +583,7 @@ export declare function hpss(samples: Float32Array, sampleRate: number, kernelHa
  * @param sampleRate - Sample rate in Hz
  * @returns Harmonic component
  */
-export declare function harmonic(samples: Float32Array, sampleRate: number): Float32Array;
+declare function harmonic(samples: Float32Array, sampleRate: number): Float32Array;
 /**
  * Extract percussive component from audio.
  *
@@ -321,7 +591,7 @@ export declare function harmonic(samples: Float32Array, sampleRate: number): Flo
  * @param sampleRate - Sample rate in Hz
  * @returns Percussive component
  */
-export declare function percussive(samples: Float32Array, sampleRate: number): Float32Array;
+declare function percussive(samples: Float32Array, sampleRate: number): Float32Array;
 /**
  * Time-stretch audio without changing pitch.
  *
@@ -330,7 +600,7 @@ export declare function percussive(samples: Float32Array, sampleRate: number): F
  * @param rate - Time stretch rate (0.5 = double duration, 2.0 = half duration)
  * @returns Time-stretched audio
  */
-export declare function timeStretch(samples: Float32Array, sampleRate: number, rate: number): Float32Array;
+declare function timeStretch(samples: Float32Array, sampleRate: number, rate: number): Float32Array;
 /**
  * Pitch-shift audio without changing duration.
  *
@@ -339,7 +609,7 @@ export declare function timeStretch(samples: Float32Array, sampleRate: number, r
  * @param semitones - Pitch shift in semitones (+12 = one octave up, -12 = one octave down)
  * @returns Pitch-shifted audio
  */
-export declare function pitchShift(samples: Float32Array, sampleRate: number, semitones: number): Float32Array;
+declare function pitchShift(samples: Float32Array, sampleRate: number, semitones: number): Float32Array;
 /**
  * Normalize audio to target peak level.
  *
@@ -348,7 +618,146 @@ export declare function pitchShift(samples: Float32Array, sampleRate: number, se
  * @param targetDb - Target peak level in dB (default: 0 dB = full scale)
  * @returns Normalized audio
  */
-export declare function normalize(samples: Float32Array, sampleRate: number, targetDb?: number): Float32Array;
+declare function normalize(samples: Float32Array, sampleRate: number, targetDb?: number): Float32Array;
+/**
+ * Apply mastering loudness normalization with a true-peak ceiling.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param targetLufs - Target integrated LUFS (default: -14)
+ * @param ceilingDb - True/sample peak ceiling in dBFS (default: -1)
+ * @param truePeakOversample - Oversampling factor used for peak estimation
+ * @returns Processed audio and loudness metadata
+ */
+declare function mastering(samples: Float32Array, sampleRate: number, targetLufs?: number, ceilingDb?: number, truePeakOversample?: number): MasteringResult;
+declare function masteringProcessorNames(): string[];
+declare function masteringPairProcessorNames(): string[];
+declare function masteringPairAnalysisNames(): string[];
+declare function masteringStereoAnalysisNames(): string[];
+declare function masteringProcess(processorName: string, samples: Float32Array, sampleRate: number, params?: MasteringProcessorParams): MasteringResult;
+declare function masteringProcessStereo(processorName: string, left: Float32Array, right: Float32Array, sampleRate: number, params?: MasteringProcessorParams): MasteringStereoResult;
+declare function masteringPairProcess(processorName: string, source: Float32Array, reference: Float32Array, sampleRate: number, params?: MasteringProcessorParams): MasteringResult;
+declare function masteringPairAnalyze(analysisName: string, source: Float32Array, reference: Float32Array, sampleRate: number, params?: MasteringProcessorParams): string;
+declare function masteringStereoAnalyze(analysisName: string, left: Float32Array, right: Float32Array, sampleRate: number, params?: MasteringProcessorParams): string;
+/**
+ * Apply a configurable mastering chain in WASM.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param config - Chain stage configuration
+ * @returns Processed audio, loudness metadata, and applied stage names
+ */
+declare function masteringChain(samples: Float32Array, sampleRate: number, config: MasteringChainConfig): MasteringChainResult;
+/**
+ * Apply a configurable stereo mastering chain in WASM.
+ *
+ * @param left - Left channel samples
+ * @param right - Right channel samples
+ * @param sampleRate - Sample rate in Hz
+ * @param config - Chain stage configuration
+ * @returns Processed stereo audio, loudness metadata, and applied stage names
+ */
+declare function masteringChainStereo(left: Float32Array, right: Float32Array, sampleRate: number, config: MasteringChainConfig): MasteringStereoChainResult;
+/**
+ * Apply a configurable mastering chain in WASM with progress reporting.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param config - Chain stage configuration
+ * @param onProgress - Progress callback (progress: 0-1, stage: string)
+ * @returns Processed audio, loudness metadata, and applied stage names
+ */
+declare function masteringChainWithProgress(samples: Float32Array, sampleRate: number, config: MasteringChainConfig, onProgress: ProgressCallback): MasteringChainResult;
+/**
+ * Apply a configurable stereo mastering chain in WASM with progress reporting.
+ *
+ * @param left - Left channel samples
+ * @param right - Right channel samples
+ * @param sampleRate - Sample rate in Hz
+ * @param config - Chain stage configuration
+ * @param onProgress - Progress callback (progress: 0-1, stage: string)
+ * @returns Processed stereo audio, loudness metadata, and applied stage names
+ */
+declare function masteringChainStereoWithProgress(left: Float32Array, right: Float32Array, sampleRate: number, config: MasteringChainConfig, onProgress: ProgressCallback): MasteringStereoChainResult;
+/**
+ * List built-in mastering preset identifiers.
+ *
+ * @returns Preset names in display order (e.g. "pop", "edm", "aiMusic")
+ */
+declare function masteringPresetNames(): string[];
+/**
+ * Apply a named mastering preset chain to mono audio.
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param presetName - Preset identifier from {@link masteringPresetNames}
+ * @param overrides - Optional flat overrides (dot-notation, e.g. `'loudness.targetLufs'`) applied on top of the preset. Pass `null` for preset defaults.
+ * @returns Processed audio, loudness metadata, and applied stage names
+ */
+declare function masterAudio(samples: Float32Array, sampleRate: number, presetName: string, overrides?: Record<string, number | boolean> | null): MasteringChainResult;
+/**
+ * Apply a named mastering preset chain to stereo audio.
+ *
+ * @param left - Left channel samples
+ * @param right - Right channel samples
+ * @param sampleRate - Sample rate in Hz
+ * @param presetName - Preset identifier from {@link masteringPresetNames}
+ * @param overrides - Optional flat overrides (dot-notation, e.g. `'loudness.targetLufs'`) applied on top of the preset. Pass `null` for preset defaults.
+ * @returns Processed stereo audio, loudness metadata, and applied stage names
+ */
+declare function masterAudioStereo(left: Float32Array, right: Float32Array, sampleRate: number, presetName: string, overrides?: Record<string, number | boolean> | null): MasteringStereoChainResult;
+/**
+ * Block-by-block streaming variant of {@link masteringChain}.
+ *
+ * Maintains processor state across {@link processMono}/{@link processStereo}
+ * calls. Only ProcessorBase-backed stages are supported. Configurations that
+ * enable `repair.denoise` or `loudness` throw at construction.
+ *
+ * Call {@link delete} (or use a `try/finally`) to release the underlying WASM
+ * object — the embind handle is not garbage-collected automatically.
+ *
+ * @example
+ * ```typescript
+ * const chain = new StreamingMasteringChain({ eq: { tiltDb: 1.0 } });
+ * try {
+ *   chain.prepare(44100, 512, 1);
+ *   const out = chain.processMono(blockSamples);
+ * } finally {
+ *   chain.delete();
+ * }
+ * ```
+ */
+declare class StreamingMasteringChain {
+    private chain;
+    constructor(config: MasteringChainConfig);
+    /**
+     * 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;
+    };
+    /** 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[];
+    /** Release the underlying WASM object. Safe to call only once. */
+    delete(): void;
+}
 /**
  * Trim silence from beginning and end of audio.
  *
@@ -357,7 +766,7 @@ export declare function normalize(samples: Float32Array, sampleRate: number, tar
  * @param thresholdDb - Silence threshold in dB (default: -60 dB)
  * @returns Trimmed audio
  */
-export declare function trim(samples: Float32Array, sampleRate: number, thresholdDb?: number): Float32Array;
+declare function trim(samples: Float32Array, sampleRate: number, thresholdDb?: number): Float32Array;
 /**
  * Compute Short-Time Fourier Transform (STFT).
  *
@@ -367,7 +776,7 @@ export declare function trim(samples: Float32Array, sampleRate: number, threshol
  * @param hopLength - Hop length (default: 512)
  * @returns STFT result with magnitude and power spectrograms
  */
-export declare function stft(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): StftResult;
+declare function stft(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): StftResult;
 /**
  * Compute STFT and return magnitude in decibels.
  *
@@ -377,7 +786,7 @@ export declare function stft(samples: Float32Array, sampleRate: number, nFft?: n
  * @param hopLength - Hop length (default: 512)
  * @returns STFT result with dB values
  */
-export declare function stftDb(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): {
+declare function stftDb(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): {
     nBins: number;
     nFrames: number;
     db: Float32Array;
@@ -392,7 +801,7 @@ export declare function stftDb(samples: Float32Array, sampleRate: number, nFft?:
  * @param nMels - Number of Mel bands (default: 128)
  * @returns Mel spectrogram result
  */
-export declare function melSpectrogram(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number, nMels?: number): MelSpectrogramResult;
+declare function melSpectrogram(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number, nMels?: number): MelSpectrogramResult;
 /**
  * Compute MFCC (Mel-Frequency Cepstral Coefficients).
  *
@@ -404,7 +813,7 @@ export declare function melSpectrogram(samples: Float32Array, sampleRate: number
  * @param nMfcc - Number of MFCC coefficients (default: 13)
  * @returns MFCC result
  */
-export declare function mfcc(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number, nMels?: number, nMfcc?: number): MfccResult;
+declare function mfcc(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number, nMels?: number, nMfcc?: number): MfccResult;
 /**
  * Compute chromagram (pitch class distribution).
  *
@@ -414,7 +823,7 @@ export declare function mfcc(samples: Float32Array, sampleRate: number, nFft?: n
  * @param hopLength - Hop length (default: 512)
  * @returns Chroma features result
  */
-export declare function chroma(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): ChromaResult;
+declare function chroma(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): ChromaResult;
 /**
  * Compute spectral centroid (center of mass of spectrum).
  *
@@ -424,7 +833,7 @@ export declare function chroma(samples: Float32Array, sampleRate: number, nFft?:
  * @param hopLength - Hop length (default: 512)
  * @returns Spectral centroid in Hz for each frame
  */
-export declare function spectralCentroid(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): Float32Array;
+declare function spectralCentroid(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): Float32Array;
 /**
  * Compute spectral bandwidth.
  *
@@ -434,7 +843,7 @@ export declare function spectralCentroid(samples: Float32Array, sampleRate: numb
  * @param hopLength - Hop length (default: 512)
  * @returns Spectral bandwidth in Hz for each frame
  */
-export declare function spectralBandwidth(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): Float32Array;
+declare function spectralBandwidth(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): Float32Array;
 /**
  * Compute spectral rolloff frequency.
  *
@@ -445,7 +854,7 @@ export declare function spectralBandwidth(samples: Float32Array, sampleRate: num
  * @param rollPercent - Percentage threshold (default: 0.85)
  * @returns Rolloff frequency in Hz for each frame
  */
-export declare function spectralRolloff(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number, rollPercent?: number): Float32Array;
+declare function spectralRolloff(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number, rollPercent?: number): Float32Array;
 /**
  * Compute spectral flatness.
  *
@@ -455,7 +864,7 @@ export declare function spectralRolloff(samples: Float32Array, sampleRate: numbe
  * @param hopLength - Hop length (default: 512)
  * @returns Spectral flatness for each frame (0 = tonal, 1 = noise-like)
  */
-export declare function spectralFlatness(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): Float32Array;
+declare function spectralFlatness(samples: Float32Array, sampleRate: number, nFft?: number, hopLength?: number): Float32Array;
 /**
  * Compute zero crossing rate.
  *
@@ -465,7 +874,7 @@ export declare function spectralFlatness(samples: Float32Array, sampleRate: numb
  * @param hopLength - Hop length (default: 512)
  * @returns Zero crossing rate for each frame
  */
-export declare function zeroCrossingRate(samples: Float32Array, sampleRate: number, frameLength?: number, hopLength?: number): Float32Array;
+declare function zeroCrossingRate(samples: Float32Array, sampleRate: number, frameLength?: number, hopLength?: number): Float32Array;
 /**
  * Compute RMS energy.
  *
@@ -475,7 +884,7 @@ export declare function zeroCrossingRate(samples: Float32Array, sampleRate: numb
  * @param hopLength - Hop length (default: 512)
  * @returns RMS energy for each frame
  */
-export declare function rmsEnergy(samples: Float32Array, sampleRate: number, frameLength?: number, hopLength?: number): Float32Array;
+declare function rmsEnergy(samples: Float32Array, sampleRate: number, frameLength?: number, hopLength?: number): Float32Array;
 /**
  * Detect pitch using YIN algorithm.
  *
@@ -488,7 +897,7 @@ export declare function rmsEnergy(samples: Float32Array, sampleRate: number, fra
  * @param threshold - YIN threshold (default: 0.3)
  * @returns Pitch detection result
  */
-export declare function pitchYin(samples: Float32Array, sampleRate: number, frameLength?: number, hopLength?: number, fmin?: number, fmax?: number, threshold?: number): PitchResult;
+declare function pitchYin(samples: Float32Array, sampleRate: number, frameLength?: number, hopLength?: number, fmin?: number, fmax?: number, threshold?: number): PitchResult;
 /**
  * Detect pitch using pYIN algorithm (probabilistic YIN with HMM smoothing).
  *
@@ -501,49 +910,49 @@ export declare function pitchYin(samples: Float32Array, sampleRate: number, fram
  * @param threshold - YIN threshold (default: 0.3)
  * @returns Pitch detection result
  */
-export declare function pitchPyin(samples: Float32Array, sampleRate: number, frameLength?: number, hopLength?: number, fmin?: number, fmax?: number, threshold?: number): PitchResult;
+declare function pitchPyin(samples: Float32Array, sampleRate: number, frameLength?: number, hopLength?: number, fmin?: number, fmax?: number, threshold?: number): PitchResult;
 /**
  * Convert frequency in Hz to Mel scale.
  *
  * @param hz - Frequency in Hz
  * @returns Mel frequency
  */
-export declare function hzToMel(hz: number): number;
+declare function hzToMel(hz: number): number;
 /**
  * Convert Mel scale to frequency in Hz.
  *
  * @param mel - Mel frequency
  * @returns Frequency in Hz
  */
-export declare function melToHz(mel: number): number;
+declare function melToHz(mel: number): number;
 /**
  * Convert frequency in Hz to MIDI note number.
  *
  * @param hz - Frequency in Hz
  * @returns MIDI note number (A4 = 440 Hz = 69)
  */
-export declare function hzToMidi(hz: number): number;
+declare function hzToMidi(hz: number): number;
 /**
  * Convert MIDI note number to frequency in Hz.
  *
  * @param midi - MIDI note number
  * @returns Frequency in Hz
  */
-export declare function midiToHz(midi: number): number;
+declare function midiToHz(midi: number): number;
 /**
  * Convert frequency in Hz to note name.
  *
  * @param hz - Frequency in Hz
  * @returns Note name (e.g., "A4", "C#5")
  */
-export declare function hzToNote(hz: number): string;
+declare function hzToNote(hz: number): string;
 /**
  * Convert note name to frequency in Hz.
  *
  * @param note - Note name (e.g., "A4", "C#5")
  * @returns Frequency in Hz
  */
-export declare function noteToHz(note: string): number;
+declare function noteToHz(note: string): number;
 /**
  * Convert frame index to time in seconds.
  *
@@ -552,7 +961,7 @@ export declare function noteToHz(note: string): number;
  * @param hopLength - Hop length in samples
  * @returns Time in seconds
  */
-export declare function framesToTime(frames: number, sr: number, hopLength: number): number;
+declare function framesToTime(frames: number, sr: number, hopLength: number): number;
 /**
  * Convert time in seconds to frame index.
  *
@@ -561,7 +970,27 @@ export declare function framesToTime(frames: number, sr: number, hopLength: numb
  * @param hopLength - Hop length in samples
  * @returns Frame index
  */
-export declare function timeToFrames(time: number, sr: number, hopLength: number): number;
+declare function timeToFrames(time: number, sr: number, hopLength: number): number;
+declare function framesToSamples(frames: number, hopLength?: number, nFft?: number): number;
+declare function samplesToFrames(samples: number, hopLength?: number, nFft?: number): number;
+declare function powerToDb(values: Float32Array, ref?: number, amin?: number, topDb?: number): Float32Array;
+declare function amplitudeToDb(values: Float32Array, ref?: number, amin?: number, topDb?: number): Float32Array;
+declare function dbToPower(values: Float32Array, ref?: number): Float32Array;
+declare function dbToAmplitude(values: Float32Array, ref?: number): Float32Array;
+declare function preemphasis(samples: Float32Array, coef?: number, zi?: number): Float32Array;
+declare function deemphasis(samples: Float32Array, coef?: number, zi?: number): Float32Array;
+declare function trimSilence(samples: Float32Array, topDb?: number, frameLength?: number, hopLength?: number): WasmTrimResult;
+declare function splitSilence(samples: Float32Array, topDb?: number, frameLength?: number, hopLength?: number): Int32Array;
+declare function frameSignal(samples: Float32Array, frameLength: number, hopLength: number): WasmFrameResult;
+declare function padCenter(values: Float32Array, size: number, padValue?: number): Float32Array;
+declare function fixLength(values: Float32Array, size: number, padValue?: number): Float32Array;
+declare function fixFrames(frames: Int32Array, xMin?: number, xMax?: number, pad?: boolean): Int32Array;
+declare function peakPick(values: Float32Array, preMax: number, postMax: number, preAvg: number, postAvg: number, delta: number, wait: number): Int32Array;
+declare function vectorNormalize(values: Float32Array, normType?: number, threshold?: number): Float32Array;
+declare function pcen(values: Float32Array, nBins: number, nFrames: number, options?: Record<string, number>): Float32Array;
+declare function tonnetz(chromagram: Float32Array, nChroma: number, nFrames: number): Float32Array;
+declare function tempogram(onsetEnvelope: Float32Array, sampleRate: number, hopLength?: number, winLength?: number): WasmTempogramResult;
+declare function plp(onsetEnvelope: Float32Array, sampleRate: number, hopLength?: number, tempoMin?: number, tempoMax?: number, winLength?: number): Float32Array;
 /**
  * Resample audio to a different sample rate.
  *
@@ -570,7 +999,7 @@ export declare function timeToFrames(time: number, sr: number, hopLength: number
  * @param targetSr - Target sample rate in Hz
  * @returns Resampled audio
  */
-export declare function resample(samples: Float32Array, srcSr: number, targetSr: number): Float32Array;
+declare function resample(samples: Float32Array, srcSr: number, targetSr: number): Float32Array;
 /**
  * Wrapper around audio data that exposes all analysis and feature functions as instance methods.
  *
@@ -587,7 +1016,7 @@ export declare function resample(samples: Float32Array, srcSr: number, targetSr:
  * const mel = audio.melSpectrogram();
  * ```
  */
-export declare class Audio {
+declare class Audio {
     private _samples;
     private _sampleRate;
     private constructor();
@@ -613,6 +1042,10 @@ export declare class Audio {
     timeStretch(rate: number): Float32Array;
     pitchShift(semitones: number): Float32Array;
     normalize(targetDb?: number): Float32Array;
+    mastering(targetLufs?: number, ceilingDb?: number, truePeakOversample?: number): MasteringResult;
+    masteringChain(config: MasteringChainConfig): MasteringChainResult;
+    masterAudio(presetName: string, overrides?: Record<string, number | boolean> | null): MasteringChainResult;
+    masteringProcess(processorName: string, params?: MasteringProcessorParams): MasteringResult;
     trim(thresholdDb?: number): Float32Array;
     stft(nFft?: number, hopLength?: number): StftResult;
     stftDb(nFft?: number, hopLength?: number): {
@@ -633,96 +1066,6 @@ export declare class Audio {
     pitchPyin(frameLength?: number, hopLength?: number, fmin?: number, fmax?: number, threshold?: number): PitchResult;
     resample(targetSr: number): Float32Array;
 }
-/**
- * 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 {
-    barIndex: number;
-    root: PitchClass;
-    quality: ChordQuality;
-    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;
-    bpmCandidateCount: number;
-    key: PitchClass;
-    keyMinor: boolean;
-    keyConfidence: number;
-    chordRoot: PitchClass;
-    chordQuality: ChordQuality;
-    chordConfidence: number;
-    chordProgression: ChordChange[];
-    barChordProgression: BarChord[];
-    currentBar: number;
-    barDuration: number;
-    votedPattern: BarChord[];
-    patternLength: number;
-    detectedPatternName: string;
-    detectedPatternScore: number;
-    allPatternScores: PatternScore[];
-    accumulatedSeconds: number;
-    usedFrames: number;
-    updated: boolean;
-}
-/**
- * Statistics and current state of the analyzer
- */
-export interface AnalyzerStats {
-    totalFrames: number;
-    totalSamples: number;
-    durationSeconds: number;
-    estimate: ProgressiveEstimate;
-}
-/**
- * Frame buffer with analysis results
- */
-export interface FrameBuffer {
-    nFrames: number;
-    timestamps: Float32Array;
-    mel: Float32Array;
-    chroma: Float32Array;
-    onsetStrength: Float32Array;
-    rmsEnergy: Float32Array;
-    spectralCentroid: Float32Array;
-    spectralFlatness: Float32Array;
-    chordRoot: Int32Array;
-    chordQuality: Int32Array;
-    chordConfidence: Float32Array;
-}
-/**
- * Configuration for StreamAnalyzer
- */
-export interface StreamConfig {
-    sampleRate: number;
-    nFft?: number;
-    hopLength?: number;
-    nMels?: number;
-    computeMel?: boolean;
-    computeChroma?: boolean;
-    computeOnset?: boolean;
-    emitEveryNFrames?: number;
-}
 /**
  * Real-time streaming audio analyzer.
  *
@@ -744,7 +1087,7 @@ export interface StreamConfig {
  * console.log('Chord progression:', stats.estimate.chordProgression);
  * ```
  */
-export declare class StreamAnalyzer {
+declare class StreamAnalyzer {
     private analyzer;
     /**
      * Create a new StreamAnalyzer.
@@ -828,5 +1171,5 @@ export declare class StreamAnalyzer {
      */
     dispose(): void;
 }
-export { PitchClass as Pitch };
-//# sourceMappingURL=index.d.ts.map
+
+export { type AnalysisResult, type AnalyzerStats, Audio, type BarChord, type Beat, type Chord, type ChordChange, ChordQuality, type ChromaResult, type Dynamics, type FrameBuffer, type HpssResult, type Key, type MasteringChainConfig, type MasteringChainResult, type MasteringProcessorParams, type MasteringResult, type MasteringStereoChainResult, type MasteringStereoResult, type MelSpectrogramResult, type MfccResult, Mode, type PatternScore, PitchClass as Pitch, PitchClass, type PitchResult, type ProgressCallback, type ProgressiveEstimate, type RhythmFeatures, type Section, SectionType, type StftResult, StreamAnalyzer, type StreamConfig, StreamingMasteringChain, type Timbre, type TimeSignature, amplitudeToDb, analyze, analyzeWithProgress, chroma, dbToAmplitude, dbToPower, deemphasis, detectBeats, detectBpm, detectKey, detectOnsets, fixFrames, fixLength, frameSignal, framesToSamples, framesToTime, harmonic, hpss, hzToMel, hzToMidi, hzToNote, init, isInitialized, masterAudio, masterAudioStereo, mastering, masteringChain, masteringChainStereo, masteringChainStereoWithProgress, masteringChainWithProgress, masteringPairAnalysisNames, masteringPairAnalyze, masteringPairProcess, masteringPairProcessorNames, masteringPresetNames, masteringProcess, masteringProcessStereo, masteringProcessorNames, masteringStereoAnalysisNames, masteringStereoAnalyze, melSpectrogram, melToHz, mfcc, midiToHz, normalize, noteToHz, padCenter, pcen, peakPick, percussive, pitchPyin, pitchShift, pitchYin, plp, powerToDb, preemphasis, resample, rmsEnergy, samplesToFrames, spectralBandwidth, spectralCentroid, spectralFlatness, spectralRolloff, splitSilence, stft, stftDb, tempogram, timeStretch, timeToFrames, tonnetz, trim, trimSilence, vectorNormalize, version, zeroCrossingRate };