refactor(webui): replace direct VOICES_INTERNAL/DEFAULT_SUPERTONIC_VOICES with get_metadata API

- Add get_default_voice() helper to tts_backend_registry
- Replace all VOICES_INTERNAL imports in WebUI with get_metadata().voices
- Replace all DEFAULT_SUPERTONIC_VOICES imports in conversion_runner with get_metadata().voices
- Remove unused VOICES_INTERNAL import from voices.py

Core modules (voice_profiles, voice_formulas, voice_cache) already used
get_metadata(). This completes the WebUI migration.

.github/workflows/test_pip.yml

@@ -2,6 +2,7 @@ name: pip install
 run-name: pip install
 on:
   push:
+    branches: [main]
     paths:
       - '**.py'
       - 'pyproject.toml'
@@ -15,18 +16,18 @@ jobs:
   install-and-run:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, macos-14, windows-latest]
         python-version: ['3.12']
       fail-fast: false
-    continue-on-error: true
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
       - name: Install from repository
         run: python -m pip install .
       #- name: Run abogen

.github/workflows/test_publish.yml

@@ -18,7 +18,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
 
     - name: Login to Github Container Registry
       # Only if we need to push an image

abogen/tts_backend.py

@@ -18,11 +18,13 @@ class TTSBackendMetadata:
         id: Unique backend identifier (e.g. ``"kokoro"``, ``"supertonic"``).
         name: Human-readable display name.
         description: Short description of the backend.
+        voices: Tuple of supported voice identifiers.
     """
 
     id: str
     name: str
     description: str
+    voices: tuple[str, ...] = ()
 
 
 class TTSBackend(Protocol):

abogen/tts_backend_registry.py

@@ -66,6 +66,25 @@ def register_backend(
     _registry.register(metadata, factory)
 
 
+def get_metadata(backend_id: str) -> TTSBackendMetadata:
+    """Get metadata for a specific backend by id.
+
+    Ensures all backends are registered by importing the tts_backends
+    package on first access.
+
+    Raises:
+        KeyError: If backend with given id is not registered.
+    """
+    import abogen.tts_backends  # noqa: F401  — triggers backend registration
+    return _registry.get_metadata(backend_id)
+
+
+def get_default_voice(backend_id: str, fallback: str = "") -> str:
+    """Return the first voice of a backend, or *fallback* if none."""
+    voices = get_metadata(backend_id).voices
+    return voices[0] if voices else fallback
+
+
 def create_backend(backend_id: str, **kwargs: Any) -> TTSBackend:
     """Create a TTS backend instance by provider id."""
     return _registry.create_backend(backend_id, **kwargs)

abogen/tts_backends/kokoro.py

@@ -10,6 +10,16 @@ from typing import Any, Dict, Iterator, List, Optional
 
 import numpy as np
 
+from abogen.constants import VOICES_INTERNAL
+from abogen.tts_backend import TTSBackendMetadata
+
+_KOKORO_METADATA = TTSBackendMetadata(
+    id="kokoro",
+    name="Kokoro",
+    description="Kokoro TTS engine",
+    voices=tuple(VOICES_INTERNAL),
+)
+
 
 def _load_kpipeline():
     """Lazy-load Kokoro dependencies."""
@@ -39,14 +49,8 @@ class KokoroBackend:
         self._lang_code = lang_code
 
     @property
-    def metadata(self):
-        from abogen.tts_backend import TTSBackendMetadata
-
-        return TTSBackendMetadata(
-            id="kokoro",
-            name="Kokoro",
-            description="Kokoro TTS engine",
-        )
+    def metadata(self) -> TTSBackendMetadata:
+        return _KOKORO_METADATA
 
     def __call__(
         self,
@@ -89,9 +93,7 @@ class KokoroBackend:
 
     def get_available_voices(self) -> List[str]:
         """Return known Kokoro voice identifiers."""
-        from abogen.constants import VOICES_INTERNAL
-
-        return list(VOICES_INTERNAL)
+        return list(self.metadata.voices)
 
     def get_supported_formats(self) -> List[str]:
         """Kokoro outputs raw PCM float32 audio."""
@@ -111,14 +113,9 @@ def create_kokoro_backend(**kwargs: Any) -> KokoroBackend:
 
 
 # --- Registration ---
-from abogen.tts_backend import TTSBackendMetadata  # noqa: E402
 from abogen.tts_backend_registry import register_backend  # noqa: E402
 
 register_backend(
-    metadata=TTSBackendMetadata(
-        id="kokoro",
-        name="Kokoro",
-        description="Kokoro TTS engine",
-    ),
+    metadata=_KOKORO_METADATA,
     factory=create_kokoro_backend,
 )

abogen/tts_backends/supertonic.py

@@ -15,6 +15,15 @@ logger = logging.getLogger(__name__)
 
 DEFAULT_SUPERTONIC_VOICES = ("M1", "M2", "M3", "M4", "M5", "F1", "F2", "F3", "F4", "F5")
 
+from abogen.tts_backend import TTSBackendMetadata
+
+_SUPERTONIC_METADATA = TTSBackendMetadata(
+    id="supertonic",
+    name="SuperTonic",
+    description="SuperTonic TTS engine",
+    voices=DEFAULT_SUPERTONIC_VOICES,
+)
+
 
 @dataclass
 class SupertonicSegment:
@@ -282,12 +291,8 @@ class SupertonicBackend:
     """
 
     @property
