playlist-data-engine 1.1.0

package/dist/core/generation/LevelGenerator.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Level Generator - Orchestrates complete rhythm game level generation
+ *
+ * This is the main entry point for generating playable rhythm game levels from audio.
+ * It orchestrates all phases of the pipeline:
+ *
+ * Phase 1: Rhythm generation (from procedural-rhythm-generation.md)
+ * Phase 2: Pitch analysis (if pitchInfluenceWeight > 0)
+ * Phase 3: Button mapping (from pitch-detection-button-mapping.md)
+ * Phase 4: Conversion to ChartedBeatMap
+ *
+ * Part of the Pitch Detection & Button Mapping pipeline - Phase 3.1
+ *
+ * @example
+ * ```typescript
+ * const generator = new LevelGenerator({
+ *   difficulty: 'medium',
+ *   controllerMode: 'ddr',
+ *   buttons: { pitchInfluenceWeight: 08 },
+ * });
+ *
+ * // Generate level from audio
+ * const level = await generator.generate(audioBuffer, unifiedBeatMap);
+ *
+ * // Use the chart with BeatStream
+ * const beatStream = new BeatStream(level.chart, audioContext);
+ * ```
+ */
+import type { RhythmGenerationOptions, GeneratedRhythm, RhythmMetadata } from './RhythmGenerator.js';
+import type { PitchAlgorithm } from '../analysis/EssentiaPitchDetector.js';
+import type { MelodyContourAnalysisResult } from '../analysis/MelodyContourAnalyzer.js';
+import type { ButtonMappingMetadata } from './ButtonMapper.js';
+import type { ButtonMappingConfig, ControllerMode } from '../types/ButtonMapping.js';
+import type { DifficultyPreset } from '../types/BeatMap.js';
+import type { UnifiedBeatMap } from '../types/BeatMap.js';
+import type { ChartedBeatMap } from '../types/ChartedBeatMap.js';
+import { type DifficultyVariant, type DensityGenerationConfig } from '../analysis/beat/DifficultyVariantGenerator.js';
+/**
+ * Options for level generation
+ */
+export interface LevelGenerationOptions {
+    /** Target difficulty for the generated chart */
+    difficulty: DifficultyPreset;
+    /** Controller mode (DDR or Guitar Hero) */
+    controllerMode: ControllerMode;
+    /** Rhythm generation settings (passed through to RhythmGenerator) */
+    rhythm?: Partial<RhythmGenerationOptions>;
+    /** Button mapping settings */
+    buttons?: Partial<ButtonMappingConfig>;
+    /** Seed for reproducibility */
+    seed?: string;
+    /**
+     * Pre-generated rhythm to use instead of generating new.
+     * When provided, skips the rhythm generation phase entirely.
+     * Useful for reusing rhythm from a previous generation step.
+     */
+    cachedRhythm?: GeneratedRhythm;
+    /** Which pitch detection algorithm to use. 'pyin_legacy' uses built-in pYIN; others use Essentia.js. (default: 'pitch_melodia') */
+    pitchAlgorithm?: PitchAlgorithm;
+    /** URL to the CREPE TFJS model (only required when pitchAlgorithm is 'pitch_crepe') */
+    crepeModelUrl?: string;
+    /** Optional callback to resolve Arweave URLs (gateway fallback for CREPE model) */
+    resolveUrl?: (url: string) => Promise<string>;
+    /**
+     * Probability threshold for voiced/unvoiced decision in pitch detection.
+     * Higher values require stronger pitch signal to be considered "voiced".
+     * Passed through to PitchDetectorConfig.
+     *
+     * @default 0.2
+     */
+    voicingThreshold?: number;
+}
+/**
+ * Metadata about the generated level
+ */
+export interface LevelMetadata {
+    /** Difficulty preset used */
+    difficulty: DifficultyPreset;
+    /** Controller mode used */
+    controllerMode: ControllerMode;
+    /** Rhythm generation metadata */
+    rhythmMetadata: RhythmMetadata;
+    /** Button mapping metadata */
+    buttonMetadata: ButtonMappingMetadata;
+    /** Pitch analysis metadata (if pitch detection was used) */
+    pitchMetadata: {
+        melodyRange: {
+            min: string;
+            max: string;
+        } | null;
+        directionStats: {
+            up: number;
+            down: number;
+            stable: number;
+            none: number;
+        } | null;
+        intervalStats: {
+            unison: number;
+            small: number;
+            medium: number;
+            large: number;
+            very_large: number;
+        } | null;
+    } | null;
+    /** Chart metadata */
+    chartMetadata: {
+        totalBeats: number;
+        detectedBeats: number;
+        generatedBeats: number;
+    };
+    /** Generation configuration */
+    generationConfig: LevelGenerationOptions;
+}
+/**
+ * Complete generated level ready for gameplay
+ */
+export interface GeneratedLevel {
+    /** The playable ChartedBeatMap */
+    chart: ChartedBeatMap;
+    /** The selected difficulty variant with keys assigned */
+    variant: DifficultyVariant;
+    /** Original rhythm generation output preserved */
+    rhythm: GeneratedRhythm;
+    /** Pitch analysis results (null if pitchInfluenceWeight was 0) */
+    pitchAnalysis: MelodyContourAnalysisResult | null;
+    /** Combined metadata */
+    metadata: LevelMetadata;
+}
+/**
+ * Progress callback for generation progress updates
+ */
+export type LevelProgressCallback = (progress: LevelGenerationProgress) => void;
+/**
+ * Progress information during level generation
+ */
+export interface LevelGenerationProgress {
+    /** Current stage of generation */
+    stage: 'rhythm' | 'pitch' | 'buttons' | 'conversion' | 'finalizing';
+    /** Progress within current stage (0-1) */
+    progress: number;
+    /** Human-readable status message */
+    message: string;
+}
+/**
+ * Result of level generation for all difficulties
+ */
+export interface AllDifficultiesResult {
+    easy: GeneratedLevel;
+    medium: GeneratedLevel;
+    hard: GeneratedLevel;
+    natural?: GeneratedLevel;
+}
+/**
+ * Cache phase identifier
+ */
+export type LevelCachePhase = 'rhythm' | 'pitch';
+/**
+ * Statistics about the cache
+ */
+export interface LevelCacheStats {
+    /** Number of entries currently cached */
+    entryCount: number;
+    /** Phases that have cached results */
+    cachedPhases: LevelCachePhase[];
+    /** Number of cache hits during this session */
+    hits: number;
+    /** Number of cache misses during this session */
+    misses: number;
+}
+/**
+ * Extended options for level generation with cache settings
+ */
+export interface LevelGenerationOptionsWithCache extends LevelGenerationOptions {
+    /** Enable caching of intermediate results (default: true) */
+    enableCache?: boolean;
+    /** Maximum age of cache entries in milliseconds (default: 30 minutes) */
+    cacheMaxAge?: number;
+}
+/**
+ * Level Generator
+ *
+ * Orchestrates the complete rhythm game level generation pipeline.
+ * Takes audio input and produces playable ChartedBeatMap output.
+ *
+ * @example
+ * ```typescript
+ * // With caching enabled (default)
+ * const generator = new LevelGenerator({
+ *   difficulty: 'medium',
+ *   controllerMode: 'ddr',
+ *   enableCache: true,
+ * });
+ *
+ * // First call computes and caches rhythm/pitch
+ * const level1 = await generator.generate(audioBuffer, beatMap);
+ *
+ * // Second call reuses cached results (much faster)
+ * const level2 = await generator.generate(audioBuffer, beatMap);
+ *
+ * // Clear cache when done with this audio
+ * generator.clearCache();
+ * ```
+ */
+export declare class LevelGenerator {
+    private options;
+    private buttonConfig;
+    private cache;
+    private cacheHits;
+    private cacheMisses;
+    /**
+     * Create a new LevelGenerator
+     *
+     * @param options - Generation options (partial, defaults applied)
+     */
+    constructor(options?: Partial<LevelGenerationOptionsWithCache>);
+    /**
+     * Get the current configuration
+     */
+    getOptions(): LevelGenerationOptionsWithCache;
+    /**
+     * Generate a cache key for a specific phase and inputs
+     */
+    private generateCacheKey;
+    /**
+     * Create a config fingerprint for cache invalidation
+     * Only includes config options that affect the output
+     */
+    private createConfigFingerprint;
+    /**
+     * Get a cached result if available and not expired
+     */
+    private getFromCache;
+    /**
+     * Store a result in the cache
+     */
+    private setCache;
+    /**
+     * Clear all cached results
+     */
+    clearCache(): void;
+    /**
+     * Clear expired cache entries
+     */
+    pruneExpiredCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): LevelCacheStats;
+    /**
+     * Check if a phase result is cached for the given audio ID
+     */
+    isCached(audioId: string, phase: LevelCachePhase): boolean;
+    /**
+     * Get the cache hit ratio (0-1)
+     */
+    getCacheHitRatio(): number;
+    /**
+     * Generate a level for a specific difficulty
+     *
+     * @param audioBuffer - Web Audio API AudioBuffer to analyze
+     * @param unifiedBeatMap - The unified beat map for measure/beat info
+     * @param progressCallback - Optional callback for progress updates
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Generated level with playable chart
+     * @throws {DOMException} If the operation is cancelled via signal
+     */
+    generate(audioBuffer: AudioBuffer, unifiedBeatMap: UnifiedBeatMap, progressCallback?: LevelProgressCallback, signal?: AbortSignal): Promise<GeneratedLevel>;
+    /**
+     * Generate levels for all difficulties
+     *
+     * This method efficiently reuses cached rhythm and pitch analysis results
+     * across all difficulty levels.
+     *
+     * @param audioBuffer - Web Audio API AudioBuffer to analyze
+     * @param unifiedBeatMap - The unified beat map for measure/beat info
+     * @param progressCallback - Optional callback for progress updates
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Generated levels for easy, medium, and hard
+     * @throws {DOMException} If the operation is cancelled via signal
+     */
+    generateAllDifficulties(audioBuffer: AudioBuffer, unifiedBeatMap: UnifiedBeatMap, progressCallback?: LevelProgressCallback, signal?: AbortSignal): Promise<AllDifficultiesResult>;
+    /**
+     * Generate a level at a specific target density
+     *
+     * This method provides fine-grained control over difficulty by allowing
+     * independent specification of target density (notes/second) and maximum
+     * quantization grid. Unlike the preset-based `generate()` method, this
+     * enables a continuous spectrum of difficulty.
+     *
+     * @param audioBuffer - Web Audio API AudioBuffer to analyze
+     * @param unifiedBeatMap - The unified beat map for measure/beat info
+     * @param config - Density generation configuration
+     * @param progressCallback - Optional callback for progress updates
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Generated level with playable chart
+     * @throws {DOMException} If the operation is cancelled via signal
+     *
+     * @example
+     * ```typescript
+     * const generator = new LevelGenerator({
+     *   controllerMode: 'ddr',
+     *   buttons: { pitchInfluenceWeight: 0.8 },
+     * });
+     *
+     * // Dense chart with only 8th note quantization
+     * const denseLevel = await generator.generateAtDensity(
+     *   audioBuffer,
+     *   beatMap,
+     *   { targetDensity: 3.0, maxGridType: 'straight_8th' }
+     * );
+     *
+     * // Sparse chart with 16th note grid allowed
+     * const sparseLevel = await generator.generateAtDensity(
+     *   audioBuffer,
+     *   beatMap,
+     *   { targetDensity: 0.5, maxGridType: 'straight_16th' }
+     * );
+     * ```
+     */
+    generateAtDensity(audioBuffer: AudioBuffer, unifiedBeatMap: UnifiedBeatMap, config: DensityGenerationConfig, progressCallback?: LevelProgressCallback, signal?: AbortSignal): Promise<GeneratedLevel>;
+    /**
+     * Generate levels for multiple density configurations in one call
+     *
+     * This method efficiently reuses cached rhythm and pitch analysis results
+     * across all density configurations, similar to how `generateAllDifficulties()`
+     * works for preset difficulties.
+     *
+     * @param audioBuffer - Web Audio API AudioBuffer to analyze
+     * @param unifiedBeatMap - The unified beat map for measure/beat info
+     * @param configs - Array of labeled density configurations
+     * @param progressCallback - Optional callback for progress updates
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns Map of labels to generated levels
+     * @throws {DOMException} If the operation is cancelled via signal
+     *
+     * @example
+     * ```typescript
+     * const generator = new LevelGenerator({
+     *   controllerMode: 'ddr',
+     *   buttons: { pitchInfluenceWeight: 0.8 },
+     * });
+     *
+     * const levels = await generator.generateAtDensities(
+     *   audioBuffer,
+     *   beatMap,
+     *   [
+     *     { label: 'sparse', config: { targetDensity: 0.5, maxGridType: 'straight_8th' } },
+     *     { label: 'medium', config: { targetDensity: 2.0, maxGridType: 'straight_16th' } },
+     *     { label: 'dense', config: { targetDensity: 3.5, maxGridType: 'straight_16th' } },
+     *   ]
+     * );
+     *
+     * const sparseLevel = levels.get('sparse');
+     * const denseLevel = levels.get('dense');
+     * ```
+     */
+    generateAtDensities(audioBuffer: AudioBuffer, unifiedBeatMap: UnifiedBeatMap, configs: {
+        label: string;
+        config: DensityGenerationConfig;
+    }[], progressCallback?: LevelProgressCallback, signal?: AbortSignal): Promise<Map<string, GeneratedLevel>>;
+    /**
+     * Collect grid decisions from quantization result
+     *
+     * Merges grid decisions from all bands into a single map.
+     * When multiple bands have decisions for the same beat index,
+     * the decision with higher confidence is used.
+     */
+    private collectGridDecisions;
+    /**
+     * Phase 1: Generate rhythm from audio
+     */
+    private generateRhythm;
+    /**
+     * Phase 2: Analyze pitch on rhythm beats
+     */
+    private analyzePitch;
+    /**
+     * Phase 3: Map buttons to beats
+     */
+    private mapButtons;
+    /**
+     * Phase 4: Convert to ChartedBeatMap
+     */
+    private convertToChart;
+    /**
+     * Build the final GeneratedLevel result
+     */
+    private buildLevel;
+}
+//# sourceMappingURL=LevelGenerator.d.ts.map

