Add documentation for modules and runtime instructions

- Created detailed documentation for the device_manager, model, model_extra, osc, overlay, overlay_image, transcription, translation, transliteration, utils, watchdog, and websocket modules. - Added a comprehensive run events payloads document outlining the payloads sent during various run events in the controller. - Included runtime instructions and dependencies for setting up the project in a Windows environment. - Introduced a mypy configuration file to manage type checking and ignore errors in specific modules temporarily.
2025-10-09 13:11:59 +09:00
parent b0fd63afbd
commit 5efa9c37d6
23 changed files with 2147 additions and 0 deletions
--- a/src-python/docs/modules/config.md
+++ b/src-python/docs/modules/config.md
@@ -0,0 +1,203 @@
+# config.py クラス仕様書
+
+目的: アプリケーションの全設定を集中管理するシングルトン `config`（クラス名: `Config`、インスタンス: `config`）。
+
+特徴:
+- JSON シリアライズ対象のプロパティには `@json_serializable('KEY_NAME')` デコレータが付いており、`load_config()` / `saveConfig()` によって `config.json` に永続化されます。
+- プロパティは「読み取り専用 (Read Only)」と「読み書き (Read/Write)」に分類されます。読み書き可能なプロパティはバリデーション処理とともに setter が用意されています。
+- 設定は内部的に `_config_data` に保持され、`saveConfig()` はデバウンス（2秒）でファイルへ書き込みます。即時書き込みオプションも可能です（saveConfig(..., immediate_save=True)）。
+
+## 生成とライフサイクル
+- `Config()` はシングルトン（__new__ で単一インスタンスを生成）。
+- `init_config()` でデフォルト値を初期化し、その後 `load_config()` が `config.json` を読み込んで既存値を適用します。
+
+## 主要プロパティ一覧（型・デフォルト・説明）
+
+注: 下は `config.py` の初期化ロジックに基づく抜粋です。`json_serializable` が付与されたキーは `config.json` に書き出されます。
+
+- Read only
+  - `VERSION` (str) = "3.2.2"
+  - `PATH_LOCAL` (str) = フォロー実行ファイルのディレクトリか、ソースの __file__ のディレクトリ
+  - `PATH_CONFIG` (str) = PATH_LOCAL/config.json
+  - `PATH_LOGS` (str) = PATH_LOCAL/logs
+  - `GITHUB_URL`, `UPDATER_URL`, `BOOTH_URL`, `DOCUMENTS_URL`, `DEEPL_AUTH_KEY_PAGE_URL` (str)
+  - `MAX_MIC_THRESHOLD` (int) = 2000
+  - `MAX_SPEAKER_THRESHOLD` (int) = 4000
+  - `WATCHDOG_TIMEOUT` (int) = 60
+  - `WATCHDOG_INTERVAL` (int) = 20
+  - `SELECTABLE_*` 系: 各種選択肢のリスト/イテレータ（モデルの重みや言語、UI 言語等）。
+
+- Read/Write（主な項目）
+  - `SEND_MESSAGE_FORMAT_PARTS` (dict) = デフォルトで message/translation/translation_first 等を含むフォーマット定義。json_serializable キー: 'SEND_MESSAGE_FORMAT_PARTS'
+  - `RECEIVED_MESSAGE_FORMAT_PARTS` (dict)
+  - `ENABLE_TRANSLATION` (bool) = False
+  - `ENABLE_TRANSCRIPTION_SEND` (bool) = False
+  - `ENABLE_TRANSCRIPTION_RECEIVE` (bool) = False
+  - `ENABLE_FOREGROUND` (bool) = False
+  - `ENABLE_CHECK_ENERGY_SEND` (bool) = False
+  - `ENABLE_CHECK_ENERGY_RECEIVE` (bool) = False
+  - `SELECTABLE_CTRANSLATE2_WEIGHT_TYPE_DICT` (dict) = {<weight_type>: False, ...}
+  - `SELECTABLE_WHISPER_WEIGHT_TYPE_DICT` (dict)
+  - `SELECTABLE_TRANSLATION_ENGINE_STATUS` (dict)
+  - `SELECTABLE_TRANSCRIPTION_ENGINE_STATUS` (dict)
+  - `SELECTED_TAB_NO` (str) = "1" (json_serializable: 'SELECTED_TAB_NO')
+  - `SELECTED_TRANSLATION_ENGINES` (dict) = tab毎に選択 ('CTranslate2' 等)
+  - `SELECTED_YOUR_LANGUAGES`, `SELECTED_TARGET_LANGUAGES` (dict) = 翻訳元/先の選択と有効フラグ
+  - `SELECTED_TRANSCRIPTION_ENGINE` (str) = 'Google'
+  - `CONVERT_MESSAGE_TO_ROMAJI` / `CONVERT_MESSAGE_TO_HIRAGANA` (bool)
+  - UI 設定: `TRANSPARENCY` (int), `UI_SCALING` (int), `TEXTBOX_UI_SCALING` (int), `MESSAGE_BOX_RATIO` (int)
+  - `SEND_MESSAGE_BUTTON_TYPE` (str) = 'show'（候補は SEND_MESSAGE_BUTTON_TYPE_LIST）
+  - `SHOW_RESEND_BUTTON` (bool)
+  - `FONT_FAMILY` (str) = 'Yu Gothic UI'
+  - `UI_LANGUAGE` (str) = 'en'（候補は SELECTABLE_UI_LANGUAGE_LIST）
+  - `MAIN_WINDOW_GEOMETRY` (dict) = {x_pos, y_pos, width, height}
+  - マイク/スピーカー関係: `AUTO_MIC_SELECT`, `SELECTED_MIC_HOST`, `SELECTED_MIC_DEVICE`, `MIC_THRESHOLD`, `MIC_AUTOMATIC_THRESHOLD`, `MIC_RECORD_TIMEOUT`, `MIC_PHRASE_TIMEOUT`, `MIC_MAX_PHRASES`, `MIC_WORD_FILTER`, `HOTKEYS` 等
+  - `PLUGINS_STATUS` (list)
+  - マイク転写確度閾値: `MIC_AVG_LOGPROB`, `MIC_NO_SPEECH_PROB`
+  - スピーカー関連（同様の項目）: `AUTO_SPEAKER_SELECT`, `SELECTED_SPEAKER_DEVICE`, `SPEAKER_THRESHOLD`, ...
+  - `OSC_IP_ADDRESS` (str) = '127.0.0.1'
+  - `OSC_PORT` (int) = 9000
+  - `AUTH_KEYS` (dict) = {'DeepL_API': None}
+  - `USE_EXCLUDE_WORDS` (bool) = True
+  - 計算デバイス選択: `SELECTED_TRANSLATION_COMPUTE_DEVICE` / `SELECTED_TRANSCRIPTION_COMPUTE_DEVICE`（`getComputeDeviceList()` に基づくデバイス辞書）
+  - 重み/計算タイプ: `CTRANSLATE2_WEIGHT_TYPE`, `WHISPER_WEIGHT_TYPE`, `SELECTED_TRANSLATION_COMPUTE_TYPE`, `SELECTED_TRANSCRIPTION_COMPUTE_TYPE`
+  - オーバーレイ設定: `OVERLAY_SMALL_LOG`, `OVERLAY_SMALL_LOG_SETTINGS`, `OVERLAY_LARGE_LOG`, `OVERLAY_LARGE_LOG_SETTINGS`, `OVERLAY_SHOW_ONLY_TRANSLATED_MESSAGES` 等
+  - VRC/ログ/WebSocket: `SEND_MESSAGE_TO_VRC`, `SEND_RECEIVED_MESSAGE_TO_VRC`, `LOGGER_FEATURE`, `VRC_MIC_MUTE_SYNC`, `NOTIFICATION_VRC_SFX`, `WEBSOCKET_SERVER`, `WEBSOCKET_HOST`, `WEBSOCKET_PORT`
+
+# config.py — 完全上書きドキュメント
+
+目的: アプリケーションの全設定を集中管理するシングルトン `config`（クラス名: `Config`、インスタンス: `config`）。
+
+特徴:
+- JSON シリアライズ対象のプロパティには `@json_serializable('KEY_NAME')` デコレータが付いており、`load_config()` / `saveConfig()` によって `config.json` に永続化されます。
+- プロパティは「読み取り専用 (Read Only)」と「読み書き (Read/Write)」に分類されます。読み書き可能なプロパティはバリデーション処理とともに setter が用意されています。
+- 設定は内部的に `_config_data` に保持され、`saveConfig()` はデバウンス（2秒）でファイルへ書き込みます。即時書き込みオプションも可能です（saveConfig(..., immediate_save=True)）。
+
+## 生成とライフサイクル
+- `Config()` はシングルトン（__new__ で単一インスタンスを生成）。
+- `init_config()` でデフォルト値を初期化し、その後 `load_config()` が `config.json` を読み込んで既存値を適用します。
+
+## 主要プロパティ一覧（型・デフォルト・説明）
+
+注: 下は `config.py` の初期化ロジックに基づく抜粋です。`json_serializable` が付与されたキーは `config.json` に書き出されます。
+
+- Read only
+  - `VERSION` (str) = "3.2.2"
+  - `PATH_LOCAL` (str) = フォロー実行ファイルのディレクトリか、ソースの __file__ のディレクトリ
+  - `PATH_CONFIG` (str) = PATH_LOCAL/config.json
+  - `PATH_LOGS` (str) = PATH_LOCAL/logs
+  - `GITHUB_URL`, `UPDATER_URL`, `BOOTH_URL`, `DOCUMENTS_URL`, `DEEPL_AUTH_KEY_PAGE_URL` (str)
+  - `MAX_MIC_THRESHOLD` (int) = 2000
+  - `MAX_SPEAKER_THRESHOLD` (int) = 4000
+  - `WATCHDOG_TIMEOUT` (int) = 60
+  - `WATCHDOG_INTERVAL` (int) = 20
+  - `SELECTABLE_*` 系: 各種選択肢のリスト/イテレータ（モデルの重みや言語、UI 言語等）。
+
+- Read/Write（主な項目）
+  - `SEND_MESSAGE_FORMAT_PARTS` (dict) = デフォルトで message/translation/translation_first 等を含むフォーマット定義。json_serializable キー: 'SEND_MESSAGE_FORMAT_PARTS'
+  - `RECEIVED_MESSAGE_FORMAT_PARTS` (dict)
+  - `ENABLE_TRANSLATION` (bool) = False
+  - `ENABLE_TRANSCRIPTION_SEND` (bool) = False
+  - `ENABLE_TRANSCRIPTION_RECEIVE` (bool) = False
+  - `ENABLE_FOREGROUND` (bool) = False
+  - `ENABLE_CHECK_ENERGY_SEND` (bool) = False
+  - `ENABLE_CHECK_ENERGY_RECEIVE` (bool) = False
+  - `SELECTABLE_CTRANSLATE2_WEIGHT_TYPE_DICT` (dict) = {<weight_type>: False, ...}
+  - `SELECTABLE_WHISPER_WEIGHT_TYPE_DICT` (dict)
+  - `SELECTABLE_TRANSLATION_ENGINE_STATUS` (dict)
+  - `SELECTABLE_TRANSCRIPTION_ENGINE_STATUS` (dict)
+  - `SELECTED_TAB_NO` (str) = "1" (json_serializable: 'SELECTED_TAB_NO')
+  - `SELECTED_TRANSLATION_ENGINES` (dict) = tab毎に選択 ('CTranslate2' 等)
+  - `SELECTED_YOUR_LANGUAGES`, `SELECTED_TARGET_LANGUAGES` (dict) = 翻訳元/先の選択と有効フラグ
+  - `SELECTED_TRANSCRIPTION_ENGINE` (str) = 'Google'
+  - `CONVERT_MESSAGE_TO_ROMAJI` / `CONVERT_MESSAGE_TO_HIRAGANA` (bool)
+  - UI 設定: `TRANSPARENCY` (int), `UI_SCALING` (int), `TEXTBOX_UI_SCALING` (int), `MESSAGE_BOX_RATIO` (int)
+  - `SEND_MESSAGE_BUTTON_TYPE` (str) = 'show'（候補は SEND_MESSAGE_BUTTON_TYPE_LIST）
+  - `SHOW_RESEND_BUTTON` (bool)
+  - `FONT_FAMILY` (str) = 'Yu Gothic UI'
+  - `UI_LANGUAGE` (str) = 'en'（候補は SELECTABLE_UI_LANGUAGE_LIST）
+  - `MAIN_WINDOW_GEOMETRY` (dict) = {x_pos, y_pos, width, height}
+  - マイク/スピーカー関係: `AUTO_MIC_SELECT`, `SELECTED_MIC_HOST`, `SELECTED_MIC_DEVICE`, `MIC_THRESHOLD`, `MIC_AUTOMATIC_THRESHOLD`, `MIC_RECORD_TIMEOUT`, `MIC_PHRASE_TIMEOUT`, `MIC_MAX_PHRASES`, `MIC_WORD_FILTER`, `HOTKEYS` 等
+  - `PLUGINS_STATUS` (list)
+  - マイク転写確度閾値: `MIC_AVG_LOGPROB`, `MIC_NO_SPEECH_PROB`
+  - スピーカー関連（同様の項目）: `AUTO_SPEAKER_SELECT`, `SELECTED_SPEAKER_DEVICE`, `SPEAKER_THRESHOLD`, ...
+  - `OSC_IP_ADDRESS` (str) = '127.0.0.1'
+  - `OSC_PORT` (int) = 9000
+  - `AUTH_KEYS` (dict) = {'DeepL_API': None}
+  - `USE_EXCLUDE_WORDS` (bool) = True
+  - 計算デバイス選択: `SELECTED_TRANSLATION_COMPUTE_DEVICE` / `SELECTED_TRANSCRIPTION_COMPUTE_DEVICE`（`getComputeDeviceList()` に基づくデバイス辞書）
+  - 重み/計算タイプ: `CTRANSLATE2_WEIGHT_TYPE`, `WHISPER_WEIGHT_TYPE`, `SELECTED_TRANSLATION_COMPUTE_TYPE`, `SELECTED_TRANSCRIPTION_COMPUTE_TYPE`
+  - オーバーレイ設定: `OVERLAY_SMALL_LOG`, `OVERLAY_SMALL_LOG_SETTINGS`, `OVERLAY_LARGE_LOG`, `OVERLAY_LARGE_LOG_SETTINGS`, `OVERLAY_SHOW_ONLY_TRANSLATED_MESSAGES` 等
+  - VRC/ログ/WebSocket: `SEND_MESSAGE_TO_VRC`, `SEND_RECEIVED_MESSAGE_TO_VRC`, `LOGGER_FEATURE`, `VRC_MIC_MUTE_SYNC`, `NOTIFICATION_VRC_SFX`, `WEBSOCKET_SERVER`, `WEBSOCKET_HOST`, `WEBSOCKET_PORT`
+
+## セッタのバリデーション
+- 多くの setter は型チェックと候補値チェック（リストや辞書のキー整合性）を行います。例:
+  - `SELECTED_MIC_DEVICE` は `device_manager.getMicDevices()` の一覧に存在する名前であること。
+  - `SELECTED_TRANSLATION_COMPUTE_TYPE` は `SELECTED_TRANSLATION_COMPUTE_DEVICE['compute_types']` に含まれる文字列であること。
+  - UI 関連の集合は `SELECTABLE_UI_LANGUAGE_LIST` などの一覧に従う。
+
+## 永続化の詳細
+- `load_config()` は `config.json` が存在し、かつ中身がある場合に読み込みを試み、ファイル中のキーを `setattr(self, key, value)` して既存の setter を利用して適用します。
+- 読み込み後、`json_serializable` 指定された全キーを `_config_data` に書き戻し、ファイルを上書き（常に書く）。
+
+## 使い方の例
+
+以下は `config` を使った典型的なコード例です。
+
+```python
+from config import config
+
+# 値の参照
+print('App version:', config.VERSION)
+print('Current UI language:', config.UI_LANGUAGE)
+
+# 値の更新（setter を通す）
+config.UI_LANGUAGE = 'ja'
+config.SEND_MESSAGE_TO_VRC = False
+
+# 複雑な dict を設定する例（メッセージフォーマットを上書き）
+config.SEND_MESSAGE_FORMAT_PARTS = {
+    'message': {'prefix': '[YOU] ', 'suffix': ''},
+    'separator': '\n',
+    'translation': {'prefix': '[TR] ', 'separator': '\n', 'suffix': ''},
+    'translation_first': True,
+}
+
+# 即時保存したい場合（即座に config.json を上書き）
+config.saveConfig('CUSTOM_SAVE', {'foo': 'bar'}, immediate_save=True)
+```
+
+## エッジケース / 注意点
+- `load_config()` はファイル値を setter 経由で当てはめるため、ファイルに古いキーや予期しない型があると setter によって無視されることがあります（例: 言語キーが不正の場合）。
+- `saveConfig()` はデバウンスされるため、高頻度の設定変更では複数の変更がまとめて書き込まれます。即時書き込みが必要な操作（重要な鍵の更新など）は `immediate_save=True` を使ってください。
+- `SELECTABLE_*` 系や `*_DICT` 系は初期化時に外部モジュール（翻訳リソース、whisper_models、device_manager 等）から生成されます。これらが利用できない環境ではデフォルトが空になる可能性があります。
+
+## 推奨改善点（将来的なドキュメント／実装）
+- 設定スキーマを JSON Schema で定義し、load 時の検証を明確化すると安全性が向上します。
+- 設定変更イベントを発火する仕組み（observer パターン）を導入すると、Controller/Model 側の再初期化処理をより明確に実装できます。
+
+---
+
+このファイルは `config.py` の実装に基づいて自動生成的に作成されたドキュメント（overwrite）です。実装の微細な差分は `config.py` を参照してください。
+
+## 詳細設計
+
+目的: アプリケーションの全設定を保持するシングルトン `config`。
+
+ポイント:
+- JSON シリアライズ可能な設定値には `@json_serializable` デコレータが付与され、save 操作でファイルへ書き出される。
+- 多数のプロパティが定義され、読み取り専用 (Read Only) と 読み書き (Read/Write) が混在する。
+- 設定項目の例:
+  - ENABLE_TRANSLATION, ENABLE_TRANSCRIPTION_SEND, ENABLE_TRANSCRIPTION_RECEIVE
+  - SELECTED_MIC_HOST, SELECTED_MIC_DEVICE, SELECTED_SPEAKER_DEVICE
+  - SELECTED_TRANSLATION_ENGINES, SELECTED_YOUR_LANGUAGES, SELECTED_TARGET_LANGUAGES
+  - PATH_LOCAL, PATH_LOGS, VERSION, GITHUB_URL, UPDATER_URL
+  - SELECTABLE_CTRANSLATE2_WEIGHT_TYPE_DICT / SELECTABLE_WHISPER_WEIGHT_TYPE_DICT
+  - COMPUTE 関連: SELECTABLE_COMPUTE_DEVICE_LIST, SELECTED_TRANSLATION_COMPUTE_DEVICE, SELECTED_TRANSCRIPTION_COMPUTE_DEVICE
+
+設計上の契約:
+- 全ての get/set は辞書形で status/result を返す Controller の呼び出しに合わせて変換される。
+- 外部から設定を変更した際は必要に応じて Model/Controller による再初期化処理を呼ぶ。
+
+検討事項:
+- 現状は設定変更が即時反映されるが、一部操作は再初期化（モデルロード、デバイス再取得）を要求するため Controller 側で連携している。
--- a/src-python/docs/modules/controller.md
+++ b/src-python/docs/modules/controller.md
@@ -0,0 +1,158 @@
+## 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 から直接）
+```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 通知）
+```mermaid
+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 を参照）。
+
--- a/src-python/docs/modules/device_manager.md
+++ b/src-python/docs/modules/device_manager.md
@@ -0,0 +1,73 @@
+# device_manager.py — デバイス検出と監視（overwrite）
+
+目的: システムのマイク/スピーカー（主に Windows の WASAPI）を列挙し、変更を監視してコールバックで通知する `DeviceManager` シングルトンを提供します。
+
+主要コンポーネント:
+- class Client(MMNotificationClient)
+  - オーディオデバイスのシステムイベント（追加/削除/デフォルト変更）を受け取り、監視ループの再起動をトリガーします。
+
+- class DeviceManager
+  - シングルトンインスタンス: `device_manager`
+  - 主要プロパティ:
+    - `mic_devices` (dict): {host_name: [device_info, ...]}
+    - `default_mic_device` (dict): {'host': {...}, 'device': {...}}
+    - `speaker_devices` (list): [device_info, ...]
+    - `default_speaker_device` (dict)
+    - 各種 prev_/update_flag_: 差分検出用
+    - callback 関連プロパティ: `callback_default_mic_device`, `callback_mic_device_list`, など多数
+
+  - 主要メソッド (抜粋):
+    - `update()` -> None: PyAudio を利用してホスト毎の入力デバイスとループバック（スピーカー）を列挙し内部状態を更新します。
+    - `checkUpdate()` -> bool: 前回値との差分を計算して変更フラグを返します。
+    - `monitoring()` -> None: pycaw/MMNotificationClient を使った長時間監視ループ。変化を検出すると各コールバックを呼び出す。
+    - `startMonitoring()` / `stopMonitoring()`
+    - `getMicDevices()` / `getDefaultMicDevice()` / `getSpeakerDevices()` / `getDefaultSpeakerDevice()`
+    - `forceUpdateAndSetMicDevices()` / `forceUpdateAndSetSpeakerDevices()`
+
+コールバックAPI（例）:
+- `setCallbackMicDeviceList(callback)` — マイクデバイスリスト変更時に呼ばれる
+- `setCallbackDefaultMicDevice(callback)` — デフォルトマイク変更時に呼ばれる
+- `setCallbackProcessBeforeUpdateMicDevices(callback)` / `setCallbackProcessAfterUpdateMicDevices(callback)` — 更新前後のフック
+
+例:
+
+```python
+from device_manager import device_manager
+
+def on_default_mic(host_name, device_name):
+    print('Default mic changed:', host_name, device_name)
+
+device_manager.setCallbackDefaultMicDevice(on_default_mic)
+device_manager.forceUpdateAndSetMicDevices()
+```
+
+注意点:
+- Windows 固有のモジュール（PyAudio paWASAPI, pycaw）に依存します。クロスプラットフォーム対応が必要な場合は別実装が必要です。
+- 監視スレッドは永続的に動作するため、アプリケーション終了時は `stopMonitoring()` を呼んで安全に停止してください。
+
+## 詳細設計
+
+目的: ローカルの入力（マイク）と出力（ループバックから抽出されたスピーカー）デバイスを列挙し、変更を監視してコールバックで通知する。Windows の WASAPI 等に依存。
+
+主要クラス/関数:
+- class Client(MMNotificationClient)
+  - Audio デバイスの変更イベントを受けると `loop = False` にして監視ループを再起動させる設計。
+
+- class DeviceManager
+  - シングルトン: `device_manager = DeviceManager()`
+  - 主要属性:
+    - mic_devices: {host: [device_info...]}
+    - default_mic_device: {host, device}
+    - speaker_devices: [device_info...]
+    - default_speaker_device: {device}
+    - 各種 prev_*, update_flag_*: 差分検出のために保持
+    - コールバック属性: callback_default_mic_device, callback_host_list など
+  - 主要メソッド:
+    - update(): PyAudio を使ってホストごとにデバイス列挙。Loopback デバイスを speaker_devices に集める。
+    - monitoring(): MMNotificationClient と組み合わせてデバイスの変化を検出し、コールバックを発行
+    - set/clear Callback 系: UI や Controller が登録して自動選択や再起動をトリガーできる
+    - forceUpdateAndSetMicDevices / forceUpdateAndSetSpeakerDevices: 即時更新とコールバック通知
+
+注意点:
+- Windows 固有の処理（paWASAPI, pycaw）に依存する。
+- デバイス取得はリソースに依存するので try/except で例外を吸収し errorLogging() を呼ぶ。
--- a/src-python/docs/modules/model.md
+++ b/src-python/docs/modules/model.md
@@ -0,0 +1,105 @@
+# model.py — クラスと主要メソッド
+目的: アプリケーションの中核オーケストレータ。翻訳器 (Translator)、オーバーレイ、トランスクリプタ、OSC、WebSocket、Watchdog などのインスタンスを保持し、これらの起動/停止/操作を担います。`model` は `Model` のシングルトンインスタンスです。
+
+主要クラスとシグネチャ:
+- class threadFnc(Thread)
+  - __init__(self, fnc, end_fnc=None, daemon=True, *args, **kwargs)
+  - stop(self) -> None
+  - pause(self) -> None
+  - resume(self) -> None
+
+- class Model
+  - __new__(cls) -> Model
+  - init(self) -> None
+  - checkTranslatorCTranslate2ModelWeight(self, weight_type: str) -> bool
+  - changeTranslatorCTranslate2Model(self) -> None
+  - downloadCTranslate2ModelWeight(self, weight_type, callback=None, end_callback=None) -> Any
+  - isLoadedCTranslate2Model(self) -> bool
+  - getListLanguageAndCountry(self) -> list
+  - getTranslate(self, translator_name, source_language, target_language, target_country, message) -> tuple
+  - getInputTranslate(self, message, source_language=None) -> (list, list)
+  - getOutputTranslate(self, message, source_language=None) -> (list, list)
+  - startMicTranscript(self, fnc) -> None
+  - stopMicTranscript(self) -> None
+  - startSpeakerTranscript(self, fnc: Optional[Callable[[dict], None]] = None) -> None
+  - stopSpeakerTranscript(self) -> None
+  - startWebSocketServer(self, host, port) -> None
+  - stopWebSocketServer(self) -> None
+  - websocketSendMessage(self, message_dict: dict) -> bool
+
+  変更点（2025-10-09）:
+
+  - startCheckMicEnergy(self, fnc: Optional[Callable[[float], None]] = None) -> None
+    - 説明: 進捗/エネルギー表示用のコールバックを受け取ります。fnc が None の場合は内部で no-op を使い、呼び出し前に callable チェックを行います。これにより呼び出し側が None を渡しても安全になりました。
+
+  - startCheckSpeakerEnergy(self, fnc: Optional[Callable[[float], None]] = None) -> None
+    - 説明: 同上（fnc を Optional として受け取り、呼び出し時に callable を確認します）。内部では Queue を作成して録音データを受け取り、定期的にコールバックを呼びます。
+
+  - convertMessageToTransliteration(self, message: str, hiragana: bool = True, romaji: bool = True) -> list
+    - 説明: 以前は単一の文字列や別形を返す箇所がありましたが、現在は常にリスト（トークン単位の dict を要素とする list）を返します。hiragana/romaji の両方が False の場合は空リストを返します。
+
+  - createOverlayImageLargeLog(self, message_type: str, message: Optional[str], your_language: Optional[str], translation: list, target_language: Optional[dict] = None) -> object
+    - 説明: `target_language` は辞書形式で渡される場合があり、内部で言語リストに正規化されます（enabled な言語のみ抽出）。`message` / `your_language` は Optional となり、`None` を渡して翻訳のみのログを作ることが可能です。
+
+使用例（簡易）:
+
+```python
+from model import model
+
+# 翻訳を呼び出す
+translation, success = model.getTranslate('CTranslate2', 'Japanese', 'English', 'United States', 'こんにちは')
+print(translation, success)
+
+# マイク文字起こしの開始（コールバックで結果を受け取る）
+def on_mic_transcript(result):
+    print('mic transcript:', result)
+
+model.startMicTranscript(on_mic_transcript)
+
+# WebSocket サーバー起動
+model.startWebSocketServer('127.0.0.1', 2231)
+
+```
+
+注意点:
+- `Model` は多くの外部リソース（GPU、ファイル、ネットワーク）に依存するため、各操作は例外処理で保護されています。
+- 大きなモデルのロードで VRAM OOM を検出する `detectVRAMError` を備え、Controller 側でのフォールバック処理に使われます。
+
+## 詳細設計
+
+目的: 各モデル（翻訳/転写/Overlay/Watchdog/OSC/WebSocket 等）のインスタンスを保持し、高レベルの操作を提供するファサード。
+
+主要クラス/変数:
+- class threadFnc(Thread)
+  - 説明: ループする関数をバックグラウンドで呼ぶヘルパ。pause/stop/end callback をサポート。
+
+- class Model
+  - シングルトン: ファイル末で `model = Model()` として公開。
+  - 主な属性:
+    - translator (Translator)
+    - overlay (Overlay)
+    - overlay_image (OverlayImage)
+    - mic_audio_queue, mic_audio_recorder, mic_transcriber
+    - speaker_audio_queue, speaker_audio_recorder, speaker_transcriber
+    - watchdog (Watchdog)
+    - osc_handler (OSCHandler)
+    - websocket_server (WebSocketServer)
+  - 主なメソッド:
+    - start/stop logger, overlay, watchdog
+    - startMicTranscript / stopMicTranscript: 録音、transcriber の起動とキュー処理
+    - startSpeakerTranscript / stopSpeakerTranscript
+    - startCheckMicEnergy / stopCheckMicEnergy
+    - startCheckSpeakerEnergy / stopCheckSpeakerEnergy
+    - getTranslate / getInputTranslate / getOutputTranslate: Translator を利用する高レベル関数
+    - createOverlayImage* / updateOverlay* : OverlayImage と Overlay を結合して VR 表示を作成
+    - startWebSocketServer / stopWebSocketServer / websocketSendMessage
+
+エラー処理:
+- 音声認識や翻訳で VRAM エラーが発生した場合、detectVRAMError() で特殊な例外内容を検査し、Controller 経由で翻訳機能を OFF にする処理がある。
+
+非同期/リソース:
+- Recorder/Transcriber/Overlay/Watchdog/WebSocket はそれぞれ別スレッドで動作する。Model はそれらの開始/停止を管理する。
+
+依存:
+- models/translation, models/transcription, models/overlay, models/osc, models/websocket
+
--- a/src-python/docs/modules/model_extra.md
+++ b/src-python/docs/modules/model_extra.md
@@ -0,0 +1,60 @@
+# model.py — クラス一覧と使用例
+
+以下は `model.py` で提供される主要クラスのシグネチャ概要と、簡単な呼び出し例です。
+
+## クラス / 主要シグネチャ
+
+- class threadFnc(Thread)
+  - __init__(self, fnc: Callable, interval: float = 0.1, end_callback: Callable | None = None)
+  - start(self) -> None
+  - pause(self) -> None
+  - resume(self) -> None
+  - stop(self) -> None
+
+- class Model
+  - startLogger(self) -> None
+  - stopLogger(self) -> None
+  - startOverlay(self) -> None
+  - shutdownOverlay(self) -> None
+  - startMicTranscript(self, callback: Callable[[dict], None]) -> None
+  - stopMicTranscript(self) -> None
+  - startSpeakerTranscript(self, callback: Callable[[dict], None]) -> None
+  - stopSpeakerTranscript(self) -> None
+  - startCheckMicEnergy(self, progress_callback: Callable[[int], None]) -> None
+  - stopCheckMicEnergy(self) -> None
+  - startCheckSpeakerEnergy(self, progress_callback: Callable[[int], None]) -> None
+  - stopCheckSpeakerEnergy(self) -> None
+  - startWebSocketServer(self, host: str, port: int) -> None
+  - stopWebSocketServer(self) -> None
+  - websocketSendMessage(self, message: dict) -> None
+  - getListMicHost(self) -> dict
+  - getListMicDevice(self) -> list
+  - getListSpeakerDevice(self) -> list
+  - getInputTranslate(self, text: str, source_language: str = None) -> tuple[list[str], list[bool]]
+  - getOutputTranslate(self, text: str, source_language: str = None) -> tuple[list[str], list[bool]]
+  - detectVRAMError(self, exception: Exception) -> tuple[bool, str]
+
+## サンプル（呼び出し例）
+
+以下は Model の簡単な呼び出し例です。
+
+```python
+from model import model
+
+# マイク転写のコールバック例
+def on_mic_result(result: dict):
+    # result の想定形: {"text": str|False, "language": str}
+    text = result.get("text")
+    language = result.get("language")
+    print('mic:', text, language)
+
+# マイク転写を開始（別スレッドで動く）
+model.startMicTranscript(on_mic_result)
+
+# 一度だけ翻訳を呼ぶ
+translation, success = model.getInputTranslate('Hello', source_language='English')
+print('translation:', translation, 'success:', success)
+
+# WebSocket 経由で外部クライアントへイベント送信
+model.websocketSendMessage({'type': 'INFO', 'message': 'VRCT ready'})
+```
--- a/src-python/docs/modules/osc.md
+++ b/src-python/docs/modules/osc.md
@@ -0,0 +1,17 @@
+# models/osc — 詳細設計
+
+目的: VRChat 等と OSC / OSCQuery 経由で値の取得やチャット送信を行う。
+
+主要クラス/関数:
+- class OSCHandler
+  - sendMessage(message: str, notification: bool=True): OSC で chatbox/input を送信
+  - sendTyping(flag: bool): chatbox/typing を送信
+  - receiveOscParameters(): OSCQuery を立て、指定したフィルタに対してローカルでサーバを実装してイベントを受ける
+  - getOSCParameterValue(address: str): OSCQuery を通じて現在値を問い合わせる（use tinyoscquery）
+
+注意点:
+- `is_osc_query_enabled` が True のときに OSCQuery を使う（127.0.0.1 や localhost の場合に True）
+- 受信ハンドラは dispatcher にマップしてコールバックを呼ぶ。
+- ネットワーク環境や OSCQuery の可否により動作が変わるため例外処理が多く入っている。
+
+依存: python-osc, tinyoscquery
--- a/src-python/docs/modules/overlay.md
+++ b/src-python/docs/modules/overlay.md
@@ -0,0 +1,31 @@
+# overlay.py — OpenVR オーバーレイ管理
+
+目的: OpenVR を使ったオーバーレイ表示（複数サイズ: small/large）を管理する `Overlay` クラスを提供します。
+
+主要メソッド:
+- __init__(self, settings_dict)
+- init(self) -> None
+- startOverlay(self) -> None
+- shutdownOverlay(self) -> None
+- reStartOverlay(self) -> None
+- updateImage(self, img: PIL.Image.Image, size: str) -> None
+- updateOpacity(self, opacity: float, size: str, with_fade: bool = False) -> None
+- updateUiScaling(self, ui_scaling: float, size: str) -> None
+- updatePosition(self, x_pos, y_pos, z_pos, x_rotation, y_rotation, z_rotation, tracker, size) -> None
+- mainloop(self) -> None  # アニメーション / フェード評価ループ
+
+使用上の注意:
+- OpenVR (SteamVR) が稼働していることが前提です。`checkSteamvrRunning()` で `vrmonitor.exe` の存在チェックを行います。
+- 例外が発生した場合は `errorLogging()` を呼んでスタックトレースを残します。
+
+## モジュール構成（補足）
+
+- overlay.py — OpenVR を使ったオーバーレイ管理。Overlay クラスは複数サイズ（small/large）を扱い、位置/回転/透明度/フェードを制御する。
+- overlay_image.py — PIL を使ってオーバーレイに表示する画像を生成（テキストボックス、ログレイアウト、フォント管理）。
+- overlay_utils.py — 行列演算や座標変換ユーティリティ。
+
+注意点:
+- OpenVR（SteamVR）に依存。SteamVR が動作していることが前提。
+- フォントファイルは repo の fonts フォルダか、ランタイム内パスを探索して読み込む。
+- 生成画像は RGBA バイト列に変換され `overlay.setOverlayRaw` で渡される。
+
--- a/src-python/docs/modules/overlay_image.md
+++ b/src-python/docs/modules/overlay_image.md
@@ -0,0 +1,115 @@
+# overlay_image.py — 画像生成ユーティリティ
+目的: `models.overlay.overlay_image.OverlayImage` の実装に基づき、オーバーレイ用のテキストボックス／ログ画像を PIL (Pillow) で生成するための仕様書です。
+
+このドキュメントは実装に合わせて書かれており、主要な公開メソッドの振る舞い、引数、返り値、例外、使用例、注意点を含みます。
+
+概要
+------
+- 提供クラス: `OverlayImage`
+- 役割: 文字列（元文／翻訳）やメッセージタイプ(send/receive) を受け取り、Small/Large 向けの RGBA PIL.Image を生成する。
+- 依存: Pillow (PIL)、フォントファイル群（`fonts/` ディレクトリまたは環境配下）
+
+主要機能
+--------
+- テキストをラップして画像化する（行折り返しを含む）
+- 複数テキストブロック（原文＋複数の翻訳）を縦に連結して一つの画像にする
+- 背景（角丸矩形）を合成して最終的な RGBA 画像を返す
+- Small と Large で UI 設定（幅、高さ、フォントサイズ等）を切り替え
+- フォント探索: 実行環境の `fonts/` 配下または相対パスからフォントを探し、見つからない場合は FileNotFoundError を投げる
+
+公開 API（要約）
+-----------------
+- class OverlayImage(root_path: str | None = None)
+	- コンストラクタ引数
+		- root_path: フォント等のリソースのベースディレクトリ。None の場合は実装に合わせて repo の `fonts/` を候補パスとして探索する。
+
+- OverlayImage.createOverlayImageSmallLog(message: str, your_language: str, translation: list | None = None, target_language: list | None = None) -> PIL.Image.Image
+	- 説明: Small ログ向け（横長・1行〜複数行）にテキストブロックを作成して結合し、角丸背景と合成して RGBA 画像を返す。
+	- 引数
+		- message: 表示する原文テキスト（None を許容しない想定）
+		- your_language: 原文の言語キー（フォントマッピングに使用）
+		- translation: 翻訳テキストのリスト（省略可）
+		- target_language: 翻訳それぞれに対応する言語キーのリスト（省略可）
+	- 戻り値: PIL.Image.Image (RGBA)
+	- 例外: フォントが見つからない場合は FileNotFoundError を投げる可能性あり
+
+- OverlayImage.createOverlayImageLargeLog(message_type: str, message: str | None = None, your_language: str | None = None, translation: list | None = None, target_language: list | None = None) -> PIL.Image.Image
+	- 説明: Large ログ（複数行 + ヘッダ（Send/Receive）や時刻）向けに、複数ブロックを作成して縦結合し、背景を合成して返す。
+	- 引数
+		- message_type: 'send' または 'receive'（UI 向けアンカー／色指定に使用）
+		- message: 表示する原文テキスト（None 可。この場合翻訳のみを表示することもある）
+		- your_language: 原文の言語キー（フォント選定に使用）
+		- translation: 翻訳テキストのリスト（省略可）
+		- target_language: 翻訳それぞれに対応する言語キーのリスト（省略可）
+	- 戻り値: PIL.Image.Image (RGBA)
+	- 例外: フォント未発見などで FileNotFoundError を投げる可能性あり
+
+内部で使われる補助メソッド（要旨）
+---------------------------------
+- concatenateImagesVertically(img1, img2, margin=0) -> Image
+- addImageMargin(image, top, right, bottom, left, color) -> Image
+- createTextboxSmallLog(...) -> Image
+- createTextImageLargeLog(...) -> Image
+- createTextboxLargeLog(...) -> Image
+- getUiSizeSmallLog(), getUiColorSmallLog(), getUiSizeLargeLog(), getUiColorLargeLog()
+
+フォントとローカライズ
+-----------------------
+- 実装は `LANGUAGES` マッピングを持ち、言語キーからフォントファイル名を決定します（例: "Japanese" -> "NotoSansJP-Regular.ttf"）。
+- フォントは `root_path` を基準に探索します。実行環境によりフォントファイルの場所が異なるため、実装は複数パスを順に試します。フォントが見つからない場合は FileNotFoundError を発生させる設計です。
+
+描画と折り返しロジック（実装に基づく注意点）
+--------------------------------------------
+- テキスト幅を計算し、基準幅に収まるように文字数ベースで分割して折り返す単純なロジックを採用しています。厳密な単語単位折り返しではなく、文字数ベースの分割になります。
+- Small/Large でフォントサイズや余白、角丸半径などを分けており、複数行のテキストブロックを縦結合することで最終画像を作ります。
+
+使用例
+------
+Small ログ画像を作る例:
+
+```python
+from models.overlay.overlay_image import OverlayImage
+
+overlay = OverlayImage()
+img = overlay.createOverlayImageSmallLog(
+		message='こんにちは、世界！',
+		your_language='Japanese',
+		translation=['Hello, world!'],
+		target_language=['English']
+)
+img.save('overlay_small.png')
+```
+
+Large ログ（複数メッセージ履歴）を作る例:
+
+```python
+from models.overlay.overlay_image import OverlayImage
+from datetime import datetime
+
+overlay = OverlayImage()
+img = overlay.createOverlayImageLargeLog(
+		message_type='send',
+		message='Hello from VRCT',
+		your_language='English',
+		translation=['こんにちは'],
+		target_language=['Japanese']
+)
+img.save('overlay_large.png')
+```
+
+実装上の注意と推奨事項
+-----------------------
+- 実行環境にフォントが存在することを確認してください（`fonts/` に主要フォントを置くのが簡単です）。
+- Pillow (PIL) のバージョンに依存する描画 API を使っています。Pillow は v8〜最新程度で問題ありません。
+- 長いテキストの折り返しは単純な文字幅分割ロジックです。より自然な折り返し（単語単位・ルビ考慮等）が必要なら実装拡張を推奨します。
+- 生成画像は RGBA（透過）です。Overlay 側の API（`overlay.setOverlayRaw` 相当）へ渡して使う前提です。
+
+復元メモ
+--------
+このファイルは実装ファイル `models/overlay/overlay_image.py` を参照して復元しました。実装を変更した場合は本ドキュメントも同期して更新してください。
+
+関連ファイル
+-------------
+- 実装: `models/overlay/overlay_image.py`
+- ヘルパ: `models/overlay/overlay_utils.py`
+- フォント: `fonts/` ディレクトリ
--- a/src-python/docs/modules/transcription.md
+++ b/src-python/docs/modules/transcription.md
@@ -0,0 +1,51 @@
+# transcription — 文字起こしモジュール
+概要: マイク/スピーカー音声の録音と Whisper/Google などのエンジンを使った文字起こしを提供するモジュール群です。主なクラスは録音用の Recorder と `AudioTranscriber` です。
+
+主要クラス/シグネチャ:
+- SelectedMicEnergyAndAudioRecorder(device, energy_threshold, dynamic_energy_threshold, phrase_time_limit)
+- SelectedSpeakerEnergyAndAudioRecorder(...)
+- SelectedMicEnergyRecorder(device)
+- SelectedSpeakerEnergyRecorder(device)
+- AudioTranscriber(speaker: bool, source, phrase_timeout: int, max_phrases: int, transcription_engine: str, root: str, whisper_weight_type: str, device: str, device_index: int, compute_type: str)
+  - transcribeAudioQueue(queue, languages:list, countries:list, avg_logprob: float, no_speech_prob: float) -> bool
+  - getTranscript() -> dict
+
+使用例:
+
+```python
+from models.transcription.transcription_recorder import SelectedMicEnergyAndAudioRecorder
+from models.transcription.transcription_transcriber import AudioTranscriber
+
+# 録音
+rec = SelectedMicEnergyAndAudioRecorder(device, energy_threshold=300, dynamic_energy_threshold=False, phrase_time_limit=3)
+queue = Queue()
+rec.recordIntoQueue(queue, None)
+
+# 文字起こし
+transcriber = AudioTranscriber(speaker=False, source=rec.source, phrase_timeout=3, max_phrases=10, transcription_engine='Google', root='.', whisper_weight_type='base', device='cpu', device_index=0, compute_type='auto')
+transcriber.transcribeAudioQueue(queue, ['Japanese'], ['Japan'], -0.8, 0.6)
+print(transcriber.getTranscript())
+```
+
+注意点:
+- Whisper のモデルロードは VRAM を消費します。`Model.detectVRAMError` のような検知と回復策が必要です。
+- 録音は OS のデバイス依存のため `device_manager` でのデバイス取得と組み合わせて利用してください。
+
+# models/transcription — 詳細設計
+
+構成ファイル:
+- transcription_recorder.py — 各デバイス向け Recorder クラス群（Base, SelectedMic*, SelectedSpeaker*）。speech_recognition をラップし、Audio / Energy をキューへ出す。
+- transcription_transcriber.py — AudioTranscriber: Google Speech API または faster-whisper を使った音声→テキスト変換の実行ロジック。複数言語に対する最良候補選択と confidence に基づく選出。
+- transcription_whisper.py — Whisper（faster-whisper）重みのダウンロードとモデル生成のユーティリティ。
+
+主要契約:
+- Recorder は recordIntoQueue(audio_queue, energy_queue) を提供し、バックグラウンドで音声データをキューに流す。
+- AudioTranscriber.transcribeAudioQueue(audio_queue, languages, countries, avg_logprob, no_speech_prob) -> bool
+  - audio_queue から音声を取り出し認識を試みる。結果は getTranscript() で取得する。常に True/False を返して呼び出し側がループ継続を制御。
+
+VRAM エラー対策:
+- Whisper のモデルロードで GPU メモリ不足が発生すると、ValueError("VRAM_OUT_OF_MEMORY", message) を投げる実装。Controller で捕捉して機能停止/通知する。
+
+外部依存:
+- speech_recognition, faster_whisper, pydub, numpy, torch
+
--- a/src-python/docs/modules/translation.md
+++ b/src-python/docs/modules/translation.md
@@ -0,0 +1,21 @@
+# models/translation — 詳細設計
+
+構成ファイル:
+- translation_translator.py — Translator クラス。DeepL/API、Google、Bing、Papago、CTranslate2 を統一インターフェースで扱う。
+- translation_utils.py — 重みファイルのダウンロード・検証ロジック（CTranslate2 用）。
+- translation_languages.py — 各エンジンの対応言語マップ。
+
+Translator の契約:
+- translate(translator_name, source_language, target_language, target_country, message) -> str|False
+  - 成功時は文字列、失敗または一時的エラーは False を返す。
+- changeCTranslate2Model(path, model_type, device, device_index, compute_type)
+  - CTranslate2 の Translator オブジェクトと Tokenizer を初期化する。
+
+フォールバック:
+- Controller/Model 層で翻訳が失敗した場合に CTranslate2 にフォールバックする実装がある。
+
+外部依存:
+- ctranslate2, transformers, deepl（オプション）、translators（任意）
+
+安全性:
+- 翻訳 API キー（DeepL）は Translator.authenticationDeepLAuthKey で検証して保持。
--- a/src-python/docs/modules/transliteration.md
+++ b/src-python/docs/modules/transliteration.md
@@ -0,0 +1,17 @@
+# models/transliteration — 詳細設計
+
+目的: 日本語テキストの仮名読みを解析し、ひらがな/ローマ字（Hepburn）に変換する。
+
+主要クラス/関数:
+- class Transliterator
+  - analyze(text: str, use_macron: bool=False) -> List[dict]
+    - 入力: テキスト
+    - 出力: トークンのリスト。各要素は { orig, kana, hira, hepburn }
+  - split_kanji_okurigana(surface, reading_kana): 漢字＋送り仮名を分割して kana を割り当てるロジックを持つ（詳細設計あり）
+
+実装上のポイント:
+- SudachiPy を使い形態素解析して読みを得る。
+- Katakana を Hiragana に変換し、katakana_to_hepburn モジュールでローマ字化を行う。
+- 文脈ルールを `transliteration_context_rules.apply_context_rules` で適用できる設計（ルールエンジン）。
+
+依存: sudachipy
--- a/src-python/docs/modules/utils.md
+++ b/src-python/docs/modules/utils.md
@@ -0,0 +1,74 @@
+# utils.py — 関数一覧と使用例
+目的: 共通ユーティリティ（ログ、JSON 出力、ネットワーク/ポート検査、デバイス/計算タイプ列挙、バリデーション等）を提供します。
+
+主要関数とシグネチャ:
+- validateDictStructure(data: dict, structure: dict) -> bool
+- isConnectedNetwork(url: str = "http://www.google.com", timeout: int = 3) -> bool
+- isAvailableWebSocketServer(host: str, port: int) -> bool
+- isValidIpAddress(ip_address: str) -> bool
+- getComputeDeviceList() -> dict
+- getBestComputeType(device: str, device_index: int) -> str
+- encodeBase64(data: str) -> dict
+- removeLog() -> None
+- setupLogger(name, log_file, level=logging.INFO) -> logging.Logger
+- printLog(log: str, data: Any = None) -> None
+- printResponse(status: int, endpoint: str, result: Any = None) -> None
+- errorLogging() -> None
+
+使用例:
+
+```python
+from utils import printResponse, getComputeDeviceList, validateDictStructure
+
+# JSON 形式で mainloop に応答を返す
+printResponse(200, '/get/data/version', {'version': '3.2.2'})
+
+# 利用可能な計算デバイス一覧を取得
+devices = getComputeDeviceList()
+print(devices)
+
+# 辞書構造のバリデーション
+data = {'a': 1, 'b': {'c': 'x'}}
+structure = {'a': int, 'b': {'c': str}}
+ok = validateDictStructure(data, structure)
+print('valid:', ok)
+```
+
+注意点:
+- `printResponse` は stdout に JSON を出力しつつログファイルにも書き込みます。大きなオブジェクトは json.dumps で失敗する可能性があるため、例外処理が含まれています。
+
+# utils.py — 詳細設計
+
+目的: 小さなユーティリティ関数群。ロギング、ネットワーク検査、型検証、計算デバイス列挙など。
+
+主要関数/変数:
+- validateDictStructure(data: dict, structure: dict) -> bool
+  - 説明: 辞書が期待される構造（キーセットと値の型／入れ子）に完全一致するか検証する。
+  - 入力: data（検証対象）, structure（期待構造: 値が型または入れ子 dict）
+  - 出力: bool
+  - 例外: 型不一致や欠落時は False を返す（例外は投げない）。
+
+- isConnectedNetwork(url="http://www.google.com", timeout=3) -> bool
+  - 説明: 指定 URL に HTTP GET して接続可否を判定。requests を使用。
+
+- isAvailableWebSocketServer(host: str, port: int) -> bool
+  - 説明: 指定ポートへ bind できるかを試し、使用中かを判別する（True=利用可能）。
+
+- isValidIpAddress(ip_address: str) -> bool
+  - 説明: ipaddress.ip_address で検証。
+
+- getComputeDeviceList() -> dict
+  - 説明: CPU と CUDA（利用可能なら）を列挙し、各デバイスでサポートされる compute types を取得する。
+  - 依存: torch, ctranslate2.get_supported_compute_types
+
+- getBestComputeType(device: str, device_index: int) -> str
+  - 説明: デバイス名に基づき優先 compute_type を選び、利用可能なものを返す。デフォルトは "float32"。
+
+- setupLogger(name, log_file, level=logging.INFO) -> Logger
+  - 説明: RotatingFileHandler を使って UTF-8 ログを作る。10MB ローテーション。
+
+- printLog / printResponse / errorLogging
+  - 説明: mainloop と通信するために標準出力へ JSON を flush するユーティリティ。内部で file ログへも書く。
+
+注意点:
+- ネットワーク検査やファイル生成で例外が発生した場合、errorLogging() を呼んでトレースを error.log に保存する。
--- a/src-python/docs/modules/watchdog.md
+++ b/src-python/docs/modules/watchdog.md
@@ -0,0 +1,12 @@
+# models/watchdog — 詳細設計
+
+目的: 外部（Process 管理側）へ定期的に "生存" を知らせるために使う軽量ウォッチドッグ。
+
+設計:
+- class Watchdog(timeout:int=60, interval:int=20)
+  - feed(): 最終フィード時刻を更新
+  - setCallback(callback): タイムアウト時に呼ぶコールバックを登録
+  - start(): 現状は単純で、呼び出し側がループ中に start() を呼ぶかたち。実装は簡易（将来的にスレッド化推奨）
+
+注意:
+- 現行実装は非常にシンプルで、長時間のブロッキングやスレッド運用の見直しが必要になり得る。
--- a/src-python/docs/modules/websocket.md
+++ b/src-python/docs/modules/websocket.md
@@ -0,0 +1,18 @@
+# models/websocket — 詳細設計
+
+目的: 外部クライアント（例えば第三者のアプリ）へ翻訳済みテキストやイベントをブロードキャストする軽量 WebSocket サーバー。
+
+API:
+- class WebSocketServer(host='127.0.0.1', port=8765)
+  - start(): 別スレッドで asyncio ループを生成しサーバを起動。
+  - stop(): サーバ停止、全クライアント切断。
+  - set_message_handler(handler): クライアントからのメッセージ受信時のコールバックを登録。handler(server, websocket, message)
+  - send(message): 非同期キューに積んで全クライアントへ送信（スレッドセーフ）。
+  - broadcast(message): asyncio を経由して即時ブロードキャスト。
+
+実装上の工夫:
+- サーバ本体は別スレッドで asyncio イベントループを run_forever している。
+- 送信用に内部キュー `_send_queue` を持ち、_send_loop で順次送信する。これにより GUI 等から安全に send() を呼べる。
+
+依存: websockets（asyncio）
+