chart-preview 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,496 @@
+import { parseChartFile, Instrument, Difficulty, InstrumentType, NoteType } from 'scan-chart';
+export { Difficulty, Instrument, InstrumentType, getInstrumentType, instrumentTypes } from 'scan-chart';
+import * as THREE from 'three';
+
+type ParsedChart = ReturnType<typeof parseChartFile>;
+/**
+ * Custom note types for 6-fret barre notes.
+ * These are the only sprites without a dedicated NoteType from scan-chart.
+ */
+declare const BARRE1_TYPE: 99991;
+declare const BARRE2_TYPE: 99992;
+declare const BARRE3_TYPE: 99993;
+type BarreType = typeof BARRE1_TYPE | typeof BARRE2_TYPE | typeof BARRE3_TYPE;
+/** Extended note type that includes custom barre types */
+type ExtendedNoteType = NoteType | BarreType;
+interface ChartPreviewEvents {
+    progress: (percentComplete: number) => void;
+    end: () => void;
+}
+interface ChartPreviewConfig {
+    /** The parsed chart data from scan-chart's parseChartFile function */
+    parsedChart: ParsedChart;
+    /** Pre-loaded textures from ChartPreview.loadTextures() */
+    textures: Awaited<ReturnType<typeof loadTextures>>;
+    /** Array of audio file data (Uint8Array) to be played in sync with the preview */
+    audioFiles: Uint8Array[];
+    /** The instrument to display */
+    instrument: Instrument;
+    /** The difficulty level to display */
+    difficulty: Difficulty;
+    /** The amount of time to delay the start of the audio in milliseconds (can be negative) */
+    startDelayMs: number;
+    /** The length of the longest audio file stem in milliseconds */
+    audioLengthMs: number;
+    /** The HTML div element where the preview should be rendered */
+    container: HTMLDivElement;
+    /** Minimum interval between progress events in milliseconds. Defaults to 50ms. */
+    progressIntervalMs?: number;
+}
+/**
+ * Renders a chart preview inside a container element, and plays audio files in sync with the render.
+ * Works like a video player but generates 3D visualization of the chart in real-time.
+ */
+declare class ChartPreview {
+    private eventEmitter;
+    instrumentType: InstrumentType;
+    private paused;
+    private scene;
+    private highwayTexture;
+    private camera;
+    private renderer;
+    private audioManager;
+    private notesManager;
+    private progressIntervalMs;
+    private lastProgressEmitTime;
+    /**
+     * Loads textures required for the chart preview.
+     * Call this once per instrument type and cache the result for reuse.
+     */
+    static loadTextures: typeof loadTextures;
+    private constructor();
+    /**
+     * Adds an event listener.
+     *
+     * Available events:
+     * - `progress`: called during playback with the current progress (0-1), throttled by progressIntervalMs.
+     * - `end`: called when the chart preview ends.
+     */
+    on<T extends keyof ChartPreviewEvents>(event: T, listener: ChartPreviewEvents[T]): void;
+    /**
+     * Removes an event listener.
+     */
+    off<T extends keyof ChartPreviewEvents>(event: T, listener: ChartPreviewEvents[T]): void;
+    /**
+     * Creates a new ChartPreview instance.
+     *
+     * @param config - Configuration object for the chart preview
+     *
+     * Will throw an exception if textures fail to load or if audio decoding fails.
+     *
+     * @example
+     * ```ts
+     * import { ChartPreview, ParsedChart } from 'chart-preview'
+     * import { parseChartFile, getInstrumentType } from 'scan-chart'
+     *
+     * // Parse your chart file first
+     * const parsedChart = parseChartFile(chartData, format, modifiers)
+     *
+     * // Load textures for the instrument type
+     * const textures = await ChartPreview.loadTextures(getInstrumentType('guitar'))
+     *
+     * // Create the preview
+     * const preview = await ChartPreview.create({
+     *   parsedChart,
+     *   textures,
+     *   audioFiles: [audioData],
+     *   instrument: 'guitar',
+     *   difficulty: 'expert',
+     *   startDelayMs: 0,
+     *   audioLengthMs: 180000,
+     *   container: document.getElementById('preview-container')
+     * })
+     *
+     * // Control playback
+     * await preview.togglePaused()
+     * ```
+     */
+    static create(config: ChartPreviewConfig): Promise<ChartPreview>;
+    /**
+     * Toggles between playing and paused states.
+     */
+    togglePaused(): Promise<void>;
+    /**
+     * Returns whether the preview is currently paused.
+     */
+    get isPaused(): boolean;
+    /**
+     * Moves the playback time to `percentComplete` of the way through the preview.
+     * @param percentComplete A number between 0 and 1 (inclusive)
+     */
+    seek(percentComplete: number): Promise<void>;
+    /**
+     * Gets or sets the volume (0 to 1).
+     * Returns `null` if audio isn't loaded (e.g., using SilentAudioManager).
+     */
+    set volume(volume: number | null);
+    get volume(): number | null;
+    /** Current playback position in milliseconds */
+    get chartCurrentTimeMs(): number;
+    /** Total duration in milliseconds */
+    get chartEndTimeMs(): number;
+    /**
+     * Cleans up all resources. Call this when discarding the preview.
+     * The preview should not be used after calling dispose().
+     */
+    dispose(): void;
+    private addHighwayToScene;
+    private addStrikelineToScene;
+    private animateFrame;
+}
+/**
+ * Loads all required textures for the chart preview.
+ * @param instrumentType The type of instrument to load textures for
+ * @returns An object containing highway, strikeline, and note textures
+ */
+declare function loadTextures(instrumentType: InstrumentType): Promise<{
+    highwayTexture: THREE.Texture;
+    strikelineTexture: THREE.Texture;
+    noteTextures: Map<ExtendedNoteType, Map<number, THREE.Texture>>;
+}>;
+
+/**
+ * Configuration for loading a chart from a URL.
+ */
+interface LoadFromUrlConfig {
+    /** URL to the .sng file */
+    url: string;
+    /** The instrument to display */
+    instrument: Instrument;
+    /** The difficulty level to display */
+    difficulty: Difficulty;
+    /** Initial seek position as a percentage (0-1). Defaults to 0. */
+    initialSeekPercent?: number;
+    /** AbortSignal to cancel the fetch operation */
+    signal?: AbortSignal;
+}
+/**
+ * Configuration for loading a chart from raw .sng file data.
+ */
+interface LoadFromSngFileConfig {
+    /** Raw .sng file data */
+    sngFile: Uint8Array;
+    /** The instrument to display */
+    instrument: Instrument;
+    /** The difficulty level to display */
+    difficulty: Difficulty;
+    /** Initial seek position as a percentage (0-1). Defaults to 0. */
+    initialSeekPercent?: number;
+}
+/**
+ * Configuration for loading a chart from individual chart and audio files.
+ */
+interface LoadFromChartFilesConfig {
+    /** Array of files with their names and data */
+    files: {
+        fileName: string;
+        data: Uint8Array;
+    }[];
+    /** The instrument to display */
+    instrument: Instrument;
+    /** The difficulty level to display */
+    difficulty: Difficulty;
+    /** Initial seek position as a percentage (0-1). Defaults to 0. */
+    initialSeekPercent?: number;
+}
+/**
+ * Result of preparing chart data for playback.
+ */
+interface PreparedChartData {
+    parsedChart: ParsedChart;
+    textures: Awaited<ReturnType<typeof ChartPreview.loadTextures>>;
+    audioFiles: Uint8Array[];
+    instrument: Instrument;
+    difficulty: Difficulty;
+    startDelayMs: number;
+    audioLengthMs: number;
+    initialSeekPercent: number;
+}
+/**
+ * Extracts files from a .sng archive.
+ *
+ * @param data - Raw .sng file data
+ * @returns Array of extracted files with their names and data
+ */
+declare function extractSngFile(data: Uint8Array): Promise<{
+    fileName: string;
+    data: Uint8Array;
+}[]>;
+/**
+ * Finds the chart file (.chart or .mid) from an array of files.
+ * Prefers .mid over .chart when both exist.
+ *
+ * @param files - Array of files to search
+ * @returns The chart file, or null if not found
+ */
+declare function findChartFile(files: {
+    fileName: string;
+    data: Uint8Array;
+}[]): {
+    fileName: string;
+    data: Uint8Array;
+    format: "chart" | "mid";
+} | null;
+/**
+ * Finds audio files from an array of files, excluding preview and crowd stems.
+ *
+ * @param files - Array of files to search
+ * @returns Array of audio file data
+ */
+declare function findAudioFiles(files: {
+    fileName: string;
+    data: Uint8Array;
+}[]): Uint8Array[];
+/**
+ * Checks if a filename is a video file (to be excluded from .sng extraction).
+ */
+declare function isVideoFile(fileName: string): boolean;
+/**
+ * Prepares chart data for playback by extracting, parsing, and loading all resources.
+ *
+ * @param files - Array of extracted files
+ * @param instrument - The instrument to display
+ * @param difficulty - The difficulty level to display
+ * @param initialSeekPercent - Initial seek position (0-1)
+ * @returns Prepared chart data ready for the player
+ */
+declare function prepareChartData(files: {
+    fileName: string;
+    data: Uint8Array;
+}[], instrument: Instrument, difficulty: Difficulty, initialSeekPercent?: number): Promise<PreparedChartData>;
+/**
+ * Fetches a .sng file from a URL.
+ *
+ * @param url - URL to fetch the .sng file from
+ * @param signal - Optional AbortSignal to cancel the fetch
+ * @returns Raw .sng file data
+ */
+declare function fetchSngFile(url: string, signal?: AbortSignal): Promise<Uint8Array>;
+
+type PlayerState = "idle" | "loading" | "ready" | "playing" | "paused" | "seeking" | "ended" | "error";
+interface ChartPreviewPlayerConfig {
+    parsedChart: ChartPreviewConfig["parsedChart"];
+    textures: ChartPreviewConfig["textures"];
+    audioFiles: ChartPreviewConfig["audioFiles"];
+    instrument: ChartPreviewConfig["instrument"];
+    difficulty: ChartPreviewConfig["difficulty"];
+    startDelayMs: ChartPreviewConfig["startDelayMs"];
+    audioLengthMs: ChartPreviewConfig["audioLengthMs"];
+    /** Initial seek position as a percentage (0-1). Defaults to 0. */
+    initialSeekPercent?: number;
+}
+/**
+ * A Web Component that provides a complete chart preview player with controls.
+ *
+ * @example
+ * ```html
+ * <chart-preview-player id="player"></chart-preview-player>
+ *
+ * <script type="module">
+ *   import { ChartPreviewPlayer, ChartPreview } from 'chart-preview';
+ *
+ *   const player = document.getElementById('player');
+ *   const textures = await ChartPreview.loadTextures(instrumentType);
+ *
+ *   await player.loadChart({
+ *     parsedChart,
+ *     textures,
+ *     audioFiles,
+ *     instrument: 'guitar',
+ *     difficulty: 'expert',
+ *     startDelayMs: 0,
+ *     audioLengthMs: 180000,
+ *   });
+ * </script>
+ * ```
+ *
+ * @fires player-statechange - When the player state changes
+ * @fires player-progress - During playback with current position info
+ * @fires player-end - When playback ends
+ * @fires player-error - When an error occurs
+ *
+ * @attr {string} volume - Initial volume (0-100), defaults to 50
+ */
+declare class ChartPreviewPlayer extends HTMLElement {
+    private shadow;
+    private chartPreview;
+    private _state;
+    private _volume;
+    private _lastVolumeBeforeMute;
+    private _isFullscreen;
+    private timestampInterval;
+    private _wasPlayingBeforeSeek;
+    private _isSeeking;
+    private _currentAbortController;
+    private container;
+    private viewport;
+    private playBtn;
+    private volumeBtn;
+    private volumeSlider;
+    private seekBar;
+    private timestampEl;
+    private fullscreenBtn;
+    constructor();
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private render;
+    private setupEventListeners;
+    private handleKeydown;
+    private handleFullscreenChange;
+    private onSeekStart;
+    private onSeekInput;
+    private onSeekEnd;
+    /**
+     * Prepares the viewport for loading by removing messages and setting loading state.
+     */
+    private prepareForLoading;
+    /**
+     * Handles load errors by showing error message and dispatching error event.
+     */
+    private handleLoadError;
+    private setState;
+    private updatePlayButton;
+    private updateVolumeIcon;
+    private updateTimestamp;
+    private formatTime;
+    private startTimestampUpdates;
+    private stopTimestampUpdates;
+    /**
+     * Current player state
+     */
+    get state(): PlayerState;
+    /**
+     * Whether the player is currently playing
+     */
+    get isPlaying(): boolean;
+    /**
+     * Current volume (0-100)
+     */
+    get volume(): number;
+    /**
+     * Set volume (0-100)
+     */
+    setVolume(volume: number): void;
+    /**
+     * Current playback position in milliseconds
+     */
+    get currentTimeMs(): number;
+    /**
+     * Total duration in milliseconds
+     */
+    get durationMs(): number;
+    /**
+     * Whether the player is in fullscreen mode
+     */
+    get isFullscreen(): boolean;
+    /**
+     * Load a chart into the player from pre-processed data.
+     * Use this when you've already parsed the chart and loaded textures.
+     *
+     * @example
+     * ```ts
+     * const textures = await ChartPreview.loadTextures(instrumentType);
+     * await player.loadChart({
+     *   parsedChart,
+     *   textures,
+     *   audioFiles,
+     *   instrument: 'guitar',
+     *   difficulty: 'expert',
+     *   startDelayMs: 0,
+     *   audioLengthMs: 180000,
+     * });
+     * ```
+     */
+    loadChart(config: ChartPreviewPlayerConfig): Promise<void>;
+    /**
+     * Load a chart from a URL pointing to a .sng file.
+     * This is the simplest way to load a chart - just provide a URL and instrument/difficulty.
+     *
+     * @example
+     * ```ts
+     * await player.loadFromUrl({
+     *   url: 'https://files.enchor.us/abc123.sng',
+     *   instrument: 'guitar',
+     *   difficulty: 'expert',
+     * });
+     * ```
+     */
+    loadFromUrl(config: LoadFromUrlConfig): Promise<void>;
+    /**
+     * Load a chart from raw .sng file data.
+     * Use this when you've already fetched the .sng file yourself.
+     *
+     * @example
+     * ```ts
+     * const response = await fetch('https://files.enchor.us/abc123.sng');
+     * const sngData = new Uint8Array(await response.arrayBuffer());
+     *
+     * await player.loadFromSngFile({
+     *   sngFile: sngData,
+     *   instrument: 'guitar',
+     *   difficulty: 'expert',
+     * });
+     * ```
+     */
+    loadFromSngFile(config: LoadFromSngFileConfig): Promise<void>;
+    /**
+     * Load a chart from individual files (chart file + audio files).
+     * Use this when loading from a folder or when you have the files separately.
+     *
+     * @example
+     * ```ts
+     * // From file picker
+     * const files = await getFilesFromFolder();
+     *
+     * await player.loadFromChartFiles({
+     *   files: files.map(f => ({ fileName: f.name, data: new Uint8Array(f.data) })),
+     *   instrument: 'guitar',
+     *   difficulty: 'expert',
+     * });
+     * ```
+     */
+    loadFromChartFiles(config: LoadFromChartFilesConfig): Promise<void>;
+    /**
+     * Toggle between playing and paused states
+     */
+    togglePlayPause(): Promise<void>;
+    /**
+     * Play the chart
+     */
+    play(): Promise<void>;
+    /**
+     * Pause the chart
+     */
+    pause(): Promise<void>;
+    /**
+     * Seek to a specific position
+     * @param percent Position as a percentage (0-1)
+     */
+    seek(percent: number): Promise<void>;
+    /**
+     * Seek relative to current position
+     * @param deltaMs Milliseconds to seek (positive = forward, negative = backward)
+     */
+    seekRelative(deltaMs: number): Promise<void>;
+    /**
+     * Toggle mute
+     */
+    toggleMute(): void;
+    /**
+     * Toggle fullscreen mode
+     */
+    toggleFullscreen(): Promise<void>;
+    /**
+     * Dispose of the player and clean up resources
+     */
+    dispose(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "chart-preview-player": ChartPreviewPlayer;
+    }
+}
+
+export { ChartPreview, ChartPreviewConfig, ChartPreviewEvents, ChartPreviewPlayer, ChartPreviewPlayerConfig, LoadFromChartFilesConfig, LoadFromSngFileConfig, LoadFromUrlConfig, ParsedChart, PlayerState, PreparedChartData, extractSngFile, fetchSngFile, findAudioFiles, findChartFile, isVideoFile, prepareChartData };