fcb1295302
- Introduced a comprehensive coding rules document outlining naming conventions, module structure, import order, type annotations, error handling, and testing practices. - Created a specification document detailing project goals, target users, and functional/non-functional requirements for the VRCT project. - Added a design document describing the application's architecture, initialization policies, concurrency models, and error handling strategies. - Included a detailed design document specifying major classes, functions, data structures, and exception handling. - Removed outdated mypy configuration and several unused scripts related to documentation verification and cleanup. - Deleted test files for OSC and overlay imports as part of the cleanup process.
4.1 KiB
4.1 KiB
設計書
概要
- 本設計書はアプリケーションのアーキテクチャ、主要コンポーネント、並列化モデル、エラー処理ポリシー、設定の保存方針を記述する。
アーキテクチャ概要
- 層構造
- 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 で選択し、不適切な設定を検出した場合はフォールバック。