package/dist/core/generation/LevelGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LevelGenerator.d.ts","sourceRoot":"","sources":["../../../src/core/generation/LevelGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAIrG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAE3E,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AAExF,OAAO,KAAK,EAAqB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAElF,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAErF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAEH,KAAK,iBAAiB,EAEtB,KAAK,uBAAuB,EAC/B,MAAM,gDAAgD,CAAC;AAQxD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACnC,gDAAgD;IAChD,UAAU,EAAE,gBAAgB,CAAC;IAE7B,2CAA2C;IAC3C,cAAc,EAAE,cAAc,CAAA;IAE9B,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAA;IAEzC,8BAA8B;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAA;IAEtC,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;;;OAIG;IACH,YAAY,CAAC,EAAE,eAAe,CAAA;IAE9B,mIAAmI;IACnI,cAAc,CAAC,EAAE,cAAc,CAAA;IAE/B,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB,mFAAmF;IACnF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAE7C;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,6BAA6B;IAC7B,UAAU,EAAE,gBAAgB,CAAA;IAE5B,2BAA2B;IAC3B,cAAc,EAAE,cAAc,CAAA;IAE9B,iCAAiC;IACjC,cAAc,EAAE,cAAc,CAAA;IAE9B,8BAA8B;IAC9B,cAAc,EAAE,qBAAqB,CAAA;IAErC,4DAA4D;IAC5D,aAAa,EAAE;QACX,WAAW,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;QAChD,cAAc,EAAE;YACZ,EAAE,EAAE,MAAM,CAAA;YACV,IAAI,EAAE,MAAM,CAAA;YACZ,MAAM,EAAE,MAAM,CAAA;YACd,IAAI,EAAE,MAAM,CAAA;SACf,GAAG,IAAI,CAAA;QACR,aAAa,EAAE;YACX,MAAM,EAAE,MAAM,CAAA;YACd,KAAK,EAAE,MAAM,CAAA;YACb,MAAM,EAAE,MAAM,CAAA;YACd,KAAK,EAAE,MAAM,CAAA;YACb,UAAU,EAAE,MAAM,CAAA;SACrB,GAAG,IAAI,CAAA;KACX,GAAG,IAAI,CAAA;IAER,qBAAqB;IACrB,aAAa,EAAE;QACX,UAAU,EAAE,MAAM,CAAA;QAClB,aAAa,EAAE,MAAM,CAAA;QACrB,cAAc,EAAE,MAAM,CAAA;KACzB,CAAA;IAED,+BAA+B;IAC/B,gBAAgB,EAAE,sBAAsB,CAAA;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,kCAAkC;IAClC,KAAK,EAAE,cAAc,CAAA;IAErB,yDAAyD;IACzD,OAAO,EAAE,iBAAiB,CAAA;IAE1B,kDAAkD;IAClD,MAAM,EAAE,eAAe,CAAA;IAEvB,kEAAkE;IAClE,aAAa,EAAE,2BAA2B,GAAG,IAAI,CAAA;IAEjD,wBAAwB;IACxB,QAAQ,EAAE,aAAa,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,uBAAuB,KAAK,IAAI,CAAA;AAE/E;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACpC,kCAAkC;IAClC,KAAK,EAAE,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,YAAY,GAAG,YAAY,CAAA;IAEnE,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAEhB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC,IAAI,EAAE,cAAc,CAAA;IACpB,MAAM,EAAE,cAAc,CAAA;IACtB,IAAI,EAAE,cAAc,CAAA;IACpB,OAAO,CAAC,EAAE,cAAc,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,OAAO,CAAA;AAchD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB,sCAAsC;IACtC,YAAY,EAAE,eAAe,EAAE,CAAA;IAC/B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,+BAAgC,SAAQ,sBAAsB;IAC3E,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAsBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,YAAY,CAAsB;IAG1C,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,WAAW,CAAa;IAEhC;;;;OAIG;gBACS,OAAO,GAAE,OAAO,CAAC,+BAA+B,CAAM;IAuBlE;;OAEG;IACH,UAAU,IAAI,+BAA+B;IAQ7C;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAwB/B;;OAEG;IACH,OAAO,CAAC,YAAY;IA0BpB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAYhB;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAUzB;;OAEG;IACH,aAAa,IAAI,eAAe;IAkBhC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO;IAM1D;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAU1B;;;;;;;;;OASG;IACG,QAAQ,CACV,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,cAAc,EAC9B,gBAAgB,CAAC,EAAE,qBAAqB,EACxC,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,cAAc,CAAC;IAsG1B;;;;;;;;;;;;OAYG;IACG,uBAAuB,CACzB,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,cAAc,EAC9B,gBAAgB,CAAC,EAAE,qBAAqB,EACxC,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,qBAAqB,CAAC;IAmGjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,iBAAiB,CACnB,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,cAAc,EAC9B,MAAM,EAAE,uBAAuB,EAC/B,gBAAgB,CAAC,EAAE,qBAAqB,EACxC,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,cAAc,CAAC;IAkI1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,mBAAmB,CACrB,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,uBAAuB,CAAA;KAAE,EAAE,EAC7D,gBAAgB,CAAC,EAAE,qBAAqB,EACxC,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IA2JvC;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;OAEG;YACW,cAAc;IAwB5B;;OAEG;YACW,YAAY;IA4D1B;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB;;OAEG;IACH,OAAO,CAAC,cAAc;IAgBtB;;OAEG;IACH,OAAO,CAAC,UAAU;CAoCrB"}

