fix(tts): harden provider URL handling and local voice loading

Author: Kiritogu

backend/app/api/tts.py

@@ -454,23 +454,15 @@ def _resolve_tts_media_type(format_name: str) -> str:
 
 
 def _resolve_volcengine_tts_url(runtime_config, overrides: Dict[str, Any]) -> str:
-    explicit = _read_string(overrides, "volcengine_url", "volcengineUrl", "provider_url", "providerUrl")
-    if explicit:
-        return explicit
     base_url = str(runtime_config.base_url or "").strip().lower()
     if "openspeech.bytedance.com" in base_url:
         return runtime_config.base_url.rstrip("/")
     return VOLCENGINE_TTS_URL
 
 
 def _resolve_alibaba_tts_ws_url(runtime_config, overrides: Dict[str, Any]) -> str:
-    explicit = _read_string(overrides, "dashscope_ws_url", "dashscopeWsUrl", "ws_url", "wsUrl")
-    if explicit:
-        return explicit
-
-    explicit_base = _read_string(overrides, "base_url", "baseUrl", "dashscope_base_url", "dashscopeBaseUrl")
     runtime_base = str(runtime_config.base_url or "").strip()
-    normalized_base = (explicit_base or runtime_base).lower()
+    normalized_base = runtime_base.lower()
 
     region = _read_string(overrides, "region").lower()
     if region in {"intl", "sg", "singapore", "intl-singapore", "ap-southeast-1"}:

backend/app/services/providers/registry.py

@@ -1,5 +1,6 @@
 import os
 import json
+import logging
 from functools import lru_cache
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set
@@ -56,6 +57,8 @@
     "volcengine-speech": LOCAL_TTS_VOICES_DIR / "volcengine.json",
     "alibaba-cloud-model-studio-speech": LOCAL_TTS_VOICES_DIR / "alibaba.json",
 }
+_LAST_GOOD_LOCAL_TTS_VOICES: Dict[str, List[dict]] = {}
+logger = logging.getLogger(__name__)
 
 
 class ProviderRegistry:
@@ -190,19 +193,47 @@ async def _load_local_tts_voices(provider_id: str) -> List[dict]:
     path = LOCAL_TTS_VOICE_FILES.get(provider_id)
     if not path:
         return []
-    return _load_local_tts_voices_cached(provider_id, str(path))
 
-
-@lru_cache(maxsize=8)
-def _load_local_tts_voices_cached(provider_id: str, path: str) -> List[dict]:
     source = Path(path)
-    if not source.exists():
-        return []
-
     try:
-        raw = json.loads(source.read_text(encoding="utf-8"))
-    except Exception:
+        mtime_ns = source.stat().st_mtime_ns
+        voices = _load_local_tts_voices_cached(provider_id, str(source), mtime_ns)
+    except FileNotFoundError:
+        logger.warning("Local TTS voices file not found for provider=%s path=%s", provider_id, source)
+        return _load_last_good_local_tts_voices(provider_id)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        logger.exception(
+            "Failed to load local TTS voices for provider=%s path=%s",
+            provider_id,
+            source,
+            exc_info=exc,
+        )
+        return _load_last_good_local_tts_voices(provider_id)
+    except Exception as exc:
+        logger.exception(
+            "Unexpected error while loading local TTS voices for provider=%s path=%s",
+            provider_id,
+            source,
+            exc_info=exc,
+        )
+        return _load_last_good_local_tts_voices(provider_id)
+
+    _LAST_GOOD_LOCAL_TTS_VOICES[provider_id] = list(voices)
+    return list(voices)
+
+
+def _load_last_good_local_tts_voices(provider_id: str) -> List[dict]:
+    voices = _LAST_GOOD_LOCAL_TTS_VOICES.get(provider_id)
+    if not voices:
         return []
+    return list(voices)
+
+
+@lru_cache(maxsize=16)
+def _load_local_tts_voices_cached(provider_id: str, path: str, mtime_ns: int) -> List[dict]:
+    source = Path(path)
+    _ = mtime_ns
+    raw = json.loads(source.read_text(encoding="utf-8"))
 
     if provider_id == "alibaba-cloud-model-studio-speech":
         return _parse_alibaba_voices(raw)

