playlist-data-engine 1.1.0

package/dist/core/analysis/beat/BeatStream.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Beat Stream
+ *
+ * Real-time beat event streaming synchronized with audio playback.
+ * Provides precise beat timing with latency compensation and anticipation.
+ *
+ * Key features:
+ * - Sample-accurate timing via AudioContext synchronization
+ * - Configurable anticipation time for pre-rendering (default 2.0s)
+ * - Latency compensation (output + base + user offset)
+ * - Rolling BPM calculation from actual beat intervals
+ * - Button press accuracy detection for rhythm games
+ *
+ * @example
+ * ```typescript
+ * const beatStream = new BeatStream(beatMap, audioContext, {
+ *   anticipationTime: 2.0,
+ *   userOffsetMs: 0,
+ *   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();
+ * ```
+ */
+import type { Beat, BeatMap, BeatStreamOptions, BeatStreamCallback, AudioSyncState, ButtonPressResult, InterpolatedBeatMap, SubdividedBeatMap } from '../../types/BeatMap.js';
+import type { AccuracyThresholds } from '../../types/BeatMap.js';
+/**
+ * Beat Stream - Real-time beat event streaming synchronized with audio playback
+ *
+ * Emits beat events ('upcoming', 'exact', 'passed') synchronized with audio
+ * playback using the Web Audio API for precise timing.
+ *
+ * Supports BeatMap, InterpolatedBeatMap, and SubdividedBeatMap:
+ * - When given a BeatMap, uses the beats array directly
+ * - When given an InterpolatedBeatMap with useInterpolatedBeats: true, uses mergedBeats
+ * - When given an InterpolatedBeatMap with useInterpolatedBeats: false, uses detectedBeats
+ * - When given a SubdividedBeatMap, uses the subdivided beats array directly
+ */
+export declare class BeatStream {
+    private beatMap;
+    private normalizedBeatMap;
+    private audioContext;
+    private options;
+    private state;
+    private subscribers;
+    private scheduledBeats;
+    private rollingBpmWindowSize;
+    /**
+     * Create a new BeatStream
+     *
+     * @param beatMap - The beat map containing beat data (BeatMap, InterpolatedBeatMap, or SubdividedBeatMap)
+     * @param audioContext - The Web Audio API AudioContext for timing
+     * @param options - Configuration options
+     * @param rollingBpmWindowSize - Number of beats for rolling BPM calculation (default: 8)
+     *
+     * @example
+     * ```typescript
+     * // With a regular BeatMap
+     * const beatStream = new BeatStream(beatMap, audioContext);
+     *
+     * // With an InterpolatedBeatMap using interpolated beats
+     * const interpolatedMap = interpolator.interpolate(beatMap);
+     * const beatStream = new BeatStream(interpolatedMap, audioContext, {
+     *     useInterpolatedBeats: true
+     * });
+     *
+     * // With a SubdividedBeatMap (e.g., eighth notes)
+     * const unifiedMap = unifyBeatMap(interpolatedMap);
+     * const subdividedMap = subdivider.subdivide(unifiedMap, {
+     *     beatSubdivisions: new Map(),
+     *     defaultSubdivision: 'eighth',
+     * });
+     * const beatStream = new BeatStream(subdividedMap, audioContext);
+     * ```
+     */
+    constructor(beatMap: BeatMap | InterpolatedBeatMap | SubdividedBeatMap, audioContext: AudioContext, options?: BeatStreamOptions, rollingBpmWindowSize?: number);
+    /**
+     * Create a normalized BeatMap for internal use
+     *
+     * Handles BeatMap, InterpolatedBeatMap, and SubdividedBeatMap inputs,
+     * selecting the appropriate beat array based on the map type and options.
+     */
+    private createNormalizedBeatMap;
+    /**
+     * Initialize scheduled beats array
+     */
+    private initializeScheduledBeats;
+    /**
+     * Get the current configuration
+     */
+    getOptions(): Required<BeatStreamOptions>;
+    /**
+     * Get the current accuracy thresholds being used
+     *
+     * Returns the resolved thresholds based on the difficulty preset
+     * and any custom threshold overrides.
+     *
+     * @returns The current accuracy thresholds
+     */
+    getAccuracyThresholds(): AccuracyThresholds;
+    /**
+     * Change difficulty settings mid-stream
+     *
+     * Allows changing the difficulty preset and/or custom thresholds without
+     * recreating the BeatStream. Useful for:
+     * - Adaptive difficulty (adjust based on player performance)
+     * - Practice mode (try different difficulties without restarting)
+     * - Accessibility (let players adjust on the fly)
+     *
+     * @param options - Difficulty options
+     * @param options.preset - New difficulty preset ('easy', 'medium', 'hard')
+     * @param options.customThresholds - Custom threshold overrides (merged with preset)
+     *
+     * @example
+     * ```typescript
+     * // Switch to easy mode
+     * beatStream.setDifficulty({ preset: 'easy' });
+     *
+     * // Use custom thresholds
+     * beatStream.setDifficulty({
+     *     preset: 'medium',
+     *     customThresholds: { perfect: 0.060 }  // Looser perfect window
+     * });
+     *
+     * // Clear custom thresholds and use preset only
+     * beatStream.setDifficulty({ preset: 'hard', customThresholds: {} });
+     * ```
+     */
+    setDifficulty(options: {
+        preset?: import('../../types/BeatMap.js').DifficultyPreset;
+        customThresholds?: Partial<AccuracyThresholds>;
+    }): void;
+    /**
+     * Subscribe to beat events
+     *
+     * @param callback - Function to call when beat events occur
+     * @returns Unsubscribe function
+     */
+    subscribe(callback: BeatStreamCallback): () => void;
+    /**
+     * Start streaming beat events
+     *
+     * Begins emitting events synchronized with audio playback.
+     * Should be called when audio starts playing.
+     */
+    start(): void;
+    /**
+     * Stop streaming beat events
+     *
+     * Stops all event emission and resets state.
+     */
+    stop(): void;
+    /**
+     * Pause the beat stream
+     *
+     * Temporarily stops event emission but preserves position.
+     */
+    pause(): void;
+    /**
+     * Resume a paused beat stream
+     */
+    resume(): void;
+    /**
+     * Seek to a specific time position
+     *
+     * @param time - Time in seconds to seek to
+     */
+    seek(time: number): void;
+    /**
+     * Get the current audio time with latency compensation
+     *
+     * @returns Current audio time in seconds
+     */
+    private getCurrentAudioTime;
+    /**
+     * Get total latency compensation in seconds
+     *
+     * Combines output latency, base latency, and user offset
+     */
+    private getTotalLatencyCompensation;
+    /**
+     * Get the current synchronization state for debugging
+     *
+     * @returns Current audio sync state
+     */
+    getSyncState(): AudioSyncState;
+    /**
+     * Schedule the next update frame
+     */
+    private scheduleUpdate;
+    /**
+     * Main update loop - checks for beat events to emit
+     */
+    private update;
+    /**
+     * Emit a beat event to all subscribers
+     */
+    private emitEvent;
+    /**
+     * Get upcoming beats for pre-rendering
+     *
+     * Returns beats that will occur within the anticipation window.
+     *
+     * @param count - Maximum number of beats to return
+     * @returns Array of upcoming beats
+     */
+    getUpcomingBeats(count: number): Beat[];
+    /**
+     * Get the beat at a specific time
+     *
+     * Returns the beat closest to the given time within the timing tolerance.
+     *
+     * @param time - Time in seconds
+     * @returns Beat at the time, or null if no beat is near
+     */
+    getBeatAtTime(time: number): Beat | null;
+    /**
+     * Get the current beat (the beat that is currently playing or most recently passed)
+     *
+     * @returns Current beat, or null if before first beat
+     */
+    getCurrentBeat(): Beat | null;
+    /**
+     * Get the next beat (the beat that will occur next)
+     *
+     * @returns Next beat, or null if after last beat
+     */
+    getNextBeat(): Beat | null;
+    /**
+     * Get the current BPM calculated from recent beat intervals
+     *
+     * Uses a rolling window of beat intervals to calculate the
+     * current tempo, which handles gradual tempo drift.
+     *
+     * @returns Current BPM, or the beat map's initial BPM if not enough beats
+     */
+    getCurrentBpm(): number;
+    /**
+     * Resolve the effective accuracy thresholds based on options
+     *
+     * If custom thresholds are provided, they are merged with the base preset.
+     * Otherwise, the preset thresholds are used directly.
+     *
+     * @returns The effective accuracy thresholds
+     */
+    private resolveThresholds;
+    /**
+     * Check the accuracy of a button press
+     *
+     * Determines how close the button press was to the nearest beat.
+     * If the beat has a requiredKey, validates that the pressedKey matches.
+     *
+     * @param timestamp - The time of the button press (use audioContext.currentTime)
+     * @param pressedKey - Optional key that was pressed (for key-matching beats)
+     * @returns Button press result with accuracy level and key match info
+     */
+    checkButtonPress(timestamp: number, pressedKey?: string): ButtonPressResult;
+    /**
+     * Get the accuracy of the last button press
+     *
+     * @returns Last button press result, or null if no button has been pressed
+     */
+    getLastBeatAccuracy(): ButtonPressResult | null;
+    /**
+     * Check if the stream is currently running
+     */
+    isRunning(): boolean;
+    /**
+     * Check if the stream is paused
+     */
+    isPaused(): boolean;
+    /**
+     * Get the current playback position
+     *
+     * @returns Current time in seconds
+     */
+    getCurrentTime(): number;
+    /**
+     * Get the beat map duration
+     */
+    getDuration(): number;
+    /**
+     * Get the original beat map (may be BeatMap, InterpolatedBeatMap, or SubdividedBeatMap)
+     *
+     * @returns The original beat map passed to the constructor
+     */
+    getBeatMap(): BeatMap | InterpolatedBeatMap | SubdividedBeatMap;
+    /**
+     * Get the normalized beat map used internally
+     *
+     * This is always a BeatMap, regardless of whether the original was
+     * a BeatMap or InterpolatedBeatMap.
+     *
+     * @returns The normalized beat map
+     */
+    getNormalizedBeatMap(): BeatMap;
+    /**
+     * Update the beat map (e.g., after manual editing)
+     *
+     * @param beatMap - New beat map to use (BeatMap, InterpolatedBeatMap, or SubdividedBeatMap)
+     */
+    setBeatMap(beatMap: BeatMap | InterpolatedBeatMap | SubdividedBeatMap): void;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=BeatStream.d.ts.map

package/dist/core/analysis/beat/BeatStream.d.ts.map

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

package/dist/core/analysis/beat/BeatSubdivider.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Beat Subdivider
+ *
+ * Transforms a UnifiedBeatMap into a SubdividedBeatMap by applying rhythmic
+ * subdivision patterns. Supports half notes, eighth notes, sixteenth notes,
+ * triplets, dotted patterns, and rests.
+ *
+ * Each beat can have its own subdivision type, enabling fine-grained control
+ * for creating complex rhythmic phrases.
+ *
+ * @example
+ * ```typescript
+ * const subdivider = new BeatSubdivider();
+ *
+ * // Subdivide with default config (quarter notes)
+ * const subdividedMap = subdivider.subdivide(unifiedMap);
+ *
+ * // Subdivide with custom per-beat config
+ * const customConfig: SubdivisionConfig = {
+ *   beatSubdivisions: new Map([
+ *     [0, 'quarter'],
+ *     [1, 'eighth'],
+ *     [2, 'eighth'],
+ *     [3, 'rest'],  // No beat on beat 3
+ *   ]),
+ *   defaultSubdivision: 'quarter',
+ * };
+ * const customMap = subdivider.subdivide(unifiedMap, customConfig);
+ * ```
+ */
+import type { UnifiedBeatMap, SubdividedBeatMap, SubdivisionConfig } from '../../types/BeatMap.js';
+/**
+ * Options for the BeatSubdivider
+ */
+export interface BeatSubdividerOptions {
+    /**
+     * Tolerance in seconds for aligning beats to detected beats
+     * When generating new beats, if a beat falls within this tolerance
+     * of a detected beat, it will be marked as detected.
+     * @default 0.02 (20ms)
+     */
+    tolerance?: number;
+    /**
+     * Default intensity for newly generated beats (0.0 - 1.0)
+     * Used when intensity cannot be interpolated from neighbors.
+     * @default 0.5
+     */
+    defaultIntensity?: number;
+    /**
+     * Default confidence for newly generated beats (0.0 - 1.0)
+     * Used when confidence cannot be interpolated from neighbors.
+     * @default 0.7
+     */
+    defaultConfidence?: number;
+}
+/**
+ * Beat Subdivider
+ *
+ * Transforms quarter-note beat grids into various rhythmic subdivisions.
+ * Each beat can have its own subdivision type for fine-grained rhythm control.
+ */
+export declare class BeatSubdivider {
+    private options;
+    /**
+     * Create a new BeatSubdivider
+     *
+     * @param options - Optional configuration options
+     */
+    constructor(options?: BeatSubdividerOptions);
+    /**
+     * Subdivide a unified beat map according to the given configuration
+     *
+     * Each beat can have its own subdivision type, enabling fine-grained
+     * control for creating complex rhythmic phrases.
+     *
+     * @param unifiedMap - The unified beat map to subdivide
+     * @param config - Optional subdivision configuration (defaults to quarter notes)
+     * @returns The subdivided beat map
+     * @throws Error if configuration is invalid
+     */
+    subdivide(unifiedMap: UnifiedBeatMap, config?: SubdivisionConfig): SubdividedBeatMap;
+    /**
+     * Create interpolated beats for a specific subdivision type
+     *
+     * @param beat - The current beat
+     * @param nextBeat - The next beat
+     * @param beatIndex - The global index of the current beat
+     * @param subdivision - The subdivision type to apply
+     * @param unifiedMap - The unified beat map
+     * @param hasMultipleTempos - Whether there are multiple tempo sections
+     * @param config - The subdivision configuration (for checking adjacent beat subdivisions)
+     * @param triplet4ChainPosition - Position in triplet4 chain (0 = first, 1 = second)
+     * @returns Array of interpolated beats (empty for quarter/half subdivisions)
+     */
+    private createInterpolatedBeatsForSubdivision;
+    /**
+     * Create an empty subdivided beat map
+     */
+    private createEmptySubdividedBeatMap;
+    /**
+     * Create an interpolated beat between two beats
+     */
+    private createInterpolatedBeat;
+    /**
+     * Find the closest beat to a given timestamp
+     */
+    private findClosestBeat;
+    /**
+     * Calculate beatInMeasure for a timestamp
+     */
+    private calculateBeatInMeasure;
+    /**
+     * Calculate measure number for a timestamp
+     */
+    private calculateMeasureNumber;
+    /**
+     * Build the detected beat indices array for the result
+     */
+    private buildDetectedBeatIndices;
+    /**
+     * Get the tempo section for a given timestamp
+     *
+     * @param tempoSections - Array of tempo sections (or undefined)
+     * @param timestamp - The timestamp to look up
+     * @returns The matching tempo section, or undefined if none
+     */
+    private getTempoSectionForTimestamp;
+    /**
+     * Get the quarter note interval for a given timestamp
+     *
+     * Returns the interval from the tempo section if available,
+     * otherwise falls back to the primary quarterNoteInterval.
+     *
+     * @param unifiedMap - The unified beat map
+     * @param timestamp - The timestamp to get the interval for
+     * @returns The quarter note interval in seconds
+     */
+    private getQuarterNoteIntervalForTimestamp;
+    /**
+     * Get the tempo section for a given beat index
+     *
+     * @param tempoSections - Array of tempo sections (or undefined)
+     * @param beatIndex - The beat index to look up
+     * @returns The matching tempo section, or undefined if none
+     */
+    private getTempoSectionForBeatIndex;
+    /**
+     * Convert a SubdividedBeatMap to a JSON string
+     *
+     * @param subdividedBeatMap - Subdivided beat map to serialize
+     * @returns JSON string
+     *
+     * @example
+     * ```typescript
+     * const subdividedMap = subdivider.subdivide(unifiedMap, config);
+     *
+     * // Serialize to JSON for storage
+     * const json = BeatSubdivider.toJSON(subdividedMap);
+     * localStorage.setItem('subdividedMap', json);
+     * ```
+     */
+    static toJSON(subdividedBeatMap: SubdividedBeatMap): string;
+    /**
+     * Parse a SubdividedBeatMap from a JSON string
+     *
+     * @param jsonString - JSON string to parse
+     * @returns Subdivided beat map
+     *
+     * @example
+     * ```typescript
+     * // Load from storage
+     * const json = localStorage.getItem('subdividedMap');
+     * const subdividedMap = BeatSubdivider.fromJSON(json);
+     *
+     * // Use the loaded beat map
+     * console.log(subdividedMap.beats.length);
+     * ```
+     */
+    static fromJSON(jsonString: string): SubdividedBeatMap;
+    /**
+     * Save a SubdividedBeatMap to a file (Node.js only)
+     *
+     * @param subdividedBeatMap - Subdivided beat map to save
+     * @param filePath - Path to save the file
+     *
+     * @example
+     * ```typescript
+     * await BeatSubdivider.saveToFile(subdividedMap, 'chart.json');
+     * ```
+     */
+    static saveToFile(subdividedBeatMap: SubdividedBeatMap, filePath: string): Promise<void>;
+    /**
+     * Load a SubdividedBeatMap from a file (Node.js only)
+     *
+     * @param filePath - Path to load the file from
+     * @returns Subdivided beat map
+     *
+     * @example
+     * ```typescript
+     * const subdividedMap = await BeatSubdivider.loadFromFile('chart.json');
+     * ```
+     */
+    static loadFromFile(filePath: string): Promise<SubdividedBeatMap>;
+}
+//# sourceMappingURL=BeatSubdivider.d.ts.map

package/dist/core/analysis/beat/BeatSubdivider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BeatSubdivider.d.ts","sourceRoot":"","sources":["../../../../src/core/analysis/beat/BeatSubdivider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAER,cAAc,EAEd,iBAAiB,EACjB,iBAAiB,EAMpB,MAAM,wBAAwB,CAAC;AAWhC;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAkCD;;;;;GAKG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,OAAO,CAAkC;IAEjD;;;;OAIG;gBACS,OAAO,CAAC,EAAE,qBAAqB;IAS3C;;;;;;;;;;OAUG;IACH,SAAS,CACL,UAAU,EAAE,cAAc,EAC1B,MAAM,GAAE,iBAA8C,GACvD,iBAAiB;IAkKpB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,qCAAqC;IAmL7C;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAwBpC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA+B9B;;OAEG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAW9B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAa9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAgBhC;;;;;;OAMG;IACH,OAAO,CAAC,2BAA2B;IAoBnC;;;;;;;;;OASG;IACH,OAAO,CAAC,kCAAkC;IAgB1C;;;;;;OAMG;IACH,OAAO,CAAC,2BAA2B;IAwBnC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,iBAAiB,GAAG,MAAM;IAkD3D;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB;IAkDtD;;;;;;;;;;OAUG;WACU,UAAU,CACnB,iBAAiB,EAAE,iBAAiB,EACpC,QAAQ,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;;;;;;OAUG;WACU,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAW1E"}

package/dist/core/analysis/beat/BeatTracker.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Beat Tracker using Dynamic Programming
+ *
+ * Implements the Ellis 2007 beat tracking algorithm using dynamic programming
+ * to find the globally optimal beat sequence.
+ *
+ * Reference: "Beat Tracking by Dynamic Programming" (Ellis, 2007)
+ * https://www.ee.columbia.edu/~dpwe/pubs/Ellis07-beattrack.pdf
+ *
+ * The algorithm finds beat times {t₁, t₂, ..., tₙ} that maximize:
+ *   C({ti}) = Σ O(ti) + α Σ F(ti - ti-1, τp)
+ *
+ * Where:
+ *   O(t) = Onset Strength Envelope (high at moments that make good beats)
+ *   F(Δt, τ) = Transition cost function (penalizes tempo deviation)
+ *   α = Balance factor (paper found optimal: 680)
+ *   τp = Target inter-beat interval (from tempo estimation)
+ */
+import type { Beat, BeatTrackerConfig, TempoEstimate } from '../../types/BeatMap.js';
+/**
+ * Internal result of beat tracking
+ */
+export interface BeatTrackingResult {
+    /** Detected beats */
+    beats: Beat[];
+    /** Frame indices of beats */
+    beatFrames: number[];
+    /** Cumulative scores (for debugging) */
+    cumulativeScores: Float32Array;
+}
+/**
+ * Beat Tracker using Ellis Dynamic Programming Algorithm
+ *
+ * Finds the globally optimal beat sequence by:
+ * 1. Precomputing transition costs for different inter-beat intervals
+ * 2. Forward pass: calculating best cumulative scores with backlinks
+ * 3. Backward pass: extracting the optimal beat sequence
+ *
+ * @example
+ * ```typescript
+ * const tracker = new BeatTracker({
+ *   dpAlpha: 680,
+ * });
+ *
+ * const result = tracker.trackBeats(onsetEnvelope, tempoEstimate, hopSizeSeconds);
+ * // result.beats contains detected Beat objects
+ * ```
+ */
+export declare class BeatTracker {
+    private config;
+    /**
+     * Create a new Beat Tracker
+     *
+     * @param config - Configuration options (all optional, defaults provided)
+     */
+    constructor(config?: BeatTrackerConfig);
+    /**
+     * Get the current configuration
+     *
+     * @returns The current configuration
+     */
+    getConfig(): Required<BeatTrackerConfig>;
+    /**
+     * Track beats in an onset strength envelope
+     *
+     * Implements the Ellis DP algorithm:
+     * 1. Precompute transition costs for all possible intervals
+     * 2. Forward pass: find best predecessor for each frame
+     * 3. Backward pass: extract optimal beat sequence
+     * 4. Convert frame indices to Beat objects
+     *
+     * @param onsetEnvelope - Onset strength envelope from OSE calculation
+     * @param tempoEstimate - Tempo estimate from TempoDetector
+     * @param hopSizeSeconds - Hop size in seconds (time between envelope frames)
+     * @returns Beat tracking result with detected beats
+     */
+    trackBeats(onsetEnvelope: Float32Array, tempoEstimate: TempoEstimate, hopSizeSeconds: number): BeatTrackingResult;
+    /**
+     * Convert beat frame indices to Beat objects
+     *
+     * @param beatFrames - Array of frame indices where beats occur
+     * @param onsetEnvelope - Original onset strength envelope
+     * @param cumscore - Cumulative scores from DP
+     * @param hopSizeSeconds - Hop size in seconds
+     * @param period - Target period in frames
+     * @returns Array of Beat objects
+     */
+    private convertToBeats;
+    /**
+     * Track beats with additional options for fine-tuning
+     *
+     * This method provides more control over the tracking process,
+     * useful for debugging or special cases.
+     *
+     * @param onsetEnvelope - Onset strength envelope
+     * @param tempoEstimate - Tempo estimate
+     * @param hopSizeSeconds - Hop size in seconds
+     * @param options - Additional options
+     * @returns Beat tracking result
+     */
+    trackBeatsWithOptions(onsetEnvelope: Float32Array, tempoEstimate: TempoEstimate, hopSizeSeconds: number, options?: {
+        /** Minimum score threshold for beat acceptance */
+        minScoreThreshold?: number;
+        /** Apply discounted score trimming for start/end beats */
+        applyTrimming?: boolean;
+    }): BeatTrackingResult;
+    /**
+     * Apply discounted score trimming to find valid beat boundaries
+     *
+     * Ellis notes that the cumulative score grows steadily, but we can
+     * find the first and last valid beats by looking at the difference
+     * from a straight line connecting origin to final value.
+     *
+     * C*(t) - (t/length) * C*(length-1)
+     *
+     * @param result - Beat tracking result to modify in place
+     * @param length - Total number of frames
+     * @param period - Target period in frames
+     */
+    private applyDiscountedScoreTrimming;
+    /**
+     * Get beat tracking statistics for debugging
+     *
+     * @param result - Beat tracking result
+     * @param hopSizeSeconds - Hop size in seconds
+     * @returns Statistics about the detected beats
+     */
+    getTrackingStats(result: BeatTrackingResult, hopSizeSeconds: number): {
+        numBeats: number;
+        avgInterval: number;
+        stdInterval: number;
+        avgIntensity: number;
+        avgConfidence: number;
+        estimatedBpm: number;
+    };
+}
+//# sourceMappingURL=BeatTracker.d.ts.map

package/dist/core/analysis/beat/BeatTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BeatTracker.d.ts","sourceRoot":"","sources":["../../../../src/core/analysis/beat/BeatTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAerF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,qBAAqB;IACrB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,6BAA6B;IAC7B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,wCAAwC;IACxC,gBAAgB,EAAE,YAAY,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,MAAM,CAA8B;IAE5C;;;;OAIG;gBACS,MAAM,GAAE,iBAAsB;IAI1C;;;;OAIG;IACH,SAAS,IAAI,QAAQ,CAAC,iBAAiB,CAAC;IAIxC;;;;;;;;;;;;;OAaG;IACH,UAAU,CACN,aAAa,EAAE,YAAY,EAC3B,aAAa,EAAE,aAAa,EAC5B,cAAc,EAAE,MAAM,GACvB,kBAAkB;IAoJrB;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAiEtB;;;;;;;;;;;OAWG;IACH,qBAAqB,CACjB,aAAa,EAAE,YAAY,EAC3B,aAAa,EAAE,aAAa,EAC5B,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;QACL,kDAAkD;QAClD,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,0DAA0D;QAC1D,aAAa,CAAC,EAAE,OAAO,CAAC;KACtB,GACP,kBAAkB;IA6BrB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,4BAA4B;IAyDpC;;;;;;OAMG;IACH,gBAAgB,CACZ,MAAM,EAAE,kBAAkB,EAC1B,cAAc,EAAE,MAAM,GACvB;QACC,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;KACxB;CAgDJ"}