Upload 17 files

upgrade_codes/compare_yaml.py

@@ -0,0 +1,100 @@
+from ruamel.yaml import YAML
+
+conf1 = "conf.yaml"
+conf2 = "config_templates/conf.ZH.default.yaml"
+
+
+def collect_all_key_paths(d, prefix=""):
+    keys = set()
+    for k, v in d.items():
+        full_key = f"{prefix}.{k}" if prefix else k
+        keys.add(full_key)
+        if isinstance(v, dict):
+            keys.update(collect_all_key_paths(v, full_key))
+    return keys
+
+
+def collect_leaf_key_paths(d, prefix=""):
+    keys = set()
+    for k, v in d.items():
+        full_key = f"{prefix}.{k}" if prefix else k
+        if isinstance(v, dict):
+            keys.update(collect_leaf_key_paths(v, full_key))
+        else:
+            keys.add(full_key)
+    return keys
+
+
+def get_value_by_path(d, path_str):
+    keys = path_str.split(".")
+    current = d
+    for key in keys:
+        if isinstance(current, dict) and key in current:
+            current = current[key]
+        else:
+            return None
+    return current
+
+
+def compare_yaml_keys(dict1, dict2):
+    keys1 = collect_all_key_paths(dict1)
+    keys2 = collect_all_key_paths(dict2)
+    only_in_1 = keys1 - keys2
+    only_in_2 = keys2 - keys1
+    return only_in_1, only_in_2
+
+
+def compare_yaml_values(dict1, dict2):
+    leaf_keys1 = collect_leaf_key_paths(dict1)
+    leaf_keys2 = collect_leaf_key_paths(dict2)
+    common_leaf_keys = leaf_keys1 & leaf_keys2
+
+    differences = []
+
+    for key in sorted(common_leaf_keys):
+        value1 = get_value_by_path(dict1, key)
+        value2 = get_value_by_path(dict2, key)
+
+        if value1 != value2:
+            differences.append({"key_path": key, "value1": value1, "value2": value2})
+
+    if not differences:
+        print("✅ 所有共同叶子节点的值完全一致\n")
+    else:
+        print(f"❌ 发现 {len(differences)} 个值不同的字段:\n\n")
+        for diff in differences:
+            print(f"键路径: {diff['key_path']}\n")
+            print(f"  {conf1}中的值: {diff['value1']}\n")
+            print(f"  {conf2}中的值: {diff['value2']}\n")
+            print("-" * 50 + "\n")
+
+    return differences
+
+
+if __name__ == "__main__":
+    yaml = YAML(typ="safe")
+    with (
+        open(conf1, "r", encoding="utf-8") as f1,
+        open(conf2, "r", encoding="utf-8") as f2,
+    ):
+        config1 = yaml.load(f1)
+        config2 = yaml.load(f2)
+
+    # Compare differences in keys.
+    only_in_1, only_in_2 = compare_yaml_keys(config1, config2)
+
+    if not only_in_1 and not only_in_2:
+        print("✅ 两个 YAML 文件的 key 完全一致")
+    else:
+        print("❌ 不一致:")
+        if only_in_1:
+            print(f"仅在 {conf1} 中存在的 key ({len(only_in_1)} 个):")
+            for key in sorted(only_in_1):
+                print(f"  - {key}")
+        if only_in_2:
+            print(f"\n仅在 {conf2} 中存在的 key ({len(only_in_2)} 个):")
+            for key in sorted(only_in_2):
+                print(f"  - {key}")
+
+    # Compare differences in values.
+    diff_count = compare_yaml_values(config1, config2)

upgrade_codes/config_sync.py

