playlist-data-engine 1.1.0

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

@@ -0,0 +1,477 @@
+/**
+ * Beat Interpolator
+ *
+ * Post-processing pass that runs AFTER BeatMap generation to fill gaps
+ * where detected beats are missing. Uses dense section priority to determine
+ * the quarter note interval, then generates interpolated beats using the
+ * Adaptive Phase-Locked Grid algorithm.
+ *
+ * The Adaptive Phase-Locked approach uses anchor points (detected beats) to
+ * track tempo drift and maintain phase alignment throughout the track.
+ *
+ * @example
+ * ```typescript
+ * const interpolator = new BeatInterpolator({
+ *   minAnchorConfidence: 0.3,
+ *   gridSnapTolerance: 0.05,
+ * });
+ *
+ * const interpolatedBeatMap = interpolator.interpolate(beatMap);
+ *
+ * // Access original detected beats
+ * console.log(interpolatedBeatMap.detectedBeats.length);
+ *
+ * // Access merged beats (interpolated + detected override)
+ * console.log(interpolatedBeatMap.mergedBeats.length);
+ * ```
+ */
+import type { BeatMap, BeatInterpolationOptions, InterpolatedBeatMap } from '../../types/BeatMap.js';
+/**
+ * Beat Interpolator
+ *
+ * Generates interpolated beats to fill gaps in detected beat maps using
+ * the Pace + Anchors model with dense section priority.
+ */
+export declare class BeatInterpolator {
+    private options;
+    /**
+     * Create a new BeatInterpolator
+     *
+     * @param options - Configuration options (all optional, defaults provided)
+     */
+    constructor(options?: BeatInterpolationOptions);
+    /**
+     * Get the current configuration
+     *
+     * @returns The current configuration
+     */
+    getConfig(): Required<BeatInterpolationOptions>;
+    /**
+     * Interpolate beats in a BeatMap
+     *
+     * Main entry point that orchestrates the interpolation process:
+     * 1. Detect quarter note interval using dense section priority
+     * 2. Analyze gaps between detected beats
+     * 3. Generate beat grid using selected algorithm
+     * 4. Merge detected beats with interpolated beats
+     *
+     * @param beatMap - The beat map to interpolate
+     * @returns Interpolated beat map with two output streams
+     */
+    interpolate(beatMap: BeatMap): InterpolatedBeatMap;
+    /**
+     * Detect quarter note interval using dense section priority
+     *
+     * Algorithm:
+     * 1. Identify dense sections (consecutive beats at similar intervals)
+     * 2. Build weighted histogram of intervals
+     * 3. Find primary peak (most weighted interval = quarter note)
+     * 4. Calculate confidence based on peak prominence and dense section contribution
+     *
+     * @param beats - Detected beats to analyze
+     * @returns Quarter note detection result
+     */
+    private detectQuarterNote;
+    /**
+     * Identify dense sections in the beat sequence
+     *
+     * A dense section is a sequence of consecutive beats (3+ by default)
+     * where the intervals between beats are consistent (low variance).
+     *
+     * @param beats - Beats to analyze
+     * @returns Array of dense sections
+     */
+    private identifyDenseSections;
+    /**
+     * Identify tempo clusters from dense sections
+     *
+     * Builds on identifyDenseSections() output to group dense sections by tempo
+     * similarity and create verified tempo clusters for multi-tempo detection.
+     *
+     * Algorithm:
+     * 1. Convert dense sections to cluster candidates with BPM
+     * 2. Group sections by tempo similarity (within tempoSectionThreshold)
+     * 3. Merge adjacent sections with similar tempo into clusters
+     * 4. Filter clusters by minClusterBeats requirement
+     * 5. Return only verified clusters
+     *
+     * @param beats - Detected beats to analyze
+     * @returns Array of verified tempo clusters
+     */
+    private identifyTempoClusters;
+    /**
+     * Find conflicting tempo clusters
+     *
+     * Checks if any two verified clusters have tempos that differ by more than
+     * the tempoSectionThreshold. Filters out octave-related tempos (e.g., 60 BPM
+     * vs 120 BPM are considered the same tempo).
+     *
+     * @param clusters - Verified tempo clusters to analyze
+     * @returns Array of conflicting cluster pairs, or null if no conflicts
+     */
+    private findConflictingClusters;
+    /**
+     * Check if two tempos are octave multiples
+     *
+     * Used to filter out false "conflicts" where two clusters are actually
+     * at the same tempo but detected at different octaves (e.g., 60 BPM vs 120 BPM).
+     *
+     * @param tempoA - First tempo in BPM
+     * @param tempoB - Second tempo in BPM
+     * @param tolerance - Tolerance for ratio comparison (default: 0.1 = 10%)
+     * @returns True if tempos are ~0.5x or ~2x each other
+     */
+    private isOctaveMultiple;
+    /**
+     * Filter out octave multiples from a list of tempos
+     *
+     * When multiple tempos are detected but some are octave multiples of others,
+     * we keep only one representative tempo. This prevents false detection of
+     * "multiple tempos" when the track is actually at a consistent tempo but
+     * detected at different octaves (e.g., 60 BPM and 120 BPM).
+     *
+     * Algorithm:
+     * 1. Sort tempos in ascending order
+     * 2. For each tempo, check if it's an octave multiple of any already-kept tempo
+     * 3. If not an octave multiple of any kept tempo, add it to the result
+     *
+     * @param tempos - Array of tempo values in BPM
+     * @returns Filtered array with octave multiples removed
+     */
+    private filterOctaveMultiples;
+    /**
+     * Find the crossing point between two tempo clusters
+     *
+     * Core boundary detection algorithm for the crossing paths strategy:
+     * 1. If NO beats between clusters → automatic boundary (no evidence of drift)
+     * 2. If beats exist between clusters:
+     *    - Interpolate forwards from Cluster 1 with drift
+     *    - Interpolate backwards from Cluster 2 with drift
+     *    - At crossing point, measure gap between forward and backward positions
+     *    - If gap < threshold → drift bridged it → no boundary
+     *    - If gap > threshold → sudden jump → return boundary timestamp
+     *
+     * @param cluster1 - First tempo cluster (earlier in time)
+     * @param cluster2 - Second tempo cluster (later in time)
+     * @param allBeats - All detected beats in the track
+     * @returns Crossing point analysis result
+     */
+    private findCrossingPoint;
+    /**
+     * Measure the gap between forwards and backwards interpolation at crossing point
+     *
+     * Compares forwards and backwards interpolation results at the crossing point
+     * to determine if tempo drift could bridge the gap between clusters.
+     *
+     * @param forwardsResult - Result of forwards drift interpolation
+     * @param backwardsResult - Result of backwards drift interpolation
+     * @param c1Interval - Cluster 1's interval (for reference)
+     * @param c2Interval - Cluster 2's interval (for reference)
+     * @returns Gap measurement result
+     */
+    private measureGapAtCrossing;
+    /**
+     * Assign connecting beats to sections based on phase alignment
+     *
+     * For each beat between clusters, check phase alignment with both clusters
+     * and assign to the one with better alignment.
+     *
+     * @param connectingBeats - Beats between the two clusters
+     * @param cluster1 - First cluster (earlier in time)
+     * @param cluster2 - Second cluster (later in time)
+     * @param boundaryTimestamp - The determined boundary timestamp
+     * @returns Beats assigned to each section
+     */
+    private assignBeatsToSections;
+    /**
+     * Calculate phase alignment between a beat and a cluster's tempo grid
+     *
+     * Binary check: returns 1 if beat is within tolerance of expected grid position,
+     * 0 otherwise.
+     *
+     * @param beatTimestamp - Timestamp of the beat to check
+     * @param clusterAnchor - Anchor timestamp (e.g., first or last beat of cluster)
+     * @param clusterInterval - Cluster's interval in seconds
+     * @param tolerance - Tolerance as ratio of interval (default: 0.1 = 10%)
+     * @returns 1 if aligned, 0 if not
+     */
+    private calculatePhaseAlignment;
+    /**
+     * Run full multi-tempo analysis to detect section boundaries
+     *
+     * This is the expensive part that only runs when:
+     * 1. enableMultiTempo option is true
+     * 2. Multiple tempo clusters have been detected
+     *
+     * Uses the crossing paths strategy to determine exact boundaries between sections.
+     *
+     * @param beats - All detected beats in the track
+     * @param clusters - Verified tempo clusters
+     * @param duration - Track duration in seconds
+     * @returns TempoSection array with boundaries, or null if no valid sections
+     */
+    private runMultiTempoAnalysis;
+    /**
+     * Re-interpolate boundary regions between tempo sections
+     *
+     * When multi-tempo is applied, beats near section boundaries need to be
+     * re-interpolated using the correct tempo for each section.
+     *
+     * @param mergedBeats - Current merged beats (single-tempo interpolation)
+     * @param tempoSections - Detected tempo sections with boundaries
+     * @param detectedBeats - Original detected beats
+     * @param downbeatConfig - Downbeat configuration
+     * @returns Re-interpolated merged beats
+     */
+    private reinterpolateBoundaryRegions;
+    /**
+     * Check if multi-tempo re-analysis can be applied to a beat map
+     *
+     * Used by UI to determine whether to show a "Re-analyze with Multi-Tempo" button.
+     *
+     * @param interpolatedBeatMap - The interpolated beat map to check
+     * @returns true if multi-tempo analysis is available and not yet applied
+     */
+    canApplyMultiTempo(interpolatedBeatMap: InterpolatedBeatMap): boolean;
+    /**
+     * Calculate weighted intervals between beats
+     *
+     * Weight factors:
+     * - Is the interval from a dense section? (higher weight)
+     * - Is the interval consistent with neighbors? (higher weight)
+     * - Are the bounding beats high-confidence? (higher weight)
+     *
+     * @param beats - Beats to analyze
+     * @param denseSections - Identified dense sections
+     * @returns Array of weighted intervals
+     */
+    private calculateWeightedIntervals;
+    /**
+     * Build a histogram of intervals
+     *
+     * Uses bucketing to group similar intervals together.
+     *
+     * @param weightedIntervals - Weighted intervals to histogram
+     * @returns Map of interval buckets to total weights
+     */
+    private buildIntervalHistogram;
+    /**
+     * Find peaks in the interval histogram
+     *
+     * Returns peaks sorted by weight (descending).
+     *
+     * @param histogram - Interval histogram
+     * @returns Array of peaks with interval and weight
+     */
+    private findHistogramPeaks;
+    /**
+     * Calculate simple average interval (fallback method)
+     *
+     * @param beats - Beats to analyze
+     * @returns Average interval in seconds
+     */
+    private calculateAverageInterval;
+    /**
+     * Analyze gaps between detected beats
+     *
+     * Identifies:
+     * - Half-note gaps (exactly 2x quarter note)
+     * - Anomalies (single unusual intervals)
+     * - Grid alignment score
+     *
+     * @param beats - Beats to analyze
+     * @param quarterNote - Detected quarter note interval
+     * @returns Gap analysis result
+     */
+    private analyzeGaps;
+    /**
+     * Generate beat grid using the selected algorithm
+     *
+     * Delegates to the appropriate algorithm implementation based on options.
+     *
+     * @param beatMap - Original beat map
+     * @param quarterNote - Quarter note detection
+     * @param gapAnalysis - Gap analysis result
+     * @returns Array of beats with source information
+     */
+    private generateGrid;
+    /**
+     * Interpolate forwards from a start anchor through connecting beats with drift
+     *
+     * Used by the crossing paths strategy to determine how tempo evolves when
+     * interpolating from one cluster towards another. Each detected beat encountered
+     * can push/pull the tempo based on phase alignment.
+     *
+     * @param startAnchor - Starting beat timestamp (anchor point)
+     * @param initialInterval - Initial tempo as interval in seconds
+     * @param connectingBeats - Beats to interpolate through (sorted by timestamp)
+     * @param adaptationRate - How quickly tempo adapts (0-1)
+     * @param stopAtTimestamp - Optional timestamp to stop interpolation at
+     * @returns Drift interpolation result with final tempo and beat positions
+     */
+    private interpolateForwardsWithDrift;
+    /**
+     * Interpolate backwards from an end anchor through connecting beats with drift
+     *
+     * Used by the crossing paths strategy to determine how tempo evolves when
+     * interpolating from one cluster backwards towards another. Each detected beat
+     * encountered can push/pull the tempo (in reverse time direction).
+     *
+     * @param endAnchor - Ending beat timestamp (anchor point)
+     * @param initialInterval - Initial tempo as interval in seconds
+     * @param connectingBeats - Beats to interpolate through (sorted by timestamp)
+     * @param adaptationRate - How quickly tempo adapts (0-1)
+     * @param stopAtTimestamp - Optional timestamp to stop interpolation at
+     * @returns Drift interpolation result with final tempo and beat positions
+     */
+    private interpolateBackwardsWithDrift;
+    /**
+     * Approach 2: Adaptive Phase-Locked Grid
+     *
+     * Handles tempo drift by:
+     * 1. Starting with quarter note interval
+     * 2. Phase tracking at each detected beat anchor
+     * 3. Allowing tempo to drift slightly between anchors
+     *
+     * @param beatMap - Original beat map
+     * @param quarterNote - Quarter note detection
+     * @returns Grid beats with source information
+     */
+    private interpolateAdaptivePhaseLocked;
+    /**
+     * Merge detected beats with grid beats
+     *
+     * Detected beats override interpolated beats at the same position.
+     *
+     * @param detectedBeats - Original detected beats
+     * @param gridBeats - Grid beats (interpolated)
+     * @param downbeatConfig - Downbeat configuration from the BeatMap
+     * @returns Merged beats with source information
+     */
+    private mergeBeats;
+    /**
+     * Reassign beat positions (beatInMeasure, isDownbeat, measureNumber)
+     * based on the merged beat sequence using the provided downbeat configuration.
+     *
+     * Supports multiple segments for time signature changes within a track.
+     *
+     * IMPORTANT: Measure numbers CONTINUE across segment boundaries.
+     * When time signature changes, measure number doesn't reset - it keeps
+     * incrementing. Only the beatsPerMeasure changes.
+     *
+     * @param beats - Merged beats to update
+     * @param downbeatConfig - Downbeat configuration from BeatMap (undefined = default)
+     */
+    private reassignBeatPositions;
+    /**
+     * Compute measure offsets for each segment to continue numbering across boundaries
+     *
+     * @param segments - Array of downbeat segments (must be ordered by startBeat)
+     * @param totalBeats - Total number of beats
+     * @returns Array of measure offsets for each segment
+     */
+    private computeMeasureOffsets;
+    /**
+     * Find the index of the active segment for a given beat index
+     * Segments are contiguous - each covers beats until the next segment starts
+     *
+     * @param segments - Array of downbeat segments (must be ordered by startBeat)
+     * @param beatIndex - The beat index to find the active segment for
+     * @returns The index of the active segment
+     */
+    private findActiveSegmentIndex;
+    /**
+     * Calculate confidence score from components
+     */
+    private calculateConfidence;
+    /**
+     * Create an interpolated beat
+     */
+    private createInterpolatedBeat;
+    /**
+     * Create a detected beat with source info
+     */
+    private createDetectedBeat;
+    /**
+     * Find a beat near a given timestamp within tolerance
+     */
+    private findBeatNear;
+    /**
+     * Find the nearest anchor beat to a given time
+     */
+    private findNearestAnchor;
+    /**
+     * Calculate tempo drift ratio (max local tempo / min local tempo)
+     */
+    private calculateTempoDriftRatio;
+    /**
+     * Create an empty interpolated beat map (edge case)
+     */
+    private createEmptyInterpolatedBeatMap;
+    /**
+     * Create a single-beat interpolated beat map (edge case)
+     */
+    private createSingleBeatInterpolatedBeatMap;
+    /**
+     * Convert an InterpolatedBeatMap to JSON string
+     *
+     * @param interpolatedBeatMap - Interpolated beat map to serialize
+     * @returns JSON string
+     *
+     * @example
+     * ```typescript
+     * const interpolator = new BeatInterpolator();
+     * const interpolatedBeatMap = interpolator.interpolate(beatMap);
+     *
+     * // Serialize to JSON for storage
+     * const json = BeatInterpolator.toJSON(interpolatedBeatMap);
+     * localStorage.setItem('beatmap', json);
+     * ```
+     */
+    static toJSON(interpolatedBeatMap: InterpolatedBeatMap): string;
+    /**
+     * Parse an InterpolatedBeatMap from JSON string
+     *
+     * @param jsonString - JSON string to parse
+     * @returns Interpolated beat map
+     *
+     * @example
+     * ```typescript
+     * // Load from storage
+     * const json = localStorage.getItem('beatmap');
+     * const interpolatedBeatMap = BeatInterpolator.fromJSON(json);
+     *
+     * // Use the loaded beat map
+     * console.log(interpolatedBeatMap.mergedBeats.length);
+     * ```
+     */
+    static fromJSON(jsonString: string): InterpolatedBeatMap;
+    /**
+     * Save an InterpolatedBeatMap to a file (Node.js only)
+     *
+     * @param interpolatedBeatMap - Interpolated beat map to save
+     * @param filePath - Path to save to
+     *
+     * @example
+     * ```typescript
+     * const interpolator = new BeatInterpolator();
+     * const interpolatedBeatMap = interpolator.interpolate(beatMap);
+     * await BeatInterpolator.saveToFile(interpolatedBeatMap, './beatmap.json');
+     * ```
+     */
+    static saveToFile(interpolatedBeatMap: InterpolatedBeatMap, filePath: string): Promise<void>;
+    /**
+     * Load an InterpolatedBeatMap from a file (Node.js only)
+     *
+     * @param filePath - Path to load from
+     * @returns Interpolated beat map
+     *
+     * @example
+     * ```typescript
+     * const interpolatedBeatMap = await BeatInterpolator.loadFromFile('./beatmap.json');
+     * console.log(interpolatedBeatMap.mergedBeats.length);
+     * ```
+     */
+    static loadFromFile(filePath: string): Promise<InterpolatedBeatMap>;
+}
+//# sourceMappingURL=BeatInterpolator.d.ts.map

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

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

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

