Status Management

Stretcher は通常の playing / paused / stopped に加えて、buffering と buffer health という独自の状態管理を持ちます。チャンクの変換状況に応じて再生を一時停止・再開し、UI にバッファ状態を通知します。

Phase（再生状態）遷移

Stretcher の再生状態は 5 つの Phase で管理されます。

start()
  ↓
waiting ──→ buffering ──→ playing ←──→ paused
               ↑              │            │
               │              ↓            │
               └── underrun ──┘            │
                                           ↓
                              ended ←──────┘

Phase	説明
waiting	初期化中。チャンク分割が完了し、最初のバッファリングに入る直前
buffering	バッファ不足で再生を一時停止中。チャンク変換の完了を待っている
playing	再生中。チャンクプレーヤーが音声を出力している
paused	ユーザー操作による一時停止
ended	最終チャンクの再生が完了

通常の音楽プレーヤーと異なり、Stretcher にはリアルタイム変換に起因する buffering 状態があります。動画ストリーミングサービスのバッファリングと同じ考え方で、変換が再生に追いつかないとき（underrun）に自動的に一時停止し、十分なバッファが溜まったら再開します。

Buffer Health

Buffer Health は、再生位置から先にどれだけ変換済みチャンクがあるかを段階的に表します。

再生位置の前方に連続する変換済みチャンクを数え、その合計時間から健全性を 4 段階（healthy / low / critical / empty）で判定します。

チャンク:    [ready] [ready] [ready] [converting] [ready] [pending]
                                        ↑
                                   ここで停止

最初の未完了チャンクで計算が停止する点がポイントです。後方に飛び地で完了しているチャンクがあっても、再生には連続性が必要なため、健全性には含めません。

この段階的な指標を UI に公開することで、ユーザーに対して適切なフィードバック（バッファ状態の表示や警告）を提供できます。

ヒステリシスによるフリッカー防止

バッファリングの開始と終了に同じ閾値を使うと、バッファが閾値付近で揺れたときに状態が高速で切り替わります（フリッカー問題）。

Buffer seconds
  30 ─── healthy ───────────────────
  10 ─── low ───────────────────────
   5 ─── ← exit buffering ─────────   ↑ ヒステリシス幅
   3 ─── ← enter buffering ────────   ↓
   0 ─── empty ────────────────────

開始閾値と終了閾値をずらすヒステリシスを設けることで、バッファがこの範囲内で揺れても状態が安定します。一度バッファリングに入ったら、開始閾値より高い終了閾値を超えるまで抜けません。

これはサーモスタットの温度制御と同じ原理です。「暑くなったら冷房を入れ、十分涼しくなったら止める」というように、開始と終了に余裕を持たせて頻繁な ON/OFF を防ぎます。

Buffering Reason

バッファリングに入った理由は buffering イベントで通知されます。

Reason	説明
initial	初回再生開始前のバッファリング
seek	Seek 先のチャンクが未変換
tempo-change	テンポ変更で既存チャンクが無効化
underrun	再生が変換に追いついてしまった

UI では reason に応じてメッセージを出し分けることができます。例えば initial では「読み込み中…」、underrun では「バッファリング中…」など、ユーザーにとって意味のあるフィードバックを提供できます。

イベント

Stretcher は再生状態やバッファ状況の変化をイベントとして発行します。

イベント	説明
buffering	バッファリング開始（reason 付き）
buffered	バッファリング終了（待機時間付き）
chunkready	チャンク変換完了
progress	変換進捗更新
bufferhealth	バッファ健全性更新
complete	全チャンク変換完了
ended	再生完全終了
error	変換エラー