playlist-data-engine 1.1.0

package/dist/core/analysis/PitchAnalyzer.d.ts

@@ -0,0 +1,266 @@
+/**
+ * PitchAnalyzer - Standalone full-track pitch detection
+ *
+ * Provides per-frame pitch detection and melody contour analysis directly from
+ * raw audio, with zero dependency on beat detection or rhythm generation.
+ *
+ * ## Key Design Decisions
+ *
+ * - **No `PitchBeatLinker` dependency.** Uses `PitchDetector`/`EssentiaPitchDetector`
+ *   directly on the audio signal and does not align pitch frames to beats.
+ *
+ * - **Contour analysis on `PitchResult[]`.** Provides its own contour analysis that
+ *   works directly on the `PitchResult[]` output from the detectors.
+ *
+ * - **Same analyzer pattern as `AudioAnalyzer` / `MusicClassifier`.** Accepts a URL,
+ *   fetches/decodes audio internally, returns a typed profile with metadata.
+ *
+ * @example
+ * ```typescript
+ * const analyzer = new PitchAnalyzer({
+ *   algorithm: 'pitch_melodia',
+ *   includeContour: true
+ * });
+ *
+ * const profile = await analyzer.analyze('https://example.com/audio.mp3');
+ *
+ * console.log(`Voicing ratio: ${(profile.voicingRatio * 100).toFixed(1)}%`);
+ * console.log(`Range: ${profile.lowestNote} - ${profile.highestNote}`);
+ * console.log(`Contour direction: ${profile.contour?.direction}`);
+ * ```
+ */
+import type { PitchResult } from './PitchDetector.js';
+import type { PitchAlgorithm } from './EssentiaPitchDetector.js';
+import type { DirectionStats, IntervalStats } from './MelodyContourAnalyzer.js';
+/**
+ * Configuration for the PitchAnalyzer
+ */
+export interface PitchAnalyzerConfig {
+    /**
+     * Which pitch detection algorithm to use.
+     * @default 'pitch_melodia'
+     */
+    algorithm?: PitchAlgorithm;
+    /**
+     * Minimum frequency to detect in Hz.
+     * @default 80
+     */
+    minFrequency?: number;
+    /**
+     * Maximum frequency to detect in Hz.
+     * Default varies by algorithm: 1000 for pyin_legacy, 20000 for others.
+     */
+    maxFrequency?: number;
+    /**
+     * Target sample rate for analysis.
+     * @default 44100
+     */
+    sampleRate?: number;
+    /**
+     * Hop size in samples between consecutive frames.
+     * Larger values = fewer frames = faster analysis, lower time resolution.
+     * Default is 1024 (~23ms at 44.1kHz, ~43 frames/sec) for the standalone
+     * analyzer. The beat-aligned path (PitchBeatLinker) uses smaller hops
+     * internally since it only evaluates at beat positions.
+     * @default 1024
+     */
+    hopSize?: number;
+    /**
+     * CREPE model URL (only for 'pitch_crepe' algorithm).
+     */
+    crepeModelUrl?: string;
+    /**
+     * URL resolver for Arweave URLs.
+     */
+    resolveUrl?: (url: string) => Promise<string>;
+    /**
+     * Whether to include melody contour analysis.
+     * @default true
+     */
+    includeContour?: boolean;
+    /**
+     * Optional progress callback.
+     * Reports phase name and progress (0-1).
+     */
+    onProgress?: (phase: string, progress: number) => void;
+}
+/**
+ * Direction of a pitch contour segment
+ */
+export type PitchContourSegmentDirection = 'up' | 'down' | 'stable';
+/**
+ * Overall direction of a pitch contour
+ */
+export type PitchContourDirection = 'ascending' | 'descending' | 'stable' | 'mixed';
+/**
+ * A segment of a pitch contour with consistent direction
+ */
+export interface PitchContourSegment {
+    /** Start time in seconds */
+    startTime: number;
+    /** End time in seconds */
+    endTime: number;
+    /** Starting note name (e.g., "C4") */
+    startNote: string;
+    /** Ending note name (e.g., "G5") */
+    endNote: string;
+    /** Direction of this segment */
+    direction: PitchContourSegmentDirection;
+    /** Interval in semitones between start and end */
+    interval: number;
+}
+/**
+ * Pitch contour representing the overall melodic shape
+ *
+ * Populated by pitch contour analysis when `includeContour !== false`.
+ * Provides the same depth of analysis as `MelodyContour` from `MelodyContourAnalyzer`.
+ */
+export interface PitchContour {
+    /** Overall melody direction */
+    direction: PitchContourDirection;
+    /** Pitch range information */
+    range: {
+        /** Lowest note (e.g., "C4") */
+        minNote: string;
+        /** Highest note (e.g., "F#5") */
+        maxNote: string;
+        /** Total span in semitones */
+        semitones: number;
+    };
+    /** Melody segments (groups of consecutive frames with same direction) */
+    segments: PitchContourSegment[];
+    /** Time-window direction analysis */
+    shortTermDirection: PitchContourDirection;
+    mediumTermDirection: PitchContourDirection;
+    longTermDirection: PitchContourDirection;
+}
+/**
+ * Result of full-track pitch analysis
+ *
+ * Contains per-frame pitch detection results, optional melody contour analysis,
+ * and summary statistics. Flat structure mirrors `AudioProfile` pattern.
+ */
+export interface PitchAnalysisProfile {
+    /** Per-frame pitch detection results */
+    pitchResults: PitchResult[];
+    /** Melody contour analysis (only populated when includeContour !== false) */
+    contour?: PitchContour;
+    /** Ratio of voiced to total frames (0.0 - 1.0) */
+    voicingRatio: number;
+    /** Average frequency of voiced frames in Hz */
+    averageFrequency: number;
+    /** Median frequency of voiced frames in Hz */
+    medianFrequency: number;
+    /** Minimum detected frequency in Hz */
+    minFrequency: number;
+    /** Maximum detected frequency in Hz */
+    maxFrequency: number;
+    /** Pitch range in semitones */
+    pitchRangeSemitones: number;
+    /** Lowest detected note name (e.g., "C3"), null if no voiced frames */
+    lowestNote: string | null;
+    /** Highest detected note name (e.g., "G5"), null if no voiced frames */
+    highestNote: string | null;
+    /** Most common note names, sorted by frequency */
+    noteDistribution: {
+        note: string;
+        count: number;
+        percentage: number;
+    }[];
+    /** Total frames analyzed */
+    totalFrames: number;
+    /** Number of voiced frames */
+    voicedFrames: number;
+    /** Direction statistics from contour analysis (when contour enabled) */
+    directionStats?: DirectionStats;
+    /** Interval statistics from contour analysis (when contour enabled) */
+    intervalStats?: IntervalStats;
+    /** Analysis metadata (pipeline info only) */
+    analysis_metadata: {
+        algorithm_used: string;
+        analyzed_at: string;
+        duration_analyzed: number;
+    };
+}
+/**
+ * Standalone full-track pitch analyzer
+ *
+ * Provides per-frame pitch detection and melody contour analysis directly from
+ * raw audio, with zero dependency on beat detection or rhythm generation.
+ *
+ * Uses the same analyzer pattern as `AudioAnalyzer` and `MusicClassifier`:
+ * accepts a URL, fetches/decodes audio internally, returns a typed profile.
+ */
+export declare class PitchAnalyzer {
+    private config;
+    /**
+     * Create a new PitchAnalyzer
+     *
+     * @param config - Configuration options
+     */
+    constructor(config?: PitchAnalyzerConfig);
+    /**
+     * Get the current configuration
+     */
+    getConfig(): Required<Omit<PitchAnalyzerConfig, 'onProgress'>> & {
+        onProgress?: (phase: string, progress: number) => void;
+    };
+    /**
+     * Analyze audio from a URL
+     *
+     * Fetches and decodes the audio, performs pitch detection, computes summary
+     * statistics, and optionally computes melody contour analysis.
+     *
+     * @param audioUrl - URL of the audio file to analyze
+     * @returns Promise resolving to the pitch analysis profile
+     */
+    analyze(audioUrl: string): Promise<PitchAnalysisProfile>;
+    /**
+     * Fetch and decode audio from a URL
+     *
+     * @param url - URL of the audio file
+     * @returns Promise resolving to mono signal, sample rate, and duration
+     */
+    private fetchAndDecodeAudio;
+    /**
+     * Resolve algorithm-specific defaults
+     *
+     * When `algorithm === 'pyin_legacy'` and `maxFrequency` is not explicitly
+     * provided, defaults to 1000 Hz (the YIN algorithm's practical ceiling).
+     * All other algorithms default to 20000 Hz.
+     */
+    private resolveDefaults;
+    /**
+     * Run pitch detection on the audio signal
+     */
+    private detectPitch;
+    /**
+     * Compute summary statistics from pitch results
+     */
+    private computeSummary;
+    /**
+     * Compute melody contour from pitch results
+     */
+    private computeContour;
+    /**
+     * Determine overall contour direction from segments
+     */
+    private determineOverallDirection;
+    /**
+     * Calculate direction over a specific time window
+     */
+    private calculateTimeWindowDirection;
+    /**
+     * Determine overall direction from direction counts
+     */
+    private determineOverallDirectionFromCounts;
+    /**
+     * Convert frequency in Hz to MIDI note number
+     */
+    private frequencyToMidi;
+    /**
+     * Convert MIDI note number to note name (e.g., "C4", "F#5")
+     */
+    private midiToNoteName;
+}
+//# sourceMappingURL=PitchAnalyzer.d.ts.map

