VRCT/src-python/docs/modules/controller.md

Controller クラス仕様書

概要

• Controller はアプリケーションのコントロール層（Facade）で、model と device_manager、および外部 UI / mainloop とを仲介します。
• UI からのコマンドを受け取り、model の開始/停止、設定の変更、ダウンロードの開始、各種フラグの切り替え、進捗通知（run コールバック経由）を行います。
• 多くのメソッドは JSON 系の応答オブジェクトを返します: {"status": int, "result": Any}。副作用で self.run(status, run_mapping[key], payload) を呼び出して UI に通知します。

初期化とランタイムフック

• init() -> None
  • フィールド: init_mapping: dict, run_mapping: dict, run: Callable, device_access_status: bool
  • setInitMapping(init_mapping: dict) / setRunMapping(run_mapping: dict) / setRun(run: Callable) で mainloop からマッピング・コールバックを注入されることを想定。

コールバック通知用メソッド（UI への通知）

• connectedNetwork() / disconnectedNetwork() -> None
• enableAiModels() / disableAiModels() -> None
• updateMicHostList() / updateMicDeviceList() / updateSpeakerDeviceList() -> None
• updateConfigSettings() -> None
  • これらは self.run(status, run_mapping[key], payload) を使って UI にイベントを送ります。

ダウンロード用ヘルパークラス

• class DownloadCTranslate2(run_mapping: dict, weight_type: str, run: Callable)
  • progressBar(progress: float) -> None
  • downloaded() -> None
• class DownloadWhisper(run_mapping: dict, weight_type: str, run: Callable)
  • progressBar(progress: float) -> None
  • downloaded() -> None

音声・翻訳イベントハンドラ

• micMessage(result: dict) -> None

  • 引数: result: {"text": str|False, "language": str}
  • 挙動: ワードフィルタ、繰り返し検出、翻訳（model.getInputTranslate）、音声送信（OSC）・オーバーレイ更新・WebSocket ブロードキャスト等を行う。
  • エラー: 翻訳中に VRAM OOM が起きた場合は model.detectVRAMError を使って検出し、翻訳機能を無効化して UI に 400 を通知。

• speakerMessage(result: dict) -> None

  • 引数: result: {"text": str|False, "language": str}
  • micMessage と同様だが、受信（speaker）側のロジックやオーバーレイの扱いが異なる。

• chatMessage(data: dict) -> dict

  • 引数: {"id": Any, "message": str}
  • 戻り値: {"status": int, "result": {"id":..., "original":..., "translations":[...]}}
  • 挙動詳細:
    • 翻訳処理は model.getInputTranslate を呼び出します。翻訳処理中に VRAM 関連の例外が発生した場合、model.detectVRAMError によって検出し、翻訳機能を自動で無効化します。
    • VRAM エラー検出時は Controller は UI に対して 400 系の run イベントを発行する（例: error_translation_chat_vram_overflow, enable_translation で無効化通知）。
    • エラー発生時の戻り値: 翻訳を行わずに基本情報を含む 200 応答を返すコードパスがあり、クライアント側でのハンドリングを想定しています。

設定取得/変更系メソッド（代表例）

• getVersion() -> {"status":200, "result": config.VERSION}
• getComputeMode() / getComputeDeviceList() / getSelectedTranslationComputeDevice() -> dict
• setSelectedTranslationComputeDevice(device: str) -> {"status":200, "result": device}
• getSelectableCtranslate2WeightTypeDict() -> dict
• setEnableTranslation() / setDisableTranslation() -> dict
  • setEnableTranslation はモデルロード時に VRAM エラーを検知するロジックを内包している。
  • 多くの setXXX / getXXX メソッドは config を直接操作して即時反映する。

自動デバイス選択

• applyAutoMicSelect() / applyAutoSpeakerSelect()
  • device_manager にコールバックを登録して自動選択を有効化する。

トランスクリプション制御（スレッドで実行）

• startTranscriptionSendMessage() / stopTranscriptionSendMessage() / startThreadingTranscriptionSendMessage() / stopThreadingTranscriptionSendMessage()
• startTranscriptionReceiveMessage() / stopTranscriptionReceiveMessage() / startThreadingTranscriptionReceiveMessage() / stopThreadingTranscriptionReceiveMessage()
  • 実際の処理は model.startMicTranscript / model.startSpeakerTranscript に委譲される。VRAM エラーは検出して UI に通知し、自動的に停止する処理あり。

閾値・チェック系

• startCheckMicEnergy() / stopCheckMicEnergy() / startThreadingCheckMicEnergy() / stopThreadingCheckMicEnergy()
• startCheckSpeakerEnergy() / stopCheckSpeakerEnergy() / startThreadingCheckSpeakerEnergy() / stopThreadingCheckSpeakerEnergy()

