waa-play 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ivgtr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# waa-play
+
+[![npm version](https://img.shields.io/npm/v/waa-play)](https://www.npmjs.com/package/waa-play)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+Composable Web Audio API utilities.
+
+BYO AudioContext / Zero Dependencies / Framework-agnostic / Sample-accurate / Pitch-preserving time-stretch / Chunk-based streaming
+
+**[Demo](https://ivgtr.github.io/waa/)**
+
+## Features
+
+再生からピッチ保持タイムストレッチまで、必要な機能を関数単位で組み合わせられる Web Audio ライブラリです。
+
+- **BYO AudioContext** — AudioContext を外から渡す設計で、他のライブラリとの共存が容易
+- **Composable** — モノリシックな Player クラスではなく、小さな関数を組み合わせて利用
+- **Zero Dependencies** — Web Audio API のみに依存、バンドルサイズを最小化
+- **Framework-agnostic** — React / Vue / Svelte / Vanilla JS のどれでも同じ API で動作
+- **TypeScript-first** — 完全な型定義により、エディタ補完で快適に開発
+- **Sample-accurate** — `AudioContext.currentTime` ベースの精密な再生位置追跡
+- **Tree-shakeable** — 使う関数だけがバンドルに含まれる
+- **Pitch-preserving time-stretch** — WSOLA アルゴリズムによるテンポ変更を Web Worker で処理
+- **Chunk-based streaming** — 音声をチャンク分割で逐次処理し、低スペック環境でも安定動作
+
+## Install
+
+```bash
+npm install waa-play
+```
+
+## Quick Start
+
+```ts
+import { createContext, loadBuffer, play, createGain } from "waa-play";
+
+const ctx = createContext();
+const buffer = await loadBuffer(ctx, "/audio/track.mp3");
+
+const gain = createGain(ctx, 0.8);
+const playback = play(ctx, buffer, { through: [gain] });
+
+playback.on("timeupdate", ({ position, duration }) => {
+  console.log(`${position.toFixed(1)}s / ${duration.toFixed(1)}s`);
+});
+
+playback.pause();
+playback.seek(30);
+playback.resume();
+```
+
+## Usage Examples
+
+### オーディオグラフの構築
+
+```ts
+import { createGain, createFilter, createPanner, chain } from "waa-play";
+
+const gain = createGain(ctx, 0.8);
+const lowpass = createFilter(ctx, { type: "lowpass", frequency: 2000 });
+const panner = createPanner(ctx, -0.5);
+
+chain(sourceNode, gain, lowpass, panner);
+panner.connect(ctx.destination);
+```
+
+### 波形の描画
+
+```ts
+import { extractPeaks } from "waa-play";
+
+const peaks = extractPeaks(buffer, { resolution: 500 });
+peaks.forEach((peak, i) => {
+  ctx2d.fillRect(i * barWidth, canvas.height * (1 - peak), barWidth - 1, canvas.height * peak);
+});
+```
+
+### React で使う
+
+```tsx
+import { useSyncExternalStore, useCallback } from "react";
+import { subscribeSnapshot, getSnapshot, type Playback } from "waa-play";
+
+function usePlayback(playback: Playback | null) {
+  const subscribe = useCallback(
+    (cb: () => void) => {
+      if (!playback) return () => {};
+      return subscribeSnapshot(playback, cb);
+    },
+    [playback],
+  );
+  return useSyncExternalStore(
+    subscribe,
+    () => (playback ? getSnapshot(playback) : null),
+  );
+}
+```
+
+### ピッチを保持したままテンポを変更
+
+```ts
+import { createContext, loadBuffer, play, onFrame } from "waa-play";
+
+const ctx = createContext();
+const buffer = await loadBuffer(ctx, "/audio/track.mp3");
+
+// preservePitch: true を渡すだけでピッチ保持タイムストレッチが有効に
+const playback = play(ctx, buffer, {
+  playbackRate: 0.75,     // テンポ 75%（スロー再生）
+  preservePitch: true,    // ピッチは変わらない
+});
+
+// 再生中にテンポを変更
+playback.setPlaybackRate(1.25); // テンポ 125%（高速再生）
+
+// stretcher の状態を監視
+const stopLoop = onFrame(playback, (snapshot) => {
+  if (snapshot.stretcher) {
+    console.log(`変換進捗: ${(snapshot.stretcher.conversionProgress * 100).toFixed(0)}%`);
+    console.log(`バッファ: ${snapshot.stretcher.bufferHealth}`);
+  }
+});
+```
+
+### 他のライブラリの AudioContext を使う
+
+```ts
+import { play, loadBuffer } from "waa-play";
+import { Tone } from "tone";
+
+const ctx = Tone.context.rawContext;
+const buffer = await loadBuffer(ctx, "/audio/track.mp3");
+play(ctx, buffer);
+```
+
+## Modules
+
+必要なものだけ import できます。
+
+```ts
+import { play } from "waa-play/play";
+import { loadBuffer } from "waa-play/buffer";
+import { extractPeaks } from "waa-play/waveform";
+```
+
+| Module | 概要 |
+|--------|------|
+| `context` | AudioContext のライフサイクル管理 |
+| `buffer` | 音声ファイルのロード・デコード |
+| `play` | 再生制御（play / pause / seek / loop / preservePitch） |
+| `emitter` | 型安全なイベントエミッター |
+| `nodes` | AudioNode のファクトリとチェーン接続 |
+| `waveform` | 波形データの抽出（ピーク・RMS） |
+| `fade` | フェード処理（in / out / crossfade） |
+| `scheduler` | スケジューリングと BPM ベースのクロック |
+| `synth` | 波形バッファの生成（sin / noise / click） |
+| `adapters` | フレームワーク統合（React / Vue / Svelte） |
+| `stretcher` | ピッチ保持タイムストレッチ（WSOLA） |
+
+## License
+
+MIT

package/dist/adapters.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+var chunkHTGOHC73_cjs = require('./chunk-HTGOHC73.cjs');
+
+
+
+Object.defineProperty(exports, "getSnapshot", {
+  enumerable: true,
+  get: function () { return chunkHTGOHC73_cjs.getSnapshot; }
+});
+Object.defineProperty(exports, "onFrame", {
+  enumerable: true,
+  get: function () { return chunkHTGOHC73_cjs.onFrame; }
+});
+Object.defineProperty(exports, "subscribeSnapshot", {
+  enumerable: true,
+  get: function () { return chunkHTGOHC73_cjs.subscribeSnapshot; }
+});
+Object.defineProperty(exports, "whenEnded", {
+  enumerable: true,
+  get: function () { return chunkHTGOHC73_cjs.whenEnded; }
+});
+Object.defineProperty(exports, "whenPosition", {
+  enumerable: true,
+  get: function () { return chunkHTGOHC73_cjs.whenPosition; }
+});
+//# sourceMappingURL=adapters.cjs.map
+//# sourceMappingURL=adapters.cjs.map

package/dist/adapters.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"adapters.cjs"}

package/dist/adapters.d.cts

@@ -0,0 +1,42 @@
+import { e as Playback, g as PlaybackSnapshot } from './types-DUrbEbPl.cjs';
+
+/**
+ * Get an immutable snapshot of the current playback state.
+ * Designed for use with React's `useSyncExternalStore` or similar patterns.
+ */
+declare function getSnapshot(playback: Playback): PlaybackSnapshot;
+/**
+ * Subscribe to playback state changes, calling `callback` with a fresh
+ * snapshot whenever the state updates.
+ *
+ * Returns an unsubscribe function. Works as the `subscribe` parameter for
+ * React's `useSyncExternalStore`.
+ *
+ * ```ts
+ * // React example:
+ * const snap = useSyncExternalStore(
+ *   (cb) => subscribeSnapshot(playback, cb),
+ *   () => getSnapshot(playback),
+ * );
+ * ```
+ */
+declare function subscribeSnapshot(playback: Playback, callback: () => void): () => void;
+/**
+ * Call `callback` on every animation frame with the current playback snapshot.
+ * Useful for smooth UI animations (waveform cursors, progress bars, etc.).
+ *
+ * Returns a `stop` function that cancels the loop.
+ */
+declare function onFrame(playback: Playback, callback: (snapshot: PlaybackSnapshot) => void): () => void;
+/**
+ * Return a `Promise` that resolves when the playback reaches the `"stopped"`
+ * state via the `ended` event (natural end, not manual stop).
+ */
+declare function whenEnded(playback: Playback): Promise<void>;
+/**
+ * Return a `Promise` that resolves when the playback position reaches or
+ * exceeds `position` seconds.
+ */
+declare function whenPosition(playback: Playback, position: number): Promise<void>;
+
+export { getSnapshot, onFrame, subscribeSnapshot, whenEnded, whenPosition };

package/dist/adapters.d.ts

@@ -0,0 +1,42 @@
+import { e as Playback, g as PlaybackSnapshot } from './types-DUrbEbPl.js';
+
+/**
+ * Get an immutable snapshot of the current playback state.
+ * Designed for use with React's `useSyncExternalStore` or similar patterns.
+ */
+declare function getSnapshot(playback: Playback): PlaybackSnapshot;
+/**
+ * Subscribe to playback state changes, calling `callback` with a fresh
+ * snapshot whenever the state updates.
+ *
+ * Returns an unsubscribe function. Works as the `subscribe` parameter for
+ * React's `useSyncExternalStore`.
+ *
+ * ```ts
+ * // React example:
+ * const snap = useSyncExternalStore(
+ *   (cb) => subscribeSnapshot(playback, cb),
+ *   () => getSnapshot(playback),
+ * );
+ * ```
+ */
+declare function subscribeSnapshot(playback: Playback, callback: () => void): () => void;
+/**
+ * Call `callback` on every animation frame with the current playback snapshot.
+ * Useful for smooth UI animations (waveform cursors, progress bars, etc.).
+ *
+ * Returns a `stop` function that cancels the loop.
+ */
+declare function onFrame(playback: Playback, callback: (snapshot: PlaybackSnapshot) => void): () => void;
+/**
+ * Return a `Promise` that resolves when the playback reaches the `"stopped"`
+ * state via the `ended` event (natural end, not manual stop).
+ */
+declare function whenEnded(playback: Playback): Promise<void>;
+/**
+ * Return a `Promise` that resolves when the playback position reaches or
+ * exceeds `position` seconds.
+ */
+declare function whenPosition(playback: Playback, position: number): Promise<void>;
+
+export { getSnapshot, onFrame, subscribeSnapshot, whenEnded, whenPosition };

package/dist/adapters.js

@@ -0,0 +1,3 @@
+export { getSnapshot, onFrame, subscribeSnapshot, whenEnded, whenPosition } from './chunk-AGP2IRC6.js';
+//# sourceMappingURL=adapters.js.map
+//# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"adapters.js"}

package/dist/buffer.cjs

@@ -0,0 +1,24 @@
+'use strict';
+
+var chunkCPAT75WD_cjs = require('./chunk-CPAT75WD.cjs');
+
+
+
+Object.defineProperty(exports, "getBufferInfo", {
+  enumerable: true,
+  get: function () { return chunkCPAT75WD_cjs.getBufferInfo; }
+});
+Object.defineProperty(exports, "loadBuffer", {
+  enumerable: true,
+  get: function () { return chunkCPAT75WD_cjs.loadBuffer; }
+});
+Object.defineProperty(exports, "loadBufferFromBlob", {
+  enumerable: true,
+  get: function () { return chunkCPAT75WD_cjs.loadBufferFromBlob; }
+});
+Object.defineProperty(exports, "loadBuffers", {
+  enumerable: true,
+  get: function () { return chunkCPAT75WD_cjs.loadBuffers; }
+});
+//# sourceMappingURL=buffer.cjs.map
+//# sourceMappingURL=buffer.cjs.map

package/dist/buffer.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"buffer.cjs"}

package/dist/buffer.d.cts

@@ -0,0 +1,34 @@
+import { B as BufferInfo, L as LoadBufferOptions } from './types-DUrbEbPl.cjs';
+
+/**
+ * Fetch an audio file from a URL and decode it into an `AudioBuffer`.
+ *
+ * ```ts
+ * const buffer = await loadBuffer(ctx, "/audio/track.mp3", {
+ *   onProgress: (p) => console.log(`${(p * 100).toFixed(0)}%`),
+ * });
+ * ```
+ */
+declare function loadBuffer(ctx: AudioContext, url: string, options?: LoadBufferOptions): Promise<AudioBuffer>;
+/**
+ * Decode an `AudioBuffer` from a `Blob` or `File`.
+ */
+declare function loadBufferFromBlob(ctx: AudioContext, blob: Blob): Promise<AudioBuffer>;
+/**
+ * Load multiple audio files in parallel.
+ *
+ * ```ts
+ * const buffers = await loadBuffers(ctx, {
+ *   kick: "/samples/kick.wav",
+ *   snare: "/samples/snare.wav",
+ * });
+ * buffers.get("kick"); // AudioBuffer
+ * ```
+ */
+declare function loadBuffers(ctx: AudioContext, map: Record<string, string>): Promise<Map<string, AudioBuffer>>;
+/**
+ * Return metadata about an `AudioBuffer`.
+ */
+declare function getBufferInfo(buffer: AudioBuffer): BufferInfo;
+
+export { getBufferInfo, loadBuffer, loadBufferFromBlob, loadBuffers };

package/dist/buffer.d.ts

@@ -0,0 +1,34 @@
+import { B as BufferInfo, L as LoadBufferOptions } from './types-DUrbEbPl.js';
+
+/**
+ * Fetch an audio file from a URL and decode it into an `AudioBuffer`.
+ *
+ * ```ts
+ * const buffer = await loadBuffer(ctx, "/audio/track.mp3", {
+ *   onProgress: (p) => console.log(`${(p * 100).toFixed(0)}%`),
+ * });
+ * ```
+ */
+declare function loadBuffer(ctx: AudioContext, url: string, options?: LoadBufferOptions): Promise<AudioBuffer>;
+/**
+ * Decode an `AudioBuffer` from a `Blob` or `File`.
+ */
+declare function loadBufferFromBlob(ctx: AudioContext, blob: Blob): Promise<AudioBuffer>;
+/**
+ * Load multiple audio files in parallel.
+ *
+ * ```ts
+ * const buffers = await loadBuffers(ctx, {
+ *   kick: "/samples/kick.wav",
+ *   snare: "/samples/snare.wav",
+ * });
+ * buffers.get("kick"); // AudioBuffer
+ * ```
+ */
+declare function loadBuffers(ctx: AudioContext, map: Record<string, string>): Promise<Map<string, AudioBuffer>>;
+/**
+ * Return metadata about an `AudioBuffer`.
+ */
+declare function getBufferInfo(buffer: AudioBuffer): BufferInfo;
+
+export { getBufferInfo, loadBuffer, loadBufferFromBlob, loadBuffers };

package/dist/buffer.js

@@ -0,0 +1,3 @@
+export { getBufferInfo, loadBuffer, loadBufferFromBlob, loadBuffers } from './chunk-T74FBKTY.js';
+//# sourceMappingURL=buffer.js.map
+//# sourceMappingURL=buffer.js.map

package/dist/buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"buffer.js"}

