Fix model download reliability and silent import failures

Extract ensure_pretrained_models() into ensure_models.py and call it
from webui.py before AppState init, so models are downloaded regardless
of entry point. Narrow except clauses in preprocess/tools/__init__.py
from Exception to ImportError so real errors propagate instead of
silently setting classes to None.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app.py

@@ -3,55 +3,15 @@ Hugging Face Space entry point for SoulX-Singer.
 Downloads pretrained models from the Hub if needed, then launches the Gradio app.
 """
 import os
-import sys
 from pathlib import Path
 
 # Set matplotlib backend before any imports that might use it (required for headless environments)
 import matplotlib
 matplotlib.use('Agg')  # Use non-interactive backend
 
-ROOT = Path(__file__).resolve().parent
-PRETRAINED_DIR = ROOT / "pretrained_models"
-MODEL_DIR_SVS = PRETRAINED_DIR / "SoulX-Singer"
-MODEL_DIR_PREPROCESS = PRETRAINED_DIR / "SoulX-Singer-Preprocess"
-
-
-def ensure_pretrained_models():
-    """Download SoulX-Singer and Preprocess models from Hugging Face Hub if not present."""
-    if (MODEL_DIR_SVS / "model.pt").exists() and MODEL_DIR_PREPROCESS.exists():
-        print("Pretrained models already present, skipping download.", flush=True)
-        return
-
-    try:
-        from huggingface_hub import snapshot_download
-    except ImportError:
-        print(
-            "huggingface_hub not installed. Install with: pip install huggingface_hub",
-            file=sys.stderr,
-            flush=True,
-        )
-        raise
-
-    PRETRAINED_DIR.mkdir(parents=True, exist_ok=True)
-
-    if not (MODEL_DIR_SVS / "model.pt").exists():
-        print("Downloading SoulX-Singer model...", flush=True)
-        snapshot_download(
-            repo_id="Soul-AILab/SoulX-Singer",
-            local_dir=str(MODEL_DIR_SVS),
-            local_dir_use_symlinks=False,
-        )
-        print("SoulX-Singer model ready.", flush=True)
-
-    if not MODEL_DIR_PREPROCESS.exists():
-        print("Downloading SoulX-Singer-Preprocess models...", flush=True)
-        snapshot_download(
-            repo_id="Soul-AILab/SoulX-Singer-Preprocess",
-            local_dir=str(MODEL_DIR_PREPROCESS),
-            local_dir_use_symlinks=False,
-        )
-        print("SoulX-Singer-Preprocess models ready.", flush=True)
+from ensure_models import ensure_pretrained_models
 
+ROOT = Path(__file__).resolve().parent
 
 if __name__ == "__main__":
     os.chdir(ROOT)

ensure_models.py

@@ -0,0 +1,45 @@
+"""Download pretrained models from Hugging Face Hub if not already present."""
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+PRETRAINED_DIR = ROOT / "pretrained_models"
+MODEL_DIR_SVS = PRETRAINED_DIR / "SoulX-Singer"
+MODEL_DIR_PREPROCESS = PRETRAINED_DIR / "SoulX-Singer-Preprocess"
+
+
+def ensure_pretrained_models():
+    """Download SoulX-Singer and Preprocess models from Hugging Face Hub if not present."""
+    if (MODEL_DIR_SVS / "model.pt").exists() and MODEL_DIR_PREPROCESS.exists():
+        print("Pretrained models already present, skipping download.", flush=True)
+        return
+
+    try:
+        from huggingface_hub import snapshot_download
+    except ImportError:
+        print(
+            "huggingface_hub not installed. Install with: pip install huggingface_hub",
+            file=sys.stderr,
+            flush=True,
+        )
+        raise
+
+    PRETRAINED_DIR.mkdir(parents=True, exist_ok=True)
+
+    if not (MODEL_DIR_SVS / "model.pt").exists():
+        print("Downloading SoulX-Singer model...", flush=True)
+        snapshot_download(
+            repo_id="Soul-AILab/SoulX-Singer",
+            local_dir=str(MODEL_DIR_SVS),
+            local_dir_use_symlinks=False,
+        )
+        print("SoulX-Singer model ready.", flush=True)
+
+    if not MODEL_DIR_PREPROCESS.exists():
+        print("Downloading SoulX-Singer-Preprocess models...", flush=True)
+        snapshot_download(
+            repo_id="Soul-AILab/SoulX-Singer-Preprocess",
+            local_dir=str(MODEL_DIR_PREPROCESS),
+            local_dir_use_symlinks=False,
+        )
+        print("SoulX-Singer-Preprocess models ready.", flush=True)

preprocess/tools/__init__.py

@@ -28,16 +28,16 @@ from .vocal_detection import VocalDetector
 # Keep the public surface stable while avoiding hard import failures.
 try:
     from .vocal_separation.model import VocalSeparator  # type: ignore
-except Exception:  # pragma: no cover
+except ImportError:  # pragma: no cover
     VocalSeparator = None  # type: ignore
 
 try:
     from .note_transcription.model import NoteTranscriber  # type: ignore
-except Exception:  # pragma: no cover
+except ImportError:  # pragma: no cover
     NoteTranscriber = None  # type: ignore
 try:
     from .lyric_transcription import LyricTranscriber
-except Exception:  # pragma: no cover
+except ImportError:  # pragma: no cover
     LyricTranscriber = None  # type: ignore
 
 __all__ = [

webui.py

@@ -269,6 +269,9 @@ class AppState:
         return True, "svs inference done", merged
 
 
+from ensure_models import ensure_pretrained_models
+ensure_pretrained_models()
+
 APP_STATE = AppState()