-    def metadata(self) -> "TTSBackendMetadata":
-        return TTSBackendMetadata(
-            id="supertonic",
-            name="SuperTonic",
-            description="SuperTonic TTS engine",
-        )
+    def metadata(self) -> TTSBackendMetadata:
+        return _SUPERTONIC_METADATA
 
     def __init__(self, **kwargs: Any) -> None:
         self._pipeline = SupertonicPipeline(
@@ -333,7 +338,7 @@ class SupertonicBackend:
 
     def get_available_voices(self) -> List[str]:
         """Return the list of built-in SuperTonic voice identifiers."""
-        return list(DEFAULT_SUPERTONIC_VOICES)
+        return list(self.metadata.voices)
 
     def get_supported_formats(self) -> List[str]:
         return ["wav"]
@@ -379,14 +384,9 @@ def create_supertonic_backend(**kwargs: Any) -> SupertonicBackend:
     return SupertonicBackend(**kwargs)
 
 
-from abogen.tts_backend import TTSBackendMetadata
-from abogen.tts_backend_registry import register_backend
+from abogen.tts_backend_registry import register_backend  # noqa: E402
 
 register_backend(
-    metadata=TTSBackendMetadata(
-        id="supertonic",
-        name="SuperTonic",
-        description="SuperTonic TTS engine",
-    ),
+    metadata=_SUPERTONIC_METADATA,
     factory=create_supertonic_backend,
 )

abogen/voice_cache.py

@@ -17,7 +17,7 @@ if LocalEntryNotFoundError is None:  # pragma: no cover - fallback for tests
         pass
 
 
-from abogen.constants import VOICES_INTERNAL
+from abogen.tts_backend_registry import get_metadata
 
 _CACHE_LOCK = threading.Lock()
 _CACHED_VOICES: Set[str] = set()
@@ -26,8 +26,9 @@ _BOOTSTRAPPED = False
 
 
 def _normalize_targets(voices: Optional[Iterable[str]]) -> Set[str]:
+    kokoro_voices = get_metadata("kokoro").voices
     if not voices:
-        return set(VOICES_INTERNAL)
+        return set(kokoro_voices)
     normalized: Set[str] = set()
     for voice in voices:
         if not voice:
@@ -35,7 +36,7 @@ def _normalize_targets(voices: Optional[Iterable[str]]) -> Set[str]:
         voice_id = str(voice).strip()
         if not voice_id:
             continue
-        if voice_id in VOICES_INTERNAL:
+        if voice_id in kokoro_voices:
             normalized.add(voice_id)
     return normalized
 

abogen/voice_formulas.py

@@ -1,7 +1,7 @@
 import re
 from typing import List, Tuple
 
-from abogen.constants import VOICES_INTERNAL
+from abogen.tts_backend_registry import get_metadata
 
 
 # Calls parsing and loads the voice to gpu or cpu
@@ -22,6 +22,7 @@ def parse_formula_terms(formula: str) -> List[Tuple[str, float]]:
         raise ValueError("Empty voice formula")
 
     terms: List[Tuple[str, float]] = []
+    kokoro_voices = get_metadata("kokoro").voices
     for segment in formula.split("+"):
         part = segment.strip()
         if not part:
@@ -30,7 +31,7 @@ def parse_formula_terms(formula: str) -> List[Tuple[str, float]]:
             raise ValueError("Each component must be in the form voice*weight")
         voice_name, raw_weight = part.split("*", 1)
         voice_name = voice_name.strip()
-        if voice_name not in VOICES_INTERNAL:
+        if voice_name not in kokoro_voices:
             raise ValueError(f"Unknown voice: {voice_name}")
         try:
             weight = float(raw_weight.strip())

abogen/voice_profiles.py

@@ -2,8 +2,7 @@ import json
 import os
 from typing import Any, Dict, Iterable, List, Tuple
 
-from abogen.constants import VOICES_INTERNAL
-from abogen.tts_backends.supertonic import DEFAULT_SUPERTONIC_VOICES
+from abogen.tts_backend_registry import get_metadata
 from abogen.utils import get_user_config_path
 
 
@@ -70,7 +69,8 @@ def serialize_profiles() -> Dict[str, Dict[str, Iterable[Tuple[str, float]]]]:
 
 def _normalize_supertonic_voice(value: Any) -> str:
     raw = str(value or "").strip().upper()
-    return raw if raw in DEFAULT_SUPERTONIC_VOICES else "M1"
+    supertonic_voices = get_metadata("supertonic").voices
+    return raw if raw in supertonic_voices else "M1"
 
 
 def _coerce_supertonic_steps(value: Any) -> int:
@@ -135,6 +135,7 @@ def normalize_profile_entry(entry: Any) -> Dict[str, Any]:
 
 def _normalize_voice_entries(entries: Iterable) -> List[Tuple[str, float]]:
     normalized: List[Tuple[str, float]] = []
+    kokoro_voices = get_metadata("kokoro").voices
     for item in entries or []:
         if isinstance(item, dict):
             voice = item.get("id") or item.get("voice")
@@ -143,7 +144,7 @@ def _normalize_voice_entries(entries: Iterable) -> List[Tuple[str, float]]:
             voice, weight = item[0], item[1]
         else:
             continue
-        if voice not in VOICES_INTERNAL:
+        if voice not in kokoro_voices:
             continue
         if weight is None:
             continue

abogen/webui/Dockerfile

@@ -27,8 +27,6 @@ RUN python3 -m venv "$VIRTUAL_ENV"
 WORKDIR /app
 
 COPY pyproject.toml README.md ./
-COPY abogen ./abogen
-
 RUN pip install --upgrade pip \
   && if [ -n "$TORCH_VERSION" ]; then \
        pip install torch=="$TORCH_VERSION" torchvision=="$TORCH_VERSION" torchaudio=="$TORCH_VERSION" --index-url "$TORCH_INDEX_URL"; \
@@ -39,6 +37,8 @@ RUN pip install --upgrade pip \
     https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl \
   && pip install --no-cache-dir "mutagen>=1.47.0"
 
+COPY abogen ./abogen
+
 # Install onnxruntime-gpu for CUDA acceleration (supertonic uses ONNX Runtime)
 # Set USE_GPU=false to skip this for CPU-only deployments
 RUN if [ "$USE_GPU" = "true" ]; then \

abogen/webui/conversion_runner.py

@@ -20,7 +20,7 @@ import numpy as np
 import soundfile as sf
 import static_ffmpeg
 
-from abogen.constants import VOICES_INTERNAL
+from abogen.tts_backend_registry import get_metadata
 from abogen.epub3.exporter import build_epub3_package
 from abogen.kokoro_text_normalization import ApostropheConfig, normalize_for_pipeline, HAS_NUM2WORDS
 from abogen.normalization_settings import (
@@ -47,7 +47,7 @@ from abogen.voice_formulas import extract_voice_ids, get_new_voice
 from abogen.voice_profiles import load_profiles, normalize_profile_entry
 from abogen.pronunciation_store import increment_usage
 from abogen.llm_client import LLMClientError
-from abogen.tts_backends.supertonic import DEFAULT_SUPERTONIC_VOICES
+
 
 from .service import Job, JobStatus
 
@@ -68,11 +68,11 @@ def _supertonic_voice_from_spec(spec: Any, fallback: str) -> str:
         raw = "M1"
 
     upper = raw.upper()
-    if upper in DEFAULT_SUPERTONIC_VOICES:
+    if upper in get_metadata("supertonic").voices:
         return upper
 
     fallback_upper = fallback_raw.upper() if fallback_raw else ""
-    if fallback_upper in DEFAULT_SUPERTONIC_VOICES:
+    if fallback_upper in get_metadata("supertonic").voices:
         return fallback_upper
 
     return "M1"
@@ -123,7 +123,7 @@ def _infer_provider_from_spec(value: Any, fallback: str = "kokoro") -> str:
     if not raw:
         return fallback
     upper = raw.upper()
-    if upper in DEFAULT_SUPERTONIC_VOICES:
+    if upper in get_metadata("supertonic").voices:
         return "supertonic"
     if "*" in raw or "+" in raw:
         return "kokoro"
@@ -576,7 +576,7 @@ def _spec_to_voice_ids(spec: Any) -> Set[str]:
             return set(extract_voice_ids(text))
         except ValueError:
             return set()
-    if text in VOICES_INTERNAL:
+    if text in get_metadata("kokoro").voices:
         return {text}
     return set()
 
@@ -640,7 +640,7 @@ def _collect_required_voice_ids(job: Job) -> Set[str]:
             for key in ("resolved_voice", "voice_formula", "voice"):
                 voices.update(_spec_to_voice_ids(payload.get(key)))
 
-    voices.update(VOICES_INTERNAL)
+    voices.update(get_metadata("kokoro").voices)
     return voices
 
 
@@ -1803,8 +1803,8 @@ def run_conversion_job(job: Job) -> None:
                     fallback_key = next(iter(voice_cache.keys()), "")
                     if fallback_key and fallback_key != "__custom_mix":
                         intro_voice_spec = fallback_key.split(":", 1)[-1]
-                if not intro_voice_spec and VOICES_INTERNAL:
-                    intro_voice_spec = VOICES_INTERNAL[0]
+                if not intro_voice_spec:
+                    intro_voice_spec = get_default_voice("kokoro")
 
                 if intro_voice_spec:
                     intro_provider, _, intro_voice_choice, intro_speed, intro_steps = resolve_voice_choice(
@@ -2237,8 +2237,8 @@ def run_conversion_job(job: Job) -> None:
                 if fallback_key and fallback_key != "__custom_mix":
                     # `voice_cache` keys are internal and include provider prefixes.
                     outro_voice_spec = fallback_key.split(":", 1)[-1]
-            if not outro_voice_spec and VOICES_INTERNAL:
-                outro_voice_spec = VOICES_INTERNAL[0]
+            if not outro_voice_spec:
+                outro_voice_spec = get_default_voice("kokoro")
 
             if outro_text and outro_voice_spec:
                 outro_start_time = current_time

abogen/webui/routes/utils/form.py

@@ -32,7 +32,7 @@ from abogen.webui.routes.utils.common import split_profile_spec
 from abogen.utils import calculate_text_length
 from abogen.voice_profiles import serialize_profiles, normalize_profile_entry
 from abogen.chunking import ChunkLevel, build_chunks_for_chapters
-from abogen.constants import VOICES_INTERNAL
+from abogen.tts_backend_registry import get_default_voice
 from abogen.speaker_configs import get_config
 from abogen.kokoro_text_normalization import normalize_roman_numeral_titles
 from dataclasses import dataclass
@@ -616,8 +616,8 @@ def apply_book_step_form(
         custom_formula = ""
 
     base_voice_spec = resolved_default_voice or narrator_voice_raw
-    if not base_voice_spec and VOICES_INTERNAL:
-        base_voice_spec = VOICES_INTERNAL[0]
+    if not base_voice_spec:
+        base_voice_spec = get_default_voice("kokoro")
 
     voice_choice, resolved_language, selected_profile = resolve_voice_choice(
         pending.language,
@@ -796,8 +796,8 @@ def build_pending_job_from_extraction(
         profile_selection = inferred_profile
 
     base_voice = base_voice_input or resolved_default_voice or str(default_voice_setting).strip()
-    if not base_voice and VOICES_INTERNAL:
-        base_voice = VOICES_INTERNAL[0]
+    if not base_voice:
+        base_voice = get_default_voice("kokoro")
     selected_speaker_config = (form.get("speaker_config") or "").strip()
     speaker_config_payload = get_config(selected_speaker_config) if selected_speaker_config else None
 

abogen/webui/routes/utils/settings.py

@@ -6,8 +6,8 @@ from abogen.constants import (
     LANGUAGE_DESCRIPTIONS,
     SUBTITLE_FORMATS,
     SUPPORTED_SOUND_FORMATS,
-    VOICES_INTERNAL,
 )
+from abogen.tts_backend_registry import get_default_voice
 from abogen.normalization_settings import (
     DEFAULT_LLM_PROMPT,
     environment_llm_defaults,
@@ -174,7 +174,7 @@ def settings_defaults() -> Dict[str, Any]:
         "subtitle_format": "srt",
         "save_mode": "default_output" if has_output_override() else "save_next_to_input",
         "default_speaker": "",
-        "default_voice": VOICES_INTERNAL[0] if VOICES_INTERNAL else "",
+        "default_voice": get_default_voice("kokoro"),
         "supertonic_total_steps": 5,
         "supertonic_speed": 1.0,
         "replace_single_newlines": False,

abogen/webui/routes/utils/voice.py

@@ -17,8 +17,8 @@ from abogen.constants import (
     SUPPORTED_SOUND_FORMATS,
     SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION,
     SAMPLE_VOICE_TEXTS,
-    VOICES_INTERNAL,
 )
+from abogen.tts_backend_registry import get_metadata
 from abogen.speaker_configs import list_configs
 from abogen.tts_backend_registry import create_backend
 from abogen.webui.conversion_runner import _select_device, _to_float32, SAMPLE_RATE, SPLIT_PATTERN
@@ -285,7 +285,7 @@ def filter_voice_catalog(
 def build_voice_catalog() -> List[Dict[str, str]]:
     catalog: List[Dict[str, str]] = []
     gender_map = {"f": "Female", "m": "Male"}
-    for voice_id in VOICES_INTERNAL:
+    for voice_id in get_metadata("kokoro").voices:
         prefix, _, rest = voice_id.partition("_")
         language_code = prefix[0] if prefix else "a"
         gender_code = prefix[1] if len(prefix) > 1 else ""
@@ -590,7 +590,7 @@ def template_options() -> Dict[str, Any]:
     voice_catalog = build_voice_catalog()
     return {
         "languages": LANGUAGE_DESCRIPTIONS,
-        "voices": VOICES_INTERNAL,
+        "voices": get_metadata("kokoro").voices,
         "subtitle_formats": SUBTITLE_FORMATS,
         "supported_langs_for_subs": SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION,
         "output_formats": SUPPORTED_SOUND_FORMATS,

abogen/webui/routes/voices.py

@@ -17,7 +17,7 @@ from abogen.speaker_configs import (
     save_configs,
     delete_config,
 )
-from abogen.constants import VOICES_INTERNAL
+
 
 voices_bp = Blueprint("voices", __name__)
 

tests/test_tts_backend.py

@@ -18,6 +18,23 @@ class TestTTSBackendMetadata:
         assert meta.name == "Test Backend"
         assert meta.description == "A test backend"
 
+    def test_voices_field_default_empty(self):
+        meta = TTSBackendMetadata(
+            id="test",
+            name="Test",
+            description="Test backend",
+        )
+        assert meta.voices == ()
+
+    def test_voices_field_stored(self):
+        meta = TTSBackendMetadata(
+            id="test",
+            name="Test",
+            description="Test backend",
+            voices=("v1", "v2"),
+        )
+        assert meta.voices == ("v1", "v2")
+
     def test_is_immutable(self):
         import pytest
 
@@ -132,6 +149,26 @@ class TestBackendRegistration:
         assert meta.name == "SuperTonic"
         assert "SuperTonic" in meta.description
 
+    def test_kokoro_metadata_has_voices(self):
+        import abogen.tts_backends  # noqa: F401
+
+        from abogen.tts_backend_registry import _registry
+
+        meta = _registry.get_metadata("kokoro")
+        assert isinstance(meta.voices, tuple)
+        assert len(meta.voices) > 0
+        assert all(isinstance(v, str) for v in meta.voices)
+
+    def test_supertonic_metadata_has_voices(self):
+        import abogen.tts_backends  # noqa: F401
+
+        from abogen.tts_backend_registry import _registry
+
+        meta = _registry.get_metadata("supertonic")
+        assert isinstance(meta.voices, tuple)
+        assert len(meta.voices) == 10
+        assert meta.voices == ("M1", "M2", "M3", "M4", "M5", "F1", "F2", "F3", "F4", "F5")
+
     def test_kokoro_factory_callable(self):
         import abogen.tts_backends  # noqa: F401
 
@@ -147,3 +184,21 @@ class TestBackendRegistration:
 
         factory = _registry._factories["supertonic"]
         assert callable(factory)
+
+    def test_kokoro_metadata_voices_match_registry(self):
+        """Ensure the metadata property on the instance shares voices with registry."""
+        from abogen.tts_backends.kokoro import _KOKORO_METADATA
+        from abogen.tts_backend_registry import _registry
+
+        registry_meta = _registry.get_metadata("kokoro")
+        assert _KOKORO_METADATA is registry_meta
+        assert _KOKORO_METADATA.voices == registry_meta.voices
+
+    def test_supertonic_metadata_voices_match_registry(self):
+        """Ensure the metadata property on the instance shares voices with registry."""
+        from abogen.tts_backends.supertonic import _SUPERTONIC_METADATA
+        from abogen.tts_backend_registry import _registry
+
+        registry_meta = _registry.get_metadata("supertonic")
+        assert _SUPERTONIC_METADATA is registry_meta
+        assert _SUPERTONIC_METADATA.voices == registry_meta.voices