Enhance reference audio management and model configuration validation

- Introduced a new `reference_audio_storage_root` function to manage storage paths for reference audio files, improving organization and accessibility.
- Updated audio model configuration functions to utilize the new reference audio management, ensuring proper handling of voice references and paths.
- Enhanced validation logic for audio model configurations, including coercion of numeric strings for `device` and `threads` parameters.
- Improved tests to cover new functionalities related to reference audio and validation scenarios, ensuring robust integration with existing workflows.

Author: lapy

backend/audio_cpp_runtime.py

@@ -15,6 +15,7 @@
     normalize_default_voice_preset,
     normalize_voice_presets,
 )
+from backend.reference_audio import reference_audio_storage_root
 from backend.runtime_env import audio_cpp_library_dirs, build_swap_process_env
 
 
@@ -198,15 +199,21 @@ def build_audio_cpp_runtime(
             model_row[key] = config[key]
     if "model_lazy" in config:
         model_row["lazy"] = bool(config["model_lazy"])
+    reference_root = reference_audio_storage_root(
+        model_path,
+        storage_key=model.get("id"),
+    )
     presets = normalize_voice_presets(
         config.get("voice_presets"),
         model_root=model_path,
+        reference_root=reference_root,
     )
     if presets:
         model_row["voice_presets"] = presets
     default_preset = normalize_default_voice_preset(
         config.get("default_voice_preset"),
         model_root=model_path,
+        reference_root=reference_root,
         voice_presets=presets,
     )
     if default_preset is not None:
@@ -240,4 +247,3 @@ def build_audio_cpp_runtime(
         "use_model_name": stable_id,
         "generic_task_path": f"/upstream/{stable_id}/v1/tasks/run",
     }
-

backend/audio_model_config.py

@@ -19,9 +19,29 @@
     validate_speech_default_references,
     validate_voice_presets,
 )
+from backend.reference_audio import reference_audio_storage_root
 from backend.model_config import effective_model_config
 
 
