wave-roll/dist/lib/core/playback/core-playback-engine.d.ts

JavaScript Library for Comparative MIDI Piano-Roll Visualization

/**
 * CorePlaybackEngine - Unified playback engine for audio and visualization
 *
 * Consolidates AudioController and VisualizationEngine functionality into a single
 * cohesive engine that manages one AudioPlayer instance and coordinates with
 * PianoRoll visualization.
 */
import { NoteData } from "@/lib/midi/types";
import { AudioPlayerContainer, AudioPlayerState } from "@/core/audio";
import { PianoRollManager } from "@/core/playback";
import { StateManager } from "@/core/state";
/**
 * Core playback engine configuration
 */
export interface CorePlaybackEngineConfig {
    /** Default volume (0-1) */
    defaultVolume?: number;
    /** Default tempo in BPM */
    defaultTempo?: number;
    /** Min tempo in BPM */
    minTempo?: number;
    /** Max tempo in BPM */
    maxTempo?: number;
    /** Update interval for UI sync in ms */
    updateInterval?: number;
    /** Enable state manager integration */
    enableStateSync?: boolean;
}
/**
 * Visual update callback parameters
 */
export interface VisualUpdateParams {
    currentTime: number;
    duration: number;
    isPlaying: boolean;
    volume: number;
    tempo: number;
    pan: number;
}
/**
 * CorePlaybackEngine - Single source of truth for playback control
 *
 * This engine manages:
 * - Single AudioPlayer instance
 * - Synchronization with PianoRoll visualization
 * - State management integration (optional)
 * - UI update callbacks
 */
export declare class CorePlaybackEngine implements AudioPlayerContainer {
    private audioPlayer;
    private pianoRollManager;
    private stateManager;
    private config;
    private updateLoopId;
    private visualUpdateCallbacks;
    private loopPoints;
    private seeking;
    private muteDueNoLR;
    private lastVolumeBeforeMute;
    private lastAudioSignature;
    private lastKnownState;
    private pendingOriginalTempo;
    constructor(stateManager?: StateManager, config?: CorePlaybackEngineConfig);
    /**
     * Master volume property (0-1).
     * Getter reads from current audio player state,
     * setter delegates to setVolume() for consistent propagation.
     */
    get masterVolume(): number;
    set masterVolume(volume: number);
    /**
     * Initialize the engine with PianoRoll manager
     */
    initialize(pianoRollManager: PianoRollManager): Promise<void>;
    /**
     * Update audio with new notes
     */
    updateAudio(notes: NoteData[]): Promise<void>;
    /**
     * Recreate audio player with new notes
     */
    private recreateAudioPlayer;
    /**
     * AudioPlayerContainer implementation
     */
    play(): Promise<void>;
    pause(): void;
    restart(): void;
    toggleRepeat(enabled: boolean): void;
    seek(seconds: number, updateVisual?: boolean): void;
    setVolume(volume: number): void;
    setTempo(bpm: number): void;
    /**
     * Legacy compatibility: global pan setter (no-op in v2)
     * Exposed to satisfy older call sites that expect setPan on the engine.
     */
    setPan(_pan: number): void;
    /**
     * Set baseline/original tempo used as 100% reference for percent-based rate.
     */
    setOriginalTempo(bpm: number): void;
    setLoopPoints(start: number | null, end: number | null, preservePosition?: boolean): void;
    /**
     * Set pan for a specific file track.
     */
    setFilePan(fileId: string, pan: number): void;
    /**
     * Set mute state for a specific file track.
     */
    setFileMute(fileId: string, mute: boolean): void;
    /**
     * Set playback rate as percentage (10-200, 100 = normal speed)
     */
    setPlaybackRate(rate: number): void;
    /**
     * Set volume for a specific MIDI file
     */
    setFileVolume(fileId: string, volume: number): void;
    /**
     * Set volume for a specific WAV file
     */
    setWavVolume(fileId: string, volume: number): void;
    /**
     * Refresh WAV/audio players from registry (for mute state updates)
     */
    refreshAudioPlayers(): void;
    getState(): AudioPlayerState;
    destroy(): void;
    /**
     * Additional methods for UI integration
     */
    /**
     * Register visual update callback
     */
    onVisualUpdate(callback: (params: VisualUpdateParams) => void): void;
    /**
     * Remove visual update callback
     */
    offVisualUpdate(callback: (params: VisualUpdateParams) => void): void;
    /**
     * Handle channel mute for L/R controls
     */
    handleChannelMute(shouldMute: boolean): void;
    /**
     * Get PianoRollManager instance
     */
    getPianoRollManager(): PianoRollManager | null;
    /**
     * Check if engine is initialized
     */
    isInitialized(): boolean;
    /**
     * Private helper methods
     */
    private getNotesSignature;
    /**
     * Dispatch a visual update event to all registered callbacks.
     */
    private dispatchVisualUpdate;
    /**
     * Helper: build `VisualUpdateParams` from an `AudioPlayerState` and dispatch.
     */
    private dispatchVisualUpdateFromState;
    private startUpdateLoop;
    private stopUpdateLoop;
    private syncWithStateManager;
}
export declare function createCorePlaybackEngine(stateManager?: StateManager, config?: CorePlaybackEngineConfig): CorePlaybackEngine;
//# sourceMappingURL=core-playback-engine.d.ts.map