every_holiday/VRCT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4559d83766bef1dc338ab1471c5e0cdd7a91982b
VRCT/src-python/docs/details/config.md

12 KiB
Raw Blame History

config.py - 設定管理モジュール

概要

VRCTアプリケーションの全設定を一元管理するモジュールです。シングルトンパターンを採用し、アプリケーション全体で統一された設定アクセスを提供します。JSON設定ファイルの読み書き、設定の永続化、デバウンス機能付き保存機能を提供します。

主要機能

シングルトン設計

  • アプリケーション全体で単一の設定インスタンス
  • スレッドセーフな設定アクセス
  • 遅延初期化による軽量インポート

設定永続化

  • JSON形式での設定ファイル管理
  • デバウンス機能付き自動保存
  • 設定変更の即座反映

動的設定管理

  • 実行時設定変更対応
  • デバイス情報の動的取得
  • 言語・エンジン設定の自動更新

型安全な設定アクセス

  • プロパティベースのアクセス制御
  • 読み取り専用・読み書き可能設定の分離
  • デコレータによるシリアライゼーション管理

クラス構造

Config クラス

class Config:
    _instance = None              # シングルトンインスタンス
    _config_data: Dict[str, Any]  # 設定データ
    _timer: Optional[threading.Timer]  # デバウンスタイマー
    _debounce_time: int = 2       # デバウンス時間（秒）

設定カテゴリ

読み取り専用設定

@property
def VERSION(self) -> str
  • アプリケーションバージョン
@property
def PATH_LOCAL(self) -> str
  • ローカルディレクトリパス
@property
def PATH_CONFIG(self) -> str
  • 設定ファイルパス

UI・表示設定

@property
def UI_LANGUAGE(self) -> str
  • UIの表示言語
@property  
def TRANSPARENCY(self) -> int
  • ウィンドウの透明度（0-100）
@property
def UI_SCALING(self) -> int
  • UIのスケーリング（50-200%）
@property
def FONT_FAMILY(self) -> str
  • 使用フォントファミリー

翻訳設定

@property
def ENABLE_TRANSLATION(self) -> bool
  • 翻訳機能の有効・無効
@property
def SELECTED_TRANSLATION_ENGINES(self) -> Dict[str, str]
  • 選択されている翻訳エンジン
@property
def SELECTED_YOUR_LANGUAGES(self) -> Dict[str, Dict[str, Any]]
  • 送信言語設定
@property
def SELECTED_TARGET_LANGUAGES(self) -> Dict[str, Dict[str, Any]]
  • 受信言語設定

音声認識設定

@property
def ENABLE_TRANSCRIPTION_SEND(self) -> bool
  • 送信音声認識の有効・無効
@property
def SELECTED_TRANSCRIPTION_ENGINE(self) -> str
  • 音声認識エンジン
@property
def SELECTED_MIC_DEVICE(self) -> str
  • 選択されたマイクデバイス
@property
def MIC_THRESHOLD(self) -> int
  • マイク音声しきい値
@property
def MIC_RECORD_TIMEOUT(self) -> int
  • マイク録音タイムアウト（秒）

VR設定

@property
def OVERLAY_SMALL_LOG(self) -> bool
  • 小型ログオーバーレイの有効・無効
@property
def OVERLAY_SMALL_LOG_SETTINGS(self) -> Dict[str, Any]
  • 小型オーバーレイの詳細設定
@property
def OVERLAY_LARGE_LOG_SETTINGS(self) -> Dict[str, Any]
  • 大型オーバーレイの詳細設定

通信設定

@property
def OSC_IP_ADDRESS(self) -> str
  • OSC通信IPアドレス
@property
def OSC_PORT(self) -> int
  • OSC通信ポート
@property
def WEBSOCKET_HOST(self) -> str
  • WebSocketサーバーホスト
@property
def WEBSOCKET_PORT(self) -> int
  • WebSocketサーバーポート

クリップボード設定

@property
def ENABLE_CLIPBOARD(self) -> bool
  • クリップボード機能（コピー・ペースト）の有効・無効

テレメトリ設定

@property
def ENABLE_TELEMETRY(self) -> bool
  • テレメトリ（Aptabase）の有効・無効
  • デフォルト: True（有効）
  • ユーザーは設定から任意で無効化可能

計算デバイス設定

@property
def SELECTED_TRANSLATION_COMPUTE_DEVICE(self) -> Dict[str, Any]
  • 翻訳用計算デバイス
@property
def SELECTED_TRANSCRIPTION_COMPUTE_DEVICE(self) -> Dict[str, Any]
  • 音声認識用計算デバイス

主要メソッド

設定保存

saveConfig(key: str, value: Any, immediate_save: bool = False) -> None
  • 設定値の保存（デバウンス付き）
  • immediate_save=Trueで即座保存
saveConfigToFile() -> None
  • 設定ファイルへの直接保存

初期化・設定読み込み

init_config() -> None
  • 設定の初期化
  • デフォルト値の設定
load_config() -> None
  • 設定ファイルからの読み込み
  • 存在しない場合はデフォルト設定を作成

デコレータ機能

@json_serializable

@json_serializable("setting_name")
@property
def SETTING_NAME(self) -> Any:
  • 設定のJSONシリアライゼーション対象指定
  • 自動的にconfig.jsonに保存される設定を定義

使用方法

基本的な使い方

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

複雑な設定の変更

# 翻訳エンジンの設定
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

即座保存

# 重要な設定変更時の即座保存
config.saveConfig("ENABLE_TRANSLATION", True, immediate_save=True)

設定ファイル形式

設定はconfig.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検知 安全停止と軽量エンジン切替で安定性向上
テスト増強 大量ペア検証で言語/モデル設定の信頼性向上
Reference in New Issue View Git Blame Copy Permalink