@@ -0,0 +1,313 @@
+import os
+import shutil
+from upgrade_codes.upgrade_core.constants import (
+    USER_CONF,
+    BACKUP_CONF,
+    TEXTS,
+    ZH_DEFAULT_CONF,
+    EN_DEFAULT_CONF,
+    TEXTS_COMPARE,
+    TEXTS_MERGE,
+)
+import logging
+from ruamel.yaml import YAML
+from src.open_llm_vtuber.config_manager.utils import load_text_file_with_guess_encoding
+from upgrade_codes.upgrade_core.comment_sync import CommentSynchronizer
+from upgrade_codes.version_manager import VersionUpgradeManager
+from upgrade_codes.upgrade_core.upgrade_utils import UpgradeUtility
+from upgrade_codes.upgrade_core.comment_diff_fn import comment_diff_fn
+from packaging import version
+
+
+class ConfigSynchronizer:
+    def __init__(self, lang="en", logger=logging.getLogger(__name__)):
+        self.lang = lang
+        self.texts = TEXTS[lang]
+        self.default_path = ZH_DEFAULT_CONF if lang == "zh" else EN_DEFAULT_CONF
+        self.yaml = YAML()
+        self.yaml.preserve_quotes = True
+        self.user_path = USER_CONF
+        self.backup_path = BACKUP_CONF
+        self.texts_merge = TEXTS_MERGE.get(lang, TEXTS_MERGE["en"])
+        self.texts_compare = TEXTS_COMPARE.get(lang, TEXTS_COMPARE["en"])
+        self.logger = logger
+        self.upgrade_utils = UpgradeUtility(self.logger, self.lang)
+
+    def sync_user_config(self) -> None:
+        """
+        Ensure the user configuration file exists and create a backup if necessary.
+        If the user config file does not exist, copy the default config.
+        """
+        # Check if the user config file exists
+        if not os.path.exists(self.user_path):
+            self.logger.warning(self.texts["no_config"])
+            self.logger.warning(self.texts["copy_default_config"])
+            # Copy default config to user path
+            shutil.copy2(self.default_path, self.user_path)
+            return
+
+        # Create a backup of the user config file
+        self.backup_user_config()
+
+    def update_user_config(self) -> None:
+        """
+        Perform the actual update operations on the user configuration file:
+        1. Compare and update configuration fields
+        2. Synchronize comments
+        3. Upgrade version if needed
+        """
+
+        # Step 1: Update config fields
+        if not self.compare_field_keys():
+            self.merge_and_update_user_config()
+        else:
+            self.logger.info(self.texts["configs_up_to_date"])
+
+        # Step 2: Sync comments
+        if not self.compare_comments():
+            comment_sync = CommentSynchronizer(
+                self.default_path,
+                self.user_path,
+                self.logger,
+                self.yaml,
+                self.texts_compare,
+            )
+            comment_sync.sync()
+        else:
+            self.logger.info(self.texts_compare["comments_up_to_date"])
+
+        # Step 3: Determine whether upgrade is needed
+        new_version = self.get_latest_version()
+        old_version = self.get_old_version()
+        need_upgrade = old_version != new_version
+
+        # Step 4: Run upgrade if needed
+        if need_upgrade:
+            version_upgrade_manager = VersionUpgradeManager(self.lang, self.logger)
+            final_version = version_upgrade_manager.upgrade(old_version)
+            self.logger.info(
+                self.texts["version_upgrade_success"].format(
+                    old=old_version, new=final_version
+                )
+            )
+        else:
+            self.logger.info(
+                self.texts["version_upgrade_none"].format(version=old_version)
+            )
+
+    def backup_user_config(self):
+        backup_path = os.path.abspath(self.backup_path)
+        self.logger.info(
+            self.texts["backup_user_config"].format(
+                user_conf=self.user_path, backup_conf=self.backup_path
+            )
+        )
+        self.logger.debug(self.texts["config_backup_path"].format(path=backup_path))
+        shutil.copy2(self.user_path, self.backup_path)
+
+    def merge_and_update_user_config(self):
+        try:
+            new_keys = self.merge_configs()
+            if new_keys:
+                self.logger.info(self.texts["merged_config_success"])
+                for key in new_keys:
+                    self.logger.info(f"  - {key}")
+            else:
+                self.logger.info(self.texts["merged_config_none"])
+        except Exception as e:
+            self.logger.error(self.texts["merge_failed"].format(error=e))
+
+    def merge_configs(self):
+        user_config = self.yaml.load(load_text_file_with_guess_encoding(self.user_path))
+        default_config = self.yaml.load(
+            load_text_file_with_guess_encoding(self.default_path)
+        )
+
+        new_keys = []
+
+        def merge(d_user, d_default, path=""):
+            for k, v in d_default.items():
+                current_path = f"{path}.{k}" if path else k
+                if k not in d_user:
+                    d_user[k] = v
+                    new_keys.append(current_path)
+                elif isinstance(v, dict) and isinstance(d_user.get(k), dict):
+                    merge(d_user[k], v, current_path)
+            return d_user
+
+        merged = merge(user_config, default_config)
+
+        with open(self.user_path, "w", encoding="utf-8") as f:
+            self.yaml.dump(merged, f)
+
+        for key in new_keys:
+            self.logger.info(self.texts_merge["new_config_item"].format(key=key))
+        return new_keys
+
+    def collect_all_subkeys(self, d, base_path):
+        """Collect all keys in the dictionary d, recursively, with base_path as the prefix."""
+        keys = []
+        # Only process if d is a dictionary
+        if isinstance(d, dict):
+            for key, value in d.items():
+                current_path = f"{base_path}.{key}" if base_path else key
+                keys.append(current_path)
+                if isinstance(value, dict):
+                    keys.extend(self.collect_all_subkeys(value, current_path))
+        return keys
+
+    def get_missing_keys(self, user, default, path=""):
+        """Recursively find keys in default that are missing in user."""
+        missing = []
+        for key, default_val in default.items():
+            current_path = f"{path}.{key}" if path else key
+            if key not in user:
+                missing.append(current_path)
+            else:
+                user_val = user[key]
+                if isinstance(default_val, dict):
+                    if isinstance(user_val, dict):
+                        missing.extend(
+                            self.get_missing_keys(user_val, default_val, current_path)
+                        )
+                    else:
+                        subtree_missing = self.collect_all_subkeys(
+                            default_val, current_path
+                        )
+                        missing.extend(subtree_missing)
+        return missing
+
+    def get_extra_keys(self, user, default, path=""):
+        """Recursively find keys in user that are not present in default."""
+        extra = []
+        for key, user_val in user.items():
+            current_path = f"{path}.{key}" if path else key
+            if key not in default:
+                # Only collect subkeys if the value is a dictionary
+                if isinstance(user_val, dict):
+                    subtree_extra = self.collect_all_subkeys(user_val, current_path)
+                    extra.extend(subtree_extra)
+                extra.append(current_path)
+            else:
+                default_val = default[key]
+                if isinstance(user_val, dict) and isinstance(default_val, dict):
+                    extra.extend(
+                        self.get_extra_keys(user_val, default_val, current_path)
+                    )
+                elif isinstance(user_val, dict):
+                    subtree_extra = self.collect_all_subkeys(user_val, current_path)
+                    extra.extend(subtree_extra)
+        return extra
+
+    def delete_extra_keys(self):
+        """Delete extra keys in user config that are not present in default config."""
+
+        user_config = self.yaml.load(load_text_file_with_guess_encoding(self.user_path))
+        default_config = self.yaml.load(
+            load_text_file_with_guess_encoding(self.default_path)
+        )
+        extra_keys = self.get_extra_keys(user_config, default_config)
+
+        def delete_key_by_path(config_dict, key_path):
+            keys = key_path.split(".")
+            sub_dict = config_dict
+            for k in keys[:-1]:
+                if k in sub_dict and isinstance(sub_dict[k], dict):
+                    sub_dict = sub_dict[k]
+                else:
+                    return False
+            return sub_dict.pop(keys[-1], None) is not None
+
+        deleted_keys = []
+        for key_path in extra_keys:
+            if delete_key_by_path(user_config, key_path):
+                deleted_keys.append(key_path)
+
+        with open(self.user_path, "w", encoding="utf-8") as f:
+            self.yaml.dump(user_config, f)
+
+        self.logger.info(
+            self.texts_compare["extra_keys_deleted_count"].format(
+                count=len(deleted_keys)
+            )
+        )
+        for key in deleted_keys:
+            self.logger.info(
+                self.texts_compare["extra_keys_deleted_item"].format(key=key)
+            )
+
+    def compare_field_keys(self) -> bool:
+        """Compare field structure differences (missing/extra keys)"""
+
+        def field_compare_fn(user, default):
+            missing = self.get_missing_keys(user, default)
+            extra = self.get_extra_keys(user, default)
+
+            if missing:
+                self.logger.warning(
+                    self.texts_compare["missing_keys"].format(keys=", ".join(missing))
+                )
+            if extra:
+                self.logger.warning(
+                    self.texts_compare["extra_keys"].format(keys=", ".join(extra))
+                )
+                self.delete_extra_keys()
+            return (not missing, missing + extra)
+
+        return self.upgrade_utils.compare_dicts(
+            name="keys",
+            get_a=lambda: self.yaml.load(
+                load_text_file_with_guess_encoding(self.user_path)
+            ),
+            get_b=lambda: self.yaml.load(
+                load_text_file_with_guess_encoding(self.default_path)
+            ),
+            compare_fn=field_compare_fn,
+        )
+
+    def compare_comments(self) -> bool:
+        return self.upgrade_utils.compare_dicts(
+            name="comments",
+            get_a=lambda: load_text_file_with_guess_encoding(self.user_path),
+            get_b=lambda: load_text_file_with_guess_encoding(self.default_path),
+            compare_fn=comment_diff_fn,
+        )
+
+    def get_latest_version(self):
+        with open(self.default_path, "r", encoding="utf-8") as f:
+            default_config = self.yaml.load(f)
+        return default_config.get("system_config", {}).get("conf_version", "")
+
+    def get_old_version(self) -> str:
+        """
+        Extract the old version from backup config.
+        If missing or too old (< v1.1.1), fallback to v1.1.1.
+        """
+        fallback_version = "v1.1.1"
+        try:
+            yaml = YAML()
+            with open(BACKUP_CONF, "r", encoding="utf-8") as f:
+                backup_conf = yaml.load(f)
+                raw_version = backup_conf.get("system_config", {}).get(
+                    "conf_version", fallback_version
+                )
+
+                if version.parse(raw_version) < version.parse(fallback_version):
+                    self.logger.warning(
+                        self.texts["version_too_old"].format(
+                            found=raw_version, adjusted=fallback_version
+                        )
+                    )
+                    return fallback_version
+
+                self.logger.info(
+                    self.texts["backup_used_version"].format(backup_version=raw_version)
+                )
+                return raw_version
+        except Exception as e:
+            self.logger.warning(
+                self.texts["backup_read_error"].format(
+                    version=fallback_version, error=e
+                )
+            )
+            return fallback_version

upgrade_codes/from_version/v_1_1_1.py

@@ -0,0 +1,119 @@
+import copy
+import yaml
+
+
+class to_v_1_2_1:
+    def __init__(self, old_model_list, conf_yaml_path, language):
+        """
+        :param old_model_list: list of dicts (each representing a Live2D model config)
+        :param conf_yaml_path: path to conf.yaml that should be upgraded
+        :param language: language of the configuration ("zh" or "en")
+        """
+        self.old_models = old_model_list
+        self.conf_yaml_path = conf_yaml_path
+        self.language = language
+
+        # Configuration migration mapping table (language-specific)
+        self.migration_map = {
+            "zh": {
+                "shizuku.png": "mao.png",
+                "Shizuku": "Mao",
+                "shizuku-local": "mao_pro",
+                "shizuku-local-001": "mao_pro_001",
+                "distil-medium.en": "large-v3-turbo",
+                "en": "zh",
+                "v1.1.1": "v1.2.1",
+                "v1.2.0": "v1.2.1",
+            },
+            "en": {
+                "shizuku.png": "mao.png",
+                "Shizuku": "Mao",
+                "shizuku-local": "mao_pro",
+                "shizuku-local-001": "mao_pro_001",
+                "distil-medium.en": "large-v3-turbo",
+                "v1.1.1": "v1.2.1",
+                "v1.2.0": "v1.2.1",
+            },
+        }
+
+    def upgrade(self):
+        """
+        Return upgraded model_dict structure including 'models' list and new version
+        And perform in-place upgrade of conf.yaml
+        """
+        upgraded_models = self._upgrade_live2d_models(self.old_models)
+        self._upgrade_conf_yaml()
+        return upgraded_models
+
+    def _upgrade_live2d_models(self, old_model_list: list) -> list:
+        deprecated = {
+            "other_unit_90001",
+            "player_unit_00003",
+            "mashiro",
+            "shizuku-local",
+            "shizuku",
+        }
+        upgrades = {"mao_pro"}
+        new_models = []
+
+        for model in old_model_list:
+            name = model.get("name")
+            if name in deprecated:
+                continue
+
+            upgraded = copy.deepcopy(model)
+
+            if name in upgrades:
+                if name == "mao_pro":
+                    upgraded["url"] = (
+                        "/live2d-models/mao_pro/runtime/mao_pro.model3.json"
+                    )
+                    upgraded["kScale"] = 0.5
+
+            new_models.append(upgraded)
+
+        return new_models
+
+    def _upgrade_conf_yaml(self):
+        try:
+            with open(self.conf_yaml_path, "r", encoding="utf-8") as f:
+                data = yaml.safe_load(f)
+
+            # Update system version number
+            if "system_config" in data and isinstance(data["system_config"], dict):
+                data["system_config"]["conf_version"] = "v1.2.1"
+
+            # Update VAD config
+            vad_config = data.get("character_config", {}).get("vad_config", {})
+            if vad_config.get("vad_model") == "silero_vad":
+                vad_config["vad_model"] = None
+
+            # Update role-related configurations
+            char_config = data.get("character_config", {})
+            self._migrate_field(char_config, "avatar")
+            self._migrate_field(char_config, "character_name")
+            self._migrate_field(char_config, "conf_name")
+            self._migrate_field(char_config, "conf_uid")
+            self._migrate_field(char_config, "live2d_model_name")
+
+            # Update ASR config
+            asr_config = char_config.get("asr_config", {}).get("faster_whisper", {})
+            self._migrate_field(asr_config, "model_path")
+
+            if self.language == "zh":
+                self._migrate_field(asr_config, "language")
+
+            with open(self.conf_yaml_path, "w", encoding="utf-8") as f:
+                yaml.safe_dump(
+                    data, f, allow_unicode=True, sort_keys=False, default_style="'"
+                )  # Auto formatting with '
+
+        except Exception as e:
+            raise RuntimeError(f"Failed to upgrade conf.yaml: {e}")
+
+    def _migrate_field(self, config_section: dict, field_name: str):
+        if field_name in config_section:
+            current_value = config_section[field_name]
+            lang_map = self.migration_map.get(self.language, {})
+            new_value = lang_map.get(current_value, current_value)
+            config_section[field_name] = new_value