+_AUDIO_DOCUMENTATION_CONFIG_KEYS = frozenset({"key=value"})
+
+
+def _is_bogus_audio_config_key(key: Any) -> bool:
+    name = str(key or "")
+    return not name or name in _AUDIO_DOCUMENTATION_CONFIG_KEYS or "=" in name
+
+
+def sanitize_audio_engine_section(section: dict) -> dict:
+    """Remove parser/documentation artifacts from a stored audio.cpp engine section."""
+    if not isinstance(section, dict):
+        return {}
+    cleaned = dict(section)
+    for key in list(cleaned):
+        if _is_bogus_audio_config_key(key):
+            cleaned.pop(key, None)
+    return cleaned
+
+
 _RESERVED_AUDIO_FLAGS = {
     "--config",
     "--host",
@@ -158,11 +178,29 @@ def _validate_custom_args(value: Any, errors: List[str]) -> None:
             errors.append(f"{flag} is Studio-owned and cannot be set in custom_args")
 
 
+def _coerce_nonneg_int(value: Any) -> Any:
+    if isinstance(value, int) and not isinstance(value, bool):
+        return value
+    if isinstance(value, float) and not isinstance(value, bool):
+        return int(value)
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped.isdigit() or (
+            stripped.startswith("-") and stripped[1:].isdigit()
+        ):
+            return int(stripped)
+    return value
+
+
 def _validate_core_runtime_options(config: dict, errors: List[str]) -> None:
     for key, minimum in (("device", 0), ("threads", 1)):
         value = config.get(key)
         if not _present(value):
             continue
+        coerced = _coerce_nonneg_int(value)
+        if coerced is not value:
+            config[key] = coerced
+            value = coerced
         if not isinstance(value, int) or isinstance(value, bool):
             errors.append(f"{key} must be int")
             continue
@@ -188,6 +226,10 @@ def validate_audio_model_config(
     Raises ``ValueError`` with all user-actionable validation failures.
     """
 
+    engines = normalized_config.get("engines")
+    if isinstance(engines, dict) and isinstance(engines.get("audio_cpp"), dict):
+        engines["audio_cpp"] = sanitize_audio_engine_section(engines["audio_cpp"])
+
     effective = effective_model_config(normalized_config)
     if effective.get("engine") != "audio_cpp":
         return {"errors": [], "warnings": []}
@@ -301,6 +343,15 @@ def validate_audio_model_config(
         )
 
     _validate_core_runtime_options(effective, errors)
+    audio_section = (
+        normalized_config.get("engines", {}).get("audio_cpp")
+        if isinstance(normalized_config.get("engines"), dict)
+        else None
+    )
+    if isinstance(audio_section, dict):
+        for key in ("device", "threads"):
+            if key in effective:
+                audio_section[key] = effective[key]
 
     request_options = effective.get("request_options")
     if isinstance(request_options, dict) and request_options:
@@ -314,15 +365,18 @@ def validate_audio_model_config(
         or model.get("model_path")
         or ""
     )
+    reference_root = reference_audio_storage_root(model_root, storage_key=model.get("id"))
     if is_tts_task(task):
         validate_voice_presets(
             effective,
             model_root=model_root,
+            reference_root=reference_root,
             errors=errors,
         )
         validate_speech_default_references(
             effective,
             model_root=model_root,
+            reference_root=reference_root,
             errors=errors,
         )
         if effective.get("speech_defaults") is not None and not isinstance(

backend/audio_voice_presets.py

@@ -16,54 +16,94 @@ def _clean_text(value: Any) -> Optional[str]:
     return text or None
 
 
-def _resolve_voice_ref(model_root: str, value: Any) -> Optional[str]:
+def _reference_roots(model_root: str, reference_root: Optional[str] = None) -> list[str]:
+    roots: list[str] = []
+    for root in (reference_root, model_root):
+        text = _clean_text(root)
+        if text:
+            resolved = os.path.abspath(text)
+            if resolved not in roots:
+                roots.append(resolved)
+    return roots
+
+
+def _resolve_voice_ref(
+    model_root: str,
+    value: Any,
+    *,
+    reference_root: Optional[str] = None,
+) -> Optional[str]:
     raw = _clean_text(value)
     if not raw:
         return None
     if os.path.isabs(raw):
         return raw
-    root = os.path.abspath(model_root)
+    roots = _reference_roots(model_root, reference_root)
+    for root in roots:
+        candidate = os.path.abspath(os.path.join(root, raw))
+        if os.path.exists(candidate):
+            return candidate
+    root = roots[0] if roots else os.path.abspath(model_root)
     return os.path.abspath(os.path.join(root, raw))
 
 
-def _relative_voice_ref_escapes(model_root: str, value: Any) -> bool:
+def _relative_voice_ref_escapes(
+    model_root: str,
+    value: Any,
+    *,
+    reference_root: Optional[str] = None,
+) -> bool:
     raw = _clean_text(value)
     if not raw or os.path.isabs(raw):
         return False
-    root = os.path.realpath(model_root)
-    target = os.path.realpath(os.path.join(root, raw))
-    try:
-        return os.path.commonpath([root, target]) != root
-    except ValueError:
-        return True
+    escaped_all_roots = True
+    for root in _reference_roots(model_root, reference_root):
+        root_real = os.path.realpath(root)
+        target = os.path.realpath(os.path.join(root_real, raw))
+        try:
+            if os.path.commonpath([root_real, target]) == root_real:
+                escaped_all_roots = False
+        except ValueError:
+            continue
+    return escaped_all_roots
 
 
 def _validate_voice_ref_path(
     *,
     label: str,
     value: Any,
     model_root: str,
+    reference_root: Optional[str] = None,
     errors: list[str],
 ) -> None:
     raw = _clean_text(value)
     if not raw:
         return
-    if _relative_voice_ref_escapes(model_root, raw):
+    if _relative_voice_ref_escapes(model_root, raw, reference_root=reference_root):
         errors.append(f"{label} escapes model bundle: {raw}")
         return
-    resolved = _resolve_voice_ref(model_root, raw)
+    resolved = _resolve_voice_ref(model_root, raw, reference_root=reference_root)
     if not resolved or not os.path.exists(resolved):
         errors.append(f"{label} does not exist: {resolved or raw}")
 
 
-def normalize_voice_preset(preset: Any, *, model_root: str) -> Optional[Dict[str, str]]:
+def normalize_voice_preset(
+    preset: Any,
+    *,
+    model_root: str,
+    reference_root: Optional[str] = None,
+) -> Optional[Dict[str, str]]:
     if not isinstance(preset, dict):
         return None
     out: Dict[str, str] = {}
     voice_id = _clean_text(preset.get("voice_id"))
     if voice_id:
         out["voice_id"] = voice_id
-    voice_ref = _resolve_voice_ref(model_root, preset.get("voice_ref"))
+    voice_ref = _resolve_voice_ref(
+        model_root,
+        preset.get("voice_ref"),
+        reference_root=reference_root,
+    )
     if voice_ref:
         out["voice_ref"] = voice_ref
     reference_text = _clean_text(preset.get("reference_text"))
@@ -76,6 +116,7 @@ def normalize_voice_presets(
     presets: Any,
     *,
     model_root: str,
+    reference_root: Optional[str] = None,
 ) -> Dict[str, Dict[str, str]]:
     if not isinstance(presets, dict):
         return {}
@@ -84,7 +125,11 @@ def normalize_voice_presets(
         name = str(raw_name or "").strip()
         if not name:
             continue
-        normalized = normalize_voice_preset(raw_preset, model_root=model_root)
+        normalized = normalize_voice_preset(
+            raw_preset,
+            model_root=model_root,
+            reference_root=reference_root,
+        )
         if normalized:
             out[name] = normalized
     return out
@@ -94,6 +139,7 @@ def normalize_default_voice_preset(
     value: Any,
     *,
     model_root: str,
+    reference_root: Optional[str] = None,
     voice_presets: Optional[Dict[str, Dict[str, str]]] = None,
 ) -> Any:
     if value is None or value == "":
@@ -102,7 +148,11 @@ def normalize_default_voice_preset(
         name = value.strip()
         return name or None
     if isinstance(value, dict):
-        normalized = normalize_voice_preset(value, model_root=model_root)
+        normalized = normalize_voice_preset(
+            value,
+            model_root=model_root,
+            reference_root=reference_root,
+        )
         return normalized
     return None
 
@@ -173,7 +223,30 @@ def _task_normalized_to_swap_params(normalized: Dict[str, Any]) -> Dict[str, Any
     return params
 
 
-def audio_request_defaults_to_swap_set_params(config: dict) -> Dict[str, Any]:
+def _resolve_normalized_reference_fields(
+    normalized: Dict[str, Any],
+    *,
+    model_root: Optional[str] = None,
+    reference_root: Optional[str] = None,
+) -> Dict[str, Any]:
+    if not model_root or "voice_ref" not in normalized:
+        return normalized
+    resolved = _resolve_voice_ref(
+        model_root,
+        normalized.get("voice_ref"),
+        reference_root=reference_root,
+    )
+    if not resolved:
+        return normalized
+    return {**normalized, "voice_ref": resolved}
+
+
+def audio_request_defaults_to_swap_set_params(
+    config: dict,
+    *,
+    model_root: Optional[str] = None,
+    reference_root: Optional[str] = None,
+) -> Dict[str, Any]:
     """
     Map Studio request defaults to llama-swap ``filters.setParams`` for audio.cpp.
 
@@ -186,6 +259,11 @@ def audio_request_defaults_to_swap_set_params(config: dict) -> Dict[str, Any]:
 
     defaults_key = request_defaults_key_for(config.get("task"), config.get("family"))
     normalized = normalize_request_defaults(defaults_key, config.get(defaults_key))
+    normalized = _resolve_normalized_reference_fields(
+        normalized,
+        model_root=model_root,
+        reference_root=reference_root,
+    )
     if not normalized:
         return {}
     if defaults_key == "speech_defaults":
@@ -254,16 +332,25 @@ def validate_voice_presets(
     config: dict,
     *,
     model_root: str,
+    reference_root: Optional[str] = None,
     errors: list[str],
 ) -> Dict[str, Dict[str, str]]:
-    presets = normalize_voice_presets(config.get("voice_presets"), model_root=model_root)
+    presets = normalize_voice_presets(
+        config.get("voice_presets"),
+        model_root=model_root,
+        reference_root=reference_root,
+    )
     default_value = config.get("default_voice_preset")
     if isinstance(default_value, str):
         name = default_value.strip()
         if name and name not in presets:
             errors.append(f"default_voice_preset '{name}' is not defined in voice_presets")
     elif isinstance(default_value, dict):
-        if not normalize_voice_preset(default_value, model_root=model_root):
+        if not normalize_voice_preset(
+            default_value,
+            model_root=model_root,
+            reference_root=reference_root,
+        ):
             errors.append(
                 "default_voice_preset must include voice_id, voice_ref, or reference_text"
             )
@@ -273,6 +360,7 @@ def validate_voice_presets(
                 label=f"default_voice_preset {path_key}",
                 value=raw,
                 model_root=model_root,
+                reference_root=reference_root,
                 errors=errors,
             )
     raw_presets = config.get("voice_presets")
@@ -288,6 +376,7 @@ def validate_voice_presets(
             label=f"voice_presets.{name}.voice_ref",
             value=raw_voice_ref,
             model_root=model_root,
+            reference_root=reference_root,
             errors=errors,
         )
     return presets
@@ -297,6 +386,7 @@ def validate_speech_default_references(
     config: dict,
     *,
     model_root: str,
+    reference_root: Optional[str] = None,
     errors: list[str],
 ) -> None:
     defaults = config.get("speech_defaults")
@@ -306,5 +396,6 @@ def validate_speech_default_references(
         label="speech_defaults.voice_ref",
         value=defaults.get("voice_ref"),
         model_root=model_root,
+        reference_root=reference_root,
         errors=errors,
     )