playlist-data-engine 1.1.0

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

@@ -0,0 +1,180 @@
+/**
+ * Beat Key Helper Functions
+ *
+ * Utility functions for assigning and managing required keys on beat maps.
+ * Used for rhythm game chart creation where specific keys must be pressed
+ * for specific beats.
+ *
+ * @module beatKeyHelpers
+ */
+import type { BeatMap, InterpolatedBeatMap, UnifiedBeatMap, SubdividedBeatMap } from '../../types/BeatMap.js';
+/**
+ * Union type of all beat map types that support key assignment
+ */
+export type KeyAssignableBeatMap = BeatMap | InterpolatedBeatMap | UnifiedBeatMap | SubdividedBeatMap;
+/**
+ * Assignment for bulk key operations
+ */
+export interface KeyAssignment {
+    /** Index of the beat to assign the key to */
+    beatIndex: number;
+    /** Key to assign (string to set, null to remove) */
+    key: string | null;
+}
+/**
+ * Assign a required key to a single beat in a beat map
+ *
+ * Returns a new beat map with the updated beat (immutable operation).
+ * Pass `null` as the key to remove an existing required key assignment.
+ *
+ * @param beatMap - The beat map to modify (BeatMap, InterpolatedBeatMap, UnifiedBeatMap, or SubdividedBeatMap)
+ * @param beatIndex - Index of the beat to update
+ * @param key - Key to assign (e.g., 'up', 'down', 'left', 'right') or null to remove
+ * @returns New beat map with the updated beat
+ * @throws Error if beatIndex is out of bounds
+ *
+ * @example
+ * ```typescript
+ * import { assignKeyToBeat } from 'playlist-data-engine';
+ *
+ * // Assign a key to a beat
+ * const updatedMap = assignKeyToBeat(subdividedMap, 0, 'left');
+ *
+ * // Remove a key from a beat
+ * const clearedMap = assignKeyToBeat(updatedMap, 0, null);
+ * ```
+ */
+export declare function assignKeyToBeat<T extends KeyAssignableBeatMap>(beatMap: T, beatIndex: number, key: string | null): T;
+/**
+ * Assign required keys to multiple beats in a single operation
+ *
+ * More efficient than calling assignKeyToBeat multiple times for bulk updates.
+ * Useful for chart creation UI with "paint/brush" mode.
+ *
+ * @param beatMap - The beat map to modify
+ * @param assignments - Array of key assignments to apply
+ * @returns New beat map with all updates applied
+ * @throws Error if any beatIndex is out of bounds
+ *
+ * @example
+ * ```typescript
+ * import { assignKeysToBeats } from 'playlist-data-engine';
+ *
+ * const chartMap = assignKeysToBeats(subdividedMap, [
+ *     { beatIndex: 0, key: 'left' },
+ *     { beatIndex: 1, key: 'down' },
+ *     { beatIndex: 2, key: 'up' },
+ *     { beatIndex: 3, key: 'right' },
+ * ]);
+ * ```
+ */
+export declare function assignKeysToBeats<T extends KeyAssignableBeatMap>(beatMap: T, assignments: KeyAssignment[]): T;
+/**
+ * Extract a map of beat indices to required keys
+ *
+ * Returns a Map containing only the beats that have required keys assigned.
+ * Useful for serialization, UI display, and debugging.
+ *
+ * @param beatMap - The beat map to extract keys from
+ * @returns Map of beatIndex → requiredKey for beats with keys assigned
+ *
+ * @example
+ * ```typescript
+ * import { extractKeyMap } from 'playlist-data-engine';
+ *
+ * const keyMap = extractKeyMap(chartMap);
+ *
+ * // Iterate over assigned keys
+ * for (const [beatIndex, key] of keyMap) {
+ *     console.log(`Beat ${beatIndex}: ${key}`);
+ * }
+ *
+ * // Check if any keys are assigned
+ * if (keyMap.size === 0) {
+ *     console.log('No keys assigned - not a chart');
+ * }
+ *
+ * // Convert to plain object for JSON
+ * const keyObject = Object.fromEntries(keyMap);
+ * // { "0": "left", "1": "down", "2": "up" }
+ * ```
+ */
+export declare function extractKeyMap(beatMap: KeyAssignableBeatMap): Map<number, string>;
+/**
+ * Remove all required key assignments from a beat map
+ *
+ * Returns a new beat map with all requiredKey properties removed.
+ * Useful for resetting a chart back to a plain beat map.
+ *
+ * @param beatMap - The beat map to clear keys from
+ * @returns New beat map with all keys removed
+ *
+ * @example
+ * ```typescript
+ * import { clearAllKeys } from 'playlist-data-engine';
+ *
+ * // Reset a chart to a plain beat map
+ * const plainMap = clearAllKeys(chartMap);
+ *
+ * // Verify no keys remain
+ * const keyMap = extractKeyMap(plainMap);
+ * console.log(keyMap.size); // 0
+ * ```
+ */
+export declare function clearAllKeys<T extends KeyAssignableBeatMap>(beatMap: T): T;
+/**
+ * Check if a beat map has any required keys assigned
+ *
+ * @param beatMap - The beat map to check
+ * @returns true if any beat has a required key assigned
+ *
+ * @example
+ * ```typescript
+ * import { hasRequiredKeys } from 'playlist-data-engine';
+ *
+ * if (hasRequiredKeys(beatMap)) {
+ *     console.log('This is a chart with key requirements');
+ * } else {
+ *     console.log('This is a plain beat map');
+ * }
+ * ```
+ */
+export declare function hasRequiredKeys(beatMap: KeyAssignableBeatMap): boolean;
+/**
+ * Get the count of beats with required keys assigned
+ *
+ * @param beatMap - The beat map to count keys from
+ * @returns Number of beats with required keys
+ *
+ * @example
+ * ```typescript
+ * import { getKeyCount } from 'playlist-data-engine';
+ *
+ * const keyCount = getKeyCount(chartMap);
+ * console.log(`${keyCount} beats have key requirements`);
+ * ```
+ */
+export declare function getKeyCount(beatMap: KeyAssignableBeatMap): number;
+/**
+ * Get all unique keys used in a beat map
+ *
+ * Useful for determining which input buttons are needed for gameplay.
+ *
+ * @param beatMap - The beat map to get keys from
+ * @returns Array of unique key strings (sorted alphabetically)
+ *
+ * @example
+ * ```typescript
+ * import { getUsedKeys } from 'playlist-data-engine';
+ *
+ * const usedKeys = getUsedKeys(chartMap);
+ * // ['down', 'left', 'right', 'up']
+ *
+ * // Set up game controls for only the needed keys
+ * for (const key of usedKeys) {
+ *     setupKeyHandler(key);
+ * }
+ * ```
+ */
+export declare function getUsedKeys(beatMap: KeyAssignableBeatMap): string[];
+//# sourceMappingURL=beatKeyHelpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"beatKeyHelpers.d.ts","sourceRoot":"","sources":["../../../../src/core/analysis/beat/beatKeyHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAER,OAAO,EACP,mBAAmB,EACnB,cAAc,EAEd,iBAAiB,EACpB,MAAM,wBAAwB,CAAC;AAMhC;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,mBAAmB,GAAG,cAAc,GAAG,iBAAiB,CAAC;AAEtG;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAgDD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,oBAAoB,EAC1D,OAAO,EAAE,CAAC,EACV,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GAAG,IAAI,GACnB,CAAC,CA4BH;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,oBAAoB,EAC5D,OAAO,EAAE,CAAC,EACV,WAAW,EAAE,aAAa,EAAE,GAC7B,CAAC,CAyCH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAYhF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,oBAAoB,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAa1E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAGtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAGjE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAWnE"}

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

