@octoseq/mir 0.1.0-main.4ecb074 → 0.1.0-main.5fdb072

package/dist/index.d.ts

@@ -1,23 +1,7 @@
-export { c as Mir1DResult, d as Mir2DResult, h as MirAudioPayload, M as MirBackend, f as MirFunctionId, e as MirResult, b as MirRunMeta, g as MirRunRequest, a as MirRunTimings } from './types-BE3py4fZ.js';
-import { S as Spectrogram, M as MirGPU } from './runMir-CSIBwNZ3.js';
-export { a as SpectrogramConfig, r as runMir, s as spectrogram } from './runMir-CSIBwNZ3.js';
-
-/**
- * Spectral centroid per frame (Hz).
- *
- * Output is aligned 1:1 with `spec.times`.
- */
-declare function spectralCentroid(spec: Spectrogram): Float32Array;
-/**
- * Spectral flux per frame (unitless).
- *
- * Definition used here:
- * - L1 distance between successive *normalised* magnitude spectra.
- * - First frame flux is 0.
- *
- * Output is aligned 1:1 with `spec.times`.
- */
-declare function spectralFlux(spec: Spectrogram): Float32Array;
+import { B as BeatCandidate, T as TempoHypothesis, P as PhaseAlignmentConfig, a as PhaseHypothesis, M as MusicalTimeSegment, b as BeatPosition, c as MusicalTimeStructure, d as BeatGrid, F as FrequencySegment, e as FrequencyBand, f as FrequencyBandStructure, g as FrequencyBoundsAtTime, h as FrequencyKeyframe, i as BandMirFunctionId, j as BandMir1DResult, k as BandEventFunctionId, l as BandEventsResult, C as CqtConfig, m as BandCqtFunctionId, n as BandCqt1DResult, o as CqtSpectrogram, p as MirRunMeta, q as CqtSignalResult, r as CqtSignalId, s as BandProposalConfig, t as BandProposalResult } from './types-DqH4umN8.js';
+export { S as BandEventDiagnostics, Q as BandMirDiagnostics, R as BandMirEvent, V as BandProposal, U as BandProposalSource, H as BeatCandidateSource, I as BeatCandidatesResult, O as FrequencyBandProvenance, N as FrequencyBandTimeScope, w as Mir1DResult, x as Mir2DResult, y as MirActivityDiagnostics, z as MirActivityResult, G as MirAudioPayload, u as MirBackend, D as MirFunctionId, A as MirResult, E as MirRunRequest, v as MirRunTimings, L as MusicalTimeProvenance, K as TempoHypothesesResult, J as TempoHypothesisEvidence } from './types-DqH4umN8.js';
+import { S as Spectrogram, M as MirGPU, A as AudioBufferLike$1 } from './runMir-CnJQbBr8.js';
+export { a as SpectrogramConfig, r as runMir, s as spectrogram } from './runMir-CnJQbBr8.js';
 
 type MelConfig = {
     nMels: number;
@@ -32,6 +16,42 @@ type MelSpectrogram = {
         gpuSubmitToReadbackMs: number;
     };
 };
+/**
+ * Convert frequency in Hz to mel scale.
+ * Uses Slaney-style (HTK-like) approximation.
+ */
+declare function hzToMel(hz: number): number;
+/**
+ * Convert mel scale value to frequency in Hz.
+ * Inverse of hzToMel.
+ */
+declare function melToHz(mel: number): number;
+/**
+ * Configuration for mel frequency conversions.
+ */
+type MelConversionConfig = {
+    nMels: number;
+    fMin: number;
+    fMax: number;
+};
+/**
+ * Convert a frequency in Hz to a feature index (0 to nMels-1).
+ * The mapping is linear in mel space.
+ *
+ * @param hz - Frequency in Hz
+ * @param config - Mel configuration with nMels, fMin, fMax
+ * @returns Feature index as a continuous value (may be fractional)
+ */
+declare function hzToFeatureIndex(hz: number, config: MelConversionConfig): number;
+/**
+ * Convert a feature index (0 to nMels-1) to frequency in Hz.
+ * Inverse of hzToFeatureIndex.
+ *
+ * @param index - Feature index (can be fractional)
+ * @param config - Mel configuration with nMels, fMin, fMax
+ * @returns Frequency in Hz
+ */
+declare function featureIndexToHz(index: number, config: MelConversionConfig): number;
 /**
  * Compute a (log) mel spectrogram by projecting an existing spectrogram.
  *
@@ -41,10 +61,437 @@ type MelSpectrogram = {
  */
 declare function melSpectrogram(spec: Spectrogram, config: MelConfig, gpu?: MirGPU): Promise<MelSpectrogram>;
 
