playlist-data-engine 1.1.0

package/dist/core/types/BeatMap.d.ts

@@ -0,0 +1,1825 @@
+/**
+ * Beat Detection type definitions
+ *
+ * Based on the Ellis Dynamic Programming beat tracking algorithm
+ * Reference: "Beat Tracking by Dynamic Programming" (Ellis, 2007)
+ */
+/**
+ * Represents a single detected beat in the audio
+ */
+export interface Beat {
+    /** Timestamp in seconds from the start of the audio */
+    timestamp: number;
+    /** Position within the measure (0 = downbeat, 1, 2, 3, etc. for subsequent beats) */
+    beatInMeasure: number;
+    /** Whether this beat is a downbeat (first beat of a measure) */
+    isDownbeat: boolean;
+    /** Measure number (0-indexed from first detected downbeat) */
+    measureNumber: number;
+    /** Onset strength at this beat (0.0 - 1.0, normalized) */
+    intensity: number;
+    /** Confidence score for this beat detection (0.0 - 1.0) */
+    confidence: number;
+    /**
+     * Optional required key for rhythm game chart creation.
+     * When specified, this key must be pressed for the beat to count as a hit.
+     * Frontend maps physical inputs to these strings before calling the engine.
+     * @example 'up', 'down', 'left', 'right', 'a', 'b', 'x', 'y'
+     */
+    requiredKey?: string;
+}
+/**
+ * Time signature configuration for beat grid
+ * Defaults to 4/4 time if not specified
+ */
+export interface TimeSignatureConfig {
+    /** Number of beats per measure (default: 4 for 4/4 time) */
+    beatsPerMeasure: number;
+}
+/** Default time signature (4/4) */
+export declare const DEFAULT_TIME_SIGNATURE: TimeSignatureConfig;
+/**
+ * A segment of downbeat configuration
+ * Used to support time signature changes within a track
+ *
+ * Segments are CONTIGUOUS - each segment covers all beats from its startBeat
+ * until the next segment's startBeat (or end of track). There are no gaps.
+ *
+ * Example: If segment 1 has startBeat: 0 and segment 2 has startBeat: 32,
+ * then segment 1 covers beats 0-31 and segment 2 covers beats 32+.
+ */
+export interface DownbeatSegment {
+    /**
+     * Beat index where this segment starts
+     * The first segment should typically have startBeat: 0
+     */
+    startBeat: number;
+    /**
+     * Beat index that represents the "one" (downbeat) in this segment
+     * This is an absolute beat index, not relative to startBeat
+     *
+     * Example: If set to 9 with beatsPerMeasure: 4, then beats 1, 5, 9, 13, 17... are downbeats
+     * (calculated bidirectionally from beat 9)
+     */
+    downbeatBeatIndex: number;
+    /** Time signature for this segment */
+    timeSignature: TimeSignatureConfig;
+}
+/**
+ * Downbeat configuration for manual placement
+ * Supports multiple segments for time signature changes within a track
+ */
+export interface DownbeatConfig {
+    /**
+     * Array of downbeat segments
+     * - For simple tracks: single segment with startBeat: 0
+     * - For time signature changes: multiple segments ordered by startBeat
+     *
+     * Each segment defines its own downbeat anchor and time signature.
+     * The downbeatBeatIndex is absolute (not relative to segment start).
+     */
+    segments: DownbeatSegment[];
+}
+/** Default downbeat config (first beat is the one, 4/4 time) */
+export declare const DEFAULT_DOWNBEAT_CONFIG: DownbeatConfig;
+/** Minimum beats per measure */
+export declare const MIN_BEATS_PER_MEASURE = 2;
+/** Maximum beats per measure */
+export declare const MAX_BEATS_PER_MEASURE = 12;
+/**
+ * Validate downbeat configuration (structural validation only)
+ *
+ * Note: Beat count validation (e.g., downbeatBeatIndex < totalBeats) happens
+ * inside generateBeatMap() AFTER beat detection, since we don't know the
+ * total beat count until then.
+ *
+ * @param config - The downbeat configuration to validate
+ * @throws Error if configuration is invalid
+ */
+export declare function validateDownbeatConfig(config: DownbeatConfig): void;
+/**
+ * Validate downbeat config against actual beat count
+ * Called inside generateBeatMap() after beat detection
+ *
+ * @param config - The downbeat configuration to validate
+ * @param totalBeats - The total number of beats in the beat map
+ * @throws Error if downbeatBeatIndex exceeds total beats
+ */
+export declare function validateDownbeatConfigAgainstBeats(config: DownbeatConfig, totalBeats: number): void;
+/**
+ * Reapply downbeat configuration to recalculate measure labels
+ *
+ * This is the PRIMARY way to set downbeat configuration. The typical workflow is:
+ * 1. Generate beat map with default config
+ * 2. Examine the beat map to identify the correct downbeat position
+ * 3. Call this function to apply the correct configuration
+ *
+ * This does NOT re-analyze audio - it only recalculates measure labels.
+ *
+ * @param beatMap - The original beat map
+ * @param newConfig - New downbeat configuration to apply
+ * @returns New BeatMap with updated measure labels (original is not modified)
+ * @throws Error if configuration is invalid or downbeatBeatIndex exceeds total beats
+ *
+ * @example
+ * ```typescript
+ * // Generate first, then configure
+ * const beatMap = await generator.generateBeatMap('song.mp3', 'track-1');
+ *
+ * // After examining, you identify beat 9 as the downbeat
+ * const correctedMap = reapplyDownbeatConfig(beatMap, {
+ *   segments: [{
+ *     startBeat: 0,
+ *     downbeatBeatIndex: 9,  // Beat 9 is the "one"
+ *     timeSignature: { beatsPerMeasure: 4 },
+ *   }],
+ * });
+ * // Beats 1, 5, 9, 13, 17... are now downbeats
+ * ```
+ */
+export declare function reapplyDownbeatConfig(beatMap: BeatMap, newConfig: DownbeatConfig): BeatMap;
+/**
+ * Metadata about the beat detection algorithm and settings used
+ */
+export interface BeatMapMetadata {
+    /** Version of the beat detection algorithm */
+    version: string;
+    /** Algorithm name (e.g., 'ellis-dp-v1') */
+    algorithm: string;
+    /** Minimum BPM threshold used during detection */
+    minBpm: number;
+    /** Maximum BPM threshold used during detection */
+    maxBpm: number;
+    /** Pre-processing sensitivity used (0.1 - 10.0) */
+    sensitivity: number;
+    /** Post-processing grid-alignment filter used (0.0 - 1.0) */
+    filter: number;
+    /** Noise floor threshold for filtering low-energy detections */
+    noiseFloorThreshold: number;
+    /** Milliseconds between FFT frames */
+    hopSizeMs: number;
+    /** FFT window size in samples */
+    fftSize: number;
+    /** Ellis balance factor (alpha) for tempo consistency vs onset strength */
+    dpAlpha: number;
+    /** Number of Mel frequency bands for onset strength envelope */
+    melBands: number;
+    /** High-pass filter cutoff in Hz for onset strength envelope */
+    highPassCutoff: number;
+    /** Gaussian smoothing window in ms for onset strength envelope */
+    gaussianSmoothMs: number;
+    /** Tempo center in seconds (default 0.5s = 120 BPM) */
+    tempoCenter: number;
+    /** Tempo width in octaves for perception weighting */
+    tempoWidth: number;
+    /** Whether TPS2 octave resolution was enabled for duple meter detection */
+    useOctaveResolution: boolean;
+    /** Whether TPS3 triple meter resolution was enabled for 3/4, 6/8 detection */
+    useTripleMeter: boolean;
+    /** Timestamp when the beat map was generated */
+    generatedAt: string;
+}
+/**
+ * Complete beat map for a single audio track
+ *
+ * Contains all detected beats and metadata. BPM is calculated dynamically
+ * during playback from actual beat intervals, not stored as a static value.
+ */
+export interface BeatMap {
+    /** Unique identifier for the audio source */
+    audioId: string;
+    /** Duration of the audio in seconds */
+    duration: number;
+    /** Array of all detected beats */
+    beats: Beat[];
+    /** Initial BPM estimate from tempo detection */
+    bpm: number;
+    /** Algorithm metadata and settings */
+    metadata: BeatMapMetadata;
+    /**
+     * The downbeat configuration used to generate this beat map
+     * Only stored if explicitly provided; undefined means default (beat 0 = downbeat, 4/4 time)
+     * Stored for reproducibility and reprocessing
+     */
+    downbeatConfig?: DownbeatConfig;
+}
+/**
+ * Event types emitted by the BeatStream during playback
+ */
+export type BeatEventType = 'upcoming' | 'exact' | 'passed';
+/**
+ * Event emitted by the BeatStream during playback
+ */
+export interface BeatEvent {
+    /** The beat this event relates to */
+    beat: Beat;
+    /** Current BPM calculated from recent beat intervals */
+    currentBpm: number;
+    /** Current audio context time in seconds */
+    audioTime: number;
+    /** Time until the beat occurs (negative if passed) */
+    timeUntilBeat: number;
+    /** Type of event: 'upcoming', 'exact', or 'passed' */
+    type: BeatEventType;
+}
+/**
+ * Callback function type for BeatStream subscriptions
+ */
+export type BeatStreamCallback = (event: BeatEvent) => void;
+/**
+ * Audio synchronization state for debugging and monitoring
+ */
+export interface AudioSyncState {
+    /** Current audio context time in seconds */
+    audioContextTime: number;
+    /** Audio element current time in seconds */
+    audioElementTime: number;
+    /** Calculated drift between audio and beat stream */
+    drift: number;
+    /** Whether the sync is within acceptable tolerance */
+    isSynchronized: boolean;
+    /** Output latency from AudioContext (0 if unsupported) */
+    outputLatency: number;
+    /** Base latency from AudioContext (0 if unsupported) */
+    baseLatency: number;
+    /** User-calibrated offset in milliseconds */
+    userOffsetMs: number;
+    /** Total effective latency compensation in seconds */
+    totalCompensation: number;
+}
+/**
+ * Options for BeatMapGenerator
+ *
+ * ## OSE Parameter Modes
+ *
+ * OSE parameters support two configuration styles:
+ * - **Mode-based**: Use `hopSizeMode`, `melBandsMode`, `gaussianSmoothMode` for preset values
+ * - **Direct numeric**: Use `hopSizeMs`, `melBands`, `gaussianSmoothMs` for exact control
+ *
+ * **Precedence**: When both mode and direct value are provided, mode takes precedence.
+ *
+ * @example
+ * ```typescript
+ * // Mode-based configuration (recommended)
+ * const options: BeatMapGeneratorOptions = {
+ *   hopSizeMode: { mode: 'standard' },      // 4ms (Ellis 2007 paper spec)
+ *   melBandsMode: { mode: 'detailed' },     // 64 bands
+ *   gaussianSmoothMode: { mode: 'smooth' }  // 40ms
+ * };
+ *
+ * // Direct numeric configuration (backward compatible)
+ * const options: BeatMapGeneratorOptions = {
+ *   hopSizeMs: 4,
+ *   melBands: 40,
+ *   gaussianSmoothMs: 20
+ * };
+ * ```
+ */
+export interface BeatMapGeneratorOptions {
+    /** Minimum BPM to detect (default: 90) */
+    minBpm?: number;
+    /** Maximum BPM to detect (default: 180) */
+    maxBpm?: number;
+    /** Pre-processing sensitivity (0.1-10.0, default: 1.0) */
+    sensitivity?: number;
+    /** Post-processing grid-alignment filter (0.0-1.0, default: 0.0) */
+    filter?: number;
+    /** Minimum threshold to prevent noise detection (default: 0) */
+    noiseFloorThreshold?: number;
+    /**
+     * Milliseconds between FFT frames (default: 4).
+     * Ignored if hopSizeMode is provided.
+     * @see hopSizeMode for mode-based configuration
+     */
+    hopSizeMs?: number;
+    /** FFT window size in samples (default: 2048) */
+    fftSize?: number;
+    /** Number of beats for rolling BPM calculation (default: 8) */
+    rollingBpmWindowSize?: number;
+    /**
+     * Ellis balance factor for tempo consistency vs onset strength (default: 680)
+     * Higher values = stricter tempo adherence (good for songs with clear beats)
+     * Lower values = more flexibility for songs with weak/irregular beats
+     */
+    dpAlpha?: number;
+    /**
+     * Number of Mel frequency bands for OSE (default: 40).
+     * Ignored if melBandsMode is provided.
+     * @see melBandsMode for mode-based configuration
+     */
+    melBands?: number;
+    /** High-pass filter cutoff in Hz, removes DC offset from OSE (default: 0.4) */
+    highPassCutoff?: number;
+    /**
+     * Gaussian smoothing window in ms for OSE (default: 20).
+     * Ignored if gaussianSmoothMode is provided.
+     * @see gaussianSmoothMode for mode-based configuration
+     */
+    gaussianSmoothMs?: number;
+    /** Tempo center in seconds for perception bias (default: 0.5 = 120 BPM) */
+    tempoCenter?: number;
+    /** Tempo width in octaves for perception weighting (default: 1.4) */
+    tempoWidth?: number;
+    /**
+     * Whether to use TPS2 octave resolution to prevent half-tempo/double-tempo ambiguity.
+     *
+     * When enabled, uses the Ellis TPS2 calculation (Equation 7) to prefer tempos
+     * with strong half-period evidence, improving accuracy from 77% to 84%.
+     *
+     * This helps prevent the algorithm from locking onto 73 BPM when the true tempo
+     * is 146 BPM (octave error).
+     *
+     * Default: false (opt-in for now)
+     */
+    useOctaveResolution?: boolean;
+    /**
+     * Whether to use TPS3 triple meter resolution for 3/4, 6/8 time signatures.
+     *
+     * When enabled, uses the Ellis TPS3 calculation (Equation 7 variant) to prefer tempos
+     * with strong third-period evidence, improving detection for waltzes and triple meter music.
+     *
+     * The TPS3 formula combines the main tempo with its third-harmonic:
+     * `TPS3(τ) = TPS(τ) + 0.33×TPS(3τ) + 0.33×TPS(3τ-1) + 0.33×TPS(3τ+1)`
+     *
+     * Tempos with strong third-period evidence (indicating triple meter) will have
+     * higher TPS3 scores, allowing proper beat detection for waltzes and 6/8 shuffles.
+     *
+     * Default: false (opt-in for triple meter music)
+     */
+    useTripleMeter?: boolean;
+    /**
+     * Hop size mode configuration.
+     * Takes precedence over hopSizeMs when both are provided.
+     * @default { mode: 'standard' } (4ms)
+     */
+    hopSizeMode?: HopSizeConfig;
+    /**
+     * Mel bands mode configuration.
+     * Takes precedence over melBands when both are provided.
+     * @default { mode: 'standard' } (40 bands)
+     */
+    melBandsMode?: MelBandsConfig;
+    /**
+     * Gaussian smooth mode configuration.
+     * Takes precedence over gaussianSmoothMs when both are provided.
+     * @default { mode: 'standard' } (20ms)
+     */
+    gaussianSmoothMode?: GaussianSmoothConfig;
+}
+/**
+ * Options for BeatStream configuration
+ */
+export interface BeatStreamOptions {
+    /** Time before beat to emit 'upcoming' event in seconds (default: 2.0) */
+    anticipationTime?: number;
+    /** Player-calibrated audio/visual offset in milliseconds (default: 0) */
+    userOffsetMs?: number;
+    /**
+     * Auto-adjust using AudioContext.outputLatency (default: true)
+     * Gracefully falls back to 0 if unsupported (e.g., Safari/older browsers)
+     */
+    compensateOutputLatency?: boolean;
+    /** Timing tolerance for synchronization in seconds (default: 0.01 = 10ms) */
+    timingTolerance?: number;
+    /**
+     * Difficulty preset for accuracy thresholds (default: 'medium')
+     * Ignored if customThresholds is provided.
+     */
+    difficultyPreset?: DifficultyPreset;
+    /**
+     * Custom accuracy thresholds (in seconds)
+     * If provided, overrides difficultyPreset.
+     */
+    customThresholds?: Partial<AccuracyThresholds>;
+    /**
+     * Use interpolated beats from InterpolatedBeatMap (default: false)
+     * If true and an InterpolatedBeatMap is provided to the BeatStream constructor,
+     * the stream will use mergedBeats (interpolated + detected) instead of
+     * the original detectedBeats.
+     *
+     * This allows seamless use of beat interpolation without modifying the BeatMap.
+     *
+     * @example
+     * ```typescript
+     * // With interpolation
+     * const interpolatedMap = interpolator.interpolate(beatMap);
+     * const beatStream = new BeatStream(interpolatedMap, audioContext, {
+     *     useInterpolatedBeats: true  // Use mergedBeats
+     * });
+     *
+     * // Without interpolation (original behavior)
+     * const beatStream = new BeatStream(beatMap, audioContext, {
+     *     useInterpolatedBeats: false  // Use beats array
+     * });
+     * ```
+     */
+    useInterpolatedBeats?: boolean;
+    /**
+     * Ignore required key assignments on beats (default: false)
+     * When true, beats with requiredKey will use timing-only evaluation,
+     * ignoring key matching. Useful for "easy mode" gameplay.
+     *
+     * When false (default), if a beat has a requiredKey:
+     * - Correct key: timing-based accuracy (perfect/great/good/ok/miss)
+     * - Wrong key: accuracy becomes 'wrongKey' regardless of timing
+     * - No key provided: treated as 'miss'
+     */
+    ignoreKeyRequirements?: boolean;
+}
+/**
+ * Accuracy levels for button press detection
+ */
+export type BeatAccuracy = 'perfect' | 'great' | 'good' | 'ok' | 'miss' | 'wrongKey';
+/**
+ * Accuracy thresholds for button press detection (in seconds)
+ * Used to configure difficulty levels for rhythm games.
+ */
+export interface AccuracyThresholds {
+    /** Perfect: within this threshold (seconds) */
+    perfect: number;
+    /** Great: within this threshold (seconds) */
+    great: number;
+    /** Good: within this threshold (seconds) */
+    good: number;
+    /** Ok: within this threshold (seconds) */
+    ok: number;
+}
+/**
+ * Preset difficulty levels for accuracy thresholds
+ *
+ * - 'easy': Forgiving timing, simplified rhythm
+ * - 'medium': Balanced timing and rhythm
+ * - 'hard': Tight timing, full rhythm density
+ * - 'natural': Unedited composite stream (what was actually detected in the audio)
+ * - 'custom': User-defined settings
+ */
+export type DifficultyPreset = 'easy' | 'medium' | 'hard' | 'natural' | 'custom';
+/**
+ * Easy difficulty thresholds (forgiving)
+ */
+export declare const EASY_ACCURACY_THRESHOLDS: AccuracyThresholds;
+/**
+ * Medium difficulty thresholds (balanced)
+ */
+export declare const MEDIUM_ACCURACY_THRESHOLDS: AccuracyThresholds;
+/**
+ * Hard difficulty thresholds (strict - for veterans)
+ */
+export declare const HARD_ACCURACY_THRESHOLDS: AccuracyThresholds;
+/**
+ * Natural difficulty thresholds (same as hard - unedited composite)
+ */
+export declare const NATURAL_ACCURACY_THRESHOLDS: AccuracyThresholds;
+/**
+ * Result of a button press accuracy check
+ */
+export interface ButtonPressResult {
+    /** Accuracy level of the press */
+    accuracy: BeatAccuracy;
+    /** Time difference from nearest beat in seconds (negative = early, positive = late) */
+    offset: number;
+    /** The beat that was matched (nearest beat to the press) */
+    matchedBeat: Beat;
+    /** Absolute time difference in seconds */
+    absoluteOffset: number;
+    /**
+     * Whether the pressed key matched the required key (if any).
+     * True if: no key required, or pressedKey matches requiredKey.
+     * False if: key required but wrong key pressed (accuracy will be 'wrongKey').
+     */
+    keyMatch: boolean;
+    /**
+     * The key that was pressed (passed to checkButtonPress).
+     * Undefined if no key was provided.
+     */
+    pressedKey?: string;
+    /**
+     * The required key from the matched beat (convenience copy).
+     * Undefined if the beat has no required key.
+     */
+    requiredKey?: string;
+}
+/**
+ * JSON-serializable version of BeatMap
+ *
+ * Identical to BeatMap but ensures all values are JSON-safe
+ * for serialization/deserialization operations
+ */
+export interface BeatMapJSON {
+    audioId: string;
+    duration: number;
+    beats: Array<{
+        timestamp: number;
+        beatInMeasure: number;
+        isDownbeat: boolean;
+        measureNumber: number;
+        intensity: number;
+        confidence: number;
+        requiredKey?: string;
+    }>;
+    bpm: number;
+    metadata: BeatMapMetadata;
+    /**
+     * The downbeat configuration used to generate this beat map
+     * Only stored if explicitly provided; undefined means default (beat 0 = downbeat, 4/4 time)
+     * Stored for reproducibility and reprocessing
+     */
+    downbeatConfig?: DownbeatConfig;
+}
+/**
+ * JSON-serializable version of BeatWithSource
+ */
+export interface BeatWithSourceJSON {
+    timestamp: number;
+    beatInMeasure: number;
+    isDownbeat: boolean;
+    measureNumber: number;
+    intensity: number;
+    confidence: number;
+    requiredKey?: string;
+    source: BeatSource;
+    distanceToAnchor?: number;
+    nearestAnchorTimestamp?: number;
+}
+/**
+ * JSON-serializable version of QuarterNoteDetection
+ */
+export interface QuarterNoteDetectionJSON {
+    intervalSeconds: number;
+    bpm: number;
+    confidence: number;
+    histogramPeak: number;
+    secondaryPeaks: number[];
+    method: 'histogram' | 'kde' | 'tempo-detector-fallback';
+    denseSectionCount: number;
+    denseSectionBeats: number;
+}
+/**
+ * JSON-serializable version of GapAnalysis
+ */
+export interface GapAnalysisJSON {
+    totalGaps: number;
+    halfNoteGaps: number;
+    anomalies: number[];
+    avgGapSize: number;
+    gridAlignmentScore: number;
+}
+/**
+ * JSON-serializable version of TempoSection
+ */
+export interface TempoSectionJSON {
+    start: number;
+    end: number;
+    bpm: number;
+    intervalSeconds: number;
+    beatCount: number;
+    startBeatIndex: number;
+    endBeatIndex: number;
+}
+/**
+ * JSON-serializable version of InterpolationMetadata
+ */
+export interface InterpolationMetadataJSON {
+    quarterNoteDetection: QuarterNoteDetectionJSON;
+    gapAnalysis: GapAnalysisJSON;
+    detectedBeatCount: number;
+    interpolatedBeatCount: number;
+    totalBeatCount: number;
+    interpolationRatio: number;
+    avgInterpolatedConfidence: number;
+    tempoDriftRatio: number;
+    /** Tempos found during normal analysis (e.g., [128, 140]) */
+    detectedClusterTempos?: number[];
+    /** Quick flag for checking if multi-tempo re-analysis is available */
+    hasMultipleTempos: boolean;
+    /** Full section data (only after multi-tempo re-analysis) */
+    tempoSections?: TempoSectionJSON[];
+    /** True only after multi-tempo re-analysis completes */
+    hasMultiTempoApplied?: boolean;
+}
+/**
+ * JSON-serializable version of InterpolatedBeatMap
+ *
+ * Ensures all values are JSON-safe for serialization/deserialization operations.
+ * Use with BeatInterpolator.toJSON() and BeatInterpolator.fromJSON() methods.
+ */
+export interface InterpolatedBeatMapJSON {
+    audioId: string;
+    duration: number;
+    detectedBeats: Array<{
+        timestamp: number;
+        beatInMeasure: number;
+        isDownbeat: boolean;
+        measureNumber: number;
+        intensity: number;
+        confidence: number;
+        requiredKey?: string;
+    }>;
+    mergedBeats: BeatWithSourceJSON[];
+    quarterNoteInterval: number;
+    quarterNoteBpm: number;
+    quarterNoteConfidence: number;
+    originalMetadata: BeatMapMetadata;
+    interpolationMetadata: InterpolationMetadataJSON;
+    /** The downbeat configuration inherited from the original BeatMap */
+    downbeatConfig?: DownbeatConfig;
+}
+/**
+ * JSON-serializable version of SubdividedBeat
+ *
+ * Extends Beat with subdivision-specific fields.
+ * Use with BeatSubdivider.toJSON() and BeatSubdivider.fromJSON() methods.
+ */
+export interface SubdividedBeatJSON {
+    timestamp: number;
+    beatInMeasure: number;
+    isDownbeat: boolean;
+    measureNumber: number;
+    intensity: number;
+    confidence: number;
+    requiredKey?: string;
+    isDetected: boolean;
+    originalBeatIndex?: number;
+    subdivisionType: SubdivisionType;
+}
+/**
+ * JSON-serializable version of SubdivisionMetadata
+ */
+export interface SubdivisionMetadataJSON {
+    originalBeatCount: number;
+    subdividedBeatCount: number;
+    averageDensityMultiplier: number;
+    explicitBeatCount: number;
+    subdivisionsUsed: SubdivisionType[];
+    hasMultipleTempos: boolean;
+    maxDensity: number;
+}
+/**
+ * JSON-serializable version of SubdividedBeatMap
+ *
+ * Ensures all values are JSON-safe for serialization/deserialization operations.
+ * Use with BeatSubdivider.toJSON() and BeatSubdivider.fromJSON() methods.
+ */
+export interface SubdividedBeatMapJSON {
+    audioId: string;
+    duration: number;
+    beats: SubdividedBeatJSON[];
+    detectedBeatIndices: number[];
+    subdivisionConfig: SubdivisionConfigJSON;
+    downbeatConfig: DownbeatConfig;
+    tempoSections?: TempoSectionJSON[];
+    subdivisionMetadata: SubdivisionMetadataJSON;
+}
+/**
+ * Tempo estimation result from the TempoDetector
+ */
+export interface TempoEstimate {
+    /** Main tempo estimate in BPM */
+    primaryBpm: number;
+    /** Adjacent metrical level in BPM (e.g., half-time or double-time) */
+    secondaryBpm: number;
+    /** Relative strength of the primary tempo (0.0 - 1.0) */
+    primaryWeight: number;
+    /** Relative strength of the secondary tempo (0.0 - 1.0) */
+    secondaryWeight: number;
+    /** Target inter-beat interval in seconds for DP tracker */
+    targetIntervalSeconds: number;
+}
+/**
+ * Tier 1: Hop size mode for controlling beat detection precision
+ *
+ * Hop size determines the time resolution of onset detection.
+ * Smaller values = more precise but slower analysis.
+ */
+export type HopSizeMode = 'efficient' | 'standard' | 'hq' | 'custom';
+/**
+ * Preset hop size values in milliseconds
+ *
+ * - efficient: 10ms - Fast analysis, reduced precision (legacy default)
+ * - standard: 4ms - Paper specification (Ellis 2007) - RECOMMENDED
+ * - hq: 2ms - High quality, maximum precision
+ */
+export declare const HOP_SIZE_PRESETS: {
+    readonly efficient: 10;
+    readonly standard: 4;
+    readonly hq: 2;
+};
+/**
+ * Configuration for hop size mode selection
+ */
+export interface HopSizeConfig {
+    /** The hop size mode to use */
+    mode: HopSizeMode;
+    /** Custom hop size in milliseconds (only used when mode === 'custom') */
+    customValue?: number;
+}
+/**
+ * Tier 2: Mel bands mode for controlling frequency resolution
+ *
+ * Mel bands determine the frequency resolution of the onset detection.
+ * More bands = better frequency resolution but slightly slower analysis.
+ */
+export type MelBandsMode = 'standard' | 'detailed' | 'maximum';
+/**
+ * Preset mel bands values
+ *
+ * - standard: 40 bands - Paper default, librosa default - RECOMMENDED
+ * - detailed: 64 bands - Better frequency resolution
+ * - maximum: 80 bands - Maximum detail
+ */
+export declare const MEL_BANDS_PRESETS: {
+    readonly standard: 40;
+    readonly detailed: 64;
+    readonly maximum: 80;
+};
+/**
+ * Configuration for mel bands mode selection
+ */
+export interface MelBandsConfig {
+    /** The mel bands mode to use */
+    mode: MelBandsMode;
+}
+/**
+ * Tier 2: Gaussian smooth mode for controlling onset envelope smoothing
+ *
+ * Gaussian smoothing determines how much the onset envelope is smoothed.
+ * More smoothing = cleaner peaks but may miss fast transients.
+ */
+export type GaussianSmoothMode = 'minimal' | 'standard' | 'smooth';
+/**
+ * Preset gaussian smoothing values in milliseconds
+ *
+ * - minimal: 10ms - Preserves fast transients
+ * - standard: 20ms - Paper default - RECOMMENDED
+ * - smooth: 40ms - Cleaner peaks, less noise
+ */
+export declare const GAUSSIAN_SMOOTH_PRESETS: {
+    readonly minimal: 10;
+    readonly standard: 20;
+    readonly smooth: 40;
+};
+/**
+ * Configuration for gaussian smooth mode selection
+ */
+export interface GaussianSmoothConfig {
+    /** The gaussian smooth mode to use */
+    mode: GaussianSmoothMode;
+}
+/**
+ * Convert hop size mode to actual milliseconds value
+ *
+ * @param config - Hop size configuration (default: { mode: 'standard' })
+ * @returns Hop size in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // Using preset modes
+ * getHopSizeMs({ mode: 'standard' });  // 4ms (Ellis 2007 paper spec)
+ * getHopSizeMs({ mode: 'efficient' }); // 10ms (fast analysis)
+ * getHopSizeMs({ mode: 'hq' });        // 2ms (maximum precision)
+ *
+ * // Using custom value (clamped to 1-50ms)
+ * getHopSizeMs({ mode: 'custom', customValue: 5 }); // 5ms
+ * getHopSizeMs({ mode: 'custom', customValue: 100 }); // 50ms (clamped)
+ * ```
+ */
+export declare function getHopSizeMs(config?: HopSizeConfig): number;
+/**
+ * Convert mel bands mode to actual count
+ *
+ * @param config - Mel bands configuration (default: { mode: 'standard' })
+ * @returns Number of mel bands
+ *
+ * @example
+ * ```typescript
+ * getMelBands({ mode: 'standard' }); // 40 bands (librosa default)
+ * getMelBands({ mode: 'detailed' }); // 64 bands (better resolution)
+ * getMelBands({ mode: 'maximum' });  // 80 bands (maximum detail)
+ * ```
+ */
+export declare function getMelBands(config?: MelBandsConfig): number;
+/**
+ * Convert gaussian smooth mode to actual milliseconds value
+ *
+ * @param config - Gaussian smooth configuration (default: { mode: 'standard' })
+ * @returns Smoothing window in milliseconds
+ *
+ * @example
+ * ```typescript
+ * getGaussianSmoothMs({ mode: 'minimal' });  // 10ms (preserves transients)
+ * getGaussianSmoothMs({ mode: 'standard' }); // 20ms (paper default)
+ * getGaussianSmoothMs({ mode: 'smooth' });   // 40ms (cleaner peaks)
+ * ```
+ */
+export declare function getGaussianSmoothMs(config?: GaussianSmoothConfig): number;
+/**
+ * Configuration for Onset Strength Envelope calculation
+ *
+ * ## Parameter Modes vs Direct Values
+ *
+ * OSE parameters support two configuration styles:
+ * - **Mode-based**: Use `hopSizeMode`, `melBandsMode`, `gaussianSmoothMode` for preset values
+ * - **Direct numeric**: Use `hopSizeMs`, `melBands`, `gaussianSmoothMs` for exact control
+ *
+ * **Precedence**: When both mode and direct value are provided, mode takes precedence.
+ *
+ * @example
+ * ```typescript
+ * // Mode-based configuration (recommended)
+ * const config: OSEConfig = {
+ *   hopSizeMode: { mode: 'standard' },     // 4ms (Ellis 2007 paper spec)
+ *   melBandsMode: { mode: 'detailed' },    // 64 bands
+ *   gaussianSmoothMode: { mode: 'smooth' } // 40ms
+ * };
+ *
+ * // Direct numeric configuration (backward compatible)
+ * const config: OSEConfig = {
+ *   hopSizeMs: 4,
+ *   melBands: 40,
+ *   gaussianSmoothMs: 20
+ * };
+ *
+ * // Mixed - mode takes precedence (hopSizeMs is ignored)
+ * const config: OSEConfig = {
+ *   hopSizeMode: { mode: 'hq' },  // Uses 2ms
+ *   hopSizeMs: 10                  // Ignored because hopSizeMode is set
+ * };
+ * ```
+ */
+export interface OSEConfig {
+    /** Target sample rate for resampling (default: 8000 Hz) */
+    targetSampleRate?: number;
+    /** FFT window size in milliseconds (default: 32) */
+    fftWindowSize?: number;
+    /**
+     * Hop size in milliseconds (default: 4).
+     * Ignored if hopSizeMode is provided.
+     * @see hopSizeMode for mode-based configuration
+     */
+    hopSizeMs?: number;
+    /**
+     * Hop size mode configuration.
+     * Takes precedence over hopSizeMs when both are provided.
+     * @default { mode: 'standard' }
+     */
+    hopSizeMode?: HopSizeConfig;
+    /**
+     * Number of Mel frequency bands (default: 40).
+     * Ignored if melBandsMode is provided.
+     * @see melBandsMode for mode-based configuration
+     */
+    melBands?: number;
+    /**
+     * Mel bands mode configuration.
+     * Takes precedence over melBands when both are provided.
+     * @default { mode: 'standard' }
+     */
+    melBandsMode?: MelBandsConfig;
+    /** High-pass filter cutoff in Hz (default: 0.4) */
+    highPassCutoff?: number;
+    /**
+     * Gaussian smoothing window in ms (default: 20).
+     * Ignored if gaussianSmoothMode is provided.
+     * @see gaussianSmoothMode for mode-based configuration
+     */
+    gaussianSmoothMs?: number;
+    /**
+     * Gaussian smooth mode configuration.
+     * Takes precedence over gaussianSmoothMs when both are provided.
+     * @default { mode: 'standard' }
+     */
+    gaussianSmoothMode?: GaussianSmoothConfig;
+}
+/**
+ * Configuration for the BeatTracker (DP algorithm)
+ */
+export interface BeatTrackerConfig {
+    /** Ellis balance factor (default: 680) */
+    dpAlpha?: number;
+    /** Sensitivity multiplier (0.1-10, default: 1.0) */
+    sensitivity?: number;
+    /** Minimum predecessor ratio (default: 0.5 = τp/2) */
+    minPredecessorRatio?: number;
+    /** Maximum predecessor ratio (default: 2.0 = 2τp) */
+    maxPredecessorRatio?: number;
+}
+/**
+ * Configuration for the TempoDetector.
+ *
+ * Controls tempo estimation behavior including BPM range, perceptual weighting,
+ * and optional meter resolution algorithms.
+ *
+ * Key options:
+ * - `useOctaveResolution`: Enable TPS2 calculation to resolve duple meter ambiguity
+ *   (half-tempo/double-tempo errors). Use for most 4/4, 2/4 music.
+ * - `useTripleMeter`: Enable TPS3 calculation to resolve triple meter ambiguity
+ *   (3/4, 6/8 time signatures). Use for waltzes and shuffle feels.
+ *
+ * Both options can be enabled simultaneously - they run independently and each
+ * resolves its respective meter ambiguity.
+ *
+ * @see {@link https://eeewing.com/pubs/ismir2007.pdf} - Ellis 2007, "Beat Tracking by Dynamic Programming"
+ */
+export interface TempoDetectorConfig {
+    /** Tempo center in seconds (default: 0.5 = 120 BPM) */
+    tempoCenter?: number;
+    /** Tempo width in octaves (default: 1.4, or 0.9 for stricter) */
+    tempoWidth?: number;
+    /** Minimum BPM (default: 90) */
+    minBpm?: number;
+    /** Maximum BPM (default: 180) */
+    maxBpm?: number;
+    /**
+     * Whether to use TPS2 octave resolution to prevent half-tempo/double-tempo ambiguity.
+     *
+     * When enabled, uses the Ellis TPS2 calculation (Equation 7) to prefer tempos
+     * with strong half-period evidence, improving accuracy from 77% to 84%.
+     *
+     * This helps prevent the algorithm from locking onto 73 BPM when the true tempo
+     * is 146 BPM (octave error).
+     *
+     * Default: false (opt-in for now)
+     */
+    useOctaveResolution?: boolean;
+    /**
+     * Whether to use TPS3 triple meter resolution for 3/4, 6/8 time signatures.
+     *
+     * When enabled, uses the Ellis TPS3 calculation (Equation 7 variant) to prefer tempos
+     * with strong third-period evidence, improving detection for waltzes and triple meter music.
+     *
+     * The TPS3 formula combines the main tempo with its third-harmonic:
+     * `TPS3(τ) = TPS(τ) + 0.33×TPS(3τ) + 0.33×TPS(3τ-1) + 0.33×TPS(3τ+1)`
+     *
+     * Tempos with strong third-period evidence (indicating triple meter) will have
+     * higher TPS3 scores, allowing proper beat detection for waltzes and 6/8 shuffles.
+     *
+     * Default: false (opt-in for triple meter music)
+     */
+    useTripleMeter?: boolean;
+}
+/**
+ * Progress information during beat map generation
+ */
+export interface BeatMapGenerationProgress {
+    /** Current phase of generation */
+    phase: 'loading' | 'preprocessing' | 'ose_calculation' | 'tempo_estimation' | 'beat_tracking' | 'measure_labeling' | 'finalizing' | 'complete' | 'error';
+    /** Progress percentage (0-100) */
+    progress: number;
+    /** Human-readable status message */
+    message: string;
+    /** Error message if phase is 'error' */
+    error?: string;
+}
+/**
+ * Default values for BeatMapGeneratorOptions
+ */
+export declare const DEFAULT_BEATMAP_GENERATOR_OPTIONS: Required<BeatMapGeneratorOptions>;
+/**
+ * Default values for BeatStreamOptions
+ */
+export declare const DEFAULT_BEATSTREAM_OPTIONS: Required<BeatStreamOptions>;
+/**
+ * Default accuracy thresholds (Hard difficulty preset)
+ * Equivalent to HARD_ACCURACY_THRESHOLDS - use either constant
+ */
+export declare const BEAT_ACCURACY_THRESHOLDS: AccuracyThresholds;
+/**
+ * Get accuracy thresholds for a difficulty preset
+ * @param preset - The difficulty preset ('easy', 'medium', 'hard', or 'custom')
+ * @returns The accuracy thresholds for the specified preset
+ * @note 'custom' preset returns hard thresholds as a base for customization
+ */
+export declare function getAccuracyThresholdsForPreset(preset: DifficultyPreset): AccuracyThresholds;
+/**
+ * Result of validating accuracy thresholds
+ */
+export interface ThresholdValidationResult {
+    /** Whether the thresholds are valid */
+    valid: boolean;
+    /** List of validation error messages (empty if valid) */
+    errors: string[];
+}
+/**
+ * Source of a beat - whether it was detected by the algorithm or interpolated
+ */
+export type BeatSource = 'detected' | 'interpolated';
+/**
+ * A beat with source information for interpolation
+ *
+ * Extends the base Beat interface with fields tracking the beat's origin
+ * and relationship to detected beats.
+ */
+export interface BeatWithSource extends Beat {
+    /** Whether this beat was detected or interpolated */
+    source: BeatSource;
+    /** Distance in seconds to the nearest detected beat (for interpolated beats) */
+    distanceToAnchor?: number;
+    /** Timestamp of the nearest detected beat (for interpolated beats) */
+    nearestAnchorTimestamp?: number;
+}
+/**
+ * Result of quarter note detection with dense section priority
+ *
+ * The quarter note interval is determined by analyzing beat intervals,
+ * with higher weight given to intervals from dense sections (consecutive
+ * beats at regular spacing).
+ */
+export interface QuarterNoteDetection {
+    /** Detected quarter note duration in seconds */
+    intervalSeconds: number;
+    /** Equivalent BPM (60 / intervalSeconds) */
+    bpm: number;
+    /** Confidence in the detection (0-1) */
+    confidence: number;
+    /** Raw histogram peak value for the detected interval */
+    histogramPeak: number;
+    /** Other significant peaks (e.g., half-note = 2× quarter note) */
+    secondaryPeaks: number[];
+    /** Method used for detection */
+    method: 'histogram' | 'kde' | 'tempo-detector-fallback';
+    /** Number of dense sections that contributed to the detection */
+    denseSectionCount: number;
+    /** Total beats from dense sections used in the detection */
+    denseSectionBeats: number;
+}
+/**
+ * Analysis of gaps between detected beats
+ *
+ * Identifies missing beats and anomalies in the detected beat pattern.
+ */
+export interface GapAnalysis {
+    /** Total number of gaps found between detected beats */
+    totalGaps: number;
+    /** Number of gaps that are exactly 2× quarter note (half-note gaps) */
+    halfNoteGaps: number;
+    /** Indices of beats that appear to be anomalies (false positives) */
+    anomalies: number[];
+    /** Average gap size in beats (1.0 = one quarter note) */
+    avgGapSize: number;
+    /** How well the detected beats align to the grid (0-1, higher is better) */
+    gridAlignmentScore: number;
+}
+/**
+ * Represents a distinct tempo section within a track
+ *
+ * When a track has multiple distinct tempo sections (e.g., a slow intro at 90 BPM
+ * followed by a fast section at 140 BPM), each section is represented by this interface.
+ *
+ * Sections have hard boundaries - no morphing/blending between tempos.
+ * This is only populated when multi-tempo analysis is enabled and detects multiple tempos.
+ */
+export interface TempoSection {
+    /** Section start time in seconds */
+    start: number;
+    /** Section end time in seconds */
+    end: number;
+    /** Tempo for this section in BPM */
+    bpm: number;
+    /** Quarter note interval in seconds (60 / bpm) */
+    intervalSeconds: number;
+    /** Number of detected beats in this section's cluster */
+    beatCount: number;
+    /** Index of the first beat in this section */
+    startBeatIndex: number;
+    /** Index of the last beat in this section */
+    endBeatIndex: number;
+}
+/**
+ * Metadata about the interpolation process
+ */
+export interface InterpolationMetadata {
+    /** Quarter note detection details */
+    quarterNoteDetection: QuarterNoteDetection;
+    /** Gap analysis results */
+    gapAnalysis: GapAnalysis;
+    /** Number of originally detected beats */
+    detectedBeatCount: number;
+    /** Number of beats added by interpolation */
+    interpolatedBeatCount: number;
+    /** Total beats in the merged output */
+    totalBeatCount: number;
+    /** Ratio of interpolated beats to total beats */
+    interpolationRatio: number;
+    /** Average confidence of interpolated beats */
+    avgInterpolatedConfidence: number;
+    /** Ratio of maximum local tempo to minimum local tempo (drift indicator) */
+    tempoDriftRatio: number;
+    /**
+     * Tempos found during normal analysis (e.g., [128, 140])
+     * Populated by normal analysis - cheap to compute
+     */
+    detectedClusterTempos?: number[];
+    /**
+     * Quick flag for checking if multi-tempo re-analysis is available
+     * True if detectedClusterTempos has more than one tempo
+     */
+    hasMultipleTempos: boolean;
+    /**
+     * Full section data with boundaries
+     * Only populated after multi-tempo re-analysis (enableMultiTempo: true)
+     */
+    tempoSections?: TempoSection[];
+    /**
+     * True only after multi-tempo re-analysis completes
+     * Used to distinguish between "detected multi-tempo" and "applied multi-tempo"
+     */
+    hasMultiTempoApplied?: boolean;
+}
+/**
+ * Complete interpolated beat map with two output streams
+ *
+ * Contains both the original detected beats and a merged stream that
+ * includes interpolated beats to fill gaps.
+ */
+export interface InterpolatedBeatMap {
+    /** Unique identifier for the audio source */
+    audioId: string;
+    /** Duration of the audio in seconds */
+    duration: number;
+    /** Original detected beats only (unchanged from BeatMap) */
+    detectedBeats: Beat[];
+    /** Interpolated beats with detected beats overriding at same positions */
+    mergedBeats: BeatWithSource[];
+    /** Detected quarter note interval in seconds */
+    quarterNoteInterval: number;
+    /** Equivalent BPM for the quarter note */
+    quarterNoteBpm: number;
+    /** Confidence in the quarter note detection */
+    quarterNoteConfidence: number;
+    /** Metadata from the original BeatMap */
+    originalMetadata: BeatMapMetadata;
+    /** Metadata about the interpolation process */
+    interpolationMetadata: InterpolationMetadata;
+    /**
+     * The downbeat configuration inherited from the original BeatMap
+     * Used for subdivision to determine measure boundaries
+     */
+    downbeatConfig?: DownbeatConfig;
+}
+/**
+ * Options for beat interpolation
+ *
+ * Controls how the interpolation algorithm generates the beat grid.
+ * Uses the Adaptive Phase-Locked Grid algorithm for beat interpolation.
+ */
+export interface BeatInterpolationOptions {
+    /** Minimum confidence for a beat to be used as an anchor (default: 0.3) */
+    minAnchorConfidence?: number;
+    /** Tolerance in seconds for snapping detected beats to grid (default: 0.05) */
+    gridSnapTolerance?: number;
+    /**
+     * Rate of tempo adaptation at anchor points (0-1, default: 0.3)
+     * 0 = fixed tempo, 1 = full adaptation to each anchor
+     */
+    tempoAdaptationRate?: number;
+    /** Whether to extrapolate grid before first detected beat (default: true) */
+    extrapolateStart?: boolean;
+    /** Whether to extrapolate grid after last detected beat (default: true) */
+    extrapolateEnd?: boolean;
+    /**
+     * Multiplier for anomaly detection (default: 0.4)
+     * Intervals < (1 - threshold) × QN or > (1 + threshold) × QN are flagged
+     */
+    anomalyThreshold?: number;
+    /** Minimum beats to count as a dense section (default: 3) */
+    denseSectionMinBeats?: number;
+    /** Weight for grid alignment in confidence calculation (default: 0.5) */
+    gridAlignmentWeight?: number;
+    /** Weight for anchor confidence in confidence calculation (default: 0.3) */
+    anchorConfidenceWeight?: number;
+    /** Weight for pace confidence in confidence calculation (default: 0.2) */
+    paceConfidenceWeight?: number;
+    /**
+     * Tempo difference threshold for section detection (default: 0.1 = 10%)
+     * Two tempos must differ by more than this ratio to be considered separate sections
+     */
+    tempoSectionThreshold?: number;
+    /**
+     * Minimum beats for a valid tempo cluster (default: 4)
+     * Clusters with fewer beats are not considered for multi-tempo detection
+     */
+    minClusterBeats?: number;
+    /**
+     * Enable multi-tempo analysis and interpolation (default: false)
+     * If true and hasMultipleTempos is detected, runs crossing paths analysis
+     * and applies per-section interpolation
+     */
+    enableMultiTempo?: boolean;
+}
+/**
+ * Default values for BeatInterpolationOptions
+ */
+export declare const DEFAULT_BEAT_INTERPOLATION_OPTIONS: Required<BeatInterpolationOptions>;
+/**
+ * Validate accuracy thresholds for correctness
+ *
+ * Checks that:
+ * - All provided threshold values are positive numbers
+ * - Thresholds are in ascending order (perfect < great < good < ok)
+ *
+ * @param thresholds - The thresholds to validate (can be partial)
+ * @returns Validation result with detailed error messages
+ *
+ * @example
+ * ```typescript
+ * // Valid thresholds
+ * const result = validateThresholds({ perfect: 0.05, great: 0.1, good: 0.15, ok: 0.2 });
+ * console.log(result.valid); // true
+ *
+ * // Invalid thresholds (not ascending)
+ * const invalid = validateThresholds({ perfect: 0.1, great: 0.05 });
+ * console.log(invalid.valid); // false
+ * console.log(invalid.errors); // ['great (0.05) must be greater than perfect (0.1)']
+ * ```
+ */
+export declare function validateThresholds(thresholds: Partial<AccuracyThresholds>): ThresholdValidationResult;
+/**
+ * Types of beat subdivision
+ *
+ * - quarter: Default, 1x density (unchanged)
+ * - half: 0.5x density (beats on 1 and 3 only)
+ * - eighth: 2x density (beat between each quarter)
+ * - sixteenth: 4x density (3 beats between each quarter) - MAXIMUM DENSITY
+ * - triplet8: Eighth triplets (3 beats per quarter note)
+ * - triplet4: Quarter triplets (3 beats per half note)
+ * - dotted4: Dotted quarter (keeps every 3rd beat: positions 0, 3, 6...)
+ * - dotted8: Dotted eighth (beat at 3/4 between quarters - 3:1 long-short ratio)
+ * - swing: Swing feel (beat at 2/3 between quarters - 2:1 long-short ratio)
+ * - offbeat8: 8th rest + 8th note (skips original beat, adds beat at 0.5)
+ * - rest: 0x density (no beats generated - used for gaps in rhythm patterns)
+ *
+ * Note: Sixteenth notes (4x) are the maximum supported density.
+ * Higher densities are not supported and will throw an error.
+ */
+export type SubdivisionType = 'quarter' | 'half' | 'eighth' | 'sixteenth' | 'triplet8' | 'triplet4' | 'dotted4' | 'dotted8' | 'swing' | 'offbeat8' | 'rest';
+/**
+ * Subdivision configuration for rhythm pattern generation
+ *
+ * This configuration allows each beat to have its own subdivision type,
+ * enabling fine-grained control for creating complex rhythmic phrases.
+ * Uses a sparse Map for efficient storage - beats not in the map use
+ * the default subdivision.
+ *
+ * @example
+ * ```typescript
+ * // Create a rhythm phrase with varying subdivisions
+ * const config: SubdivisionConfig = {
+ *   beatSubdivisions: new Map([
+ *     [0, 'quarter'],   // Beat 0: quarter note
+ *     [1, 'eighth'],    // Beat 1: eighth notes
+ *     [2, 'eighth'],    // Beat 2: eighth notes
+ *     [3, 'quarter'],   // Beat 3: quarter note
+ *   ]),
+ *   defaultSubdivision: 'quarter',
+ * };
+ *
+ * // Sparse representation - only specify beats that differ from default
+ * const sparseConfig: SubdivisionConfig = {
+ *   beatSubdivisions: new Map([
+ *     [4, 'triplet8'],  // Only beat 4 uses triplets
+ *     [8, 'triplet8'],  // Only beat 8 uses triplets
+ *   ]),
+ *   defaultSubdivision: 'quarter',  // All other beats are quarter notes
+ * };
+ *
+ * // Create gaps in rhythm using 'rest'
+ * const configWithRests: SubdivisionConfig = {
+ *   beatSubdivisions: new Map([
+ *     [0, 'quarter'],   // Beat 0: quarter note
+ *     [1, 'rest'],      // Beat 1: no beat (rest)
+ *     [2, 'eighth'],    // Beat 2: eighth notes
+ *     [3, 'rest'],      // Beat 3: no beat (rest)
+ *   ]),
+ *   defaultSubdivision: 'quarter',
+ * };
+ * ```
+ */
+export interface SubdivisionConfig {
+    /**
+     * Subdivision type for each beat index (sparse).
+     * Beats not in this map use the defaultSubdivision.
+     * Key: beat index (0-based), Value: subdivision type
+     */
+    beatSubdivisions: Map<number, SubdivisionType>;
+    /** Default subdivision for beats not in the beatSubdivisions map */
+    defaultSubdivision: SubdivisionType;
+}
+/** JSON-serializable version of SubdivisionConfig */
+export interface SubdivisionConfigJSON {
+    /** Subdivision assignments as array of [beatIndex, subdivisionType] tuples */
+    beatSubdivisions: [number, SubdivisionType][];
+    /** Default subdivision for beats not in the beatSubdivisions array */
+    defaultSubdivision: SubdivisionType;
+}
+/** Default subdivision config (quarter notes throughout) */
+export declare const DEFAULT_SUBDIVISION_CONFIG: SubdivisionConfig;
+/**
+ * A unified beat map with detected + interpolated beats merged
+ *
+ * This is the foundation for subdivision. All beats are treated equally
+ * regardless of whether they were originally detected or interpolated.
+ * Detected beats are flagged for accent/rhythm pattern use.
+ *
+ * Created from an InterpolatedBeatMap by the unifyBeatMap() utility.
+ *
+ * @example
+ * ```typescript
+ * import { BeatMapGenerator, BeatInterpolator, unifyBeatMap } from 'playlist-data-engine';
+ *
+ * // Generate and interpolate beat map
+ * const beatMap = await generator.generateBeatMap('song.mp3', 'track-1');
+ * const interpolatedMap = interpolator.interpolate(beatMap);
+ *
+ * // Create unified beat map (foundation for subdivision)
+ * const unifiedMap = unifyBeatMap(interpolatedMap);
+ *
+ * // Access detected beats for accent patterns
+ * const detectedBeats = unifiedMap.beats.filter((_, i) =>
+ *   unifiedMap.detectedBeatIndices.includes(i)
+ * );
+ * ```
+ */
+export interface UnifiedBeatMap {
+    /** Unique identifier for the audio source */
+    audioId: string;
+    /** Duration of the audio in seconds */
+    duration: number;
+    /** All beats (detected + interpolated) as a single unified list */
+    beats: Beat[];
+    /** Indices of beats that were originally detected (for accent lookup) */
+    detectedBeatIndices: number[];
+    /** Quarter note interval in seconds (primary tempo) */
+    quarterNoteInterval: number;
+    /** Equivalent BPM for the quarter note (primary tempo) */
+    quarterNoteBpm: number;
+    /** The downbeat configuration inherited from interpolation */
+    downbeatConfig: DownbeatConfig;
+    /** Tempo sections for multi-tempo support (from InterpolationMetadata) */
+    tempoSections?: TempoSection[];
+    /** Metadata from the original beat map */
+    originalMetadata: BeatMapMetadata;
+}
+/**
+ * A beat in a subdivided beat map
+ *
+ * Note: beatInMeasure is a DECIMAL in SubdividedBeat (e.g., 0.5, 1.25, 2.75)
+ * while the base Beat interface uses integers. This allows for positions
+ * like "the 'and' of beat 1" (1.5) or swing patterns.
+ *
+ * @example
+ * ```typescript
+ * // Eighth note positions in 4/4 time
+ * // beatInMeasure values: 0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5
+ *
+ * // Triplet positions in 4/4 time
+ * // beatInMeasure values: 0, 0.33, 0.66, 1, 1.33, 1.66...
+ *
+ * // Check if a beat was originally detected
+ * if (beat.isDetected) {
+ *   // Use for accent patterns
+ *   playAccentSound(beat);
+ * }
+ *
+ * // Get original position before subdivision
+ * const originalIndex = beat.originalBeatIndex; // undefined for generated beats
+ * ```
+ */
+export interface SubdividedBeat extends Beat {
+    /** Position within the measure as a decimal (e.g., 0, 0.5, 1, 1.5 for eighth notes) */
+    beatInMeasure: number;
+    /** Whether this beat was originally detected (vs interpolated or subdivision-generated) */
+    isDetected: boolean;
+    /** Index of the original beat in the UnifiedBeatMap (input to subdivider) */
+    originalBeatIndex?: number;
+    /** The subdivision type that created this beat */
+    subdivisionType: SubdivisionType;
+}
+/**
+ * Metadata about the subdivision process
+ *
+ * @example
+ * ```typescript
+ * const metadata = subdividedMap.subdivisionMetadata;
+ *
+ * console.log(`Original beats: ${metadata.originalBeatCount}`);
+ * console.log(`Subdivided beats: ${metadata.subdividedBeatCount}`);
+ * console.log(`Density multiplier: ${metadata.averageDensityMultiplier}x`);
+ * console.log(`Subdivisions used: ${metadata.subdivisionsUsed.join(', ')}`);
+ * console.log(`Has tempo changes: ${metadata.hasMultipleTempos}`);
+ * console.log(`Max density: ${metadata.maxDensity}x`);
+ * ```
+ */
+export interface SubdivisionMetadata {
+    /** Number of beats in the original unified map */
+    originalBeatCount: number;
+    /** Number of beats after subdivision */
+    subdividedBeatCount: number;
+    /** Overall density multiplier (2.0 = twice as many beats) */
+    averageDensityMultiplier: number;
+    /** Number of beats with explicit non-default subdivision */
+    explicitBeatCount: number;
+    /** Subdivision types used */
+    subdivisionsUsed: SubdivisionType[];
+    /** Whether the track has multiple tempo sections */
+    hasMultipleTempos: boolean;
+    /** Maximum density encountered (for validation against limit) */
+    maxDensity: number;
+}
+/**
+ * A beat map with subdivision applied
+ *
+ * The beat grid has been transformed according to the subdivision config,
+ * which may add beats (eighth, sixteenth, triplets), remove beats (half),
+ * or reposition beats (dotted patterns).
+ *
+ * @example
+ * ```typescript
+ * import { BeatSubdivider, unifyBeatMap } from 'playlist-data-engine';
+ *
+ * const subdivider = new BeatSubdivider();
+ * const unifiedMap = unifyBeatMap(interpolatedMap);
+ *
+ * // Apply subdivision
+ * const subdividedMap = subdivider.subdivide(unifiedMap, {
+ *   beatSubdivisions: new Map(),
+ *   defaultSubdivision: 'eighth',
+ * });
+ *
+ * // Access subdivision results
+ * console.log(`Original beats: ${subdividedMap.subdivisionMetadata.originalBeatCount}`);
+ * console.log(`Subdivided beats: ${subdividedMap.subdivisionMetadata.subdividedBeatCount}`);
+ * console.log(`Density multiplier: ${subdividedMap.subdivisionMetadata.averageDensityMultiplier}`);
+ *
+ * // Filter beats by type
+ * const detectedBeats = subdividedMap.beats.filter(b => b.isDetected);
+ * ```
+ */
+export interface SubdividedBeatMap {
+    /** Unique identifier for the audio source */
+    audioId: string;
+    /** Duration of the audio in seconds */
+    duration: number;
+    /** Beats after subdivision applied */
+    beats: SubdividedBeat[];
+    /** Indices of beats that were originally detected (for accent lookup) */
+    detectedBeatIndices: number[];
+    /** The subdivision configuration used */
+    subdivisionConfig: SubdivisionConfig;
+    /** The downbeat configuration inherited from UnifiedBeatMap (preserved unchanged) */
+    downbeatConfig: DownbeatConfig;
+    /** Tempo sections inherited from UnifiedBeatMap (for reference) */
+    tempoSections?: TempoSection[];
+    /** Metadata about the subdivision process */
+    subdivisionMetadata: SubdivisionMetadata;
+}
+/** Maximum density multiplier (sixteenth notes = 4x) */
+export declare const MAX_SUBDIVISION_DENSITY = 4;
+/** All valid subdivision type values */
+export declare const VALID_SUBDIVISION_TYPES: SubdivisionType[];
+/**
+ * Check if a value is a valid SubdivisionType
+ *
+ * @param value - The value to check
+ * @returns true if the value is a valid SubdivisionType
+ */
+export declare function isValidSubdivisionType(value: unknown): value is SubdivisionType;
+/**
+ * Get the density multiplier for a subdivision type
+ *
+ * @param subdivision - The subdivision type
+ * @returns The density multiplier (e.g., 2 for eighth notes, 4 for sixteenth notes)
+ */
+export declare function getSubdivisionDensity(subdivision: SubdivisionType): number;
+/**
+ * Validate subdivision configuration (structural validation only)
+ *
+ * This validates:
+ * - beatSubdivisions is a Map
+ * - All subdivision types in the map are valid
+ * - defaultSubdivision is a valid subdivision type
+ *
+ * @param config - The subdivision configuration to validate
+ * @throws Error if configuration is invalid
+ */
+export declare function validateSubdivisionConfig(config: SubdivisionConfig): void;
+/**
+ * Validate subdivision config against actual beat count
+ *
+ * This validates:
+ * - Beat indices in beatSubdivisions don't exceed total beat count
+ *
+ * Note: Beat indices beyond the beat count are no-ops (they just won't apply).
+ *
+ * @param config - The subdivision configuration to validate
+ * @param totalBeats - The total number of beats in the unified beat map
+ * @throws Error if beat index configuration is invalid
+ */
+export declare function validateSubdivisionConfigAgainstBeats(config: SubdivisionConfig, totalBeats: number): void;
+/**
+ * Validate that subdivision density does not exceed maximum
+ *
+ * This validates that the requested subdivision doesn't exceed the
+ * maximum supported density (sixteenth notes = 4x).
+ *
+ * @param subdivision - The subdivision type to validate
+ * @throws Error if subdivision exceeds maximum density
+ */
+export declare function validateSubdivisionDensity(subdivision: SubdivisionType): void;
+/**
+ * Transition mode for subdivision changes during playback
+ *
+ * - 'immediate': Switch subdivision instantly at the current position
+ * - 'next-downbeat': Wait for the next downbeat before switching
+ * - 'next-measure': Wait for the next measure before switching
+ */
+export type SubdivisionTransitionMode = 'immediate' | 'next-downbeat' | 'next-measure';
+/**
+ * Options for the SubdivisionPlaybackController
+ *
+ * @example
+ * ```typescript
+ * const controller = new SubdivisionPlaybackController(unifiedMap, audioContext, {
+ *   initialSubdivision: 'quarter',
+ *   transitionMode: 'next-downbeat',
+ *   anticipationTime: 2.0,
+ *   onSubdivisionChange: (oldType, newType) => {
+ *     console.log(`Switched from ${oldType} to ${newType}`);
+ *   },
+ * });
+ * ```
+ */
+export interface SubdivisionPlaybackOptions {
+    /** Starting subdivision type (default: 'quarter') */
+    initialSubdivision?: SubdivisionType;
+    /** How to handle subdivision changes (default: 'immediate') */
+    transitionMode?: SubdivisionTransitionMode;
+    /** Callback when subdivision changes */
+    onSubdivisionChange?: (oldType: SubdivisionType, newType: SubdivisionType) => void;
+    /** Anticipation time for beat events in seconds (default: 2.0) */
+    anticipationTime?: number;
+    /** Timing tolerance for beat event detection in seconds (default: 0.01) */
+    timingTolerance?: number;
+    /** User-calibrated offset in milliseconds (default: 0) */
+    userOffsetMs?: number;
+    /** Whether to compensate for output latency (default: true) */
+    compensateOutputLatency?: boolean;
+}
+/**
+ * Default options for SubdivisionPlaybackController
+ */
+export declare const DEFAULT_SUBDIVISION_PLAYBACK_OPTIONS: Required<SubdivisionPlaybackOptions>;
+/**
+ * Event emitted by the SubdivisionPlaybackController during playback
+ *
+ * @example
+ * ```typescript
+ * controller.subscribe((event) => {
+ *   console.log(`Beat at ${event.beat.timestamp}s, subdivision: ${event.currentSubdivision}`);
+ *   console.log(`Time until beat: ${event.timeUntilBeat}s`);
+ * });
+ * ```
+ */
+export interface SubdivisionBeatEvent {
+    /** The beat this event relates to */
+    beat: SubdividedBeat;
+    /** Current subdivision type being used */
+    currentSubdivision: SubdivisionType;
+    /** Time until the beat occurs (negative if passed) */
+    timeUntilBeat: number;
+    /** Current audio context time in seconds */
+    audioTime: number;
+    /** Type of event: 'upcoming', 'exact', or 'passed' */
+    type: BeatEventType;
+}
+/**
+ * Callback function type for SubdivisionPlaybackController subscriptions
+ */
+export type SubdivisionCallback = (event: SubdivisionBeatEvent) => void;
+/**
+ * Current version of the beat detection algorithm
+ */
+export declare const BEAT_DETECTION_VERSION = "1.0.0";
+/**
+ * Algorithm identifier for the Ellis DP beat tracker
+ */
+export declare const BEAT_DETECTION_ALGORITHM = "ellis-dp-v1";
+/**
+ * Groove tier representing the player's current groove intensity level.
+ *
+ * Tiers are determined by hotness value:
+ * - D: 0-33 (starting groove)
+ * - C: 33-66 (building momentum)
+ * - B: 66-100 (solid groove)
+ * - A: 100-150 (locked in)
+ * - S: 150-200 (exceptional)
+ * - SS: 200+ (legendary)
+ */
+export type GrooveTier = 'D' | 'C' | 'B' | 'A' | 'S' | 'SS' | 'Platinum';
+/**
+ * Configuration for a single groove tier.
+ */
+export interface GrooveTierConfig {
+    /** Tier name/label */
+    tier: GrooveTier;
+    /** Minimum hotness for this tier (inclusive) */
+    minHotness: number;
+    /** Maximum hotness for this tier (exclusive, except for SS which has no max) */
+    maxHotness: number;
+    /** Pocket window size in milliseconds at this tier */
+    windowMs: number;
+}
+/**
+ * Groove tier configurations with thresholds and window sizes.
+ *
+ * Window sizes represent the pocket tolerance at each tier:
+ * - Lower tier = more forgiving (larger window)
+ * - Higher tier = more demanding (smaller window)
+ *
+ * The window continues to shrink as you climb tiers, making it progressively
+ * harder to maintain your groove.
+ */
+export declare const GROOVE_TIERS: GrooveTierConfig[];
+/**
+ * Get the groove tier for a given hotness value.
+ *
+ * @param hotness - Current hotness value (can exceed 100)
+ * @returns The groove tier (D, C, B, A, S, SS, or Platinum)
+ */
+export declare function getGrooveTier(hotness: number): GrooveTier;
+/**
+ * Get the pocket window size in milliseconds for a given hotness value.
+ *
+ * Uses linear interpolation within each tier for smooth transitions.
+ *
+ * @param hotness - Current hotness value
+ * @returns Pocket window size in milliseconds
+ */
+export declare function getGrooveWindowMs(hotness: number): number;
+/**
+ * Get the minimum hotness required for a specific tier.
+ *
+ * @param tier - The groove tier
+ * @returns Minimum hotness required for that tier
+ */
+export declare function getMinHotnessForTier(tier: GrooveTier): number;
+/**
+ * Direction of the established pocket relative to the beat
+ *
+ * - 'push': Playing ahead of the beat (rushing, negative offset)
+ * - 'pull': Playing behind the beat (dragging, positive offset)
+ * - 'neutral': Playing on the beat (within ±10ms dead zone)
+ */
+export type GrooveDirection = 'push' | 'pull' | 'neutral';
+/**
+ * Result returned after each hit recorded by the GrooveAnalyzer
+ *
+ * Provides all information needed for UI display and game feedback.
+ */
+export interface GrooveResult {
+    /** Direction of current pocket */
+    pocketDirection: GrooveDirection;
+    /** Running average offset in seconds (established pocket center) */
+    establishedOffset: number;
+    /** How close this hit was to the pocket (0-1, 1 = perfect consistency) */
+    consistency: number;
+    /** Current hotness/meter value (0+, can exceed 100 for higher tiers) */
+    hotness: number;
+    /** Current groove tier based on hotness (D, C, B, A, S, or SS) */
+    tier: GrooveTier;
+    /** Current streak length within pocket */
+    streakLength: number;
+    /** Whether this hit was in the pocket window */
+    inPocket: boolean;
+    /** Current pocket window size in seconds (changes with tier) */
+    pocketWindow: number;
+    /**
+     * Stats from the groove that just ended (if any).
+     * Present when hotness drops to 0 or direction changes (push↔pull).
+     * Use this to calculate groove end bonus XP immediately.
+     */
+    endedGrooveStats?: {
+        maxStreak: number;
+        maxHotness: number;
+        avgHotness: number;
+        duration: number;
+        totalHits: number;
+        startTime: number;
+        endTime: number;
+    };
+}
+/**
+ * Snapshot of current groove analyzer state
+ *
+ * Used for UI display and state inspection.
+ */
+export interface GrooveState {
+    /** Direction of established pocket */
+    pocketDirection: GrooveDirection;
+    /** Running average offset in seconds */
+    establishedOffset: number;
+    /** Current hotness/meter value (0+, can exceed 100 for higher tiers) */
+    hotness: number;
+    /** Current groove tier based on hotness (D, C, B, A, S, or SS) */
+    tier: GrooveTier;
+    /** Current streak length within pocket */
+    streakLength: number;
+    /** Total number of hits recorded */
+    hitCount: number;
+    /** Current pocket window size in seconds */
+    pocketWindow: number;
+    /** When the current groove started (audio time in seconds), null if no active groove */
+    grooveStartTime: number | null;
+    /** Duration of the current groove in seconds (0 if no active groove) */
+    grooveDuration: number;
+    /** Peak hotness reached during the current groove (0+) */
+    maxHotness: number;
+    /** Average hotness over the groove lifetime (0+) */
+    avgHotness: number;
+    /** Total hits in the current groove */
+    grooveHitCount: number;
+}
+/**
+ * Statistics for groove end bonus calculation.
+ * Returned by GrooveAnalyzer.getGrooveStats() when a groove ends.
+ */
+export interface GrooveStats {
+    /** Peak streak during the groove */
+    maxStreak: number;
+    /** Peak hotness reached during the groove (0-100) */
+    maxHotness: number;
+    /** Average hotness over the groove lifetime (0-100) */
+    avgHotness: number;
+    /** How long the groove lasted in seconds */
+    duration: number;
+    /** Total hits in the groove */
+    totalHits: number;
+    /** When the groove started (audio time in seconds) */
+    startTime: number;
+    /** When the groove ended (audio time in seconds) */
+    endTime: number;
+}
+/**
+ * Configuration options for the GrooveAnalyzer
+ */
+export interface GrooveAnalyzerOptions {
+    /** Minimum hits to establish a pocket (default: 3) */
+    minHitsForPocket: number;
+    /** Base pocket window as fraction of beat (default: 0.03125 = 1/32 note) */
+    basePocketWindowFraction: number;
+    /** Minimum pocket window in seconds (floor for progressive tightening) */
+    minPocketWindowSeconds: number;
+    /** Hotness gain per consistent hit (default: 8) */
+    hotnessGainPerHit: number;
+    /** Hotness loss on pocket break (default: 80) */
+    hotnessLossOnBreak: number;
+    /** Hotness loss on missed beat (default: 80) */
+    hotnessLossOnMiss: number;
+    /** Number of recent hits to average for pocket establishment (default: 4) */
+    averagingWindowSize: number;
+    /** Dead zone around zero for neutral classification in seconds (default: 0.010 = ±10ms) */
+    neutralDeadZone: number;
+}
+/**
+ * Default configuration options for the GrooveAnalyzer
+ */
+export declare const DEFAULT_GROOVE_OPTIONS: GrooveAnalyzerOptions;
+/**
+ * Groove penalty configuration for difficulty presets.
+ *
+ * These values control how harshly the groove meter punishes mistakes.
+ * Higher values = more severe penalties for misses and wrong keys.
+ */
+export interface GroovePenaltyConfig {
+    /** Hotness loss when missing a beat or pressing wrong key */
+    hotnessLossOnMiss: number;
+    /** Hotness loss when breaking the pocket (hitting outside established timing) */
+    hotnessLossOnBreak: number;
+}
+/**
+ * Easy groove penalties - forgiving for casual players.
+ * Miss penalty: 35 (moderate)
+ */
+export declare const EASY_GROOVE_PENALTIES: GroovePenaltyConfig;
+/**
+ * Medium groove penalties - balanced difficulty.
+ * Miss penalty: 50 (noticeable)
+ */
+export declare const MEDIUM_GROOVE_PENALTIES: GroovePenaltyConfig;
+/**
+ * Hard groove penalties - strict for veterans.
+ * Miss penalty: 65 (severe)
+ */
+export declare const HARD_GROOVE_PENALTIES: GroovePenaltyConfig;
+/**
+ * Map of preset names to their groove penalty configurations.
+ */
+export declare const GROOVE_PENALTY_PRESETS: Record<Exclude<DifficultyPreset, 'custom'>, GroovePenaltyConfig>;
+/**
+ * Get groove penalty configuration for a difficulty preset.
+ *
+ * @param preset - The difficulty preset ('easy', 'medium', 'hard', or 'custom')
+ * @param customPenalties - Custom penalties to use when preset is 'custom'
+ * @returns The groove penalty configuration for the given preset
+ */
+export declare function getGroovePenaltiesForPreset(preset: DifficultyPreset, customPenalties?: Partial<GroovePenaltyConfig>): GroovePenaltyConfig;
+//# sourceMappingURL=BeatMap.d.ts.map