chart-preview 1.0.3 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # chart-preview
 
+## 1.2.0
+
+### Minor Changes
+
+- 95d0918: Add support for animated note textures and improve fullscreen handling
+
+## 1.1.0
+
+### Minor Changes
+
+- 885a2db: Add note animations (Chrome only)
+
 ## 1.0.3
 
 ### Patch Changes

package/README.md

@@ -13,6 +13,7 @@ A 3D chart preview player for rhythm games like Clone Hero. Renders chart files
 - **Web Component** that can be dropped into any project
 - **Multiple instance support** - run several players simultaneously
 - **Simple URL-based loading** - just provide a URL to a .sng file
+- **Animated note textures** - supports animated WebP textures
 
 ## Installation
 
@@ -102,6 +103,7 @@ import {
   ChartPreview,
   ChartPreviewPlayer,
   getInstrumentType,
+  areAnimationsSupported,
 } from "chart-preview";
 import { parseChartFile } from "scan-chart";
 
@@ -109,7 +111,9 @@ import { parseChartFile } from "scan-chart";
 const parsedChart = parseChartFile(chartData, "chart", modifiers);
 
 // 2. Load textures (cache and reuse for same instrument type)
-const textures = await ChartPreview.loadTextures(getInstrumentType("guitar"));
+const textures = await ChartPreview.loadTextures(getInstrumentType("guitar"), {
+  animationsEnabled: areAnimationsSupported(),
+});
 
 // 3. Load the chart
 await player.loadChart({
@@ -365,6 +369,10 @@ interface LoadFromUrlConfig {
   difficulty: Difficulty;
   /** Initial seek position (0-1). Defaults to 0 */
   initialSeekPercent?: number;
+  /** AbortSignal to cancel the fetch operation */
+  signal?: AbortSignal;
+  /** Whether to enable animated textures. Defaults to true */
+  animationsEnabled?: boolean;
 }
 ```
 
@@ -380,6 +388,8 @@ interface LoadFromSngFileConfig {
   difficulty: Difficulty;
   /** Initial seek position (0-1). Defaults to 0 */
   initialSeekPercent?: number;
+  /** Whether to enable animated textures. Defaults to true */
+  animationsEnabled?: boolean;
 }
 ```
 
@@ -395,6 +405,8 @@ interface LoadFromChartFilesConfig {
   difficulty: Difficulty;
   /** Initial seek position (0-1). Defaults to 0 */
   initialSeekPercent?: number;
+  /** Whether to enable animated textures. Defaults to true */
+  animationsEnabled?: boolean;
 }
 ```
 
@@ -444,10 +456,17 @@ interface ChartPreviewPlayerConfig {
 For advanced use cases, you can use the `ChartPreview` class directly:
 
 ```typescript
-import { ChartPreview, getInstrumentType } from "chart-preview";
+import {
+  ChartPreview,
+  getInstrumentType,
+  areAnimationsSupported,
+} from "chart-preview";
 
 // Load textures (cache for reuse)
-const textures = await ChartPreview.loadTextures(getInstrumentType("guitar"));
+// Optionally disable animations for better performance
+const textures = await ChartPreview.loadTextures(getInstrumentType("guitar"), {
+  animationsEnabled: areAnimationsSupported(), // or set to false to always use static textures
+});
 
 // Create preview
 const preview = await ChartPreview.create({
@@ -485,8 +504,15 @@ import {
   prepareChartData,
   findChartFile,
   findAudioFiles,
+  isVideoFile,
+  areAnimationsSupported,
 } from "chart-preview";
 
+// Check if animated textures are supported (ImageDecoder API)
+if (areAnimationsSupported()) {
+  console.log("Animated note textures will be used");
+}
+
 // Fetch and extract a .sng file
 const sngData = await fetchSngFile("https://example.com/chart.sng");
 const files = await extractSngFile(sngData);
@@ -495,6 +521,9 @@ const files = await extractSngFile(sngData);
 const chartFile = findChartFile(files); // Returns .chart or .mid file
 const audioFiles = findAudioFiles(files); // Returns audio file data
 
+// Check if a file is a video (to exclude from processing)
+const nonVideoFiles = files.filter((f) => !isVideoFile(f.fileName));
+
 // Prepare all data for playback
 const preparedData = await prepareChartData(files, "guitar", "expert");
 ```
@@ -528,13 +557,14 @@ Requires support for:
 - Web Audio API
 - WebGL
 
+**Animated Textures:** Requires the ImageDecoder API (Chromium-based browsers only: Chrome, Edge, Opera). Use `areAnimationsSupported()` to check. Other browsers fall back to static textures.
+
 ## Dependencies
 
 - `three` - 3D rendering
 - `scan-chart` - Chart parsing
 - `parse-sng` - .sng file extraction
 - `eventemitter3` - Event handling
-- `lodash` - Utility functions
 
 ## License
 

package/dist/index.d.ts

@@ -3,6 +3,56 @@ export { Difficulty, Instrument, InstrumentType, getInstrumentType, instrumentTy
 import * as THREE from 'three';
 
 type ParsedChart = ReturnType<typeof parseChartFile>;
+/**
+ * Check if animations are supported on this browser.
+ * Use this to conditionally enable/disable animation features.
+ */
+declare function areAnimationsSupported(): boolean;
+/**
+ * Manages an animated WebP texture using the ImageDecoder API.
+ * Pre-decodes all frames during initialization for optimal performance.
+ * Falls back to a static texture if ImageDecoder is not supported.
+ */
+declare class AnimatedTexture {
+    private canvas;
+    private ctx;
+    texture: THREE.CanvasTexture;
+    private frameIndex;
+    private frameCount;
+    private lastFrameTime;
+    private frameDurations;
+    /** Pre-decoded frames stored as ImageBitmap for fast synchronous access */
+    private frameCache;
+    private isAnimated;
+    private disposed;
+    private constructor();
+    /**
+     * Creates an AnimatedTexture from a URL.
+     * Uses ImageDecoder for animation if available, otherwise loads as static texture.
+     * Pre-decodes all frames during initialization for optimal render performance.
+     */
+    static create(url: string): Promise<AnimatedTexture | THREE.Texture>;
+    /**
+     * Updates the texture to the current animation frame based on elapsed time.
+     * This method is SYNCHRONOUS for optimal render performance - all frames
+     * are pre-decoded during initialization.
+     */
+    tick(): void;
+    /**
+     * Disposes of resources used by this animated texture.
+     */
+    dispose(): void;
+}
+/** Collection of animated textures that need to be ticked each frame */
+declare class AnimatedTextureManager {
+    private animatedTextures;
+    register(texture: AnimatedTexture | THREE.Texture): void;
+    /**
+     * Updates all animated textures. This is now SYNCHRONOUS for optimal performance.
+     */
+    tick(): void;
+    dispose(): void;
+}
 /**
  * Custom note types for 6-fret barre notes.
  * These are the only sprites without a dedicated NoteType from scan-chart.
@@ -51,6 +101,7 @@ declare class ChartPreview {
     private renderer;
     private audioManager;
     private notesManager;
+    private animatedTextureManager;
     private progressIntervalMs;
     private lastProgressEmitTime;
     /**
@@ -138,15 +189,26 @@ declare class ChartPreview {
     private addStrikelineToScene;
     private animateFrame;
 }
+interface LoadTexturesOptions {
+    /**
+     * Whether to enable animated textures.
+     * When true (default), uses ImageDecoder API for animated WebP if available.
+     * When false, always loads static textures for better performance.
+     * Use `areAnimationsSupported()` to check if animations are supported on the current browser.
+     */
+    animationsEnabled?: boolean;
+}
 /**
  * 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
+ * @param options Optional configuration for texture loading
+ * @returns An object containing highway, strikeline, note textures, and animated texture manager
  */
-declare function loadTextures(instrumentType: InstrumentType): Promise<{
+declare function loadTextures(instrumentType: InstrumentType, options?: LoadTexturesOptions): Promise<{
     highwayTexture: THREE.Texture;
     strikelineTexture: THREE.Texture;
     noteTextures: Map<ExtendedNoteType, Map<number, THREE.Texture>>;
+    animatedTextureManager: AnimatedTextureManager;
 }>;
 
 /**
@@ -163,6 +225,11 @@ interface LoadFromUrlConfig {
     initialSeekPercent?: number;
     /** AbortSignal to cancel the fetch operation */
     signal?: AbortSignal;
+    /**
+     * Whether to enable animated textures. Defaults to true.
+     * Set to false for better performance or when animations aren't supported.
+     */
+    animationsEnabled?: boolean;
 }
 /**
  * Configuration for loading a chart from raw .sng file data.
@@ -176,6 +243,11 @@ interface LoadFromSngFileConfig {
     difficulty: Difficulty;
     /** Initial seek position as a percentage (0-1). Defaults to 0. */
     initialSeekPercent?: number;
+    /**
+     * Whether to enable animated textures. Defaults to true.
+     * Set to false for better performance or when animations aren't supported.
+     */
+    animationsEnabled?: boolean;
 }
 /**
  * Configuration for loading a chart from individual chart and audio files.
@@ -192,6 +264,11 @@ interface LoadFromChartFilesConfig {
     difficulty: Difficulty;
     /** Initial seek position as a percentage (0-1). Defaults to 0. */
     initialSeekPercent?: number;
+    /**
+     * Whether to enable animated textures. Defaults to true.
+     * Set to false for better performance or when animations aren't supported.
+     */
+    animationsEnabled?: boolean;
 }
 /**
  * Result of preparing chart data for playback.
@@ -252,12 +329,13 @@ declare function isVideoFile(fileName: string): boolean;
  * @param instrument - The instrument to display
  * @param difficulty - The difficulty level to display
  * @param initialSeekPercent - Initial seek position (0-1)
+ * @param textureOptions - Options for texture loading (e.g., animations enabled)
  * @returns Prepared chart data ready for the player
  */
 declare function prepareChartData(files: {
     fileName: string;
     data: Uint8Array;
-}[], instrument: Instrument, difficulty: Difficulty, initialSeekPercent?: number): Promise<PreparedChartData>;
+}[], instrument: Instrument, difficulty: Difficulty, initialSeekPercent?: number, textureOptions?: LoadTexturesOptions): Promise<PreparedChartData>;
 /**
  * Fetches a .sng file from a URL.
  *
@@ -493,4 +571,4 @@ declare global {
     }
 }
 
-export { ChartPreview, ChartPreviewConfig, ChartPreviewEvents, ChartPreviewPlayer, ChartPreviewPlayerConfig, LoadFromChartFilesConfig, LoadFromSngFileConfig, LoadFromUrlConfig, ParsedChart, PlayerState, PreparedChartData, extractSngFile, fetchSngFile, findAudioFiles, findChartFile, isVideoFile, prepareChartData };
+export { ChartPreview, ChartPreviewConfig, ChartPreviewEvents, ChartPreviewPlayer, ChartPreviewPlayerConfig, LoadFromChartFilesConfig, LoadFromSngFileConfig, LoadFromUrlConfig, LoadTexturesOptions, ParsedChart, PlayerState, PreparedChartData, areAnimationsSupported, extractSngFile, fetchSngFile, findAudioFiles, findChartFile, isVideoFile, prepareChartData };