package/dist/chunk-2DL7CAEP.js

@@ -0,0 +1,69 @@
+// src/scheduler.ts
+function createScheduler(ctx, options) {
+  const { lookahead = 0.1, interval = 25 } = options ?? {};
+  const events = [];
+  let timerId = null;
+  function tick() {
+    const horizon = ctx.currentTime + lookahead;
+    for (let i = events.length - 1; i >= 0; i--) {
+      const evt = events[i];
+      if (evt.time <= horizon) {
+        evt.callback(evt.time);
+        events.splice(i, 1);
+      }
+    }
+  }
+  return {
+    schedule(id, time, callback) {
+      events.push({ id, time, callback });
+    },
+    cancel(id) {
+      const idx = events.findIndex((e) => e.id === id);
+      if (idx !== -1) events.splice(idx, 1);
+    },
+    start() {
+      if (timerId !== null) return;
+      timerId = setInterval(tick, interval);
+    },
+    stop() {
+      if (timerId !== null) {
+        clearInterval(timerId);
+        timerId = null;
+      }
+    },
+    dispose() {
+      this.stop();
+      events.length = 0;
+    }
+  };
+}
+function createClock(ctx, options) {
+  let bpm = options?.bpm ?? 120;
+  const startTime = ctx.currentTime;
+  function secondsPerBeat() {
+    return 60 / bpm;
+  }
+  return {
+    beatToTime(beat) {
+      return startTime + beat * secondsPerBeat();
+    },
+    getCurrentBeat() {
+      return (ctx.currentTime - startTime) / secondsPerBeat();
+    },
+    getNextBeatTime() {
+      const current = this.getCurrentBeat();
+      const next = Math.ceil(current);
+      return this.beatToTime(next === current ? next + 1 : next);
+    },
+    setBpm(value) {
+      bpm = value;
+    },
+    getBpm() {
+      return bpm;
+    }
+  };
+}
+
+export { createClock, createScheduler };
+//# sourceMappingURL=chunk-2DL7CAEP.js.map
+//# sourceMappingURL=chunk-2DL7CAEP.js.map

