chart-preview

A 3D chart preview player for rhythm games like Clone Hero. Renders chart files as an interactive video-like preview using THREE.js.

Features

Renders .chart and .mid files as a 3D highway visualization
Supports 5-fret guitar, 6-fret (GHL) guitar, and drums
Plays audio files in sync with the visual preview
Video player-like controls (play, pause, seek, volume, fullscreen)
Keyboard shortcuts for easy control
Framework-agnostic - works with React, Angular, Vue, or vanilla JS
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

npm install chart-preview

Quick Start

The simplest way to use chart-preview is with the Web Component and URL-based loading:

<chart-preview-player id="player"></chart-preview-player>

<script type="module">
  const player = document.getElementById("player");

  await player.loadFromUrl({
    url: "https://files.enchor.us/abc123.sng",
    instrument: "guitar",
    difficulty: "expert",
  });
</script>

That's it! The component handles fetching, parsing, texture loading, and rendering.

Usage Options

Option 1: URL-Based Loading (Simplest)

Load directly from a URL to a .sng file:

import "chart-preview"; // Registers the web component

const player = document.querySelector("chart-preview-player");

await player.loadFromUrl({
  url: "https://files.enchor.us/abc123.sng",
  instrument: "guitar",
  difficulty: "expert",
  initialSeekPercent: 0.25, // Optional: start at 25%
});

Option 2: Raw .sng File Loading

When you've already fetched the .sng file:

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",
});

Option 3: Individual Files Loading

When loading from a folder or file picker:

// From a file input or folder selection
const files = [
  { fileName: "notes.chart", data: chartFileData },
  { fileName: "song.ogg", data: audioFileData },
  { fileName: "guitar.ogg", data: guitarAudioData },
];

await player.loadFromChartFiles({
  files,
  instrument: "guitar",
  difficulty: "expert",
});

Option 4: Pre-Processed Data (Advanced)

For maximum control, you can pre-process the data yourself:

import {
  ChartPreview,
  ChartPreviewPlayer,
  getInstrumentType,
  areAnimationsSupported,
} from "chart-preview";
import { parseChartFile } from "scan-chart";

// 1. Parse your chart file
const parsedChart = parseChartFile(chartData, "chart", modifiers);

// 2. Load textures (cache and reuse for same instrument type)
const textures = await ChartPreview.loadTextures(getInstrumentType("guitar"), {
  animationsEnabled: areAnimationsSupported(),
});

// 3. Load the chart
await player.loadChart({
  parsedChart,
  textures,
  audioFiles: [audioData],
  instrument: "guitar",
  difficulty: "expert",
  startDelayMs: 0,
  audioLengthMs: 180000,
});

Framework Integration

Angular

import {
  Component,
  ViewChild,
  ElementRef,
  CUSTOM_ELEMENTS_SCHEMA,
} from "@angular/core";
import type { ChartPreviewPlayer } from "chart-preview";
import "chart-preview"; // Register web component