package/dist/core/generation/NamingEngine.d.ts

@@ -0,0 +1,136 @@
+import type { PlaylistTrack } from '../types/Playlist';
+import type { AudioProfile } from '../types/AudioProfile';
+import type { Class } from '../types/Character';
+/**
+ * Generate RPG-style character names from track metadata and character class
+ *
+ * Combines track title, artist, and genre with audio characteristics and actual
+ * character class to create unique fantasy-inspired character names using seven
+ * random formats with weighted distribution (20-20-10-20-15-10-5):
+ * - 20% Class Title (e.g., "Midnight Dreams the Wizard")
+ * - 20% Adjective Construct (e.g., "Hypnotic Midnight Dreams")
+ * - 10% Clan Construct (e.g., "Midnight Dreams of Daft Punk")
+ * - 20% Descriptive Epithet (e.g., "Midnight Dreams, the Swift Sage")
+ * - 15% Compound Adjective (e.g., "Thunder-Blessed Midnight Dreams")
+ * - 10% Artist-Inspired (e.g., "Daftsmith of the Crystal Spire")
+ * - 5% Mononym Subtitle (e.g., "Midnight [Dreams Eternal]")
+ *
+ * Key design principle: Audio characteristics provide LIGHT influence (~50%) on name
+ * generation, with random selection equally important (~50%). All adjective categories
+ * are always considered - audio just provides weight boosts, not hard selection rules.
+ */
+export declare class NamingEngine {
+    /**
+     * Generate a unique RPG-style character name from track metadata and character class
+     *
+     * Creates fantasy-inspired character names by combining:
+     * - Track title/artist with cleaning (removes "Official Video", "Remix", etc.)
+     * - Genre classification
+     * - Audio profile characteristics (light influence via weights)
+     * - Actual character class (not genre-guessed)
+     * - Randomized format and word selection
+     *
+     * @param {string} seed - Seed for random generation (provided by CharacterGenerator)
+     * @param {PlaylistTrack} track - Track with title, artist, genre metadata
+     * @param {AudioProfile} audioProfile - Audio frequency characteristics
+     * @param {Class} characterClass - Actual D&D character class
+     * @param {boolean} deterministic - If true, same seed always produces same name. Default: false (adds timestamp/random variation)
+     * @returns {string} Generated RPG-style character name
+     *
+     * @example
+     * // Non-deterministic (default) - slightly different each time
+     * const name1 = namingEngine.generateName(seed, track, audioProfile, 'Wizard');
+     * const name2 = namingEngine.generateName(seed, track, audioProfile, 'Wizard');
+     * // name1 might be "Midnight Dreams the Wizard"
+     * // name2 might be "Hypnotic Midnight Dreams" (different format!)
+     *
+     * @example
+     * // Deterministic mode - same seed always produces same name
+     * const name = namingEngine.generateName(seed, track, audioProfile, 'Wizard', true);
+     * // Always same result for this seed
+     */
+    generateName(seed: string, track: PlaylistTrack, audioProfile: AudioProfile, characterClass: Class, deterministic?: boolean): string;
+    /**
+     * Clean track title by removing metadata and noise
+     *
+     * Removes common metadata suffixes and prefixes:
+     * - Removes "(Official Video)", "[Remix]", "[feat. Artist]", etc.
+     * - Removes leading track numbers like "01 - " or "1. "
+     * - Removes audio file extensions (.mp3, .wav, .flac, etc.)
+     *
+     * @param {string} title - Raw track title
+     * @returns {string} Cleaned title suitable for character naming
+     *
+     * @example
+     * namingEngine.cleanTitle("01 - Midnight Dreams (Official Video)");
+     * // Returns: "Midnight Dreams"
+     */
+    cleanTitle(title: string): string;
+    /**
+     * Select naming format using weighted random selection
+     * Distribution: 20-20-10-20-15-10-5
+     */
+    private selectFormat;
+    /**
+     * Format 1: Class Title
+     * Pattern: "{title} the {class}"
+     * Uses actual character class instead of genre-guessing
+     *
+     * @example "Midnight Dreams the Wizard"
+     */
+    private formatClassTitle;
+    /**
+     * Format 2: Adjective Construct
+     * Pattern: "{adjective} {title}"
+     * Uses RNG-based selection with balanced audio/random weights
+     *
+     * @example "Hypnotic Midnight Dreams"
+     */
+    private formatAdjectiveConstruct;
+    /**
+     * Format 3: Clan Construct
+     * Pattern: "{title} of {artist}"
+     *
+     * @example "Midnight Dreams of Daft Punk"
+     */
+    private formatClanConstruct;
+    /**
+     * Format 4: Descriptive Epithet
+     * Pattern: "{title}, the {descriptor} {class_aspect}"
+     *
+     * @example "Midnight Dreams, the Swift Sage"
+     */
+    private formatDescriptiveEpithet;
+    /**
+     * Format 5: Compound Adjective
+     * Pattern: "{prefix}-{suffix} {title}"
+     *
+     * @example "Thunder-Blessed Midnight Dreams"
+     */
+    private formatCompoundAdjective;
+    /**
+     * Format 6: Artist-Inspired
+     * Pattern: "{artist_word}{occupation} of the {realm}"
+     *
+     * @example "Daftsmith of the Crystal Spire"
+     */
+    private formatArtistInspired;
+    /**
+     * Format 7: Mononym Subtitle
+     * Pattern: "{first_word} [{subtitle}]"
+     *
+     * @example "Midnight [Dreams Eternal]"
+     */
+    private formatMononymSubtitle;
+    /**
+     * Calculate balanced adjective weights for 50/50 audio/random influence
+     * All categories are always considered - audio just provides weight boosts
+     */
+    private calculateBalancedAdjectiveWeights;
+    /**
+     * Find matching genre key in NAMING_DATA.adjectives
+     * Returns 'default' if no match (ensures all adjectives available)
+     */
+    private findGenreKey;
+}
+//# sourceMappingURL=NamingEngine.d.ts.map