backend/tests/test_provider_voices_tts.py

@@ -1,5 +1,6 @@
 import asyncio
 import sys
+import uuid
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parents[1]
@@ -104,7 +105,112 @@ def test_list_voices_unsupported_provider_returns_empty():
     assert result == []
 
 
+def _volcengine_voices_payload() -> str:
+    return """
+{
+  "status": "success",
+  "error": null,
+  "data": {
+    "resource_packs": [
+      {
+        "code": "zh_female_test",
+        "resource_display": "Test Voice",
+        "details": {
+          "language": "Chinese",
+          "voice_type": "zh_female_test",
+          "tone_number": "zh_female_test",
+          "recommended_scenario": "General"
+        }
+      }
+    ]
+  }
+}
+""".strip()
+
+
+def _make_local_temp_file() -> Path:
+    root = ROOT / "tests_tmp"
+    root.mkdir(parents=True, exist_ok=True)
+    path = root / f"tmp-{uuid.uuid4().hex}.json"
+    return path
+
+
+def test_load_local_tts_voices_recovers_after_transient_parse_error():
+    temp_path = _make_local_temp_file()
+    try:
+        temp_path.write_text("{ invalid json", encoding="utf-8")
+
+        original_map = provider_registry_module.LOCAL_TTS_VOICE_FILES
+        provider_registry_module.LOCAL_TTS_VOICE_FILES = {
+            **original_map,
+            "volcengine-speech": temp_path,
+        }
+        provider_registry_module._load_local_tts_voices_cached.cache_clear()
+        provider_registry_module._LAST_GOOD_LOCAL_TTS_VOICES.pop("volcengine-speech", None)
+        try:
+            broken = asyncio.run(
+                provider_registry_module._load_local_tts_voices("volcengine-speech")
+            )
+            assert broken == []
+
+            temp_path.write_text(_volcengine_voices_payload(), encoding="utf-8")
+            recovered = asyncio.run(
+                provider_registry_module._load_local_tts_voices("volcengine-speech")
+            )
+            assert len(recovered) == 1
+            assert recovered[0]["id"] == "zh_female_test"
+        finally:
+            provider_registry_module.LOCAL_TTS_VOICE_FILES = original_map
+            provider_registry_module._load_local_tts_voices_cached.cache_clear()
+            provider_registry_module._LAST_GOOD_LOCAL_TTS_VOICES.pop("volcengine-speech", None)
+    finally:
+        if temp_path.exists():
+            temp_path.unlink()
+
+
+def test_load_local_tts_voices_uses_last_good_on_parse_error():
+    temp_path = _make_local_temp_file()
+    try:
+        temp_path.write_text(_volcengine_voices_payload(), encoding="utf-8")
+
+        original_map = provider_registry_module.LOCAL_TTS_VOICE_FILES
+        provider_registry_module.LOCAL_TTS_VOICE_FILES = {
+            **original_map,
+            "volcengine-speech": temp_path,
+        }
+        provider_registry_module._load_local_tts_voices_cached.cache_clear()
+        provider_registry_module._LAST_GOOD_LOCAL_TTS_VOICES.pop("volcengine-speech", None)
+        try:
+            first = asyncio.run(
+                provider_registry_module._load_local_tts_voices("volcengine-speech")
+            )
+            assert len(first) == 1
+
+            temp_path.write_text("{ invalid json", encoding="utf-8")
+            provider_registry_module._load_local_tts_voices_cached.cache_clear()
+            fallback = asyncio.run(
+                provider_registry_module._load_local_tts_voices("volcengine-speech")
+            )
+            assert len(fallback) == 1
+            assert fallback[0]["id"] == "zh_female_test"
+        finally:
+            provider_registry_module.LOCAL_TTS_VOICE_FILES = original_map
+            provider_registry_module._load_local_tts_voices_cached.cache_clear()
+            provider_registry_module._LAST_GOOD_LOCAL_TTS_VOICES.pop("volcengine-speech", None)
+    finally:
+        if temp_path.exists():
+            temp_path.unlink()
+
+
 if __name__ == "__main__":
     run("list voices volcengine from local catalog", test_list_voices_volcengine_from_local_catalog)
     run("list voices alibaba filters by model", test_list_voices_alibaba_filters_by_model)
     run("list voices unsupported provider returns empty", test_list_voices_unsupported_provider_returns_empty)