+/**
+ * Activity Signal - First-class MIR feature for audibility detection.
+ *
+ * The Activity Signal represents whether audible content is present at each frame.
+ * It is the foundation for silence-aware MIR processing across all features.
+ *
+ * Design Principles:
+ * 1. Silence is a distinct state, not "low energy sound"
+ * 2. Activity detection is shared, not reimplemented per feature
+ * 3. Activity is computed from whole-track context (adaptive thresholds)
+ * 4. The signal is inspectable and visualizable
+ *
+ * Semantics:
+ * - activity_level: 0 = silence/inaudible, 1 = confidently audible
+ * - is_active: boolean derived from activity_level
+ */
+
+/**
+ * Configuration for activity detection.
+ */
+type ActivityConfig = {
+    /**
+     * Percentile (0-100) used to estimate the noise floor from frame energies.
+     * Lower values are more conservative (estimate floor from quieter frames).
+     * @default 10
+     */
+    energyPercentile?: number;
+    /**
+     * Margin above noise floor to enter active state.
+     * For log-scale energies (mel), this is effectively dB.
+     * @default 6
+     */
+    enterMargin?: number;
+    /**
+     * Margin above noise floor to remain in active state.
+     * Must be less than enterMargin for proper hysteresis.
+     * @default 3
+     */
+    exitMargin?: number;
+    /**
+     * Duration in milliseconds to remain active after energy drops below exit threshold.
+     * Prevents rapid toggling near silence.
+     * @default 50
+     */
+    hangoverMs?: number;
+    /**
+     * Minimum duration in milliseconds a region must be active.
+     * Regions shorter than this are marked inactive.
+     * @default 30
+     */
+    minActiveMs?: number;
+    /**
+     * Smoothing window in milliseconds for activity_level output.
+     * Produces smoother transitions. 0 = no smoothing.
+     * @default 20
+     */
+    smoothMs?: number;
+};
+/**
+ * Activity Signal result - the main output type.
+ */
+type ActivitySignal = {
+    /** Frame times in seconds, aligned with source spectrogram/mel. */
+    times: Float32Array;
+    /**
+     * Continuous activity level in range [0, 1].
+     * 0 = silence, 1 = confidently active.
+     * Intermediate values occur at transitions and represent uncertainty.
+     */
+    activityLevel: Float32Array;
+    /**
+     * Binary activity mask (0 = inactive, 1 = active).
+     * Derived from the underlying hysteresis state machine.
+     */
+    isActive: Uint8Array;
+    /**
+     * Per-frame suppression mask (0 = allow, 1 = suppress).
+     * Used to suppress features immediately after silence-to-active transitions.
+     */
+    suppressMask: Uint8Array;
+    /** Diagnostic information for debugging and visualization. */
+    diagnostics: ActivityDiagnostics;
+};
+/**
+ * Diagnostics for inspecting activity detection behavior.
+ */
+type ActivityDiagnostics = {
+    /** Per-frame energy values used for detection. */
+    frameEnergy: Float32Array;
+    /** Estimated noise floor value. */
+    noiseFloor: number;
+    /** Threshold for entering active state. */
+    enterThreshold: number;
+    /** Threshold for exiting active state. */
+    exitThreshold: number;
+};
+/**
+ * Compute Activity Signal from mel spectrogram.
+ *
+ * This is the primary entry point for activity detection.
+ * Mel spectrograms are preferred because their log-scale energies
+ * provide more perceptually meaningful thresholds.
+ *
+ * @param mel - Mel spectrogram (log-scale energies)
+ * @param config - Activity detection configuration
+ * @returns Complete activity signal with diagnostics
+ */
+declare function computeActivityFromMel(mel: MelSpectrogram, config?: ActivityConfig): ActivitySignal;
+/**
+ * Compute Activity Signal from linear magnitude spectrogram.
+ *
+ * This function first converts magnitudes to log scale for threshold computation.
+ *
+ * @param spec - Linear magnitude spectrogram
+ * @param config - Activity detection configuration
+ * @returns Complete activity signal with diagnostics
+ */
+declare function computeActivityFromSpectrogram(spec: Spectrogram, config?: ActivityConfig): ActivitySignal;
+/**
+ * Compute Activity Signal from raw audio samples.
+ *
+ * Uses a simple RMS-based energy computation. This is useful when
+ * no spectrogram is available, but mel-based detection is preferred.
+ *
+ * @param samples - Mono audio samples
+ * @param sampleRate - Sample rate of the audio
+ * @param hopSize - Analysis hop size in samples
+ * @param windowSize - Analysis window size in samples
+ * @param config - Activity detection configuration
+ * @returns Complete activity signal with diagnostics
+ */
+declare function computeActivityFromAudio(samples: Float32Array, sampleRate: number, hopSize: number, windowSize: number, config?: ActivityConfig): ActivitySignal;
+/**
+ * Apply activity gating to a 1D signal.
+ *
+ * Zeros out values where activity is low.
+ *
+ * @param values - Signal values to gate (modified in place)
+ * @param activity - Activity signal
+ * @param options - Gating options
+ */
+declare function applyActivityGating(values: Float32Array, activity: ActivitySignal, options?: {
+    /** Use binary mask instead of continuous level. Default: true */
+    useBinaryMask?: boolean;
+    /** Also apply post-silence suppression. Default: true */
+    suppressPostSilence?: boolean;
+    /** Threshold for activity_level when not using binary mask. Default: 0.5 */
+    levelThreshold?: number;
+}): void;
+/**
+ * Interpolate activity signal to a different time grid.
+ *
+ * Useful when you have activity computed at one resolution (e.g., mel frames)
+ * but need it at another resolution (e.g., pitch frames).
+ *
+ * @param activity - Source activity signal
+ * @param targetTimes - Target time grid
+ * @returns Activity signal interpolated to target times
+ */
+declare function interpolateActivity(activity: ActivitySignal, targetTimes: Float32Array): ActivitySignal;
+
+/**
+ * Options for activity-aware spectral features.
+ */
+type SpectralActivityOptions = {
+    /**
+     * Activity signal to use for gating.
+     * If provided, feature values will be zeroed in inactive regions.
+     */
+    activity?: ActivitySignal;
+    /**
+     * Behavior for inactive frames.
+     * - "zero": Output 0 (default)
+     * - "hold": Hold the last active value
+     */
+    inactiveBehavior?: "zero" | "hold";
+};
+type AmplitudeEnvelopeConfig = {
+    /** Hop size in samples (determines time resolution). Default: 512 */
+    hopSize?: number;
+    /** Window size for RMS calculation. Default: same as hopSize */
+    windowSize?: number;
+};
+type AmplitudeEnvelopeResult = {
+    times: Float32Array;
+    values: Float32Array;
+};
+/**
+ * Amplitude envelope from raw audio samples.
+ *
+ * Computes RMS amplitude over windows of the time-domain signal.
+ * More efficient than spectrogram-based computation for full spectrum.
+ *
+ * @param samples - Mono audio samples
+ * @param sampleRate - Sample rate of the audio
+ * @param config - Configuration options
+ * @returns Times (seconds) and RMS amplitude values
+ */
+declare function amplitudeEnvelope(samples: Float32Array, sampleRate: number, config?: AmplitudeEnvelopeConfig): AmplitudeEnvelopeResult;
+/**
+ * Spectral centroid per frame (Hz).
+ *
+ * Output is aligned 1:1 with `spec.times`.
+ *
+ * When activity gating is enabled:
+ * - Inactive frames output 0 (or hold last valid value if configured)
+ * - This prevents noise-induced centroid values during silence
+ *
+ * @param spec - Input spectrogram
+ * @param options - Activity gating options
+ */
+declare function spectralCentroid(spec: Spectrogram, options?: SpectralActivityOptions): Float32Array;
+/**
+ * Spectral flux per frame (unitless).
+ *
+ * Definition used here:
+ * - L1 distance between successive *normalised* magnitude spectra.
+ * - First frame flux is 0.
+ *
+ * Output is aligned 1:1 with `spec.times`.
+ *
+ * When activity gating is enabled:
+ * - Inactive frames output 0
+ * - Post-silence suppression is applied (first active frames after silence are zeroed)
+ * - This prevents false flux spikes at silence/sound boundaries
+ *
+ * @param spec - Input spectrogram
+ * @param options - Activity gating options
+ */
+declare function spectralFlux(spec: Spectrogram, options?: SpectralActivityOptions): Float32Array;
+
+/**
+ * Silence-aware gating for onset detection.
+ *
+ * This module implements a production-grade silence detection and activity masking
+ * pipeline. Silence is treated as a first-class state, not "low energy sound".
+ *
+ * Pipeline stages:
+ * 1. Frame-level energy computation
+ * 2. Adaptive noise floor estimation (percentile-based)
+ * 3. Activity mask with hysteresis and hangover
+ * 4. Post-silence suppression window
+ *
+ * Design principles:
+ * - No fixed absolute thresholds - all thresholds are relative to estimated noise floor
+ * - Hysteresis prevents oscillation at threshold boundaries
+ * - Hangover prevents premature exit from active state
+ * - Post-silence suppression prevents the first audible frame from being an onset
+ */
+/**
+ * Configuration for silence-aware gating.
+ */
+type SilenceGateConfig = {
+    /**
+     * Whether gating is enabled. If false, all frames are considered active.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Percentile (0-100) used to estimate the noise floor from frame energies.
+     * Lower values are more conservative (estimate floor from quieter frames).
+     * @default 10
+     */
+    energyPercentile?: number;
+    /**
+     * Margin above noise floor (in the same units as frame energy) to enter active state.
+     * For log-scale energies (mel), this is effectively dB.
+     * @default 6 (approximately 6 dB above floor for mel-based energy)
+     */
+    enterMargin?: number;
+    /**
+     * Margin above noise floor to remain in active state.
+     * Must be less than enterMargin for proper hysteresis.
+     * @default 3 (approximately 3 dB above floor)
+     */
+    exitMargin?: number;
+    /**
+     * Duration in milliseconds to remain active after energy drops below exit threshold.
+     * Prevents premature exit during brief dips.
+     * @default 50
+     */
+    hangoverMs?: number;
+    /**
+     * Minimum duration in milliseconds a region must be active before allowing onsets.
+     * @default 0
+     */
+    minActiveMs?: number;
+    /**
+     * Duration in milliseconds after transitioning from inactive to active
+     * during which onsets are suppressed.
+     * Prevents the first audible frame from being detected as an onset.
+     * @default 50
+     */
+    postSilenceSuppressMs?: number;
+};
+/**
+ * Configuration for bin-level gating (CPU paths only).
+ * Ignores bins whose energy is below a relative floor.
+ */
+type BinGateConfig = {
+    /**
+     * Whether bin-level gating is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Relative floor as a fraction of frame energy.
+     * Bins with value < frameEnergy * binFloorRel are ignored.
+     * @default 0.05
+     */
+    binFloorRel?: number;
+};
+/**
+ * Result of silence gating analysis.
+ * Useful for debugging and visualization.
+ */
+type SilenceGateResult = {
+    /** Per-frame energy values used for gating. */
+    frameEnergy: Float32Array;
+    /** Estimated noise floor value. */
+    noiseFloor: number;
+    /** Threshold for entering active state. */
+    enterThreshold: number;
+    /** Threshold for exiting active state. */
+    exitThreshold: number;
+    /** Per-frame activity mask (true = active). */
+    activityMask: Uint8Array;
+    /** Per-frame onset suppression mask (true = suppress onset). */
+    suppressionMask: Uint8Array;
+};
+/**
+ * Merge user config with defaults.
+ */
+declare function withSilenceGateDefaults(config?: SilenceGateConfig): Required<SilenceGateConfig>;
+/**
+ * Merge user config with defaults for bin gating.
+ */
+declare function withBinGateDefaults(config?: BinGateConfig): Required<BinGateConfig>;
+/**
+ * Compute per-frame energy from mel spectrogram.
+ *
+ * Since mel bands are already log10(eps + energy), we compute the mean
+ * of the log-energy values. This gives us a perceptually-relevant
+ * frame energy proxy in log space.
+ *
+ * @param melBands - Array of frames, each containing mel band values (log10 scale)
+ * @returns Per-frame energy values (log scale)
+ */
+declare function computeFrameEnergyFromMel(melBands: Float32Array[]): Float32Array;
+/**
+ * Compute per-frame energy from linear magnitude spectrogram.
+ *
+ * Uses mean magnitude (or power) across bins as the energy proxy.
+ *
+ * @param magnitudes - Array of frames, each containing magnitude values (linear scale)
+ * @param usePower - If true, use sum of squared magnitudes (power). Default: false (RMS-like).
+ * @returns Per-frame energy values (linear scale)
+ */
+declare function computeFrameEnergyFromSpectrogram(magnitudes: Float32Array[], usePower?: boolean): Float32Array;
+/**
+ * Estimate adaptive noise floor from frame energies.
+ *
+ * Uses a robust percentile-based estimation rather than absolute thresholds.
+ *
+ * @param frameEnergy - Per-frame energy values
+ * @param percentile - Percentile to use for floor estimation (0-100)
+ * @returns Estimated noise floor
+ */
+declare function estimateNoiseFloor(frameEnergy: Float32Array, percentile: number): number;
+/**
+ * Build activity mask with hysteresis and hangover.
+ *
+ * State machine:
+ * - INACTIVE: energy < enterThreshold -> stay inactive
+ * - INACTIVE: energy >= enterThreshold -> enter ACTIVE
+ * - ACTIVE: energy >= exitThreshold -> stay active, reset hangover counter
+ * - ACTIVE: energy < exitThreshold -> decrement hangover counter
+ * - ACTIVE: hangover counter exhausted -> enter INACTIVE
+ *
+ * @param frameEnergy - Per-frame energy values
+ * @param enterThreshold - Threshold to enter active state
+ * @param exitThreshold - Threshold to remain in active state
+ * @param hangoverFrames - Number of frames to remain active after dropping below exit threshold
+ * @returns Activity mask (1 = active, 0 = inactive)
+ */
+declare function buildActivityMask(frameEnergy: Float32Array, enterThreshold: number, exitThreshold: number, hangoverFrames: number): Uint8Array;
+/**
+ * Full silence gating analysis.
+ *
+ * Computes frame energy, noise floor, thresholds, activity mask, and suppression mask.
+ *
+ * @param frameEnergy - Per-frame energy values
+ * @param frameDurationSec - Duration of one frame in seconds
+ * @param config - Silence gate configuration
+ * @returns Complete gating result including all intermediate values
+ */
+declare function computeSilenceGating(frameEnergy: Float32Array, frameDurationSec: number, config?: SilenceGateConfig): SilenceGateResult;
+
 type OnsetEnvelope = {
     times: Float32Array;
     values: Float32Array;
 };
