playlist-data-engine 1.1.0

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

@@ -0,0 +1,399 @@
+/**
+ * Rhythm Quantizer for Procedural Rhythm Generation
+ *
+ * Translates raw transients into quantized rhythmic subdivisions that align with the beat map grid.
+ *
+ * Part of the Procedural Rhythm Generation pipeline.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - quantize transients to beat grid
+ * const quantizer = new RhythmQuantizer();
+ * const result = quantizer.quantize(transientAnalysis, unifiedBeatMap);
+ *
+ * // Access quantized streams for each band
+ * const lowBandBeats = result.streams.low.beats;
+ * const midBandBeats = result.streams.mid.beats;
+ * const highBandBeats = result.streams.high.beats;
+ *
+ * // Check grid decisions (16th vs triplet) for each beat
+ * for (const decision of result.streams.low.gridDecisions) {
+ *   console.log(`Beat ${decision.beatIndex}: ${decision.selectedGrid} (confidence: ${decision.confidence.toFixed(2)})`);
+ * }
+ *
+ * // Custom configuration with intensity filtering
+ * const customQuantizer = new RhythmQuantizer({
+ *   minimumTransientIntensity: 0.3, // Filter weak transients
+ *   densityValidation: {
+ *     maxRetries: 5,  // Per-band retry limit (opt-in, default: 0)
+ *     baseSensitivityReduction: 0.1,  // Linear increment per retry
+ *     maxCumulativeReduction: 0.5,  // Max threshold increase (default: 0.5)
+ *   },
+ * });
+ * ```
+ */
+import type { TransientResult, TransientAnalysis } from './TransientDetector.js';
+import type { UnifiedBeatMap } from '../../types/BeatMap.js';
+import type { FrequencyBand } from './utils/audioUtils.js';
+/**
+ * Configuration for density validation
+ */
+export interface DensityValidationConfig {
+    /** Maximum number of retries for sensitivity adjustment (default: 0, opt-in) */
+    maxRetries: number;
+    /** Base sensitivity reduction amount per retry (default: 0.1) */
+    baseSensitivityReduction: number;
+    /** Maximum cumulative sensitivity reduction (default: 0.5) */
+    maxCumulativeReduction: number;
+}
+/**
+ * Band type for per-band processing
+ */
+type BandType = 'low' | 'mid' | 'high';
+/**
+ * Configuration for the RhythmQuantizer
+ */
+export interface QuantizationConfig {
+    /** Density validation configuration */
+    densityValidation?: DensityValidationConfig;
+    /** Minimum transient intensity to include (0.0 = catch all, default: 0.0) */
+    minimumTransientIntensity: number;
+    /** Custom frequency bands (default: FREQUENCY_BANDS from audioUtils) */
+    bands?: FrequencyBand[];
+}
+/**
+ * Complete Phase 1 output - all 3 band streams plus metadata
+ */
+export interface QuantizedBandStreams {
+    streams: {
+        low: GeneratedRhythmMap;
+        mid: GeneratedRhythmMap;
+        high: GeneratedRhythmMap;
+    };
+    metadata: {
+        /** Per-band density validation results */
+        densityValidation: DensityValidationResult;
+        /** Total transients filtered by intensity across all bands */
+        transientsFilteredByIntensity: number;
+        /** Per-band filtered counts */
+        transientsFilteredByBand: {
+            low: number;
+            mid: number;
+            high: number;
+        };
+    };
+}
+/**
+ * Result of density validation for a single band
+ */
+export interface BandDensityValidationResult {
+    /** Band that was validated */
+    band: BandType;
+    /** Whether the density is valid */
+    isValid: boolean;
+    /** Smallest gap between transients (seconds) */
+    minIntervalDetected: number;
+    /** Required minimum interval (16th note duration at current tempo) */
+    requiredMinInterval: number;
+    /** Number of retries attempted */
+    retryCount: number;
+    /** Cumulative sensitivity reduction applied */
+    sensitivityReduction: number;
+    /** Final intensity threshold used */
+    finalIntensityThreshold: number;
+    /** Number of transients after filtering */
+    transientsRemaining: number;
+}
+/**
+ * Combined density validation result for all bands
+ */
+export interface DensityValidationResult {
+    /** Whether all bands have valid density */
+    isValid: boolean;
+    /** Per-band density validation results */
+    bands: {
+        low: BandDensityValidationResult;
+        mid: BandDensityValidationResult;
+        high: BandDensityValidationResult;
+    };
+    /** Maximum retry count across all bands */
+    maxRetryCount: number;
+    /** Maximum sensitivity reduction across all bands */
+    maxSensitivityReduction: number;
+}
+/**
+ * Grid type for a beat
+ */
+export type GridType = 'straight_16th' | 'triplet_8th' | 'straight_8th';
+/**
+ * Grid decision metadata (produced during grid detection)
+ */
+export interface GridDecision {
+    /** Index into UnifiedBeatMap.beats[] */
+    beatIndex: number;
+    /** Selected grid type for this beat */
+    selectedGrid: GridType;
+    /** Average ms offset from straight 16th grid (undefined when grid is forced) */
+    straightAvgOffset?: number;
+    /** Average ms offset from triplet grid (undefined when grid is forced) */
+    tripletAvgOffset?: number;
+    /** Number of transients in this beat */
+    transientCount: number;
+    /** How much better the chosen grid fits */
+    confidence: number;
+}
+/**
+ * A single quantized note
+ */
+export interface GeneratedBeat {
+    /** Quantized time in seconds */
+    timestamp: number;
+    /** Index into UnifiedBeatMap.beats[] - which quarter note this belongs to */
+    beatIndex: number;
+    /** Position within that beat (0-3 for 16th, 0-2 for triplet, 0-1 for 8th) */
+    gridPosition: number;
+    /** Grid type for this beat */
+    gridType: GridType;
+    /** Transient strength (0.0 - 1.0) */
+    intensity: number;
+    /** Frequency band */
+    band: 'low' | 'mid' | 'high';
+    /** Original transient detection timestamp in seconds (before quantization) */
+    detectedTimestamp?: number;
+    /** How far it was moved from original (ms), for debugging */
+    quantizationError?: number;
+}
+/**
+ * Per-band rhythm map - a complete rhythm chart for one frequency band
+ */
+export interface GeneratedRhythmMap {
+    /** Unique identifier for the audio source */
+    audioId: string;
+    /** Duration in seconds */
+    duration: number;
+    /** All quantized beats for this band */
+    beats: GeneratedBeat[];
+    /** Per-beat grid choices (16th vs triplet) */
+    gridDecisions: GridDecision[];
+    /** Duration of a quarter note in seconds (from UnifiedBeatMap - the ground truth) */
+    quarterNoteInterval: number;
+}
+/**
+ * Callback for custom grid decision logic.
+ *
+ * When provided to `quantize()`, replaces the internal `decideGrids()` call
+ * for each band. Used by `TempoAwareQuantizer` to inject BPM-aware grid
+ * decisions into the decide-then-quantize flow without duplicating the
+ * density validation and deduplication logic.
+ *
+ * The returned grid decisions are passed directly to `quantizeToGrids()`.
+ */
+export type GridDecider = (transients: TransientResult[], unifiedBeatMap: UnifiedBeatMap, band: BandType) => GridDecision[];
+/**
+ * Multi-Band Rhythm Quantizer
+ *
+ * Translates raw transients into quantized rhythmic subdivisions that align with the beat map grid.
+ *
+ * ## Overview
+ *
+ * The quantization process consists of three main phases:
+ *
+ * 1. **Density Validation**: Checks if transients are too dense (closer than 16th note interval)
+ *    - If too dense, triggers sensitivity adjustment with retry logic
+ *    - Uses exponential backoff for sensitivity reduction
+ *
+ * 2. **Intensity Filtering**: Removes transients below the minimum intensity threshold
+ *
+ * 3. **Decide-then-Quantize**: Two-phase per-band processing:
+ *    a. **Grid Decision** (`decideGrids()`): For each beat, determines whether transients
+ *       fit better on a straight 16th note grid or an 8th note triplet grid. Does NOT
+ *       perform quantization — the returned decisions can be modified by downstream
+ *       rules (e.g., BPM-aware quantization) before snapping.
+ *    b. **Quantization** (`quantizeToGrids()`): Snaps each transient's original timestamp
+ *       to the nearest point on the chosen grid. Uses the original (not pre-quantized)
+ *       timestamps to minimize quantization error.
+ *
+ * The `quantizeBand()` method orchestrates: decide → quantize → deduplicate.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const quantizer = new RhythmQuantizer({
+ *   minimumTransientIntensity: 0.3
+ * });
+ * const result = quantizer.quantize(transientAnalysis, unifiedBeatMap);
+ *
+ * // Access per-band streams
+ * const lowStream = result.streams.low;
+ * const midStream = result.streams.mid;
+ * const highStream = result.streams.high;
+ * ```
+ */
+export declare class RhythmQuantizer {
+    private config;
+    /**
+     * Create a new RhythmQuantizer
+     *
+     * @param config - Configuration options (all optional, defaults provided)
+     */
+    constructor(config?: Partial<QuantizationConfig>);
+    /**
+     * Get the current configuration
+     *
+     * @returns The current configuration
+     */
+    getConfig(): Required<QuantizationConfig>;
+    /**
+     * Quantize transients into rhythm streams
+     *
+     * Implements per-band density validation with linear retry increments:
+     * - Each band (low/mid/high) is validated independently
+     * - Retry increments are linear: 0.1, 0.2, 0.3, 0.4, 0.5
+     * - If one band is too dense, only that band's threshold is increased
+     *
+     * @param transientAnalysis - Transient analysis from TransientDetector
+     * @param unifiedBeatMap - Unified beat map to quantize against
+     * @param gridDecider - Optional custom grid decider (e.g., TempoAwareQuantizer).
+     *   When provided, replaces the internal `decideGrids()` call for each band.
+     * @returns Quantized band streams
+     */
+    quantize(transientAnalysis: TransientAnalysis, unifiedBeatMap: UnifiedBeatMap, gridDecider?: GridDecider): QuantizedBandStreams;
+    /**
+     * Split transients by frequency band
+     */
+    private splitTransientsByBand;
+    /**
+     * Process a single band with per-band density validation and retry logic
+     *
+     * Uses linear increments instead of exponential:
+     * - Retry 1: +0.1
+     * - Retry 2: +0.2
+     * - Retry 3: +0.3
+     * - Retry 4: +0.4
+     * - Retry 5: +0.5
+     */
+    private processBand;
+    /**
+     * Validate density for a single band
+     */
+    private validateBandDensity;
+    /**
+     * Aggregate density results from all bands into a single result
+     */
+    private aggregateDensityResults;
+    /**
+     * Decide grid types for each beat that has transients.
+     *
+     * Grid decision phase only — determines which grid type (straight_16th,
+     * triplet_8th, or forced straight_8th) best fits the transients in each beat.
+     * Does NOT perform any quantization. The returned decisions can be modified
+     * by downstream rules (e.g., BPM-aware quantization) before quantization.
+     *
+     * @param transients - Raw transients for this band
+     * @param unifiedBeatMap - Unified beat map
+     * @param band - Band being processed
+     * @returns Array of grid decisions for beats with transients
+     */
+    decideGrids(transients: TransientResult[], unifiedBeatMap: UnifiedBeatMap, band: BandType): GridDecision[];
+    /**
+     * Quantize transients to their chosen grid positions.
+     *
+     * Quantization phase — snaps each transient's original timestamp to the
+     * nearest grid point based on the provided grid decisions. Uses the
+     * ORIGINAL transient timestamps (not pre-quantized data) to minimize
+     * quantization error.
+     *
+     * @param transients - Raw transients for this band (original timestamps)
+     * @param unifiedBeatMap - Unified beat map
+     * @param band - Band being processed
+     * @param gridDecisions - Grid decisions for each beat (may be modified by BPM rules)
+     * @returns Array of raw quantized beats (before deduplication)
+     */
+    quantizeToGrids(transients: TransientResult[], unifiedBeatMap: UnifiedBeatMap, band: BandType, gridDecisions: GridDecision[]): GeneratedBeat[];
+    /**
+     * Quantize a single band (orchestrator: decide → quantize → deduplicate)
+     */
+    private quantizeBand;
+    /**
+     * Deduplicate beats that snap to the same grid point
+     *
+     * When multiple transients quantize to the same (beatIndex, gridPosition, gridType),
+     * keep only the one with the highest intensity.
+     *
+     * @param beats - Array of quantized beats (may have duplicates)
+     * @returns Deduplicated array with only the strongest beat at each grid point
+     */
+    private deduplicateBeats;
+    /**
+     * Detect grid type for a beat
+     *
+     * ## Algorithm: Per-Beat Grid Detection (16th vs Triplet)
+     *
+     * This method determines whether transients within a beat fit better on:
+     * - **Straight 16th note grid**: 4 equally-spaced positions (0, 1, 2, 3)
+     * - **8th note triplet grid**: 3 equally-spaced positions (0, 1, 2)
+     *
+     * ### Decision Logic:
+     *
+     * 1. Calculate both grid positions for the beat
+     * 2. For each transient, measure distance to nearest point on each grid
+     * 3. Calculate average offset per transient for each grid
+     * 4. Select grid with **smaller average offset** (transients are closer to grid points)
+     * 5. Confidence = |straightAvgOffset - tripletAvgOffset| (how much better the winner fits)
+     *
+     * ### Example:
+     * - If transients are at 0ms, 250ms, 500ms in a 500ms beat:
+     *   - Straight 16th grid (0, 125, 250, 375, 500ms) → offsets: 0, 0, 0 → avg 0ms
+     *   - Triplet grid (0, 167, 333, 500ms) → offsets: 0, 83, 167 → avg 83ms
+     *   - Winner: Straight 16th (smaller offset)
+     *
+     * ### Why Per-Beat Detection?
+     *
+     * Music often mixes straight and triplet feels within the same song.
+     * By detecting the grid per-beat, we can handle:
+     * - Songs with tempo changes
+     * - Songs with mixed time signatures
+     * - Songs with swing feel in some sections but not others
+     */
+    /**
+     * Get the forced grid type for a band, if any.
+     *
+     * Returns null for bands that should auto-detect their grid.
+     */
+    private getBandGridType;
+    private detectGrid;
+    /**
+     * Calculate straight 16th note grid for a beat
+     *
+     * @param beatStart - Start time of the beat in seconds
+     * @param quarterNoteInterval - Duration of a quarter note in seconds
+     * @returns Array of grid positions in seconds
+     */
+    private calculateStraightGrid;
+    /**
+     * Calculate 8th note triplet grid for a beat
+     *
+     * @param beatStart - Start time of the beat in seconds
+     * @param quarterNoteInterval - Duration of a quarter note in seconds
+     * @returns Array of grid positions in seconds
+     */
+    private calculateTripletGrid;
+    /**
+     * Calculate straight 8th note grid for a beat
+     *
+     * @param beatStart - Start time of the beat in seconds
+     * @param quarterNoteInterval - Duration of a quarter note in seconds
+     * @returns Array of grid positions in seconds
+     */
+    private calculate8thGrid;
+    /**
+     * Calculate offset from grid (in milliseconds)
+     */
+    private calculateOffsetFromGrid;
+    /**
+     * Quantize a transient to chosen grid
+     */
+    private quantizeTransient;
+}
+export {};
+//# sourceMappingURL=RhythmQuantizer.d.ts.map

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

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

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

