chart-preview 1.0.0

package/src/SharedAudioContext.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared AudioContext manager for multi-instance support.
+ *
+ * Browsers limit the number of AudioContexts that can be created (typically ~6).
+ * By sharing a single AudioContext across all ChartPreview instances, we can
+ * support many more simultaneous players.
+ *
+ * Each player instance gets its own GainNode connected to the shared context,
+ * allowing independent volume control while sharing the same audio destination.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const AudioContextClass =
+  typeof window !== "undefined"
+    ? window.AudioContext || (window as any).webkitAudioContext
+    : null;
+
+let sharedContext: AudioContext | null = null;
+let activeInstanceCount = 0;
+
+/**
+ * Gets or creates the shared AudioContext.
+ * The context is lazily created on first use.
+ *
+ * @returns The shared AudioContext, or null if AudioContext is not supported
+ */
+export function getSharedAudioContext(): AudioContext | null {
+  if (!AudioContextClass) {
+    return null;
+  }
+
+  if (!sharedContext || sharedContext.state === "closed") {
+    sharedContext = new AudioContextClass();
+  }
+
+  return sharedContext;
+}
+
+/**
+ * Registers a new instance that will use the shared AudioContext.
+ * Call this when a player starts using the context.
+ */
+export function registerInstance(): void {
+  activeInstanceCount++;
+}
+
+/**
+ * Unregisters an instance from the shared AudioContext.
+ * When all instances are unregistered, the context can be closed.
+ *
+ * Note: We don't actually close the context here because:
+ * 1. Creating a new context is expensive
+ * 2. The user might create new players soon
+ * 3. The context uses minimal resources when not playing
+ */
+export function unregisterInstance(): void {
+  activeInstanceCount = Math.max(0, activeInstanceCount - 1);
+}
+
+/**
+ * Gets the current number of active instances using the shared context.
+ */
+export function getActiveInstanceCount(): number {
+  return activeInstanceCount;
+}
+
+/**
+ * Checks if AudioContext is supported in the current environment.
+ */
+export function isAudioContextSupported(): boolean {
+  return AudioContextClass !== null;
+}
+
+/**
+ * Resumes the shared AudioContext if it's suspended.
+ * This is needed because browsers require user interaction before playing audio.
+ */
+export async function resumeSharedContext(): Promise<void> {
+  const ctx = getSharedAudioContext();
+  if (ctx && ctx.state === "suspended") {
+    await ctx.resume();
+  }
+}

package/src/SngLoader.ts