ダウンロード開始（非同期/同期）

• downloadCtranslate2Weight(data: str, asynchronous: bool=True) -> dict
• downloadWhisperWeight(data: str, asynchronous: bool=True) -> dict
  • 非同期なら別スレッドでダウンロードを行い progressBar コールバックを経由して UI に進捗を返す。

Watchdog / WebSocket / OSC 周り

• startWatchdog() / feedWatchdog() / stopWatchdog()
• getWebSocketHost() / setWebSocketHost(data) -> dict
• setEnableWebSocketServer() / setDisableWebSocketServer()
• setOscIpAddress(data) / setOscPort(data)
  • ネットワーク周りの設定は検証ロジック（IP アドレス検証、サーバー利用可否のチェック）を含む。

ユーティリティ関数

• messageFormatter(format_type: str, translation: list, message: str) -> str
  • OSC に送る文面のフォーマットを生成（設定に基づく）。
• replaceExclamationsWithRandom(text) -> (str, dict)
• restoreText(escaped_text, escape_dict) -> str
• removeExclamations(text) -> str

重要な戻り値規約

• 成功: {"status": 200, "result": ...}
• 失敗: {"status": 400, "result": {"message": str, "data": Any}}
• 多くのメソッドは UI への通知として self.run(status, run_mapping[key], payload) を行う。

エッジケース / エラー処理

• VRAM OOM 検出: モデル例外が上がると model.detectVRAMError(e) を呼び出し、VRAM エラーが検出された場合は関連機能を自動で無効化して UI に 400 を通知する。
• デバイスアクセスの競合: device_access_status による簡易ロックで、デバイス操作中は待機する。
• ネットワーク依存: DeepL 等の外部翻訳 API 利用可否は model.authenticationTranslatorDeepLAuthKey で検査し、無効時は選択肢を更新する。

呼び出し例（Python から直接）

from controller import Controller
ctrl = Controller()
# run コールバックの例: (status:int, event_name:str, payload:any)
def ui_run(status, event, payload):
    print(status, event, payload)

ctrl.setRun(ui_run)
resp = ctrl.setEnableTranslation()
print(resp)  # {'status':200, 'result': True}

data = {"id": 123, "message": "Hello"}
resp = ctrl.chatMessage(data)
print(resp)

シーケンス図（簡易: マイク入力 -> 翻訳 -> UI 通知）

sequenceDiagram
    participant UI
    participant Mainloop
    participant Controller
    participant Model

    UI->>Mainloop: ユーザ操作 (send message)
    Mainloop->>Controller: chatMessage(data)
    Controller->>Model: getInputTranslate(message)
    Model-->>Controller: translation
    Controller->>Model: oscSendMessage(...)
  Controller->>UI: run(200, run_mapping['transcription_send_mic_message'], payload)

次の作業

• docs/api.md を mainloop.py のマッピングに基づいて拡張し、各エンドポイントの request/response 例を追加してください。

参考: 実装詳細は src-python/controller.py を参照してください（メソッドごとに細かな条件分岐や run_mapping キーが存在します）。

controller.py — 詳細設計

目的: UI（または外部プロセス）からの操作を受け、config と model を操作して副作用を生じさせるコマンド層。

主要クラス/関数:

• class Controller

  • 属性:

    • init_mapping: アプリ起動時の読み出し用マッピング（/get/data/*）
    • run_mapping: イベント通知先のエンドポイントマップ（run 関数で使用）
    • run: run(status, endpoint, result) を格納

  • 主要メソッド:

    • setEnableTranslation / setDisableTranslation: 翻訳機能の切替（モデル切替や VRAM エラー回復処理を含む）
    • start/stop transcription/energy checks: Model の startMicTranscript 等を呼ぶ
    • downloadCtranslate2Weight / downloadWhisperWeight: ダウンロードを非同期で開始し進捗を run 経由で通知
    • micMessage / speakerMessage / chatMessage: 認識結果を受け、翻訳/OSC/Overlay/WebSocket/ログ記録を行う主要ハンドラ
    • messageFormatter: OSC 用メッセージ整形
    • 多数の get/set 系関数: config の各種設定を読み書きし status/result を返す

エラー/例外:

• VRAM 関連は特に注意し、検出時は該当機能を無効化してユーザーへ通知する。

API マッピング:

• mainloop.py の mapping と連携しており、多くの /get/data/* /set/data/* /run/* が Controller のメソッドにマッピングされる（詳細は docs/api.md を参照）。