chart-preview 1.0.0 → 1.0.1

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,7 @@
+# chart-preview
+
+## 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,9 +330,10 @@ var ChartRenderer = class extends THREE.WebGLRenderer {
   }
 };
 var AudioManager = class {
-  constructor(audioFiles, startDelayMs) {
+  constructor(audioFiles, startDelayMs, fallbackAudioLengthMs) {
     this.audioFiles = audioFiles;
     this.startDelayMs = startDelayMs;
+    this.fallbackAudioLengthMs = fallbackAudioLengthMs;
     this.eventEmitter = new import_eventemitter3.EventEmitter();
     this.gainNode = null;
     this.audioSources = [];
@@ -337,6 +342,7 @@ var AudioManager = class {
     this.lastAudioCtxCurrentTime = 0;
     // Necessary because audioCtx.currentTime doesn't reset to 0 on seek
     this.audioLengthMs = 0;
+    this.endEventTimeout = null;
     const ctx = getSharedAudioContext();
     if (!ctx) {
       throw new Error("AudioContext is not supported in this environment");
@@ -347,9 +353,14 @@ 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);
+  static async create(audioFiles, startDelayMs, fallbackAudioLengthMs) {
+    const audioManager = new AudioManager(
+      audioFiles,
+      startDelayMs,
+      fallbackAudioLengthMs
+    );
     await audioManager.initAudio();
     return audioManager;
   }
@@ -381,7 +392,13 @@ var AudioManager = 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,
+      this.fallbackAudioLengthMs,
+      0
+    );
   }
   async play() {
     if (this.gainNode === null) {
@@ -390,14 +407,30 @@ var AudioManager = class {
     if (this.audioCtx.state === "suspended") {
       await this.audioCtx.resume();
     }
+    if (this.audioSources.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();
     }
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
+    }
   }
   closeAudio() {
     this.eventEmitter.removeAllListeners();
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
+    }
     for (const source of this.audioSources) {
       source.onended = null;
       try {
@@ -427,12 +460,25 @@ var AudioManager = class {
         (file) => this.audioCtx.decodeAudioData(file.slice(0).buffer)
       )
     );
-    this.audioLengthMs = Math.max(...audioBuffers.map((b) => b.duration)) * 1e3;
+    const calculatedLengthMs = audioBuffers.length > 0 ? Math.max(...audioBuffers.map((b) => b.duration)) * 1e3 : 0;
+    this.audioLengthMs = calculatedLengthMs > 0 ? calculatedLengthMs : this.fallbackAudioLengthMs;
     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;
+    if (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 audioBuffers) {
       const source = this.audioCtx.createBufferSource();
       source.buffer = audioBuffer;
@@ -459,6 +505,10 @@ var AudioManager = class {
     if (this.audioCtx.state === "running") {
       await this.audioCtx.suspend();
     }
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
+    }
     for (const source of this.audioSources) {
       source.onended = null;
       try {
@@ -517,7 +567,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) {

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,9 +291,10 @@ var ChartRenderer = class extends THREE.WebGLRenderer {
   }
 };
 var AudioManager = class {
-  constructor(audioFiles, startDelayMs) {
+  constructor(audioFiles, startDelayMs, fallbackAudioLengthMs) {
     this.audioFiles = audioFiles;
     this.startDelayMs = startDelayMs;
+    this.fallbackAudioLengthMs = fallbackAudioLengthMs;
     this.eventEmitter = new EventEmitter();
     this.gainNode = null;
     this.audioSources = [];
@@ -298,6 +303,7 @@ var AudioManager = class {
     this.lastAudioCtxCurrentTime = 0;
     // Necessary because audioCtx.currentTime doesn't reset to 0 on seek
     this.audioLengthMs = 0;
+    this.endEventTimeout = null;
     const ctx = getSharedAudioContext();
     if (!ctx) {
       throw new Error("AudioContext is not supported in this environment");
@@ -308,9 +314,14 @@ 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);
+  static async create(audioFiles, startDelayMs, fallbackAudioLengthMs) {
+    const audioManager = new AudioManager(
+      audioFiles,
+      startDelayMs,
+      fallbackAudioLengthMs
+    );
     await audioManager.initAudio();
     return audioManager;
   }
@@ -342,7 +353,13 @@ var AudioManager = 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,
+      this.fallbackAudioLengthMs,
+      0
+    );
   }
   async play() {
     if (this.gainNode === null) {
@@ -351,14 +368,30 @@ var AudioManager = class {
     if (this.audioCtx.state === "suspended") {
       await this.audioCtx.resume();
     }
+    if (this.audioSources.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();
     }
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
+    }
   }
   closeAudio() {
     this.eventEmitter.removeAllListeners();
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
+    }
     for (const source of this.audioSources) {
       source.onended = null;
       try {
@@ -388,12 +421,25 @@ var AudioManager = class {
         (file) => this.audioCtx.decodeAudioData(file.slice(0).buffer)
       )
     );
-    this.audioLengthMs = Math.max(...audioBuffers.map((b) => b.duration)) * 1e3;
+    const calculatedLengthMs = audioBuffers.length > 0 ? Math.max(...audioBuffers.map((b) => b.duration)) * 1e3 : 0;
+    this.audioLengthMs = calculatedLengthMs > 0 ? calculatedLengthMs : this.fallbackAudioLengthMs;
     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;
+    if (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 audioBuffers) {
       const source = this.audioCtx.createBufferSource();
       source.buffer = audioBuffer;
@@ -420,6 +466,10 @@ var AudioManager = class {
     if (this.audioCtx.state === "running") {
       await this.audioCtx.suspend();
     }
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
+    }
     for (const source of this.audioSources) {
       source.onended = null;
       try {
@@ -478,7 +528,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "chart-preview",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"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")
@@ -389,10 +393,12 @@ class AudioManager {
   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 constructor(
     private audioFiles: Uint8Array[],
-    private startDelayMs: number
+    private startDelayMs: number,
+    private fallbackAudioLengthMs: number
   ) {
     const ctx = getSharedAudioContext();
     if (!ctx) {
@@ -405,9 +411,18 @@ 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);
+  static async create(
+    audioFiles: Uint8Array[],
+    startDelayMs: number,
+    fallbackAudioLengthMs: number
+  ) {
+    const audioManager = new AudioManager(
+      audioFiles,
+      startDelayMs,
+      fallbackAudioLengthMs
+    );
     await audioManager.initAudio();
     return audioManager;
   }
@@ -456,7 +471,16 @@ class AudioManager {
 
   /** 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() {
@@ -468,15 +492,34 @@ class AudioManager {
     if (this.audioCtx.state === "suspended") {
       await this.audioCtx.resume();
     }
+    // Restart end event timeout for charts without audio
+    if (this.audioSources.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();
     }
+    // Clear end event timeout when pausing
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
+    }
   }
 
   closeAudio() {
     this.eventEmitter.removeAllListeners();
+    // Clear end event timeout
+    if (this.endEventTimeout) {
+      clearTimeout(this.endEventTimeout);
+      this.endEventTimeout = null;
+    }
     // Stop all audio sources
     for (const source of this.audioSources) {
       // Remove onended handler before stopping to prevent false "end" events
@@ -515,8 +558,14 @@ class AudioManager {
         this.audioCtx.decodeAudioData(file.slice(0).buffer)
       )
     );
+
+    // Use fallback if no audio files or if calculated duration is invalid
+    const calculatedLengthMs =
+      audioBuffers.length > 0
+        ? Math.max(...audioBuffers.map((b) => b.duration)) * 1000
+        : 0;
     this.audioLengthMs =
-      Math.max(...audioBuffers.map((b) => b.duration)) * 1000;
+      calculatedLengthMs > 0 ? calculatedLengthMs : this.fallbackAudioLengthMs;
 
     this.gainNode = this.audioCtx.createGain();
     this.gainNode.gain.value = this._volume;
@@ -525,6 +574,23 @@ class AudioManager {
     let endedCount = 0;
     const audioStartOffsetSeconds =
       (this.lastSeekChartTimeMs - this.startDelayMs) / 1000;
+
+    // If no audio files, use a timeout to emit "end" event like SilentAudioManager does
+    if (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 audioBuffers) {
       const source = this.audioCtx.createBufferSource();
       source.buffer = audioBuffer;
@@ -537,6 +603,10 @@ class AudioManager {
       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);
@@ -557,6 +627,12 @@ class AudioManager {
       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
@@ -635,7 +711,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() {