upgrade_codes/upgrade_core/comment_diff_fn.py

@@ -0,0 +1,54 @@
+from io import StringIO
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap
+
+
+def get_comment_text(comment_list):
+    if not comment_list:
+        return ""
+    flattened = []
+    for c in comment_list:
+        if isinstance(c, list):
+            for sub in c:
+                if hasattr(sub, "value"):
+                    flattened.append(str(sub.value).strip())
+        elif hasattr(c, "value"):
+            flattened.append(str(c.value).strip())
+    return "\n".join(flattened).strip()
+
+
+def extract_comments(yaml_text: str) -> dict:
+    yaml = YAML()
+    yaml.preserve_quotes = True
+    data = yaml.load(StringIO(yaml_text))
+
+    comment_map = {}
+
+    def recurse(node, path=""):
+        if not isinstance(node, CommentedMap):
+            return
+        if hasattr(node, "ca") and isinstance(node.ca.items, dict):
+            for key in node:
+                full_path = f"{path}.{key}" if path else str(key)
+                if key in node.ca.items:
+                    comment_map[full_path] = get_comment_text(node.ca.items[key])
+                recurse(node[key], full_path)
+
+    recurse(data)
+    return comment_map
+
+
+def comment_diff_fn(default_text: str, user_text: str):
+    default_comments = extract_comments(default_text)
+    user_comments = extract_comments(user_text)
+
+    diff_keys = []
+
+    all_keys = set(default_comments.keys()) | set(user_comments.keys())
+    for key in all_keys:
+        d = default_comments.get(key, "")
+        u = user_comments.get(key, "")
+        if d != u:
+            diff_keys.append(key)
+
+    return (len(diff_keys) == 0), diff_keys

upgrade_codes/upgrade_core/comment_sync.py

@@ -0,0 +1,56 @@
+# upgrade/comment_sync.py
+from typing import Dict
+from logging import Logger
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap
+
+
+class CommentSynchronizer:
+    def __init__(
+        self,
+        default_path: str,
+        user_path: str,
+        logger: Logger,
+        yaml: YAML,
+        texts_compare: Dict[str, str],
+    ):
+        self.default_path = default_path
+        self.user_path = user_path
+        self.logger = logger
+        self.yaml = yaml
+        self.texts_compare = texts_compare
+
+    def sync(self) -> None:
+        try:
+            with open(self.default_path, "r", encoding="utf-8") as f:
+                default_tree: CommentedMap = self.yaml.load(f)
+            with open(self.user_path, "r", encoding="utf-8") as f:
+                user_tree: CommentedMap = self.yaml.load(f)
+
+            def sync_comments(
+                default_node: CommentedMap, user_node: CommentedMap, path: str = ""
+            ) -> None:
+                if not isinstance(default_node, CommentedMap) or not isinstance(
+                    user_node, CommentedMap
+                ):
+                    return
+
+                for key in default_node:
+                    if key in user_node:
+                        current_path = f"{path}.{key}" if path else key
+                        if hasattr(default_node, "ca") and hasattr(user_node, "ca"):
+                            if key in default_node.ca.items:
+                                user_node.ca.items[key] = default_node.ca.items[key]
+                        sync_comments(default_node[key], user_node[key], current_path)
+
+            sync_comments(default_tree, user_tree)
+
+            if hasattr(default_tree, "ca") and hasattr(user_tree, "ca"):
+                user_tree.ca.end = default_tree.ca.end
+
+            with open(self.user_path, "w", encoding="utf-8") as f:
+                self.yaml.dump(user_tree, f)
+
+            self.logger.info(self.texts_compare["comment_sync_success"])
+        except Exception as e:
+            self.logger.error(self.texts_compare["comment_sync_error"].format(error=e))

upgrade_codes/upgrade_core/constants.py

