chart-preview 1.0.0 → 1.0.2

package/.changeset/config.json

@@ -5,7 +5,7 @@
 	"fixed": [],
 	"linked": [],
 	"access": "public",
-	"baseBranch": "main",
+	"baseBranch": "master",
 	"updateInternalDependencies": "patch",
 	"ignore": []
 }

package/.github/workflows/release.yml

@@ -3,7 +3,7 @@ name: Release
 on:
   push:
     branches:
-      - main
+      - master
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# chart-preview
+
+## 1.0.2
+
+### Patch Changes
+
+- 5319db5: Refactor AudioManager to improve audio playback control and state management. Introduce independent paused state tracking, enhance audio source management, and streamline audio decoding process. Update ChartPreviewPlayer styles for better UI responsiveness and remove idle message.
+
+## 1.0.1
+
+### Patch Changes
+
+- 0bbccfe: Enhance audio management by adding fallback audio length and improving start delay handling. Update AudioManager to use fallback length if no audio files are provided, and ensure end event timeout is managed correctly during playback and seeking. Refactor start delay calculation for clarity in main.ts.

package/RELEASING.md

@@ -0,0 +1,43 @@
+# Releasing
+
+This project uses [Changesets](https://github.com/changesets/changesets) for versioning and publishing.
+
+## How to Release
+
+### 1. Create a Changeset
+
+After making changes you want to release:
+
+```bash
+npx changeset
+```
+
+- Select the version bump: `patch` (bug fix), `minor` (new feature), or `major` (breaking change)
+- Write a short summary of the changes
+
+This creates a file in `.changeset/` — commit it with your changes.
+
+### 2. Push to `main`
+
+```bash
+git add .
+git commit -m "Your commit message"
+git push
+```
+
+### 3. Merge the Version PR
+
+GitHub Actions will create a **"Version Packages"** PR that:
+
+- Bumps the version in `package.json`
+- Updates `CHANGELOG.md`
+
+Merge this PR to publish to npm automatically.
+
+## Version Bump Guide
+
+| Type    | When to Use                         | Example       |
+| ------- | ----------------------------------- | ------------- |
+| `patch` | Bug fixes, minor tweaks             | 1.0.0 → 1.0.1 |
+| `minor` | New features (backwards compatible) | 1.0.0 → 1.1.0 |
+| `major` | Breaking changes                    | 1.0.0 → 2.0.0 |

package/dev/main.ts

@@ -471,9 +471,16 @@ loadBtn.addEventListener("click", async () => {
     const audioLengthMs = currentScannedChart.song_length || lastNote + 5000;
 
     // Get start delay from chart metadata
-    const startDelayMs =
-      (currentScannedChart.delay || 0) +
-      (currentScannedChart.chart_offset || 0) * 1000;
+    // delay takes priority over chart_offset if both are present
+    // Both use the same sign convention:
+    //   - Positive value = audio starts earlier (audio is ahead of chart time)
+    //   - Negative value = audio starts later (audio is delayed)
+    // We negate to convert to startDelayMs (internal representation):
+    //   - startDelayMs < 0 = audio is ahead (at chart time 0, audio is already playing)
+    //   - startDelayMs > 0 = audio is delayed (audio starts after chart time 0)
+    const startDelayMs = currentScannedChart.delay
+      ? -currentScannedChart.delay
+      : -(currentScannedChart.chart_offset || 0);
 
     // Calculate initial seek position from preview_start_time if available
     const initialSeekPercent = currentScannedChart.preview_start_time

package/dist/index.js

@@ -148,7 +148,11 @@ var _ChartPreview = class {
     chartPreview.progressIntervalMs = config.progressIntervalMs ?? DEFAULT_PROGRESS_INTERVAL_MS;
     chartPreview.camera = new ChartCamera(config.container);
     chartPreview.renderer = new ChartRenderer(config.container);
-    chartPreview.audioManager = await (isAudioContextSupported() ? AudioManager.create(config.audioFiles, config.startDelayMs) : SilentAudioManager.create(config.startDelayMs, config.audioLengthMs));
+    chartPreview.audioManager = await (isAudioContextSupported() ? AudioManager.create(
+      config.audioFiles,
+      config.startDelayMs,
+      config.audioLengthMs
+    ) : SilentAudioManager.create(config.startDelayMs, config.audioLengthMs));
     chartPreview.audioManager.on(
       "end",
       () => chartPreview.eventEmitter.emit("end")
@@ -326,10 +330,13 @@ var ChartRenderer = class extends THREE.WebGLRenderer {
   }
 };
 var AudioManager = class {
-  constructor(audioFiles, startDelayMs) {
+  // Track paused state independently since we share the AudioContext
+  constructor(audioFiles, startDelayMs, fallbackAudioLengthMs) {
     this.audioFiles = audioFiles;
     this.startDelayMs = startDelayMs;
+    this.fallbackAudioLengthMs = fallbackAudioLengthMs;
     this.eventEmitter = new import_eventemitter3.EventEmitter();
+    this.audioBuffers = [];
     this.gainNode = null;
     this.audioSources = [];
     this._volume = 0.5;
@@ -337,6 +344,8 @@ var AudioManager = class {
     this.lastAudioCtxCurrentTime = 0;
     // Necessary because audioCtx.currentTime doesn't reset to 0 on seek
     this.audioLengthMs = 0;
+    this.endEventTimeout = null;
+    this._isPaused = true;
     const ctx = getSharedAudioContext();
     if (!ctx) {
       throw new Error("AudioContext is not supported in this environment");
@@ -347,10 +356,15 @@ var AudioManager = class {
   /**
    * @param audioFiles The `Uint8Array[]` of the audio files to be played.
    * @param startDelayMs The amount of time to delay the start of the audio. (can be negative)
+   * @param fallbackAudioLengthMs The fallback audio length to use if no audio files are provided.
    */
-  static async create(audioFiles, startDelayMs) {
-    const audioManager = new AudioManager(audioFiles, startDelayMs);
-    await audioManager.initAudio();
+  static async create(audioFiles, startDelayMs, fallbackAudioLengthMs) {
+    const audioManager = new AudioManager(
+      audioFiles,
+      startDelayMs,
+      fallbackAudioLengthMs
+    );
+    await audioManager.decodeAudioFiles();
     return audioManager;
   }
   /**
@@ -374,44 +388,75 @@ var AudioManager = class {
   }
   /** Nonnegative number of milliseconds representing time elapsed since the chart preview start. */
   get chartCurrentTimeMs() {
-    const isPaused = this.audioCtx.state === "suspended";
+    if (this._isPaused) {
+      return this.lastSeekChartTimeMs;
+    }
     const audioLatency = (this.audioCtx.baseLatency + (this.audioCtx.outputLatency || 0)) * 1e3;
     const audioTimeSinceLastSeekMs = (this.audioCtx.currentTime - this.lastAudioCtxCurrentTime) * 1e3;
-    return this.lastSeekChartTimeMs + audioTimeSinceLastSeekMs - (isPaused ? 0 : audioLatency);
+    return this.lastSeekChartTimeMs + audioTimeSinceLastSeekMs - audioLatency;
   }
   /** Nonnegative number of milliseconds representing when the audio ends (and when the chart preview ends). */
   get chartEndTimeMs() {
-    return Math.max(this.startDelayMs + this.audioLengthMs, 0);
+    const theoreticalEndTime = this.startDelayMs + this.audioLengthMs;
+    return Math.max(
+      theoreticalEndTime,
+      this.audioLengthMs,
+      this.fallbackAudioLengthMs,
+      0
+    );
   }
   async play() {
-    if (this.gainNode === null) {
-      await this.initAudio();
-    }
     if (this.audioCtx.state === "suspended") {
       await this.audioCtx.resume();
     }
+    this.startAudioSources();
+    this._isPaused = false;
+    if (this.audioBuffers.length === 0 && !this.endEventTimeout) {
+      const remainingMs = this.chartEndTimeMs - this.chartCurrentTimeMs;
+      if (remainingMs > 0) {
+        this.endEventTimeout = setTimeout(() => {
+          this.eventEmitter.emit("end");
+        }, remainingMs);
+      }
+    }
   }
   async pause() {
-    if (this.audioCtx.state === "running") {
-      await this.audioCtx.suspend();
+    const currentTime = this.chartCurrentTimeMs;
+    this._isPaused = true;
+    this.lastSeekChartTimeMs = currentTime;
+    this.lastAudioCtxCurrentTime = this.audioCtx.currentTime;
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
     }
+    this.stopAudioSources();
   }
   closeAudio() {
     this.eventEmitter.removeAllListeners();
-    for (const source of this.audioSources) {
-      source.onended = null;
-      try {
-        source.stop();
-        source.disconnect();
-      } catch {
-      }
+    this._isPaused = true;
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
     }
-    this.audioSources = [];
-    this.gainNode?.disconnect();
-    this.gainNode = null;
+    this.stopAudioSources();
     unregisterInstance();
   }
-  async initAudio() {
+  /**
+   * Decodes audio files into AudioBuffers. Called once during initialization.
+   */
+  async decodeAudioFiles() {
+    this.audioBuffers = await Promise.all(
+      this.audioFiles.map(
+        (file) => this.audioCtx.decodeAudioData(file.slice(0).buffer)
+      )
+    );
+    const calculatedLengthMs = this.audioBuffers.length > 0 ? Math.max(...this.audioBuffers.map((b) => b.duration)) * 1e3 : 0;
+    this.audioLengthMs = calculatedLengthMs > 0 ? calculatedLengthMs : this.fallbackAudioLengthMs;
+  }
+  /**
+   * Stops all currently playing audio sources for this instance.
+   */
+  stopAudioSources() {
     for (const source of this.audioSources) {
       source.onended = null;
       try {
@@ -421,24 +466,37 @@ var AudioManager = class {
       }
     }
     this.audioSources = [];
-    const audioBuffers = await Promise.all(
-      // Must be recreated on each seek because seek is not supported by the Web Audio API
-      this.audioFiles.map(
-        (file) => this.audioCtx.decodeAudioData(file.slice(0).buffer)
-      )
-    );
-    this.audioLengthMs = Math.max(...audioBuffers.map((b) => b.duration)) * 1e3;
+    this.gainNode?.disconnect();
+    this.gainNode = null;
+  }
+  /**
+   * Creates and starts audio sources from the current playback position.
+   */
+  startAudioSources() {
+    this.stopAudioSources();
     this.gainNode = this.audioCtx.createGain();
     this.gainNode.gain.value = this._volume;
     this.gainNode.connect(this.audioCtx.destination);
     let endedCount = 0;
     const audioStartOffsetSeconds = (this.lastSeekChartTimeMs - this.startDelayMs) / 1e3;
-    for (const audioBuffer of audioBuffers) {
+    if (this.audioBuffers.length === 0) {
+      if (this.endEventTimeout) {
+        clearTimeout(this.endEventTimeout);
+        this.endEventTimeout = null;
+      }
+      const remainingMs = this.chartEndTimeMs - this.lastSeekChartTimeMs;
+      if (remainingMs > 0) {
+        this.endEventTimeout = setTimeout(() => {
+          this.eventEmitter.emit("end");
+        }, remainingMs);
+      }
+    }
+    for (const audioBuffer of this.audioBuffers) {
       const source = this.audioCtx.createBufferSource();
       source.buffer = audioBuffer;
       source.onended = () => {
         endedCount++;
-        if (endedCount === audioBuffers.length) {
+        if (endedCount === this.audioBuffers.length && !this._isPaused) {
           this.eventEmitter.emit("end");
         }
       };
@@ -450,29 +508,20 @@ var AudioManager = class {
       this.audioSources.push(source);
     }
     this.lastAudioCtxCurrentTime = this.audioCtx.currentTime;
-    this.pause();
   }
   /**
    * @param percentComplete The progress between the start and end of the preview.
    */
   async seek(percentComplete) {
-    if (this.audioCtx.state === "running") {
-      await this.audioCtx.suspend();
-    }
-    for (const source of this.audioSources) {
-      source.onended = null;
-      try {
-        source.stop();
-        source.disconnect();
-      } catch {
-      }
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
     }
-    this.audioSources = [];
-    this.gainNode?.disconnect();
-    this.gainNode = null;
+    this.stopAudioSources();
     const chartSeekTimeMs = percentComplete * this.chartEndTimeMs;
     this.lastSeekChartTimeMs = chartSeekTimeMs;
     this.lastAudioCtxCurrentTime = this.audioCtx.currentTime;
+    this._isPaused = true;
   }
 };
 var SilentAudioManager = class {
@@ -517,7 +566,8 @@ var SilentAudioManager = class {
   }
   /** Nonnegative number of milliseconds representing when the audio ends (and when the chart preview ends). */
   get chartEndTimeMs() {
-    return Math.max(this.startDelayMs + this.audioLengthMs, 0);
+    const theoreticalEndTime = this.startDelayMs + this.audioLengthMs;
+    return Math.max(theoreticalEndTime, this.audioLengthMs, 0);
   }
   async play() {
     if (this.lastResumeChartTimeMs >= this.chartEndTimeMs - 2) {
@@ -1218,7 +1268,6 @@ var STYLES = `
 	--accent-color: #3b82f6;
 	--text-color: #e0e0e0;
 	--text-muted: #aaa;
-	--text-idle: #666;
 	--error-color: #ef4444;
 	--shadow-color: rgba(0, 0, 0, 0.3);
 
@@ -1290,8 +1339,8 @@ var STYLES = `
 	align-items: center;
 	justify-content: center;
 	height: 40px;
-	width: 38px;
-	padding: 8px;
+	width: 32px;
+	padding: 6px;
 	transition: background 0.15s;
 	flex-shrink: 0;
 }
@@ -1376,10 +1425,10 @@ var STYLES = `
 .timestamp {
 	color: var(--text-muted);
 	font-size: 12px;
-	padding: 0 8px;
+	padding: 0 2px;
 	white-space: nowrap;
 	flex-shrink: 0;
-	min-width: 85px;
+	min-width: 70px;
 	text-align: center;
 }
 
@@ -1387,7 +1436,7 @@ var STYLES = `
 	flex: 1;
 	display: flex;
 	align-items: center;
-	padding: 0 8px;
+	padding: 0 4px;
 	min-width: 0;
 }
 
@@ -1429,11 +1478,6 @@ var STYLES = `
 	cursor: not-allowed;
 }
 
-.idle-message {
-	color: var(--text-idle);
-	font-size: 14px;
-}
-
 .error-message {
 	color: var(--error-color);
 	font-size: 14px;
@@ -1538,7 +1582,6 @@ var ChartPreviewPlayer = class extends HTMLElement {
 			<style>${STYLES}</style>
 			<div class="player-container">
 				<div class="preview-viewport">
-					<span class="idle-message">Click play to start</span>
 				</div>
 				<div class="controls">
 					<button class="control-btn play-btn" aria-label="Play" disabled>
@@ -1656,9 +1699,6 @@ var ChartPreviewPlayer = class extends HTMLElement {
    */
   prepareForLoading() {
     this.setState("loading");
-    const idleMessage = this.viewport.querySelector(".idle-message");
-    if (idleMessage)
-      idleMessage.remove();
     const errorMessage = this.viewport.querySelector(".error-message");
     if (errorMessage)
       errorMessage.remove();
@@ -1701,7 +1741,7 @@ var ChartPreviewPlayer = class extends HTMLElement {
   updatePlayButton() {
     switch (this._state) {
       case "idle":
-        this.playBtn.disabled = true;
+        this.playBtn.disabled = false;
         this.playBtn.innerHTML = ICONS.play;
         this.playBtn.setAttribute("aria-label", "Play");
         break;

package/dist/index.mjs

@@ -109,7 +109,11 @@ var _ChartPreview = class {
     chartPreview.progressIntervalMs = config.progressIntervalMs ?? DEFAULT_PROGRESS_INTERVAL_MS;
     chartPreview.camera = new ChartCamera(config.container);
     chartPreview.renderer = new ChartRenderer(config.container);
-    chartPreview.audioManager = await (isAudioContextSupported() ? AudioManager.create(config.audioFiles, config.startDelayMs) : SilentAudioManager.create(config.startDelayMs, config.audioLengthMs));
+    chartPreview.audioManager = await (isAudioContextSupported() ? AudioManager.create(
+      config.audioFiles,
+      config.startDelayMs,
+      config.audioLengthMs
+    ) : SilentAudioManager.create(config.startDelayMs, config.audioLengthMs));
     chartPreview.audioManager.on(
       "end",
       () => chartPreview.eventEmitter.emit("end")
@@ -287,10 +291,13 @@ var ChartRenderer = class extends THREE.WebGLRenderer {
   }
 };
 var AudioManager = class {
-  constructor(audioFiles, startDelayMs) {
+  // Track paused state independently since we share the AudioContext
+  constructor(audioFiles, startDelayMs, fallbackAudioLengthMs) {
     this.audioFiles = audioFiles;
     this.startDelayMs = startDelayMs;
+    this.fallbackAudioLengthMs = fallbackAudioLengthMs;
     this.eventEmitter = new EventEmitter();
+    this.audioBuffers = [];
     this.gainNode = null;
     this.audioSources = [];
     this._volume = 0.5;
@@ -298,6 +305,8 @@ var AudioManager = class {
     this.lastAudioCtxCurrentTime = 0;
     // Necessary because audioCtx.currentTime doesn't reset to 0 on seek
     this.audioLengthMs = 0;
+    this.endEventTimeout = null;
+    this._isPaused = true;
     const ctx = getSharedAudioContext();
     if (!ctx) {
       throw new Error("AudioContext is not supported in this environment");
@@ -308,10 +317,15 @@ var AudioManager = class {
   /**
    * @param audioFiles The `Uint8Array[]` of the audio files to be played.
    * @param startDelayMs The amount of time to delay the start of the audio. (can be negative)
+   * @param fallbackAudioLengthMs The fallback audio length to use if no audio files are provided.
    */
-  static async create(audioFiles, startDelayMs) {
-    const audioManager = new AudioManager(audioFiles, startDelayMs);
-    await audioManager.initAudio();
+  static async create(audioFiles, startDelayMs, fallbackAudioLengthMs) {
+    const audioManager = new AudioManager(
+      audioFiles,
+      startDelayMs,
+      fallbackAudioLengthMs
+    );
+    await audioManager.decodeAudioFiles();
     return audioManager;
   }
   /**
@@ -335,44 +349,75 @@ var AudioManager = class {
   }
   /** Nonnegative number of milliseconds representing time elapsed since the chart preview start. */
   get chartCurrentTimeMs() {
-    const isPaused = this.audioCtx.state === "suspended";
+    if (this._isPaused) {
+      return this.lastSeekChartTimeMs;
+    }
     const audioLatency = (this.audioCtx.baseLatency + (this.audioCtx.outputLatency || 0)) * 1e3;
     const audioTimeSinceLastSeekMs = (this.audioCtx.currentTime - this.lastAudioCtxCurrentTime) * 1e3;
-    return this.lastSeekChartTimeMs + audioTimeSinceLastSeekMs - (isPaused ? 0 : audioLatency);
+    return this.lastSeekChartTimeMs + audioTimeSinceLastSeekMs - audioLatency;
   }
   /** Nonnegative number of milliseconds representing when the audio ends (and when the chart preview ends). */
   get chartEndTimeMs() {
-    return Math.max(this.startDelayMs + this.audioLengthMs, 0);
+    const theoreticalEndTime = this.startDelayMs + this.audioLengthMs;
+    return Math.max(
+      theoreticalEndTime,
+      this.audioLengthMs,
+      this.fallbackAudioLengthMs,
+      0
+    );
   }
   async play() {
-    if (this.gainNode === null) {
-      await this.initAudio();
-    }
     if (this.audioCtx.state === "suspended") {
       await this.audioCtx.resume();
     }
+    this.startAudioSources();
+    this._isPaused = false;
+    if (this.audioBuffers.length === 0 && !this.endEventTimeout) {
+      const remainingMs = this.chartEndTimeMs - this.chartCurrentTimeMs;
+      if (remainingMs > 0) {
+        this.endEventTimeout = setTimeout(() => {
+          this.eventEmitter.emit("end");
+        }, remainingMs);
+      }
+    }
   }
   async pause() {
-    if (this.audioCtx.state === "running") {
-      await this.audioCtx.suspend();
+    const currentTime = this.chartCurrentTimeMs;
+    this._isPaused = true;
+    this.lastSeekChartTimeMs = currentTime;
+    this.lastAudioCtxCurrentTime = this.audioCtx.currentTime;
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
     }
+    this.stopAudioSources();
   }
   closeAudio() {
     this.eventEmitter.removeAllListeners();
-    for (const source of this.audioSources) {
-      source.onended = null;
-      try {
-        source.stop();
-        source.disconnect();
-      } catch {
-      }
+    this._isPaused = true;
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
     }
-    this.audioSources = [];
-    this.gainNode?.disconnect();
-    this.gainNode = null;
+    this.stopAudioSources();
     unregisterInstance();
   }
-  async initAudio() {
+  /**
+   * Decodes audio files into AudioBuffers. Called once during initialization.
+   */
+  async decodeAudioFiles() {
+    this.audioBuffers = await Promise.all(
+      this.audioFiles.map(
+        (file) => this.audioCtx.decodeAudioData(file.slice(0).buffer)
+      )
+    );
+    const calculatedLengthMs = this.audioBuffers.length > 0 ? Math.max(...this.audioBuffers.map((b) => b.duration)) * 1e3 : 0;
+    this.audioLengthMs = calculatedLengthMs > 0 ? calculatedLengthMs : this.fallbackAudioLengthMs;
+  }
+  /**
+   * Stops all currently playing audio sources for this instance.
+   */
+  stopAudioSources() {
     for (const source of this.audioSources) {
       source.onended = null;
       try {
@@ -382,24 +427,37 @@ var AudioManager = class {
       }
     }
     this.audioSources = [];
-    const audioBuffers = await Promise.all(
-      // Must be recreated on each seek because seek is not supported by the Web Audio API
-      this.audioFiles.map(
-        (file) => this.audioCtx.decodeAudioData(file.slice(0).buffer)
-      )
-    );
-    this.audioLengthMs = Math.max(...audioBuffers.map((b) => b.duration)) * 1e3;
+    this.gainNode?.disconnect();
+    this.gainNode = null;
+  }
+  /**
+   * Creates and starts audio sources from the current playback position.
+   */
+  startAudioSources() {
+    this.stopAudioSources();
     this.gainNode = this.audioCtx.createGain();
     this.gainNode.gain.value = this._volume;
     this.gainNode.connect(this.audioCtx.destination);
     let endedCount = 0;
     const audioStartOffsetSeconds = (this.lastSeekChartTimeMs - this.startDelayMs) / 1e3;
-    for (const audioBuffer of audioBuffers) {
+    if (this.audioBuffers.length === 0) {
+      if (this.endEventTimeout) {
+        clearTimeout(this.endEventTimeout);
+        this.endEventTimeout = null;
+      }
+      const remainingMs = this.chartEndTimeMs - this.lastSeekChartTimeMs;
+      if (remainingMs > 0) {
+        this.endEventTimeout = setTimeout(() => {
+          this.eventEmitter.emit("end");
+        }, remainingMs);
+      }
+    }
+    for (const audioBuffer of this.audioBuffers) {
       const source = this.audioCtx.createBufferSource();
       source.buffer = audioBuffer;
       source.onended = () => {
         endedCount++;
-        if (endedCount === audioBuffers.length) {
+        if (endedCount === this.audioBuffers.length && !this._isPaused) {
           this.eventEmitter.emit("end");
         }
       };
@@ -411,29 +469,20 @@ var AudioManager = class {
       this.audioSources.push(source);
     }
     this.lastAudioCtxCurrentTime = this.audioCtx.currentTime;
-    this.pause();
   }
   /**
    * @param percentComplete The progress between the start and end of the preview.
    */
   async seek(percentComplete) {
-    if (this.audioCtx.state === "running") {
-      await this.audioCtx.suspend();
-    }
-    for (const source of this.audioSources) {
-      source.onended = null;
-      try {
-        source.stop();
-        source.disconnect();
-      } catch {
-      }
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
     }
-    this.audioSources = [];
-    this.gainNode?.disconnect();
-    this.gainNode = null;
+    this.stopAudioSources();
     const chartSeekTimeMs = percentComplete * this.chartEndTimeMs;
     this.lastSeekChartTimeMs = chartSeekTimeMs;
     this.lastAudioCtxCurrentTime = this.audioCtx.currentTime;
+    this._isPaused = true;
   }
 };
 var SilentAudioManager = class {
@@ -478,7 +527,8 @@ var SilentAudioManager = class {
   }
   /** Nonnegative number of milliseconds representing when the audio ends (and when the chart preview ends). */
   get chartEndTimeMs() {
-    return Math.max(this.startDelayMs + this.audioLengthMs, 0);
+    const theoreticalEndTime = this.startDelayMs + this.audioLengthMs;
+    return Math.max(theoreticalEndTime, this.audioLengthMs, 0);
   }
   async play() {
     if (this.lastResumeChartTimeMs >= this.chartEndTimeMs - 2) {
@@ -1183,7 +1233,6 @@ var STYLES = `
 	--accent-color: #3b82f6;
 	--text-color: #e0e0e0;
 	--text-muted: #aaa;
-	--text-idle: #666;
 	--error-color: #ef4444;
 	--shadow-color: rgba(0, 0, 0, 0.3);
 
@@ -1255,8 +1304,8 @@ var STYLES = `
 	align-items: center;
 	justify-content: center;
 	height: 40px;
-	width: 38px;
-	padding: 8px;
+	width: 32px;
+	padding: 6px;
 	transition: background 0.15s;
 	flex-shrink: 0;
 }
@@ -1341,10 +1390,10 @@ var STYLES = `
 .timestamp {
 	color: var(--text-muted);
 	font-size: 12px;
-	padding: 0 8px;
+	padding: 0 2px;
 	white-space: nowrap;
 	flex-shrink: 0;
-	min-width: 85px;
+	min-width: 70px;
 	text-align: center;
 }
 
@@ -1352,7 +1401,7 @@ var STYLES = `
 	flex: 1;
 	display: flex;
 	align-items: center;
-	padding: 0 8px;
+	padding: 0 4px;
 	min-width: 0;
 }
 
@@ -1394,11 +1443,6 @@ var STYLES = `
 	cursor: not-allowed;
 }
 
-.idle-message {
-	color: var(--text-idle);
-	font-size: 14px;
-}
-
 .error-message {
 	color: var(--error-color);
 	font-size: 14px;
@@ -1503,7 +1547,6 @@ var ChartPreviewPlayer = class extends HTMLElement {
 			<style>${STYLES}</style>
 			<div class="player-container">
 				<div class="preview-viewport">
-					<span class="idle-message">Click play to start</span>
 				</div>
 				<div class="controls">
 					<button class="control-btn play-btn" aria-label="Play" disabled>
@@ -1621,9 +1664,6 @@ var ChartPreviewPlayer = class extends HTMLElement {
    */
   prepareForLoading() {
     this.setState("loading");
-    const idleMessage = this.viewport.querySelector(".idle-message");
-    if (idleMessage)
-      idleMessage.remove();
     const errorMessage = this.viewport.querySelector(".error-message");
     if (errorMessage)
       errorMessage.remove();
@@ -1666,7 +1706,7 @@ var ChartPreviewPlayer = class extends HTMLElement {
   updatePlayButton() {
     switch (this._state) {
       case "idle":
-        this.playBtn.disabled = true;
+        this.playBtn.disabled = false;
         this.playBtn.innerHTML = ICONS.play;
         this.playBtn.setAttribute("aria-label", "Play");
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "chart-preview",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"author": "Geo",
 	"license": "MIT",
 	"main": "dist/index.js",

package/src/ChartPreview.ts

@@ -167,7 +167,11 @@ export class ChartPreview {
     chartPreview.camera = new ChartCamera(config.container);
     chartPreview.renderer = new ChartRenderer(config.container);
     chartPreview.audioManager = await (isAudioContextSupported()
-      ? AudioManager.create(config.audioFiles, config.startDelayMs)
+      ? AudioManager.create(
+          config.audioFiles,
+          config.startDelayMs,
+          config.audioLengthMs
+        )
       : SilentAudioManager.create(config.startDelayMs, config.audioLengthMs));
     chartPreview.audioManager.on("end", () =>
       chartPreview.eventEmitter.emit("end")
@@ -383,16 +387,20 @@ class AudioManager {
   private eventEmitter = new EventEmitter();
 
   private audioCtx: AudioContext;
+  private audioBuffers: AudioBuffer[] = [];
   private gainNode: GainNode | null = null;
   private audioSources: AudioBufferSourceNode[] = [];
   private _volume = 0.5;
   private lastSeekChartTimeMs = 0;
   private lastAudioCtxCurrentTime = 0; // Necessary because audioCtx.currentTime doesn't reset to 0 on seek
   private audioLengthMs: number = 0;
+  private endEventTimeout: ReturnType<typeof setTimeout> | null = null;
+  private _isPaused = true; // Track paused state independently since we share the AudioContext
 
   private constructor(
     private audioFiles: Uint8Array[],
-    private startDelayMs: number
+    private startDelayMs: number,
+    private fallbackAudioLengthMs: number
   ) {
     const ctx = getSharedAudioContext();
     if (!ctx) {
@@ -405,10 +413,19 @@ class AudioManager {
   /**
    * @param audioFiles The `Uint8Array[]` of the audio files to be played.
    * @param startDelayMs The amount of time to delay the start of the audio. (can be negative)
+   * @param fallbackAudioLengthMs The fallback audio length to use if no audio files are provided.
    */
-  static async create(audioFiles: Uint8Array[], startDelayMs: number) {
-    const audioManager = new AudioManager(audioFiles, startDelayMs);
-    await audioManager.initAudio();
+  static async create(
+    audioFiles: Uint8Array[],
+    startDelayMs: number,
+    fallbackAudioLengthMs: number
+  ) {
+    const audioManager = new AudioManager(
+      audioFiles,
+      startDelayMs,
+      fallbackAudioLengthMs
+    );
+    await audioManager.decodeAudioFiles();
     return audioManager;
   }
 
@@ -438,68 +455,111 @@ class AudioManager {
 
   /** Nonnegative number of milliseconds representing time elapsed since the chart preview start. */
   get chartCurrentTimeMs() {
-    const isPaused = this.audioCtx.state === "suspended";
+    // Use our own paused state since we share the AudioContext with other instances
+    // and can't rely on audioCtx.state to determine this instance's state
+    if (this._isPaused) {
+      return this.lastSeekChartTimeMs;
+    }
     // outputLatency is not implemented in safari
     const audioLatency =
       (this.audioCtx.baseLatency + (this.audioCtx.outputLatency || 0)) * 1000;
     const audioTimeSinceLastSeekMs =
       (this.audioCtx.currentTime - this.lastAudioCtxCurrentTime) * 1000;
-    // Note: when paused, the queued audio during the latency period is skipped and never heard.
-    // The solution here is to represent that visually by jumping ahead slightly by ignoring latency when paused.
-    // If this is a more significant problem, it can be fixed by seeking backward by `audioLatency`.
-    return (
-      this.lastSeekChartTimeMs +
-      audioTimeSinceLastSeekMs -
-      (isPaused ? 0 : audioLatency)
-    );
+    return this.lastSeekChartTimeMs + audioTimeSinceLastSeekMs - audioLatency;
   }
 
   /** Nonnegative number of milliseconds representing when the audio ends (and when the chart preview ends). */
   get chartEndTimeMs() {
-    return Math.max(this.startDelayMs + this.audioLengthMs, 0);
+    // Calculate the theoretical end time based on start delay + audio length
+    const theoreticalEndTime = this.startDelayMs + this.audioLengthMs;
+    // Ensure we always have a positive end time - use audio length as minimum if startDelay is extremely negative
+    // This handles edge cases where chart metadata has invalid/extreme delay values
+    return Math.max(
+      theoreticalEndTime,
+      this.audioLengthMs,
+      this.fallbackAudioLengthMs,
+      0
+    );
   }
 
   async play() {
-    // Reinitialize audio if needed (e.g., after seeking)
-    if (this.gainNode === null) {
-      await this.initAudio();
-    }
-    // Resume context if suspended
+    // Resume the shared context if suspended (needed for initial user interaction)
     if (this.audioCtx.state === "suspended") {
       await this.audioCtx.resume();
     }
+
+    // Start audio playback
+    this.startAudioSources();
+    this._isPaused = false;
+
+    // Start end event timeout for charts without audio
+    if (this.audioBuffers.length === 0 && !this.endEventTimeout) {
+      const remainingMs = this.chartEndTimeMs - this.chartCurrentTimeMs;
+      if (remainingMs > 0) {
+        this.endEventTimeout = setTimeout(() => {
+          this.eventEmitter.emit("end");
+        }, remainingMs);
+      }
+    }
   }
+
   async pause() {
-    if (this.audioCtx.state === "running") {
-      await this.audioCtx.suspend();
+    // Record current playback position before stopping
+    const currentTime = this.chartCurrentTimeMs;
+    this._isPaused = true;
+    this.lastSeekChartTimeMs = currentTime;
+    this.lastAudioCtxCurrentTime = this.audioCtx.currentTime;
+
+    // Clear end event timeout when pausing
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
     }
+
+    // Stop all audio sources for this instance only
+    // (Don't suspend the shared AudioContext - other instances may be playing)
+    this.stopAudioSources();
   }
 
   closeAudio() {
     this.eventEmitter.removeAllListeners();
-    // Stop all audio sources
-    for (const source of this.audioSources) {
-      // Remove onended handler before stopping to prevent false "end" events
-      source.onended = null;
-      try {
-        source.stop();
-        source.disconnect();
-      } catch {
-        // Source may already be stopped
-      }
+    this._isPaused = true;
+    // Clear end event timeout
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
     }
-    this.audioSources = [];
-    this.gainNode?.disconnect();
-    this.gainNode = null;
+    // Stop all audio sources
+    this.stopAudioSources();
     // Don't close the shared context - just unregister this instance
     unregisterInstance();
   }
 
-  async initAudio() {
-    // Stop any existing sources before creating new ones
+  /**
+   * Decodes audio files into AudioBuffers. Called once during initialization.
+   */
+  private async decodeAudioFiles() {
+    this.audioBuffers = await Promise.all(
+      this.audioFiles.map((file) =>
+        this.audioCtx.decodeAudioData(file.slice(0).buffer)
+      )
+    );
+
+    // Use fallback if no audio files or if calculated duration is invalid
+    const calculatedLengthMs =
+      this.audioBuffers.length > 0
+        ? Math.max(...this.audioBuffers.map((b) => b.duration)) * 1000
+        : 0;
+    this.audioLengthMs =
+      calculatedLengthMs > 0 ? calculatedLengthMs : this.fallbackAudioLengthMs;
+  }
+
+  /**
+   * Stops all currently playing audio sources for this instance.
+   */
+  private stopAudioSources() {
     for (const source of this.audioSources) {
-      // Remove onended handler before stopping to prevent false "end" events
-      source.onended = null;
+      source.onended = null; // Prevent false "end" events
       try {
         source.stop();
         source.disconnect();
@@ -508,15 +568,16 @@ class AudioManager {
       }
     }
     this.audioSources = [];
+    this.gainNode?.disconnect();
+    this.gainNode = null;
+  }
 
-    const audioBuffers = await Promise.all(
-      // Must be recreated on each seek because seek is not supported by the Web Audio API
-      this.audioFiles.map((file) =>
-        this.audioCtx.decodeAudioData(file.slice(0).buffer)
-      )
-    );
-    this.audioLengthMs =
-      Math.max(...audioBuffers.map((b) => b.duration)) * 1000;
+  /**
+   * Creates and starts audio sources from the current playback position.
+   */
+  private startAudioSources() {
+    // Stop any existing sources before creating new ones
+    this.stopAudioSources();
 
     this.gainNode = this.audioCtx.createGain();
     this.gainNode.gain.value = this._volume;
@@ -525,18 +586,39 @@ class AudioManager {
     let endedCount = 0;
     const audioStartOffsetSeconds =
       (this.lastSeekChartTimeMs - this.startDelayMs) / 1000;
-    for (const audioBuffer of audioBuffers) {
+
+    // If no audio files, use a timeout to emit "end" event
+    if (this.audioBuffers.length === 0) {
+      // Clear any existing timeout
+      if (this.endEventTimeout) {
+        clearTimeout(this.endEventTimeout);
+        this.endEventTimeout = null;
+      }
+      // Schedule end event based on remaining time
+      const remainingMs = this.chartEndTimeMs - this.lastSeekChartTimeMs;
+      if (remainingMs > 0) {
+        this.endEventTimeout = setTimeout(() => {
+          this.eventEmitter.emit("end");
+        }, remainingMs);
+      }
+    }
+
+    for (const audioBuffer of this.audioBuffers) {
       const source = this.audioCtx.createBufferSource();
       source.buffer = audioBuffer;
       source.onended = () => {
         endedCount++;
-        if (endedCount === audioBuffers.length) {
+        if (endedCount === this.audioBuffers.length && !this._isPaused) {
           this.eventEmitter.emit("end");
         }
       };
       source.connect(this.gainNode!);
       // When using a shared AudioContext, we need to schedule relative to the current time,
       // not absolute time 0, since the context may have been running for a while
+      //
+      // audioStartOffsetSeconds calculation:
+      // - Positive value: Start audio from this position (audio is "behind" chart time)
+      // - Negative value: Delay audio start by |value| seconds (audio hasn't started yet at chart time 0)
       const delaySeconds = Math.abs(Math.min(audioStartOffsetSeconds, 0));
       const when = this.audioCtx.currentTime + delaySeconds;
       const offset = Math.max(audioStartOffsetSeconds, 0);
@@ -544,36 +626,25 @@ class AudioManager {
       this.audioSources.push(source);
     }
     this.lastAudioCtxCurrentTime = this.audioCtx.currentTime;
-    this.pause();
   }
 
   /**
    * @param percentComplete The progress between the start and end of the preview.
    */
   async seek(percentComplete: number) {
-    // Suspend context first to prevent time drift during seek
-    // (chartCurrentTimeMs is calculated from audioCtx.currentTime)
-    if (this.audioCtx.state === "running") {
-      await this.audioCtx.suspend();
+    // Clear end event timeout when seeking
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
     }
 
     // Stop existing audio sources
-    for (const source of this.audioSources) {
-      // Remove onended handler before stopping to prevent false "end" events
-      source.onended = null;
-      try {
-        source.stop();
-        source.disconnect();
-      } catch {
-        // Source may already be stopped
-      }
-    }
-    this.audioSources = [];
-    this.gainNode?.disconnect();
-    this.gainNode = null;
+    this.stopAudioSources();
+
     const chartSeekTimeMs = percentComplete * this.chartEndTimeMs;
     this.lastSeekChartTimeMs = chartSeekTimeMs;
     this.lastAudioCtxCurrentTime = this.audioCtx.currentTime;
+    this._isPaused = true;
   }
 }
 
@@ -635,7 +706,10 @@ class SilentAudioManager {
   }
   /** Nonnegative number of milliseconds representing when the audio ends (and when the chart preview ends). */
   get chartEndTimeMs() {
-    return Math.max(this.startDelayMs + this.audioLengthMs, 0);
+    // Calculate the theoretical end time based on start delay + audio length
+    const theoreticalEndTime = this.startDelayMs + this.audioLengthMs;
+    // Ensure we always have a positive end time - use audio length as minimum if startDelay is extremely negative
+    return Math.max(theoreticalEndTime, this.audioLengthMs, 0);
   }
 
   async play() {

package/src/ChartPreviewPlayer.ts

@@ -57,7 +57,6 @@ const STYLES = `
 	--accent-color: #3b82f6;
 	--text-color: #e0e0e0;
 	--text-muted: #aaa;
-	--text-idle: #666;
 	--error-color: #ef4444;
 	--shadow-color: rgba(0, 0, 0, 0.3);
 
@@ -129,8 +128,8 @@ const STYLES = `
 	align-items: center;
 	justify-content: center;
 	height: 40px;
-	width: 38px;
-	padding: 8px;
+	width: 32px;
+	padding: 6px;
 	transition: background 0.15s;
 	flex-shrink: 0;
 }
@@ -215,10 +214,10 @@ const STYLES = `
 .timestamp {
 	color: var(--text-muted);
 	font-size: 12px;
-	padding: 0 8px;
+	padding: 0 2px;
 	white-space: nowrap;
 	flex-shrink: 0;
-	min-width: 85px;
+	min-width: 70px;
 	text-align: center;
 }
 
@@ -226,7 +225,7 @@ const STYLES = `
 	flex: 1;
 	display: flex;
 	align-items: center;
-	padding: 0 8px;
+	padding: 0 4px;
 	min-width: 0;
 }
 
@@ -268,11 +267,6 @@ const STYLES = `
 	cursor: not-allowed;
 }
 
-.idle-message {
-	color: var(--text-idle);
-	font-size: 14px;
-}
-
 .error-message {
 	color: var(--error-color);
 	font-size: 14px;
@@ -379,7 +373,6 @@ export class ChartPreviewPlayer extends HTMLElement {
 			<style>${STYLES}</style>
 			<div class="player-container">
 				<div class="preview-viewport">
-					<span class="idle-message">Click play to start</span>
 				</div>
 				<div class="controls">
 					<button class="control-btn play-btn" aria-label="Play" disabled>
@@ -587,10 +580,6 @@ export class ChartPreviewPlayer extends HTMLElement {
   private prepareForLoading(): void {
     this.setState("loading");
 
-    // Remove idle message
-    const idleMessage = this.viewport.querySelector(".idle-message");
-    if (idleMessage) idleMessage.remove();
-
     // Remove error message if present
     const errorMessage = this.viewport.querySelector(".error-message");
     if (errorMessage) errorMessage.remove();
@@ -644,7 +633,7 @@ export class ChartPreviewPlayer extends HTMLElement {
   private updatePlayButton() {
     switch (this._state) {
       case "idle":
-        this.playBtn.disabled = true;
+        this.playBtn.disabled = false;
         this.playBtn.innerHTML = ICONS.play;
         this.playBtn.setAttribute("aria-label", "Play");
         break;