package/dist/chunk-2DL7CAEP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/scheduler.ts"],"names":[],"mappings":";AA6BO,SAAS,eAAA,CACd,KACA,OAAA,EACW;AACX,EAAA,MAAM,EAAE,SAAA,GAAY,GAAA,EAAK,WAAW,EAAA,EAAG,GAAI,WAAW,EAAC;AAEvD,EAAA,MAAM,SAA2B,EAAC;AAClC,EAAA,IAAI,OAAA,GAAiD,IAAA;AAErD,EAAA,SAAS,IAAA,GAAO;AACd,IAAA,MAAM,OAAA,GAAU,IAAI,WAAA,GAAc,SAAA;AAClC,IAAA,KAAA,IAAS,IAAI,MAAA,CAAO,MAAA,GAAS,CAAA,EAAG,CAAA,IAAK,GAAG,CAAA,EAAA,EAAK;AAC3C,MAAA,MAAM,GAAA,GAAM,OAAO,CAAC,CAAA;AACpB,MAAA,IAAI,GAAA,CAAI,QAAQ,OAAA,EAAS;AACvB,QAAA,GAAA,CAAI,QAAA,CAAS,IAAI,IAAI,CAAA;AACrB,QAAA,MAAA,CAAO,MAAA,CAAO,GAAG,CAAC,CAAA;AAAA,MACpB;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,QAAA,CAAS,EAAA,EAAI,IAAA,EAAM,QAAA,EAAU;AAC3B,MAAA,MAAA,CAAO,IAAA,CAAK,EAAE,EAAA,EAAI,IAAA,EAAM,UAAU,CAAA;AAAA,IACpC,CAAA;AAAA,IACA,OAAO,EAAA,EAAI;AACT,MAAA,MAAM,MAAM,MAAA,CAAO,SAAA,CAAU,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,EAAE,CAAA;AAC/C,MAAA,IAAI,GAAA,KAAQ,EAAA,EAAI,MAAA,CAAO,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,IACtC,CAAA;AAAA,IACA,KAAA,GAAQ;AACN,MAAA,IAAI,YAAY,IAAA,EAAM;AACtB,MAAA,OAAA,GAAU,WAAA,CAAY,MAAM,QAAQ,CAAA;AAAA,IACtC,CAAA;AAAA,IACA,IAAA,GAAO;AACL,MAAA,IAAI,YAAY,IAAA,EAAM;AACpB,QAAA,aAAA,CAAc,OAAO,CAAA;AACrB,QAAA,OAAA,GAAU,IAAA;AAAA,MACZ;AAAA,IACF,CAAA;AAAA,IACA,OAAA,GAAU;AACR,MAAA,IAAA,CAAK,IAAA,EAAK;AACV,MAAA,MAAA,CAAO,MAAA,GAAS,CAAA;AAAA,IAClB;AAAA,GACF;AACF;AAsBO,SAAS,WAAA,CACd,KACA,OAAA,EACO;AACP,EAAA,IAAI,GAAA,GAAM,SAAS,GAAA,IAAO,GAAA;AAC1B,EAAA,MAAM,YAAY,GAAA,CAAI,WAAA;AAEtB,EAAA,SAAS,cAAA,GAAiB;AACxB,IAAA,OAAO,EAAA,GAAK,GAAA;AAAA,EACd;AAEA,EAAA,OAAO;AAAA,IACL,WAAW,IAAA,EAAsB;AAC/B,MAAA,OAAO,SAAA,GAAY,OAAO,cAAA,EAAe;AAAA,IAC3C,CAAA;AAAA,IACA,cAAA,GAAyB;AACvB,MAAA,OAAA,CAAQ,GAAA,CAAI,WAAA,GAAc,SAAA,IAAa,cAAA,EAAe;AAAA,IACxD,CAAA;AAAA,IACA,eAAA,GAA0B;AACxB,MAAA,MAAM,OAAA,GAAU,KAAK,cAAA,EAAe;AACpC,MAAA,MAAM,IAAA,GAAO,IAAA,CAAK,IAAA,CAAK,OAAO,CAAA;AAC9B,MAAA,OAAO,KAAK,UAAA,CAAW,IAAA,KAAS,OAAA,GAAU,IAAA,GAAO,IAAI,IAAI,CAAA;AAAA,IAC3D,CAAA;AAAA,IACA,OAAO,KAAA,EAAe;AACpB,MAAA,GAAA,GAAM,KAAA;AAAA,IACR,CAAA;AAAA,IACA,MAAA,GAAiB;AACf,MAAA,OAAO,GAAA;AAAA,IACT;AAAA,GACF;AACF","file":"chunk-2DL7CAEP.js","sourcesContent":["// ---------------------------------------------------------------------------\n// M8: Scheduler & Clock\n// ---------------------------------------------------------------------------\n\nimport type { ClockOptions, ScheduledEvent, SchedulerOptions } from \"./types.js\";\n\n// ---------------------------------------------------------------------------\n// Scheduler\n// ---------------------------------------------------------------------------\n\nexport interface Scheduler {\n  /** Schedule a callback at a specific AudioContext time. */\n  schedule(id: string, time: number, callback: (time: number) => void): void;\n  /** Remove a scheduled event by id. */\n  cancel(id: string): void;\n  /** Start the scheduler loop. */\n  start(): void;\n  /** Stop the scheduler loop. */\n  stop(): void;\n  /** Dispose of all resources. */\n  dispose(): void;\n}\n\n/**\n * Create a lookahead-based event scheduler.\n *\n * Uses `setInterval` to check upcoming events and fire callbacks\n * slightly before their scheduled time, enabling sample-accurate timing.\n */\nexport function createScheduler(\n  ctx: AudioContext,\n  options?: SchedulerOptions,\n): Scheduler {\n  const { lookahead = 0.1, interval = 25 } = options ?? {};\n\n  const events: ScheduledEvent[] = [];\n  let timerId: ReturnType<typeof setInterval> | null = null;\n\n  function tick() {\n    const horizon = ctx.currentTime + lookahead;\n    for (let i = events.length - 1; i >= 0; i--) {\n      const evt = events[i]!;\n      if (evt.time <= horizon) {\n        evt.callback(evt.time);\n        events.splice(i, 1);\n      }\n    }\n  }\n\n  return {\n    schedule(id, time, callback) {\n      events.push({ id, time, callback });\n    },\n    cancel(id) {\n      const idx = events.findIndex((e) => e.id === id);\n      if (idx !== -1) events.splice(idx, 1);\n    },\n    start() {\n      if (timerId !== null) return;\n      timerId = setInterval(tick, interval);\n    },\n    stop() {\n      if (timerId !== null) {\n        clearInterval(timerId);\n        timerId = null;\n      }\n    },\n    dispose() {\n      this.stop();\n      events.length = 0;\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Clock\n// ---------------------------------------------------------------------------\n\nexport interface Clock {\n  /** Convert a beat number to AudioContext time (seconds). */\n  beatToTime(beat: number): number;\n  /** Get the current beat based on AudioContext time. */\n  getCurrentBeat(): number;\n  /** Get the AudioContext time of the next beat boundary. */\n  getNextBeatTime(): number;\n  /** Update BPM. */\n  setBpm(bpm: number): void;\n  /** Get current BPM. */\n  getBpm(): number;\n}\n\n/**\n * Create a BPM-based clock tied to an `AudioContext`.\n */\nexport function createClock(\n  ctx: AudioContext,\n  options?: ClockOptions,\n): Clock {\n  let bpm = options?.bpm ?? 120;\n  const startTime = ctx.currentTime;\n\n  function secondsPerBeat() {\n    return 60 / bpm;\n  }\n\n  return {\n    beatToTime(beat: number): number {\n      return startTime + beat * secondsPerBeat();\n    },\n    getCurrentBeat(): number {\n      return (ctx.currentTime - startTime) / secondsPerBeat();\n    },\n    getNextBeatTime(): number {\n      const current = this.getCurrentBeat();\n      const next = Math.ceil(current);\n      return this.beatToTime(next === current ? next + 1 : next);\n    },\n    setBpm(value: number) {\n      bpm = value;\n    },\n    getBpm(): number {\n      return bpm;\n    },\n  };\n}\n"]}