@@ -0,0 +1,274 @@
+# upgrade/constants.py
+# CURRENT_SCRIPT_VERSION = "0.2.0"
+from ruamel.yaml import YAML
+from src.open_llm_vtuber.config_manager.utils import load_text_file_with_guess_encoding
+import os
+
+USER_CONF = "conf.yaml"
+BACKUP_CONF = "conf.yaml.backup"
+
+ZH_DEFAULT_CONF = "config_templates/conf.ZH.default.yaml"
+EN_DEFAULT_CONF = "config_templates/conf.default.yaml"
+
+yaml = YAML()
+# user_config = yaml.load(load_text_file_with_guess_encoding(USER_CONF))
+# CURRENT_SCRIPT_VERSION = user_config.get("system_config", {}).get("conf_version")
+
+
+def load_user_config():
+    if not os.path.exists(USER_CONF):
+        return None
+    text = load_text_file_with_guess_encoding(USER_CONF)
+    if text is None:
+        return None
+    return yaml.load(text)
+
+
+def get_current_script_version():
+    config = load_user_config()
+    if config:
+        return config.get("system_config", {}).get("conf_version", "UNKNOWN")
+    return "UNKNOWN"
+
+
+CURRENT_SCRIPT_VERSION = get_current_script_version()
+
+TEXTS = {
+    "zh": {
+        # "welcome_message": f"Auto-Upgrade Script {CURRENT_SCRIPT_VERSION}\nOpen-LLM-VTuber 升级脚本 - 此脚本仍在实验阶段，可能无法按预期工作。",
+        "welcome_message": f"正在从 {CURRENT_SCRIPT_VERSION} 自动升级...",
+        # "lang_select": "请选择语言/Please select language (zh/en):",
+        # "invalid_lang": "无效的语言选择，使用英文作为默认语言",
+        "not_git_repo": "错误：当前目录不是git仓库。请进入 Open-LLM-VTuber 目录后再运行此脚本。\n当然，更有可能的是你下载的Open-LLM-VTuber不包含.git文件夹 (如果你是透过下载压缩包而非使用 git clone 命令下载的话可能会造成这种情况)，这种情况下目前无法用脚本升级。",
+        "backup_user_config": "正在备份 {user_conf} 到 {backup_conf}",
+        "configs_up_to_date": "[DEBUG] 用户配置已是最新。",
+        "no_config": "警告：未找到conf.yaml文件",
+        "copy_default_config": "正在从模板复制默认配置",
+        "uncommitted": "发现未提交的更改，正在暂存...",
+        "stash_error": "错误：无法暂存更改",
+        "changes_stashed": "更改已暂存",
+        "pulling": "正在从远程仓库拉取更新...",
+        "pull_error": "错误：无法拉取更新",
+        "restoring": "正在恢复暂存的更改...",
+        "conflict_warning": "警告：恢复暂存的更改时发生冲突",
+        "manual_resolve": "请手动解决冲突",
+        "stash_list": "你可以使用 'git stash list' 查看暂存的更改",
+        "stash_pop": "使用 'git stash pop' 恢复更改",
+        "upgrade_complete": "升级完成！",
+        "check_config": "1. 请检查conf.yaml是否需要更新",
+        "resolve_conflicts": "2. 如果有配置文件冲突，请手动解决",
+        "check_backup": "3. 检查备份的配置文件以确保没有丢失重要设置",
+        "git_not_found": "错误：未检测到 Git。请先安装 Git:\nWindows: https://git-scm.com/download/win\nmacOS: brew install git\nLinux: sudo apt install git",
+        "operation_preview": """
+此脚本将执行以下操作：
+1. 备份当前的 conf.yaml 配置文件
+2. 暂存所有未提交的更改 (git stash)
+3. 从远程仓库拉取最新代码 (git pull)
+4. 尝试恢复之前暂存的更改 (git stash pop)
+
+是否继续？(y/N): """,
+        "merged_config_success": "新增配置项已合并:",
+        "merged_config_none": "未发现新增配置项。",
+        "merge_failed": "配置合并失败: {error}",
+        "updating_submodules": "正在更新子模块...",
+        "submodules_updated": "子模块更新完成",
+        "submodule_error": "更新子模块时出错",
+        "no_submodules": "未检测到子模块，跳过更新",
+        "env_info": "系统环境: {os_name} {os_version}, Python {python_version}",
+        "git_version": "Git 版本: {git_version}",
+        "current_branch": "当前分支: {branch}",
+        "operation_time": "操作 '{operation}' 完成, 耗时: {time:.2f} 秒",
+        "checking_stash": "检查是否有未提交的更改...",
+        "detected_changes": "检测到 {count} 个文件有更改",
+        "submodule_updating": "正在更新子模块: {submodule}",
+        "submodule_updated": "子模块已更新: {submodule}",
+        "submodule_update_error": "❌ 子模块更新失败。",
+        "checking_remote": "正在检查远程仓库状态...",
+        "remote_ahead": "本地版本已是最新",
+        "remote_behind": "发现 {count} 个新提交可供更新",
+        "config_backup_path": "配置备份路径: {path}",
+        "start_upgrade": "开始升级流程...",
+        "version_upgrade_success": "配置版本已成功升级: {old} → {new}",
+        "version_upgrade_none": "无需升级配置，当前版本为 {version}",
+        "version_upgrade_failed": "升级配置时出错: {error}",
+        "finish_upgrade": "升级流程结束, 总耗时: {time:.2f} 秒",
+        "backup_used_version": "✅ 从备份文件读取配置版本: {backup_version}",
+        "backup_read_error": "⚠️ 读取备份文件失败，使用默认版本 {version}。错误信息: {error}",
+        "version_too_old": "🔁 检测到旧版本号 {found} 低于最低支持版本，已强制使用 {adjusted}",
+        "checking_ahead_status": "🔍 正在检查是否存在未推送的本地提交...",
+        "local_ahead": "🚨 你在 'main' 分支上有 {count} 个尚未推送到远程的本地 commit。",
+        "push_blocked": (
+            "⛔ 你没有权限推送到 'main' 分支。\n"
+            "这些 commit 只保存在本地，无法同步到 GitHub。\n"
+            "如果继续升级，可能会导致这些提交丢失或与远程版本发生冲突。"
+        ),
+        "backup_suggestion": (
+            "🛟 为了安全保存你的本地提交，你可以选择以下任意方式：\n"
+            "🔄 1. 撤销最近的提交（推荐）：\n"
+            "   • GitHub Desktop：点击右下角的 “Undo” 按钮\n"
+            "   • 终端命令：git reset --soft HEAD~1\n"
+            "📦 2. 导出 patch 文件（保留提交记录）：\n"
+            "   → 终端执行：git format-patch origin/main --stdout > backup.patch\n"
+            "🌿 3. 创建一个备份分支（保存当前状态）：\n"
+            "   → 终端执行：git checkout -b my-backup-before-upgrade\n"
+            "💡 提示：撤销 commit 后，你可以新建分支或导出补丁以继续操作。"
+        ),
+        "abort_upgrade": "🛑 为保护本地提交，升级流程已中止。",
+        "no_config_fatal": (
+            "❌ 未找到配置文件 conf.yaml。\n"
+            "请执行以下任一操作：\n"
+            "👉 将旧版配置文件复制到当前目录\n"
+            "👉 或运行 run_server.py 自动生成默认模板"
+        ),
+    },
+    "en": {
+        # "welcome_message": f"Auto-Upgrade Script {CURRENT_SCRIPT_VERSION}\nOpen-LLM-VTuber upgrade script - This script is highly experimental and may not work as expected.",
+        "welcome_message": f"Starting auto upgrade from {CURRENT_SCRIPT_VERSION}...",
+        # "lang_select": "请选择语言/Please select language (zh/en):",
+        # "invalid_lang": "Invalid language selection, using English as default",
+        "not_git_repo": "Error: Current directory is not a git repository. Please run this script inside the Open-LLM-VTuber directory.\nAlternatively, it is likely that the Open-LLM-VTuber you downloaded does not contain the .git folder (this can happen if you downloaded a zip archive instead of using git clone), in which case you cannot upgrade using this script.",
+        "backup_user_config": "Backing up {user_conf} to {backup_conf}",
+        "configs_up_to_date": "[DEBUG] User configuration is up-to-date.",
+        "no_config": "Warning: conf.yaml not found",
+        "copy_default_config": "Copying default configuration from template",
+        "uncommitted": "Found uncommitted changes, stashing...",
+        "stash_error": "Error: Unable to stash changes",
+        "changes_stashed": "Changes stashed",
+        "pulling": "Pulling updates from remote repository...",
+        "pull_error": "Error: Unable to pull updates",
+        "restoring": "Restoring stashed changes...",
+        "conflict_warning": "Warning: Conflicts occurred while restoring stashed changes",
+        "manual_resolve": "Please resolve conflicts manually",
+        "stash_list": "Use 'git stash list' to view stashed changes",
+        "stash_pop": "Use 'git stash pop' to restore changes",
+        "upgrade_complete": "Upgrade complete!",
+        "check_config": "1. Please check if conf.yaml needs updating",
+        "resolve_conflicts": "2. Resolve any config file conflicts manually",
+        "check_backup": "3. Check backup config to ensure no important settings are lost",
+        "git_not_found": "Error: Git not found. Please install Git first:\nWindows: https://git-scm.com/download/win\nmacOS: brew install git\nLinux: sudo apt install git",
+        "operation_preview": """
+This script will perform the following operations:
+1. Backup current conf.yaml configuration file
+2. Stash all uncommitted changes (git stash)
+3. Pull latest code from remote repository (git pull)
+4. Attempt to restore previously stashed changes (git stash pop)
+
+Continue? (y/N): """,
+        "merged_config_success": "Merged new configuration items:",
+        "merged_config_none": "No new configuration items found.",
+        "merge_failed": "Configuration merge failed: {error}",
+        "updating_submodules": "Updating submodules...",
+        "submodules_updated": "Submodules updated successfully",
+        "submodule_error": "Error updating submodules",
+        "no_submodules": "No submodules detected, skipping update",
+        "env_info": "Environment: {os_name} {os_version}, Python {python_version}",
+        "git_version": "Git version: {git_version}",
+        "current_branch": "Current branch: {branch}",
+        "operation_time": "Operation '{operation}' completed in {time:.2f} seconds",
+        "checking_stash": "Checking for uncommitted changes...",
+        "detected_changes": "Detected changes in {count} files",
+        "submodule_updating": "Updating submodule: {submodule}",
+        "submodule_updated": "Submodule updated: {submodule}",
+        "submodule_update_error": "❌ Submodule update failed.",
+        "checking_remote": "Checking remote repository status...",
+        "remote_ahead": "Local version is up to date",
+        "remote_behind": "Found {count} new commits to pull",
+        "config_backup_path": "Config backup path: {path}",
+        "start_upgrade": "Starting upgrade process...",
+        "version_upgrade_success": "Config version upgraded: {old} → {new}",
+        "version_upgrade_none": "No upgrade needed. Current version is {version}",
+        "version_upgrade_failed": "Failed to upgrade config version: {error}",
+        "finish_upgrade": "Upgrade process completed, total time: {time:.2f} seconds",
+        "backup_used_version": "✅ Loaded config version from backup: {backup_version}",
+        "backup_read_error": "⚠️ Failed to read backup file. Falling back to default version {version}. Error: {error}",
+        "version_too_old": "🔁 Detected old version {found} which is lower than the minimum supported version, forced to use {adjusted}",
+        "checking_ahead_status": "🔍 Checking for unpushed local commits...",
+        "local_ahead": "🚨 You have {count} local commit(s) on 'main' that are NOT pushed to remote.",
+        "push_blocked": (
+            "⛔ You do NOT have permission to push to the 'main' branch.\n"
+            "Your commits are local only and will NOT be synced to GitHub.\n"
+            "Continuing the upgrade may cause those commits to be lost or conflict with remote changes."
+        ),
+        "backup_suggestion": (
+            "🛟 To keep your work safe, you can choose one of the following options:\n"
+            "🔄 1. Undo the last commit:\n"
+            "   • GitHub Desktop: Click the 'Undo' button at the bottom right.\n"
+            "   • Terminal: Run: git reset --soft HEAD~1\n"
+            "📦 2. Export your commit(s) as a patch file:\n"
+            "   → Run: git format-patch origin/main --stdout > backup.patch\n"
+            "🌿 3. Create a backup branch:\n"
+            "   → Run: git checkout -b my-backup-before-upgrade\n"
+            "💡 Recommendation: After undoing the commit, you can switch to a new branch or export changes as needed."
+        ),
+        "abort_upgrade": "🛑 Upgrade aborted to protect your local commits.",
+        "no_config_fatal": (
+            "❌ Config file conf.yaml not found.\n"
+            "Please either:\n"
+            "👉 Copy your old config file to the current directory\n"
+            "👉 Or run run_server.py to generate a default template"
+        ),
+    },
+}
+
+# Multilingual texts for merge_configs log messages
+TEXTS_MERGE = {
+    "zh": {
+        "new_config_item": "[信息] 新增配置项: {key}",
+    },
+    "en": {
+        "new_config_item": "[INFO] New config item: {key}",
+    },
+}
+
+# Multilingual texts for compare_configs log messages
+TEXTS_COMPARE = {
+    "zh": {
+        "missing_keys": "用户配置缺少以下键，可能与默认配置不一致: {keys}",
+        "extra_keys": "用户配置包含以下默认配置中不存在的键: {keys}",
+        "up_to_date": "用户配置与默认配置一致。",
+        "compare_passed": "{name} 对比通过。",
+        "compare_failed": "{name} 配置不一致。",
+        "compare_diff_item": "- {item}",
+        "compare_error": "{name} 对比失败: {error}",
+        "comments_up_to_date": "注释一致，跳过注释同步。",
+        "extra_keys_deleted_count": "已删除 {count} 个额外键:",
+        "extra_keys_deleted_item": "  - {key}",
+        "comment_sync_success": "注释同步成功。",
+        "comment_sync_error": "注释同步失败: {error}",
+    },
+    "en": {
+        "missing_keys": "User config is missing the following keys, which may be out-of-date: {keys}",
+        "extra_keys": "User config contains the following keys not present in default config: {keys}",
+        "up_to_date": "User config is up-to-date with default config.",
+        "compare_passed": "{name} comparison passed.",
+        "compare_failed": "{name} comparison failed: configs differ.",
+        "compare_diff_item": "- {item}",
+        "compare_error": "{name} comparison error: {error}",
+        "comments_up_to_date": "Comments are up to date, skipping comment sync.",
+        "extra_keys_deleted_count": "Deleted {count} extra keys:",
+        "extra_keys_deleted_item": "  - {key}",
+        "comment_sync_success": "All comments synchronized successfully.",
+        "comment_sync_error": "Failed to synchronize comments: {error}",
+    },
+}
+
+UPGRADE_TEXTS = {
+    "zh": {
+        "model_dict_not_found": "⚠️ 未找到 model_dict.json，跳过升级。",
+        "model_dict_read_error": "❌ 读取 model_dict.json 失败: {error}",
+        "upgrade_success": "✅ model_dict.json 已成功升级至 v1.2.1 格式 ({language} 语言)",
+        "already_latest": "model_dict.json 已是最新格式。",
+        "upgrade_error": "❌ 升级 model_dict.json 失败: {error}",
+        "no_upgrade_routine": "没有适用于版本 {version} 的升级程序",
+        "upgrading_path": "⬆️ 正在升级配置: {from_version} → {to_version}",
+    },
+    "en": {
+        "model_dict_not_found": "⚠️ model_dict.json not found. Skipping upgrade.",
+        "model_dict_read_error": "❌ Failed to read model_dict.json: {error}",
+        "upgrade_success": "✅ model_dict.json upgraded to v1.2.1 format ({language} language)",
+        "already_latest": "model_dict.json already in latest format.",
+        "upgrade_error": "❌ Failed to upgrade model_dict.json: {error}",
+        "no_upgrade_routine": "No upgrade routine for version {version}",
+        "upgrading_path": "⬆️ Upgrading config: {from_version} → {to_version}",
+    },
+}

