chart-preview 1.0.3 → 1.2.0

package/src/ChartPreview.ts

@@ -25,6 +25,267 @@ const HIGHWAY_DURATION_MS = 1500;
 const SCALE = 0.105;
 const NOTE_SPAN_WIDTH = 0.95;
 
+/**
+ * Check if the ImageDecoder API is available for animated WebP support.
+ * This API is available in Chromium-based browsers (Chrome, Edge, Opera).
+ */
+function isImageDecoderSupported(): boolean {
+  return typeof ImageDecoder !== "undefined";
+}
+
+/**
+ * Check if animations are supported on this browser.
+ * Use this to conditionally enable/disable animation features.
+ */
+export function areAnimationsSupported(): boolean {
+  return isImageDecoderSupported();
+}
+
+/**
+ * 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.
+ */
+class AnimatedTexture {
+  private canvas: HTMLCanvasElement;
+  private ctx: CanvasRenderingContext2D;
+  public texture: THREE.CanvasTexture;
+  private frameIndex = 0;
+  private frameCount = 0;
+  private lastFrameTime = 0;
+  private frameDurations: number[] = [];
+  /** Pre-decoded frames stored as ImageBitmap for fast synchronous access */
+  private frameCache: ImageBitmap[] = [];
+  private isAnimated = false;
+  private disposed = false;
+
+  private constructor(width: number, height: number) {
+    this.canvas = document.createElement("canvas");
+    this.canvas.width = width;
+    this.canvas.height = height;
+    this.ctx = this.canvas.getContext("2d")!;
+    this.texture = new THREE.CanvasTexture(this.canvas);
+    this.texture.colorSpace = THREE.SRGBColorSpace;
+  }
+
+  /**
+   * 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 async create(url: string): Promise<AnimatedTexture | THREE.Texture> {
+    if (!isImageDecoderSupported()) {
+      // Fall back to static texture loading
+      return loadStaticTexture(url);
+    }
+
+    try {
+      const response = await fetch(url);
+      if (!response.ok || !response.body) {
+        throw new Error(`Failed to fetch ${url}`);
+      }
+
+      // Check if the image type is supported for decoding
+      const contentType = response.headers.get("content-type") || "image/webp";
+      const isSupported = await ImageDecoder.isTypeSupported(contentType);
+      if (!isSupported) {
+        // Fall back to static texture
+        return loadStaticTexture(url);
+      }
+
+      const decoder = new ImageDecoder({
+        data: response.body,
+        type: contentType,
+      });
+
+      await decoder.completed;
+
+      const track = decoder.tracks.selectedTrack;
+      if (!track) {
+        throw new Error("No track found in image");
+      }
+
+      const frameCount = track.frameCount;
+
+      // If only one frame, just return a static texture
+      if (frameCount <= 1) {
+        const result = await decoder.decode({ frameIndex: 0 });
+        const frame = result.image;
+        const animTexture = new AnimatedTexture(
+          frame.displayWidth,
+          frame.displayHeight
+        );
+        animTexture.ctx.drawImage(frame, 0, 0);
+        animTexture.texture.needsUpdate = true;
+        frame.close();
+        decoder.close();
+        return animTexture.texture;
+      }
+
+      // Animated image - pre-decode ALL frames for optimal performance
+      const firstResult = await decoder.decode({ frameIndex: 0 });
+      const firstFrame = firstResult.image;
+      const animTexture = new AnimatedTexture(
+        firstFrame.displayWidth,
+        firstFrame.displayHeight
+      );
+
+      // Pre-decode all frames into ImageBitmap cache
+      animTexture.frameDurations = [];
+      animTexture.frameCache = [];
+
+      for (let i = 0; i < frameCount; i++) {
+        try {
+          const frameResult = await decoder.decode({ frameIndex: i });
+          const videoFrame = frameResult.image;
+
+          // Create an ImageBitmap from the VideoFrame for fast synchronous access
+          const bitmap = await createImageBitmap(videoFrame);
+          animTexture.frameCache.push(bitmap);
+
+          // Duration is in microseconds, convert to milliseconds
+          const durationMs = (videoFrame.duration ?? 100000) / 1000;
+          animTexture.frameDurations.push(durationMs);
+          videoFrame.close();
+        } catch {
+          animTexture.frameDurations.push(100); // Default 100ms
+          // If frame decode fails, reuse the last successful frame or create empty bitmap
+          if (animTexture.frameCache.length > 0) {
+            animTexture.frameCache.push(
+              animTexture.frameCache[animTexture.frameCache.length - 1]
+            );
+          }
+        }
+      }
+
+      // Draw the first frame
+      if (animTexture.frameCache.length > 0) {
+        animTexture.ctx.drawImage(animTexture.frameCache[0], 0, 0);
+        animTexture.texture.needsUpdate = true;
+      }
+
+      animTexture.frameCount = animTexture.frameCache.length;
+      animTexture.isAnimated = animTexture.frameCount > 1;
+      animTexture.lastFrameTime = performance.now();
+
+      // Close the decoder - we no longer need it since all frames are cached
+      firstFrame.close();
+      decoder.close();
+
+      return animTexture;
+    } catch (error) {
+      // Fall back to static texture on any error
+      console.warn(
+        "Failed to load animated texture, falling back to static:",
+        error
+      );
+      return loadStaticTexture(url);
+    }
+  }
+
+  /**
+   * 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 {
+    if (!this.isAnimated || this.disposed || this.frameCache.length === 0) {
+      return;
+    }
+
+    const now = performance.now();
+    const elapsed = now - this.lastFrameTime;
+    const currentFrameDuration = this.frameDurations[this.frameIndex] || 100;
+
+    if (elapsed >= currentFrameDuration) {
+      this.frameIndex = (this.frameIndex + 1) % this.frameCount;
+      this.lastFrameTime = now;
+
+      // Synchronous frame update from pre-decoded cache
+      const frame = this.frameCache[this.frameIndex];
+      if (frame) {
+        this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+        this.ctx.drawImage(frame, 0, 0);
+        this.texture.needsUpdate = true;
+      }
+    }
+  }
+
+  /**
+   * Disposes of resources used by this animated texture.
+   */
+  dispose(): void {
+    this.disposed = true;
+    // Close all cached ImageBitmaps
+    for (const bitmap of this.frameCache) {
+      bitmap.close();
+    }
+    this.frameCache = [];
+    this.texture.dispose();
+  }
+}
+
+/**
+ * Loads a static texture from a URL with proper error handling.
+ * Creates a fallback placeholder texture if loading fails.
+ */
+async function loadStaticTexture(url: string): Promise<THREE.Texture> {
+  const textureLoader = new THREE.TextureLoader();
+  try {
+    const texture = await textureLoader.loadAsync(url);
+    texture.colorSpace = THREE.SRGBColorSpace;
+    return texture;
+  } catch (error) {
+    console.warn(`Failed to load static texture from ${url}:`, error);
+    // Create a small placeholder texture so notes still render
+    return createPlaceholderTexture();
+  }
+}
+
+/**
+ * Creates a placeholder texture (magenta square) for missing textures.
+ * This ensures notes always render even if texture loading fails.
+ */
+function createPlaceholderTexture(): THREE.Texture {
+  const canvas = document.createElement("canvas");
+  canvas.width = 32;
+  canvas.height = 32;
+  const ctx = canvas.getContext("2d")!;
+  // Draw a magenta square to make missing textures obvious
+  ctx.fillStyle = "#FF00FF";
+  ctx.fillRect(0, 0, 32, 32);
+  const texture = new THREE.CanvasTexture(canvas);
+  texture.colorSpace = THREE.SRGBColorSpace;
+  return texture;
+}
+
+/** Collection of animated textures that need to be ticked each frame */
+class AnimatedTextureManager {
+  private animatedTextures: AnimatedTexture[] = [];
+
+  register(texture: AnimatedTexture | THREE.Texture): void {
+    if (texture instanceof AnimatedTexture) {
+      this.animatedTextures.push(texture);
+    }
+  }
+
+  /**
+   * Updates all animated textures. This is now SYNCHRONOUS for optimal performance.
+   */
+  tick(): void {
+    for (const texture of this.animatedTextures) {
+      texture.tick();
+    }
+  }
+
+  dispose(): void {
+    for (const texture of this.animatedTextures) {
+      texture.dispose();
+    }
+    this.animatedTextures = [];
+  }
+}
+
 /**
  * Custom note types for 6-fret barre notes.
  * These are the only sprites without a dedicated NoteType from scan-chart.
@@ -89,6 +350,7 @@ export class ChartPreview {
   private renderer: ChartRenderer;
   private audioManager: AudioManager | SilentAudioManager;
   private notesManager: NotesManager;
+  private animatedTextureManager: AnimatedTextureManager;
   private progressIntervalMs: number;
   private lastProgressEmitTime = 0;
 
@@ -162,6 +424,8 @@ export class ChartPreview {
     const chartPreview = new ChartPreview();
     chartPreview.instrumentType = getInstrumentType(config.instrument);
     chartPreview.highwayTexture = config.textures.highwayTexture;
+    chartPreview.animatedTextureManager =
+      config.textures.animatedTextureManager;
     chartPreview.progressIntervalMs =
       config.progressIntervalMs ?? DEFAULT_PROGRESS_INTERVAL_MS;
     chartPreview.camera = new ChartCamera(config.container);
@@ -257,6 +521,7 @@ export class ChartPreview {
     this.renderer.dispose();
     this.renderer.forceContextLoss();
     this.audioManager.closeAudio();
+    this.animatedTextureManager.dispose();
   }
 
   private addHighwayToScene(highwayTexture: THREE.Texture) {
@@ -307,6 +572,9 @@ export class ChartPreview {
       this.audioManager.chartCurrentTimeMs
     );
 
+    // Update animated textures (for animated WebP notes)
+    this.animatedTextureManager.tick();
+
     // Shift highway position
     const scrollPosition =
       -0.9 *
@@ -858,6 +1126,17 @@ class NotesManager {
       i++
     ) {
       const note = this.noteEvents[i];
+
+      // Get the material for this note type and flags
+      const material = this.noteMaterials.get(note.type)?.get(note.flags);
+      if (!material) {
+        // Skip notes with missing textures (shouldn't happen, but prevents crashes)
+        console.warn(
+          `Missing texture for note type ${note.type} with flags ${note.flags}`
+        );
+        continue;
+      }
+
       const noteGroup = new THREE.Group();
       const scale =
         note.type === noteTypes.kick
@@ -866,9 +1145,7 @@ class NotesManager {
             this.instrumentType === instrumentTypes.sixFret
           ? 0.04
           : SCALE;
-      const sprite = new THREE.Sprite(
-        this.noteMaterials.get(note.type)!.get(note.flags)!
-      );
+      const sprite = new THREE.Sprite(material);
       noteGroup.add(sprite);
       sprite.center = new THREE.Vector2(
         note.type === noteTypes.kick ? 0.62 : 0.5,
@@ -973,16 +1250,56 @@ class EventSequence<
   }
 }
 
+export 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
  */