+/**
+ * Extended onset envelope result with optional debugging info.
+ */
+type OnsetEnvelopeResult = OnsetEnvelope & {
+    /**
+     * Optional silence gating diagnostics.
+     * Present when silenceGate.enabled is true and returnDiagnostics is true.
+     */
+    diagnostics?: OnsetDiagnostics;
+};
+/**
+ * Diagnostics for inspecting onset detection behavior.
+ */
+type OnsetDiagnostics = {
+    /** Per-frame energy used for gating. */
+    frameEnergy: Float32Array;
+    /** Estimated noise floor. */
+    noiseFloor: number;
+    /** Threshold for entering active state. */
+    enterThreshold: number;
+    /** Threshold for exiting active state. */
+    exitThreshold: number;
+    /** Per-frame activity mask (1 = active, 0 = inactive). */
+    activityMask: Uint8Array;
+    /** Per-frame suppression mask (1 = suppressed, 0 = allowed). */
+    suppressionMask: Uint8Array;
+    /** Raw onset novelty before gating was applied. */
+    rawNovelty: Float32Array;
+};
 type OnsetEnvelopeOptions = {
     /** If true, log-compress magnitudes/energies before differencing. */
     useLog?: boolean;
@@ -52,45 +499,1032 @@ type OnsetEnvelopeOptions = {
     smoothMs?: number;
     /** How to convert temporal differences into novelty. */
     diffMethod?: "rectified" | "abs";
+    /**
+     * Silence-aware gating configuration.
+     * Suppresses false onsets in silence or near-silence regions.
+     * @default { enabled: true }
+     */
+    silenceGate?: SilenceGateConfig;
+    /**
+     * Bin-level gating configuration (CPU paths only).
+     * Ignores bins with energy below a relative threshold.
+     * @default { enabled: true }
+     */
+    binGate?: BinGateConfig;
+    /**
+     * If true, include diagnostics in the result for debugging.
+     * @default false
+     */
+    returnDiagnostics?: boolean;
 };
-declare function onsetEnvelopeFromSpectrogram(spec: Spectrogram, options?: OnsetEnvelopeOptions): OnsetEnvelope;
-declare function onsetEnvelopeFromMel(mel: MelSpectrogram, options?: OnsetEnvelopeOptions): OnsetEnvelope;
+/**
+ * Compute onset envelope from spectrogram with silence-aware gating.
+ *
+ * The pipeline:
+ * 1. Compute per-frame spectral flux (novelty)
+ * 2. Compute per-frame energy from magnitudes
+ * 3. Build activity mask using adaptive noise floor + hysteresis
+ * 4. Apply silence gating and post-silence suppression
+ * 5. Apply optional smoothing
+ */
+declare function onsetEnvelopeFromSpectrogram(spec: Spectrogram, options?: OnsetEnvelopeOptions): OnsetEnvelopeResult;
+/**
+ * Compute onset envelope from mel spectrogram with silence-aware gating.
+ *
+ * The pipeline:
+ * 1. Compute per-frame mel flux (novelty)
+ * 2. Compute per-frame energy from mel bands (already log scale)
+ * 3. Build activity mask using adaptive noise floor + hysteresis
+ * 4. Apply silence gating and post-silence suppression
+ * 5. Apply optional smoothing
+ */
+declare function onsetEnvelopeFromMel(mel: MelSpectrogram, options?: OnsetEnvelopeOptions): OnsetEnvelopeResult;
 type OnsetEnvelopeGpuResult = {
     times: Float32Array;
     values: Float32Array;
     gpuTimings: {
         gpuSubmitToReadbackMs: number;
     };
+    /** Optional silence gating diagnostics. */
+    diagnostics?: OnsetDiagnostics;
+};
+/**
+ * GPU-accelerated onset envelope from mel spectrogram with silence-aware gating.
+ *
+ * Notes:
+ * - GPU kernel handles diff+reduction only (keeps WGSL simple)
+ * - Silence gating is applied on CPU after GPU readback
+ * - CPU and GPU paths produce comparable results
+ * - Callers should fall back to CPU on errors
+ */
+declare function onsetEnvelopeFromMelGpu(mel: MelSpectrogram, gpu: MirGPU, options?: Pick<OnsetEnvelopeOptions, "diffMethod" | "silenceGate" | "returnDiagnostics" | "smoothMs">): Promise<OnsetEnvelopeGpuResult>;
+
+type PeakPickEvent = {
+    time: number;
+    strength: number;
+    index: number;
+};
+type PeakPickOptions = {
+    /** Minimum peak height (absolute). */
+    threshold?: number;
+    /** Minimum inter-peak interval (seconds). */
+    minIntervalSec?: number;
+    /** If provided, use adaptive threshold: mean(values) + factor*std(values). */
+    adaptive?: {
+        method?: "meanStd" | "median";
+        factor?: number;
+    };
+    /** If true, prefer strict maxima (> neighbors); else allow flat plateaus. */
+    strict?: boolean;
+};
+declare function peakPick(times: Float32Array, values: Float32Array, options?: PeakPickOptions): PeakPickEvent[];
+
+/**
+ * Configuration for beat candidate detection.
+ */
+type BeatCandidatesOptions = {
+    /** Minimum inter-candidate interval in seconds. Default: 0.1 (100ms). */
+    minIntervalSec?: number;
+    /** Threshold factor for adaptive peak detection. Lower = more candidates. Default: 0.5. */
+    thresholdFactor?: number;
+    /** Smoothing window for salience signal in ms. Default: 50. */
+    smoothMs?: number;
+};
+/**
+ * Result of beat candidate detection.
+ */
+type BeatCandidatesOutput = {
+    candidates: BeatCandidate[];
+    /** The computed salience signal (for debugging/visualization). */
+    salience: {
+        times: Float32Array;
+        values: Float32Array;
+    };
+};
+/**
+ * Compute a beat-oriented salience signal from mel spectrogram.
+ *
+ * This combines:
+ * - Onset envelope (captures transients/attacks)
+ * - Spectral flux from the underlying spectrogram (captures spectral change)
+ *
+ * The signals are normalized and combined to produce a single salience curve
+ * suitable for peak picking.
+ *
+ * Key design choices:
+ * - Whole-track normalization (z-score) for consistent behavior
+ * - Gentle smoothing to suppress micro-transients while preserving beat structure
+ * - No BPM inference or grid assumptions
+ */
+type BeatSalienceSignal = {
+    times: Float32Array;
+    values: Float32Array;
+};
+/**
+ * Compute beat salience signal from mel spectrogram.
+ *
+ * This is an intermediate signal suitable for peak picking to extract
+ * beat candidates. It combines onset envelope with additional smoothing
+ * tuned for beat-like (rather than onset-like) detection.
+ */
+declare function beatSalienceFromMel(mel: MelSpectrogram, spec: Spectrogram, options?: {
+    smoothMs?: number;
+}): BeatSalienceSignal;
+/**
+ * Detect beat candidates from mel spectrogram and spectrogram.
+ *
+ * This is the main entry point for beat candidate detection.
+ *
+ * Design principles:
+ * - Dense candidates (err on side of too many)
+ * - No BPM inference
+ * - No grid assumptions
+ * - Whole-track normalization for consistency
+ * - Deterministic (same input -> same output)
+ */
+declare function detectBeatCandidates(mel: MelSpectrogram, spec: Spectrogram, options?: BeatCandidatesOptions): BeatCandidatesOutput;
+
+/**
+ * Configuration for tempo hypothesis generation.
+ */
+type TempoHypothesesOptions = {
+    /** Minimum BPM to consider. Default: 24. */
+    minBpm?: number;
+    /** Maximum BPM to consider. Default: 300. */
+    maxBpm?: number;
+    /** Histogram bin size in BPM. Default: 1.0. */
+    binSizeBpm?: number;
+    /** Maximum hypotheses to return. Default: 10. */
+    maxHypotheses?: number;
+    /** Minimum confidence threshold (0-1). Default: 0.05. */
+    minConfidence?: number;
+    /** Weight IOIs by candidate strength. Default: true. */
+    weightByStrength?: boolean;
+    /** Include histogram data in output. Default: false. */
+    includeHistogram?: boolean;
+};
+type TempoHypothesesOutput = {
+    hypotheses: TempoHypothesis[];
+    inputCandidateCount: number;
+    histogram?: {
+        bpmBins: Float32Array;
+        counts: Float32Array;
+    };
 };
 /**
- * GPU-accelerated onset envelope from mel spectrogram.
+ * Generate tempo hypotheses from beat candidates.
+ *
+ * Algorithm:
+ * 1. Compute inter-onset intervals (IOIs) from beat candidates
+ * 2. Filter IOIs to musically plausible range (0.2s-2.5s -> 24-300 BPM)
+ * 3. Build weighted histogram with configurable bin size
+ * 4. Extract peaks as tempo candidates
+ * 5. Refine BPM estimates using weighted centroid
+ * 6. Group into harmonic families
+ * 7. Normalize confidence scores
+ *
+ * @param candidates - Beat candidates from B1
+ * @param options - Configuration options
+ * @returns Tempo hypotheses with confidence and family groupings
+ */
+declare function generateTempoHypotheses(candidates: BeatCandidate[], options?: TempoHypothesesOptions): TempoHypothesesOutput;
+
+/**
+ * Phase alignment algorithm for beat grid generation.
+ *
+ * Given a BPM and beat candidates, this module computes optimal phase offsets
+ * that align the beat grid with detected beat candidates.
+ *
+ * The algorithm is deterministic: same inputs always produce same outputs.
+ */
+
+/**
+ * Compute phase hypotheses for a given BPM against beat candidates.
+ *
+ * Algorithm:
+ * 1. Compute beat period = 60 / bpm
+ * 2. Generate N phase offsets spanning [0, period) at resolution = period/N
+ * 3. For each phase offset:
+ *    a. For each beat candidate, find closest grid line
+ *    b. If within tolerance, add weighted score based on candidate strength
+ *    c. Track systematic offset error for penalty
+ * 4. Normalize scores and apply offset penalty
+ * 5. Return top K phases sorted by score
+ *
+ * @param bpm - Tempo in beats per minute
+ * @param candidates - Beat candidate events with time and strength
+ * @param audioDuration - Total audio duration in seconds
+ * @param config - Optional configuration overrides
+ * @returns Array of top K phase hypotheses, sorted by score descending
+ */
+declare function computePhaseHypotheses(bpm: number, candidates: BeatCandidate[], audioDuration: number, config?: PhaseAlignmentConfig): PhaseHypothesis[];
+/**
+ * Generate beat times for a given grid within the audio duration.
+ *
+ * @param bpm - Tempo in beats per minute
+ * @param phaseOffset - Base phase offset in seconds
+ * @param userNudge - User adjustment in seconds (additive)
+ * @param audioDuration - Total audio duration in seconds
+ * @returns Array of beat times in seconds
+ */
+declare function generateBeatTimes(bpm: number, phaseOffset: number, userNudge: number, audioDuration: number): number[];
+
+/**
+ * Peak Picking Algorithm
+ *
+ * Detects local maxima in a 1D signal that exceed a threshold.
+ * Used to create event streams from continuous signals.
+ */
+interface PeakPickingParams {
+    /** Minimum normalized value (0-1) for a peak to be considered. Default: 0.3 */
+    threshold: number;
+    /** Minimum time between peaks in seconds. Default: 0.1 */
+    minDistance: number;
+    /** Number of samples to look back for local max comparison. Default: 2 */
+    preMax?: number;
+    /** Number of samples to look forward for local max comparison. Default: 2 */
+    postMax?: number;
+}
+interface PeakPickingResult {
+    /** Times of detected peaks (seconds) */
+    times: Float32Array;
+    /** Normalized strength of each peak (0-1, based on normalized value) */
+    strengths: Float32Array;
+}
+/**
+ * Default peak picking parameters
+ */
+declare const DEFAULT_PEAK_PICKING_PARAMS: Required<PeakPickingParams>;
+/**
+ * Pick peaks from a continuous signal.
+ *
+ * @param times - Time values in seconds (Float32Array)
+ * @param values - Signal values (Float32Array)
+ * @param params - Peak picking parameters
+ * @returns Detected peaks with times and strengths
+ */
+declare function pickPeaks(times: Float32Array, values: Float32Array, params?: Partial<PeakPickingParams>): PeakPickingResult;
+/**
+ * Result from adaptive peak picking, including the threshold curve for visualization.
+ */
+interface AdaptivePeakPickingResult extends PeakPickingResult {
+    /** The adaptive threshold curve (normalized 0-1) for visualization */
+    thresholdCurve: Float32Array;
+    /** Time values corresponding to threshold curve samples */
+    thresholdTimes: Float32Array;
+}
+/**
+ * Compute the adaptive threshold curve for visualization.
+ * This is the normalized threshold that would be used by pickPeaksAdaptive.
+ *
+ * @param values - Signal values (Float32Array)
+ * @param windowSize - Window size for local statistics (in samples)
+ * @param thresholdMultiplier - Multiplier for local std (default 1.5)
+ * @returns Normalized threshold curve (0-1 range)
+ */
+declare function computeAdaptiveThreshold(values: Float32Array, windowSize?: number, thresholdMultiplier?: number): Float32Array;
+/**
+ * Pick peaks with adaptive threshold based on local statistics.
+ *
+ * @param times - Time values in seconds
+ * @param values - Signal values
+ * @param windowSize - Window size for local statistics (in samples)
+ * @param params - Base peak picking parameters (threshold used as multiplier of local std)
+ * @param includeThresholdCurve - If true, returns the threshold curve for visualization
+ */
+declare function pickPeaksAdaptive(times: Float32Array, values: Float32Array, windowSize?: number, params?: Partial<PeakPickingParams>, includeThresholdCurve?: boolean): PeakPickingResult | AdaptivePeakPickingResult;
+/**
+ * Hysteresis gate parameters for peak filtering.
+ */
+interface HysteresisGateParams {
+    /** Upper threshold (0-1) - signal must exceed this to trigger "on" state */
+    onThreshold: number;
+    /** Lower threshold (0-1) - signal must fall below this to trigger "off" state */
+    offThreshold: number;
+    /** Minimum time between peaks in seconds */
+    minDistance: number;
+}
+/**
+ * Apply hysteresis gating to peaks.
+ * Peaks are only kept if the signal has dropped below offThreshold since the last peak.
+ * This prevents multiple triggers during sustained high-value regions.
+ *
+ * @param times - Time values of the original signal
+ * @param values - Values of the original signal (for checking hysteresis)
+ * @param peakTimes - Times of detected peaks
+ * @param peakStrengths - Strengths of detected peaks
+ * @param params - Hysteresis gate parameters
+ * @returns Filtered peaks after hysteresis gating
+ */
+declare function applyHysteresisGate(times: Float32Array, values: Float32Array, peakTimes: Float32Array, peakStrengths: Float32Array, params: HysteresisGateParams): PeakPickingResult;
+
+/**
+ * Musical Time utilities for B4.
+ *
+ * These functions compute derived values from musical time structures.
+ * All computations are deterministic and pure.
+ */
+
+/**
+ * Find the segment containing a given time.
+ * Segments are non-overlapping, so at most one segment contains any time.
+ *
+ * @param time - Time in seconds from track start
+ * @param segments - Ordered list of segments (by startTime ascending)
+ * @returns The containing segment, or null if time is outside all segments
+ */
+declare function findSegmentAtTime(time: number, segments: MusicalTimeSegment[]): MusicalTimeSegment | null;
+/**
+ * Compute the beat position at a given time.
+ *
+ * Beat position formula:
+ *   period = 60 / bpm
+ *   beatsFromStart = (time - phaseOffset) / period
+ *   beatIndex = floor(beatsFromStart)
+ *   beatPhase = beatsFromStart - beatIndex (fractional part, 0-1)
+ *   beatPosition = beatsFromStart (continuous)
+ *
+ * @param time - Time in seconds from track start
+ * @param segments - Ordered list of segments (by startTime ascending)
+ * @returns BeatPosition if time is within a segment, null otherwise
+ */
+declare function computeBeatPosition(time: number, segments: MusicalTimeSegment[]): BeatPosition | null;
+/**
+ * Compute beat position from a MusicalTimeStructure.
+ * Convenience wrapper for computeBeatPosition.
+ */
+declare function computeBeatPositionFromStructure(time: number, structure: MusicalTimeStructure | null): BeatPosition | null;
+/**
+ * Generate a unique segment ID.
+ */
+declare function generateSegmentId(): string;
+/**
+ * Create a new MusicalTimeSegment from a BeatGrid.
+ *
+ * @param grid - The beat grid to promote
+ * @param startTime - Segment start boundary in seconds
+ * @param endTime - Segment end boundary in seconds
+ * @returns A new MusicalTimeSegment
+ */
+declare function createSegmentFromGrid(grid: BeatGrid, startTime: number, endTime: number): MusicalTimeSegment;
+/**
+ * Create a new empty MusicalTimeStructure.
+ */
+declare function createMusicalTimeStructure(): MusicalTimeStructure;
+/**
+ * Validate that segments are non-overlapping and ordered.
+ *
+ * @param segments - List of segments to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+declare function validateSegments(segments: MusicalTimeSegment[]): string[];
+/**
+ * Sort segments by startTime ascending.
+ * Returns a new array (does not mutate input).
+ */
+declare function sortSegments(segments: MusicalTimeSegment[]): MusicalTimeSegment[];
+/**
+ * Split a segment at a given time.
+ *
+ * @param segment - The segment to split
+ * @param splitTime - Time in seconds where to split
+ * @returns Tuple of [beforeSegment, afterSegment]
+ * @throws If splitTime is outside segment bounds
+ */
+declare function splitSegment(segment: MusicalTimeSegment, splitTime: number): [MusicalTimeSegment, MusicalTimeSegment];
+/**
+ * Generate beat times within a segment.
+ * Used for rendering beat markers.
+ *
+ * @param segment - The segment to generate beats for
+ * @returns Array of beat times in seconds
+ */
+declare function generateSegmentBeatTimes(segment: MusicalTimeSegment): number[];
+
+/**
+ * Frequency Band utilities for F1.
+ *
+ * These functions provide validation, creation, and query operations
+ * for frequency band structures. All computations are deterministic and pure.
+ */
+
+/**
+ * Generate a unique band ID.
+ */
+declare function generateBandId(): string;
+/**
+ * Validate frequency segments for a band.
+ *
+ * Checks:
+ * - lowHz < highHz at all segment boundaries
+ * - All frequency values are non-negative
+ * - startTime < endTime for each segment
+ * - Segments don't overlap in time
+ * - Segments are ordered by startTime
+ *
+ * @param segments - Frequency segments to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+declare function validateFrequencySegments(segments: FrequencySegment[]): string[];
+/**
+ * Validate a frequency band.
+ *
+ * @param band - Frequency band to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+declare function validateFrequencyBand(band: FrequencyBand): string[];
+/**
+ * Validate a complete frequency band structure.
+ *
+ * @param structure - Structure to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+declare function validateBandStructure(structure: FrequencyBandStructure): string[];
+/**
+ * Create an empty FrequencyBandStructure.
+ */
+declare function createBandStructure(): FrequencyBandStructure;
+/**
+ * Create a simple constant-frequency band (no time variation).
+ *
+ * @param label - Human-readable band label
+ * @param lowHz - Lower frequency bound in Hz
+ * @param highHz - Upper frequency bound in Hz
+ * @param duration - Duration in seconds (defines segment end time)
+ * @param options - Optional configuration
+ * @returns A new FrequencyBand
+ */
+declare function createConstantBand(label: string, lowHz: number, highHz: number, duration: number, options?: {
+    enabled?: boolean;
+    sortOrder?: number;
+    id?: string;
+    /** The audio source this band belongs to. Defaults to "mixdown". */
+    sourceId?: string;
+}): FrequencyBand;
+/**
+ * Create a sectioned band (applies only to a time range).
+ *
+ * @param label - Human-readable band label
+ * @param lowHz - Lower frequency bound in Hz
+ * @param highHz - Upper frequency bound in Hz
+ * @param startTime - Section start time in seconds
+ * @param endTime - Section end time in seconds
+ * @param options - Optional configuration
+ * @returns A new FrequencyBand
+ */
+declare function createSectionedBand(label: string, lowHz: number, highHz: number, startTime: number, endTime: number, options?: {
+    enabled?: boolean;
+    sortOrder?: number;
+    id?: string;
+    /** The audio source this band belongs to. Defaults to "mixdown". */
+    sourceId?: string;
+}): FrequencyBand;
+/**
+ * Create standard frequency bands for a track.
+ *
+ * Creates a standard 6-band frequency split:
+ * - Sub Bass: 20-60 Hz
+ * - Bass: 60-250 Hz
+ * - Low Mids: 250-500 Hz
+ * - Mids: 500-2000 Hz
+ * - High Mids: 2000-4000 Hz
+ * - Highs: 4000-20000 Hz
+ *
+ * @param duration - Track duration in seconds
+ * @param sourceId - The audio source these bands belong to. Defaults to "mixdown".
+ * @returns Array of FrequencyBand objects
+ */
+declare function createStandardBands(duration: number, sourceId?: string): FrequencyBand[];
+/**
+ * Get all bands active at a given time.
+ *
+ * A band is active if:
+ * - It is enabled
+ * - The time falls within its time scope
+ *
+ * @param structure - Frequency band structure (can be null)
+ * @param time - Time in seconds
+ * @param sourceId - Optional: filter to a specific audio source
+ * @returns Array of active bands
+ */
+declare function bandsActiveAt(structure: FrequencyBandStructure | null, time: number, sourceId?: string): FrequencyBand[];
+/**
+ * Get frequency bounds for a band at a given time.
+ *
+ * Uses linear interpolation within segments.
+ *
+ * @param band - The frequency band to query
+ * @param time - Time in seconds
+ * @returns Frequency bounds if band is active and has defined bounds, null otherwise
+ */
+declare function frequencyBoundsAt(band: FrequencyBand, time: number): FrequencyBoundsAtTime | null;
+/**
+ * Get all frequency bounds at a given time.
+ *
+ * Returns bounds for all active bands that have defined frequency at the given time.
+ *
+ * @param structure - Frequency band structure (can be null)
+ * @param time - Time in seconds
+ * @returns Array of frequency bounds, sorted by sortOrder
+ */
+declare function allFrequencyBoundsAt(structure: FrequencyBandStructure | null, time: number): FrequencyBoundsAtTime[];
+/**
+ * Find a band by its ID.
+ *
+ * @param structure - Frequency band structure (can be null)
+ * @param id - Band ID to find
+ * @returns The band if found, null otherwise
+ */
+declare function findBandById(structure: FrequencyBandStructure | null, id: string): FrequencyBand | null;
+/**
+ * Sort bands by sortOrder.
+ * Returns a new array (does not mutate input).
+ *
+ * @param bands - Bands to sort
+ * @returns New array sorted by sortOrder ascending
+ */
+declare function sortBands(bands: FrequencyBand[]): FrequencyBand[];
+/**
+ * Sort frequency segments by startTime.
+ * Returns a new array (does not mutate input).
+ *
+ * @param segments - Segments to sort
+ * @returns New array sorted by startTime ascending
+ */
+declare function sortFrequencySegments(segments: FrequencySegment[]): FrequencySegment[];
+/**
+ * Update the modifiedAt timestamp of a structure.
+ * Returns a new structure (does not mutate input).
+ *
+ * @param structure - Structure to update
+ * @returns New structure with updated modifiedAt
+ */
+declare function touchStructure(structure: FrequencyBandStructure): FrequencyBandStructure;
+/**
+ * Add a band to a structure.
+ * Returns a new structure (does not mutate input).
+ *
+ * @param structure - Structure to add to
+ * @param band - Band to add
+ * @returns New structure with the band added
+ */
+declare function addBandToStructure(structure: FrequencyBandStructure, band: FrequencyBand): FrequencyBandStructure;
+/**
+ * Remove a band from a structure by ID.
+ * Returns a new structure (does not mutate input).
+ *
+ * @param structure - Structure to remove from
+ * @param bandId - ID of band to remove
+ * @returns New structure with the band removed
+ */
+declare function removeBandFromStructure(structure: FrequencyBandStructure, bandId: string): FrequencyBandStructure;
+/**
+ * Update a band in a structure.
+ * Returns a new structure (does not mutate input).
+ *
+ * @param structure - Structure containing the band
+ * @param bandId - ID of band to update
+ * @param updates - Partial band updates to apply
+ * @returns New structure with the band updated
+ */
+declare function updateBandInStructure(structure: FrequencyBandStructure, bandId: string, updates: Partial<Omit<FrequencyBand, "id">>): FrequencyBandStructure;
+/**
+ * Extract keyframes from a band's frequency shape.
+ *
+ * Keyframes are a UI abstraction over the segment model.
+ * Each segment has a start keyframe and an end keyframe.
+ * Adjacent segments share keyframes at their boundaries.
+ *
+ * @param band - The frequency band to extract keyframes from
+ * @returns Array of keyframes sorted by time
+ */
+declare function keyframesFromBand(band: FrequencyBand): FrequencyKeyframe[];
+/**
+ * Convert keyframes back to frequency segments.
+ *
+ * Consecutive keyframes become segment boundaries.
+ * This is the inverse of keyframesFromBand.
+ *
+ * @param keyframes - Array of keyframes (must be sorted by time)
+ * @returns Array of frequency segments
+ */
+declare function segmentsFromKeyframes(keyframes: FrequencyKeyframe[]): FrequencySegment[];
+/**
+ * Split a band's segment at a given time, creating a new keyframe.
+ *
+ * The frequency values at the split point are interpolated from the
+ * existing segment. Returns a new band with updated frequencyShape.
+ *
+ * @param band - The band to split
+ * @param time - Time in seconds to split at
+ * @returns New band with the split segment, or original band if time is invalid
+ */
+declare function splitBandSegmentAt(band: FrequencyBand, time: number): FrequencyBand;
+/**
+ * Merge adjacent segments where frequencies match at the boundary.
+ *
+ * This is useful after deleting a keyframe to clean up redundant segments.
+ *
+ * @param band - The band to merge segments in
+ * @param tolerance - Frequency tolerance for considering values equal (default 0.1 Hz)
+ * @returns New band with merged segments
+ */
+declare function mergeAdjacentSegments(band: FrequencyBand, tolerance?: number): FrequencyBand;
+/**
+ * Remove a keyframe from a band.
+ *
+ * This merges the two adjacent segments into one.
+ * Cannot remove first or last keyframe (would make band invalid).
+ *
+ * @param band - The band to modify
+ * @param time - Time of the keyframe to remove
+ * @returns New band with keyframe removed, or original if removal is invalid
+ */
+declare function removeKeyframe(band: FrequencyBand, time: number): FrequencyBand;
+/**
+ * Update a keyframe's frequency values.
+ *
+ * This updates the corresponding segment boundary.
+ *
+ * @param band - The band to modify
+ * @param time - Time of the keyframe to update
+ * @param lowHz - New lower frequency (or undefined to keep current)
+ * @param highHz - New upper frequency (or undefined to keep current)
+ * @returns New band with updated keyframe
+ */
+declare function updateKeyframe(band: FrequencyBand, time: number, lowHz?: number, highHz?: number): FrequencyBand;
+/**
+ * Move a keyframe in time.
+ *
+ * Updates the endTime of the segment before and startTime of the segment after.
+ * Cannot move first or last keyframe.
+ *
+ * @param band - The band to modify
+ * @param oldTime - Current time of the keyframe
+ * @param newTime - New time for the keyframe
+ * @returns New band with moved keyframe, or original if move is invalid
+ */
+declare function moveKeyframeTime(band: FrequencyBand, oldTime: number, newTime: number): FrequencyBand;
+
+/**
+ * Band Masking utilities for F3.
+ *
+ * These functions apply frequency band boundaries as spectral masks
+ * to an existing spectrogram, enabling per-band MIR analysis.
+ */
+
+type BandMaskOptions = {
+    /** Soft edge width in Hz for smooth transitions (0 = hard edge). Default: 0 */
+    edgeSmoothHz?: number;
+};
+type MaskedSpectrogram = Spectrogram & {
+    /** ID of the band this mask was computed for */
+    bandId: string;
+    /** Fraction of energy retained per frame (0-1) for diagnostics */
+    energyRetainedPerFrame: Float32Array;
+};
+/**
+ * Convert an FFT bin index to frequency in Hz.
+ *
+ * @param bin - FFT bin index (0 to fftSize/2)
+ * @param sampleRate - Audio sample rate in Hz
+ * @param fftSize - FFT size (number of samples)
+ * @returns Frequency in Hz
+ */
+declare function binToHz(bin: number, sampleRate: number, fftSize: number): number;
+/**
+ * Convert a frequency in Hz to an FFT bin index.
+ *
+ * @param hz - Frequency in Hz
+ * @param sampleRate - Audio sample rate in Hz
+ * @param fftSize - FFT size (number of samples)
+ * @returns FFT bin index (may be fractional)
+ */
+declare function hzToBin(hz: number, sampleRate: number, fftSize: number): number;
+/**
+ * Compute a spectral mask for a band at a specific time.
+ *
+ * Returns a Float32Array of length (fftSize/2 + 1) containing
+ * mask values between 0 and 1.
+ *
+ * @param band - The frequency band to mask
+ * @param time - Time in seconds
+ * @param sampleRate - Audio sample rate in Hz
+ * @param fftSize - FFT size
+ * @param options - Mask options
+ * @returns Mask array, or null if band is inactive at this time
+ */
+declare function computeBandMaskAtTime(band: FrequencyBand, time: number, sampleRate: number, fftSize: number, options?: BandMaskOptions): Float32Array | null;
+/**
+ * Apply a band mask to an entire spectrogram.
+ *
+ * Creates a new spectrogram with band-masked magnitudes.
+ * Uses linear interpolation of band bounds for time-varying bands.
+ *
+ * @param spec - Source spectrogram
+ * @param band - Frequency band to apply
+ * @param options - Mask options
+ * @returns Masked spectrogram with energy retention diagnostics
+ */
+declare function applyBandMaskToSpectrogram(spec: Spectrogram, band: FrequencyBand, options?: BandMaskOptions): MaskedSpectrogram;
+/**
+ * Compute the energy of a magnitude spectrum.
+ *
+ * @param magnitudes - Magnitude spectrum (one frame)
+ * @returns Sum of squared magnitudes
+ */
+declare function computeFrameEnergy(magnitudes: Float32Array): number;
+/**
+ * Compute the amplitude (sum of magnitudes) of a frame.
+ *
+ * @param magnitudes - Magnitude spectrum (one frame)
+ * @returns Sum of magnitudes
+ */
+declare function computeFrameAmplitude(magnitudes: Float32Array): number;
+
+/**
+ * Band-Scoped MIR utilities for F3.
+ *
+ * These functions compute MIR features (amplitude envelope, onset strength,
+ * spectral flux) for frequency bands by applying spectral masks to an
+ * existing spectrogram.
+ */
+
+type BandMirOptions = {
+    /** Soft edge width in Hz for mask transitions. Default: 0 */
+    edgeSmoothHz?: number;
+    /** Options for onset strength computation */
+    onset?: {
+        /** If true, log-compress magnitudes before differencing. */
+        useLog?: boolean;
+        /** Moving-average smoothing window length in milliseconds. 0 disables smoothing. */
+        smoothMs?: number;
+        /** How to convert temporal differences into novelty. */
+        diffMethod?: "rectified" | "abs";
+    };
+    /** Optional cancellation hook */
+    isCancelled?: () => boolean;
+};
+/**
+ * Compute amplitude envelope for a frequency band.
+ *
+ * Returns the sum of magnitudes per frame within the band's frequency range.
+ *
+ * @param spec - Source spectrogram
+ * @param band - Frequency band to analyze
+ * @param options - Computation options
+ * @returns Band MIR result with amplitude envelope
+ */
+declare function bandAmplitudeEnvelope(spec: Spectrogram, band: FrequencyBand, options?: BandMirOptions): BandMir1DResult;
+/**
+ * Compute onset strength for a frequency band.
+ *
+ * Uses temporal differences of band-masked magnitudes.
+ * Adapted from onset.ts:onsetEnvelopeFromSpectrogram.
+ *
+ * @param spec - Source spectrogram
+ * @param band - Frequency band to analyze
+ * @param options - Computation options
+ * @returns Band MIR result with onset strength
+ */
+declare function bandOnsetStrength(spec: Spectrogram, band: FrequencyBand, options?: BandMirOptions): BandMir1DResult;
+/**
+ * Compute spectral flux for a frequency band.
+ *
+ * Uses L1 distance between consecutive normalized band-masked spectra.
+ * Adapted from spectral.ts:spectralFlux.
+ *
+ * @param spec - Source spectrogram
+ * @param band - Frequency band to analyze
+ * @param options - Computation options
+ * @returns Band MIR result with spectral flux
+ */
+declare function bandSpectralFlux(spec: Spectrogram, band: FrequencyBand, options?: BandMirOptions): BandMir1DResult;
+/**
+ * Compute spectral centroid for a frequency band.
+ *
+ * Returns the weighted average of frequency bins within the band (center of mass).
+ * Output is in Hz per frame.
+ *
+ * @param spec - Source spectrogram
+ * @param band - Frequency band to analyze
+ * @param options - Computation options
+ * @returns Band MIR result with spectral centroid in Hz
+ */
+declare function bandSpectralCentroid(spec: Spectrogram, band: FrequencyBand, options?: BandMirOptions): BandMir1DResult;
+type BandMirBatchRequest = {
+    bands: FrequencyBand[];
+    functions: BandMirFunctionId[];
+    /** Maximum number of bands to process concurrently. Default: 4 */
+    maxConcurrent?: number;
+};
+type BandMirBatchResult = {
+    /** Results keyed by bandId, each containing results for requested functions */
+    results: Map<string, BandMir1DResult[]>;
+    /** Total computation time in ms */
+    totalTimingMs: number;
+};
+/**
+ * Run band MIR analysis for multiple bands.
+ *
+ * Processes bands sequentially (web workers don't have real parallelism
+ * within a single thread). The maxConcurrent option is reserved for
+ * future multi-worker support.
+ *
+ * @param spec - Source spectrogram
+ * @param request - Batch request specifying bands and functions
+ * @param options - Computation options
+ * @returns Map of results by band ID
+ */
+declare function runBandMirBatch(spec: Spectrogram, request: BandMirBatchRequest, options?: BandMirOptions): Promise<BandMirBatchResult>;
+/**
+ * Get a human-readable label for a band MIR function.
+ *
+ * @param fn - Band MIR function ID
+ * @returns Human-readable label
+ */
+declare function getBandMirFunctionLabel(fn: BandMirFunctionId): string;
+
+/**
+ * Band Event Extraction for F3.
+ *
+ * These functions extract discrete events (onset peaks, beat candidates)
+ * from band-scoped 1D signals.
+ */
+
+type BandOnsetPeaksOptions = {
+    /** Minimum inter-peak interval in seconds. Default: 0.0625 (~0.125 beats at 120 BPM). */
+    minIntervalSec?: number;
+    /** Adaptive threshold factor. Default: 0.8 (conservative for bands). */
+    adaptiveFactor?: number;
+    /** Use strict peak detection (> neighbors). Default: true. */
+    strict?: boolean;
+};
+type BandBeatCandidatesOptions = {
+    /** Minimum inter-candidate interval in seconds. Default: 0.1. */
+    minIntervalSec?: number;
+    /** Threshold factor for adaptive detection. Lower = more candidates. Default: 0.5. */
+    thresholdFactor?: number;
+};
+/**
+ * Extract onset peaks from a band MIR 1D signal.
+ *
+ * Uses peak picking with conservative defaults optimized for band-scoped
+ * extraction. Typically applied to bandOnsetStrength or bandAmplitudeEnvelope.
+ *
+ * @param signal - The band MIR 1D result to extract peaks from
+ * @param options - Peak picking options
+ * @returns Band events result with onset peaks
+ */
+declare function bandOnsetPeaks(signal: BandMir1DResult, options?: BandOnsetPeaksOptions): BandEventsResult;
+/**
+ * Extract beat candidates from a band's onset peaks.
+ *
+ * Similar to full-track beat candidate detection but simplified for
+ * single-band input. Uses the onset peaks to identify beat-like events.
+ *
+ * @param onsetPeaks - Band onset peaks result
+ * @param options - Beat candidate options
+ * @returns Band events result with beat candidates
+ */
+declare function bandBeatCandidates(onsetPeaks: BandEventsResult, options?: BandBeatCandidatesOptions): BandEventsResult;
+type BandEventsBatchRequest = {
+    /** Band MIR results to extract events from (keyed by bandId) */
+    bandMirResults: Map<string, BandMir1DResult[]>;
+    /** Event functions to run */
+    functions: BandEventFunctionId[];
+    /** Source signal function to use for onset peaks. Default: bandOnsetStrength */
+    sourceFunction?: "bandOnsetStrength" | "bandAmplitudeEnvelope";
+    /** Options for onset peaks extraction */
+    onsetPeaksOptions?: BandOnsetPeaksOptions;
+    /** Options for beat candidates extraction */
+    beatCandidatesOptions?: BandBeatCandidatesOptions;
+};
+type BandEventsBatchResult = {
+    /** Results keyed by bandId, each containing results for requested functions */
+    results: Map<string, BandEventsResult[]>;
+    /** Total computation time in ms */
+    totalTimingMs: number;
+};
+/**
+ * Run band event extraction for multiple bands.
+ *
+ * @param request - Batch request specifying bands, functions, and options
+ * @returns Map of results by band ID
+ */
+declare function runBandEventsBatch(request: BandEventsBatchRequest): Promise<BandEventsBatchResult>;
+/**
+ * Get a human-readable label for a band event function.
+ *
+ * @param fn - Band event function ID
+ * @returns Human-readable label
+ */
+declare function getBandEventFunctionLabel(fn: BandEventFunctionId): string;
+
+/**
+ * Band-Scoped CQT utilities for F3.
+ *
+ * These functions compute CQT-derived features (harmonic energy, bass pitch motion,
+ * tonal stability) for frequency bands by applying spectral masks to a CQT
+ * spectrogram.
+ *
+ * CQT uses log-frequency bins, so band masking requires mapping Hz ranges
+ * to CQT bin indices using hzToCqtBin().
+ */
+
+type BandCqtOptions = {
+    /** Soft edge width in bins for mask transitions. Default: 0 */
+    edgeSmoothBins?: number;
+    /** Optional cancellation hook */
+    isCancelled?: () => boolean;
+};
+type MaskedCqtSpectrogram = {
+    /** Original CQT times */
+    times: Float32Array;
+    /** Masked CQT magnitudes */
+    magnitudes: Float32Array[];
+    /** CQT config */
+    config: CqtConfig;
+    /** Energy retained per frame (0-1) */
+    energyRetainedPerFrame: Float32Array;
+    /** CQT bin frequencies */
+    binFrequencies: Float32Array;
+};
+/**
+ * Apply a frequency band mask to a CQT spectrogram.
+ *
+ * Maps the band's Hz range to CQT bin indices and masks accordingly.
+ *
+ * @param cqt - Source CQT spectrogram
+ * @param band - Frequency band to apply
+ * @param options - Masking options
+ * @returns Masked CQT spectrogram with energy retention diagnostics
+ */
+declare function applyBandMaskToCqt(cqt: CqtSpectrogram, band: FrequencyBand, options?: BandCqtOptions): MaskedCqtSpectrogram;
+/**
+ * Compute harmonic energy for a frequency band using CQT.
+ *
+ * Measures the ratio of energy at harmonic intervals within the band.
+ * Adapted from cqtSignals.ts:harmonicEnergy.
+ *
+ * @param cqt - Source CQT spectrogram
+ * @param band - Frequency band to analyze
+ * @param options - Computation options
+ * @returns Band CQT result with harmonic energy
+ */
+declare function bandCqtHarmonicEnergy(cqt: CqtSpectrogram, band: FrequencyBand, options?: BandCqtOptions): BandCqt1DResult;
+/**
+ * Compute bass pitch motion for a frequency band using CQT.
  *
- * Notes:
- * - This bypasses JS loops for the diff+reduction step.
- * - Smoothing/log options are intentionally limited for v0.1 (keeps WGSL simple).
- * - Callers should fall back to CPU on errors.
+ * Measures pitch movement in bass-range CQT bins within the band.
+ * Most meaningful for bands overlapping the bass range (20-300 Hz).
+ *
+ * @param cqt - Source CQT spectrogram
+ * @param band - Frequency band to analyze
+ * @param options - Computation options
+ * @returns Band CQT result with bass pitch motion
  */
-declare function onsetEnvelopeFromMelGpu(mel: MelSpectrogram, gpu: MirGPU, options?: Pick<OnsetEnvelopeOptions, "diffMethod">): Promise<OnsetEnvelopeGpuResult>;
-
-type PeakPickEvent = {
-    time: number;
-    strength: number;
-    index: number;
+declare function bandCqtBassPitchMotion(cqt: CqtSpectrogram, band: FrequencyBand, options?: BandCqtOptions): BandCqt1DResult;
+/**
+ * Compute tonal stability for a frequency band using CQT.
+ *
+ * Measures consistency of chroma distribution over time within the band.
+ * Adapted from cqtSignals.ts:tonalStability.
+ *
+ * @param cqt - Source CQT spectrogram
+ * @param band - Frequency band to analyze
+ * @param options - Computation options
+ * @returns Band CQT result with tonal stability
+ */
+declare function bandCqtTonalStability(cqt: CqtSpectrogram, band: FrequencyBand, options?: BandCqtOptions): BandCqt1DResult;
+type BandCqtBatchRequest = {
+    bands: FrequencyBand[];
+    functions: BandCqtFunctionId[];
+    /** Maximum number of bands to process concurrently. Default: 4 */
+    maxConcurrent?: number;
 };
-type PeakPickOptions = {
-    /** Minimum peak height (absolute). */
-    threshold?: number;
-    /** Minimum inter-peak interval (seconds). */
-    minIntervalSec?: number;
-    /** If provided, use adaptive threshold: mean(values) + factor*std(values). */
-    adaptive?: {
-        method?: "meanStd" | "median";
-        factor?: number;
-    };
-    /** If true, prefer strict maxima (> neighbors); else allow flat plateaus. */
-    strict?: boolean;
+type BandCqtBatchResult = {
+    /** Results keyed by bandId */
+    results: Map<string, BandCqt1DResult[]>;
+    /** Total computation time in ms */
+    totalTimingMs: number;
 };
-declare function peakPick(times: Float32Array, values: Float32Array, options?: PeakPickOptions): PeakPickEvent[];
+/**
+ * Run band CQT analysis for multiple bands.
+ *
+ * @param cqt - Source CQT spectrogram
+ * @param request - Batch request specifying bands and functions
+ * @param options - Computation options
+ * @returns Map of results by band ID
+ */
+declare function runBandCqtBatch(cqt: CqtSpectrogram, request: BandCqtBatchRequest, options?: BandCqtOptions): Promise<BandCqtBatchResult>;
+/**
+ * Get a human-readable label for a band CQT function.
+ *
+ * @param fn - Band CQT function ID
+ * @returns Human-readable label
+ */
+declare function getBandCqtFunctionLabel(fn: BandCqtFunctionId): string;
 
 type SpectrogramLike2D = {
     times: Float32Array;
@@ -132,6 +1566,634 @@ type Features2D = {
 declare function delta(features: Features2D, options?: DeltaOptions): Features2D;
 declare function deltaDelta(features: Features2D, options?: DeltaOptions): Features2D;
 
+/**
+ * Constant-Q Transform (CQT) implementation for F5.
+ *
+ * CQT provides log-frequency resolution aligned to musical pitch ratios.
+ * This implementation builds on the existing STFT infrastructure by:
+ * 1. Computing an STFT using the existing spectrogram function
+ * 2. Applying a CQT filterbank in the frequency domain
+ *
+ * The CQT is an internal spectral view, not a user-facing spectrogram.
+ */
+
+/** Default CQT configuration values */
+declare const CQT_DEFAULTS: {
+    /** Quarter-tone resolution (24 bins per octave) */
+    readonly binsPerOctave: 24;
+    /** C1 (lowest note on a standard piano) */
+    readonly fMin: 32.7;
+    /** C9 (well above audible range for most content) */
+    readonly fMax: 8372;
+};
+/**
+ * Convert CQT bin index to frequency in Hz.
+ */
+declare function cqtBinToHz(bin: number, config: CqtConfig): number;
+/**
+ * Convert frequency in Hz to CQT bin index (may be fractional).
+ */
+declare function hzToCqtBin(hz: number, config: CqtConfig): number;
+/**
+ * Calculate number of octaves covered by the CQT config.
+ */
+declare function getNumOctaves(config: CqtConfig): number;
+/**
+ * Calculate total number of CQT bins.
+ */
+declare function getNumBins(config: CqtConfig): number;
+/**
+ * Generate the center frequencies for all CQT bins.
+ */
+declare function getCqtBinFrequencies(config: CqtConfig): Float32Array;
+type CqtOptions = {
+    /** Optional cancellation hook; checked periodically. */
+    isCancelled?: () => boolean;
+};
+/**
+ * Apply default values to a partial CQT config.
+ */
+declare function withCqtDefaults(partial?: Partial<CqtConfig>): CqtConfig;
+/**
+ * Compute a CQT spectrogram from audio.
+ *
+ * This function:
+ * 1. Computes an STFT using the existing spectrogram infrastructure
+ * 2. Applies a CQT filterbank to each STFT frame
+ * 3. Returns a log-frequency representation
+ *
+ * @param audio - Audio buffer to analyze
+ * @param config - CQT configuration
+ * @param options - Optional processing options
+ * @returns CQT spectrogram with log-frequency resolution
+ */
+declare function cqtSpectrogram(audio: AudioBufferLike$1, config: CqtConfig, options?: CqtOptions): Promise<CqtSpectrogram>;
+/**
+ * Compute CQT and return with metadata for MIR pipeline.
+ */
+declare function computeCqt(audio: AudioBufferLike$1, config?: Partial<CqtConfig>, options?: CqtOptions): Promise<{
+    cqt: CqtSpectrogram;
+    meta: MirRunMeta;
+}>;
+
+/**
+ * CQT-Derived 1D Signals for F5.
+ *
+ * These signals extract musically meaningful 1D features from the CQT representation:
+ * - harmonicEnergy: Measures tonal presence vs noise
+ * - bassPitchMotion: Measures bassline activity and low-end groove
+ * - tonalStability: Measures harmonic stability vs modulation
+ *
+ * All signals are:
+ * - 1D (one value per frame)
+ * - Time-aligned with the CQT frames
+ * - Deterministic
+ * - Normalized to [0, 1] range
+ */
+
+/**
+ * Compute harmonic energy signal from CQT.
+ *
+ * Measures sustained, pitch-aligned energy across harmonic bins.
+ * Intended to capture "tonal presence" vs noise.
+ */
+declare function harmonicEnergy(cqt: CqtSpectrogram): CqtSignalResult;
+/**
+ * Compute bass pitch motion signal from CQT.
+ *
+ * Measures rate and magnitude of pitch movement in low-frequency CQT bins.
+ * Intended to capture bassline motion, groove, and low-end activity.
+ *
+ * Algorithm:
+ * 1. Extract bass-range bins from each frame
+ * 2. Compute pitch centroid in bass range
+ * 3. Compute absolute difference between consecutive frames
+ */
+declare function bassPitchMotion(cqt: CqtSpectrogram): CqtSignalResult;
+/**
+ * Compute tonal stability signal from CQT.
+ *
+ * Measures consistency of dominant pitch structure over time.
+ * High values imply harmonic stability; low values imply modulation or noise.
+ *
+ * Algorithm:
+ * 1. Compute chroma histogram for each frame
+ * 2. Over a sliding window, compute variance of chroma distribution
+ * 3. Low variance = stable tonality; high variance = unstable
+ * 4. Invert so that high values = stable
+ */
+declare function tonalStability(cqt: CqtSpectrogram): CqtSignalResult;
+/**
+ * Compute a CQT-derived signal by ID.
+ */
+declare function computeCqtSignal(cqt: CqtSpectrogram, signalId: CqtSignalId): CqtSignalResult;
+/**
+ * Compute all CQT-derived signals.
+ */
+declare function computeAllCqtSignals(cqt: CqtSpectrogram): Map<CqtSignalId, CqtSignalResult>;
+
+/**
+ * YIN-based monophonic pitch detection.
+ *
+ * Implements the YIN algorithm for fundamental frequency (f0) estimation.
+ * Designed for monophonic sources: vocals, bass, lead synths.
+ *
+ * Reference: de Cheveigné, A., & Kawahara, H. (2002).
+ * "YIN, a fundamental frequency estimator for speech and music."
+ * Journal of the Acoustical Society of America, 111(4), 1917-1930.
+ */
+
+/** Options for activity gating in pitch detection */
+type PitchActivityOptions = {
+    /** Pre-computed activity signal to use for gating */
+    activity?: ActivitySignal;
+    /** How to handle inactive frames. Default: "zero" */
+    inactiveBehavior?: "zero" | "hold";
+};
+type PitchConfig = {
+    /** Minimum detectable frequency in Hz. Default: 50 */
+    fMinHz?: number;
+    /** Maximum detectable frequency in Hz. Default: 1000 */
+    fMaxHz?: number;
+    /** Hop size in samples (determines time resolution). Default: 512 */
+    hopSize?: number;
+    /** Window size for analysis. Default: 2048 */
+    windowSize?: number;
+    /** YIN threshold for voiced detection (0-1). Default: 0.15 */
+    threshold?: number;
+    /** Activity gating options */
+    activityOptions?: PitchActivityOptions;
+};
+type PitchResult = {
+    times: Float32Array;
+    values: Float32Array;
+};
+/**
+ * Extract fundamental frequency (f0) from mono audio.
+ *
+ * Uses the YIN algorithm for robust pitch detection.
+ * Returns 0 Hz for unvoiced/silent frames.
+ *
+ * @param samples - Mono audio samples
+ * @param sampleRate - Sample rate of the audio
+ * @param config - Configuration options
+ * @returns Times (seconds) and f0 values (Hz, 0 for unvoiced)
+ */
+declare function pitchF0(samples: Float32Array, sampleRate: number, config?: PitchConfig): PitchResult;
+/**
+ * Extract pitch detection confidence from mono audio.
+ *
+ * Uses the YIN algorithm's aperiodicity measure.
+ * Returns values in [0, 1] where 1 = highly periodic (confident pitch).
+ *
+ * @param samples - Mono audio samples
+ * @param sampleRate - Sample rate of the audio
+ * @param config - Configuration options
+ * @returns Times (seconds) and confidence values (0-1)
+ */
+declare function pitchConfidence(samples: Float32Array, sampleRate: number, config?: PitchConfig): PitchResult;
+
+/**
+ * Band Proposal Generation for F5.
+ *
+ * Generates automated suggestions for "interesting" frequency bands.
+ * Proposals are advisory only - they must be explicitly promoted by the user.
+ *
+ * Algorithm overview:
+ * 1. Analyze spectral structure using CQT
+ * 2. Identify regions with concentrated energy or distinct activity
+ * 3. Score and rank candidates
+ * 4. Generate proposal objects with explanations
+ */
+
+type BandProposalOptions = {
+    config?: BandProposalConfig;
+    isCancelled?: () => boolean;
+};
+/**
+ * Generate band proposals from audio.
+ *
+ * @param audio - Audio buffer to analyze
+ * @param duration - Track duration in seconds
+ * @param options - Optional configuration
+ * @returns Array of band proposals with salience scores and reasons
+ */
+declare function generateBandProposals(audio: AudioBufferLike$1, duration: number, options?: BandProposalOptions): Promise<BandProposalResult>;
+
+/**
+ * Custom Signal Reduction
+ *
+ * Provides algorithms for reducing 2D spectral data (mel spectrogram, HPSS,
+ * MFCC, etc.) to 1D signals with configurable bin ranges and reduction methods.
+ */
+/**
+ * Input format for 2D time-aligned data.
+ * Shape: data[timeIndex][featureIndex]
+ */
+interface ReductionInput {
+    /** 2D data: data[timeIndex][featureIndex] */
+    data: Float32Array[];
+    /** Time in seconds for each frame */
+    times: Float32Array;
+}
+/**
+ * Reduction algorithm identifiers.
+ */
+type ReductionAlgorithmId = "mean" | "max" | "sum" | "variance" | "amplitude" | "spectralFlux" | "spectralCentroid" | "onsetStrength";
+/**
+ * Options for bin range selection.
+ */
+interface BinRangeOptions {
+    /** Low bin index (inclusive). Default: 0 */
+    lowBin?: number;
+    /** High bin index (exclusive). Default: all bins */
+    highBin?: number;
+}
+/**
+ * Options for onset strength algorithm.
+ */
+interface OnsetStrengthOptions {
+    /** Smoothing window in milliseconds. Default: 10 */
+    smoothMs?: number;
+    /** Whether to log-compress before differencing. Default: true */
+    useLog?: boolean;
+    /** Difference method. Default: "rectified" */
+    diffMethod?: "rectified" | "abs";
+}
+/**
+ * Options for spectral flux algorithm.
+ */
+interface SpectralFluxOptions {
+    /** Whether to normalize frames before computing flux. Default: true */
+    normalized?: boolean;
+}
+/**
+ * Combined options for reduction.
+ */
+interface ReductionOptions {
+    /** Bin range selection */
+    binRange?: BinRangeOptions;
+    /** Onset strength parameters */
+    onsetStrength?: OnsetStrengthOptions;
+    /** Spectral flux parameters */
+    spectralFlux?: SpectralFluxOptions;
+}
+/**
+ * Result of a reduction operation.
+ */
+interface ReductionResult {
+    /** Frame times in seconds */
+    times: Float32Array;
+    /** Reduced values per frame */
+    values: Float32Array;
+    /** Value range for normalization */
+    valueRange: {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * Reduce 2D time-aligned data to a 1D signal using the specified algorithm.
+ *
+ * @param input - 2D input data (frames x bins)
+ * @param algorithm - Reduction algorithm to use
+ * @param options - Algorithm options including bin range selection
+ * @returns Reduction result with times, values, and value range
+ */
+declare function reduce2DToSignal(input: ReductionInput, algorithm: ReductionAlgorithmId, options?: ReductionOptions): ReductionResult;
+/**
+ * Get human-readable label for a reduction algorithm.
+ */
+declare function getReductionAlgorithmLabel(algorithm: ReductionAlgorithmId): string;
+/**
+ * Get description for a reduction algorithm.
+ */
+declare function getReductionAlgorithmDescription(algorithm: ReductionAlgorithmId): string;
+/**
+ * Polarity interpretation mode.
+ * - "signed": Preserve direction (signal can be positive or negative)
+ * - "magnitude": Activity level only (always positive, uses absolute value)
+ */
+type PolarityMode = "signed" | "magnitude";
+/**
+ * Apply polarity interpretation to a signal.
+ * Called after reduction, before stabilization.
+ *
+ * @param values - Input signal values
+ * @param mode - Polarity mode to apply
+ * @returns Transformed signal values
+ */
+declare function applyPolarity(values: Float32Array, mode: PolarityMode): Float32Array;
+/**
+ * Stabilization mode presets.
+ */
+type StabilizationMode = "none" | "light" | "medium" | "heavy";
+/**
+ * Envelope mode for signal shaping.
+ */
+type EnvelopeMode = "raw" | "attackRelease";
+/**
+ * Options for signal stabilization.
+ */
+interface StabilizationOptions {
+    /** Smoothing intensity preset. */
+    mode: StabilizationMode;
+    /** Envelope shaping mode. */
+    envelopeMode: EnvelopeMode;
+    /** Attack time in seconds (only for attackRelease mode). */
+    attackTimeSec?: number;
+    /** Release time in seconds (only for attackRelease mode). */
+    releaseTimeSec?: number;
+}
+/**
+ * Apply stabilization to a signal.
+ *
+ * @param values - Input signal values
+ * @param times - Frame times in seconds
+ * @param options - Stabilization options
+ * @returns Stabilized signal values
+ */
+declare function stabilizeSignal(values: Float32Array, times: Float32Array, options: StabilizationOptions): Float32Array;
+/**
+ * Compute percentile values from a signal.
+ *
+ * @param values - Signal values
+ * @param percentiles - Array of percentiles to compute (0-100)
+ * @returns Object mapping percentile to value
+ */
+declare function computePercentiles(values: Float32Array, percentiles: number[]): Record<number, number>;
+/**
+ * Compute local (viewport) statistics for a signal.
+ *
+ * @param values - Signal values
+ * @param times - Frame times in seconds
+ * @param startTime - Viewport start time
+ * @param endTime - Viewport end time
+ * @returns Statistics within the viewport
+ */
+declare function computeLocalStats(values: Float32Array, times: Float32Array, startTime: number, endTime: number): {
+    min: number;
+    max: number;
+    p5: number;
+    p95: number;
+};
+
+/**
+ * Event to Signal Conversion
+ *
+ * Converts discrete event streams (onsets, beats, authored events)
+ * into continuous 1D signals for use in derived signal pipelines.
+ *
+ * Reducer algorithms:
+ * - eventCount: Count events per window
+ * - eventDensity: Normalized count (events per second)
+ * - weightedSum: Sum of event weights per window
+ * - weightedMean: Mean of event weights per window
+ * - envelope: Generate continuous envelope from events
+ */
+/**
+ * A discrete event with time and optional weight.
+ */
+interface DiscreteEvent {
+    /** Event time in seconds. */
+    time: number;
+    /** Event weight (default 1.0). */
+    weight?: number;
+    /** Optional duration in seconds. */
+    duration?: number;
+}
+/**
+ * Window specification for event aggregation.
+ */
+type EventWindowSpec = {
+    kind: "seconds";
+    windowSize: number;
+} | {
+    kind: "samples";
+    windowSize: number;
+};
+/**
+ * Envelope shape for event-to-signal conversion.
+ */
+type EnvelopeShape = {
+    kind: "impulse";
+} | {
+    kind: "gaussian";
+    widthMs: number;
+} | {
+    kind: "attackDecay";
+    attackMs: number;
+    decayMs: number;
+} | {
+    kind: "gate";
+};
+/**
+ * Options for event-to-signal conversion.
+ */
+interface EventToSignalOptions {
+    /** Sample rate for output signal (samples per second). */
+    sampleRate: number;
+    /** Total duration in seconds. */
+    duration: number;
+    /** Whether to normalize output to 0-1 range. */
+    normalize?: boolean;
+}
+/**
+ * Result of event-to-signal conversion.
+ */
+interface EventSignalResult {
+    /** Signal values. */
+    values: Float32Array;
+    /** Time points in seconds. */
+    times: Float32Array;
+    /** Value range before normalization. */
+    rawRange: {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * Count events per window (sliding window approach).
+ */
+declare function eventCount(events: DiscreteEvent[], windowSpec: EventWindowSpec, options: EventToSignalOptions): EventSignalResult;
+/**
+ * Event density: events per second in each window.
+ */
+declare function eventDensity(events: DiscreteEvent[], windowSpec: EventWindowSpec, options: EventToSignalOptions): EventSignalResult;
+/**
+ * Weighted sum of events per window.
+ */
+declare function weightedSum(events: DiscreteEvent[], windowSpec: EventWindowSpec, options: EventToSignalOptions): EventSignalResult;
+/**
+ * Weighted mean of events per window.
+ */
+declare function weightedMean(events: DiscreteEvent[], windowSpec: EventWindowSpec, options: EventToSignalOptions): EventSignalResult;
+/**
+ * Generate continuous envelope from events.
+ * Each event contributes an envelope shape to the output.
+ */
+declare function eventEnvelope(events: DiscreteEvent[], shape: EnvelopeShape, options: EventToSignalOptions): EventSignalResult;
+/**
+ * Convert events to signal using specified reducer.
+ */
+type EventReducer = "eventCount" | "eventDensity" | "weightedSum" | "weightedMean" | "envelope";
+interface EventToSignalParams {
+    /** Reducer algorithm. */
+    reducer: EventReducer;
+    /** Window spec for count/density/sum/mean reducers. */
+    window?: EventWindowSpec;
+    /** Envelope shape for envelope reducer. */
+    envelopeShape?: EnvelopeShape;
+}
+declare function eventsToSignal(events: DiscreteEvent[], params: EventToSignalParams, options: EventToSignalOptions): EventSignalResult;
+
+/**
+ * Signal Transforms
+ *
+ * Transform chain implementation for derived signals.
+ * All transforms are pure functions that operate on Float32Array values.
+ *
+ * Transform categories:
+ * - Smooth: movingAverage, exponential, gaussian
+ * - Normalize: minMax, robust, zScore
+ * - Scale: linear scaling with offset
+ * - Polarity: signed, magnitude
+ * - Clamp: min/max bounds
+ * - Remap: input range to output range with curve
+ */
+/**
+ * Base transform type.
+ */
+interface TransformBase {
+    kind: string;
+}
+/**
+ * Smooth with moving average.
+ */
+interface TransformSmoothMovingAverage extends TransformBase {
+    kind: "smooth";
+    method: "movingAverage";
+    windowMs: number;
+}
+/**
+ * Smooth with exponential filter.
+ */
+interface TransformSmoothExponential extends TransformBase {
+    kind: "smooth";
+    method: "exponential";
+    timeConstantMs: number;
+}
+/**
+ * Smooth with Gaussian kernel.
+ */
+interface TransformSmoothGaussian extends TransformBase {
+    kind: "smooth";
+    method: "gaussian";
+    windowMs: number;
+}
+/**
+ * All smoothing transform types.
+ */
+type TransformSmooth = TransformSmoothMovingAverage | TransformSmoothExponential | TransformSmoothGaussian;
+/**
+ * Normalize to 0-1 range using min/max.
+ */
+interface TransformNormalizeMinMax extends TransformBase {
+    kind: "normalize";
+    method: "minMax";
+    targetMin?: number;
+    targetMax?: number;
+}
+/**
+ * Normalize using robust percentile range.
+ */
+interface TransformNormalizeRobust extends TransformBase {
+    kind: "normalize";
+    method: "robust";
+    percentileLow?: number;
+    percentileHigh?: number;
+    targetMin?: number;
+    targetMax?: number;
+}
+/**
+ * Normalize using z-score (mean and std dev).
+ */
+interface TransformNormalizeZScore extends TransformBase {
+    kind: "normalize";
+    method: "zScore";
+}
+/**
+ * All normalization transform types.
+ */
+type TransformNormalize = TransformNormalizeMinMax | TransformNormalizeRobust | TransformNormalizeZScore;
+/**
+ * Linear scale and offset.
+ */
+interface TransformScale extends TransformBase {
+    kind: "scale";
+    scale: number;
+    offset: number;
+}
+/**
+ * Polarity mode.
+ */
+interface TransformPolarity extends TransformBase {
+    kind: "polarity";
+    mode: "signed" | "magnitude";
+}
+/**
+ * Clamp to bounds.
+ */
+interface TransformClamp extends TransformBase {
+    kind: "clamp";
+    min?: number;
+    max?: number;
+}
+/**
+ * Remap from input range to output range.
+ */
+interface TransformRemap extends TransformBase {
+    kind: "remap";
+    inputMin: number;
+    inputMax: number;
+    outputMin: number;
+    outputMax: number;
+    curve?: "linear" | "ease" | "easeIn" | "easeOut";
+}
+/**
+ * Union of all transform step types.
+ */
+type TransformStep = TransformSmooth | TransformNormalize | TransformScale | TransformPolarity | TransformClamp | TransformRemap;
+/**
+ * A chain of transforms to apply in sequence.
+ */
+type TransformChain = TransformStep[];
+/**
+ * Context for transform chain execution.
+ */
+interface TransformContext {
+    /** Sample rate of the signal (samples per second). */
+    sampleRate: number;
+    /** Time points in seconds (optional, for time-aware transforms). */
+    times?: Float32Array;
+}
+/**
+ * Apply a single transform step.
+ */
+declare function applyTransformStep(values: Float32Array, step: TransformStep, context: TransformContext): Float32Array;
+/**
+ * Apply a chain of transforms to a signal.
+ */
+declare function applyTransformChain(values: Float32Array, chain: TransformChain, context: TransformContext): Float32Array;
+/**
+ * Get human-readable label for a transform step.
+ */
+declare function getTransformLabel(step: TransformStep): string;
+/**
+ * Create a default transform step for a kind.
+ */
+declare function createDefaultTransform(kind: TransformStep["kind"]): TransformStep | null;
+
 type NormaliseForWaveformOptions = {
     min?: number;
     max?: number;
@@ -189,6 +2251,19 @@ declare function spectrogramToDb(magnitudes2d: Spectrogram2D, options?: Spectrog
  */
 declare function clampDb(db2d: Spectrogram2D, minDb: number, maxDb: number): Spectrogram2D;
 
+/**
+ * Resample audio using linear interpolation.
+ *
+ * This is a simple, fast resampling algorithm suitable for MIR analysis
+ * where perfect reconstruction is not critical.
+ *
+ * @param samples - Input audio samples
+ * @param fromRate - Original sample rate (Hz)
+ * @param toRate - Target sample rate (Hz)
+ * @returns Resampled audio samples
+ */
+declare function resample(samples: Float32Array, fromRate: number, toRate: number): Float32Array;
+
 type MinMax = {
     min: number;
     max: number;
@@ -447,4 +2522,4 @@ type AudioBufferLike = {
  */
 declare function helloMir(name?: string): string;
 
-export { type AudioBufferLike, type DeltaOptions, type Features2D, type HpssOptions, MIR_VERSION, type MelConfig, type MelSpectrogram, type MfccOptions, type MfccResult, type MinMax, type MirFingerprintV1, type MirFingerprintVectorWeights, MirGPU, type MirRefinementCandidateLabelV1, type MirSearchCandidate, type MirSearchCurveKindV1, type MirSearchGuidedOptionsV1, type MirSearchOptionsV1, type MirSearchResultV1, type MirSearchResultV1Guided, type MirVersion, type OnsetEnvelope, type OnsetEnvelopeGpuResult, type OnsetEnvelopeOptions, type PeakPickEvent, type PeakPickOptions, Spectrogram, type Spectrogram2D, type SpectrogramLike2D, type SpectrogramToDbOptions, clampDb, delta, deltaDelta, fingerprintToVectorV1, fingerprintV1, helloMir, hpss, melSpectrogram, mfcc, minMax, normaliseForWaveform, onsetEnvelopeFromMel, onsetEnvelopeFromMelGpu, onsetEnvelopeFromSpectrogram, peakPick, searchTrackV1, searchTrackV1Guided, similarityFingerprintV1, spectralCentroid, spectralFlux, spectrogramToDb };
+export { type ActivityConfig, type ActivityDiagnostics, type ActivitySignal, type AdaptivePeakPickingResult, type AmplitudeEnvelopeConfig, type AmplitudeEnvelopeResult, type AudioBufferLike, type BandBeatCandidatesOptions, BandCqt1DResult, type BandCqtBatchRequest, type BandCqtBatchResult, BandCqtFunctionId, type BandCqtOptions, BandEventFunctionId, type BandEventsBatchRequest, type BandEventsBatchResult, BandEventsResult, type BandMaskOptions, BandMir1DResult, type BandMirBatchRequest, type BandMirBatchResult, BandMirFunctionId, type BandMirOptions, type BandOnsetPeaksOptions, BandProposalConfig, type BandProposalOptions, BandProposalResult, BeatCandidate, type BeatCandidatesOptions, type BeatCandidatesOutput, BeatGrid, BeatPosition, type BeatSalienceSignal, type BinGateConfig, type BinRangeOptions, CQT_DEFAULTS, CqtConfig, type CqtOptions, CqtSignalId, CqtSignalResult, CqtSpectrogram, DEFAULT_PEAK_PICKING_PARAMS, type DeltaOptions, type DiscreteEvent, type EnvelopeMode, type EnvelopeShape, type EventReducer, type EventSignalResult, type EventToSignalOptions, type EventToSignalParams, type EventWindowSpec, type Features2D, FrequencyBand, FrequencyBandStructure, FrequencyBoundsAtTime, FrequencyKeyframe, FrequencySegment, type HpssOptions, type HysteresisGateParams, MIR_VERSION, type MaskedCqtSpectrogram, type MaskedSpectrogram, type MelConfig, type MelConversionConfig, type MelSpectrogram, type MfccOptions, type MfccResult, type MinMax, type MirFingerprintV1, type MirFingerprintVectorWeights, MirGPU, type MirRefinementCandidateLabelV1, MirRunMeta, type MirSearchCandidate, type MirSearchCurveKindV1, type MirSearchGuidedOptionsV1, type MirSearchOptionsV1, type MirSearchResultV1, type MirSearchResultV1Guided, type MirVersion, MusicalTimeSegment, MusicalTimeStructure, type OnsetDiagnostics, type OnsetEnvelope, type OnsetEnvelopeGpuResult, type OnsetEnvelopeOptions, type OnsetEnvelopeResult, type OnsetStrengthOptions, type PeakPickEvent, type PeakPickOptions, type PeakPickingParams, type PeakPickingResult, PhaseAlignmentConfig, PhaseHypothesis, type PitchActivityOptions, type PitchConfig, type PitchResult, type PolarityMode, type ReductionAlgorithmId, type ReductionInput, type ReductionOptions, type ReductionResult, type SilenceGateConfig, type SilenceGateResult, type SpectralFluxOptions, Spectrogram, type Spectrogram2D, type SpectrogramLike2D, type SpectrogramToDbOptions, type StabilizationMode, type StabilizationOptions, type TempoHypothesesOptions, type TempoHypothesesOutput, TempoHypothesis, type TransformChain, type TransformClamp, type TransformContext, type TransformNormalize, type TransformNormalizeMinMax, type TransformNormalizeRobust, type TransformNormalizeZScore, type TransformPolarity, type TransformRemap, type TransformScale, type TransformSmooth, type TransformSmoothExponential, type TransformSmoothGaussian, type TransformSmoothMovingAverage, type TransformStep, addBandToStructure, allFrequencyBoundsAt, amplitudeEnvelope, applyActivityGating, applyBandMaskToCqt, applyBandMaskToSpectrogram, applyHysteresisGate, applyPolarity, applyTransformChain, applyTransformStep, bandAmplitudeEnvelope, bandBeatCandidates, bandCqtBassPitchMotion, bandCqtHarmonicEnergy, bandCqtTonalStability, bandOnsetPeaks, bandOnsetStrength, bandSpectralCentroid, bandSpectralFlux, bandsActiveAt, bassPitchMotion, beatSalienceFromMel, binToHz, buildActivityMask, clampDb, computeActivityFromAudio, computeActivityFromMel, computeActivityFromSpectrogram, computeAdaptiveThreshold, computeAllCqtSignals, computeBandMaskAtTime, computeBeatPosition, computeBeatPositionFromStructure, computeCqt, computeCqtSignal, computeFrameAmplitude, computeFrameEnergy, computeFrameEnergyFromMel, computeFrameEnergyFromSpectrogram, computeLocalStats, computePercentiles, computePhaseHypotheses, computeSilenceGating, cqtBinToHz, cqtSpectrogram, createBandStructure, createConstantBand, createDefaultTransform, createMusicalTimeStructure, createSectionedBand, createSegmentFromGrid, createStandardBands, delta, deltaDelta, detectBeatCandidates, estimateNoiseFloor, eventCount, eventDensity, eventEnvelope, eventsToSignal, featureIndexToHz, findBandById, findSegmentAtTime, fingerprintToVectorV1, fingerprintV1, frequencyBoundsAt, generateBandId, generateBandProposals, generateBeatTimes, generateSegmentBeatTimes, generateSegmentId, generateTempoHypotheses, getBandCqtFunctionLabel, getBandEventFunctionLabel, getBandMirFunctionLabel, getCqtBinFrequencies, getNumBins, getNumOctaves, getReductionAlgorithmDescription, getReductionAlgorithmLabel, getTransformLabel, harmonicEnergy, helloMir, hpss, hzToBin, hzToCqtBin, hzToFeatureIndex, hzToMel, interpolateActivity, keyframesFromBand, melSpectrogram, melToHz, mergeAdjacentSegments, mfcc, minMax, moveKeyframeTime, normaliseForWaveform, onsetEnvelopeFromMel, onsetEnvelopeFromMelGpu, onsetEnvelopeFromSpectrogram, peakPick, pickPeaks, pickPeaksAdaptive, pitchConfidence, pitchF0, reduce2DToSignal, removeBandFromStructure, removeKeyframe, resample, runBandCqtBatch, runBandEventsBatch, runBandMirBatch, searchTrackV1, searchTrackV1Guided, segmentsFromKeyframes, similarityFingerprintV1, sortBands, sortFrequencySegments, sortSegments, spectralCentroid, spectralFlux, spectrogramToDb, splitBandSegmentAt, splitSegment, stabilizeSignal, tonalStability, touchStructure, updateBandInStructure, updateKeyframe, validateBandStructure, validateFrequencyBand, validateFrequencySegments, validateSegments, weightedMean, weightedSum, withBinGateDefaults, withCqtDefaults, withSilenceGateDefaults };