package/dist/core/analysis/PitchAnalyzer.d.ts.map

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

package/dist/core/analysis/PitchDetector.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Pitch Detection using pYIN (Probabilistic YIN) Algorithm
+ *
+ * Implements the pYIN algorithm for robust pitch detection in polyphonic music.
+ * pYIN extends the classic YIN algorithm with probabilistic modeling and
+ * Hidden Markov Model (HMM) tracking for smoother, more accurate pitch estimation.
+ *
+ * ## Algorithm Overview
+ *
+ * 1. **YIN Difference Function**: Computes the difference between the signal
+ *    and time-shifted versions of itself at various lags (candidate periods).
+ *
+ * 2. **Cumulative Mean Normalization**: Normalizes the difference function
+ *    to make it more robust to amplitude variations.
+ *
+ * 3. **Pitch Candidates**: For each frame, identifies multiple pitch candidates
+ *    with associated probabilities based on the normalized difference function.
+ *
+ * 4. **HMM Tracking**: Uses a Hidden Markov Model to track pitch over time,
+ *    considering both observation probabilities and transition costs.
+ *
+ * 5. **Viterbi Decoding**: Finds the optimal sequence of pitch states that
+ *    maximizes the overall probability, producing smooth pitch trajectories.
+ *
+ * ## Key Features
+ *
+ * - **Probabilistic Output**: Provides probability/confidence for each pitch estimate
+ * - **Voicing Detection**: Automatically detects voiced (pitched) vs unvoiced segments
+ * - **Smooth Transitions**: HMM prevents erratic pitch jumps between frames
+ * - **Polyphonic Robustance**: Handles complex audio by tracking the most likely fundamental
+ *
+ * @example
+ * ```typescript
+ * const detector = new PitchDetector({
+ *   minFrequency: 80,
+ *   maxFrequency: 1000,
+ * });
+ *
+ * const results = detector.detect(audioBuffer);
+ *
+ * for (const result of results) {
+ *   if (result.isVoiced) {
+ *     console.log(`${result.timestamp.toFixed(3)}s: ${result.noteName} (${result.frequency.toFixed(1)} Hz)`);
+ *   }
+ * }
+ * ```
+ *
+ * ## References
+ *
+ * - Mauch, M., & Dixon, S. (2014). pYIN: A Fundamental Frequency Estimator Using
+ *   Probabilistic Threshold Distributions. IEEE ICASSP.
+ * - De Cheveigné, A., & Kawahara, H. (2002). YIN, a fundamental frequency
+ *   estimator for speech and music. JASA.
+ */
+/**
+ * Configuration for the PitchDetector
+ */
+export interface PitchDetectorConfig {
+    /** Minimum frequency to detect in Hz (default: 80Hz, low guitar) */
+    minFrequency: number;
+    /** Maximum frequency to detect in Hz (default: 1000Hz, high vocals) */
+    maxFrequency: number;
+    /** Frame size in samples (default: 2048, ~46ms at 44.1kHz) */
+    frameSize: number;
+    /** Hop size in samples (default: 512, ~12ms at 44.1kHz) */
+    hopSize: number;
+    /** Probability threshold for voiced/unvoiced decision (default: 0.5) */
+    voicingThreshold: number;
+    /** Penalty for large pitch jumps in HMM (default: 0.5) */
+    transitionPenalty: number;
+    /** Probability of staying in the same pitch state (default: 0.99) */
+    selfTransitionProbability: number;
+    /** Threshold for accepting a pitch candidate (default: 0.1) */
+    yinThreshold: number;
+    /** Target sample rate for analysis (default: 44100) */
+    targetSampleRate: number;
+}
+/**
+ * Result of pitch detection for a single frame
+ */
+export interface PitchResult {
+    /** Timestamp in seconds */
+    timestamp: number;
+    /** Detected frequency in Hz (0 if no pitch detected) */
+    frequency: number;
+    /** Probability from pYIN HMM (0-1) */
+    probability: number;
+    /** Whether this frame contains a detectable pitch */
+    isVoiced: boolean;
+    /** MIDI note number (null if unvoiced) */
+    midiNote: number | null;
+    /** Note name e.g., "C4", "F#5" (null if unvoiced) */
+    noteName: string | null;
+    /** Alternative hypotheses for debugging/analysis (optional) */
+    alternativeHypotheses?: {
+        frequency: number;
+        probability: number;
+    }[];
+}
+/**
+ * Pitch Detector using the pYIN algorithm
+ *
+ * Detects the fundamental frequency (pitch) of audio signals over time.
+ * Uses probabilistic YIN with HMM tracking for robust, smooth pitch estimation.
+ */
+export declare class PitchDetector {
+    private config;
+    private states;
+    private transitionMatrix;
+    /**
+     * Create a new PitchDetector
+     *
+     * @param config - Configuration options (partial, defaults applied)
+     */
+    constructor(config?: Partial<PitchDetectorConfig>);
+    /**
+     * Get the current configuration
+     */
+    getConfig(): PitchDetectorConfig;
+    /**
+     * Initialize the HMM states and transition matrix
+     *
+     * Creates pitch states covering the frequency range with 2 bins per semitone.
+     * Pre-computes the transition probabilities between all state pairs.
+     */
+    private initializeHMM;
+    /**
+     * Compute the transition probability matrix for the HMM
+     *
+     * The transition probability depends on the pitch distance between states.
+     * Closer pitches have higher transition probabilities.
+     */
+    private computeTransitionMatrix;
+    /**
+     * Calculate transition probability between two states
+     */
+    private transitionProbability;
+    /**
+     * Convert frequency in Hz to MIDI note number
+     */
+    private frequencyToMidi;
+    /**
+     * Convert MIDI note number to frequency in Hz
+     */
+    private midiToFrequency;
+    /**
+     * Convert MIDI note number to note name (e.g., "C4", "F#5")
+     */
+    private midiToNoteName;
+    /**
+     * Detect pitch in an audio buffer
+     *
+     * Processes the entire audio buffer and returns pitch estimates for each frame.
+     *
+     * @param audioBuffer - Audio buffer to analyze
+     * @returns Array of pitch results, one per analysis frame
+     */
+    detect(audioBuffer: AudioBuffer): PitchResult[];
+    /**
+     * Detect pitch continuously across a signal (full pYIN with HMM tracking)
+     *
+     * Same as detect() but accepts a Float32Array directly instead of AudioBuffer.
+     * Use this when audio has already been decoded or filtered.
+     *
+     * Note: The HMM is tuned for clean monophonic signals and may be too conservative
+     * for band-pass filtered polyphonic music. For such cases, prefer detectSignalRaw()
+     * which uses raw YIN voicing decisions without HMM bias.
+     *
+     * @param signal - Mono audio signal
+     * @param sampleRate - Sample rate of the signal
+     * @returns Array of pitch results, one per analysis frame
+     */
+    detectSignal(signal: Float32Array, sampleRate: number): PitchResult[];
+    /**
+     * Detect pitch continuously across a signal using raw YIN (no HMM)
+     *
+     * Analyzes every frame with YIN and uses raw candidate probability for voicing
+     * decisions, without the HMM's unvoiced-state bias. More suitable than detectSignal()
+     * for band-pass filtered polyphonic music where the HMM tends to stay stuck in
+     * the unvoiced state.
+     *
+     * @param signal - Mono audio signal
+     * @param sampleRate - Sample rate of the signal
+     * @returns Array of pitch results, one per analysis frame
+     */
+    detectSignalRaw(signal: Float32Array, sampleRate: number): PitchResult[];
+    /**
+     * Detect pitch at a specific timestamp
+     *
+     * Analyzes a single frame centered at the given timestamp.
+     *
+     * @param signal - Mono audio signal
+     * @param sampleRate - Sample rate of the signal
+     * @param timestamp - Timestamp in seconds to analyze
+     * @returns Pitch result for the frame
+     */
+    detectAt(signal: Float32Array, sampleRate: number, timestamp: number): PitchResult;
+    /**
+     * Analyze a single frame and return pitch candidates
+     *
+     * Implements the core YIN algorithm with probabilistic output.
+     * Uses absolute threshold method: prefers the first (highest frequency) candidate
+     * below the threshold to avoid octave errors.
+     */
+    private analyzeFrame;
+    /**
+     * Compute the YIN difference function
+     *
+     * For each lag τ, computes: d(τ) = Σ (x[i] - x[i+τ])²
+     *
+     * This measures how well the signal correlates with itself at each lag.
+     * A low value indicates the signal repeats with that period.
+     */
+    private computeDifferenceFunction;
+    /**
+     * Compute the Cumulative Mean Normalized Difference Function (CMNDF)
+     *
+     * Normalizes the difference function by dividing by the cumulative mean.
+     * This makes the function more robust to amplitude variations.
+     *
+     * Formula: cmndf(τ) = d(τ) / (1/τ * Σ d(j) for j=1 to τ)
+     */
+    private computeCMNDF;
+    /**
+     * Parabolic interpolation to refine the lag estimate
+     *
+     * Fits a parabola to three points and finds the minimum.
+     * This provides sub-sample accuracy for the pitch estimate.
+     */
+    private parabolicInterpolation;
+    /**
+     * Get the probability for a given state based on frame candidates
+     */
+    private getFrameProbability;
+    /**
+     * Run Viterbi decoding to find the optimal pitch path
+     *
+     * The Viterbi algorithm finds the most likely sequence of states given
+     * the observations (pitch candidates) and the transition model.
+     */
+    private viterbiDecode;
+    /**
+     * Calculate prior log probability for the first frame
+     */
+    private priorLogProbability;
+    /**
+     * Calculate observation log probability for a state given candidates
+     */
+    private observationLogProbability;
+}
+//# sourceMappingURL=PitchDetector.d.ts.map