+    run(
+        "load local tts voices recovers after transient parse error",
+        test_load_local_tts_voices_recovers_after_transient_parse_error,
+    )
+    run(
+        "load local tts voices uses last good on parse error",
+        test_load_local_tts_voices_uses_last_good_on_parse_error,
+    )

backend/tests/test_tts_engine_relay.py

@@ -12,6 +12,7 @@
     _extract_json_error_message,
     _extract_tts_input,
     _normalize_alibaba_provider_model,
+    _resolve_volcengine_tts_url,
     _resolve_alibaba_tts_ws_url,
     _resolve_tts_api_key,
 )
@@ -139,6 +140,22 @@ def test_build_volcengine_provider_payload_direct():
     assert payload["request"]["text"] == "hello volcengine direct"
 
 
+def test_resolve_volcengine_tts_url_ignores_client_url_override():
+    runtime = EngineRuntimeConfig(
+        id="volcengine-speech",
+        base_url="https://openspeech.bytedance.com/api/v1/tts",
+        model="v1",
+    )
+    url = _resolve_volcengine_tts_url(
+        runtime,
+        {
+            "volcengine_url": "https://attacker.example/tts",
+            "provider_url": "https://attacker-2.example/tts",
+        },
+    )
+    assert url == "https://openspeech.bytedance.com/api/v1/tts"
+
+
 def test_resolve_alibaba_tts_ws_url_prefers_intl_region():
     runtime = EngineRuntimeConfig(
         id="alibaba-cloud-model-studio-speech",
@@ -149,6 +166,23 @@ def test_resolve_alibaba_tts_ws_url_prefers_intl_region():
     assert ws_url == "wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference"
 
 
+def test_resolve_alibaba_tts_ws_url_ignores_client_url_override():
+    runtime = EngineRuntimeConfig(
+        id="alibaba-cloud-model-studio-speech",
+        base_url="https://dashscope.aliyuncs.com",
+        model="cosyvoice-v1",
+    )
+    ws_url = _resolve_alibaba_tts_ws_url(
+        runtime,
+        {
+            "ws_url": "wss://attacker.example/ws",
+            "dashscope_ws_url": "wss://attacker-2.example/ws",
+            "baseUrl": "https://dashscope-intl.aliyuncs.com",
+        },
+    )
+    assert ws_url == "wss://dashscope.aliyuncs.com/api-ws/v1/inference"
+
+
 def test_normalize_alibaba_provider_model_strips_provider_prefix():
     assert _normalize_alibaba_provider_model("alibaba/cosyvoice-v1") == "cosyvoice-v1"
     assert _normalize_alibaba_provider_model("cosyvoice-v1") == "cosyvoice-v1"
@@ -182,7 +216,15 @@ def test_decorate_tts_error_for_volcengine_grant_issue():
     run("build unspeech payload for volcengine", test_build_unspeech_payload_for_volcengine)
     run("build unspeech payload for alibaba", test_build_unspeech_payload_for_alibaba)
     run("build volcengine provider payload direct", test_build_volcengine_provider_payload_direct)
+    run(
+        "resolve volcengine tts url ignores client url override",
+        test_resolve_volcengine_tts_url_ignores_client_url_override,
+    )
     run("resolve alibaba tts ws url prefers intl region", test_resolve_alibaba_tts_ws_url_prefers_intl_region)
+    run(
+        "resolve alibaba tts ws url ignores client url override",
+        test_resolve_alibaba_tts_ws_url_ignores_client_url_override,
+    )
     run("normalize alibaba provider model strips provider prefix", test_normalize_alibaba_provider_model_strips_provider_prefix)
     run("extract json error message from errors array", test_extract_json_error_message_from_errors_array)
     run("decorate tts error for volcengine grant issue", test_decorate_tts_error_for_volcengine_grant_issue)

frontend/packages/app-core/src/services/audio-direct.test.ts

@@ -80,7 +80,7 @@ run("builds backend relay request for alibaba speech engine", () => {
   });
 });
 