upgrade_codes/upgrade_core/language.py

@@ -0,0 +1,61 @@
+import os
+import sys
+import ctypes
+import locale
+import platform
+import subprocess
+
+
+def get_system_language():
+    """Get system language using a combination of methods."""
+
+    os_name = platform.system()
+
+    if os_name == "Windows":
+        try:
+            # Use Windows API to get the UI language
+            windll = ctypes.windll.kernel32  # type: ignore
+            ui_lang = windll.GetUserDefaultUILanguage()
+            lang_code = locale.windows_locale.get(ui_lang)
+            if lang_code:
+                lang = lang_code.split("_")[0]
+                if lang.startswith("zh"):
+                    return "zh"
+        except Exception:
+            pass
+
+    elif os_name == "Darwin":  # macOS
+        try:
+            # Use defaults command to get the AppleLocale
+            result = subprocess.run(
+                ["defaults", "read", "-g", "AppleLocale"],
+                capture_output=True,
+                text=True,
+            )
+            lang = result.stdout.strip().split("_")[0]
+            if lang.startswith("zh"):
+                return "zh"
+        except Exception:
+            pass
+
+    elif os_name == "Linux":
+        # Check the LANG environment variable
+        lang = os.environ.get("LANG")
+        if lang:
+            lang = lang.split("_")[0]
+            if lang.startswith("zh"):
+                return "zh"
+
+    # Fallback to using locale.getpreferredencoding()
+    encoding = locale.getpreferredencoding()
+    if encoding.lower() in ("cp936", "gbk", "big5"):
+        return "zh"
+
+    return "en"
+
+
+def select_language():
+    """Select language based on command-line argument or system language"""
+    if len(sys.argv) > 1 and sys.argv[1].lower() in ["zh", "en"]:
+        return sys.argv[1].lower()
+    return get_system_language()

upgrade_codes/upgrade_core/upgrade_utils.py

