playlist-data-engine 1.1.0

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

@@ -0,0 +1,599 @@
+/**
+ * Audio analysis using Web Audio API with "Triple Tap" strategy
+ *
+ * Provides three audio analysis modes:
+ * 1. Triple Tap Real-Time Analysis - Peak detection at playhead position
+ * 2. Full Song Timeline Analysis - Configurable data points across entire track
+ * 3. Beat Detection System - Ellis DP algorithm for rhythm game support
+ */
+import type { AudioProfile, AudioTimelineEvent } from '../types/AudioProfile.js';
+import type { BeatMap, BeatStreamOptions, BeatInterpolationOptions, InterpolatedBeatMap, DownbeatConfig, BeatMapGeneratorOptions } from '../types/BeatMap.js';
+import { type ProgressCallback } from './beat/BeatMapGenerator.js';
+import { BeatStream } from './beat/BeatStream.js';
+import { type RhythmGenerationOptions, type GeneratedRhythm } from '../generation/RhythmGenerator.js';
+import { type LevelGenerationOptions, type GeneratedLevel, type LevelProgressCallback, type LevelGenerationProgress } from '../generation/LevelGenerator.js';
+import type { ControllerMode } from '../types/ButtonMapping.js';
+export type { LevelGenerationOptions, GeneratedLevel, LevelProgressCallback, LevelGenerationProgress };
+export type SamplingStrategy = {
+    type: 'interval';
+    intervalSeconds: number;
+} | {
+    type: 'count';
+    count: number;
+};
+export interface AudioAnalyzerOptions {
+    /** Include advanced metrics (spectral_centroid, spectral_rolloff, zero_crossing_rate) */
+    includeAdvancedMetrics?: boolean;
+    /** Sample rate for analysis */
+    sampleRate?: number;
+    /** FFT size (must be power of 2) */
+    fftSize?: number;
+    /**
+     * Treble boost multiplier (0.0-1.0+)
+     * Reduces treble dominance to help balance class selection.
+     * Default: 1
+     * @default 1
+     */
+    trebleBoost?: number;
+    /**
+     * Bass boost multiplier (0.0-1.0+)
+     * Increases bass dominance to help balance class selection.
+     * Default: 1
+     * @default 1
+     */
+    bassBoost?: number;
+    /**
+     * Mid boost multiplier (0.0-1.0+)
+     * Increases mid dominance to help balance class selection.
+     * Default: 1
+     * @default 1
+     */
+    midBoost?: number;
+}
+/**
+ * Audio analyzer using Web Audio API with Triple Tap sampling strategy
+ *
+ * Analyzes audio files using Fourier analysis to extract frequency band information
+ * (bass, mid, treble dominance). For audio longer than 3 seconds, uses Triple Tap
+ * sampling at 5%, 40%, and 70% positions to provide representative analysis.
+ */
+export declare class AudioAnalyzer {
+    private options;
+    /**
+     * Initialize AudioAnalyzer with configuration options
+     *
+     * @param {AudioAnalyzerOptions} [options] - Configuration options
+     * @param {boolean} [options.includeAdvancedMetrics=false] - Include spectral analysis metrics
+     * @param {number} [options.sampleRate=44100] - Sample rate in Hz
+     * @param {number} [options.fftSize=2048] - FFT size for frequency analysis (must be power of 2)
+     * @param {number} [options.trebleBoost=1] - Treble boost multiplier (0.0-1.0+)
+     * @param {number} [options.bassBoost=1] - Bass boost multiplier (0.0-1.0+)
+     * @param {number} [options.midBoost=1] - Mid boost multiplier (0.0-1.0+)
+     *
+     * @example
+     * const analyzer = new AudioAnalyzer({
+     *   includeAdvancedMetrics: true,
+     *   sampleRate: 48000,
+     *   trebleBoost: 0.6,
+     *   bassBoost: 1.3
+     * });
+     */
+    constructor(options?: AudioAnalyzerOptions);
+    /**
+     * Extract sonic fingerprint from audio URL
+     * Uses "Triple Tap" strategy: analyze at 5%, 40%, and 70% positions
+     */
+    extractSonicFingerprint(audioUrl: string): Promise<AudioProfile>;
+    /**
+     * Perform detailed timeline analysis of the entire song
+     *
+     * @param audioUrl URL of the audio file to analyze
+     * @param strategy strategy for sampling (interval-based or count-based)
+     */
+    analyzeTimeline(audioUrl: string, strategy: SamplingStrategy): Promise<AudioTimelineEvent[]>;
+    /**
+     * Generate a beat map from an audio URL
+     *
+     * Uses the Ellis Dynamic Programming beat tracking algorithm to detect
+     * beats and downbeats throughout the entire audio track.
+     *
+     * IMPORTANT: The typical workflow is to generate FIRST with default config,
+     * examine the beat map to identify the correct downbeat, then use
+     * reapplyDownbeatConfig() to set it. You usually don't know the correct
+     * downbeat until after seeing the generated beat map.
+     *
+     * @param audioUrl - URL of the audio file to analyze
+     * @param audioId - Unique identifier for the audio source
+     * @param options - Beat map generation options (optional)
+     * @param downbeatConfig - Optional manual downbeat configuration (defaults to beat 0 = downbeat, 4/4 time)
+     * @param onProgress - Optional progress callback for long-running analysis
+     * @returns Promise resolving to the generated beat map
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     * const beatMap = await analyzer.generateBeatMap('song.mp3', 'track-001', {
+     *   minBpm: 90,
+     *   maxBpm: 180,
+     *   dpAlpha: 680,
+     * });
+     * console.log(`Detected ${beatMap.beats.length} beats at ${beatMap.bpm} BPM`);
+     * ```
+     */
+    generateBeatMap(audioUrl: string, audioId: string, options?: BeatMapGeneratorOptions, downbeatConfig?: DownbeatConfig, onProgress?: ProgressCallback): Promise<BeatMap>;
+    /**
+     * Generate a beat map from an AudioBuffer
+     *
+     * Use this method when you already have the audio decoded.
+     *
+     * IMPORTANT: The typical workflow is to generate FIRST with default config,
+     * examine the beat map to identify the correct downbeat, then use
+     * reapplyDownbeatConfig() to set it. You usually don't know the correct
+     * downbeat until after seeing the generated beat map.
+     *
+     * @param audioBuffer - Decoded audio buffer
+     * @param audioId - Unique identifier for the audio source
+     * @param options - Beat map generation options (optional)
+     * @param downbeatConfig - Optional manual downbeat configuration (defaults to beat 0 = downbeat, 4/4 time)
+     * @param onProgress - Optional progress callback for long-running analysis
+     * @returns Promise resolving to the generated beat map
+     *
+     * @example
+     * ```typescript
+     * const audioBuffer = await analyzer.fetchAndDecodeAudio('song.mp3');
+     * const beatMap = await analyzer.generateBeatMapFromBuffer(audioBuffer, 'track-001');
+     * ```
+     */
+    generateBeatMapFromBuffer(audioBuffer: AudioBuffer, audioId: string, options?: BeatMapGeneratorOptions, downbeatConfig?: DownbeatConfig, onProgress?: ProgressCallback): Promise<BeatMap>;
+    /**
+     * Create a BeatStream for real-time beat event streaming
+     *
+     * The BeatStream emits beat events synchronized with audio playback,
+     * with configurable anticipation time for pre-rendering.
+     *
+     * @param beatMap - The beat map containing beat data
+     * @param audioContext - The Web Audio API AudioContext for timing
+     * @param options - Stream options (anticipation time, latency compensation, etc.)
+     * @returns BeatStream instance for subscribing to beat events
+     *
+     * @example
+     * ```typescript
+     * const beatStream = analyzer.createBeatStream(beatMap, audioContext, {
+     *   anticipationTime: 2.0,  // 2 seconds for animation pre-rendering
+     *   compensateOutputLatency: true,
+     * });
+     *
+     * const unsubscribe = beatStream.subscribe((event) => {
+     *   if (event.type === 'upcoming') {
+     *     // Pre-render beat visual
+     *   } else if (event.type === 'exact') {
+     *     // Beat is happening now
+     *   }
+     * });
+     *
+     * beatStream.start();
+     * ```
+     */
+    createBeatStream(beatMap: BeatMap, audioContext: AudioContext, options?: BeatStreamOptions): BeatStream;
+    /**
+     * Interpolate a beat map to fill gaps in detected beats
+     *
+     * This is a post-processing pass that runs AFTER BeatMap generation to fill
+     * gaps where detected beats are missing. Uses the Adaptive Phase-Locked Grid
+     * algorithm with dense section priority to determine the quarter note interval,
+     * then generates interpolated beats with tempo drift handling.
+     *
+     * @param beatMap - The beat map to interpolate
+     * @param options - Interpolation options (optional)
+     * @returns Interpolated beat map with two output streams
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     * const beatMap = await analyzer.generateBeatMap('song.mp3', 'track-001');
+     *
+     * // Interpolate with default options
+     * const interpolated = analyzer.interpolateBeatMap(beatMap);
+     *
+     * // Access original detected beats
+     * console.log(`Detected: ${interpolated.detectedBeats.length} beats`);
+     *
+     * // Access merged beats (interpolated + detected)
+     * console.log(`Total: ${interpolated.mergedBeats.length} beats`);
+     * ```
+     */
+    interpolateBeatMap(beatMap: BeatMap, options?: BeatInterpolationOptions): InterpolatedBeatMap;
+    /**
+     * Generate a beat map with interpolation in a single step
+     *
+     * Convenience method that combines beat map generation and interpolation.
+     * This is useful when you always want interpolated beats and don't need
+     * the intermediate BeatMap.
+     *
+     * @param audioUrl - URL of the audio file to analyze
+     * @param audioId - Unique identifier for the audio source
+     * @param beatMapOptions - Beat map generation options (optional)
+     * @param interpolationOptions - Interpolation options (optional)
+     * @param onProgress - Optional progress callback for long-running analysis
+     * @returns Promise resolving to the interpolated beat map
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     *
+     * // Generate with interpolation in one step
+     * const interpolated = await analyzer.generateBeatMapWithInterpolation(
+     *   'song.mp3',
+     *   'track-001',
+     *   { minBpm: 60, maxBpm: 180 }  // BeatMap options
+     * );
+     *
+     * console.log(`Total beats: ${interpolated.mergedBeats.length}`);
+     * console.log(`Quarter note: ${interpolated.quarterNoteBpm} BPM`);
+     * ```
+     */
+    generateBeatMapWithInterpolation(audioUrl: string, audioId: string, beatMapOptions?: BeatMapGeneratorOptions, downbeatConfig?: DownbeatConfig, interpolationOptions?: BeatInterpolationOptions, onProgress?: ProgressCallback): Promise<InterpolatedBeatMap>;
+    /**
+     * Generate a beat map with interpolation from an AudioBuffer in a single step
+     *
+     * Use this method when you already have the audio decoded and want
+     * interpolated beats in a single call.
+     *
+     * @param audioBuffer - Decoded audio buffer
+     * @param audioId - Unique identifier for the audio source
+     * @param beatMapOptions - Beat map generation options (optional)
+     * @param interpolationOptions - Interpolation options (optional)
+     * @param onProgress - Optional progress callback for long-running analysis
+     * @returns Promise resolving to the interpolated beat map
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     * const audioBuffer = await analyzer.fetchAndDecodeAudio('song.mp3');
+     *
+     * const interpolated = await analyzer.generateBeatMapWithInterpolationFromBuffer(
+     *   audioBuffer,
+     *   'track-001'
+     * );
+     * ```
+     */
+    generateBeatMapWithInterpolationFromBuffer(audioBuffer: AudioBuffer, audioId: string, beatMapOptions?: BeatMapGeneratorOptions, downbeatConfig?: DownbeatConfig, interpolationOptions?: BeatInterpolationOptions, onProgress?: ProgressCallback): Promise<InterpolatedBeatMap>;
+    /**
+     * Serialize a beat map to JSON string
+     *
+     * @param beatMap - Beat map to serialize
+     * @returns JSON string
+     */
+    static beatMapToJSON(beatMap: BeatMap): string;
+    /**
+     * Parse a beat map from JSON string
+     *
+     * @param jsonString - JSON string to parse
+     * @returns Beat map
+     */
+    static beatMapFromJSON(jsonString: string): BeatMap;
+    /**
+     * Save a beat map to a file (Node.js only)
+     *
+     * @param beatMap - Beat map to save
+     * @param filePath - Path to save to
+     */
+    static saveBeatMapToFile(beatMap: BeatMap, filePath: string): Promise<void>;
+    /**
+     * Load a beat map from a file (Node.js only)
+     *
+     * @param filePath - Path to load from
+     * @returns Beat map
+     */
+    static loadBeatMapFromFile(filePath: string): Promise<BeatMap>;
+    /**
+     * Generate procedural rhythm patterns from an audio URL
+     *
+     * This is a convenience method that combines the full pipeline:
+     * 1. Fetches and decodes the audio
+     * 2. Generates a beat map with interpolation
+     * 3. Unifies the beat map
+     * 4. Runs the RhythmGenerator to create difficulty variants
+     *
+     * @param audioUrl - URL of the audio file to analyze
+     * @param audioId - Unique identifier for the audio source
+     * @param options - Rhythm generation options (optional)
+     * @param beatMapOptions - Beat map generation options (optional)
+     * @param downbeatConfig - Optional manual downbeat configuration
+     * @param onProgress - Optional progress callback for rhythm generation
+     * @returns Promise resolving to the generated rhythm with difficulty variants
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     * const rhythm = await analyzer.generateRhythm('song.mp3', 'track-001', {
+     *   difficulty: 'medium',
+     *   outputMode: 'composite',
+     * });
+     *
+     * // Access difficulty variants
+     * const easyBeats = rhythm.difficultyVariants.easy.beats;
+     * const hardBeats = rhythm.difficultyVariants.hard.beats;
+     *
+     * // Access individual band streams
+     * const bassBeats = rhythm.bandStreams.low.beats;
+     * ```
+     */
+    generateRhythm(audioUrl: string, audioId: string, options?: RhythmGenerationOptions, beatMapOptions?: BeatMapGeneratorOptions, downbeatConfig?: DownbeatConfig, onProgress?: (phase: string, progress: number, message: string) => void): Promise<GeneratedRhythm>;
+    /**
+     * Generate procedural rhythm patterns from an AudioBuffer
+     *
+     * Use this method when you already have the audio decoded.
+     * This combines beat map generation, interpolation, unification,
+     * and rhythm generation in a single call.
+     *
+     * @param audioBuffer - Decoded audio buffer
+     * @param audioId - Unique identifier for the audio source
+     * @param options - Rhythm generation options (optional)
+     * @param beatMapOptions - Beat map generation options (optional)
+     * @param downbeatConfig - Optional manual downbeat configuration
+     * @param onProgress - Optional progress callback for rhythm generation
+     * @returns Promise resolving to the generated rhythm with difficulty variants
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     * const audioBuffer = await analyzer.fetchAndDecodeAudio('song.mp3');
+     *
+     * const rhythm = await analyzer.generateRhythmFromBuffer(
+     *   audioBuffer,
+     *   'track-001',
+     *   { difficulty: 'hard' }
+     * );
+     *
+     * console.log(`Generated ${rhythm.difficultyVariants.hard.beats.length} beats`);
+     * ```
+     */
+    generateRhythmFromBuffer(audioBuffer: AudioBuffer, audioId: string, options?: RhythmGenerationOptions, beatMapOptions?: BeatMapGeneratorOptions, downbeatConfig?: DownbeatConfig, onProgress?: (phase: string, progress: number, message: string) => void): Promise<GeneratedRhythm>;
+    /**
+     * Generate a complete rhythm game level from an audio URL
+     *
+     * This is the main convenience method that combines:
+     * 1. Fetches and decodes the audio
+     * 2. Generates a beat map with interpolation
+     * 3. Unifies the beat map
+     * 4. Runs rhythm generation
+     * 5. Runs pitch analysis (if pitchInfluenceWeight > 0)
+     * 6. Maps buttons to beats
+     * 7. Converts to ChartedBeatMap
+     *
+     * @param audioUrl - URL of the audio file to analyze
+     * @param audioId - Unique identifier for the audio source
+     * @param options - Level generation options (difficulty, controller mode, etc.)
+     * @param beatMapOptions - Beat map generation options (optional)
+     * @param downbeatConfig - Optional manual downbeat configuration
+     * @param onProgress - Optional callback for progress updates
+     * @returns Promise resolving to the generated level with playable chart
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     * const level = await analyzer.generateRhythmLevel('song.mp3', 'track-001', {
+     *   difficulty: 'medium',
+     *   controllerMode: 'ddr',
+     *   buttons: { pitchInfluenceWeight: 0.8 }
+     * });
+     *
+     * // Use the chart with BeatStream
+     * const beatStream = new BeatStream(level.chart, audioContext);
+     *
+     * // Access metadata
+     * console.log(`Generated ${level.metadata.chartMetadata.totalBeats} beats`);
+     * console.log(`Pitch influenced: ${level.metadata.buttonMetadata.pitchInfluencedBeats} beats`);
+     * ```
+     */
+    generateRhythmLevel(audioUrl: string, audioId: string, options: LevelGenerationOptions, beatMapOptions?: BeatMapGeneratorOptions, downbeatConfig?: DownbeatConfig, onProgress?: LevelProgressCallback): Promise<GeneratedLevel>;
+    /**
+     * Generate a complete rhythm game level from an AudioBuffer
+     *
+     * Use this method when you already have the audio decoded.
+     * This combines all generation phases in a single call.
+     *
+     * @param audioBuffer - Decoded audio buffer
+     * @param audioId - Unique identifier for the audio source
+     * @param options - Level generation options (difficulty, controller mode, etc.)
+     * @param beatMapOptions - Beat map generation options (optional)
+     * @param downbeatConfig - Optional manual downbeat configuration
+     * @param onProgress - Optional callback for progress updates
+     * @returns Promise resolving to the generated level with playable chart
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     * const audioBuffer = await analyzer.fetchAndDecodeAudio('song.mp3');
+     *
+     * const level = await analyzer.generateRhythmLevelFromBuffer(
+     *   audioBuffer,
+     *   'track-001',
+     *   {
+     *     difficulty: 'hard',
+     *     controllerMode: 'guitar_hero',
+     *     buttons: { pitchInfluenceWeight: 1.0 }
+     *   }
+     * );
+     *
+     * console.log(`Chart has ${level.chart.beats.length} beats`);
+     * ```
+     */
+    generateRhythmLevelFromBuffer(audioBuffer: AudioBuffer, audioId: string, options: LevelGenerationOptions, beatMapOptions?: BeatMapGeneratorOptions, downbeatConfig?: DownbeatConfig, onProgress?: LevelProgressCallback): Promise<GeneratedLevel>;
+    /**
+     * Preset name for level generation configurations
+     */
+    static LEVEL_PRESETS: {
+        casual: {
+            difficulty: "easy";
+            controllerMode: ControllerMode;
+            buttons: {
+                pitchInfluenceWeight: number;
+            };
+            description: string;
+        };
+        standard: {
+            difficulty: "medium";
+            controllerMode: ControllerMode;
+            buttons: {
+                pitchInfluenceWeight: number;
+            };
+            description: string;
+        };
+        challenge: {
+            difficulty: "hard";
+            controllerMode: ControllerMode;
+            buttons: {
+                pitchInfluenceWeight: number;
+            };
+            description: string;
+        };
+        insane: {
+            difficulty: "hard";
+            controllerMode: ControllerMode;
+            buttons: {
+                pitchInfluenceWeight: number;
+                consecutiveSameKeyLimit: number;
+            };
+            description: string;
+        };
+    };
+    /**
+     * Generate a rhythm game level using a preset configuration
+     *
+     * Quick generation method that uses predefined settings for common use cases.
+     *
+     * @param audioUrl - URL of the audio file to analyze
+     * @param audioId - Unique identifier for the audio source
+     * @param preset - Preset name: 'casual', 'standard', 'challenge', or 'insane'
+     * @param beatMapOptions - Beat map generation options (optional)
+     * @param downbeatConfig - Optional manual downbeat configuration
+     * @param onProgress - Optional callback for progress updates
+     * @returns Promise resolving to the generated level with playable chart
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     *
+     * // Quick casual level
+     * const casualLevel = await analyzer.generateRhythmLevelWithPreset(
+     *   'song.mp3',
+     *   'track-001',
+     *   'casual'
+     * );
+     *
+     * // Quick challenge level
+     * const challengeLevel = await analyzer.generateRhythmLevelWithPreset(
+     *   'song.mp3',
+     *   'track-001',
+     *   'challenge'
+     * );
+     *
+     * // List available presets
+     * console.log(AudioAnalyzer.LEVEL_PRESETS);
+     * ```
+     */
+    generateRhythmLevelWithPreset(audioUrl: string, audioId: string, preset: 'casual' | 'standard' | 'challenge' | 'insane', beatMapOptions?: BeatMapGeneratorOptions, downbeatConfig?: DownbeatConfig, onProgress?: LevelProgressCallback): Promise<GeneratedLevel>;
+    /**
+     * Generate a rhythm game level using a preset configuration from an AudioBuffer
+     *
+     * Use this method when you already have the audio decoded.
+     *
+     * @param audioBuffer - Decoded audio buffer
+     * @param audioId - Unique identifier for the audio source
+     * @param preset - Preset name: 'casual', 'standard', 'challenge', or 'insane'
+     * @param beatMapOptions - Beat map generation options (optional)
+     * @param downbeatConfig - Optional manual downbeat configuration
+     * @param onProgress - Optional callback for progress updates
+     * @returns Promise resolving to the generated level with playable chart
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     * const audioBuffer = await analyzer.fetchAndDecodeAudio('song.mp3');
+     *
+     * const level = await analyzer.generateRhythmLevelWithPresetFromBuffer(
+     *   audioBuffer,
+     *   'track-001',
+     *   'standard'
+     * );
+     * ```
+     */
+    generateRhythmLevelWithPresetFromBuffer(audioBuffer: AudioBuffer, audioId: string, preset: 'casual' | 'standard' | 'challenge' | 'insane', beatMapOptions?: BeatMapGeneratorOptions, downbeatConfig?: DownbeatConfig, onProgress?: LevelProgressCallback): Promise<GeneratedLevel>;
+    /**
+     * Fetch and decode audio from a URL
+     *
+     * This is a convenience method for fetching audio when you need
+     * to reuse the decoded buffer for multiple operations.
+     *
+     * @param audioUrl - URL of the audio file
+     * @returns Promise resolving to the decoded AudioBuffer
+     *
+     * @example
+     * ```typescript
+     * const analyzer = new AudioAnalyzer();
+     * const audioBuffer = await analyzer.fetchAndDecodeAudio('song.mp3');
+     *
+     * // Reuse buffer for multiple analyses
+     * const profile = await analyzer.extractSonicFingerprint('song.mp3');
+     * const rhythm = await analyzer.generateRhythmFromBuffer(audioBuffer, 'track-001');
+     * ```
+     */
+    fetchAndDecodeAudio(audioUrl: string): Promise<AudioBuffer>;
+    /**
+     * Shared logic to fetch and decode audio from a URL
+     */
+    private fetchAndDecode;
+    /**
+     * Analyze audio at a specific position
+     */
+    private analyzeAtPosition;
+    /**
+     * Extract audio segment from buffer
+     *
+     * Mixes all channels down to mono and extracts the specified sample range.
+     * Made protected to allow beat detection classes to access audio data.
+     */
+    protected extractAudioSegment(audioBuffer: AudioBuffer, startSample: number, endSample: number): Float32Array;
+    /**
+     * Simple FFT implementation for frequency analysis
+     * Uses Cooley-Tukey algorithm
+     *
+     * Made protected to allow beat detection classes to access FFT functionality.
+     */
+    protected performFFT(signal: Float32Array, fftSize: number): number[];
+    /**
+     * Cooley-Tukey FFT algorithm
+     */
+    private fft;
+    /**
+     * Average frequency bands across multiple samples
+     */
+    private averageFrequencyBands;
+    /**
+     * Calculate average amplitude across all channels
+     */
+    private calculateAverageAmplitude;
+    /**
+     * Calculate RMS (Root Mean Square) energy - more representative of perceived loudness
+     */
+    private calculateRMS;
+    /**
+     * Calculate Peak amplitude
+     */
+    private calculatePeak;
+    /**
+     * Calculate spectral centroid (brightness)
+     */
+    private calculateSpectralCentroid;
+    /**
+     * Calculate spectral rolloff (frequency below which 85% of energy is contained)
+     */
+    private calculateSpectralRolloff;
+    /**
+     * Calculate zero crossing rate (measure of noisiness/percussiveness)
+     */
+    private calculateZeroCrossingRate;
+}
+//# sourceMappingURL=AudioAnalyzer.d.ts.map

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

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

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