package/dist/core/generation/NamingEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NamingEngine.d.ts","sourceRoot":"","sources":["../../../src/core/generation/NamingEngine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAgBhD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,YAAY;IACrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACI,YAAY,CACf,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,aAAa,EACpB,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,KAAK,EACrB,aAAa,GAAE,OAAe,GAC/B,MAAM;IAkCT;;;;;;;;;;;;;;OAcG;IACI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAexC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAYpB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IAoBhC;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAahC;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAY/B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;;OAGG;IACH,OAAO,CAAC,iCAAiC;IA6BzC;;;OAGG;IACH,OAAO,CAAC,YAAY;CASvB"}

package/dist/core/generation/PitchBeatLinker.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Pitch Beat Linker - Links pitch detection to rhythm beat timestamps
+ *
+ * Performs full-spectrum pitch detection on the unfiltered audio signal,
+ * then matches pitch frames to beat timestamps.
+ *
+ * All bands share the same full-spectrum analysis because band-pass filtering
+ * (8th order Butterworth) removes too many harmonics for YIN/Essentia to
+ * find periodicity reliably.
+ *
+ * Part of the Pitch Detection & Button Mapping pipeline - Phase 1.3
+ *
+ * @example
+ * ```typescript
+ * const linker = new PitchBeatLinker();
+ *
+ * // Analyze pitch and link to composite beats
+ * const compositePitches = await linker.linkWithComposite(compositeStream, audioBuffer);
+ *
+ * // Access pitch at each beat
+ * for (const pitchAtBeat of compositePitches) {
+ *   if (pitchAtBeat.pitch?.isVoiced) {
+ *     console.log(`Beat ${pitchAtBeat.beatIndex}: ${pitchAtBeat.pitch.noteName}`);
+ *   }
+ * }
+ * ```
+ */
+import { type PitchResult, type PitchDetectorConfig } from '../analysis/PitchDetector.js';
+import { type PitchAlgorithm } from '../analysis/EssentiaPitchDetector.js';
+import type { CompositeStream } from '../analysis/beat/CompositeStreamGenerator.js';
+import type { DifficultyVariant } from '../analysis/beat/DifficultyVariantGenerator.js';
+/**
+ * Band name type matching FREQUENCY_BANDS
+ */
+export type PitchBandName = 'low' | 'mid' | 'high';
+/**
+ * Interval category for button mapping
+ */
+export type IntervalCategory = 'unison' | 'small' | 'medium' | 'large' | 'very_large';
+/**
+ * Direction of pitch change from previous beat
+ */
+export type PitchDirection = 'up' | 'down' | 'stable' | 'none';
+/**
+ * Pitch information linked to a single rhythm beat
+ */
+export interface PitchAtBeat {
+    /** Index into the beat stream */
+    beatIndex: number;
+    /** Timestamp in seconds */
+    timestamp: number;
+    /** Which band stream this beat originated from (rhythm origin, not pitch detection band) */
+    band: PitchBandName;
+    /** Detected pitch (null if no pitch detected) */
+    pitch: PitchResult | null;
+    /** Direction of pitch change from previous beat (populated in melody contour analysis) */
+    direction: PitchDirection;
+    /** Interval in semitones from previous beat (0 if none, populated in melody contour analysis) */
+    intervalFromPrevious: number;
+    /** Categorized interval (populated in melody contour analysis) */
+    intervalCategory?: IntervalCategory;
+}
+/**
+ * Configuration for PitchBeatLinker
+ */
+export interface PitchBeatLinkerConfig {
+    /** Pitch detector configuration (passed through to PitchDetector) */
+    pitchDetector?: Partial<PitchDetectorConfig>;
+    /** Target sample rate for analysis (default: 44100) */
+    targetSampleRate?: number;
+    /** Which pitch detection algorithm to use. 'pyin_legacy' uses the built-in detector; all others use Essentia.js. (default: 'pitch_melodia') */
+    pitchAlgorithm?: PitchAlgorithm;
+    /** URL to the CREPE TFJS model (only required when pitchAlgorithm is 'pitch_crepe') */
+    crepeModelUrl?: string;
+    /** Optional callback to resolve Arweave URLs (gateway fallback for CREPE model) */
+    resolveUrl?: (url: string) => Promise<string>;
+}
+/** Default configuration for PitchBeatLinker */
+type PitchBeatLinkerResolvedConfig = Required<Omit<PitchBeatLinkerConfig, 'pitchDetector' | 'resolveUrl'>> & {
+    pitchDetector: Partial<PitchDetectorConfig>;
+    resolveUrl?: (url: string) => Promise<string>;
+};
+/**
+ * Links pitch detection to rhythm beat timestamps
+ *
+ * Performs full-spectrum pitch detection on the unfiltered audio signal,
+ * then matches pitch frames to beat timestamps.
+ */
+export declare class PitchBeatLinker {
+    private config;
+    private fullSpectrumDetector;
+    private essentiaDetector;
+    /**
+     * Create a new PitchBeatLinker
+     *
+     * @param config - Configuration options (partial, defaults applied)
+     */
+    constructor(config?: PitchBeatLinkerConfig);
+    /**
+     * Get the current configuration
+     */
+    getConfig(): PitchBeatLinkerResolvedConfig;
+    /**
+     * Link pitch detection to composite stream beats.
+     *
+     * Runs pitch detection on the full unfiltered signal, then matches each composite
+     * beat's timestamp directly against pitch frames.
+     *
+     * When an Essentia algorithm is selected via `pitchAlgorithm`, the Essentia.js WASM
+     * module is loaded lazily on first call (async) and cached for reuse.
+     *
+     * @param compositeStream - The composite stream from GeneratedRhythm
+     * @param audioBuffer - Web Audio API AudioBuffer to analyze
+     * @returns Promise resolving to pitch at each composite beat
+     */
+    linkWithComposite(compositeStream: CompositeStream, audioBuffer: AudioBuffer): Promise<PitchAtBeat[]>;
+    /**
+     * Derive pitches for a difficulty variant from composite pitches
+     *
+     * Since difficulty variants are derived from the composite stream,
+     * we can look up pitches by matching timestamps. Simplified variants
+     * (e.g., easy) may have fewer beats, so we filter pitches accordingly.
+     *
+     * @param variant - The difficulty variant from GeneratedRhythm.difficultyVariants
+     * @param compositePitches - Pitches from linkWithComposite()
+     * @returns Array of pitch-at-beat for variant beats
+     */
+    deriveVariantPitches(variant: DifficultyVariant, compositePitches: PitchAtBeat[]): PitchAtBeat[];
+    /**
+     * Derive pitches for all difficulty variants at once
+     *
+     * Convenience method that derives pitches for easy, medium, and hard
+     * variants in a single call.
+     *
+     * @param difficultyVariants - The difficulty variants from GeneratedRhythm
+     * @param compositePitches - Pitches from linkWithComposite()
+     * @returns Object with pitches for each difficulty level
+     */
+    deriveAllVariantPitches(difficultyVariants: {
+        easy: DifficultyVariant;
+        medium: DifficultyVariant;
+        hard: DifficultyVariant;
+    }, compositePitches: PitchAtBeat[]): {
+        easy: PitchAtBeat[];
+        medium: PitchAtBeat[];
+        hard: PitchAtBeat[];
+    };
+}
+export {};
+//# sourceMappingURL=PitchBeatLinker.d.ts.map