raspi-translator

English | 日本語

Raspberry Pi 4 を PC への USB オーディオデバイス(UAC2 ガジェット)として振る舞わせ、 PC とローカルの有線 USB ヘッドセットの間で 2 言語間リアルタイム同時通訳を行う中継アプライアンスにします。 翻訳は OpenAI gpt-realtime-translate または Google gemini-3.5-live-translate-preview（Web UI で切替）。 PC からはドライバ不要の「USB ヘッドセット」として見えるため、Zoom/Teams/Meet など任意の会議アプリで そのまま使えます。設定・運用は Web UI で完結します。

前提: 翻訳に OpenAI または Google(Gemini) の API キーが必要です。API 利用料は利用者の負担です （目安は docs/operations.md のコスト節）。キーはローカルの secrets.env に保存され、 リポジトリには含まれません。本ソフトは MIT ライセンス・無保証で提供されます（LICENSE）。

画面（Web UI）

スマホでは訳文を主役に、PC では原文と並べて表示。操作系は折りたたみパネルに集約しています。

主な機能

• 双方向リアルタイム同時通訳（方向ごとに常時接続。話しながら逐次翻訳）
• 翻訳プロバイダ切替（Web UI から）：OpenAI（gpt-realtime-translate、70+→13 言語。原文は gpt-realtime-whisper）と Gemini（gemini-3.5-live-translate-preview、70+→70+ 言語、プレビュー）を ⚙設定ページのセレクタで切替。選択は secrets.env に保存され再起動後も維持
• PC からドライバ不要：UAC2 全二重ガジェット。会議アプリで「RasPi Translator Audio」を選ぶだけ
• 原音パススルー（音量可変）＋ 訳音声中の自動ダッキング
• Web 通訳画面：字幕を主役にしたレイアウト。訳文優先表示＋原文トグル、操作系は折りたたみ操作パネル （音声/言語/モニター/記録にグループ化、スマホは既定で畳む）。送信状態バッジ・稼働/停止表示・⚙設定リンク
• モニター：訳音声を実機に返すセルフモニター（方向別・既定OFF）と、原音/訳を任意選択して ブラウザで試聴するブラウザモニター（端末ごとに独立・複数選択でミックス・再接続後も自動復元）
• アプリ名カスタマイズ：config.yaml の app.name（APP_NAME env でも可）でタイトル/左上見出しを変更
• 文字起こしログ：実機保存（logs/transcript-YYYYMMDD.log）＋ テキストエクスポート
• VAD：無音を送らず API 課金を削減（方向別しきい値、vad_calibrate.py で実測調整）
• システム設定ページ：電源（再起動/シャットダウン）、ネットワーク（nmcli: Wi‑Fi/有線）、 プロバイダ切替・API キー、IP 通知 Webhook（起動時/IP 変化時。Discord/Slack 対応。通知に WebUI への リンクを同梱しワンタップで開ける）
• セキュリティ：管理操作・WebSocket 制御を admin.token で保護（定数時間比較）、Host 検証で DNS rebinding を防止。本番は token 設定を推奨（operations.md §5.6）
• systemd 常駐：起動時にガジェット構成＋アプリ自動起動。再起動で ALSA カード番号が変わっても 名前一致でデバイス自動復帰

クイックスタート

常駐アプライアンス化（Pi 実機・一発） — OS 初期状態から自動構成（冪等）:

git clone <repo> ~/raspi-translator && cd ~/raspi-translator
sudo ./setup.sh          # 依存/ガジェット/systemd/sudoers/secrets を自動構成

詳細・環境変数は docs/setup.md。

開発/手動起動:

sudo apt install -y libportaudio2
cp config.yaml.example config.yaml   # 自分用の設定(git管理外)。編集して使う
python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt
python3 -m translator.main           # http://<piのIP>:8080 、設定は ⚙設定 から

config.yaml は git 管理外。リポジトリの config.yaml.example をコピーして使う（pull で競合しない）。

ドキュメント

はじめる

• docs/setup.md — セットアップ手順（ゼロ→常駐アプライアンス、これ一本）
• docs/hardware-bom.md — 調達品リスト(BOM)

使う・運用する

• docs/operations.md — 運用・管理（systemd/コスト/言語/プロバイダ切替/AEC/電源/設定ページ/Webhook）

仕組みを知る

• docs/architecture.md — アーキテクチャ（全体構成）
• docs/development/ — 開発経緯・設計記録（実現可能性検討 / Phase 0 PoC / DSP 設計）

構成

translator/
  config.py           設定(YAML + 環境変数)
  audioutil.py        変換 / resample / RingBuffer
  translate_client.py gpt-realtime-translate WS セッション(1方向=1本)
  gemini_client.py    Gemini Live API 翻訳セッション(provider: gemini 時)
  engine.py           2方向の配線・ミキシング・VAD/ダッキング/デバイス制御
  dsp.py              DelayLine / Ducker / RmsVadGate / VadGate(pre-roll)
  logstore.py         文字起こしログ(文単位整形・保存・エクスポート)
  admin.py            電源 / ネットワーク(nmcli) / APIキー / IP取得
  webhook.py          起動時・IP変化時の Webhook 通知(Discord/Slack対応)
  envfile.py          secrets.env の非破壊更新
  mock.py             実機なし UI 確認用エンジン(--mock)
  main.py             エントリポイント
  web/server.py       FastAPI: UI配信 + WS制御 + 管理API
  web/static/index.html      通訳画面
  web/static/settings.html   システム設定ページ
  web/static/favicon.svg     アイコン
docs/                ユーザー向け(setup/operations/hardware-bom)・architecture・development/(開発経緯)
scripts/
  usb-audio-gadget.sh / .service   UAC2 ガジェット構成 + systemd
  translator.service               アプリ常駐 systemd
  raspi-translator.env.example     APIキー env 雛形
  raspi-translator.sudoers         電源/nmcli の NOPASSWD 設定
  translate_test.py                翻訳疎通テスト(Phase0)
  vad_calibrate.py                 VAD しきい値キャリブレーション
tests/   unittest(numpy のみで実行可)
config.yaml.example  設定テンプレ(コピーして config.yaml に)  requirements.txt  requirements-dev.txt