package/dist/chunk-37CPPRLV.js

@@ -0,0 +1,24 @@
+// src/context.ts
+function createContext(options) {
+  return new AudioContext({
+    sampleRate: options?.sampleRate,
+    latencyHint: options?.latencyHint
+  });
+}
+async function resumeContext(ctx) {
+  if (ctx.state === "suspended") {
+    await ctx.resume();
+  }
+}
+async function ensureRunning(ctx) {
+  if (ctx.state !== "running") {
+    await ctx.resume();
+  }
+}
+function now(ctx) {
+  return ctx.currentTime;
+}
+
+export { createContext, ensureRunning, now, resumeContext };
+//# sourceMappingURL=chunk-37CPPRLV.js.map
+//# sourceMappingURL=chunk-37CPPRLV.js.map

package/dist/chunk-37CPPRLV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.ts"],"names":[],"mappings":";AAaO,SAAS,cAAc,OAAA,EAA8C;AAC1E,EAAA,OAAO,IAAI,YAAA,CAAa;AAAA,IACtB,YAAY,OAAA,EAAS,UAAA;AAAA,IACrB,aAAa,OAAA,EAAS;AAAA,GACvB,CAAA;AACH;AAQA,eAAsB,cAAc,GAAA,EAAkC;AACpE,EAAA,IAAI,GAAA,CAAI,UAAU,WAAA,EAAa;AAC7B,IAAA,MAAM,IAAI,MAAA,EAAO;AAAA,EACnB;AACF;AAKA,eAAsB,cAAc,GAAA,EAAkC;AACpE,EAAA,IAAI,GAAA,CAAI,UAAU,SAAA,EAAW;AAC3B,IAAA,MAAM,IAAI,MAAA,EAAO;AAAA,EACnB;AACF;AAKO,SAAS,IAAI,GAAA,EAA2B;AAC7C,EAAA,OAAO,GAAA,CAAI,WAAA;AACb","file":"chunk-37CPPRLV.js","sourcesContent":["// ---------------------------------------------------------------------------\n// M1: AudioContext utilities\n// ---------------------------------------------------------------------------\n\nimport type { CreateContextOptions } from \"./types.js\";\n\n/**\n * Create an `AudioContext` with optional configuration.\n *\n * This is the only place in the library where `new AudioContext()` is called.\n * Users are encouraged to create their own context and pass it to other\n * functions — this helper exists purely for convenience.\n */\nexport function createContext(options?: CreateContextOptions): AudioContext {\n  return new AudioContext({\n    sampleRate: options?.sampleRate,\n    latencyHint: options?.latencyHint,\n  });\n}\n\n/**\n * Resume a suspended AudioContext (e.g. blocked by autoplay policy).\n *\n * Should be called inside a user-interaction event handler (click, keydown…)\n * if the context is in the `\"suspended\"` state.\n */\nexport async function resumeContext(ctx: AudioContext): Promise<void> {\n  if (ctx.state === \"suspended\") {\n    await ctx.resume();\n  }\n}\n\n/**\n * Ensure the context is in the `\"running\"` state, resuming if necessary.\n */\nexport async function ensureRunning(ctx: AudioContext): Promise<void> {\n  if (ctx.state !== \"running\") {\n    await ctx.resume();\n  }\n}\n\n/**\n * Shorthand for `ctx.currentTime`.\n */\nexport function now(ctx: AudioContext): number {\n  return ctx.currentTime;\n}\n"]}

