474 lines
12 KiB
Markdown
474 lines
12 KiB
Markdown
# config.py - 設定管理モジュール
|
||
|
||
## 概要
|
||
|
||
VRCTアプリケーションの全設定を一元管理するモジュールです。シングルトンパターンを採用し、アプリケーション全体で統一された設定アクセスを提供します。JSON設定ファイルの読み書き、設定の永続化、デバウンス機能付き保存機能を提供します。
|
||
|
||
## 主要機能
|
||
|
||
### シングルトン設計
|
||
- アプリケーション全体で単一の設定インスタンス
|
||
- スレッドセーフな設定アクセス
|
||
- 遅延初期化による軽量インポート
|
||
|
||
### 設定永続化
|
||
- JSON形式での設定ファイル管理
|
||
- デバウンス機能付き自動保存
|
||
- 設定変更の即座反映
|
||
|
||
### 動的設定管理
|
||
- 実行時設定変更対応
|
||
- デバイス情報の動的取得
|
||
- 言語・エンジン設定の自動更新
|
||
|
||
### 型安全な設定アクセス
|
||
- プロパティベースのアクセス制御
|
||
- 読み取り専用・読み書き可能設定の分離
|
||
- デコレータによるシリアライゼーション管理
|
||
|
||
## クラス構造
|
||
|
||
### Config クラス
|
||
```python
|
||
class Config:
|
||
_instance = None # シングルトンインスタンス
|
||
_config_data: Dict[str, Any] # 設定データ
|
||
_timer: Optional[threading.Timer] # デバウンスタイマー
|
||
_debounce_time: int = 2 # デバウンス時間（秒）
|
||
```
|
||
|
||
## 設定カテゴリ
|
||
|
||
### 読み取り専用設定
|
||
|
||
```python
|
||
@property
|
||
def VERSION(self) -> str
|
||
```
|
||
- アプリケーションバージョン
|
||
|
||
```python
|
||
@property
|
||
def PATH_LOCAL(self) -> str
|
||
```
|
||
- ローカルディレクトリパス
|
||
|
||
```python
|
||
@property
|
||
def PATH_CONFIG(self) -> str
|
||
```
|
||
- 設定ファイルパス
|
||
|
||
### UI・表示設定
|
||
|
||
```python
|
||
@property
|
||
def UI_LANGUAGE(self) -> str
|
||
```
|
||
- UIの表示言語
|
||
|
||
```python
|
||
@property
|
||
def TRANSPARENCY(self) -> int
|
||
```
|
||
- ウィンドウの透明度（0-100）
|
||
|
||
```python
|
||
@property
|
||
def UI_SCALING(self) -> int
|
||
```
|
||
- UIのスケーリング（50-200%）
|
||
|
||
```python
|
||
@property
|
||
def FONT_FAMILY(self) -> str
|
||
```
|
||
- 使用フォントファミリー
|
||
|
||
### 翻訳設定
|
||
|
||
```python
|
||
@property
|
||
def ENABLE_TRANSLATION(self) -> bool
|
||
```
|
||
- 翻訳機能の有効・無効
|
||
|
||
```python
|
||
@property
|
||
def SELECTED_TRANSLATION_ENGINES(self) -> Dict[str, str]
|
||
```
|
||
- 選択されている翻訳エンジン
|
||
|
||
```python
|
||
@property
|
||
def SELECTED_YOUR_LANGUAGES(self) -> Dict[str, Dict[str, Any]]
|
||
```
|
||
- 送信言語設定
|
||
|
||
```python
|
||
@property
|
||
def SELECTED_TARGET_LANGUAGES(self) -> Dict[str, Dict[str, Any]]
|
||
```
|
||
- 受信言語設定
|
||
|
||
### 音声認識設定
|
||
|
||
```python
|
||
@property
|
||
def ENABLE_TRANSCRIPTION_SEND(self) -> bool
|
||
```
|
||
- 送信音声認識の有効・無効
|
||
|
||
```python
|
||
@property
|
||
def SELECTED_TRANSCRIPTION_ENGINE(self) -> str
|
||
```
|
||
- 音声認識エンジン
|
||
|
||
```python
|
||
@property
|
||
def SELECTED_MIC_DEVICE(self) -> str
|
||
```
|
||
- 選択されたマイクデバイス
|
||
|
||
```python
|
||
@property
|
||
def MIC_THRESHOLD(self) -> int
|
||
```
|
||
- マイク音声しきい値
|
||
|
||
```python
|
||
@property
|
||
def MIC_RECORD_TIMEOUT(self) -> int
|
||
```
|
||
- マイク録音タイムアウト（秒）
|
||
|
||
### VR設定
|
||
|
||
```python
|
||
@property
|
||
def OVERLAY_SMALL_LOG(self) -> bool
|
||
```
|
||
- 小型ログオーバーレイの有効・無効
|
||
|
||
```python
|
||
@property
|
||
def OVERLAY_SMALL_LOG_SETTINGS(self) -> Dict[str, Any]
|
||
```
|
||
- 小型オーバーレイの詳細設定
|
||
|
||
```python
|
||
@property
|
||
def OVERLAY_LARGE_LOG_SETTINGS(self) -> Dict[str, Any]
|
||
```
|
||
- 大型オーバーレイの詳細設定
|
||
|
||
### 通信設定
|
||
|
||
```python
|
||
@property
|
||
def OSC_IP_ADDRESS(self) -> str
|
||
```
|
||
- OSC通信IPアドレス
|
||
|
||
```python
|
||
@property
|
||
def OSC_PORT(self) -> int
|
||
```
|
||
- OSC通信ポート
|
||
|
||
```python
|
||
@property
|
||
def WEBSOCKET_HOST(self) -> str
|
||
```
|
||
- WebSocketサーバーホスト
|
||
|
||
```python
|
||
@property
|
||
def WEBSOCKET_PORT(self) -> int
|
||
```
|
||
- WebSocketサーバーポート
|
||
|
||
### クリップボード設定
|
||
|
||
```python
|
||
@property
|
||
def ENABLE_CLIPBOARD(self) -> bool
|
||
```
|
||
- クリップボード機能（コピー・ペースト）の有効・無効
|
||
|
||
### テレメトリ設定
|
||
|
||
```python
|
||
@property
|
||
def ENABLE_TELEMETRY(self) -> bool
|
||
```
|
||
- テレメトリ（Aptabase）の有効・無効
|
||
- デフォルト: True（有効）
|
||
- ユーザーは設定から任意で無効化可能
|
||
|
||
### 計算デバイス設定
|
||
|
||
```python
|
||
@property
|
||
def SELECTED_TRANSLATION_COMPUTE_DEVICE(self) -> Dict[str, Any]
|
||
```
|
||
- 翻訳用計算デバイス
|
||
|
||
```python
|
||
@property
|
||
def SELECTED_TRANSCRIPTION_COMPUTE_DEVICE(self) -> Dict[str, Any]
|
||
```
|
||
- 音声認識用計算デバイス
|
||
|
||
## 主要メソッド
|
||
|
||
### 設定保存
|
||
|
||
```python
|
||
saveConfig(key: str, value: Any, immediate_save: bool = False) -> None
|
||
```
|
||
- 設定値の保存（デバウンス付き）
|
||
- immediate_save=Trueで即座保存
|
||
|
||
```python
|
||
saveConfigToFile() -> None
|
||
```
|
||
- 設定ファイルへの直接保存
|
||
|
||
### 初期化・設定読み込み
|
||
|
||
```python
|
||
init_config() -> None
|
||
```
|
||
- 設定の初期化
|
||
- デフォルト値の設定
|
||
|
||
```python
|
||
load_config() -> None
|
||
```
|
||
- 設定ファイルからの読み込み
|
||
- 存在しない場合はデフォルト設定を作成
|
||
|
||
## デコレータ機能
|
||
|
||
### @json_serializable
|
||
```python
|
||
@json_serializable("setting_name")
|
||
@property
|
||
def SETTING_NAME(self) -> Any:
|
||
```
|
||
- 設定のJSONシリアライゼーション対象指定
|
||
- 自動的にconfig.jsonに保存される設定を定義
|
||
|
||
## 使用方法
|
||
|
||
### 基本的な使い方
|
||
|
||
```python
|
||
from config import config
|
||
|
||
# 設定値の取得
|
||
version = config.VERSION
|
||
ui_language = config.UI_LANGUAGE
|
||
translation_enabled = config.ENABLE_TRANSLATION
|
||
|
||
# 設定値の変更
|
||
config.UI_LANGUAGE = "ja"
|
||
config.TRANSPARENCY = 80
|
||
config.MIC_THRESHOLD = 1500
|
||
```
|
||
|
||
### 複雑な設定の変更
|
||
|
||
```python
|
||
# 翻訳エンジンの設定
|
||
engines = config.SELECTED_TRANSLATION_ENGINES
|
||
engines["1"] = "DeepL"
|
||
config.SELECTED_TRANSLATION_ENGINES = engines
|
||
|
||
# オーバーレイ設定の変更
|
||
overlay_settings = config.OVERLAY_SMALL_LOG_SETTINGS
|
||
overlay_settings["x_pos"] = 0.5
|
||
overlay_settings["opacity"] = 0.8
|
||
config.OVERLAY_SMALL_LOG_SETTINGS = overlay_settings
|
||
```
|
||
|
||
### 即座保存
|
||
|
||
```python
|
||
# 重要な設定変更時の即座保存
|
||
config.saveConfig("ENABLE_TRANSLATION", True, immediate_save=True)
|
||
```
|
||
|
||
## 設定ファイル形式
|
||
|
||
設定は`config.json`ファイルにJSON形式で保存されます：
|
||
|
||
```json
|
||
{
|
||
"UI_LANGUAGE": "ja",
|
||
"TRANSPARENCY": 85,
|
||
"UI_SCALING": 100,
|
||
"ENABLE_TRANSLATION": true,
|
||
"SELECTED_TRANSLATION_ENGINES": {
|
||
"1": "DeepL",
|
||
"2": "Google",
|
||
"3": "CTranslate2"
|
||
},
|
||
"OVERLAY_SMALL_LOG_SETTINGS": {
|
||
"x_pos": 0.0,
|
||
"y_pos": -0.4,
|
||
"z_pos": 1.0,
|
||
"opacity": 1.0,
|
||
"ui_scaling": 1.0,
|
||
"display_duration": 5,
|
||
"fadeout_duration": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
## デフォルト設定
|
||
|
||
### UI設定
|
||
- UI言語: "en"（英語）
|
||
- 透明度: 85%
|
||
- UIスケーリング: 100%
|
||
- フォント: "Noto Sans JP"
|
||
|
||
### 翻訳設定
|
||
- 翻訳機能: 無効
|
||
- デフォルトエンジン: "Google"
|
||
- 送信言語: English（US）
|
||
- 受信言語: 日本語
|
||
|
||
### 音声認識設定
|
||
- 送信音声認識: 無効
|
||
- 受信音声認識: 無効
|
||
- 音声認識エンジン: "Google"
|
||
- マイクしきい値: 300
|
||
|
||
### VR設定
|
||
- 小型オーバーレイ: 無効
|
||
- 大型オーバーレイ: 無効
|
||
- オーバーレイ位置: HMD正面
|
||
|
||
### 通信設定
|
||
- OSC IP: "127.0.0.1"
|
||
- OSC ポート: 9000
|
||
- WebSocket ホスト: "127.0.0.1"
|
||
- WebSocket ポート: 8765
|
||
|
||
### クリップボード設定
|
||
- クリップボード機能: 無効
|
||
|
||
### テレメトリ設定
|
||
- テレメトリ: **有効（デフォルト）**
|
||
|
||
## 依存関係
|
||
|
||
### 必須依存関係
|
||
- `json`: 設定ファイルのシリアライゼーション
|
||
- `threading`: デバウンス機能
|
||
- `typing`: 型注釈
|
||
|
||
### オプション依存関係
|
||
- `device_manager`: デバイス情報取得
|
||
- `torch`: CUDA計算デバイス情報
|
||
- 各種モデルモジュール: 言語・エンジン情報
|
||
|
||
## エラーハンドリング
|
||
|
||
- 設定ファイル読み込みエラーの適切な処理
|
||
- 不正な設定値の検証・補正
|
||
- オプション依存関係の欠如に対するフォールバック
|
||
- ファイル書き込みエラーの処理
|
||
|
||
## パフォーマンス特性
|
||
|
||
### デバウンス機能
|
||
- 設定変更から2秒後に自動保存
|
||
- 連続する変更の統合
|
||
- I/O負荷の軽減
|
||
|
||
### 遅延初期化
|
||
- 重い依存関係の遅延読み込み
|
||
- インポート時間の短縮
|
||
|
||
### メモリ効率
|
||
- 設定データのシングルトン管理
|
||
- 不要な複製の防止
|
||
|
||
## 注意事項
|
||
|
||
- 設定変更は即座にメモリに反映される
|
||
- ファイル保存はデバウンス機能により遅延される
|
||
- 重要な設定はimmediate_save=Trueを使用
|
||
- オプション依存関係の欠如時はデフォルト値を使用
|
||
- 不正な設定値は自動的に補正される
|
||
- 設定ファイルが破損した場合は新規作成される
|
||
|
||
## セキュリティ考慮事項
|
||
|
||
- 設定ファイルの適切な権限管理
|
||
- 外部入力値の検証
|
||
- APIキー等の機密情報の適切な取り扱い
|
||
- パスインジェクション攻撃の防止
|
||
|
||
## 最近の更新 (2025-10-20)
|
||
|
||
### LMStudio / Ollama ローカル LLM 設定プロパティ追加
|
||
|
||
- `LMSTUDIO_URL` / `SELECTABLE_LMSTUDIO_MODEL_LIST` / `SELECTED_LMSTUDIO_MODEL`
|
||
- `SELECTABLE_OLLAMA_MODEL_LIST` / `SELECTED_OLLAMA_MODEL`
|
||
|
||
ローカル推論エンジン接続用 URL と動的モデルリスト取得・選択プロパティを追加。認証は不要で接続テスト後自動でモデルリストを更新。
|
||
|
||
### モデル選択プロパティ名称統一
|
||
|
||
Plamo / Gemini / OpenAI の選択モデルを `PLAMO_MODEL` / `GEMINI_MODEL` / `OPENAI_MODEL` から `SELECTED_PLAMO_MODEL` / `SELECTED_GEMINI_MODEL` / `SELECTED_OPENAI_MODEL` へ統一。設定 JSON の保存キーも `SELECTED_*` に変更し UI との整合性を確保。
|
||
|
||
### CTranslate2 言語マッピング構造変更対応
|
||
|
||
`translation_lang` 内の CTranslate2 言語辞書が `translation_lang["CTranslate2"][weight_type]["source"|"target"]` へネスト化。`CTRANSLATE2_WEIGHT_TYPE` プロパティがアクセスのキーとなるため、重みタイプ変更時に翻訳エンジン再初期化が必要。
|
||
|
||
### YAML 言語外部定義導入
|
||
|
||
`loadTranslationLanguages()` を初期化時に呼び出し、`models/translation/languages/languages.yml` を読み込んで既存マッピングへマージ。失敗時は空辞書フォールバック。動的言語追加がコード改修無しで可能になったため設定初期化の失敗ログ確認が重要。
|
||
|
||
### OpenAI モデルリスト自動更新
|
||
|
||
`setOpenAIAuthKey()` 成功後に `SELECTABLE_OPENAI_MODEL_LIST` を取得し未選択の場合は先頭を自動選択。Gemini / Plamo / LMStudio / Ollama も同様に認証/接続確立時にリスト更新と未選択モデル補完。
|
||
|
||
### フォント設定のパッケージ対応
|
||
|
||
`overlay_image.py` で PyInstaller ビルド環境（`_internal/fonts/`）検出を追加。開発環境とバンドル後でフォント探索パスが異なるため、`FONT_FAMILY` はファイル名基準のまま変更無し。
|
||
|
||
### 依存関係追加
|
||
|
||
- `PyYAML`: 言語マッピング YAML 読み込み
|
||
- `google-genai`: Gemini 連携
|
||
- `grpcio`: OpenAI 連携（ストリーミング等）
|
||
|
||
### VRAM エラー時の自動フォールバック
|
||
|
||
翻訳有効化や翻訳実行時に VRAM 不足検出で `ENABLE_TRANSLATION` を False にし CTranslate2 へ強制切替。設定値は保持されるが UI には無効化状態を通知。再度有効化要求時に重いモデル再初期化を試行。
|
||
|
||
### テスト関連
|
||
|
||
包括的翻訳ペアテストにより `SELECTED_*` モデルと言語マッピング組合せを大量実行。設定値の変更頻度増加に伴いデバウンス 2 秒でファイル書き込み負荷を抑制。
|
||
|
||
### 影響まとめ
|
||
|
||
| 項目 | 内容 |
|
||
|------|------|
|
||
| ローカルLLM | LMStudio / Ollama の導入でオフライン翻訳拡張 |
|
||
| プロパティ統一 | SELECTED_* 命名で一貫性・ドキュメント整備性向上 |
|
||
| 言語ネスト化 | CTranslate2 重みタイプ切替処理の再初期化必要性増加 |
|
||
| YAML外部化 | 言語追加が設定初期化のみで反映可能 |
|
||
| モデルリスト自動更新 | 認証後の選択ミス防止・初回 UX 改善 |
|
||
| フォント探索 | PyInstaller ビルド後でも同一コードで動作 |
|
||
| 依存追加 | 新機能対応で環境構築ステップ増加 |
|
||
| VRAM検知 | 安全停止と軽量エンジン切替で安定性向上 |
|
||
| テスト増強 | 大量ペア検証で言語/モデル設定の信頼性向上 |
|