@@ -0,0 +1,262 @@
+/**
+ * RhythmicBalancer - Enforces metric structure and downbeat anchoring
+ *
+ * A post-processing step that transforms the composite stream to ensure
+ * rhythmic playability. Operates between CompositeStreamGenerator and
+ * DifficultyVariantGenerator in the pipeline.
+ *
+ * Key operations:
+ * - Shifts lone subdivision notes to downbeats
+ * - Fills empty measures with a beat on beat 1
+ * - Enforces downbeat proximity for upbeat notes
+ * - Removes notes within the start/end audio margin
+ *
+ * Part of the Procedural Rhythm Generation pipeline - Rhythmic Balance
+ */
+import type { CompositeStream } from './CompositeStreamGenerator.js';
+import type { UnifiedBeatMap, DownbeatSegment } from '../../types/BeatMap.js';
+import type { ControllerMode } from '../../types/ButtonMapping.js';
+/**
+ * Describes what action the RhythmicBalancer took on a beat (if any).
+ *
+ * Used to tag beats in the balanced composite so the UI can visually
+ * distinguish balancer-modified beats from naturally detected ones.
+ */
+export type BalancerAction = 'none' | 'shifted_to_downbeat' | 'empty_measure_fill' | 'proximity_shift' | 'margin_removal';
+/**
+ * Summary statistics from the rhythmic balancing step.
+ */
+export interface BalanceStats {
+    /** Number of lone offbeat notes shifted to downbeats */
+    shiftedToDownbeat: number;
+    /** Number of empty measures filled with a downbeat */
+    emptyMeasuresFilled: number;
+    /** Number of upbeat notes shifted due to missing nearby downbeat */
+    proximityShifts: number;
+    /** Total beats added by the balancer (filled measures only) */
+    beatsAdded: number;
+    /** Total beats modified by the balancer (shifts) */
+    beatsShifted: number;
+    /** Total beats removed for being within the start/end audio margin */
+    marginRemovals: number;
+}
+/**
+ * Result of the balance() operation, including the balanced stream and stats.
+ */
+export interface BalanceResult {
+    /** The balanced composite stream with tagged beats */
+    composite: CompositeStream;
+    /** Statistics about what the balancer did */
+    stats: BalanceStats;
+}
+/**
+ * Strong beat emphasis mode for density reduction priority
+ *
+ * Determines which beats within a measure are considered "strong" for the
+ * purpose of density reduction (which beats to keep vs remove).
+ */
+export type StrongBeatEmphasis = 'natural' | 'backbeat' | 'neutral';
+/**
+ * Configuration for rhythmic balancing
+ *
+ * Controls how the RhythmicBalancer enforces metric structure on the
+ * composite stream before difficulty variants are generated.
+ */
+export interface RhythmicBalanceConfig {
+    /**
+     * Which beats are "strong" for density reduction priority.
+     * Derives grouping from time signature automatically.
+     *
+     * - 'natural': Emphasize natural metric accents (e.g., 4/4 → beats 1, 3; 9/8 → beats 1, 4, 7)
+     * - 'backbeat': Emphasize weak positions (e.g., 4/4 → beats 2, 4; 9/8 → beats 2, 3, 5, 6, 8, 9)
+     * - 'neutral': No positional preference
+     *
+     * @default 'natural'
+     */
+    strongBeatEmphasis: StrongBeatEmphasis;
+    /**
+     * Max distance in quarter-note beats from an upbeat note to the nearest downbeat note.
+     * 0 = same beat only, 1 = one beat, 1.5 = one beat (half-beat increments supported),
+     * 4 = same measure.
+     *
+     * Supports whole beats and 0.5 increments. Intermediate fractional values are
+     * rounded down to the nearest supported step (e.g., 1.7 behaves like 1.5).
+     *
+     * If an upbeat note has no downbeat within this range, it gets shifted to the
+     * downbeat of its beat index.
+     *
+     * @default 2
+     */
+    downbeatProximityRange: number;
+    /**
+     * Whether to fill empty measures with a beat on beat 1 downbeat.
+     *
+     * Ensures every measure has at least one beat for rhythmic foundation.
+     *
+     * @default true
+     */
+    fillEmptyMeasures: boolean;
+    /**
+     * Intensity for beats added by the balancer.
+     *
+     * Lower than detected beats (typically 0.6-0.8) so they're removable
+     * during density reduction if needed.
+     *
+     * @default 0.45
+     */
+    addedBeatIntensity: number;
+    /**
+     * Minimum distance in seconds from the start and end of the audio file
+     * where notes are allowed. Beats within this margin are removed to prevent
+     * unfair/unplayable notes at the very beginning or end of a song.
+     *
+     * 0 = disabled (no margin enforced).
+     *
+     * @default 0.5
+     */
+    marginSeconds: number;
+}
+/**
+ * Default configuration for rhythmic balancing
+ */
+export declare const DEFAULT_RHYTHMIC_BALANCE_CONFIG: RhythmicBalanceConfig;
+/**
+ * Get the default rhythmic balance config for a controller mode.
+ *
+ * @param controllerMode - The controller mode to get defaults for
+ * @returns RhythmicBalanceConfig with mode-specific values
+ */
+export declare function getControllerModeBalanceDefaults(controllerMode: ControllerMode): RhythmicBalanceConfig;
+/**
+ * Get the metric group size based on time signature
+ *
+ * Simple meter (beatsPerMeasure not divisible by 3): groups of 2
+ * Compound meter (beatsPerMeasure divisible by 3): groups of 3
+ *
+ * @param beatsPerMeasure - Number of beats per measure
+ * @returns Group size (2 for simple, 3 for compound)
+ */
+export declare function getMetricGroupSize(beatsPerMeasure: number): number;
+/**
+ * Check if a beat position is a metric strong beat within its group
+ *
+ * In simple meter (groups of 2): positions 0, 2, 4, ... are strong
+ * In compound meter (groups of 3): positions 0, 3, 6, ... are strong
+ *
+ * @param beatInMeasure - Position within the measure (0-indexed)
+ * @param groupSize - Metric group size (2 or 3)
+ * @returns True if this is a strong beat position
+ */
+export declare function isMetricStrongBeat(beatInMeasure: number, groupSize: number): boolean;
+/**
+ * Check if a beat position is a metric weak beat within its group
+ *
+ * In simple meter (groups of 2): positions 1, 3, 5, ... are weak
+ * In compound meter (groups of 3): positions 1, 2, 4, 5, 7, 8, ... are weak
+ *
+ * @param beatInMeasure - Position within the measure (0-indexed)
+ * @param groupSize - Metric group size (2 or 3)
+ * @returns True if this is a weak beat position
+ */
+export declare function isMetricWeakBeat(beatInMeasure: number, groupSize: number): boolean;
+/**
+ * Find the active downbeat segment for a given beat index
+ *
+ * @param segments - Array of downbeat segments (must be ordered by startBeat)
+ * @param beatIndex - The beat index to find the segment for
+ * @returns The active segment for the given beat index
+ */
+export declare function findActiveSegment(segments: DownbeatSegment[], beatIndex: number): DownbeatSegment;
+/**
+ * Check if a beat should be considered "strong" based on the emphasis mode
+ *
+ * @param beatInMeasure - Position within the measure (0-indexed)
+ * @param beatsPerMeasure - Number of beats per measure in this segment
+ * @param emphasis - Strong beat emphasis mode
+ * @returns True if this beat should be treated as strong
+ */
+export declare function isStrongBeatForEmphasis(beatInMeasure: number, beatsPerMeasure: number, emphasis: StrongBeatEmphasis): boolean;
+/**
+ * Balances a composite stream to enforce metric structure and downbeat anchoring
+ *
+ * Takes a CompositeStream and returns a new CompositeStream with improved
+ * rhythmic foundation for players who can't read rhythm well.
+ *
+ * @example
+ * ```typescript
+ * const balancer = new RhythmicBalancer();
+ * const balanced = balancer.balance(composite, unifiedBeatMap);
+ *
+ * // Every measure now has at least 1 beat
+ * // Lone subdivision notes are shifted to downbeats
+ * // Upbeat notes have a downbeat nearby
+ * ```
+ */
+export declare class RhythmicBalancer {
+    private config;
+    constructor(config?: Partial<RhythmicBalanceConfig>);
+    /**
+     * Get the current configuration
+     */
+    getConfig(): RhythmicBalanceConfig;
+    /**
+     * Balance a composite stream to enforce metric structure
+     *
+     * Processing order:
+     * 1. shiftLoneSubdivisionNotes() - Move lone offbeat notes to downbeats
+     * 2. fillEmptyMeasures() - Ensure every measure has a beat
+     * 3. enforceDownbeatProximity() - Ensure upbeats have nearby downbeats
+     * 4. removeMarginNotes() - Remove beats within start/end audio margin
+     *
+     * Each modified beat is tagged with a `balancerAction` field so the UI
+     * can visually distinguish balancer-modified beats from detected ones.
+     *
+     * @param composite - The composite stream to balance
+     * @param unifiedBeatMap - The unified beat map with measure/position info
+     * @returns A BalanceResult with the balanced composite and statistics
+     */
+    balance(composite: CompositeStream, unifiedBeatMap: UnifiedBeatMap): BalanceResult;
+    /**
+     * Shift lone subdivision notes to downbeats
+     *
+     * For measures with exactly 1 beat where that beat is not on a downbeat,
+     * move it to the downbeat position.
+     *
+     * @param beats - Current beats array
+     * @param unifiedBeatMap - Unified beat map with measure info
+     * @returns Updated beats array
+     */
+    private shiftLoneSubdivisionNotes;
+    /**
+     * Fill empty measures with a beat on beat 1 downbeat
+     *
+     * @param beats - Current beats array
+     * @param unifiedBeatMap - Unified beat map with measure info
+     * @returns Updated beats array with added beats
+     */
+    private fillEmptyMeasures;
+    /**
+     * Enforce downbeat proximity for upbeat notes
+     *
+     * If an upbeat note has no downbeat within the configured range,
+     * shift it to the downbeat of its beat index.
+     *
+     * @param beats - Current beats array
+     * @param unifiedBeatMap - Unified beat map with measure info
+     * @returns Updated beats array
+     */
+    private enforceDownbeatProximity;
+    /**
+     * Remove beats within the start/end audio margin
+     *
+     * Filters out beats whose timestamps fall within `marginSeconds` of
+     * the beginning or end of the audio file. This prevents unfair/unplayable
+     * notes at the very edges of a song where the player has no time to react.
+     *
+     * @param beats - Current beats array
+     * @param audioDuration - Total duration of the audio file in seconds
+     * @returns Updated beats array with margin beats removed
+     */
+    private removeMarginNotes;
+}
+//# sourceMappingURL=RhythmicBalancer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RhythmicBalancer.d.ts","sourceRoot":"","sources":["../../../../src/core/analysis/beat/RhythmicBalancer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAMnE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACpB,MAAM,GACN,qBAAqB,GACrB,oBAAoB,GACpB,iBAAiB,GACjB,gBAAgB,CAAC;AAEvB;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,sDAAsD;IACtD,SAAS,EAAE,eAAe,CAAC;IAC3B,6CAA6C;IAC7C,KAAK,EAAE,YAAY,CAAC;CACvB;AAMD;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IAClC;;;;;;;;;OASG;IACH,kBAAkB,EAAE,kBAAkB,CAAC;IAEvC;;;;;;;;;;;;OAYG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAE/B;;;;;;OAMG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAE3B;;;;;;;OAOG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAE3B;;;;;;;;OAQG;IACH,aAAa,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,eAAO,MAAM,+BAA+B,EAAE,qBAM7C,CAAC;AAqCF;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,cAAc,EAAE,cAAc,GAAG,qBAAqB,CAEtG;AAMD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAElF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC7B,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,MAAM,GAClB,eAAe,CAUjB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACnC,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,kBAAkB,GAC7B,OAAO,CAaT;AAMD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,MAAM,CAAwB;gBAE1B,MAAM,GAAE,OAAO,CAAC,qBAAqB,CAAM;IAIvD;;OAEG;IACH,SAAS,IAAI,qBAAqB;IAIlC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CACH,SAAS,EAAE,eAAe,EAC1B,cAAc,EAAE,cAAc,GAC/B,aAAa;IAyChB;;;;;;;;;OASG;IACH,OAAO,CAAC,yBAAyB;IAsDjC;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAkGzB;;;;;;;;;OASG;IACH,OAAO,CAAC,wBAAwB;IAuEhC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,iBAAiB;CAqB5B"}