@@ -0,0 +1,330 @@
+import { SngStream } from "parse-sng";
+import {
+  scanChartFolder,
+  parseChartFile,
+  getInstrumentType,
+  type Difficulty,
+  type Instrument,
+  type ScannedChart,
+} from "scan-chart";
+import { ChartPreview, type ParsedChart } from "./ChartPreview";
+
+/**
+ * Audio file extensions supported by the chart preview.
+ */
+const AUDIO_EXTENSIONS = [".ogg", ".mp3", ".wav", ".opus"];
+
+/**
+ * Audio file names to exclude from playback (preview stems, crowd noise).
+ */
+const EXCLUDED_AUDIO_NAMES = ["preview", "crowd"];
+
+/**
+ * Configuration for loading a chart from a URL.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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
+ */
+export async function extractSngFile(
+  data: Uint8Array
+): Promise<{ fileName: string; data: Uint8Array }[]> {
+  return new Promise((resolve, reject) => {
+    const files: { fileName: string; data: Uint8Array }[] = [];
+
+    // Convert Uint8Array to ReadableStream
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(data);
+        controller.close();
+      },
+    });
+
+    const sngStream = new SngStream(stream, { generateSongIni: true });
+
+    sngStream.on("error", (error) => {
+      reject(error instanceof Error ? error : new Error(String(error)));
+    });
+
+    sngStream.on("file", async (fileName, fileStream, nextFile) => {
+      try {
+        // Read the entire file stream into a Uint8Array
+        const chunks: Uint8Array[] = [];
+        const reader = fileStream.getReader();
+
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          chunks.push(value);
+        }
+
+        // Combine chunks into a single Uint8Array
+        const totalLength = chunks.reduce(
+          (sum, chunk) => sum + chunk.length,
+          0
+        );
+        const fileData = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+          fileData.set(chunk, offset);
+          offset += chunk.length;
+        }
+
+        files.push({ fileName, data: fileData });
+
+        if (nextFile) {
+          nextFile();
+        } else {
+          resolve(files);
+        }
+      } catch (error) {
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+
+    sngStream.start();
+  });
+}
+
+/**
+ * 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
+ */
+export function findChartFile(
+  files: { fileName: string; data: Uint8Array }[]
+): { fileName: string; data: Uint8Array; format: "chart" | "mid" } | null {
+  // Look for .mid first (preferred)
+  const midFile = files.find((f) => f.fileName.toLowerCase().endsWith(".mid"));
+  if (midFile) {
+    return { ...midFile, format: "mid" };
+  }
+
+  // Fall back to .chart
+  const chartFile = files.find((f) =>
+    f.fileName.toLowerCase().endsWith(".chart")
+  );
+  if (chartFile) {
+    return { ...chartFile, format: "chart" };
+  }
+
+  return 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
+ */
+export function findAudioFiles(
+  files: { fileName: string; data: Uint8Array }[]
+): Uint8Array[] {
+  return files
+    .filter((file) => {
+      const ext = file.fileName
+        .toLowerCase()
+        .slice(file.fileName.lastIndexOf("."));
+      if (!AUDIO_EXTENSIONS.includes(ext)) {
+        return false;
+      }
+
+      // Exclude preview and crowd audio files
+      const baseName =
+        file.fileName
+          .toLowerCase()
+          .replace(/\.[^/.]+$/, "")
+          .split("/")
+          .pop() || "";
+      return !EXCLUDED_AUDIO_NAMES.some((excluded) =>
+        baseName.includes(excluded)
+      );
+    })
+    .map((file) => file.data);
+}
+
+/**
+ * Checks if a filename is a video file (to be excluded from .sng extraction).
+ */
+export function isVideoFile(fileName: string): boolean {
+  const videoExtensions = [".mp4", ".avi", ".webm", ".ogv", ".mpeg"];
+  const ext = fileName.toLowerCase().slice(fileName.lastIndexOf("."));
+  return videoExtensions.includes(ext);
+}
+
+/**
+ * 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
+ */
+export async function prepareChartData(
+  files: { fileName: string; data: Uint8Array }[],
+  instrument: Instrument,
+  difficulty: Difficulty,
+  initialSeekPercent = 0
+): Promise<PreparedChartData> {
+  // Filter out video files
+  const filteredFiles = files.filter((f) => !isVideoFile(f.fileName));
+
+  // Scan the chart folder to get metadata and modifiers
+  const scannedChart: ScannedChart = scanChartFolder(filteredFiles);
+
+  if (!scannedChart.playable || !scannedChart.notesData) {
+    throw new Error("This chart has no playable tracks.");
+  }
+
+  // Find the chart file
+  const chartFile = findChartFile(filteredFiles);
+  if (!chartFile) {
+    throw new Error("No .chart or .mid file found in the chart.");
+  }
+
+  // Build chart modifiers from scanned chart
+  const modifiers = {
+    song_length: scannedChart.song_length || 0,
+    hopo_frequency: scannedChart.hopo_frequency || 0,
+    eighthnote_hopo: scannedChart.eighthnote_hopo || false,
+    multiplier_note: scannedChart.multiplier_note || 0,
+    sustain_cutoff_threshold: scannedChart.sustain_cutoff_threshold ?? -1,
+    chord_snap_threshold: scannedChart.chord_snap_threshold || 0,
+    five_lane_drums: scannedChart.five_lane_drums || false,
+    pro_drums: scannedChart.pro_drums || false,
+  };
+
+  // Parse the chart
+  const parsedChart = parseChartFile(
+    chartFile.data,
+    chartFile.format,
+    modifiers
+  );
+
+  // Verify the requested track exists
+  const track = parsedChart.trackData.find(
+    (t) => t.instrument === instrument && t.difficulty === difficulty
+  );
+  if (!track) {
+    throw new Error(
+      `No ${difficulty} ${instrument} track found in this chart.`
+    );
+  }
+
+  // Find audio files
+  const audioFiles = findAudioFiles(filteredFiles);
+
+  // Load textures for the instrument type
+  const instrumentType = getInstrumentType(instrument);
+  const textures = await ChartPreview.loadTextures(instrumentType);
+
+  // Calculate audio length from the last note or from metadata
+  const lastNote = parsedChart.trackData
+    .flatMap((t) => t.noteEventGroups.flat())
+    .reduce((max, note) => Math.max(max, note.msTime + note.msLength), 0);
+  const audioLengthMs = scannedChart.song_length || lastNote + 5000;
+
+  // Calculate start delay from chart metadata
+  const startDelayMs =
+    (scannedChart.delay || 0) + (scannedChart.chart_offset || 0) * 1000;
+
+  // Calculate initial seek position from preview_start_time if not explicitly provided
+  const seekPercent =
+    initialSeekPercent > 0
+      ? initialSeekPercent
+      : scannedChart.preview_start_time
+      ? scannedChart.preview_start_time / audioLengthMs
+      : 0;
+
+  return {
+    parsedChart,
+    textures,
+    audioFiles,
+    instrument,
+    difficulty,
+    startDelayMs,
+    audioLengthMs,
+    initialSeekPercent: seekPercent,
+  };
+}
+
+/**
+ * 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
+ */
+export async function fetchSngFile(
+  url: string,
+  signal?: AbortSignal
+): Promise<Uint8Array> {
+  const response = await fetch(url, { signal });
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch chart: ${response.status} ${response.statusText}`
+    );
+  }
+  const arrayBuffer = await response.arrayBuffer();
+  return new Uint8Array(arrayBuffer);
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// Core classes
+export {
+  ChartPreview,
+  type ChartPreviewConfig,
+  type ChartPreviewEvents,
+  type ParsedChart,
+} from "./ChartPreview";
+
+// Web Component player
+export {
+  ChartPreviewPlayer,
+  type ChartPreviewPlayerConfig,
+  type PlayerState,
+} from "./ChartPreviewPlayer";
+
+// Loader utilities and types (for advanced use cases)
+export {
+  extractSngFile,
+  fetchSngFile,
+  prepareChartData,
+  findChartFile,
+  findAudioFiles,
+  isVideoFile,
+  type LoadFromUrlConfig,
+  type LoadFromSngFileConfig,
+  type LoadFromChartFilesConfig,
+  type PreparedChartData,
+} from "./SngLoader";
+
+// Re-export commonly used types from scan-chart for convenience
+export {
+  type Difficulty,
+  type Instrument,
+  type InstrumentType,
+  getInstrumentType,
+  instrumentTypes,
+} from "scan-chart";

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"esModuleInterop": true,
+		"declaration": true,
+		"emitDeclarationOnly": false,
+		"allowSyntheticDefaultImports": true,
+		"sourceMap": true,
+		"outDir": "./dist",
+		"baseUrl": "./",
+		"skipLibCheck": true,
+		"strictNullChecks": true,
+		"noImplicitAny": true,
+		"downlevelIteration": true,
+		"strictBindCallApply": true,
+		"forceConsistentCasingInFileNames": true,
+		"noFallthroughCasesInSwitch": true,
+		"noErrorTruncation": true,
+		"noEmit": true,
+		"lib": ["ES2020", "DOM", "DOM.Iterable"]
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "dev"]
+}

package/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "vite";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  root: "dev",
+  server: {
+    port: 3000,
+    open: true,
+  },
+  resolve: {
+    alias: {
+      "chart-preview": path.resolve(__dirname, "src/index.ts"),
+    },
+  },
+});