Add documentation and coding guidelines for VRCT backend

- 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.
This commit is contained in:
misyaguziya
2025-10-13 22:55:48 +09:00
parent d4f89a734d
commit fcb1295302
43 changed files with 5829 additions and 2956 deletions

View File

@@ -0,0 +1,57 @@
# 設計書
概要
- 本設計書はアプリケーションのアーキテクチャ、主要コンポーネント、並列化モデル、エラー処理ポリシー、設定の保存方針を記述する。
アーキテクチャ概要
- 層構造
- 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 を割り当てる。
- モデル内部では threadFncThread ラッパ)で周期的な送信処理や監視処理を実装。
- Audio 録音や文字起こしは専用の Queue を用い、ProducerRecorderと ConsumerAudioTranscriberを分離。
エラー処理
- すべての外周呼び出しは 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 で選択し、不適切な設定を検出した場合はフォールバック。