dimastatz/whisper-flow

Whisper Flow – OpenAI Whisper を基盤としたリアルタイム音声認識

何ができるか – Whisper Flow は OpenAI Whisper の音声認識モデルを、WebSocket を通じてライブ音声ストリームを受け取り、部分的・最終的な認識結果を JSON 形式で返す軽量な FastAPI サービスでラップしています。通常はファイル全体を処理する Whisper を、低遅延のストリーミング ASR エンジンに変換します。

動作方法

• クライアントは ws://<host>:8181/ws を開き、バイナリフレームで 16 kHz、モノラル、int16 の PCM 音声を送信します。
• サーバーは受信したチャンクをバッファリングし、時間窓（タブリングウィンドウ）にグループ化して、各セグメントに対して Whisper を実行します。
• 各推論処理の後、JSON ペイロードが戻されます：

  {"is_partial": true|false, "data": {"text": "…"}, "time": <ms>}
  

  is_partial は、出力がまだ変更される可能性があるかどうかを示します。音声の停止、ウィンドウ制限の到達、またはクライアントが flush/stop コントロールフレームを送信したときに最終結果が発行されます。
• 小さな HTTP エンドポイント（GET /ready）は、プロトコルバージョンと利用可能な Whisper モデルファイルを報告します。

主要コンポーネント

モジュール	役割
whisperflow.transcriber	Whisper モデル（デフォルトは tiny.en.pt）を読み込み、同期（transcribe_pcm_chunks）および非同期（transcribe_pcm_chunks_async）のヘルパーを提供します。
whisperflow.streaming	TranscribeSession を実装し、クライアントごとの状態を管理し、音声チャンクをバッファリングし、トランスクリプターを呼び出し、WebSocket に JSON 結果を送信します。
FastAPI サーバー	WebSocket エンドポイント、ヘルスチェック（/health）、バッチ認識用 POST（/transcribe_pcm_chunk）を公開します。

導入方法

1. インストール – Python 3.8+、PortAudio（PyAudio 用）、その後 ./run.sh -local を実行します。これにより仮想環境が作成され、requirements.txt のインストール、フォーマット、Lint、テストスイートの実行が行われます。
2. 実行 – ./run.sh -run-server でポート 8181 でサービスを起動します。http://localhost:8181/health で確認してください。
3. 利用 – いずれかの方法で使用できます：WebSocket クライアントで PCM 音声ストリームを送信する、またはパッケージをインストール（pip install whisperflow）して README の例のようにライブラリを直接呼び出す。

パフォーマンス – Apple M1（16 GB RAM）上で LibriSpeech を用いたベンチマークでは、平均遅延は部分結果あたり約 275 ms、単語誤り率（WER）は約 7 % であり、1 秒未満のリアルタイム要件を満たしています。

デプロイオプション

• Docker – ./run.sh -docker でイメージ（whisperflow-image）をビルドし、ポート 8181 を公開するコンテナを実行します。
• Python パッケージ – ライブラリは他のプロジェクトにインポート可能で、カスタム WebSocket サーバーの構築や既存のパイプラインとの統合が可能です。

ロードマップ – v1.3 では、py‑speech エコシステム全体を通じてパッケージを公開することを目指しています。

---

すべての詳細はリポジトリの README から直接取得されています。