# 設計書

概要
- 本設計書はアプリケーションのアーキテクチャ、主要コンポーネント、並列化モデル、エラー処理ポリシー、設定の保存方針を記述する。

アーキテクチャ概要
- 層構造
  - mainloop: stdin ベースのコマンド受け取り、ワーカー（複数スレッド）で実行。
  - controller: GUI/フロントエンドからの操作とモデルの仲介。`Controller` がビジネスロジックを実行。
  - model: 実際の機能（翻訳、文字起こし、オーバーレイ、OSC、WebSocket、デバイス管理）を提供するファサード的シングルトン。
  - models/*: 翻訳、文字起こしなどのドメイン別実装（Translator, AudioTranscriber, Overlay, WebSocketServer ...）。
  - device_manager: 音声デバイス検出・監視（Windows の場合は WASAPI/pycaw を利用）。
  - utils: 共通ユーティリティ（ロギング、ネットワークチェック、compute device 列挙など）。

初期化ポリシー
- 重い初期化（GPU モデルロード、OpenVR 初期化など）は import 時に行わず、`model.init()` か要求時の `ensure_initialized()` にて遅延実行。
- `DeviceManager` は import 時に軽量な init を行い、監視スレッドは `startMonitoring()` で開始する。

並列化・同期モデル
- mainloop.Main は 1 つの受信スレッド（stdin 읽取り）と N 個のハンドラワーカースレッドを持つ。
- 各リクエストはキューに入れられ、handler() により処理される。
- 有効/無効の切替（/set/enable/**, /set/disable/**）は同一リソースを競合しないよう正規化キーで Lock を割り当てる。
- モデル内部では threadFnc（Thread ラッパ）で周期的な送信処理や監視処理を実装。
- Audio 録音や文字起こしは専用の Queue を用い、Producer（Recorder）と Consumer（AudioTranscriber）を分離。

エラー処理
- すべての外周呼び出しは try/except で保護し、`utils.errorLogging()` によってトレースバックを error.log に出力する。
- JSON シリアライズに失敗した場合はフォールバック JSON を stdout に出力してプロセスを止めない。
- VRAM 関連のエラーは model.detectVRAMError() で判定し、該当する機能（翻訳等）を無効化してユーザーに通知する。

設定管理
- `config.py` が単一の Config シングルトンを持ち、変更はデバウンスして JSON ファイルへ保存。
- GUI からの操作は Controller が受け取り、Config を更新する。

ログ
- `utils.setupLogger` によりローテートファイルハンドラを使ったログを実装（process.log / error.log）。
- stdout には構造化ログを出力してフロントエンドと通信する。

インターフェース一覧（抜粋）
- STDIN/STDOUT プロトコル: mainloop の JSON 入出力（詳細は `mainloop.py` の mapping を参照）
- OSC: `models.osc.OSCHandler` が OSC 送受信と OSCQuery を管理
- WebSocket: `models.websocket.WebSocketServer` がクライアント管理とメッセージブロードキャストを担う

スレッド図（要点）
- main_thread: メイン（stdin 読み取り、キュー投入）
- handler_threads: キューから取り出し処理
- device_manager.th_monitoring: デバイス監視
- model.mic_print_transcript / speaker_print_transcript: 音声 -> 翻訳結果送出のループ
- websocket_server_thread: WebSocket サーバの asyncio ループを別スレッドで実行

拡張性・互換性設計
- 依存性は try/except でガードして optional 機能として扱う（例: faster-whisper が無くても import は成功する）。
- 翻訳エンジンは backend 名で抽象化され、Translator クラスにより統一インターフェースを提供。

運用上の考慮
- 大きなモデルファイル（Whisper, CTranslate2）をダウンロードする仕組みを持ち、進捗を GUI に報告する。
- GPU 計算タイプは utils.getBestComputeType で選択し、不適切な設定を検出した場合はフォールバック。