@@ -0,0 +1,147 @@
+import os
+import platform
+import subprocess
+import sys
+import time
+from upgrade_codes.upgrade_core.constants import TEXTS, TEXTS_COMPARE
+from typing import Callable, Any
+
+
+class UpgradeUtility:
+    def __init__(self, logger, lang):
+        self.logger = logger
+        self.lang = lang
+        self.texts = TEXTS[lang]
+        self.texts_compare = TEXTS_COMPARE[lang]
+
+    def run_command(self, command):
+        """Run shell command and return result"""
+        try:
+            result = subprocess.run(
+                command,
+                shell=True,
+                check=True,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            return True, result.stdout
+        except subprocess.CalledProcessError as e:
+            return (
+                False,
+                f"Command failed with error code {e.returncode}\nError: {e.stderr}",
+            )
+        except Exception as e:
+            return False, f"Unexpected error: {str(e)}"
+
+    def check_git_installed(self):
+        """Check if Git is installed"""
+        command = "where git" if sys.platform == "win32" else "which git"
+        try:
+            result = subprocess.run(command, shell=True, capture_output=True, text=True)
+            return result.returncode == 0
+        except subprocess.SubprocessError:
+            return False
+
+    def log_system_info(self):
+        """Log detailed system information"""
+        texts = self.texts
+
+        # Log OS info
+        os_name = platform.system()
+        os_version = platform.version()
+        python_version = platform.python_version()
+        self.logger.info(
+            texts["env_info"].format(
+                os_name=os_name, os_version=os_version, python_version=python_version
+            )
+        )
+
+        # Log Git version
+        success, git_version = self.run_command("git --version")
+        if success:
+            self.logger.info(
+                texts["git_version"].format(git_version=git_version.strip())
+            )
+
+        # Log current branch
+        success, branch = self.run_command("git branch --show-current")
+        if success:
+            self.logger.info(texts["current_branch"].format(branch=branch.strip()))
+
+    def time_operation(self, func, *args, **kwargs):
+        """Time an operation and return result with timing information"""
+        start_time = time.time()
+        result = func(*args, **kwargs)
+        end_time = time.time()
+        elapsed = end_time - start_time
+        return result, elapsed
+
+    def get_submodule_list(self):
+        """Get a list of submodules"""
+        if not os.path.exists(".gitmodules"):
+            return []
+
+        success, output = self.run_command(
+            "git config --file .gitmodules --get-regexp path"
+        )
+        if not success:
+            return []
+
+        submodules = []
+        for line in output.strip().split("\n"):
+            if line:
+                parts = line.strip().split(" ", 1)
+                if len(parts) >= 2:
+                    submodules.append(parts[1])
+
+        return submodules
+
+    def has_submodules(self):
+        """Check if the repository has submodules by looking for .gitmodules file"""
+        return os.path.exists(".gitmodules")
+
+    def compare_dicts(
+        self,
+        name: str,
+        get_a: Callable[[], Any],
+        get_b: Callable[[], Any],
+        compare_fn: Callable[[Any, Any], Any],
+    ) -> bool:
+        try:
+            a = get_a()
+            b = get_b()
+            comparison_result = compare_fn(a, b)
+
+            if isinstance(comparison_result, tuple):
+                is_equal, differences = comparison_result
+            else:
+                is_equal, differences = comparison_result, []
+
+            if is_equal:
+                msg = self.texts_compare.get(
+                    "compare_passed", "[DEBUG] {name} comparison passed."
+                )
+                self.logger.debug(msg.format(name=name))
+                return True
+            else:
+                msg = self.texts_compare.get(
+                    "compare_failed",
+                    "[WARNING] {name} comparison failed: configs differ.",
+                )
+                self.logger.warning(msg.format(name=name))
+                if differences:
+                    for item in differences:
+                        self.logger.warning(
+                            self.texts_compare.get(
+                                "compare_diff_item", "- {item}"
+                            ).format(item=item)
+                        )
+                return False
+        except Exception as e:
+            msg = self.texts_compare.get(
+                "compare_error", "[ERROR] {name} comparison error: {error}"
+            )
+            self.logger.error(msg.format(name=name, error=e))
+            return False

upgrade_codes/upgrade_manager.py

@@ -0,0 +1,67 @@
+from loguru import logger
+from upgrade_codes.upgrade_core.language import select_language
+from upgrade_codes.config_sync import ConfigSynchronizer
+from upgrade_codes.upgrade_core.upgrade_utils import UpgradeUtility
+import os
+from datetime import datetime
+import sys
+from upgrade_codes.upgrade_core.constants import USER_CONF, TEXTS
+
+
+class UpgradeManager:
+    def __init__(self):
+        self.lang = select_language()
+        self._configure_logger()
+        self.logger = logger
+        self.upgrade_utils = UpgradeUtility(self.logger, self.lang)
+        self.config_sync = ConfigSynchronizer(self.lang, self.logger)
+        self.texts = TEXTS
+
+    def check_user_config_exists(self):
+        if not os.path.exists(USER_CONF):
+            print(self.texts[self.lang]["no_config_fatal"])
+            exit(1)
+
+    def _configure_logger(self):
+        logger.remove()
+        log_dir = "logs"
+        os.makedirs(log_dir, exist_ok=True)
+        log_file = os.path.join(
+            log_dir, f"upgrade_{datetime.now().strftime('%Y-%m-%d-%H-%M')}.log"
+        )
+
+        logger.add(
+            sys.stdout,
+            level="DEBUG",
+            colorize=True,
+            format="<green>[{level}]</green> <level>{message}</level>",
+        )
+        logger.add(
+            log_file,
+            level="DEBUG",
+            format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {message}",
+        )
+
+    def sync_user_config(self):
+        self.config_sync.sync_user_config()
+
+    def update_user_config(self):
+        self.config_sync.update_user_config()
+
+    def log_system_info(self):
+        return self.upgrade_utils.log_system_info()
+
+    def check_git_installed(self):
+        return self.upgrade_utils.check_git_installed()
+
+    def run_command(self, command):
+        return self.upgrade_utils.run_command(command)
+
+    def time_operation(self, func, *args, **kwargs):
+        return self.upgrade_utils.time_operation(func, *args, **kwargs)
+
+    def get_submodule_list(self):
+        return self.upgrade_utils.get_submodule_list()
+
+    def has_submodules(self):
+        return self.upgrade_utils.has_submodules()

upgrade_codes/version_manager.py

@@ -0,0 +1,94 @@
+import json
+from pathlib import Path
+from packaging.version import parse as parse_version
+from upgrade_codes.upgrade_core.constants import USER_CONF, UPGRADE_TEXTS
+from upgrade_codes.from_version.v_1_1_1 import to_v_1_2_1
+
+
+class VersionUpgradeManager:
+    def __init__(self, language, logger):
+        self.logger = logger
+        self.language = language
+        self.log_texts = UPGRADE_TEXTS.get(language, UPGRADE_TEXTS["en"])
+        self.indent_spaces = 4
+        self.user_config = USER_CONF
+
+    def get_upgrade_mapping(self):
+        """
+        Define version upgrade tasks using version ranges.
+        Each task maps a range [from_version, to_version) to a specific upgrade module.
+        """
+        return [
+            {
+                "from_range": (
+                    "v1.1.1",
+                    "v1.2.1",
+                ),  # Inclusive lower bound, exclusive upper bound
+                "from_version": "v1.1.1",
+                "to_version": "v1.2.1",
+                "module": to_v_1_2_1,
+            },
+            # Future upgrade example:
+            # {
+            #     "from_range": ("v1.2.1", "v1.3.0"),
+            #     "from_version": "v1.2.1",
+            #     "to_version": "v1.3.0",
+            #     "module": to_v_1_3_0,
+            # },
+        ]
+
+    def resolve_upgrade_task(self, current_version: str):
+        """
+        Determine which upgrade task applies to the given current_version.
+        Returns a tuple of (from_version, to_version, module) if matched, else None.
+        """
+        parsed_current = parse_version(current_version.strip("v"))
+        for task in self.get_upgrade_mapping():
+            low = parse_version(task["from_range"][0].strip("v"))
+            high = parse_version(task["from_range"][1].strip("v"))
+            if low <= parsed_current < high:
+                return task["from_version"], task["to_version"], task["module"]
+        return None
+
+    def upgrade(self, current_version: str) -> str:
+        """
+        Perform the upgrade process starting from current_version.
+        If a matching version range is found, run the corresponding upgrade module.
+        """
+        task = self.resolve_upgrade_task(current_version)
+        if not task:
+            self.logger.info(
+                self.log_texts["no_upgrade_routine"].format(version=current_version)
+            )
+            return current_version
+
+        from_version, to_version, module = task
+        self.logger.info(
+            self.log_texts["upgrading_path"].format(
+                from_version=current_version, to_version=to_version
+            )
+        )
+        upgraded_version = current_version
+
+        try:
+            model_path = Path("model_dict.json")
+            with open(model_path, "r", encoding="utf-8") as f:
+                model_dict = json.load(f)
+
+            if isinstance(model_dict, list):
+                new_data = module(model_dict, self.user_config, self.language).upgrade()
+                with open(model_path, "w", encoding="utf-8") as f:
+                    json.dump(
+                        new_data, f, indent=self.indent_spaces, ensure_ascii=False
+                    )
+
+                upgraded_version = to_version
+                self.logger.info(
+                    self.log_texts["upgrade_success"].format(language=self.language)
+                )
+            else:
+                self.logger.info(self.log_texts["already_latest"])
+        except Exception as e:
+            self.logger.error(self.log_texts["upgrade_error"].format(error=e))
+
+        return upgraded_version

web_tool/README.md

@@ -0,0 +1,13 @@
+# Web Tool
+
+
+## Why?
+The Open-LLM-VTuber project leverages TTS and ASR (speech recognition) models to deliver an immersive, voice-to-voice AI companion experience.
+
+While ASR and TTS technologies are powerful on their own, setting them up can be challenging. Previously, although our users installed the TTS and ASR models into our project, they were exclusively accessible as a part of the Open-LLM-VTuber's AI companion feature, preventing their use for other purposes like transcription or speech generation.
+
+## What is Web Tool?
+
+This is a dedicated web page within the Open-LLM-VTuber backend that provides direct access to the ASR and TTS models initialized by the Open-LLM-VTuber server.
+
+Access the web page at: http://localhost:12393/web-tool. Note that the ASR and TTS models are the same ones you've set in the `conf.yaml` file, and switching models at runtime is not possible at this point.

web_tool/index.html

@@ -0,0 +1,143 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>ASR & TTS Tool</title>
+    <style>
+        body {
+            font-family: Arial, sans-serif;
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 20px;
+            line-height: 1.6;
+        }
+
+        .section {
+            margin-bottom: 30px;
+            padding: 20px;
+            border: 1px solid #ccc;
+            border-radius: 8px;
+            background-color: #f9f9f9;
+        }
+
+        .controls {
+            display: flex;
+            gap: 20px;
+            margin-bottom: 15px;
+        }
+
+        .record-controls,
+        .upload-controls {
+            display: flex;
+            gap: 10px;
+            align-items: center;
+        }
+
+        .file-input {
+            max-width: 200px;
+        }
+
+        .button {
+            padding: 10px 20px;
+            margin: 5px;
+            border: none;
+            border-radius: 5px;
+            background-color: #007bff;
+            color: white;
+            cursor: pointer;
+            transition: background-color 0.3s;
+        }
+
+        .button:hover {
+            background-color: #0056b3;
+        }
+
+        .button:disabled {
+            background-color: #cccccc;
+            cursor: not-allowed;
+        }
+
+        textarea {
+            width: 100%;
+            height: 100px;
+            margin: 10px 0;
+            padding: 10px;
+            border: 1px solid #ddd;
+            border-radius: 4px;
+            resize: vertical;
+        }
+
+        .status {
+            margin: 10px 0;
+            padding: 10px;
+            border-radius: 5px;
+            font-size: 14px;
+        }
+
+        .error {
+            background-color: #ffe6e6;
+            border: 1px solid #ffcccc;
+            color: #cc0000;
+        }
+
+        .success {
+            background-color: #e6ffe6;
+            border: 1px solid #ccffcc;
+            color: #006600;
+        }
+
+        #audioPlayer {
+            width: 100%;
+            margin: 10px 0;
+        }
+
+        h1,
+        h2 {
+            color: #333;
+        }
+
+        h1 {
+            border-bottom: 2px solid #007bff;
+            padding-bottom: 10px;
+            margin-bottom: 30px;
+        }
+    </style>
+</head>
+
+<body>
+    <h1>ASR & TTS Tool</h1>
+
+    <div class="section">
+        <h2>Speech Recognition</h2>
+        <div class="controls">
+            <div class="record-controls">
+                <button id="startRecording" class="button">Start Recording</button>
+                <button id="stopRecording" class="button" disabled>Stop Recording</button>
+            </div>
+            <div class="upload-controls">
+                <input type="file" id="audioFileInput" accept="audio/*"
+                    title="Supported formats: WAV, MP3, M4A, OGG, etc. Files will be converted to 16kHz mono WAV."
+                    class="file-input" />
+                <button id="uploadAudio" class="button">Upload Audio</button>
+            </div>
+        </div>
+        <div id="asrStatus" class="status"></div>
+        <textarea id="transcription" placeholder="Transcription will appear here..." readonly></textarea>
+    </div>
+
+    <div class="section">
+        <h2>Text to Speech</h2>
+        <textarea id="ttsInput" placeholder="Enter text for TTS..."></textarea>
+        <button id="generateSpeech" class="button">Generate Speech</button>
+        <div id="ttsStatus" class="status"></div>
+        <audio id="audioPlayer" controls></audio>
+        <button id="downloadAudio" class="button" disabled>Download Audio</button>
+    </div>
+
+    <script src="recorder.js"></script>
+    <script src="main.js"></script>
+</body>
+
+</html>