@@ -0,0 +1,170 @@
+/**
+ * Beat Map Generator
+ *
+ * Orchestrates the beat detection pipeline to generate complete beat maps:
+ * 1. Load/decode audio
+ * 2. Calculate Onset Strength Envelope (OSE)
+ * 3. Estimate Tempo
+ * 4. Run DP Beat Tracker
+ * 5. Detect Downbeats
+ * 6. Assemble BeatMap
+ *
+ * Supports JSON serialization and file I/O for caching beat maps.
+ */
+import type { BeatMap, BeatMapGeneratorOptions, BeatMapGenerationProgress, DownbeatConfig } from '../../types/BeatMap.js';
+/**
+ * Progress callback type
+ */
+export type ProgressCallback = (progress: BeatMapGenerationProgress) => void;
+export declare class BeatMapGenerator {
+    private options;
+    private state;
+    /**
+     * Create a new BeatMapGenerator
+     *
+     * @param options - Configuration options (all optional, defaults provided)
+     */
+    constructor(options?: BeatMapGeneratorOptions);
+    /**
+     * Get the current configuration
+     *
+     * @returns The current configuration
+     */
+    getConfig(): Required<BeatMapGeneratorOptions>;
+    /**
+     * Generate a beat map from an audio URL
+     *
+     * IMPORTANT: The typical workflow is to generate FIRST with default config,
+     * examine the beat map to identify the correct downbeat, then use
+     * reapplyDownbeatConfig() to set it. You usually don't know the correct
+     * downbeat until after seeing the generated beat map.
+     *
+     * @param audioUrl - URL of the audio file
+     * @param audioId - Unique identifier for the audio source
+     * @param downbeatConfig - Optional manual downbeat configuration (defaults to beat 0 = downbeat, 4/4 time)
+     *                          If provided, will be stored in the resulting BeatMap
+     * @param onProgress - Optional progress callback
+     * @returns Generated beat map
+     */
+    generateBeatMap(audioUrl: string, audioId: string, downbeatConfig?: DownbeatConfig, onProgress?: ProgressCallback): Promise<BeatMap>;
+    /**
+     * Generate a beat map from an AudioBuffer
+     *
+     * IMPORTANT: The typical workflow is to generate FIRST with default config,
+     * examine the beat map to identify the correct downbeat, then use
+     * reapplyDownbeatConfig() to set it. You usually don't know the correct
+     * downbeat until after seeing the generated beat map.
+     *
+     * @param audioBuffer - Decoded audio buffer
+     * @param audioId - Unique identifier for the audio source
+     * @param downbeatConfig - Optional manual downbeat configuration (defaults to beat 0 = downbeat, 4/4 time)
+     *                          If provided, will be stored in the resulting BeatMap
+     * @param onProgress - Optional progress callback
+     * @returns Generated beat map
+     */
+    generateBeatMapFromBuffer(audioBuffer: AudioBuffer, audioId: string, downbeatConfig?: DownbeatConfig, onProgress?: ProgressCallback): Promise<BeatMap>;
+    /**
+     * Get the current generation progress
+     *
+     * @returns Current progress or null if no generation is active
+     */
+    getProgress(): BeatMapGenerationProgress | null;
+    /**
+     * Cancel the current generation
+     */
+    cancel(): void;
+    /**
+     * Apply intensity threshold to filter weak beats
+     *
+     * @param beats - Beats to filter
+     * @returns Filtered beats
+     */
+    private applyIntensityThreshold;
+    /**
+     * Apply measure labels to beats based on downbeat configuration
+     *
+     * Calculates beatInMeasure, isDownbeat, and measureNumber for each beat
+     * based on the provided downbeat configuration.
+     *
+     * IMPORTANT: Measure numbers CONTINUE across segment boundaries.
+     * When time signature changes, measure number doesn't reset - it keeps
+     * incrementing. Only the beatsPerMeasure changes.
+     *
+     * @param beats - Beats to label (with timestamps)
+     * @param config - Downbeat configuration
+     * @returns Beats with measure information populated
+     */
+    private applyMeasureLabels;
+    /**
+     * Compute measure offsets for each segment to continue numbering across boundaries
+     *
+     * @param segments - Array of downbeat segments (must be ordered by startBeat)
+     * @param totalBeats - Total number of beats
+     * @returns Array of measure offsets for each segment
+     */
+    private computeMeasureOffsets;
+    /**
+     * Find the index of the active segment for a given beat index
+     * Segments are contiguous - each covers beats until the next segment starts
+     *
+     * @param segments - Array of downbeat segments (must be ordered by startBeat)
+     * @param beatIndex - The beat index to find the active segment for
+     * @returns The index of the active segment
+     */
+    private findActiveSegmentIndex;
+    /**
+     * Filter beats by how well they align with the tempo grid.
+     *
+     * This post-processing step removes beats that deviate significantly from
+     * the expected quarter-note grid based on the detected tempo.
+     *
+     * @param beats - Beats to filter
+     * @param tempoEstimate - Tempo estimate with beat period
+     * @param filterThreshold - Grid alignment threshold (0.0-1.0)
+     * @returns Filtered beats
+     */
+    private filterBeatsByGridAlignment;
+    /**
+     * Update progress state
+     */
+    private updateProgress;
+    /**
+     * Fetch and decode audio from a URL
+     */
+    private fetchAndDecode;
+    /**
+     * Convert a BeatMap to JSON string
+     *
+     * @param beatMap - Beat map to serialize
+     * @returns JSON string
+     */
+    static toJSON(beatMap: BeatMap): string;
+    /**
+     * Parse a BeatMap from JSON string
+     *
+     * @param jsonString - JSON string to parse
+     * @returns Beat map
+     */
+    static fromJSON(jsonString: string): BeatMap;
+    /**
+     * Save a BeatMap to a file (Node.js only)
+     *
+     * @param beatMap - Beat map to save
+     * @param filePath - Path to save to
+     */
+    static saveToFile(beatMap: BeatMap, filePath: string): Promise<void>;
+    /**
+     * Load a BeatMap from a file (Node.js only)
+     *
+     * @param filePath - Path to load from
+     * @returns Beat map
+     */
+    static loadFromFile(filePath: string): Promise<BeatMap>;
+}
+export interface BeatMapGeneratorInstance {
+    /** Instance method for toJSON - serializes a beat map */
+    toJSON(beatMap: BeatMap): string;
+    /** Instance method for fromJSON - parses a beat map */
+    fromJSON(jsonString: string): BeatMap;
+}
+//# sourceMappingURL=BeatMapGenerator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BeatMapGenerator.d.ts","sourceRoot":"","sources":["../../../../src/core/analysis/beat/BeatMapGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAER,OAAO,EAEP,uBAAuB,EAEvB,yBAAyB,EAEzB,cAAc,EAEjB,MAAM,wBAAwB,CAAC;AAiBhC;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,yBAAyB,KAAK,IAAI,CAAC;AA+D7E,qBAAa,gBAAgB;IACzB,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,KAAK,CAAgC;IAE7C;;;;OAIG;gBACS,OAAO,GAAE,uBAA4B;IAqCjD;;;;OAIG;IACH,SAAS,IAAI,QAAQ,CAAC,uBAAuB,CAAC;IAI9C;;;;;;;;;;;;;;OAcG;IACG,eAAe,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,cAAc,EAC/B,UAAU,CAAC,EAAE,gBAAgB,GAC9B,OAAO,CAAC,OAAO,CAAC;IAuBnB;;;;;;;;;;;;;;OAcG;IACG,yBAAyB,CAC3B,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,cAAc,EAC/B,UAAU,CAAC,EAAE,gBAAgB,GAC9B,OAAO,CAAC,OAAO,CAAC;IA8JnB;;;;OAIG;IACH,WAAW,IAAI,yBAAyB,GAAG,IAAI;IAI/C;;OAEG;IACH,MAAM,IAAI,IAAI;IAYd;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAS/B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB;IA0C1B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IA2B7B;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAe9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAkClC;;OAEG;IACH,OAAO,CAAC,cAAc;IAUtB;;OAEG;YACW,cAAc;IAqB5B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM;IAoBvC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAoB5C;;;;;OAKG;WACU,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1E;;;;;OAKG;WACU,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAWhE;AAGD,MAAM,WAAW,wBAAwB;IACrC,yDAAyD;IACzD,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IACjC,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CACzC"}