@@ -0,0 +1,41 @@
+/**
+ * Beat Detection Module
+ *
+ * Exports for the Ellis Dynamic Programming beat tracking system.
+ */
+export type { Beat, BeatMap, BeatMapMetadata, BeatEvent, BeatEventType, BeatStreamCallback, AudioSyncState, BeatMapGeneratorOptions, BeatStreamOptions, BeatMapJSON, BeatAccuracy, ButtonPressResult, TempoEstimate, OSEConfig, BeatTrackerConfig, TempoDetectorConfig, BeatMapGenerationProgress, AccuracyThresholds, DifficultyPreset, ThresholdValidationResult, TimeSignatureConfig, DownbeatSegment, DownbeatConfig, BeatSource, BeatWithSource, QuarterNoteDetection, GapAnalysis, InterpolationMetadata, InterpolatedBeatMap, BeatInterpolationOptions, BeatWithSourceJSON, QuarterNoteDetectionJSON, GapAnalysisJSON, InterpolationMetadataJSON, InterpolatedBeatMapJSON, UnifiedBeatMap, SubdivisionType, SubdivisionConfig, SubdividedBeat, SubdividedBeatMap, SubdivisionMetadata, GrooveDirection, GrooveResult, GrooveState, GrooveAnalyzerOptions, } from '../../types/BeatMap.js';
+export { DEFAULT_BEATMAP_GENERATOR_OPTIONS, DEFAULT_BEATSTREAM_OPTIONS, BEAT_ACCURACY_THRESHOLDS, BEAT_DETECTION_VERSION, BEAT_DETECTION_ALGORITHM, EASY_ACCURACY_THRESHOLDS, MEDIUM_ACCURACY_THRESHOLDS, HARD_ACCURACY_THRESHOLDS, getAccuracyThresholdsForPreset, validateThresholds, DEFAULT_BEAT_INTERPOLATION_OPTIONS, DEFAULT_TIME_SIGNATURE, DEFAULT_DOWNBEAT_CONFIG, MIN_BEATS_PER_MEASURE, MAX_BEATS_PER_MEASURE, validateDownbeatConfig, validateDownbeatConfigAgainstBeats, DEFAULT_SUBDIVISION_CONFIG, MAX_SUBDIVISION_DENSITY, VALID_SUBDIVISION_TYPES, isValidSubdivisionType, getSubdivisionDensity, validateSubdivisionConfig, validateSubdivisionConfigAgainstBeats, validateSubdivisionDensity, DEFAULT_GROOVE_OPTIONS, } from '../../types/BeatMap.js';
+export { OnsetStrengthEnvelope, type OSEResult } from './OnsetStrengthEnvelope.js';
+export { TempoDetector } from './TempoDetector.js';
+export { BeatTracker, type BeatTrackingResult } from './BeatTracker.js';
+export { BeatMapGenerator, type ProgressCallback } from './BeatMapGenerator.js';
+export { BeatStream } from './BeatStream.js';
+export { BeatInterpolator } from './BeatInterpolator.js';
+export { BeatSubdivider, type BeatSubdividerOptions } from './BeatSubdivider.js';
+export { GrooveAnalyzer } from './GrooveAnalyzer.js';
+export { unifyBeatMap } from './utils/unifyBeatMap.js';
+export { subdivideBeatMap } from './utils/subdivideBeatMap.js';
+export { generateDebugReport, collectHistogramData, collectGapDetails, collectBeatDebugInfo, collectTempoDriftData, formatDebugReportToConsole, formatDebugReportToJSON, generateTempoDriftVisualization, generateConfidenceVisualization, BeatInterpolationDebug, DEFAULT_DEBUG_OUTPUT_OPTIONS, } from './utils/beatInterpolationDebug.js';
+export type { HistogramEntry, GapDetail, TempoDriftPoint, BeatDebugInfo, InterpolationDebugReport, DebugOutputOptions, } from './utils/beatInterpolationDebug.js';
+export { hzToMel, melToHz, resampleAudio, createMelFilterbank, highPassFilter, gaussianSmooth, calculateStdDev, performFFT, performSTFT, type ResampledAudio, type STFTResult, } from './utils/audioUtils.js';
+export { TransientDetector } from './TransientDetector.js';
+export type { TransientResult, TransientAnalysis, TransientDetectorConfig, TransientDetectionMethod, } from './TransientDetector.js';
+export { RhythmQuantizer } from './RhythmQuantizer.js';
+export type { QuantizationConfig, QuantizedBandStreams, DensityValidationConfig, DensityValidationResult, GridType, GridDecision, GeneratedBeat, GeneratedRhythmMap, GridDecider, } from './RhythmQuantizer.js';
+export { TempoAwareQuantizer, HighBpmGridRestrictionRule, DEFAULT_TEMPO_AWARE_CONFIG, } from './TempoAwareQuantizer.js';
+export type { TempoQuantizationRule, TempoRuleContext, TempoAwareQuantizerConfig, HighBpmGridRestrictionConfig, } from './TempoAwareQuantizer.js';
+export { PhraseAnalyzer } from './PhraseAnalyzer.js';
+export type { PhraseOccurrence, RhythmicPhrase, BandPhraseAnalysis, PhraseAnalysisResult, PhraseAnalyzerConfig, } from './PhraseAnalyzer.js';
+export { DensityAnalyzer } from './DensityAnalyzer.js';
+export type { DensityCategory, NaturalDifficulty, BeatDensityMetrics, SectionDensityMetrics, BandDensityMetrics, DensityAnalysisResult, DensityAnalyzerConfig, } from './DensityAnalyzer.js';
+export { StreamScorer } from './StreamScorer.js';
+export type { Band, ScoringFactors, SectionScore, StreamScoringResult, SectionWinner, StreamScorerConfig, BandBiasWeights, } from './StreamScorer.js';
+export { CompositeStreamGenerator } from './CompositeStreamGenerator.js';
+export type { CompositeSection, CompositeBeat, CompositeStream, CompositeStreamConfig, } from './CompositeStreamGenerator.js';
+export { DifficultyVariantGenerator, SUBDIVISION_LIMITS, ALL_GRID_TYPES, isGridTypeAllowed, getAllowedGridTypes, convertToAllowedGridType, naturalDifficultyToLevel, validateSubdivisionLimits, getTempoAwareAllowedGridTypes, MEDIUM_RESTRICT_BPM, HARD_RESTRICT_BPM, EASY_QUARTER_NOTE_BPM, } from './DifficultyVariantGenerator.js';
+export type { ExtendedGridType, DifficultyLevel, PresetDifficultyLevel, MaxSubdivision, SubdivisionLimitConfig, EditType, VariantBeat, DifficultyVariant, SubdivisionConversionMetadata, SubdivisionValidationResult, SubdivisionViolation, DifficultyVariantConfig, DensityTargetStrategy, BeatCountTarget, VariantDensityValidationResult, } from './DifficultyVariantGenerator.js';
+export { assignKeyToBeat, assignKeysToBeats, extractKeyMap, clearAllKeys, hasRequiredKeys, getKeyCount, getUsedKeys, type KeyAssignableBeatMap, type KeyAssignment, } from './beatKeyHelpers.js';
+export { RhythmicBalancer } from './RhythmicBalancer.js';
+export type { RhythmicBalanceConfig, StrongBeatEmphasis, BalancerAction, BalanceStats, BalanceResult, } from './RhythmicBalancer.js';
+export { DEFAULT_RHYTHMIC_BALANCE_CONFIG, getMetricGroupSize, isMetricStrongBeat, isMetricWeakBeat, findActiveSegment, isStrongBeatForEmphasis, } from './RhythmicBalancer.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/analysis/beat/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACR,IAAI,EACJ,OAAO,EACP,eAAe,EACf,SAAS,EACT,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACvB,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EAEzB,kBAAkB,EAClB,gBAAgB,EAChB,yBAAyB,EAEzB,mBAAmB,EACnB,eAAe,EACf,cAAc,EAEd,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,EAExB,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,EACf,yBAAyB,EACzB,uBAAuB,EAEvB,cAAc,EAEd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EAEnB,eAAe,EACf,YAAY,EACZ,WAAW,EACX,qBAAqB,GACxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACH,iCAAiC,EACjC,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,wBAAwB,EAExB,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,8BAA8B,EAE9B,kBAAkB,EAElB,kCAAkC,EAElC,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,kCAAkC,EAElC,0BAA0B,EAC1B,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,EACzB,qCAAqC,EACrC,0BAA0B,EAE1B,sBAAsB,GACzB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,qBAAqB,EAAE,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D,OAAO,EACH,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,EAC1B,uBAAuB,EACvB,+BAA+B,EAC/B,+BAA+B,EAC/B,sBAAsB,EACtB,4BAA4B,GAC/B,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACR,cAAc,EACd,SAAS,EACT,eAAe,EACf,aAAa,EACb,wBAAwB,EACxB,kBAAkB,GACrB,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EACH,OAAO,EACP,OAAO,EACP,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,eAAe,EACf,UAAU,EACV,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,UAAU,GAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EACR,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EACvB,wBAAwB,GAC3B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACR,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,WAAW,GACd,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACH,mBAAmB,EACnB,0BAA0B,EAC1B,0BAA0B,GAC7B,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACR,qBAAqB,EACrB,gBAAgB,EAChB,yBAAyB,EACzB,4BAA4B,GAC/B,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EACR,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACvB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACR,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,GACxB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EACR,IAAI,EACJ,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,eAAe,GAClB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,YAAY,EACR,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,qBAAqB,GACxB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACH,0BAA0B,EAC1B,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,EACzB,6BAA6B,EAC7B,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACxB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACR,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,sBAAsB,EACtB,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,6BAA6B,EAC7B,2BAA2B,EAC3B,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB,EACrB,eAAe,EACf,8BAA8B,GACjC,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EACH,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,WAAW,EACX,WAAW,EACX,KAAK,oBAAoB,EACzB,KAAK,aAAa,GACrB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EACR,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,aAAa,GAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACH,+BAA+B,EAC/B,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,GAC1B,MAAM,uBAAuB,CAAC"}