web_tool/main.js

@@ -0,0 +1,398 @@
+const API_BASE_URL = window.location.origin;
+const recorder = new AudioRecorder();
+
+// Audio context and buffers
+let audioContext = null;
+let audioBuffers = [];
+let pendingAudioPaths = new Set();
+let currentAudioPath = null;
+let ws = null;
+
+// DOM Elements
+const startRecordingBtn = document.getElementById('startRecording');
+const stopRecordingBtn = document.getElementById('stopRecording');
+const transcriptionArea = document.getElementById('transcription');
+const asrStatus = document.getElementById('asrStatus');
+const ttsInput = document.getElementById('ttsInput');
+const generateSpeechBtn = document.getElementById('generateSpeech');
+const ttsStatus = document.getElementById('ttsStatus');
+const audioPlayer = document.getElementById('audioPlayer');
+const downloadAudioBtn = document.getElementById('downloadAudio');
+const audioFileInput = document.getElementById('audioFileInput');
+const uploadAudioBtn = document.getElementById('uploadAudio');
+
+// File upload handler with format conversion
+uploadAudioBtn.addEventListener('click', async () => {
+    const file = audioFileInput.files[0];
+    if (!file) {
+        asrStatus.textContent = 'Please select an audio file';
+        asrStatus.className = 'status error';
+        return;
+    }
+
+    try {
+        asrStatus.textContent = 'Processing audio file...';
+        asrStatus.className = 'status';
+
+        // Convert audio to WAV format
+        const audioContext = new (window.AudioContext || window.webkitAudioContext)();
+        const arrayBuffer = await file.arrayBuffer();
+        const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
+        
+        // Create WAV file
+        const wavBuffer = await audioBufferToWav(audioBuffer);
+        const wavBlob = new Blob([wavBuffer], { type: 'audio/wav' });
+
+        const formData = new FormData();
+        formData.append('file', wavBlob, 'recording.wav');
+
+        const response = await fetch(`${API_BASE_URL}/asr`, {
+            method: 'POST',
+            body: formData
+        });
+
+        if (!response.ok) throw new Error('ASR request failed');
+
+        const data = await response.json();
+        transcriptionArea.value = data.text;
+        asrStatus.textContent = 'Transcription complete!';
+        asrStatus.className = 'status success';
+        
+        // Clean up
+        audioContext.close();
+    } catch (error) {
+        asrStatus.textContent = 'Error: ' + error.message;
+        asrStatus.className = 'status error';
+    }
+});
+
+// Recording handlers
+startRecordingBtn.addEventListener('click', async () => {
+    try {
+        asrStatus.textContent = 'Starting recording...';
+        asrStatus.className = 'status';
+        await recorder.start();
+        startRecordingBtn.disabled = true;
+        stopRecordingBtn.disabled = false;
+        asrStatus.textContent = 'Recording...';
+    } catch (error) {
+        asrStatus.textContent = 'Error starting recording: ' + error.message;
+        asrStatus.className = 'status error';
+    }
+});
+
+stopRecordingBtn.addEventListener('click', async () => {
+    try {
+        const audioBlob = await recorder.stop();
+        startRecordingBtn.disabled = false;
+        stopRecordingBtn.disabled = true;
+        asrStatus.textContent = 'Processing audio...';
+
+        // Send to ASR endpoint
+        const formData = new FormData();
+        formData.append('file', audioBlob);
+
+        const response = await fetch(`${API_BASE_URL}/asr`, {
+            method: 'POST',
+            body: formData
+        });
+
+        if (!response.ok) throw new Error('ASR request failed');
+
+        const data = await response.json();
+        transcriptionArea.value = data.text;
+        asrStatus.textContent = 'Transcription complete!';
+        asrStatus.className = 'status success';
+    } catch (error) {
+        asrStatus.textContent = 'Error: ' + error.message;
+        asrStatus.className = 'status error';
+        startRecordingBtn.disabled = false;
+        stopRecordingBtn.disabled = true;
+    }
+});
+
+// TTS handlers
+function connectWebSocket() {
+    const wsProtocol = window.location.protocol === 'https:' ? 'wss' : 'ws';
+    ws = new WebSocket(`${wsProtocol}://${window.location.host}/tts-ws`);
+    
+    ws.onopen = () => {
+        console.log('WebSocket connected');
+        generateSpeechBtn.disabled = false;
+        ttsStatus.textContent = 'Connected to TTS service';
+        ttsStatus.className = 'status success';
+        
+        // Initialize AudioContext if needed
+        if (!audioContext) {
+            audioContext = new (window.AudioContext || window.webkitAudioContext)();
+        } else if (audioContext.state === 'suspended') {
+            audioContext.resume();
+        }
+    };
+
+    ws.onmessage = async (event) => {
+        const response = JSON.parse(event.data);
+        
+        if (response.status === 'partial') {
+            ttsStatus.textContent = 'Generating audio...';
+            ttsStatus.className = 'status';
+            
+            try {
+                const audioPath = response.audioPath.split('/').pop();
+                pendingAudioPaths.add(audioPath);
+                
+                if (audioContext.state === 'suspended') {
+                    await audioContext.resume();
+                }
+                
+                // Use retry mechanism for fetching audio
+                const audioResponse = await fetchWithRetry(`${API_BASE_URL}/cache/${audioPath}`);
+                const arrayBuffer = await audioResponse.arrayBuffer();
+                
+                if (arrayBuffer.byteLength === 0) {
+                    throw new Error('Empty audio data received');
+                }
+                
+                const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
+                audioBuffers.push(audioBuffer);
+                pendingAudioPaths.delete(audioPath);
+            } catch (error) {
+                console.error('Error loading audio:', error);
+                ttsStatus.textContent = 'Error loading audio: ' + error.message;
+                ttsStatus.className = 'status error';
+                pendingAudioPaths.clear();
+            }
+        } else if (response.status === 'complete') {
+            // Wait for any pending audio loads to complete
+            if (pendingAudioPaths.size > 0) {
+                ttsStatus.textContent = 'Finalizing audio...';
+                await new Promise(resolve => setTimeout(resolve, 500));
+            }
+
+            try {
+                // Combine all audio buffers
+                const targetSampleRate = 16000;
+                const totalLength = audioBuffers.reduce((acc, buffer) => {
+                    // Calculate resampled length if needed
+                    const ratio = targetSampleRate / buffer.sampleRate;
+                    return acc + Math.ceil(buffer.length * ratio);
+                }, 0);
+                
+                const combinedBuffer = audioContext.createBuffer(
+                    1,  // mono
+                    totalLength,
+                    targetSampleRate
+                );
+                
+                let offset = 0;
+                for (const buffer of audioBuffers) {
+                    // Resample if needed
+                    let channelData = buffer.getChannelData(0);
+                    if (buffer.sampleRate !== targetSampleRate) {
+                        channelData = await resampleAudio(channelData, buffer.sampleRate, targetSampleRate);
+                    }
+                    combinedBuffer.copyToChannel(channelData, 0, offset);
+                    offset += channelData.length;
+                }
+                
+                // Convert to WAV for download
+                const wavBlob = new Blob([await audioBufferToWav(combinedBuffer)], { type: 'audio/wav' });
+                const audioUrl = URL.createObjectURL(wavBlob);
+                
+                // Update audio player
+                audioPlayer.src = audioUrl;
+                audioPlayer.load();
+                downloadAudioBtn.disabled = false;
+                
+                // Store for download
+                currentAudioPath = audioUrl;
+                
+                ttsStatus.textContent = 'Audio generated successfully!';
+                ttsStatus.className = 'status success';
+            } catch (error) {
+                console.error('Error combining audio:', error);
+                ttsStatus.textContent = 'Error combining audio: ' + error.message;
+                ttsStatus.className = 'status error';
+            } finally {
+                // Clear buffers
+                audioBuffers = [];
+                pendingAudioPaths.clear();
+            }
+        } else if (response.status === 'error') {
+            ttsStatus.textContent = 'Error: ' + response.message;
+            ttsStatus.className = 'status error';
+            audioBuffers = [];
+            pendingAudioPaths.clear();
+        }
+    };
+
+    ws.onclose = () => {
+        console.log('WebSocket disconnected');
+        generateSpeechBtn.disabled = true;
+        ttsStatus.textContent = 'Disconnected. Trying to reconnect...';
+        ttsStatus.className = 'status error';
+        
+        // Clean up any pending audio resources
+        audioBuffers = [];
+        pendingAudioPaths.clear();
+        if (currentAudioPath) {
+            URL.revokeObjectURL(currentAudioPath);
+            currentAudioPath = null;
+        }
+        
+        setTimeout(connectWebSocket, 5000);
+    };
+
+    ws.onerror = (error) => {
+        console.error('WebSocket error:', error);
+        ttsStatus.textContent = 'Connection error. Retrying...';
+        ttsStatus.className = 'status error';
+        
+        // Clean up audio resources on error
+        audioBuffers = [];
+        pendingAudioPaths.clear();
+        if (currentAudioPath) {
+            URL.revokeObjectURL(currentAudioPath);
+            currentAudioPath = null;
+        }
+    };
+}
+
+// Convert AudioBuffer to WAV with specific format requirements
+async function audioBufferToWav(buffer) {
+    // Resample to 16kHz if needed
+    let audioData = buffer.getChannelData(0);
+    if (buffer.sampleRate !== 16000) {
+        audioData = await resampleAudio(audioData, buffer.sampleRate, 16000);
+    }
+    
+    const numChannels = 1; // Mono
+    const sampleRate = 16000;
+    const format = 1; // PCM
+    const bitDepth = 16;
+    
+    const dataLength = audioData.length * (bitDepth / 8);
+    const headerLength = 44;
+    const totalLength = headerLength + dataLength;
+    
+    const arrayBuffer = new ArrayBuffer(totalLength);
+    const view = new DataView(arrayBuffer);
+    
+    // Write WAV header
+    writeString(view, 0, 'RIFF');
+    view.setUint32(4, totalLength - 8, true);
+    writeString(view, 8, 'WAVE');
+    writeString(view, 12, 'fmt ');
+    view.setUint32(16, 16, true);
+    view.setUint16(20, format, true);
+    view.setUint16(22, numChannels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, sampleRate * numChannels * (bitDepth / 8), true);
+    view.setUint16(32, numChannels * (bitDepth / 8), true);
+    view.setUint16(34, bitDepth, true);
+    writeString(view, 36, 'data');
+    view.setUint32(40, dataLength, true);
+    
+    // Write audio data
+    floatTo16BitPCM(view, 44, audioData);
+    
+    return arrayBuffer;
+}
+
+function resampleAudio(audioData, originalSampleRate, targetSampleRate) {
+    const ratio = targetSampleRate / originalSampleRate;
+    const newLength = Math.round(audioData.length * ratio);
+    const result = new Float32Array(newLength);
+    
+    for (let i = 0; i < newLength; i++) {
+        const position = i / ratio;
+        const index = Math.floor(position);
+        const fraction = position - index;
+        
+        if (index + 1 < audioData.length) {
+            result[i] = audioData[index] * (1 - fraction) + audioData[index + 1] * fraction;
+        } else {
+            result[i] = audioData[index];
+        }
+    }
+    
+    return result;
+}
+
+function writeString(view, offset, string) {
+    for (let i = 0; i < string.length; i++) {
+        view.setUint8(offset + i, string.charCodeAt(i));
+    }
+}
+
+function floatTo16BitPCM(view, offset, input) {
+    for (let i = 0; i < input.length; i++, offset += 2) {
+        const s = Math.max(-1, Math.min(1, input[i]));
+        view.setInt16(offset, s < 0 ? s * 0x8000 : s * 0x7FFF, true);
+    }
+}
+
+generateSpeechBtn.addEventListener('click', () => {
+    const text = ttsInput.value.trim();
+    if (!text) {
+        ttsStatus.textContent = 'Please enter some text';
+        ttsStatus.className = 'status error';
+        return;
+    }
+
+    if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ text }));
+        ttsStatus.textContent = 'Generating audio...';
+        ttsStatus.className = 'status';
+    } else {
+        ttsStatus.textContent = 'Connection lost. Reconnecting...';
+        ttsStatus.className = 'status error';
+        connectWebSocket();
+    }
+});
+
+downloadAudioBtn.addEventListener('click', () => {
+    if (currentAudioPath) {
+        const link = document.createElement('a');
+        link.href = currentAudioPath;
+        link.download = `combined_audio_${Date.now()}.wav`;
+        document.body.appendChild(link);
+        link.click();
+        document.body.removeChild(link);
+    }
+});
+
+// Clean up resources when leaving the page
+window.addEventListener('beforeunload', () => {
+    if (audioContext) {
+        audioContext.close();
+    }
+    if (ws) {
+        ws.close();
+    }
+    // Clean up any blob URLs
+    if (currentAudioPath) {
+        URL.revokeObjectURL(currentAudioPath);
+    }
+    // Clear any pending audio buffers
+    audioBuffers = [];
+    pendingAudioPaths.clear();
+});
+
+// Initialize WebSocket connection
+connectWebSocket();
+
+async function fetchWithRetry(url, maxRetries = 3, retryDelay = 1000) {
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            return response;
+        } catch (error) {
+            if (i === maxRetries - 1) throw error;
+            await new Promise(resolve => setTimeout(resolve, retryDelay));
+        }
+    }
+}