package/dist/chunk-4LNVRSTM.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+// src/fade.ts
+var EXP_MIN = 1e-4;
+function applyRamp(node, from, to, duration, curve) {
+  const param = node.gain;
+  const now = node.context.currentTime;
+  param.cancelScheduledValues(now);
+  param.setValueAtTime(from, now);
+  switch (curve) {
+    case "exponential":
+      param.exponentialRampToValueAtTime(
+        Math.max(to, EXP_MIN),
+        now + duration
+      );
+      break;
+    case "equal-power": {
+      const steps = Math.max(Math.ceil(duration * 100), 2);
+      const values = new Float32Array(steps);
+      for (let i = 0; i < steps; i++) {
+        const t = i / (steps - 1);
+        const gain = from + (to - from) * Math.sin(t * Math.PI / 2);
+        values[i] = gain;
+      }
+      param.setValueCurveAtTime(values, now, duration);
+      break;
+    }
+    case "linear":
+    default:
+      param.linearRampToValueAtTime(to, now + duration);
+      break;
+  }
+}
+function fadeIn(gain, target, options) {
+  const { duration = 1, curve = "linear" } = options ?? {};
+  applyRamp(gain, 0, target, duration, curve);
+}
+function fadeOut(gain, options) {
+  const { duration = 1, curve = "linear" } = options ?? {};
+  applyRamp(gain, gain.gain.value, 0, duration, curve);
+}
+function crossfade(gainA, gainB, options) {
+  const { duration = 1, curve = "linear" } = options ?? {};
+  applyRamp(gainA, gainA.gain.value, 0, duration, curve);
+  applyRamp(gainB, 0, gainA.gain.value || 1, duration, curve);
+}
+function autoFade(playback, gain, options) {
+  const {
+    fadeIn: fadeInDuration = 0,
+    fadeOut: fadeOutDuration = 0,
+    curve = "linear"
+  } = options ?? {};
+  const duration = playback.getDuration();
+  let fadeOutScheduled = false;
+  if (fadeInDuration > 0) {
+    applyRamp(gain, 0, 1, fadeInDuration, curve);
+  }
+  const unsub = playback.on("timeupdate", ({ position }) => {
+    if (fadeOutDuration > 0 && !fadeOutScheduled && position >= duration - fadeOutDuration) {
+      fadeOutScheduled = true;
+      applyRamp(gain, gain.gain.value, 0, fadeOutDuration, curve);
+    }
+  });
+  return unsub;
+}
+
+exports.autoFade = autoFade;
+exports.crossfade = crossfade;
+exports.fadeIn = fadeIn;
+exports.fadeOut = fadeOut;
+//# sourceMappingURL=chunk-4LNVRSTM.cjs.map
+//# sourceMappingURL=chunk-4LNVRSTM.cjs.map