package/dist/core/analysis/beat/utils/audioUtils.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Audio utility functions for beat detection
+ *
+ * These utilities support the Ellis Dynamic Programming beat tracking algorithm
+ * by providing audio preprocessing, Mel filterbank generation, and signal processing.
+ */
+/**
+ * Convert frequency in Hz to Mel scale
+ * Formula: m = 2595 * log10(1 + f/700)
+ *
+ * @param hz - Frequency in Hz
+ * @returns Mel scale value
+ */
+export declare function hzToMel(hz: number): number;
+/**
+ * Convert Mel scale value to frequency in Hz
+ * Formula: f = 700 * (10^(m/2595) - 1)
+ *
+ * @param mel - Mel scale value
+ * @returns Frequency in Hz
+ */
+export declare function melToHz(mel: number): number;
+/**
+ * Result of audio resampling
+ */
+export interface ResampledAudio {
+    /** Resampled audio data as mono Float32Array */
+    data: Float32Array;
+    /** Original sample rate */
+    originalSampleRate: number;
+    /** Target sample rate */
+    targetSampleRate: number;
+}
+/**
+ * Resample audio buffer to a target sample rate
+ * Uses linear interpolation for simplicity
+ *
+ * @param audioBuffer - Source audio buffer
+ * @param targetRate - Target sample rate in Hz
+ * @returns Resampled audio data with metadata
+ */
+export declare function resampleAudio(audioBuffer: AudioBuffer, targetRate: number): ResampledAudio;
+/**
+ * Create a Mel filterbank for spectral analysis
+ *
+ * Creates triangular filters spaced evenly on the Mel scale,
+ * suitable for perceptual audio analysis as per Ellis 2007.
+ *
+ * @param numBands - Number of Mel bands to create
+ * @param fftSize - FFT size used for analysis
+ * @param sampleRate - Audio sample rate in Hz
+ * @param minFreq - Minimum frequency in Hz (default: 0)
+ * @param maxFreq - Maximum frequency in Hz (default: sampleRate/2)
+ * @returns Array of Float32Array filters, each representing one Mel band
+ */
+export declare function createMelFilterbank(numBands: number, fftSize: number, sampleRate: number, minFreq?: number, maxFreq?: number): Float32Array[];
+/**
+ * Apply a high-pass filter to remove DC offset and low-frequency components
+ * Uses a simple first-order IIR filter
+ *
+ * @param signal - Input signal
+ * @param cutoff - Cutoff frequency in Hz
+ * @param sampleRate - Sample rate in Hz
+ * @returns Filtered signal
+ */
+export declare function highPassFilter(signal: Float32Array, cutoff: number, sampleRate: number): Float32Array;
+/**
+ * Apply Gaussian smoothing to a signal
+ *
+ * @param signal - Input signal
+ * @param windowMs - Window size in milliseconds
+ * @param sampleRate - Sample rate in Hz
+ * @returns Smoothed signal
+ */
+export declare function gaussianSmooth(signal: Float32Array, windowMs: number, sampleRate: number): Float32Array;
+/**
+ * Calculate the standard deviation of a signal
+ *
+ * @param signal - Input signal
+ * @returns Standard deviation
+ */
+export declare function calculateStdDev(signal: Float32Array): number;
+/**
+ * Perform FFT on a signal and return magnitude spectrum
+ * Uses Cooley-Tukey algorithm with Hann window
+ *
+ * @param signal - Input signal (will be padded to nearest power of 2)
+ * @returns Magnitude spectrum (half spectrum, positive frequencies only)
+ */
+export declare function performFFT(signal: Float32Array): Float32Array;
+/**
+ * Result of STFT analysis
+ */
+export interface STFTResult {
+    /** 2D array of magnitude spectra (frame x frequency bin) */
+    frames: Float32Array[];
+    /** Number of frames */
+    numFrames: number;
+    /** FFT size used */
+    fftSize: number;
+    /** Hop size in samples */
+    hopSize: number;
+    /** Sample rate */
+    sampleRate: number;
+}
+/**
+ * Perform Short-Time Fourier Transform (STFT) on a signal
+ *
+ * @param signal - Input signal
+ * @param fftSize - FFT window size in samples
+ * @param hopSize - Hop size in samples
+ * @param sampleRate - Sample rate in Hz
+ * @returns STFT result containing magnitude spectra for each frame
+ */
+export declare function performSTFT(signal: Float32Array, fftSize: number, hopSize: number, sampleRate: number): STFTResult;
+/**
+ * Configuration for the Butterworth band-pass filter
+ *
+ * The filter uses cascaded 2nd-order biquad sections for steep cutoff.
+ * An 8th order filter provides 48 dB/octave slope.
+ */
+export interface BandPassFilterConfig {
+    /** Filter order (must be even positive integer). Default: 8 for 48 dB/octave */
+    order?: number;
+    /** Optional Q factor adjustment. Default: 0.707 (Butterworth maximally flat) */
+    qFactor?: number;
+}
+/**
+ * Frequency band definition for multi-band analysis
+ */
+export interface FrequencyBand {
+    /** Band name identifier (e.g., 'low', 'mid', 'high') */
+    name: string;
+    /** Lower cutoff frequency in Hz */
+    lowHz: number;
+    /** Upper cutoff frequency in Hz */
+    highHz: number;
+    /** Human-readable description of the band's typical content */
+    description: string;
+}
+/**
+ * Standard frequency bands for multi-band transient detection
+ *
+ * These three bands cover the full audible spectrum and are optimized
+ * for detecting different types of rhythmic elements:
+ * - Low: Bass, kick drums, sub frequencies
+ * - Mid: Vocals, snare body, lead instruments
+ * - High: Hi-hats, cymbals, harmonics, air
+ */
+export declare const FREQUENCY_BANDS: FrequencyBand[];
+/**
+ * Apply a Butterworth band-pass filter to a signal
+ *
+ * Implements a band-pass filter by cascading high-pass and low-pass filters.
+ * Uses cascaded 2nd-order biquad sections for steep cutoff slopes.
+ *
+ * Default configuration is 8th order (48 dB/octave slope) which provides
+ * clean band separation at crossover points without significant phase distortion.
+ *
+ * @param signal - Input signal to filter
+ * @param lowHz - Lower cutoff frequency in Hz
+ * @param highHz - Upper cutoff frequency in Hz
+ * @param sampleRate - Sample rate in Hz
+ * @param config - Optional filter configuration
+ * @returns Filtered signal (same length as input)
+ * @throws Error if order is not a positive even integer
+ *
+ * @example
+ * ```typescript
+ * // Apply default 8th order band-pass filter for low band (20-500 Hz)
+ * const filtered = bandPassFilter(signal, 20, 500, 44100);
+ *
+ * // Apply 4th order filter with custom Q factor
+ * const filtered = bandPassFilter(signal, 500, 2000, 44100, { order: 4, qFactor: 0.5 });
+ * ```
+ */
+export declare function bandPassFilter(signal: Float32Array, lowHz: number, highHz: number, sampleRate: number, config?: BandPassFilterConfig): Float32Array;
+/**
+ * Apply a frequency band filter to a signal
+ *
+ * Convenience function that applies the band-pass filter using
+ * predefined frequency band settings from FREQUENCY_BANDS.
+ *
+ * @param signal - Input signal to filter
+ * @param bandName - Name of the frequency band ('low', 'mid', or 'high')
+ * @param sampleRate - Sample rate in Hz
+ * @param config - Optional filter configuration
+ * @returns Filtered signal
+ * @throws Error if bandName is not recognized
+ *
+ * @example
+ * ```typescript
+ * // Apply low band filter (20-500 Hz) for bass/kick detection
+ * const lowFiltered = applyFrequencyBand(signal, 'low', 44100);
+ *
+ * // Apply mid band filter (500-2000 Hz) for vocal/snare detection
+ * const midFiltered = applyFrequencyBand(signal, 'mid', 44100);
+ *
+ * // Apply high band filter (2000-20000 Hz) for hi-hat/cymbal detection
+ * const highFiltered = applyFrequencyBand(signal, 'high', 44100);
+ * ```
+ */
+export declare function applyFrequencyBand(signal: Float32Array, bandName: 'low' | 'mid' | 'high', sampleRate: number, config?: BandPassFilterConfig): Float32Array;
+//# sourceMappingURL=audioUtils.d.ts.map

package/dist/core/analysis/beat/utils/audioUtils.d.ts.map

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