package/dist/core/analysis/PitchDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PitchDetector.d.ts","sourceRoot":"","sources":["../../../src/core/analysis/PitchDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAQH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAEhC,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IAGrB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAGhB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,yBAAyB,EAAE,MAAM,CAAC;IAGlC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IAGrB,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,qBAAqB,CAAC,EAAE;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACvB,EAAE,CAAC;CACP;AAqED;;;;;GAKG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,gBAAgB,CAAkB;IAE1C;;;;OAIG;gBACS,MAAM,GAAE,OAAO,CAAC,mBAAmB,CAAM;IAwBrD;;OAEG;IACH,SAAS,IAAI,mBAAmB;IAIhC;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IA4BrB;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA2B7B;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;;;;;;OAOG;IACH,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,WAAW,EAAE;IA4D/C;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,EAAE;IAmDrE;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,EAAE;IAwFxE;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW;IA0DlF;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAsFpB;;;;;;;OAOG;IACH,OAAO,CAAC,yBAAyB;IAmBjC;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAgBpB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAiB9B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA0B3B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAyErB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;OAEG;IACH,OAAO,CAAC,yBAAyB;CAsDpC"}

package/dist/core/analysis/SpectrumScanner.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Spectrum Scanner - Separates frequency data into bands
+ * Based on specs/001-core-engine/SPEC.md
+ *
+ * Previous bands (severely imbalanced):
+ * - Bass: 20Hz - 250Hz (230 Hz range, only 3% of spectrum)
+ * - Mid: 250Hz - 4kHz (3,750 Hz range, 47% of spectrum)
+ * - Treble: 4kHz - 20kHz (16,000 Hz range, 200% of spectrum!)
+ *
+ * Rebalanced bands (v2):
+ * - Bass: 20Hz - 400Hz (380 Hz range, 11% of spectrum) - Expanded from 20-250Hz
+ * - Mid: 400Hz - 4kHz (3,600 Hz range, 52% of spectrum) - Expanded from 250-4kHz
+ * - Treble: 4kHz - 14kHz (10,000 Hz range, 37% of spectrum) - Narrowed from 4kHz-20kHz
+ *
+ * This creates a more balanced distribution that prevents treble from dominating
+ * class selection (which caused over-representation of Rogues/Rangers/Monks).
+ */
+import type { FrequencyBands } from '../types/AudioProfile.js';
+/** Current frequency band version (used for tracking audio profile format changes) */
+export declare const CURRENT_BAND_VERSION = 2;
+export declare class SpectrumScanner {
+    /**
+     * Separate frequency data into bass, mid, and treble bands
+     *
+     * Rebalanced band v2 ranges:
+     * - Bass: 20Hz - 400Hz (expanded from 20-250Hz)
+     * - Mid: 400Hz - 4kHz (expanded from 250-4kHz)
+     * - Treble: 4kHz - 14kHz (narrowed from 4kHz-20kHz)
+     *
+     * These rebalanced ranges prevent treble dominance that caused over-representation
+     * of dexterity-based classes (Rogue, Ranger, Monk).
+     *
+     * @param frequencyData - Raw FFT frequency data from audio analysis
+     * @param sampleRate - Audio sample rate in Hz (typically 44100 or 48000)
+     * @returns Frequency bands with normalized amplitude values (0-1)
+     */
+    static separateFrequencyBands(frequencyData: Uint8Array, sampleRate: number): FrequencyBands;
+    /**
+     * Calculate dominance (average amplitude) for a frequency band
+     *
+     * Bandwidth-aware normalization prevents wider frequency bands from dominating
+     * the dominance calculation. Previously, wider bands had more frequency bins,
+     * so their averages were naturally higher even if music wasn't louder in those ranges.
+     * This version normalizes by bandwidth (per kHz) to create fair comparisons across bands.
+     *
+     * @param band - Array of amplitude values for a frequency band
+     * @param bandWidthHz - Width of the frequency band in Hz (e.g., 380 for bass: 400-20)
+     * @returns Normalized dominance value (typically 0-1, may exceed 1 for very loud bands)
+     */
+    static calculateDominance(band: number[], bandWidthHz?: number): number;
+}
+//# sourceMappingURL=SpectrumScanner.d.ts.map

package/dist/core/analysis/SpectrumScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpectrumScanner.d.ts","sourceRoot":"","sources":["../../../src/core/analysis/SpectrumScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,qBAAa,eAAe;IACxB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,sBAAsB,CACzB,aAAa,EAAE,UAAU,EACzB,UAAU,EAAE,MAAM,GACnB,cAAc;IA4BjB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM;CAe1E"}