@@ -0,0 +1,64 @@
+import type { ColorPalette } from '../types/AudioProfile';
+/**
+ * Configuration options for ColorExtractor.
+ *
+ * Gateway resolution is automatic - Arweave URLs are resolved with fallback
+ * using the default arweaveGatewayManager. No configuration needed.
+ */
+export interface ColorExtractorOptions {
+}
+/**
+ * Extract color palettes from images using k-means and median-cut algorithms
+ * Analyzes image pixels to identify dominant colors and brightness characteristics
+ */
+export declare class ColorExtractor {
+    private canvas;
+    private context;
+    /**
+     * Initialize ColorExtractor with canvas for image processing
+     * Canvas is only created in browser environments (safe for Node.js)
+     *
+     * @param _options - Configuration options (reserved for future use)
+     */
+    constructor(_options?: ColorExtractorOptions);
+    /**
+     * Extract dominant colors from image URL
+     *
+     * Applies k-means clustering (primary) or median-cut (fallback) to identify
+     * the 4 most representative colors in the image. Analyzes color frequency,
+     * brightness, saturation, and monochrome characteristics.
+     *
+     * Arweave URLs are automatically resolved with gateway fallback via
+     * arweaveGatewayManager.resolveUrl - no configuration needed.
+     *
+     * @param {string} imageUrl - URL of the image to analyze
+     * @returns {Promise<ColorPalette>} Color palette with dominant colors and characteristics
+     * @throws {Error} If canvas is not supported in the environment
+     *
+     * @example
+     * const extractor = new ColorExtractor();
+     * const palette = await extractor.extractPalette('https://example.com/image.jpg');
+     * console.log(`Primary color: ${palette.primary_color}`);
+     */
+    extractPalette(imageUrl: string): Promise<ColorPalette>;
+    private loadImage;
+    private getPixels;
+    /**
+     * K-means clustering algorithm for color quantization
+     */
+    private kMeans;
+    /**
+     * Median cut algorithm for color quantization (fallback)
+     */
+    private medianCut;
+    private getBoxRange;
+    private sortPixelsByChannel;
+    private distance;
+    private sortColorsByFrequency;
+    private analyzePalette;
+    private getBrightness;
+    private getSaturation;
+    private rgbToHex;
+    private getFallbackPalette;
+}
+//# sourceMappingURL=ColorExtractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ColorExtractor.d.ts","sourceRoot":"","sources":["../../../src/core/analysis/ColorExtractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1D;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;CAErC;AAED;;;GAGG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,OAAO,CAAyC;IAExD;;;;;OAKG;gBACS,QAAQ,GAAE,qBAA0B;IAUhD;;;;;;;;;;;;;;;;;;OAkBG;IACU,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgCpE,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,SAAS;IAcjB;;OAEG;IACH,OAAO,CAAC,MAAM;IA6Dd;;OAEG;IACH,OAAO,CAAC,SAAS;IAsDjB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,qBAAqB;IAyB7B,OAAO,CAAC,cAAc;IA2BtB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,kBAAkB;CAW7B"}