waa-play 0.1.0 → 0.2.0

package/README.md

@@ -4,25 +4,11 @@
 [![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.
+Convenient composable building blocks for Web Audio API.
 
-BYO AudioContext / Zero Dependencies / Framework-agnostic / Sample-accurate / Pitch-preserving time-stretch / Chunk-based streaming
+Time-stretch / Streaming / Waveform / BYO AudioContext / Zero Dependencies
 
-**[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** — 音声をチャンク分割で逐次処理し、低スペック環境でも安定動作
+[Documentation & Demo](https://ivgtr.github.io/waa/)
 
 ## Install
 
@@ -30,122 +16,81 @@ BYO AudioContext / Zero Dependencies / Framework-agnostic / Sample-accurate / Pi
 npm install waa-play
 ```
 
-## Quick Start
+## Features
 
-```ts
-import { createContext, loadBuffer, play, createGain } from "waa-play";
+### Pitch-preserving time-stretch
+再生速度を変えてもピッチが変わりません。処理は別スレッドで実行されるため、UI をブロックしません。
 
-const ctx = createContext();
-const buffer = await loadBuffer(ctx, "/audio/track.mp3");
+### Streaming playback
+音声を段階的に処理し、バッファリング状態をイベントで通知します。ローディング UI を簡単に実装できます。
 
-const gain = createGain(ctx, 0.8);
-const playback = play(ctx, buffer, { through: [gain] });
+### BYO AudioContext
+既存の AudioContext やオーディオグラフをそのまま使えます。他のライブラリとの統合も容易です。
 
-playback.on("timeupdate", ({ position, duration }) => {
-  console.log(`${position.toFixed(1)}s / ${duration.toFixed(1)}s`);
-});
+### Framework integration
+React・Vue・Svelte など、お好みのフレームワークで再生状態をリアクティブに扱えます。
 
-playback.pause();
-playback.seek(30);
-playback.resume();
-```
+### Waveform extraction
+波形データを取得し、プログレスバーや波形ビジュアライザーを構築できます。
+
+### Background-tab safe
+バックグラウンドタブでも再生位置の追跡が継続します。
+
+## Quick Start
 
-## Usage Examples
+### Class API (WaaPlayer)
 
-### オーディオグラフの構築
+最もシンプルな使い方です。`WaaPlayer` が `AudioContext` を内部管理し、全モジュールの機能を統合して提供します。
 
 ```ts
-import { createGain, createFilter, createPanner, chain } from "waa-play";
+import { WaaPlayer } from "waa-play";
 
-const gain = createGain(ctx, 0.8);
-const lowpass = createFilter(ctx, { type: "lowpass", frequency: 2000 });
-const panner = createPanner(ctx, -0.5);
+const player = new WaaPlayer();
+const buffer = await player.load("/audio/track.mp3");
+
+const gain = player.createGain(0.8);
+const playback = player.play(buffer, { through: [gain] });
 
-chain(sourceNode, gain, lowpass, panner);
-panner.connect(ctx.destination);
+player.dispose();
 ```
 
-### 波形の描画
+既存の `AudioContext` を渡すこともできます。
 
 ```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);
-});
+const player = new WaaPlayer(existingAudioContext);
 ```
 
-### 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),
-  );
-}
-```
+### Function API
 
-### ピッチを保持したままテンポを変更
+個別の関数だけ import したい場合はこちら。全関数が `AudioContext` を第一引数に取ります。
 
 ```ts
-import { createContext, loadBuffer, play, onFrame } from "waa-play";
+import { createContext, loadBuffer, play, createGain } 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%（高速再生）
+const gain = createGain(ctx, 0.8);
+const playback = play(ctx, buffer, { through: [gain] });
 
-// stretcher の状態を監視
-const stopLoop = onFrame(playback, (snapshot) => {
-  if (snapshot.stretcher) {
-    console.log(`変換進捗: ${(snapshot.stretcher.conversionProgress * 100).toFixed(0)}%`);
-    console.log(`バッファ: ${snapshot.stretcher.bufferHealth}`);
-  }
+playback.on("timeupdate", ({ position, duration }) => {
+  console.log(`${position.toFixed(1)}s / ${duration.toFixed(1)}s`);
 });
 ```
 
-### 他のライブラリの 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 できます。
+必要なものだけ個別に import できます。
 
 ```ts
 import { play } from "waa-play/play";
 import { loadBuffer } from "waa-play/buffer";
-import { extractPeaks } from "waa-play/waveform";
+import { WaaPlayer } from "waa-play/player";
 ```
 
 | Module | 概要 |
 |--------|------|
+| `player` | 全モジュールを統合するクラスベース API |
 | `context` | AudioContext のライフサイクル管理 |
 | `buffer` | 音声ファイルのロード・デコード |
 | `play` | 再生制御（play / pause / seek / loop / preservePitch） |
@@ -158,6 +103,26 @@ import { extractPeaks } from "waa-play/waveform";
 | `adapters` | フレームワーク統合（React / Vue / Svelte） |
 | `stretcher` | ピッチ保持タイムストレッチ（WSOLA） |
 
+## API
+
+詳細な使い方・API リファレンスは [Documentation & Demo](https://ivgtr.github.io/waa/) をご覧ください。
+
+### WaaPlayer
+
+| メソッド | 概要 |
+|----------|------|
+| `resume()` / `ensureRunning()` / `now()` | AudioContext 制御 |
+| `load(url)` / `loadFromBlob(blob)` / `loadAll(map)` | 音声ロード |
+| `play(buffer, options?)` | 再生（`Playback` を返す） |
+| `createGain()` / `createFilter()` / `createPanner()` / `createCompressor()` / `createAnalyser()` | ノード生成 |
+| `chain(...nodes)` / `disconnectChain(...nodes)` | グラフ接続 |
+| `fadeIn()` / `fadeOut()` / `crossfade()` / `autoFade()` | フェード |
+| `extractPeaks()` / `extractPeakPairs()` / `extractRMS()` | 波形抽出 |
+| `createScheduler()` / `createClock()` | スケジューリング |
+| `createSineBuffer()` / `createNoiseBuffer()` / `createClickBuffer()` | バッファ合成 |
+| `getSnapshot()` / `subscribeSnapshot()` / `onFrame()` / `whenEnded()` / `whenPosition()` | アダプター |
+| `dispose()` | リソース解放 |
+
 ## License
 
 MIT

package/dist/adapters.cjs

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

package/dist/adapters.d.cts

@@ -3,6 +3,12 @@ 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.
+ *
+ * Always returns a referentially stable (cached) object. The cache is updated
+ * by `subscribeSnapshot` (on playback events) and `onFrame` (every animation
+ * frame), so `getSnapshot` itself never computes a fresh snapshot — it only
+ * reads or initialises the cache. This guarantees the reference-equality
+ * contract required by `useSyncExternalStore`.
  */
 declare function getSnapshot(playback: Playback): PlaybackSnapshot;
 /**
@@ -14,10 +20,16 @@ declare function getSnapshot(playback: Playback): PlaybackSnapshot;
  *
  * ```ts
  * // React example:
- * const snap = useSyncExternalStore(
- *   (cb) => subscribeSnapshot(playback, cb),
+ * import { useCallback } from "react";
+ * const subscribe = useCallback(
+ *   (cb: () => void) => subscribeSnapshot(playback, cb),
+ *   [playback],
+ * );
+ * const snap = useCallback(
  *   () => getSnapshot(playback),
+ *   [playback],
  * );
+ * const snapshot = useSyncExternalStore(subscribe, snap, snap);
  * ```
  */
 declare function subscribeSnapshot(playback: Playback, callback: () => void): () => void;

package/dist/adapters.d.ts

@@ -3,6 +3,12 @@ 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.
+ *
+ * Always returns a referentially stable (cached) object. The cache is updated
+ * by `subscribeSnapshot` (on playback events) and `onFrame` (every animation
+ * frame), so `getSnapshot` itself never computes a fresh snapshot — it only
+ * reads or initialises the cache. This guarantees the reference-equality
+ * contract required by `useSyncExternalStore`.
  */
 declare function getSnapshot(playback: Playback): PlaybackSnapshot;
 /**
@@ -14,10 +20,16 @@ declare function getSnapshot(playback: Playback): PlaybackSnapshot;
  *
  * ```ts
  * // React example:
- * const snap = useSyncExternalStore(
- *   (cb) => subscribeSnapshot(playback, cb),
+ * import { useCallback } from "react";
+ * const subscribe = useCallback(
+ *   (cb: () => void) => subscribeSnapshot(playback, cb),
+ *   [playback],
+ * );
+ * const snap = useCallback(
  *   () => getSnapshot(playback),
+ *   [playback],
  * );
+ * const snapshot = useSyncExternalStore(subscribe, snap, snap);
  * ```
  */
 declare function subscribeSnapshot(playback: Playback, callback: () => void): () => void;

package/dist/adapters.js

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

package/dist/{chunk-V2QX5K42.js → chunk-2FFORBOP.js}

@@ -1148,7 +1148,6 @@ function createChunkPlayer(ctx, options) {
   }
   function resume() {
     if (!paused || disposed) return;
-    paused = false;
   }
   function stop() {
     if (stopped || disposed) return;
@@ -1277,6 +1276,7 @@ function createStretcherEngine(ctx, buffer, options) {
   const {
     tempo: initialTempo,
     offset = 0,
+    loop: initialLoop = false,
     through = [],
     destination = ctx.destination
   } = options;
@@ -1285,6 +1285,7 @@ function createStretcherEngine(ctx, buffer, options) {
   const totalDuration = buffer.duration;
   let phase = "waiting";
   let currentTempo = initialTempo;
+  let isLooping = initialLoop;
   let disposed = false;
   let bufferingStartTime = 0;
   let currentChunkIndex = 0;
@@ -1461,6 +1462,20 @@ function createStretcherEngine(ctx, buffer, options) {
   function advanceToNextChunk() {
     const nextIdx = currentChunkIndex + 1;
     if (nextIdx >= chunks.length) {
+      if (isLooping) {
+        currentChunkIndex = 0;
+        scheduler.handleSeek(0);
+        const chunk2 = chunks[0];
+        if (chunk2 && chunk2.state === "ready") {
+          playCurrentChunk();
+        } else {
+          bufferingResumePosition = 0;
+          enterBuffering("seek");
+        }
+        emitter.emit("loop", void 0);
+        evictDistantChunks();
+        return;
+      }
       phase = "ended";
       chunkPlayer.stop();
       emitter.emit("ended", void 0);
@@ -1631,9 +1646,10 @@ function createStretcherEngine(ctx, buffer, options) {
     if (disposed || phase !== "paused") return;
     const chunk = chunks[currentChunkIndex];
     if (chunk && chunk.state === "ready") {
+      const resumePosition = chunkPlayer.getCurrentPosition();
       phase = "playing";
       chunkPlayer.resume();
-      playCurrentChunk(chunkPlayer.getCurrentPosition());
+      playCurrentChunk(resumePosition);
     } else {
       enterBuffering("underrun");
     }
@@ -1670,6 +1686,9 @@ function createStretcherEngine(ctx, buffer, options) {
     phase = "ended";
     chunkPlayer.stop();
   }
+  function setLoop(value) {
+    isLooping = value;
+  }
   function setTempo(newTempo) {
     if (disposed || phase === "ended" || newTempo === currentTempo) return;
     bufferingResumePosition = getPositionInOriginalBuffer();
@@ -1694,6 +1713,7 @@ function createStretcherEngine(ctx, buffer, options) {
     seek,
     stop,
     setTempo,
+    setLoop,
     getCurrentPosition: getPositionInOriginalBuffer,
     getStatus,
     getSnapshot,
@@ -1704,5 +1724,5 @@ function createStretcherEngine(ctx, buffer, options) {
 }
 
 export { createStretcherEngine };
-//# sourceMappingURL=chunk-V2QX5K42.js.map
-//# sourceMappingURL=chunk-V2QX5K42.js.map
+//# sourceMappingURL=chunk-2FFORBOP.js.map
+//# sourceMappingURL=chunk-2FFORBOP.js.map