-async function loadTextures(instrumentType: InstrumentType) {
+async function loadTextures(
+  instrumentType: InstrumentType,
+  options: LoadTexturesOptions = {}
+) {
+  const { animationsEnabled = true } = options;
   const textureLoader = new THREE.TextureLoader();
+  const animatedTextureManager = new AnimatedTextureManager();
+
   const load = (path: string) =>
     textureLoader.loadAsync("https://static.enchor.us/" + path);
 
+  /**
+   * Loads a texture with animation support.
+   * Uses ImageDecoder API for animated WebP when available, falls back to static.
+   * If animationsEnabled is false, always loads static textures.
+   */
+  const loadAnimated = async (path: string): Promise<THREE.Texture> => {
+    const url = `https://static.enchor.us/preview-${path}.webp`;
+
+    // If animations are disabled, load static texture directly
+    if (!animationsEnabled) {
+      return loadStaticTexture(url);
+    }
+
+    const result = await AnimatedTexture.create(url);
+
+    if (result instanceof AnimatedTexture) {
+      animatedTextureManager.register(result);
+      return result.texture;
+    }
+
+    return result;
+  };
+
   const [highwayTexture, strikelineTexture, noteTextures] = await Promise.all([
     (async () => {
       const texture = await load("preview-highway.png");
@@ -1014,9 +1331,7 @@ async function loadTextures(instrumentType: InstrumentType) {
         flags: number,
         path: string
       ) => {
-        const texture = textureLoader.loadAsync(
-          `https://static.enchor.us/preview-${path}.webp`
-        );
+        const texture = loadAnimated(path);
         texturePromises.push({ type, flags, texture });
         return texture;
       };
@@ -1199,6 +1514,7 @@ async function loadTextures(instrumentType: InstrumentType) {
     highwayTexture,
     strikelineTexture,
     noteTextures,
+    animatedTextureManager,
   };
 }
 

package/src/ChartPreviewPlayer.ts

@@ -357,6 +357,11 @@ export class ChartPreviewPlayer extends HTMLElement {
   connectedCallback() {
     this.setAttribute("tabindex", "0");
     document.addEventListener("fullscreenchange", this.handleFullscreenChange);
+    // Safari uses webkit prefix
+    document.addEventListener(
+      "webkitfullscreenchange",
+      this.handleFullscreenChange
+    );
   }
 
   disconnectedCallback() {
@@ -365,6 +370,10 @@ export class ChartPreviewPlayer extends HTMLElement {
       "fullscreenchange",
       this.handleFullscreenChange
     );
+    document.removeEventListener(
+      "webkitfullscreenchange",
+      this.handleFullscreenChange
+    );
     this.removeEventListener("keydown", this.handleKeydown);
   }
 
@@ -467,8 +476,9 @@ export class ChartPreviewPlayer extends HTMLElement {
       }
     });
 
-    // Fullscreen button
-    this.fullscreenBtn.addEventListener("click", () => {
+    // Fullscreen button - stop propagation to prevent any parent handlers
+    this.fullscreenBtn.addEventListener("click", (e) => {
+      e.stopPropagation();
       this.toggleFullscreen();
     });
 
@@ -525,14 +535,20 @@ export class ChartPreviewPlayer extends HTMLElement {
   };
 
   private handleFullscreenChange = () => {
-    this._isFullscreen = document.fullscreenElement === this.container;
+    // Check if we're in fullscreen mode (support both standard and webkit prefix)
+    const fullscreenElement =
+      document.fullscreenElement ||
+      (document as unknown as { webkitFullscreenElement?: Element })
+        .webkitFullscreenElement;
+    this._isFullscreen =
+      fullscreenElement !== null && fullscreenElement !== undefined;
     this.container.classList.toggle("fullscreen", this._isFullscreen);
     this.fullscreenBtn.innerHTML = this._isFullscreen
       ? ICONS.fullscreenExit
       : ICONS.fullscreen;
     this.fullscreenBtn.title = this._isFullscreen
       ? "Exit fullscreen"
-      : "Toggle fullscreen";
+      : "Enter fullscreen";
   };
 
   private onSeekStart() {
@@ -900,7 +916,8 @@ export class ChartPreviewPlayer extends HTMLElement {
         files,
         config.instrument,
         config.difficulty,
-        config.initialSeekPercent
+        config.initialSeekPercent,
+        { animationsEnabled: config.animationsEnabled }
       );
 
       // Load the chart
@@ -948,7 +965,8 @@ export class ChartPreviewPlayer extends HTMLElement {
         files,
         config.instrument,
         config.difficulty,
-        config.initialSeekPercent
+        config.initialSeekPercent,
+        { animationsEnabled: config.animationsEnabled }
       );
 
       // Load the chart
@@ -992,7 +1010,8 @@ export class ChartPreviewPlayer extends HTMLElement {
         config.files,
         config.instrument,
         config.difficulty,
-        config.initialSeekPercent
+        config.initialSeekPercent,
+        { animationsEnabled: config.animationsEnabled }
       );
 
       // Load the chart
@@ -1105,12 +1124,46 @@ export class ChartPreviewPlayer extends HTMLElement {
    * Toggle fullscreen mode
    */
   async toggleFullscreen(): Promise<void> {
-    if (!document.fullscreenEnabled) return;
+    // Check for fullscreen support (standard and webkit)
+    const doc = document as unknown as {
+      fullscreenEnabled?: boolean;
+      webkitFullscreenEnabled?: boolean;
+      fullscreenElement?: Element;
+      webkitFullscreenElement?: Element;
+      exitFullscreen?: () => Promise<void>;
+      webkitExitFullscreen?: () => void;
+    };
+    const container = this.container as unknown as {
+      requestFullscreen?: () => Promise<void>;
+      webkitRequestFullscreen?: () => void;
+    };
+
+    const isFullscreenEnabled =
+      doc.fullscreenEnabled || doc.webkitFullscreenEnabled;
+    if (!isFullscreenEnabled) return;
+
+    const fullscreenElement =
+      doc.fullscreenElement || doc.webkitFullscreenElement;
 
-    if (this._isFullscreen) {
-      await document.exitFullscreen();
-    } else {
-      await this.container.requestFullscreen();
+    try {
+      if (fullscreenElement) {
+        // Exit fullscreen
+        if (doc.exitFullscreen) {
+          await doc.exitFullscreen();
+        } else if (doc.webkitExitFullscreen) {
+          doc.webkitExitFullscreen();
+        }
+      } else {
+        // Enter fullscreen
+        if (container.requestFullscreen) {
+          await container.requestFullscreen();
+        } else if (container.webkitRequestFullscreen) {
+          container.webkitRequestFullscreen();
+        }
+      }
+    } catch (error) {
+      // Fullscreen request can fail due to user gesture requirements or other reasons
+      console.warn("Fullscreen toggle failed:", error);
     }
   }
 

package/src/SngLoader.ts

@@ -7,7 +7,11 @@ import {
   type Instrument,
   type ScannedChart,
 } from "scan-chart";
-import { ChartPreview, type ParsedChart } from "./ChartPreview";
+import {
+  ChartPreview,
+  type LoadTexturesOptions,
+  type ParsedChart,
+} from "./ChartPreview";
 
 /**
  * Audio file extensions supported by the chart preview.
@@ -33,6 +37,11 @@ export 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;
 }
 
 /**
@@ -47,6 +56,11 @@ export 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;
 }
 
 /**
@@ -61,6 +75,11 @@ export 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;
 }
 
 /**
@@ -218,13 +237,15 @@ export 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
  */
 export async function prepareChartData(
   files: { fileName: string; data: Uint8Array }[],
   instrument: Instrument,
   difficulty: Difficulty,
-  initialSeekPercent = 0
+  initialSeekPercent = 0,
+  textureOptions: LoadTexturesOptions = {}
 ): Promise<PreparedChartData> {
   // Filter out video files
   const filteredFiles = files.filter((f) => !isVideoFile(f.fileName));
@@ -276,7 +297,10 @@ export async function prepareChartData(
 
   // Load textures for the instrument type
   const instrumentType = getInstrumentType(instrument);
-  const textures = await ChartPreview.loadTextures(instrumentType);
+  const textures = await ChartPreview.loadTextures(
+    instrumentType,
+    textureOptions
+  );
 
   // Calculate audio length from the last note or from metadata
   const lastNote = parsedChart.trackData

package/src/index.ts

@@ -1,8 +1,10 @@
 // Core classes
 export {
   ChartPreview,
+  areAnimationsSupported,
   type ChartPreviewConfig,
   type ChartPreviewEvents,
+  type LoadTexturesOptions,
   type ParsedChart,
 } from "./ChartPreview";