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.
58 lines
4.1 KiB
Markdown
58 lines
4.1 KiB
Markdown
# 設計書
|
||
|
||
概要
|
||
- 本設計書はアプリケーションのアーキテクチャ、主要コンポーネント、並列化モデル、エラー処理ポリシー、設定の保存方針を記述する。
|
||
|
||
アーキテクチャ概要
|
||
- 層構造
|
||
- 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 で選択し、不適切な設定を検出した場合はフォールバック。
|