web_tool/recorder.js

@@ -0,0 +1,132 @@
+class AudioRecorder {
+    constructor() {
+        this.mediaRecorder = null;
+        this.audioChunks = [];
+        this.isRecording = false;
+        this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
+    }
+
+    async start() {
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({
+                audio: {
+                    channelCount: 1,
+                    sampleRate: 16000
+                }
+            });
+            this.mediaRecorder = new MediaRecorder(stream);
+            this.audioChunks = [];
+            this.isRecording = true;
+
+            this.mediaRecorder.addEventListener("dataavailable", (event) => {
+                this.audioChunks.push(event.data);
+            });
+
+            this.mediaRecorder.start();
+            return true;
+        } catch (error) {
+            console.error("Error starting recording:", error);
+            throw error;
+        }
+    }
+
+    async stop() {
+        return new Promise(async (resolve) => {
+            this.mediaRecorder.addEventListener("stop", async () => {
+                const audioBlob = new Blob(this.audioChunks, { type: 'audio/wav' });
+                this.isRecording = false;
+
+                // Convert to WAV with correct format
+                const arrayBuffer = await audioBlob.arrayBuffer();
+                const audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer);
+
+                // Create WAV file
+                const wavBuffer = await this.createWAV(audioBuffer);
+                const wavBlob = new Blob([wavBuffer], { type: 'audio/wav' });
+
+                resolve(wavBlob);
+            });
+
+            this.mediaRecorder.stop();
+            this.mediaRecorder.stream.getTracks().forEach(track => track.stop());
+        });
+    }
+
+    async createWAV(audioBuffer) {
+        const numChannels = 1; // Mono
+        const sampleRate = 16000; // Target sample rate
+        const format = 1; // PCM
+        const bitDepth = 16;
+
+        // Resample if needed
+        let samples = audioBuffer.getChannelData(0);
+        if (audioBuffer.sampleRate !== sampleRate) {
+            samples = await this.resampleAudio(samples, audioBuffer.sampleRate, sampleRate);
+        }
+
+        const dataLength = samples.length * (bitDepth / 8);
+        const headerLength = 44;
+        const totalLength = headerLength + dataLength;
+
+        const buffer = new ArrayBuffer(totalLength);
+        const view = new DataView(buffer);
+
+        // Write WAV header
+        this.writeString(view, 0, 'RIFF');
+        view.setUint32(4, totalLength - 8, true);
+        this.writeString(view, 8, 'WAVE');
+        this.writeString(view, 12, 'fmt ');
+        view.setUint32(16, 16, true);
+        view.setUint16(20, format, true);
+        view.setUint16(22, numChannels, true);
+        view.setUint32(24, sampleRate, true);
+        view.setUint32(28, sampleRate * numChannels * (bitDepth / 8), true);
+        view.setUint16(32, numChannels * (bitDepth / 8), true);
+        view.setUint16(34, bitDepth, true);
+        this.writeString(view, 36, 'data');
+        view.setUint32(40, dataLength, true);
+
+        // Write audio data
+        this.floatTo16BitPCM(view, 44, samples);
+
+        return buffer;
+    }
+
+    writeString(view, offset, string) {
+        for (let i = 0; i < string.length; i++) {
+            view.setUint8(offset + i, string.charCodeAt(i));
+        }
+    }
+
+    floatTo16BitPCM(view, offset, input) {
+        for (let i = 0; i < input.length; i++, offset += 2) {
+            const s = Math.max(-1, Math.min(1, input[i]));
+            view.setInt16(offset, s < 0 ? s * 0x8000 : s * 0x7FFF, true);
+        }
+    }
+
+    async resampleAudio(audioData, originalSampleRate, targetSampleRate) {
+        const originalLength = audioData.length;
+        const ratio = targetSampleRate / originalSampleRate;
+        const newLength = Math.round(originalLength * ratio);
+        const result = new Float32Array(newLength);
+
+        for (let i = 0; i < newLength; i++) {
+            const position = i / ratio;
+            const index = Math.floor(position);
+            const fraction = position - index;
+
+            if (index + 1 < originalLength) {
+                result[i] = audioData[index] * (1 - fraction) + audioData[index + 1] * fraction;
+            } else {
+                result[i] = audioData[index];
+            }
+        }
+
+        return result;
+    }
+
+    isActive() {
+        return this.isRecording;
+    }
+}