waa-play 0.2.0 → 0.2.2

package/README.md

@@ -1,128 +1,80 @@
 # 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/)
 
-Convenient composable building blocks for Web Audio API.
+Web Audio API modules with WSOLA time-stretching, chunk-based streaming, and waveform extraction
 
-Time-stretch / Streaming / Waveform / BYO AudioContext / Zero Dependencies
+waa-play は Web Audio API を用いた音声操作のためのモジュール群です。ピッチ保持タイムストレッチ、ストリーミング再生、波形抽出、AudioNode チェーン接続などの機能を提供します。
 
-[Documentation & Demo](https://ivgtr.github.io/waa/)
+Web Audio API の `playbackRate` で再生速度を変更するとピッチも連動して変化します。waa-play は、ピッチを保持したまま再生速度を変えたいユースケースのために作成しました。
 
-## Install
+この実装は完璧なものではなく、すべてのユースケースに対応するわけではないことに注意してください。
 
-```bash
-npm install waa-play
-```
-
-## Features
+## Documentation & Demo
 
-### Pitch-preserving time-stretch
-再生速度を変えてもピッチが変わりません。処理は別スレッドで実行されるため、UI をブロックしません。
+https://ivgtr.github.io/waa/
 
-### Streaming playback
-音声を段階的に処理し、バッファリング状態をイベントで通知します。ローディング UI を簡単に実装できます。
+## ピッチ保持タイムストレッチ（WSOLA）
 
-### BYO AudioContext
-既存の AudioContext やオーディオグラフをそのまま使えます。他のライブラリとの統合も容易です。
+waa-play は WSOLA (Waveform Similarity Overlap-Add) アルゴリズムを採用しています。
+音声信号を小さなフレームに分割し、類似した波形を重ね合わせて再構築することで、ピッチを変えずに時間的な伸縮を実現します。
 
-### Framework integration
-React・Vue・Svelte など、お好みのフレームワークで再生状態をリアクティブに扱えます。
+HTML5 Audio 要素の `preservePitch` オプションと同様の効果を目指していますが、いくつかの制約があります。
+WSOLA の処理はクライアントサイドで行われるため、CPU リソースを多く消費する可能性があります。
+また、AudioBuffer 全体を事前に読み込む必要があるため、長い音声ファイルでは変換に時間がかかる場合があります。
 
-### Waveform extraction
-波形データを取得し、プログレスバーや波形ビジュアライザーを構築できます。
-
-### Background-tab safe
-バックグラウンドタブでも再生位置の追跡が継続します。
-
-## Quick Start
+これらの制約に対して、Worker による並列処理やチャンクベースのストリーミングで対処しています。
 
-### Class API (WaaPlayer)
+### Worker ベースの変換
 
-最もシンプルな使い方です。`WaaPlayer` が `AudioContext` を内部管理し、全モジュールの機能を統合して提供します。
+WSOLA 変換は Web Worker 内で実行され、メインスレッドのパフォーマンスへの影響を最小限に抑えています。
+Worker は複数生成され、変換タスクがキューイングされて効率的に処理されます。
 
-```ts
-import { WaaPlayer } from "waa-play";
+### チャンクベースのストリーミング再生
 
-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] });
+### イベント通知
 
-player.dispose();
-```
+再生位置の更新や再生終了などのイベントが通知され、UI の更新や他の処理に利用できます。
 
-既存の `AudioContext` を渡すこともできます。
+## Quick Start
 
-```ts
-const player = new WaaPlayer(existingAudioContext);
+```bash
+npm install waa-play
 ```
 
-### Function API
+### 最も簡単な使い方（WaaPlayer）
 
-個別の関数だけ import したい場合はこちら。全関数が `AudioContext` を第一引数に取ります。
+`WaaPlayer` が `AudioContext` を内部管理し、全モジュールの機能を統合して提供します。
 
 ```ts
-import { createContext, loadBuffer, play, createGain } from "waa-play";
+import { WaaPlayer } from "waa-play";
+
+const player = new WaaPlayer();
+const buffer = await player.load("/audio/track.mp3");
 
-const ctx = createContext();
-const buffer = await loadBuffer(ctx, "/audio/track.mp3");
+const gain = player.createGain(0.8);
+const playback = player.play(buffer, { through: [gain] }); // 再生
 
-const gain = createGain(ctx, 0.8);
-const playback = play(ctx, buffer, { through: [gain] });
+playback.setPlaybackRate(1.5); // 再生速度を 1.5 倍に変更（リアルタイム反映）
 
 playback.on("timeupdate", ({ position, duration }) => {
-  console.log(`${position.toFixed(1)}s / ${duration.toFixed(1)}s`);
+  console.log(`${position.toFixed(2)}s / ${duration.toFixed(2)}s`);
 });
-```
 
-## Modules
+playback.dispose(); // 再生停止・リソース解放
+```
 
-必要なものだけ個別に import できます。
+既存の `AudioContext` を渡すこともできます。これは例えば、他の AudioNode と接続したい場合に有用です。
 
 ```ts
-import { play } from "waa-play/play";
-import { loadBuffer } from "waa-play/buffer";
-import { WaaPlayer } from "waa-play/player";
+const player = new WaaPlayer(existingAudioContext);
 ```
 
-| Module | 概要 |
-|--------|------|
-| `player` | 全モジュールを統合するクラスベース API |
-| `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） |
-
-## 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
+MIT © [ivgtr](https://github.com/ivgtr)
+
+[![Twitter Follow](https://img.shields.io/twitter/follow/ivgtr?style=social)](https://twitter.com/ivgtr) [![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)

package/dist/adapters.cjs

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

package/dist/adapters.d.cts

@@ -1,4 +1,4 @@
-import { e as Playback, g as PlaybackSnapshot } from './types-DUrbEbPl.cjs';
+import { e as Playback, g as PlaybackSnapshot } from './types-BYC6m7Q0.cjs';
 
 /**
  * Get an immutable snapshot of the current playback state.

package/dist/adapters.d.ts

@@ -1,4 +1,4 @@
-import { e as Playback, g as PlaybackSnapshot } from './types-DUrbEbPl.js';
+import { e as Playback, g as PlaybackSnapshot } from './types-BYC6m7Q0.js';
 
 /**
  * Get an immutable snapshot of the current playback state.

package/dist/adapters.js

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

package/dist/buffer.cjs

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

package/dist/buffer.d.cts

@@ -1,4 +1,4 @@
-import { B as BufferInfo, L as LoadBufferOptions } from './types-DUrbEbPl.cjs';
+import { B as BufferInfo, L as LoadBufferOptions } from './types-BYC6m7Q0.cjs';
 
 /**
  * Fetch an audio file from a URL and decode it into an `AudioBuffer`.

package/dist/buffer.d.ts

@@ -1,4 +1,4 @@
-import { B as BufferInfo, L as LoadBufferOptions } from './types-DUrbEbPl.js';
+import { B as BufferInfo, L as LoadBufferOptions } from './types-BYC6m7Q0.js';
 
 /**
  * Fetch an audio file from a URL and decode it into an `AudioBuffer`.

package/dist/buffer.js

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

package/dist/{chunk-T74FBKTY.js → chunk-2FGUFHZM.js}

@@ -51,5 +51,5 @@ function getBufferInfo(buffer) {
 }
 
 export { getBufferInfo, loadBuffer, loadBufferFromBlob, loadBuffers };
-//# sourceMappingURL=chunk-T74FBKTY.js.map
-//# sourceMappingURL=chunk-T74FBKTY.js.map
+//# sourceMappingURL=chunk-2FGUFHZM.js.map
+//# sourceMappingURL=chunk-2FGUFHZM.js.map

package/dist/{chunk-CPAT75WD.cjs → chunk-3VTU5OX5.cjs}

@@ -56,5 +56,5 @@ exports.getBufferInfo = getBufferInfo;
 exports.loadBuffer = loadBuffer;
 exports.loadBufferFromBlob = loadBufferFromBlob;
 exports.loadBuffers = loadBuffers;
-//# sourceMappingURL=chunk-CPAT75WD.cjs.map
-//# sourceMappingURL=chunk-CPAT75WD.cjs.map
+//# sourceMappingURL=chunk-3VTU5OX5.cjs.map
+//# sourceMappingURL=chunk-3VTU5OX5.cjs.map

package/dist/{chunk-2DL7CAEP.js → chunk-7JUVBZ6B.js}

@@ -65,5 +65,5 @@ function createClock(ctx, options) {
 }
 
 export { createClock, createScheduler };
-//# sourceMappingURL=chunk-2DL7CAEP.js.map
-//# sourceMappingURL=chunk-2DL7CAEP.js.map
+//# sourceMappingURL=chunk-7JUVBZ6B.js.map
+//# sourceMappingURL=chunk-7JUVBZ6B.js.map

package/dist/{chunk-D5CD5KQZ.cjs → chunk-BRS7LZVH.cjs}

@@ -68,5 +68,5 @@ function createClock(ctx, options) {
 
 exports.createClock = createClock;
 exports.createScheduler = createScheduler;
-//# sourceMappingURL=chunk-D5CD5KQZ.cjs.map
-//# sourceMappingURL=chunk-D5CD5KQZ.cjs.map
+//# sourceMappingURL=chunk-BRS7LZVH.cjs.map
+//# sourceMappingURL=chunk-BRS7LZVH.cjs.map

package/dist/{chunk-QWNV2BZ5.cjs → chunk-F6WXD3XW.cjs}

@@ -33,5 +33,5 @@ function createClickBuffer(ctx, frequency, duration) {
 exports.createClickBuffer = createClickBuffer;
 exports.createNoiseBuffer = createNoiseBuffer;
 exports.createSineBuffer = createSineBuffer;
-//# sourceMappingURL=chunk-QWNV2BZ5.cjs.map
-//# sourceMappingURL=chunk-QWNV2BZ5.cjs.map
+//# sourceMappingURL=chunk-F6WXD3XW.cjs.map
+//# sourceMappingURL=chunk-F6WXD3XW.cjs.map

package/dist/{chunk-C2ASIYN5.js → chunk-FESPIMZM.js}

@@ -7,10 +7,7 @@ function applyRamp(node, from, to, duration, curve) {
   param.setValueAtTime(from, now);
   switch (curve) {
     case "exponential":
-      param.exponentialRampToValueAtTime(
-        Math.max(to, EXP_MIN),
-        now + duration
-      );
+      param.exponentialRampToValueAtTime(Math.max(to, EXP_MIN), now + duration);
       break;
     case "equal-power": {
       const steps = Math.max(Math.ceil(duration * 100), 2);
@@ -23,7 +20,6 @@ function applyRamp(node, from, to, duration, curve) {
       param.setValueCurveAtTime(values, now, duration);
       break;
     }
-    case "linear":
     default:
       param.linearRampToValueAtTime(to, now + duration);
       break;
@@ -63,5 +59,5 @@ function autoFade(playback, gain, options) {
 }
 
 export { autoFade, crossfade, fadeIn, fadeOut };
-//# sourceMappingURL=chunk-C2ASIYN5.js.map
-//# sourceMappingURL=chunk-C2ASIYN5.js.map
+//# sourceMappingURL=chunk-FESPIMZM.js.map
+//# sourceMappingURL=chunk-FESPIMZM.js.map

package/dist/{chunk-GYH2JSCY.js → chunk-FY273Z3I.js}

@@ -38,5 +38,5 @@ function createEmitter() {
 }
 
 export { createEmitter };
-//# sourceMappingURL=chunk-GYH2JSCY.js.map
-//# sourceMappingURL=chunk-GYH2JSCY.js.map
+//# sourceMappingURL=chunk-FY273Z3I.js.map
+//# sourceMappingURL=chunk-FY273Z3I.js.map