-run("normalizes legacy unspeech base url to provider official endpoint", () => {
+run("does not forward base url for fixed direct providers", () => {
   const volcRequest = buildDirectTtsHttpRequest({
     text: "hello",
     engineId: "volcengine-speech",
@@ -94,10 +94,7 @@ run("normalizes legacy unspeech base url to provider official endpoint", () => {
     },
   });
   assert.ok(volcRequest);
-  assert.equal(
-    (volcRequest?.body.config as { baseUrl?: string }).baseUrl,
-    "https://openspeech.bytedance.com/api/v1/tts"
-  );
+  assert.equal((volcRequest?.body.config as { baseUrl?: string }).baseUrl, undefined);
 
   const alibabaRequest = buildDirectTtsHttpRequest({
     text: "hello",
@@ -111,10 +108,7 @@ run("normalizes legacy unspeech base url to provider official endpoint", () => {
     },
   });
   assert.ok(alibabaRequest);
-  assert.equal(
-    (alibabaRequest?.body.config as { baseUrl?: string }).baseUrl,
-    "https://dashscope.aliyuncs.com"
-  );
+  assert.equal((alibabaRequest?.body.config as { baseUrl?: string }).baseUrl, undefined);
 });
 
 run("builds legacy synthesize fallback request from backend relay request", () => {
@@ -142,8 +136,6 @@ run("builds legacy synthesize fallback request from backend relay request", () =
     config: {
       apiKey: "token-123",
       api_key: "token-123",
-      baseUrl: "https://unspeech.example/v1",
-      base_url: "https://unspeech.example/v1",
       model: "volcengine/v1",
       voice: "zh_female_test",
       appId: "appid-xyz",

frontend/packages/app-core/src/utils/tts-direct-request.ts

@@ -30,7 +30,6 @@ const allowedBackendTtsEngineIds = new Set([
   "volcengine-speech",
   "alibaba-cloud-model-studio-speech",
 ]);
-const legacyUnspeechHost = "unspeech.hyp3r.link";
 
 function asRecord(value: unknown): Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
@@ -74,28 +73,6 @@ function normalizeAlibabaModelId(model: string, engineId: string) {
   return model.replace(/^alibaba\//i, "").trim();
 }
 
-function normalizeLegacyUnspeechBaseUrl(engineId: string, baseUrl: string) {
-  const normalized = baseUrl.trim();
-  if (!normalized) return normalized;
-
-  try {
-    const parsed = new URL(normalized);
-    if (parsed.hostname.toLowerCase() !== legacyUnspeechHost) {
-      return normalized;
-    }
-  } catch {
-    return normalized;
-  }
-
-  if (engineId === "volcengine-speech") {
-    return "https://openspeech.bytedance.com/api/v1/tts";
-  }
-  if (engineId === "alibaba-cloud-model-studio-speech") {
-    return "https://dashscope.aliyuncs.com";
-  }
-  return normalized;
-}
-
 function resolveVolcengineAppId(config: Record<string, unknown>) {
   const topLevel = readString(config, ["appId", "appid", "app_id"]);
   if (topLevel) return topLevel;
@@ -132,10 +109,6 @@ export function buildDirectTtsHttpRequest(input: {
   const config = asRecord(input.config);
   const apiBaseUrl = (input.apiBaseUrl || "").trim();
   const apiKey = readString(config, ["apiKey", "api_key"]);
-  const baseUrl = normalizeLegacyUnspeechBaseUrl(
-    engineId,
-    readString(config, ["baseUrl", "base_url"])
-  );
   const model = normalizeAlibabaModelId(readString(config, ["model"]), engineId);
   const voice = readString(config, ["voice"]);
   const text = (input.text || "").trim();
@@ -150,10 +123,6 @@ export function buildDirectTtsHttpRequest(input: {
     voice,
   };
 
-  if (baseUrl) {
-    backendConfig.baseUrl = baseUrl;
-  }
-
   const responseFormat = readString(config, ["response_format", "responseFormat", "format"]);
   if (responseFormat) {
     backendConfig.response_format = responseFormat;