@Component({
  selector: "app-chart-preview",
  template: `
    <chart-preview-player
      #player
      [attr.volume]="volume"
      (player-statechange)="onStateChange($event)"
      (player-error)="onError($event)"
    >
    </chart-preview-player>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class ChartPreviewComponent {
  @ViewChild("player") player: ElementRef<ChartPreviewPlayer>;
  volume = 50;

  async loadChart(chartUrl: string, instrument: string, difficulty: string) {
    await this.player.nativeElement.loadFromUrl({
      url: chartUrl,
      instrument,
      difficulty,
    });
  }

  onStateChange(event: CustomEvent) {
    console.log("State:", event.detail.state);
  }

  onError(event: CustomEvent) {
    console.error("Error:", event.detail.error);
  }
}

React

import { useRef, useEffect } from "react";
import type { ChartPreviewPlayer } from "chart-preview";
import "chart-preview";

function ChartPreview({ chartUrl, instrument, difficulty }) {
  const playerRef = useRef<ChartPreviewPlayer>(null);

  useEffect(() => {
    const player = playerRef.current;
    if (!player || !chartUrl) return;

    player.loadFromUrl({ url: chartUrl, instrument, difficulty });

    const handleError = (e: CustomEvent) => console.error(e.detail.error);
    player.addEventListener("player-error", handleError);

    return () => {
      player.removeEventListener("player-error", handleError);
      player.dispose();
    };
  }, [chartUrl, instrument, difficulty]);

  return <chart-preview-player ref={playerRef} volume="50" />;
}

Vue

<template>
  <chart-preview-player
    ref="player"
    :volume="volume"
    @player-statechange="onStateChange"
    @player-error="onError"
  />
</template>

<script setup>
import { ref, onMounted, onUnmounted } from "vue";
import "chart-preview";

const player = ref(null);
const volume = ref(50);

async function loadChart(url, instrument, difficulty) {
  await player.value.loadFromUrl({ url, instrument, difficulty });
}

function onStateChange(event) {
  console.log("State:", event.detail.state);
}

function onError(event) {
  console.error("Error:", event.detail.error);
}

onUnmounted(() => {
  player.value?.dispose();
});
</script>

Web Component API

`<chart-preview-player>`

A complete chart preview player with built-in controls.

Attributes

Attribute	Type	Default	Description
`volume`	`string`	`"50"`	Initial volume (0-100)

Properties

Property	Type	Description
`state`	`PlayerState`	Current player state
`isPlaying`	`boolean`	Whether currently playing
`volume`	`number`	Current volume (0-100)
`currentTimeMs`	`number`	Current playback position in ms
`durationMs`	`number`	Total duration in ms
`isFullscreen`	`boolean`	Whether in fullscreen mode

Methods

Method	Description
`loadFromUrl(config)`	Load from a URL to a .sng file
`loadFromSngFile(config)`	Load from raw .sng file data
`loadFromChartFiles(config)`	Load from individual files
`loadChart(config)`	Load from pre-processed data
`togglePlayPause()`	Toggle play/pause
`play()`	Start playback
`pause()`	Pause playback
`seek(percent)`	Seek to position (0-1)
`seekRelative(deltaMs)`	Seek relative to current position
`setVolume(volume)`	Set volume (0-100)
`toggleMute()`	Toggle mute
`toggleFullscreen()`	Toggle fullscreen mode
`dispose()`	Clean up resources

Events

Event	Detail	Description
`player-statechange`	`{ state, previousState }`	State changed
`player-progress`	`{ percent, currentMs, totalMs }`	Playback progress
`player-end`	-	Playback ended
`player-error`	`{ error }`	Error occurred

Player States

type PlayerState =
  | "idle" // No chart loaded
  | "loading" // Loading chart/audio
  | "ready" // Ready to play
  | "playing" // Currently playing
  | "paused" // Paused
  | "seeking" // Seeking
  | "ended" // Playback ended
  | "error"; // Error occurred

Keyboard Shortcuts

Key	Action
`Space`	Play/Pause
`←`	Seek backward 5s
`→`	Seek forward 5s
`↑`	Volume up 10%
`↓`	Volume down 10%
`M`	Toggle mute
`F`	Toggle fullscreen
`Escape`	Exit fullscreen

Multiple Instances

The library supports multiple simultaneous players on the same page:

<chart-preview-player id="player1"></chart-preview-player>
<chart-preview-player id="player2"></chart-preview-player>
<chart-preview-player id="player3"></chart-preview-player>

<script type="module">
  const players = document.querySelectorAll("chart-preview-player");

  // Each player can load a different chart
  await players[0].loadFromUrl({
    url: "chart1.sng",
    instrument: "guitar",
    difficulty: "expert",
  });
  await players[1].loadFromUrl({
    url: "chart2.sng",
    instrument: "drums",
    difficulty: "hard",
  });
  await players[2].loadFromUrl({
    url: "chart3.sng",
    instrument: "bass",
    difficulty: "medium",
  });

  // All can play simultaneously
  players.forEach((p) => p.play());
</script>

The library uses a shared AudioContext internally to support many players without hitting browser limits.

Configuration Types

LoadFromUrlConfig

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 (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;
}

LoadFromSngFileConfig

interface LoadFromSngFileConfig {
  /** Raw .sng file data */
  sngFile: Uint8Array;
  /** The instrument to display */
  instrument: Instrument;
  /** The difficulty level to display */
  difficulty: Difficulty;
  /** Initial seek position (0-1). Defaults to 0 */
  initialSeekPercent?: number;
  /** Whether to enable animated textures. Defaults to true */
  animationsEnabled?: boolean;
}

LoadFromChartFilesConfig

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 (0-1). Defaults to 0 */
  initialSeekPercent?: number;
  /** Whether to enable animated textures. Defaults to true */
  animationsEnabled?: boolean;
}

ChartPreviewPlayerConfig (Advanced)

interface ChartPreviewPlayerConfig {
  parsedChart: ParsedChart;
  textures: Awaited<ReturnType<typeof ChartPreview.loadTextures>>;
  audioFiles: Uint8Array[];
  instrument: Instrument;
  difficulty: Difficulty;
  startDelayMs: number;
  audioLengthMs: number;
  initialSeekPercent?: number;
}

Supported Instruments & Difficulties

Instruments

Value	Description
`'guitar'`	Lead Guitar (5-fret)
`'guitarcoop'`	Co-op Guitar
`'rhythm'`	Rhythm Guitar
`'bass'`	Bass Guitar
`'drums'`	Drums
`'keys'`	Keys
`'guitarghl'`	GHL Guitar (6-fret)
`'guitarcoopghl'`	GHL Co-op Guitar
`'rhythmghl'`	GHL Rhythm Guitar
`'bassghl'`	GHL Bass

Difficulties

Value	Description
`'expert'`	Expert
`'hard'`	Hard
`'medium'`	Medium
`'easy'`	Easy

Low-Level API

For advanced use cases, you can use the ChartPreview class directly:

import {
  ChartPreview,
  getInstrumentType,
  areAnimationsSupported,
} from "chart-preview";

// Load textures (cache for reuse)
// 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({
  parsedChart,
  textures,
  audioFiles,
  instrument: "guitar",
  difficulty: "expert",
  startDelayMs: 0,
  audioLengthMs: 180000,
  container: document.getElementById("container"),
});

// Control playback
await preview.togglePaused();
await preview.seek(0.5);
preview.volume = 0.8;

// Listen to events
preview.on("progress", (percent) => console.log(`${percent * 100}%`));
preview.on("end", () => console.log("Ended"));

// Clean up
preview.dispose();

Helper Utilities

The library exports helper utilities for advanced use cases:

import {
  extractSngFile,
  fetchSngFile,
  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);

// Find specific files
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");

Development

# Install dependencies
npm install

# Start dev server
npm run dev

# Build for production
npm run build

# Type check
npm run lint

Browser Compatibility

Chrome 80+
Firefox 75+
Safari 14+
Edge 80+

Requires support for:

Web Components (Custom Elements v1)
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

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.changeset		.changeset
.github/workflows		.github/workflows
.vscode		.vscode
dev		dev
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
RELEASING.md		RELEASING.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Geomitron/chart-preview

Folders and files

Latest commit

History

Repository files navigation