package/dist/chunk-4LNVRSTM.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fade.ts"],"names":[],"mappings":"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","file":"chunk-4LNVRSTM.cjs","sourcesContent":["// ---------------------------------------------------------------------------\n// M7: Fade utilities\n// ---------------------------------------------------------------------------\n\nimport type {\n  AutoFadeOptions,\n  CrossfadeOptions,\n  FadeCurve,\n  FadeOptions,\n  Playback,\n} from \"./types.js\";\n\n/** Minimum value used for exponential ramps (cannot ramp to/from 0). */\nconst EXP_MIN = 0.0001;\n\nfunction applyRamp(\n  node: GainNode,\n  from: number,\n  to: number,\n  duration: number,\n  curve: FadeCurve,\n): void {\n  const param = node.gain;\n  const now = node.context.currentTime;\n  param.cancelScheduledValues(now);\n  param.setValueAtTime(from, now);\n\n  switch (curve) {\n    case \"exponential\":\n      param.exponentialRampToValueAtTime(\n        Math.max(to, EXP_MIN),\n        now + duration,\n      );\n      break;\n    case \"equal-power\": {\n      // Approximate equal-power with a setValueCurveAtTime.\n      const steps = Math.max(Math.ceil(duration * 100), 2);\n      const values = new Float32Array(steps);\n      for (let i = 0; i < steps; i++) {\n        const t = i / (steps - 1);\n        const gain = from + (to - from) * Math.sin((t * Math.PI) / 2);\n        values[i] = gain;\n      }\n      param.setValueCurveAtTime(values, now, duration);\n      break;\n    }\n    case \"linear\":\n    default:\n      param.linearRampToValueAtTime(to, now + duration);\n      break;\n  }\n}\n\n/**\n * Fade a `GainNode` in from 0 to `target`.\n */\nexport function fadeIn(\n  gain: GainNode,\n  target: number,\n  options?: FadeOptions,\n): void {\n  const { duration = 1, curve = \"linear\" } = options ?? {};\n  applyRamp(gain, 0, target, duration, curve);\n}\n\n/**\n * Fade a `GainNode` out to 0.\n */\nexport function fadeOut(gain: GainNode, options?: FadeOptions): void {\n  const { duration = 1, curve = \"linear\" } = options ?? {};\n  applyRamp(gain, gain.gain.value, 0, duration, curve);\n}\n\n/**\n * Crossfade between two `GainNode`s.\n */\nexport function crossfade(\n  gainA: GainNode,\n  gainB: GainNode,\n  options?: CrossfadeOptions,\n): void {\n  const { duration = 1, curve = \"linear\" } = options ?? {};\n  applyRamp(gainA, gainA.gain.value, 0, duration, curve);\n  applyRamp(gainB, 0, gainA.gain.value || 1, duration, curve);\n}\n\n/**\n * Automatically apply fade-in at start and/or fade-out near end of a Playback.\n * Returns a cleanup function.\n */\nexport function autoFade(\n  playback: Playback,\n  gain: GainNode,\n  options?: AutoFadeOptions,\n): () => void {\n  const {\n    fadeIn: fadeInDuration = 0,\n    fadeOut: fadeOutDuration = 0,\n    curve = \"linear\",\n  } = options ?? {};\n\n  const duration = playback.getDuration();\n  let fadeOutScheduled = false;\n\n  // Apply fade-in immediately if playing from the start.\n  if (fadeInDuration > 0) {\n    applyRamp(gain, 0, 1, fadeInDuration, curve);\n  }\n\n  const unsub = playback.on(\"timeupdate\", ({ position }) => {\n    if (\n      fadeOutDuration > 0 &&\n      !fadeOutScheduled &&\n      position >= duration - fadeOutDuration\n    ) {\n      fadeOutScheduled = true;\n      applyRamp(gain, gain.gain.value, 0, fadeOutDuration, curve);\n    }\n  });\n\n  return unsub;\n}\n"]}

package/dist/chunk-5J7S6QV3.cjs

@@ -0,0 +1,44 @@
+'use strict';
+
+// src/emitter.ts
+function createEmitter() {
+  const listeners = /* @__PURE__ */ new Map();
+  function getSet(event) {
+    let set = listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      listeners.set(event, set);
+    }
+    return set;
+  }
+  return {
+    on(event, handler) {
+      const set = getSet(event);
+      set.add(handler);
+      return () => {
+        set.delete(handler);
+      };
+    },
+    off(event, handler) {
+      listeners.get(event)?.delete(handler);
+    },
+    emit(event, data) {
+      const set = listeners.get(event);
+      if (!set) return;
+      for (const handler of set) {
+        handler(data);
+      }
+    },
+    clear(event) {
+      if (event !== void 0) {
+        listeners.delete(event);
+      } else {
+        listeners.clear();
+      }
+    }
+  };
+}
+
+exports.createEmitter = createEmitter;
+//# sourceMappingURL=chunk-5J7S6QV3.cjs.map
+//# sourceMappingURL=chunk-5J7S6QV3.cjs.map