Runtime model switching, per-model voice caching, thread-safety fix (#12)

* test: add pytest harness for TTS server tests

* feat(config): add supported languages, aliases, cache dir

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

* feat(voice-cache): add per-model voice path resolution

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

* feat(voice-cache): add stem listing and mtime staleness

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

* feat(tts): track active model state with boot snapshot

Add _lock, _loading, _active, _boot_active to TTSService.__init__,
rewrite load_model to record active model state and snapshot boot config.
Change voice_cache type from dict to OrderedDict.

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

* feat(tts): wire per-model cache dir and voice resolution

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

* feat(tts): add reload_model with rollback-on-failure

Add TTSService.reload_model(language, quantize) with mutual-exclusion
guard (_loading flag), boot-source check, SUPPORTED_LANGUAGES validation,
and exception-safe rollback of model + _active on failure. Five new
TDD tests cover the happy path, all rejection cases, and rollback.

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

* feat(tts): gen lock, _loading short-circuit, tagged cache save+stale

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

* feat(tts): collapse voice list by stem

Replace per-file iteration in list_voices with list_voice_stems so
each unique voice name appears exactly once regardless of how many
file variants (wav, safetensors, tagged cache) exist on disk.

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

* feat: add cached version helper for UI

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

* feat(routes): GET /v1/model returns state + versions

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

* feat(routes): POST /v1/model kicks off async reload

Add POST /v1/model endpoint that validates language, guards against
model_path lock / in-flight reload, and delegates to a new
reload_model_async helper (daemon thread, fire-and-forget).

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

* feat(routes): 503 while loading + voice_model_mismatch error

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

* feat(routes): /health includes active_model; pass versions to home

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

* feat(server): validate --language against supported list

* feat(ui): header version strip + GitHub link

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

* feat(ui): model settings panel markup + styles

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

* feat(ui): model settings state machine + polling

Appends the Model Settings panel JS to static/js/app.js: modelUI
element references, updateUIForState, fetchModelState, startPolling,
applyModel, and event-listener wiring for the language select,
quantize toggle, and Apply button.

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

* feat(docker): add pockettts-voice-cache named volume

* feat: pre-create voice cache dir at server boot

* style: ruff check --fix + ruff format across suite

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: bump version to 2.5.3

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ui): version fallback, hidden indicators, btn-secondary, panel padding

- Hardcode app.__version__ as fallback so dev runs (no pip install -e)
no longer show 'Server vunknown'.
- Override [hidden] on flex elements so the loading spinner actually
disappears when not loading.
- Add .btn-secondary styles for the Apply button.
- Restore top padding inside the model settings body so the Language
label has breathing room.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ui): bring select chevron next to content

The native browser chevron pins to the right edge of the select box,
leaving a wide gap on full-width selects. Replace with a custom inline
SVG chevron positioned 14px from the right edge with 36px padding, so
the dropdown indicator visually anchors near the content.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ui): override inline background to make custom chevron visible

#format-select's inline `background: var(--input-bg)` was resetting
background-image to none, hiding the custom chevron. Add !important to
the background- rules so the chevron survives.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ui): more breathing room around Apply button and info banners

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: ignore docs/superpowers/ (local design specs / plans)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(voice-cache): resolve files tagged with the language alias

Files written as <voice>.<alias>.safetensors (e.g. emma.english.safetensors)
were never resolved because we only checked the canonical tag
(emma.english_2026-04.safetensors). Add an alias-tagged fallback after the
canonical lookup in both cache_dir and voices_dir so externally-written or
older caches still resolve. Canonical remains the preferred name; new caches
continue to be written with the canonical tag.

Reported by GitHub Copilot review on PR #12.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(tts): treat existing relative paths as local for cache + staleness

get_voice_state only set resolved_path when os.path.isabs() was true. For
local dev runs where voices_dir/cache_dir is configured as a relative path
(e.g. ./voices), resolve_voice_path returns a relative string — silently
skipping truncate=True, the disk cache save, and stale-cache regeneration.

Treat any existing filesystem path as local, while still preserving the
passthrough for built-in names and hf:// URLs.

Reported by GitHub Copilot review on PR #12.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ui): normalize active language and clear stale error banner

Three related UI bugs surfaced by GitHub Copilot review on PR #12:

1. When the server boots without --language, /v1/model returns
active.value=null. The dropdown wasn't being set to match, and
updateApplyButton compared targetLang !== null, so Apply was enabled
on every fresh load even with no real change pending.

2. Same null comparison made unnecessary reloads possible if the user
clicked Apply with the default selection.

3. The error banner was set when state.last_error was truthy but never
cleared when a subsequent successful reload set it back to null,
leaving stale errors visible indefinitely.

Add effectiveActiveValue() that maps null → 'english' (the actual
default per pocket-tts), use it for the label, dropdown, and diff
comparison. Add the missing else branch on the error banner.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(tts): hold lock around voice state calls; restore filename-with-ext support

Two bugs reported by GitHub Copilot review on PR #12:

1. get_voice_state called model.get_state_for_audio_prompt without
acquiring self._lock, racing with concurrent generation/reload —
pocket-tts v2 TTSModel is not thread-safe. Wrap the model call and
the LRU cache mutation under the lock and short-circuit with the
same _loading 503-style RuntimeError as generate_audio.

2. _resolve_voice_path no longer accepted full filenames in voices_dir
like 'emma.wav'. The new stem-based resolve_voice_path would join
it with another extension ('emma.wav.wav') and fail. Added an early
exact-match check in cache_dir / voices_dir before delegating.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(tts): cover filename-with-extension resolution

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(routes): validate quantize is a JSON boolean

bool('false') is True, which silently enabled quantization for any
client passing a string. Reject non-bool quantize with 400 instead.

Reported by GitHub Copilot review on PR #12.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ui): use normalized active value when reverting after failed apply

The error path was reverting the dropdown using
currentModelState.active.value, which can be null for the default
model — the same case effectiveActiveValue() normalizes to 'english'
in the rest of the UI. Use it here too so the select never lands on
an empty value.

Reported by GitHub Copilot review on PR #12.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(tts): atomic reload claim, race-safe cache hit, dotted-stem parsing

Three bugs found in proper code review of the runtime model switching PR:

1. Reload claim was racy. `if self._loading: raise` followed by
`self._loading = True` could be passed by two threads simultaneously
when concurrent POSTs hit /v1/model. The losing reload would silently
start after the winner completed. Split into atomic `_claim_loading`
helper guarded by a new `_state_lock` (separate from `_lock` so the
claim doesn't wait on long-running generation), and refactor
`reload_model_async` to return False on a lost race so the route can
map directly to 409.

2. The `voice_cache` cache-hit fast path could KeyError if a concurrent
`reload_model` cleared the dict between the `in` check and the
`move_to_end` / read. Catch and fall through to re-encode.

3. The staleness regeneration extracted the voice stem with
`resolved_path.stem.split('.', 1)[0]`, which mangles names containing
dots ('John.Doe.<tag>.safetensors' → 'John' instead of 'John.Doe').
Use `parse_safetensors_name` with `known_model_tags()` so stem and
tag are extracted by the same logic the rest of the cache uses.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(routes): validate JSON body shape and harden mismatch detection

1. `data = request.json or {}` would let JSON values like `42` or

.env.example

@@ -20,3 +20,8 @@ POCKET_TTS_STREAM_DEFAULT=true
 # Hugging Face token for voice cloning (optional)
 # Get your token from: https://huggingface.co/settings/tokens
 # HF_TOKEN=hf_xxxxxxxxxxxxx
+
+# Writable cache for per-model cloned voice safetensors
+# Defaults to <app_base>/voice_cache. In Docker this is /app/voice_cache backed
+# by the `pockettts-voice-cache` named volume.
+# POCKET_TTS_VOICE_CACHE_DIR=/path/to/cache

.gitignore

@@ -185,3 +185,8 @@ cython_debug/
 .cursorindexingignore
 
 .DS_Store
+
+voice_cache/
+
+# Internal design specs and implementation plans (kept locally, not in git)
+docs/superpowers/

Dockerfile

@@ -51,6 +51,9 @@ RUN chown pockettts:pockettts /app && mkdir -p /app/logs && chown pockettts:pock
 RUN mkdir -p /home/pockettts/.cache/huggingface && \
     chown -R pockettts:pockettts /home/pockettts/.cache
 
+# Create voice cache directory with correct ownership for the named volume
+RUN mkdir -p /app/voice_cache && chown pockettts:pockettts /app/voice_cache
+
 # Switch to non-root user
 USER pockettts
 

app/__init__.py

@@ -4,6 +4,10 @@ PocketTTS OpenAI-Compatible Server
 Flask application factory and initialization.
 """
 
+# Keep in sync with pyproject.toml — used as the version fallback when the
+# package isn't installed via pip (e.g. running directly from a clone).
+__version__ = '2.5.3'
+
 from flask import Flask
 
 from app.config import Config
@@ -71,6 +75,9 @@ def init_tts_service(
     # Load model
     tts.load_model(model_path=model_path, language=language, quantize=quantize)
 
+    # Pre-create the voice cache directory (or log warning if not writable)
+    tts._ensure_cache_dir()
+
     # Set voices directory
     if voices_dir:
         tts.set_voices_dir(voices_dir)

app/config.py

@@ -35,6 +35,35 @@ class Config:
     MODEL_PATH = os.environ.get('POCKET_TTS_MODEL_PATH', None)
     LANGUAGE = os.environ.get('POCKET_TTS_LANGUAGE', None)
     QUANTIZE = os.environ.get('POCKET_TTS_QUANTIZE', 'false').lower() == 'true'
+
+    # Supported languages (pocket-tts v2.0.0 predefined model YAMLs)
+    SUPPORTED_LANGUAGES = [
+        'english',  # alias for english_2026-04 (default)
+        'english_2026-01',
+        'english_2026-04',
+        'french_24l',  # no bare `french` — upstream raises
+        'german',
+        'german_24l',
+        'italian',
+        'italian_24l',
+        'portuguese',
+        'portuguese_24l',
+        'spanish',
+        'spanish_24l',
+    ]
+
+    # Canonicalize equivalent model IDs so tagged caches dedupe.
+    LEGACY_MODEL_ALIASES = {
+        'english': 'english_2026-04',
+        'english_2026-01': 'english_2026-04',
+    }
+
+    # Writable voice cache dir for tagged .safetensors clones.
+    VOICE_CACHE_DIR = os.environ.get(
+        'POCKET_TTS_VOICE_CACHE_DIR',
+        str(BASE_PATH / 'voice_cache'),
+    )
+
     DEFAULT_VOICE = os.environ.get(
         'POCKET_TTS_DEFAULT_VOICE', 'hf://kyutai/tts-voices/alba-mackenna/casual.wav'
     )

app/routes.py

@@ -14,6 +14,7 @@ from flask import (
     stream_with_context,
 )
 
+from app.config import Config
 from app.logging_config import get_logger
 from app.services.audio import (
     convert_audio,
@@ -24,6 +25,7 @@ from app.services.audio import (
 )
 from app.services.preprocess import TextPreprocessor
 from app.services.tts import get_tts_service
+from app.services.versions import get_versions
 
 logger = get_logger('routes')
 
@@ -48,7 +50,11 @@ def home():
     """Serve the web interface."""
     from app.config import Config
 
-    return render_template('index.html', is_docker=Config.IS_DOCKER)
+    return render_template(
+        'index.html',
+        is_docker=Config.IS_DOCKER,
+        versions=get_versions(),
+    )
 
 
 @api.route('/health', methods=['GET'])
@@ -71,6 +77,7 @@ def health():
             'sample_rate': tts.sample_rate if tts.is_loaded else None,
             'voices_dir': tts.voices_dir,
             'voice_check': {'valid': voice_valid, 'message': voice_msg},
+            'active_model': tts._active,
         }
     ), 200 if tts.is_loaded else 503
 
@@ -101,6 +108,84 @@ def list_voices():
     )
 
 
+@api.route('/v1/model', methods=['GET'])
+def get_model():
+    """Return the active model state, boot snapshot, and supported languages."""
+    tts = get_tts_service()
+
+    active = tts._active or {'source': 'default', 'value': None, 'quantize': False}
+    boot = tts._boot_active or active
+    differs = active != boot
+    model_path_locked = boot.get('source') == 'model_path'
+    versions = get_versions()
+
+    return jsonify(
+        {
+            'active': active,
+            'boot': boot,
+            'differs_from_boot': differs,
+            'loading': tts._loading,
+            'loading_target': getattr(tts, '_loading_target', None),
+            'last_error': getattr(tts, '_last_reload_error', None),
+            'model_path_locked': model_path_locked,
+            'available_languages': list(Config.SUPPORTED_LANGUAGES),
+            'server_version': versions['server'],
+            'pocket_tts_version': versions['pocket_tts'],
+        }
+    )
+
+
+@api.route('/v1/model', methods=['POST'])
+def post_model():
+    """Request a runtime model switch. Returns 202; UI polls GET for completion."""
+    data = request.json
+    if not isinstance(data, dict):
+        return jsonify({'error': 'Request body must be a JSON object'}), 400
+
+    language = data.get('language')
+
+    # Reject non-bool `quantize` rather than coercing — `bool('false')` is True,
+    # which would silently enable quantization for any client sending a string.
+    quantize = False
+    if 'quantize' in data:
+        if not isinstance(data['quantize'], bool):
+            return jsonify({'error': "Field 'quantize' must be a boolean"}), 400
+        quantize = data['quantize']
+
+    if not language:
+        return jsonify({'error': "Missing required field 'language'"}), 400
+
+    if language not in Config.SUPPORTED_LANGUAGES:
+        return jsonify(
+            {
+                'error': f"Unknown language: '{language}'",
+                'available': list(Config.SUPPORTED_LANGUAGES),
+            }
+        ), 400
+
+    tts = get_tts_service()
+
+    if tts._boot_active and tts._boot_active.get('source') == 'model_path':
+        return jsonify(
+            {
+                'error': 'Language switching disabled: server started with --model-path.',
+            }
+        ), 403
+
+    # `reload_model_async` does the atomic check-and-claim, so the 409 race
+    # window between `if tts._loading` and `start()` is gone.
+    started = tts.reload_model_async(language=language, quantize=quantize)
+    if not started:
+        return jsonify({'error': 'A model reload is already in progress.'}), 409
+
+    return jsonify(
+        {
+            'status': 'accepted',
+            'loading_target': {'value': language, 'quantize': quantize},
+        }
+    ), 202
+
+
 @api.route('/v1/audio/speech', methods=['POST'])
 def generate_speech():
     """
@@ -120,8 +205,8 @@ def generate_speech():
 
     data = request.json
 
-    if not data:
-        return jsonify({'error': 'Missing JSON body'}), 400
+    if not isinstance(data, dict):
+        return jsonify({'error': 'Request body must be a JSON object'}), 400
 
     text = data.get('input')
     if not text:
@@ -135,6 +220,9 @@ def generate_speech():
 
     tts = get_tts_service()
 
+    if tts._loading:
+        return jsonify({'error': 'Model is reloading; retry shortly.'}), 503
+
     # Validate voice first
     is_valid, msg = tts.validate_voice(voice)
     if not is_valid:
@@ -172,8 +260,35 @@ def generate_speech():
         return _generate_file(tts, voice_state, text, target_format)
 
     except ValueError as e:
+        msg = str(e)
+        # Detect the legacy-unlabeled-safetensors mismatch pattern. Re-resolving
+        # can itself raise (e.g. SSRF protection on http:// URLs); treat any
+        # failure here as "not a mismatch" and fall through to the generic 400.
+        try:
+            resolved = tts._resolve_voice_path(voice) if not tts._loading else ''
+        except Exception:
+            resolved = ''
+        is_legacy_st = resolved.endswith('.safetensors') and not any(
+            resolved.endswith(f'.{tag}.safetensors') for tag in Config.SUPPORTED_LANGUAGES
+        )
+        mismatch_markers = ('size mismatch', 'Error(s) in loading state_dict', 'shape')
+        if is_legacy_st and any(m in msg for m in mismatch_markers):
+            return jsonify(
+                {
+                    'error': 'voice_model_mismatch',
+                    'message': (
+                        f"Voice '{voice}' appears to have been cloned for a different "
+                        f'model. Upload the original audio (.wav/.mp3/.flac) to '
+                        f're-clone for the active model, or switch to the model it '
+                        f'was generated for.'
+                    ),
+                    'voice': voice,
+                    'active_model': (tts._active or {}).get('value'),
+                }
+            ), 400
+
         logger.warning(f'Voice loading failed: {e}')
-        return jsonify({'error': str(e)}), 400
+        return jsonify({'error': msg}), 400
     except Exception as e:
         logger.exception('Generation failed')
         return jsonify({'error': str(e)}), 500

app/services/tts.py

@@ -4,11 +4,8 @@ TTS Service - handles model loading, voice management, and audio generation.
 
 import os
 import time
-from collections.abc import Iterator
 from pathlib import Path
 
-import torch
-
 from app.config import Config
 from app.logging_config import get_logger
 
@@ -16,16 +13,19 @@ logger = get_logger('tts')
 
 # Lazy import pocket_tts to allow for better error handling
 TTSModel = None
+export_model_state = None
 
 
 def _ensure_pocket_tts():
     """Ensure pocket-tts is imported."""
-    global TTSModel
+    global TTSModel, export_model_state
     if TTSModel is None:
         try:
             from pocket_tts import TTSModel as _TTSModel
+            from pocket_tts.models.tts_model import export_model_state as _export_state
 
             TTSModel = _TTSModel
+            export_model_state = _export_state
         except ImportError as exc:
             raise ImportError('pocket-tts not found. Install with: pip install pocket-tts') from exc
 
@@ -37,11 +37,60 @@ class TTSService:
     """
 
     def __init__(self):
+        import threading
+        from collections import OrderedDict
+
         self.model = None
-        self.voice_cache: dict = {}
+        self.voice_cache: OrderedDict = OrderedDict()
         self.voices_dir: str | None = None
         self._model_loaded = False
 
+        # Concurrency + reload state.
+        # _lock is held for the duration of model operations (load, generate);
+        # _state_lock is held only briefly to mutate the loading flag and
+        # related state, so concurrent reload claims are atomic without
+        # waiting for in-flight generation to finish.
+        self._lock = threading.Lock()
+        self._state_lock = threading.Lock()
+        self._loading = False  # fast-path flag; read without lock, written under _state_lock
+        self._active: dict | None = None
+        self._boot_active: dict | None = None
+        self._loading_target: dict | None = None
+        self._last_reload_error: str | None = None
+
+        self.cache_dir: Path | None = Path(Config.VOICE_CACHE_DIR)
+
+    def _ensure_cache_dir(self) -> None:
+        """Create the voice cache directory on first need. Tolerate read-only FS."""
+        if self.cache_dir is None:
+            return
+        try:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            logger.warning(
+                f'Voice cache dir {self.cache_dir} is not writable ({e}); '
+                f'cache persistence disabled.'
+            )
+            self.cache_dir = None
+
+    def _save_cloned_state(self, state: dict, audio_path) -> None:
+        """Persist a freshly-cloned state as <stem>.<active_tag>.safetensors."""
+
+        from app.services.voice_cache import active_model_tag
+
+        self._ensure_cache_dir()
+        if self.cache_dir is None:
+            return
+
+        audio_path = Path(audio_path)
+        tag = active_model_tag((self._active or {}).get('value') or 'english')
+        target = self.cache_dir / f'{audio_path.stem}.{tag}.safetensors'
+        try:
+            export_model_state(state, target)
+            logger.info(f'Saved cloned voice state to {target}')
+        except OSError as e:
+            logger.warning(f'Could not save voice cache to {target}: {e}')
+
     @property
     def is_loaded(self) -> bool:
         """Check if the model is loaded."""
@@ -66,6 +115,7 @@ class TTSService:
         model_path: str | None = None,
         language: str | None = None,
         quantize: bool = False,
+        _is_boot: bool = True,
     ) -> None:
         """
         Load the TTS model.
@@ -75,17 +125,17 @@ class TTSService:
             language: Optional language identifier (e.g., english, french_24l).
                       Incompatible with model_path.
             quantize: If True, apply dynamic int8 quantization to reduce memory.
+            _is_boot: Internal; True only for the first boot-time load. Controls
+                      whether _boot_active is initialized.
         """
         _ensure_pocket_tts()
 
         logger.info('Loading Pocket TTS model...')
         t0 = time.time()
 
-        # Determine model path
         effective_path = model_path
 
         if not effective_path:
-            # Check for bundled model in frozen executable
             _, bundle_model = Config.get_bundle_paths()
             if bundle_model and os.path.isfile(bundle_model):
                 effective_path = bundle_model
@@ -95,14 +145,21 @@ class TTSService:
             if effective_path:
                 logger.info(f'Loading model from: {effective_path}')
                 self.model = TTSModel.load_model(config=effective_path, quantize=quantize)
+                active = {'source': 'model_path', 'value': effective_path, 'quantize': quantize}
             elif language:
                 logger.info(f'Loading model with language: {language}')
                 self.model = TTSModel.load_model(language=language, quantize=quantize)
+                active = {'source': 'language', 'value': language, 'quantize': quantize}
             else:
                 logger.info('Loading default model from HuggingFace...')
                 self.model = TTSModel.load_model(quantize=quantize)
+                active = {'source': 'default', 'value': None, 'quantize': quantize}
 
             self._model_loaded = True
+            self._active = active
+            if _is_boot:
+                self._boot_active = dict(active)
+
             load_time = time.time() - t0
             logger.info(
                 f'Model loaded in {load_time:.2f}s. '
@@ -113,6 +170,95 @@ class TTSService:
             logger.error(f'Failed to load model: {e}')
             raise
 
+    def _validate_reload(self, language: str) -> None:
+        """Pre-flight checks shared by sync and async reload paths."""
+        if self._boot_active and self._boot_active['source'] == 'model_path':
+            raise RuntimeError(
+                'Cannot switch language: server was started with a custom model_path.'
+            )
+        if language not in Config.SUPPORTED_LANGUAGES:
+            raise ValueError(f'Unsupported language: {language!r}')
+
+    def _claim_loading(self, language: str, quantize: bool) -> bool:
+        """Atomically check-and-set the loading flag.
+
+        Returns True if this caller owns the reload slot, False if another
+        reload is already in progress. Held briefly under _state_lock so
+        concurrent claims race-free without waiting on the long-held _lock.
+        """
+        with self._state_lock:
+            if self._loading:
+                return False
+            self._loading = True
+            self._loading_target = {'value': language, 'quantize': quantize}
+            self._last_reload_error = None
+        return True
+
+    def _release_loading(self) -> None:
+        with self._state_lock:
+            self._loading = False
+            self._loading_target = None
+
+    def _do_reload(self, language: str, quantize: bool) -> None:
+        """Perform the actual model swap. Caller must already hold the loading
+        slot via `_claim_loading`. Restores the previous model on failure."""
+        with self._lock:
+            previous_model = self.model
+            previous_active = self._active
+            try:
+                self.load_model(language=language, quantize=quantize, _is_boot=False)
+                self.voice_cache.clear()
+            except Exception:
+                # Restore previous state on failure so the server remains usable.
+                self.model = previous_model
+                self._active = previous_active
+                raise
+
+    def reload_model(self, language: str, quantize: bool) -> None:
+        """Reload the model synchronously.
+
+        Validates, atomically claims the reload slot, then performs the swap
+        while holding the model lock. Pocket-tts v2 `TTSModel` is not
+        thread-safe so generation is serialized via the same lock.
+
+        Raises:
+            ValueError: unknown language.
+            RuntimeError: model_path locked, already loading, or load failure.
+        """
+        self._validate_reload(language)
+        if not self._claim_loading(language, quantize):
+            raise RuntimeError('already loading')
+        try:
+            self._do_reload(language, quantize)
+        finally:
+            self._release_loading()
+
+    def reload_model_async(self, language: str, quantize: bool) -> bool:
+        """Atomically claim the reload slot and start a worker thread.
+
+        Returns True if the claim succeeded (worker started), False if a
+        reload was already in progress. Validation errors are still raised
+        synchronously so the caller can surface them as 400/403.
+        """
+        import threading
+
+        self._validate_reload(language)
+        if not self._claim_loading(language, quantize):
+            return False
+
+        def _worker():
+            try:
+                self._do_reload(language, quantize)
+            except Exception as e:
+                with self._state_lock:
+                    self._last_reload_error = f'{type(e).__name__}: {e}'
+                logger.error(f'Reload failed: {self._last_reload_error}')
+            finally:
+                self._release_loading()
+
+        threading.Thread(target=_worker, daemon=True, name='tts-reload').start()
+        return True
+
     def set_voices_dir(self, voices_dir: str | None) -> None:
         """
         Set the directory for custom voice files.
@@ -130,36 +276,87 @@ class TTSService:
             self.voices_dir = None
 
     def get_voice_state(self, voice_id_or_path: str) -> dict:
-        """
-        Resolve voice ID to a model state with caching.
+        """Resolve a voice ID to a cached model state.
 
-        Args:
-            voice_id_or_path: Voice identifier (name, file path, or URL)
-
-        Returns:
-            Model state dictionary for the voice
+        When the resolved path is raw audio, encode it against the active model
+        and persist the result as <stem>.<active_tag>.safetensors in cache_dir.
+        If a tagged cache exists but its source audio is newer, regenerate.
 
-        Raises:
-            ValueError: If voice cannot be loaded
+        Pocket-tts v2 `TTSModel` is not thread-safe, so model invocations are
+        serialized under `self._lock` (the same lock that protects generation
+        and reload).
         """
+
+        from app.services.voice_cache import (
+            AUDIO_EXTENSIONS,
+            cache_is_stale,
+            known_model_tags,
+            parse_safetensors_name,
+        )
+
+        if self._loading:
+            raise RuntimeError('model reloading')
         if not self.is_loaded:
             raise RuntimeError('Model not loaded. Call load_model() first.')
 
-        # Resolve the voice path
         resolved_key = self._resolve_voice_path(voice_id_or_path)
 
-        # Check cache
+        # Cache hit fast path. The dict can be cleared concurrently by
+        # `reload_model`, so guard against a KeyError between `in` and access.
         if resolved_key in self.voice_cache:
-            logger.debug(f'Using cached voice state for: {resolved_key}')
-            return self.voice_cache[resolved_key]
+            try:
+                self.voice_cache.move_to_end(resolved_key)
+                logger.debug(f'Using in-memory voice state for: {resolved_key}')
+                return self.voice_cache[resolved_key]
+            except KeyError:
+                pass  # raced with cache clear; fall through and re-encode
+
+        # If resolved to a tagged cache, check staleness against raw-audio source.
+        # Treat any existing filesystem path as local — relative paths from a
+        # configured `voices_dir` (common in local dev) must still get the
+        # truncate=True clone path and disk caching.
+        resolved_path = (
+            Path(resolved_key)
+            if os.path.isabs(resolved_key) or os.path.exists(resolved_key)
+            else None
+        )
+        regenerate_from_source: Path | None = None
+
+        if resolved_path and resolved_path.suffix == '.safetensors' and self.voices_dir:
+            # Use the same parser the cache module uses so stems containing
+            # dots (e.g. "John.Doe.english_2026-04.safetensors" → "John.Doe")
+            # are extracted correctly.
+            stem, _tag = parse_safetensors_name(resolved_path.name, known_model_tags())
+            for ext in AUDIO_EXTENSIONS:
+                source = Path(self.voices_dir) / f'{stem}{ext}'
+                if cache_is_stale(cache_path=resolved_path, source_path=source):
+                    regenerate_from_source = source
+                    break
 
-        # Load voice
         logger.info(f'Loading voice: {resolved_key}')
         t0 = time.time()
 
         try:
-            state = self.model.get_state_for_audio_prompt(resolved_key)
-            self.voice_cache[resolved_key] = state
+            with self._lock:
+                if regenerate_from_source:
+                    logger.info(f'Regenerating stale cache from {regenerate_from_source}')
+                    state = self.model.get_state_for_audio_prompt(
+                        regenerate_from_source, truncate=True
+                    )
+                    self._save_cloned_state(state, regenerate_from_source)
+                elif resolved_path and resolved_path.suffix.lower() in AUDIO_EXTENSIONS:
+                    state = self.model.get_state_for_audio_prompt(resolved_path, truncate=True)
+                    self._save_cloned_state(state, resolved_path)
+                else:
+                    # Pre-made .safetensors OR built-in OR hf:// — let pocket-tts handle it.
+                    state = self.model.get_state_for_audio_prompt(resolved_key)
+
+                # LRU insert (under the lock for consistency with the dict mutation
+                # in `reload_model.voice_cache.clear()`).
+                self.voice_cache[resolved_key] = state
+                if len(self.voice_cache) > 32:
+                    self.voice_cache.popitem(last=False)
+
             load_time = time.time() - t0
             logger.info(f'Voice loaded in {load_time:.2f}s: {resolved_key}')
             return state
@@ -169,53 +366,53 @@ class TTSService:
             raise ValueError(f"Voice '{voice_id_or_path}' could not be loaded: {e}") from e
 
     def _resolve_voice_path(self, voice_id_or_path: str) -> str:
+        """Resolve a voice identifier using per-model cache preference.
+
+        Raises ValueError on unsafe URL schemes (retained from previous behavior).
         """
-        Resolve a voice identifier to its actual path or ID.
 
-        Args:
-            voice_id_or_path: Voice identifier
+        from app.services.voice_cache import resolve_voice_path
 
-        Returns:
-            Resolved path or identifier
-
-        Raises:
-            ValueError: If unsafe URL scheme is used
-        """
-        # Block potentially dangerous URL schemes (SSRF protection)
+        # Retain SSRF protection.
         if voice_id_or_path.startswith(('http://', 'https://')):
             raise ValueError(
                 f'URL scheme not allowed for security reasons: {voice_id_or_path[:50]}. '
                 "Use 'hf://' for HuggingFace models or provide a local file path."
             )
 
-        # Allow HuggingFace URLs
         if voice_id_or_path.startswith('hf://'):
             return voice_id_or_path
 
-        # Check if it's a built-in voice
+        # Built-in names pass through untouched (pocket-tts handles resolution).
         if voice_id_or_path.lower() in Config.BUILTIN_VOICES:
             return voice_id_or_path.lower()
 
-        # Check voices directory
-        if self.voices_dir:
-            for ext in Config.VOICE_EXTENSIONS:
-                # Try exact match first
-                possible_path = os.path.join(self.voices_dir, voice_id_or_path)
-                if os.path.exists(possible_path):
-                    return os.path.abspath(possible_path)
-
-                # Try with extension
-                if not voice_id_or_path.endswith(ext):
-                    possible_path = os.path.join(self.voices_dir, voice_id_or_path + ext)
-                    if os.path.exists(possible_path):
-                        return os.path.abspath(possible_path)
-
-        # Check if it's an absolute path that exists
+        # Absolute path hit.
         if os.path.isabs(voice_id_or_path) and os.path.exists(voice_id_or_path):
             return voice_id_or_path
 
-        # Return as-is, let pocket-tts handle it
-        return voice_id_or_path
+        voices_path = Path(self.voices_dir) if self.voices_dir else None
+
+        # Backwards-compat: accept full filenames (e.g. `emma.wav`) by checking
+        # for an exact match in cache_dir / voices_dir before falling through
+        # to stem-based resolution. Without this, `voice_id_or_path` containing
+        # an extension would never match anything and pocket-tts would receive
+        # the raw string.
+        for directory in (self.cache_dir, voices_path):
+            if directory:
+                exact = directory / voice_id_or_path
+                if exact.exists():
+                    return str(exact)
+
+        active_model = (self._active or {}).get('value') or 'english'
+
+        resolved = resolve_voice_path(
+            voice_id=voice_id_or_path,
+            active_model=active_model,
+            voices_dir=voices_path,
+            cache_dir=self.cache_dir,
+        )
+        return str(resolved) if isinstance(resolved, Path) else resolved
 
     def validate_voice(self, voice_id_or_path: str) -> tuple[bool, str]:
         """
@@ -253,84 +450,53 @@ class TTSService:
 
         return False, f'Voice not found: {voice_id_or_path}'
 
-    def generate_audio(self, voice_state: dict, text: str) -> torch.Tensor:
-        """
-        Generate complete audio for given text.
+    def generate_audio(self, voice_state: dict, text: str):
+        """Generate complete audio for given text."""
+        import torch  # noqa: F401 — kept for return-type doc
 
-        Args:
-            voice_state: Model state from get_voice_state()
-            text: Text to synthesize
-
-        Returns:
-            Audio tensor
-        """
+        if self._loading:
+            raise RuntimeError('model reloading')
         if not self.is_loaded:
             raise RuntimeError('Model not loaded')
 
-        t0 = time.time()
-        audio = self.model.generate_audio(voice_state, text)
-        gen_time = time.time() - t0
+        with self._lock:
+            t0 = time.time()
+            audio = self.model.generate_audio(voice_state, text)
+            gen_time = time.time() - t0
 
         logger.info(f'Generated {len(text)} chars in {gen_time:.2f}s')
         return audio
 
-    def generate_audio_stream(self, voice_state: dict, text: str) -> Iterator[torch.Tensor]:
-        """
-        Generate audio in streaming chunks.
-
-        Args:
-            voice_state: Model state from get_voice_state()
-            text: Text to synthesize
-
-        Yields:
-            Audio tensor chunks
-        """
+    def generate_audio_stream(self, voice_state: dict, text: str):
+        """Generate audio in streaming chunks. Holds the lock for the entire stream."""
+        if self._loading:
+            raise RuntimeError('model reloading')
         if not self.is_loaded:
             raise RuntimeError('Model not loaded')
 
         logger.info(f'Starting streaming generation for {len(text)} chars')
-        yield from self.model.generate_audio_stream(voice_state, text)
+        with self._lock:
+            yield from self.model.generate_audio_stream(voice_state, text)
 
     def list_voices(self) -> list[dict]:
-        """
-        List all available voices.
+        """List built-in voices and custom voices (one entry per stem)."""
+
+        from app.services.voice_cache import list_voice_stems
+
+        voices: list[dict] = []
+
+        # Built-in voices (sorted).
+        for name in sorted(Config.BUILTIN_VOICES):
+            voices.append({'id': name, 'name': name.capitalize(), 'type': 'builtin'})
+
+        voices_path = Path(self.voices_dir) if self.voices_dir else None
+        stems = list_voice_stems(voices_dir=voices_path, cache_dir=self.cache_dir)
+
+        for stem in stems:
+            # Format name: "bobby_mcfern" -> "Bobby Mcfern"
+            clean_name = stem.replace('_', ' ').replace('-', ' ').title()
+            voices.append({'id': stem, 'name': clean_name, 'type': 'custom'})
 
-        Returns:
-            List of voice dictionaries with 'id' and 'name' keys
-        """
-        voices = []
-
-        # Built-in voices (sorted alphabetically)
-        builtin_sorted = sorted(Config.BUILTIN_VOICES)
-        for voice in builtin_sorted:
-            voices.append({'id': voice, 'name': voice.capitalize(), 'type': 'builtin'})
-
-        # Custom voices from directory
-        custom_voices = []
-        if self.voices_dir and os.path.isdir(self.voices_dir):
-            voice_dir = Path(self.voices_dir)
-
-            # Collect all valid files
-            voice_files = []
-            for ext in Config.VOICE_EXTENSIONS:
-                voice_files.extend(voice_dir.glob(f'*{ext}'))
-
-            # Sort alphabetically by filename
-            voice_files.sort(key=lambda f: f.name.lower())
-
-            for voice_file in voice_files:
-                # Format name: "bobby_mcfern" -> "Bobby Mcfern"
-                clean_name = voice_file.stem.replace('_', ' ').replace('-', ' ').title()
-
-                custom_voices.append(
-                    {
-                        'id': voice_file.name,
-                        'name': clean_name,
-                        'type': 'custom',
-                    }
-                )
-
-        voices.extend(custom_voices)
         return voices
 
 

app/services/versions.py

@@ -0,0 +1,26 @@
+"""Cached version lookup for the web UI."""
+
+from functools import lru_cache
+from importlib.metadata import PackageNotFoundError, version
+
+from app import __version__ as _SERVER_VERSION_FALLBACK
+
+
+@lru_cache(maxsize=1)
+def get_versions() -> dict[str, str]:
+    """Return {'server': ..., 'pocket_tts': ...}.
+
+    Falls back to the hardcoded `app.__version__` for the server when the
+    package isn't installed via pip. `pocket_tts` falls back to 'unknown'.
+    """
+    try:
+        server = version('pocket-tts-openai-server')
+    except PackageNotFoundError:
+        server = _SERVER_VERSION_FALLBACK
+
+    try:
+        pocket_tts = version('pocket-tts')
+    except PackageNotFoundError:
+        pocket_tts = 'unknown'
+
+    return {'server': server, 'pocket_tts': pocket_tts}

app/services/voice_cache.py

@@ -0,0 +1,122 @@
+"""Pure filename and path logic for per-model cached voice states.
+
+Kept separate from tts.py so it can be exercised without loading pocket-tts.
+"""
+
+from pathlib import Path
+
+from app.config import Config
+
+
+def active_model_tag(raw_model: str) -> str:
+    """Normalize a language identifier for use as a filename tag.
+
+    Equivalent names (english, english_2026-01, english_2026-04) map to a
+    single canonical tag so cache files don't duplicate.
+    """
+    return Config.LEGACY_MODEL_ALIASES.get(raw_model, raw_model)
+
+
+def known_model_tags() -> set[str]:
+    """Filename tags we treat as model identifiers during parsing.
+
+    Includes both the raw supported languages and the alias-target canonicals.
+    """
+    return set(Config.SUPPORTED_LANGUAGES) | set(Config.LEGACY_MODEL_ALIASES.values())
+
+
+def parse_safetensors_name(filename: str, tags: set[str]) -> tuple[str, str | None]:
+    """Split `stem.model_tag.safetensors` into (stem, tag).
+
+    Returns (stem, None) when the filename is unlabeled or the final segment
+    is not a recognized tag.
+    """
+    base = Path(filename).stem  # strips .safetensors
+    if '.' in base:
+        stem, tag = base.rsplit('.', 1)
+        if tag in tags:
+            return stem, tag
+    return base, None
+
+
+def resolve_voice_path(
+    voice_id: str,
+    active_model: str,
+    voices_dir: Path | None,
+    cache_dir: Path | None,
+) -> Path | str:
+    """Resolve a voice identifier to its on-disk source.
+
+    Preference order (within each directory, the canonical-tagged filename
+    is checked first; if `active_model` is an alias, the alias-tagged
+    filename is checked as a fallback so files written under either name
+    resolve correctly):
+      1. cache_dir/<voice_id>.<canonical_tag>.safetensors
+      2. cache_dir/<voice_id>.<active_model>.safetensors  (alias fallback)
+      3. voices_dir/<voice_id>.<canonical_tag>.safetensors
+      4. voices_dir/<voice_id>.<active_model>.safetensors  (alias fallback)
+      5. voices_dir/<voice_id>.{wav,mp3,flac}
+      6. voices_dir/<voice_id>.safetensors  (legacy unlabeled)
+      7. The bare voice_id string — pocket-tts will resolve (e.g. built-ins).
+
+    New caches are always written using the canonical tag (see
+    `_save_cloned_state` in tts.py), so the alias-tagged paths exist only
+    for files placed by external tools or by users running an older version.
+    """
+    canonical_tag = active_model_tag(active_model)
+    candidates = [f'{voice_id}.{canonical_tag}.safetensors']
+    if active_model != canonical_tag:
+        candidates.append(f'{voice_id}.{active_model}.safetensors')
+
+    for directory in (cache_dir, voices_dir):
+        if not directory:
+            continue
+        for name in candidates:
+            p = directory / name
+            if p.exists():
+                return p
+
+    if voices_dir:
+        for ext in ('.wav', '.mp3', '.flac'):
+            p = voices_dir / f'{voice_id}{ext}'
+            if p.exists():
+                return p
+
+        p = voices_dir / f'{voice_id}.safetensors'
+        if p.exists():
+            return p
+
+    return voice_id
+
+
+AUDIO_EXTENSIONS = ('.wav', '.mp3', '.flac')
+
+
+def list_voice_stems(
+    voices_dir: Path | None,
+    cache_dir: Path | None,
+) -> list[str]:
+    """Return the unique voice stems present across voices_dir and cache_dir."""
+    stems: set[str] = set()
+    tags = known_model_tags()
+
+    for directory in (voices_dir, cache_dir):
+        if not directory or not directory.is_dir():
+            continue
+        for ext in AUDIO_EXTENSIONS:
+            for f in directory.glob(f'*{ext}'):
+                stems.add(f.stem)
+        for f in directory.glob('*.safetensors'):
+            stem, _tag = parse_safetensors_name(f.name, tags)
+            stems.add(stem)
+
+    return sorted(stems)
+
+
+def cache_is_stale(cache_path: Path, source_path: Path) -> bool:
+    """True when `source_path` exists and is newer than `cache_path`."""
+    if not source_path.exists():
+        return False
+    if not cache_path.exists():
+        return False
+    return source_path.stat().st_mtime > cache_path.stat().st_mtime

docker-compose.yml

@@ -30,6 +30,7 @@ services:
       - POCKET_TTS_LANGUAGE=${POCKET_TTS_LANGUAGE:-}
       # Enable int8 quantization for lower memory usage and improved speed
       - POCKET_TTS_QUANTIZE=${POCKET_TTS_QUANTIZE:-false}
+      - POCKET_TTS_VOICE_CACHE_DIR=/app/voice_cache
       # Hugging Face token for voice cloning (optional)
       - HF_TOKEN=${HF_TOKEN:-}
 
@@ -40,6 +41,8 @@ services:
       - ./logs:/app/logs
       # Cache HuggingFace models to avoid re-downloading
       - pockettts-cache:/home/pockettts/.cache/huggingface
+      # Writable cache for per-model cloned voice safetensors
+      - pockettts-voice-cache:/app/voice_cache
 
     restart: unless-stopped
 
@@ -67,3 +70,5 @@ services:
 volumes:
   pockettts-cache:
     name: pockettts-huggingface-cache
+  pockettts-voice-cache:
+    name: pockettts-voice-cache

pyproject.toml

@@ -4,7 +4,7 @@ license = {text = "MIT"}
 name = "pocket-tts-openai-server"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "2.5.2"
+version = "2.5.3"
 
 dependencies = [
   "flask>=3.0.0",

pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+addopts = -v --tb=short

server.py

@@ -126,6 +126,14 @@ def main():
         logger.error('--language and --model-path are mutually exclusive. Use one or the other.')
         sys.exit(1)
 
+    # Validate --language against supported list (prevents cryptic pocket-tts errors).
+    if args.language and args.language not in Config.SUPPORTED_LANGUAGES:
+        logger.error(
+            f"Unknown language '{args.language}'. "
+            f'Supported: {", ".join(Config.SUPPORTED_LANGUAGES)}'
+        )
+        sys.exit(1)
+
     # Initialize TTS service
     try:
         init_tts_service(

static/css/style.css

@@ -109,6 +109,21 @@ select {
 		box-shadow 0.2s;
 }
 
+/* Replace native select chevron with a custom one positioned right next to
+   the content area instead of floating at the far edge of the box.
+   `!important` on background-image is needed because #format-select has an
+   inline `background: var(--input-bg)` that would otherwise reset the image. */
+select {
+	appearance: none;
+	-webkit-appearance: none;
+	-moz-appearance: none;
+	background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8' viewBox='0 0 12 8'%3E%3Cpath fill='none' stroke='%238b949e' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' d='M1 1l5 5 5-5'/%3E%3C/svg%3E") !important;
+	background-repeat: no-repeat !important;
+	background-position: right 14px center !important;
+	background-size: 12px 8px !important;
+	padding-right: 36px !important;
+}
+
 input[type='file'] {
 	width: 100%;
 	padding: 0.5rem;
@@ -622,6 +637,171 @@ audio {
 	transform: translateY(1px);
 }
 
+.version-strip {
+	color: var(--text-secondary);
+	font-size: 0.8em;
+	margin-top: 4px;
+	margin-bottom: 0;
+}
+
+.version-strip a {
+	color: var(--text-secondary);
+	text-decoration: none;
+	border-bottom: 1px dotted currentColor;
+}
+
+.version-strip a:hover {
+	color: var(--text-color);
+}
+
+.model-settings {
+    margin-bottom: 20px;
+    border: 1px solid var(--border-color);
+    border-radius: 6px;
+    background: var(--input-bg);
+}
+
+.model-settings-summary {
+    padding: 10px 14px;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-weight: 500;
+    list-style: none;
+}
+
+.model-settings-summary::-webkit-details-marker {
+    display: none;
+}
+
+.disclosure-caret {
+    display: inline-block;
+    transition: transform 0.15s ease;
+    color: var(--text-secondary);
+}
+
+.model-settings[open] .disclosure-caret {
+    transform: rotate(90deg);
+}
+
+.summary-label #active-model-label {
+    font-family: monospace;
+    color: var(--text-color);
+}
+
+.model-badge {
+    font-size: 0.75em;
+    padding: 2px 6px;
+    border-radius: 3px;
+    background: var(--border-color);
+    color: var(--text-secondary);
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+}
+
+.session-badge {
+    background: #b45309;
+    color: #fff;
+}
+
+.loading-indicator {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 0.9em;
+    color: var(--text-secondary);
+}
+
+.spinner-small {
+    width: 12px;
+    height: 12px;
+    border: 2px solid var(--border-color);
+    border-top-color: var(--text-color);
+    border-radius: 50%;
+    display: inline-block;
+    animation: spin 0.8s linear infinite;
+}
+
+.model-settings-body {
+    padding: 14px 14px 14px 14px;
+    border-top: 1px solid var(--border-color);
+}
+
+/* HTML [hidden] is otherwise overridden by display: inline-flex etc. */
+.model-settings [hidden] {
+    display: none !important;
+}
+
+.btn-secondary {
+    padding: 8px 18px;
+    margin-top: 14px;
+    border: 1px solid var(--border-color);
+    border-radius: 6px;
+    background: transparent;
+    color: var(--text-color);
+    font-weight: 500;
+    cursor: pointer;
+    transition:
+        background 0.15s,
+        border-color 0.15s,
+        opacity 0.15s;
+}
+
+.btn-secondary:hover:not(:disabled) {
+    background: var(--input-bg);
+    border-color: var(--accent-color);
+}
+
+.btn-secondary:active:not(:disabled) {
+    transform: translateY(1px);
+}
+
+.btn-secondary:disabled {
+    opacity: 0.45;
+    cursor: not-allowed;
+}
+
+.inline-label {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    cursor: pointer;
+}
+
+.info-banner {
+    padding: 10px 12px;
+    border-radius: 4px;
+    margin-top: 14px;
+    font-size: 0.9em;
+    line-height: 1.4;
+}
+
+.info-banner code {
+    font-family: monospace;
+    background: rgba(255,255,255,0.06);
+    padding: 1px 4px;
+    border-radius: 2px;
+}
+
+.info-banner.info {
+    background: rgba(59,130,246,0.08);
+    border-left: 3px solid #3b82f6;
+    color: var(--text-color);
+}
+
+.info-banner.warning {
+    background: rgba(234,179,8,0.08);
+    border-left: 3px solid #eab308;
+    color: var(--text-color);
+}
+
+.info-banner.error {
+    background: rgba(239,68,68,0.08);
+    border-left: 3px solid #ef4444;
+    color: var(--text-color);
+}
+
 /* Responsive adjustments */
 @media (max-width: 600px) {
 	.params-table {

static/js/app.js

@@ -485,3 +485,196 @@ document.addEventListener('DOMContentLoaded', async () => {
 	// Initial load
 	await loadVoices();
 });
+
+// ============================================================
+// Model Settings panel
+// ============================================================
+
+const modelUI = {
+    activeLabel: document.getElementById('active-model-label'),
+    quantizeBadge: document.getElementById('quantize-badge'),
+    sessionBadge: document.getElementById('session-badge'),
+    loadingIndicator: document.getElementById('loading-indicator'),
+    loadingTargetLabel: document.getElementById('loading-target-label'),
+    languageSelect: document.getElementById('language-select'),
+    quantizeToggle: document.getElementById('quantize-toggle'),
+    applyBtn: document.getElementById('apply-model-btn'),
+    nonEnglishWarning: document.getElementById('non-english-warning'),
+    modelPathLockedNotice: document.getElementById('model-path-locked-notice'),
+    sessionOnlyNotice: document.getElementById('session-only-notice'),
+    applyError: document.getElementById('apply-error'),
+    generateBtn: document.getElementById('generate-btn'),
+};
+
+let currentModelState = null;
+let pollTimer = null;
+let pollDeadline = 0;
+
+function populateLanguageOptions(languages) {
+    if (modelUI.languageSelect.options.length > 0) return;  // already populated
+    for (const lang of languages) {
+        const opt = document.createElement('option');
+        opt.value = lang;
+        opt.textContent = lang;
+        modelUI.languageSelect.appendChild(opt);
+    }
+}
+
+function setHidden(el, hidden) {
+    if (hidden) { el.setAttribute('hidden', ''); }
+    else        { el.removeAttribute('hidden'); }
+}
+
+// Backend reports `value: null` when the server was started without a
+// --language flag. Pocket-tts treats that as "english" internally, so we
+// surface the same string in the UI to keep the dropdown, label, and Apply
+// diff comparison consistent.
+function effectiveActiveValue(state) {
+    return state.active.value || 'english';
+}
+
+function updateUIForState(state) {
+    currentModelState = state;
+    populateLanguageOptions(state.available_languages);
+
+    const activeLang = effectiveActiveValue(state);
+
+    // Header labels
+    modelUI.activeLabel.textContent = activeLang;
+    setHidden(modelUI.quantizeBadge, !state.active.quantize);
+    setHidden(modelUI.sessionBadge, !state.differs_from_boot);
+
+    // Loading indicator
+    if (state.loading && state.loading_target) {
+        modelUI.loadingTargetLabel.textContent = `→ ${state.loading_target.value}`;
+        setHidden(modelUI.loadingIndicator, false);
+    } else {
+        setHidden(modelUI.loadingIndicator, true);
+    }
+
+    // Dropdown reflects active (not the pending target).
+    if (modelUI.languageSelect.value !== activeLang) {
+        modelUI.languageSelect.value = activeLang;
+    }
+    modelUI.quantizeToggle.checked = state.active.quantize;
+
+    // Lock state
+    const locked = state.model_path_locked;
+    modelUI.languageSelect.disabled = locked || state.loading;
+    modelUI.quantizeToggle.disabled = locked || state.loading;
+    setHidden(modelUI.modelPathLockedNotice, !locked);
+
+    // Warnings
+    const selectedLang = modelUI.languageSelect.value;
+    const isEnglishVariant = selectedLang && selectedLang.startsWith('english');
+    setHidden(modelUI.nonEnglishWarning, locked || isEnglishVariant);
+
+    // Session-only notice
+    setHidden(modelUI.sessionOnlyNotice, !state.differs_from_boot);
+
+    // Apply button
+    updateApplyButton();
+
+    // Error banner from last failed reload — also clear it once the backend
+    // reports no error (e.g. after a successful subsequent reload).
+    if (state.last_error) {
+        modelUI.applyError.textContent = state.last_error;
+        setHidden(modelUI.applyError, false);
+    } else {
+        modelUI.applyError.textContent = '';
+        setHidden(modelUI.applyError, true);
+    }
+
+    // Generate button disabled during load
+    modelUI.generateBtn.disabled = state.loading;
+    modelUI.generateBtn.title = state.loading ? 'Model is loading…' : '';
+}
+
+function updateApplyButton() {
+    if (!currentModelState) return;
+    const { active, model_path_locked, loading } = currentModelState;
+    const activeLang = effectiveActiveValue(currentModelState);
+    const targetLang = modelUI.languageSelect.value;
+    const targetQuantize = modelUI.quantizeToggle.checked;
+    const differs = targetLang !== activeLang || targetQuantize !== active.quantize;
+    modelUI.applyBtn.disabled = loading || model_path_locked || !differs;
+}
+
+async function fetchModelState() {
+    try {
+        const resp = await fetch('/v1/model');
+        if (!resp.ok) throw new Error(`GET /v1/model → ${resp.status}`);
+        const state = await resp.json();
+        updateUIForState(state);
+
+        if (!state.loading && pollTimer) {
+            clearInterval(pollTimer);
+            pollTimer = null;
+        }
+    } catch (err) {
+        console.warn('Failed to fetch model state:', err);
+    }
+}
+
+function startPolling() {
+    if (pollTimer) return;
+    pollDeadline = Date.now() + 120_000;  // 2 min timeout
+    pollTimer = setInterval(() => {
+        if (Date.now() > pollDeadline) {
+            clearInterval(pollTimer);
+            pollTimer = null;
+            modelUI.applyError.textContent =
+                'Model load timed out after 2 minutes. Check server logs.';
+            setHidden(modelUI.applyError, false);
+            return;
+        }
+        fetchModelState();
+    }, 1000);
+}
+
+async function applyModel() {
+    setHidden(modelUI.applyError, true);
+    modelUI.applyBtn.disabled = true;
+
+    try {
+        const resp = await fetch('/v1/model', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({
+                language: modelUI.languageSelect.value,
+                quantize: modelUI.quantizeToggle.checked,
+            }),
+        });
+        if (resp.status === 202) {
+            startPolling();
+            // Immediately refresh to show loading state.
+            fetchModelState();
+        } else {
+            const body = await resp.json();
+            modelUI.applyError.textContent =
+                body.error || `Server returned ${resp.status}`;
+            setHidden(modelUI.applyError, false);
+            // Revert dropdown to the normalized active value so we never
+            // leave the select on an empty string when the backend reports
+            // the default model with value=null.
+            if (currentModelState) {
+                modelUI.languageSelect.value =
+                    effectiveActiveValue(currentModelState);
+            }
+            updateApplyButton();
+        }
+    } catch (err) {
+        modelUI.applyError.textContent = `Apply failed: ${err.message}`;
+        setHidden(modelUI.applyError, false);
+        updateApplyButton();
+    }
+}
+
+modelUI.languageSelect.addEventListener('change', updateApplyButton);
+modelUI.quantizeToggle.addEventListener('change', updateApplyButton);
+modelUI.applyBtn.addEventListener('click', applyModel);
+
+// Kick off on page load.
+fetchModelState().then(() => {
+    if (currentModelState?.loading) startPolling();
+});

templates/index.html

@@ -29,9 +29,70 @@
 				/>
 				<h1>Pocket TTS</h1>
 				<p class="subtitle">Real-time local speech synthesis & voice cloning</p>
+				<p
+					class="version-strip"
+					data-server-version="{{ versions.server }}"
+					data-pocket-tts-version="{{ versions.pocket_tts }}"
+				>
+					Server v{{ versions.server }}
+					· pocket-tts v{{ versions.pocket_tts }}
+					· <a
+						href="https://github.com/teddybear082/pocket-tts-openai_streaming_server"
+						target="_blank"
+						rel="noopener"
+					>GitHub ↗</a>
+				</p>
 			</header>
 
 			<div class="content">
+				<details class="model-settings" id="model-settings">
+				    <summary class="model-settings-summary">
+				        <span class="disclosure-caret" aria-hidden="true">▸</span>
+				        <span class="summary-label">
+				            Model: <span id="active-model-label">loading…</span>
+				        </span>
+				        <span class="model-badge" id="quantize-badge" hidden>int8</span>
+				        <span class="model-badge session-badge" id="session-badge" hidden>session override</span>
+				        <span class="loading-indicator" id="loading-indicator" hidden>
+				            <span class="spinner-small"></span>
+				            <span id="loading-target-label"></span>
+				        </span>
+				    </summary>
+				    <div class="model-settings-body">
+				        <div class="control-group">
+				            <label for="language-select">Language</label>
+				            <select id="language-select">
+				                <!-- Populated by JS from /v1/model -->
+				            </select>
+				        </div>
+				        <div class="control-group">
+				            <label class="inline-label">
+				                <input type="checkbox" id="quantize-toggle" />
+				                Int8 quantization (lower memory, ~30% faster on CPU)
+				            </label>
+				        </div>
+				        <div id="non-english-warning" class="info-banner warning" hidden>
+				            Built-in voices are English only. For best results in other languages,
+				            upload a reference audio sample that matches the target language.
+				            Cloned voices are cached per-model, so switching back to a previously-used
+				            model is instant.
+				        </div>
+				        <div id="model-path-locked-notice" class="info-banner info" hidden>
+				            Server started with a custom model path. Restart without
+				            <code>--model-path</code> to enable language switching.
+				        </div>
+				        <button type="button" id="apply-model-btn" class="btn-secondary" disabled>
+				            Apply
+				        </button>
+				        <div id="session-only-notice" class="info-banner info" hidden>
+				            ⓘ Session-only change. On server restart, the model will revert to the
+				            startup configuration (<code>POCKET_TTS_LANGUAGE</code> env var or
+				            <code>--language</code> CLI flag).
+				        </div>
+				        <div id="apply-error" class="info-banner error" hidden></div>
+				    </div>
+				</details>
+
 				<div class="control-group">
 					<label for="text-input">Text Prompt</label>
 					<textarea

tests/conftest.py

@@ -0,0 +1,41 @@
+"""Shared pytest fixtures."""
+
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+
+@pytest.fixture
+def tmp_voices(tmp_path: Path) -> Path:
+    """Temporary voices directory (simulates user-provided audio)."""
+    d = tmp_path / 'voices'
+    d.mkdir()
+    return d
+
+
+@pytest.fixture
+def tmp_cache(tmp_path: Path) -> Path:
+    """Temporary voice cache directory (simulates writable cache volume)."""
+    d = tmp_path / 'voice_cache'
+    d.mkdir()
+    return d
+
+
+@pytest.fixture(autouse=True)
+def reset_tts_singleton():
+    """Reset the TTSService singleton between tests."""
+    import app.services.tts as tts_module
+
+    tts_module._tts_service = None
+    yield
+    tts_module._tts_service = None
+
+
+@pytest.fixture
+def mock_tts_model():
+    """Mock pocket-tts TTSModel for unit tests."""
+    model = MagicMock()
+    model.sample_rate = 24000
+    model.device = 'cpu'
+    return model

tests/test_config.py

@@ -0,0 +1,44 @@
+"""Tests for app.config constants."""
+
+from pathlib import Path
+
+from app.config import Config
+
+
+def test_supported_languages_contains_all_yaml_configs():
+    """All 12 language YAMLs from pocket-tts v2.0.0 must be listed."""
+    expected = {
+        'english',
+        'english_2026-01',
+        'english_2026-04',
+        'french_24l',
+        'german',
+        'german_24l',
+        'italian',
+        'italian_24l',
+        'portuguese',
+        'portuguese_24l',
+        'spanish',
+        'spanish_24l',
+    }
+    assert set(Config.SUPPORTED_LANGUAGES) == expected
+
+
+def test_legacy_aliases_canonicalize_english_variants():
+    """english and english_2026-01 both resolve to english_2026-04 for cache tagging."""
+    assert Config.LEGACY_MODEL_ALIASES == {
+        'english': 'english_2026-04',
+        'english_2026-01': 'english_2026-04',
+    }
+
+
+def test_alias_targets_are_supported_languages():
+    """Every alias target must itself be a valid supported language."""
+    for target in Config.LEGACY_MODEL_ALIASES.values():
+        assert target in Config.SUPPORTED_LANGUAGES
+
+
+def test_voice_cache_dir_defaults_to_base_path_subdir():
+    """Default cache dir sits under BASE_PATH."""
+    cache_dir = Path(Config.VOICE_CACHE_DIR)
+    assert cache_dir.name == 'voice_cache'

tests/test_routes.py

@@ -0,0 +1,196 @@
+"""Tests for /v1/model routes."""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from app import create_app
+
+
+@pytest.fixture
+def app():
+    return create_app()
+
+
+@pytest.fixture
+def client(app):
+    return app.test_client()
+
+
+@pytest.fixture
+def mock_tts_service():
+    """Install a mock TTSService for route tests."""
+    import app.services.tts as tts_module
+
+    service = MagicMock()
+    service.is_loaded = True
+    service.sample_rate = 24000
+    service.device = 'cpu'
+    service.voices_dir = None
+    service._active = {'source': 'language', 'value': 'english', 'quantize': False}
+    service._boot_active = {'source': 'language', 'value': 'english', 'quantize': False}
+    service._loading = False
+    service._last_reload_error = None
+    service._loading_target = None
+    service.validate_voice.return_value = (True, 'ok')
+    tts_module._tts_service = service
+    yield service
+    tts_module._tts_service = None
+
+
+def test_get_model_returns_active_state(client, mock_tts_service):
+    resp = client.get('/v1/model')
+    assert resp.status_code == 200
+    body = resp.get_json()
+    assert body['active'] == {'source': 'language', 'value': 'english', 'quantize': False}
+    assert body['boot'] == {'source': 'language', 'value': 'english', 'quantize': False}
+    assert body['differs_from_boot'] is False
+    assert body['loading'] is False
+    assert body['model_path_locked'] is False
+    assert 'english' in body['available_languages']
+    assert len(body['available_languages']) == 12
+    assert 'server_version' in body
+    assert 'pocket_tts_version' in body
+
+
+def test_get_model_reports_differs_from_boot(client, mock_tts_service):
+    mock_tts_service._active = {'source': 'language', 'value': 'german_24l', 'quantize': True}
+    resp = client.get('/v1/model')
+    assert resp.get_json()['differs_from_boot'] is True
+
+
+def test_get_model_reports_model_path_locked(client, mock_tts_service):
+    mock_tts_service._boot_active = {'source': 'model_path', 'value': '/x.yaml', 'quantize': False}
+    mock_tts_service._active = mock_tts_service._boot_active
+    resp = client.get('/v1/model')
+    assert resp.get_json()['model_path_locked'] is True
+
+
+def test_post_model_returns_202_and_starts_load(client, mock_tts_service):
+    resp = client.post('/v1/model', json={'language': 'german_24l', 'quantize': True})
+    assert resp.status_code == 202
+    body = resp.get_json()
+    assert body['loading_target'] == {'value': 'german_24l', 'quantize': True}
+    mock_tts_service.reload_model_async.assert_called_once_with(
+        language='german_24l',
+        quantize=True,
+    )
+
+
+def test_post_model_rejects_unknown_language(client, mock_tts_service):
+    resp = client.post('/v1/model', json={'language': 'klingon', 'quantize': False})
+    assert resp.status_code == 400
+    assert 'klingon' in resp.get_json()['error']
+
+
+def test_post_model_409_when_already_loading(client, mock_tts_service):
+    """Route relies on reload_model_async's atomic claim returning False
+    when a reload is already in progress, not on its own pre-check."""
+    mock_tts_service.reload_model_async.return_value = False
+    resp = client.post('/v1/model', json={'language': 'german_24l', 'quantize': False})
+    assert resp.status_code == 409
+
+
+def test_post_model_403_when_model_path_locked(client, mock_tts_service):
+    mock_tts_service._boot_active = {'source': 'model_path', 'value': '/x', 'quantize': False}
+    resp = client.post('/v1/model', json={'language': 'german_24l', 'quantize': False})
+    assert resp.status_code == 403
+
+
+def test_post_model_400_on_missing_language(client, mock_tts_service):
+    resp = client.post('/v1/model', json={'quantize': True})
+    assert resp.status_code == 400
+
+
+def test_post_model_400_on_empty_body(client, mock_tts_service):
+    resp = client.post('/v1/model', json={})
+    assert resp.status_code == 400
+
+
+def test_post_model_400_on_non_dict_body(client, mock_tts_service):
+    """A JSON value that isn't an object (e.g. a number, string, list) must be
+    rejected without raising AttributeError on .get()."""
+    resp = client.post('/v1/model', data='42', content_type='application/json')
+    assert resp.status_code == 400
+    assert 'object' in resp.get_json()['error'].lower()
+
+
+def test_speech_400_on_non_dict_body(client, mock_tts_service):
+    resp = client.post('/v1/audio/speech', data='"hello"', content_type='application/json')
+    assert resp.status_code == 400
+    assert 'object' in resp.get_json()['error'].lower()
+
+
+def test_post_model_400_on_non_bool_quantize(client, mock_tts_service):
+    """JSON booleans only — string 'false' would be truthy under bool() coercion."""
+    resp = client.post('/v1/model', json={'language': 'german_24l', 'quantize': 'false'})
+    assert resp.status_code == 400
+    assert 'boolean' in resp.get_json()['error'].lower()
+
+
+def test_post_model_accepts_omitted_quantize(client, mock_tts_service):
+    """Omitted quantize defaults to False without triggering the type check."""
+    resp = client.post('/v1/model', json={'language': 'german_24l'})
+    assert resp.status_code == 202
+    mock_tts_service.reload_model_async.assert_called_once_with(
+        language='german_24l', quantize=False
+    )
+
+
+def test_speech_returns_503_when_loading(client, mock_tts_service):
+    mock_tts_service._loading = True
+    resp = client.post('/v1/audio/speech', json={'input': 'hi', 'voice': 'alba'})
+    assert resp.status_code == 503
+    assert 'reloading' in resp.get_json()['error'].lower()
+
+
+def test_speech_does_not_500_when_resolve_raises_in_mismatch_path(client, mock_tts_service):
+    """If get_voice_state raises ValueError AND _resolve_voice_path itself
+    raises (e.g. SSRF protection on http://), the mismatch detection must
+    not propagate the second exception — it should fall through to a clean
+    400 with the original error message."""
+    mock_tts_service.validate_voice.return_value = (True, 'ok')
+    mock_tts_service.get_voice_state.side_effect = ValueError('Voice could not be loaded: nope')
+    mock_tts_service._resolve_voice_path.side_effect = ValueError('URL scheme not allowed')
+
+    resp = client.post(
+        '/v1/audio/speech', json={'input': 'hi', 'voice': 'http://evil.example/voice.wav'}
+    )
+    assert resp.status_code == 400
+    assert resp.get_json()['error'].startswith('Voice could not be loaded')
+
+
+def test_speech_voice_model_mismatch_returns_400_with_code(client, mock_tts_service, tmp_path):
+    """When the resolved voice is a legacy unlabeled .safetensors and pocket-tts
+    raises a shape-mismatch during load, the route surfaces a helpful error."""
+    # Simulate: validate_voice succeeds, get_voice_state raises.
+    legacy = tmp_path / 'emma.safetensors'
+    legacy.write_bytes(b'x')
+    mock_tts_service.validate_voice.return_value = (True, 'ok')
+    mock_tts_service._resolve_voice_path.return_value = str(legacy)
+    mock_tts_service.get_voice_state.side_effect = ValueError(
+        "Voice 'emma' could not be loaded: RuntimeError: size mismatch for layer.0.weight"
+    )
+    resp = client.post('/v1/audio/speech', json={'input': 'hi', 'voice': 'emma'})
+    assert resp.status_code == 400
+    body = resp.get_json()
+    assert body['error'] == 'voice_model_mismatch'
+    assert body['voice'] == 'emma'
+    assert body['active_model'] == 'english'
+
+
+def test_health_includes_active_model(client, mock_tts_service):
+    resp = client.get('/health')
+    body = resp.get_json()
+    assert body['active_model'] == {
+        'source': 'language',
+        'value': 'english',
+        'quantize': False,
+    }
+
+
+def test_home_passes_versions_to_template(client, mock_tts_service):
+    resp = client.get('/')
+    assert resp.status_code == 200
+    html = resp.data.decode()
+    assert 'data-server-version=' in html

tests/test_tts_service.py

@@ -0,0 +1,375 @@
+"""Tests for TTSService state and load_model."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from app.services.tts import TTSService
+
+
+@pytest.fixture
+def service():
+    return TTSService()
+
+
+def test_service_has_lock_and_flag_on_init(service):
+    import threading
+
+    # threading.Lock() returns a _thread.lock instance; check via acquire/release protocol
+    assert isinstance(service._lock, type(threading.Lock()))
+    assert service._loading is False
+    assert service._active is None
+    assert service._boot_active is None
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_load_model_with_language_populates_active(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='german_24l', quantize=True)
+
+    assert service._active == {
+        'source': 'language',
+        'value': 'german_24l',
+        'quantize': True,
+    }
+    MockModel.load_model.assert_called_once_with(language='german_24l', quantize=True)
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_boot_load_snapshots_active_to_boot_active(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+
+    assert service._boot_active == service._active
+    assert service._boot_active['value'] == 'english'
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_non_boot_load_does_not_mutate_boot_active(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+        boot_snapshot = dict(service._boot_active)
+
+        # Second load with _is_boot=False (reload flow).
+        service.load_model(language='german_24l', quantize=True, _is_boot=False)
+
+    assert service._boot_active == boot_snapshot
+    assert service._active['value'] == 'german_24l'
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_load_model_with_model_path_sets_source(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(model_path='/custom/path.yaml', quantize=False)
+
+    assert service._active['source'] == 'model_path'
+    assert service._active['value'] == '/custom/path.yaml'
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_load_model_default_has_default_source(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(quantize=False)
+
+    assert service._active['source'] == 'default'
+    assert service._active['value'] is None
+
+
+def test_service_initializes_cache_dir(tmp_path, monkeypatch):
+    cache = tmp_path / 'voice_cache'
+    monkeypatch.setattr('app.config.Config.VOICE_CACHE_DIR', str(cache))
+    service = TTSService()
+    # Lazy create on first use is fine — just verify the path is stored
+    assert service.cache_dir == cache
+
+
+def test_service_cache_dir_mkdir_on_first_save(tmp_path, monkeypatch):
+    cache = tmp_path / 'voice_cache'  # does not exist yet
+    monkeypatch.setattr('app.config.Config.VOICE_CACHE_DIR', str(cache))
+    service = TTSService()
+    service._ensure_cache_dir()
+    assert cache.is_dir()
+
+
+def test_service_cache_dir_read_only_is_tolerated(tmp_path, monkeypatch, caplog):
+    """If mkdir raises (read-only FS), log and disable caching."""
+    import os
+
+    ro_parent = tmp_path / 'ro'
+    ro_parent.mkdir()
+    os.chmod(ro_parent, 0o500)  # r-x, not writable
+    cache = ro_parent / 'voice_cache'
+    monkeypatch.setattr('app.config.Config.VOICE_CACHE_DIR', str(cache))
+    service = TTSService()
+    service._ensure_cache_dir()
+    assert service.cache_dir is None
+    os.chmod(ro_parent, 0o700)  # restore for cleanup
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_resolve_voice_path_uses_active_model(_ensure, tmp_path, monkeypatch, mock_tts_model):
+    voices = tmp_path / 'voices'
+    voices.mkdir()
+    cache = tmp_path / 'voice_cache'
+    cache.mkdir()
+    (cache / 'emma.german_24l.safetensors').write_bytes(b'x')
+    monkeypatch.setattr('app.config.Config.VOICE_CACHE_DIR', str(cache))
+
+    service = TTSService()
+    service.set_voices_dir(str(voices))
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='german_24l', quantize=False)
+
+    resolved = service._resolve_voice_path('emma')
+    assert resolved == str(cache / 'emma.german_24l.safetensors')
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_resolve_voice_path_accepts_filename_with_extension(
+    _ensure, tmp_path, monkeypatch, mock_tts_model
+):
+    """Backwards-compat: passing 'emma.wav' (with extension) should resolve to
+    the existing file, not get joined with another extension."""
+    voices = tmp_path / 'voices'
+    voices.mkdir()
+    cache = tmp_path / 'voice_cache'
+    cache.mkdir()
+    (voices / 'emma.wav').write_bytes(b'fake-audio')
+    monkeypatch.setattr('app.config.Config.VOICE_CACHE_DIR', str(cache))
+
+    service = TTSService()
+    service.set_voices_dir(str(voices))
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+
+    resolved = service._resolve_voice_path('emma.wav')
+    assert resolved == str(voices / 'emma.wav')
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_reload_model_swaps_and_clears_voice_cache(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+        service.voice_cache['stale'] = {'fake': 'state'}
+
+        new_model = MagicMock()
+        new_model.sample_rate = 24000
+        new_model.device = 'cpu'
+        MockModel.load_model.return_value = new_model
+        service.reload_model(language='german_24l', quantize=True)
+
+    assert service.model is new_model
+    assert service.voice_cache == {}
+    assert service._active['value'] == 'german_24l'
+    assert service._active['quantize'] is True
+    assert service._boot_active['value'] == 'english'  # unchanged
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_reload_model_rejects_if_boot_used_model_path(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(model_path='/custom/x.yaml', quantize=False)
+
+    with pytest.raises(RuntimeError, match='model_path'):
+        service.reload_model(language='german_24l', quantize=False)
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_reload_model_rejects_unknown_language(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+
+    with pytest.raises(ValueError, match='klingon'):
+        service.reload_model(language='klingon', quantize=False)
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_reload_model_rejects_if_already_loading(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+
+    service._loading = True
+    with pytest.raises(RuntimeError, match='already loading'):
+        service.reload_model(language='german_24l', quantize=False)
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_reload_model_async_returns_false_when_already_loading(_ensure, service, mock_tts_model):
+    """Async API uses an atomic check-and-set so concurrent callers can't both
+    win the claim. The loser gets False instead of an exception so the route
+    can map it directly to 409."""
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+
+    service._loading = True
+    started = service.reload_model_async(language='german_24l', quantize=False)
+    assert started is False
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_reload_model_async_validation_still_raises(_ensure, service, mock_tts_model):
+    """Validation errors are still raised synchronously so the route can
+    return 400/403 instead of 409 — only the in-progress check is silent."""
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+
+    with pytest.raises(ValueError, match='klingon'):
+        service.reload_model_async(language='klingon', quantize=False)
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_reload_model_restores_previous_on_failure(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+        original_model = service.model
+
+        MockModel.load_model.side_effect = RuntimeError('weights corrupted')
+        with pytest.raises(RuntimeError, match='weights corrupted'):
+            service.reload_model(language='german_24l', quantize=False)
+
+    assert service.model is original_model
+    assert service._active['value'] == 'english'
+    assert service._loading is False
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_generate_audio_raises_when_loading(_ensure, service, mock_tts_model):
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+    service._loading = True
+    with pytest.raises(RuntimeError, match='model reloading'):
+        service.generate_audio(voice_state={}, text='hi')
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_get_voice_state_saves_clone_to_cache(_ensure, tmp_path, monkeypatch, mock_tts_model):
+    voices = tmp_path / 'voices'
+    voices.mkdir()
+    cache = tmp_path / 'voice_cache'
+    (voices / 'emma.wav').write_bytes(b'fake-audio')
+    monkeypatch.setattr('app.config.Config.VOICE_CACHE_DIR', str(cache))
+
+    service = TTSService()
+    service.set_voices_dir(str(voices))
+    mock_tts_model.get_state_for_audio_prompt.return_value = {'fake': 'state'}
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+
+    with patch('app.services.tts.export_model_state') as mock_export:
+        state = service.get_voice_state('emma')
+
+    assert state == {'fake': 'state'}
+    mock_export.assert_called_once()
+    # Called with state and expected cache path
+    args = mock_export.call_args.args
+    assert args[0] == {'fake': 'state'}
+    assert str(args[1]).endswith('emma.english_2026-04.safetensors')
+    assert (cache).is_dir()
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_get_voice_state_regenerates_when_source_newer(
+    _ensure, tmp_path, monkeypatch, mock_tts_model
+):
+    import os
+    import time
+
+    voices = tmp_path / 'voices'
+    voices.mkdir()
+    cache = tmp_path / 'voice_cache'
+    cache.mkdir()
+    stale = cache / 'emma.english_2026-04.safetensors'
+    stale.write_bytes(b'old')
+    os.utime(stale, (time.time() - 100, time.time() - 100))
+    (voices / 'emma.wav').write_bytes(b'new-audio')  # mtime = now
+    monkeypatch.setattr('app.config.Config.VOICE_CACHE_DIR', str(cache))
+
+    service = TTSService()
+    service.set_voices_dir(str(voices))
+    mock_tts_model.get_state_for_audio_prompt.return_value = {'fresh': 'state'}
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+
+    with patch('app.services.tts.export_model_state') as mock_export:
+        state = service.get_voice_state('emma')
+
+    assert state == {'fresh': 'state'}
+    # Should have called get_state_for_audio_prompt with the .wav file, not the stale cache
+    call_arg = mock_tts_model.get_state_for_audio_prompt.call_args.args[0]
+    assert str(call_arg).endswith('emma.wav')
+    mock_export.assert_called_once()
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_get_voice_state_stem_with_dot_regenerates_correctly(
+    _ensure, tmp_path, monkeypatch, mock_tts_model
+):
+    """A voice stem containing dots (e.g. 'John.Doe') must be parsed via the
+    known_model_tags helper so the staleness check finds the right source
+    file. Naive split('.', 1)[0] would yield 'John' and miss 'John.Doe.wav'."""
+    import os
+    import time
+
+    voices = tmp_path / 'voices'
+    voices.mkdir()
+    cache = tmp_path / 'voice_cache'
+    cache.mkdir()
+    stale = cache / 'John.Doe.english_2026-04.safetensors'
+    stale.write_bytes(b'old')
+    os.utime(stale, (time.time() - 100, time.time() - 100))
+    (voices / 'John.Doe.wav').write_bytes(b'new-audio')
+    monkeypatch.setattr('app.config.Config.VOICE_CACHE_DIR', str(cache))
+
+    service = TTSService()
+    service.set_voices_dir(str(voices))
+    mock_tts_model.get_state_for_audio_prompt.return_value = {'fresh': 'state'}
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+
+    with patch('app.services.tts.export_model_state'):
+        service.get_voice_state('John.Doe')
+
+    call_arg = mock_tts_model.get_state_for_audio_prompt.call_args.args[0]
+    assert str(call_arg).endswith('John.Doe.wav')
+
+
+@patch('app.services.tts._ensure_pocket_tts')
+def test_list_voices_collapses_per_stem(_ensure, tmp_path, monkeypatch, mock_tts_model):
+    voices = tmp_path / 'voices'
+    voices.mkdir()
+    cache = tmp_path / 'voice_cache'
+    cache.mkdir()
+    (voices / 'emma.wav').write_bytes(b'a')
+    (voices / 'emma.safetensors').write_bytes(b'a')
+    (cache / 'emma.english_2026-04.safetensors').write_bytes(b'a')
+    (cache / 'emma.german_24l.safetensors').write_bytes(b'a')
+    (voices / 'morgan.mp3').write_bytes(b'a')
+    monkeypatch.setattr('app.config.Config.VOICE_CACHE_DIR', str(cache))
+
+    service = TTSService()
+    service.set_voices_dir(str(voices))
+    with patch('app.services.tts.TTSModel') as MockModel:
+        MockModel.load_model.return_value = mock_tts_model
+        service.load_model(language='english', quantize=False)
+
+    voices_list = service.list_voices()
+    custom_ids = [v['id'] for v in voices_list if v['type'] == 'custom']
+    assert custom_ids == ['emma', 'morgan']

tests/test_versions.py

@@ -0,0 +1,25 @@
+"""Tests for version helpers."""
+
+from unittest.mock import patch
+
+from app.services.versions import get_versions
+
+
+def test_get_versions_returns_both():
+    result = get_versions()
+    assert 'server' in result
+    assert 'pocket_tts' in result
+
+
+def test_get_versions_handles_missing_package():
+    """When importlib metadata is unavailable, server falls back to the
+    hardcoded `app.__version__` constant; pocket_tts has no such fallback
+    and reports 'unknown'."""
+    from importlib.metadata import PackageNotFoundError
+
+    from app import __version__ as server_fallback
+
+    get_versions.cache_clear()
+    with patch('app.services.versions.version', side_effect=PackageNotFoundError):
+        result = get_versions()
+    assert result == {'server': server_fallback, 'pocket_tts': 'unknown'}

tests/test_voice_cache.py

@@ -0,0 +1,212 @@
+"""Tests for voice cache filename parsing and resolution."""
+
+from app.services.voice_cache import (
+    active_model_tag,
+    cache_is_stale,
+    known_model_tags,
+    list_voice_stems,
+    parse_safetensors_name,
+    resolve_voice_path,
+)
+
+
+def test_active_model_tag_returns_raw_when_not_aliased():
+    assert active_model_tag('german_24l') == 'german_24l'
+
+
+def test_active_model_tag_canonicalizes_english_alias():
+    assert active_model_tag('english') == 'english_2026-04'
+
+
+def test_active_model_tag_canonicalizes_english_2026_01():
+    assert active_model_tag('english_2026-01') == 'english_2026-04'
+
+
+def test_known_model_tags_includes_all_supported_plus_alias_targets():
+    tags = known_model_tags()
+    assert 'english_2026-04' in tags
+    assert 'german_24l' in tags
+    assert 'french_24l' in tags
+    # Alias keys are also included so users can name files with them.
+    assert 'english' in tags
+
+
+def test_parse_safetensors_name_recognizes_tagged_file():
+    tags = known_model_tags()
+    stem, tag = parse_safetensors_name('Emma Watson.english_2026-04.safetensors', tags)
+    assert stem == 'Emma Watson'
+    assert tag == 'english_2026-04'
+
+
+def test_parse_safetensors_name_legacy_unlabeled():
+    tags = known_model_tags()
+    stem, tag = parse_safetensors_name('legacy.safetensors', tags)
+    assert stem == 'legacy'
+    assert tag is None
+
+
+def test_parse_safetensors_name_dot_in_stem_but_unknown_tag():
+    """A filename like 'my.voice.safetensors' has 'voice' as the final segment —
+    but 'voice' isn't a known tag, so we treat the whole thing as the stem."""
+    tags = known_model_tags()
+    stem, tag = parse_safetensors_name('my.voice.safetensors', tags)
+    assert stem == 'my.voice'
+    assert tag is None
+
+
+def test_resolve_voice_path_prefers_tagged_cache(tmp_voices, tmp_cache):
+    """Preference: cache_dir tagged > voices_dir tagged > raw audio > legacy."""
+    (tmp_voices / 'emma.wav').write_bytes(b'fake-audio')
+    (tmp_cache / 'emma.english_2026-04.safetensors').write_bytes(b'fake-st')
+
+    result = resolve_voice_path(
+        'emma',
+        active_model='english_2026-04',
+        voices_dir=tmp_voices,
+        cache_dir=tmp_cache,
+    )
+    assert result == tmp_cache / 'emma.english_2026-04.safetensors'
+
+
+def test_resolve_voice_path_falls_back_to_raw_audio(tmp_voices, tmp_cache):
+    (tmp_voices / 'emma.wav').write_bytes(b'fake-audio')
+    result = resolve_voice_path(
+        'emma',
+        active_model='english_2026-04',
+        voices_dir=tmp_voices,
+        cache_dir=tmp_cache,
+    )
+    assert result == tmp_voices / 'emma.wav'
+
+
+def test_resolve_voice_path_legacy_unlabeled(tmp_voices, tmp_cache):
+    (tmp_voices / 'emma.safetensors').write_bytes(b'fake-st')
+    result = resolve_voice_path(
+        'emma',
+        active_model='english_2026-04',
+        voices_dir=tmp_voices,
+        cache_dir=tmp_cache,
+    )
+    assert result == tmp_voices / 'emma.safetensors'
+
+
+def test_resolve_voice_path_passthrough_for_builtin_name(tmp_voices, tmp_cache):
+    """Built-in names (no matching file anywhere) pass through untouched —
+    pocket-tts handles them via HuggingFace."""
+    result = resolve_voice_path(
+        'alba',
+        active_model='english_2026-04',
+        voices_dir=tmp_voices,
+        cache_dir=tmp_cache,
+    )
+    assert result == 'alba'
+
+
+def test_resolve_voice_path_respects_alias(tmp_voices, tmp_cache):
+    """Asking for 'english' should find a cache tagged 'english_2026-04'."""
+    (tmp_cache / 'emma.english_2026-04.safetensors').write_bytes(b'fake-st')
+    result = resolve_voice_path(
+        'emma',
+        active_model='english',  # alias
+        voices_dir=tmp_voices,
+        cache_dir=tmp_cache,
+    )
+    assert result == tmp_cache / 'emma.english_2026-04.safetensors'
+
+
+def test_resolve_voice_path_finds_alias_tagged_file(tmp_voices, tmp_cache):
+    """Files tagged with the alias itself (e.g. emma.english.safetensors) should
+    resolve when canonical-tagged file is absent — supports caches written by
+    older versions or by external tools using the alias."""
+    (tmp_cache / 'emma.english.safetensors').write_bytes(b'fake-st')
+    result = resolve_voice_path(
+        'emma',
+        active_model='english',
+        voices_dir=tmp_voices,
+        cache_dir=tmp_cache,
+    )
+    assert result == tmp_cache / 'emma.english.safetensors'
+
+
+def test_resolve_voice_path_canonical_preferred_over_alias(tmp_voices, tmp_cache):
+    """When both canonical and alias-tagged files exist, prefer canonical."""
+    (tmp_cache / 'emma.english.safetensors').write_bytes(b'fake-st')
+    (tmp_cache / 'emma.english_2026-04.safetensors').write_bytes(b'fake-st')
+    result = resolve_voice_path(
+        'emma',
+        active_model='english',
+        voices_dir=tmp_voices,
+        cache_dir=tmp_cache,
+    )
+    assert result == tmp_cache / 'emma.english_2026-04.safetensors'
+
+
+def test_resolve_voice_path_voices_dir_tagged_cache(tmp_voices, tmp_cache):
+    """A tagged cache dropped directly into voices_dir (e.g. by WingmanAI) is honored."""
+    (tmp_voices / 'emma.german_24l.safetensors').write_bytes(b'fake-st')
+    result = resolve_voice_path(
+        'emma',
+        active_model='german_24l',
+        voices_dir=tmp_voices,
+        cache_dir=tmp_cache,
+    )
+    assert result == tmp_voices / 'emma.german_24l.safetensors'
+
+
+def test_list_voice_stems_collapses_duplicates(tmp_voices, tmp_cache):
+    (tmp_voices / 'emma.wav').write_bytes(b'a')
+    (tmp_voices / 'emma.safetensors').write_bytes(b'a')
+    (tmp_cache / 'emma.english_2026-04.safetensors').write_bytes(b'a')
+    (tmp_cache / 'emma.german_24l.safetensors').write_bytes(b'a')
+    (tmp_voices / 'morgan.mp3').write_bytes(b'a')
+
+    stems = list_voice_stems(voices_dir=tmp_voices, cache_dir=tmp_cache)
+    assert stems == ['emma', 'morgan']
+
+
+def test_list_voice_stems_empty(tmp_voices, tmp_cache):
+    assert list_voice_stems(voices_dir=tmp_voices, cache_dir=tmp_cache) == []
+
+
+def test_list_voice_stems_ignores_unknown_extensions(tmp_voices, tmp_cache):
+    (tmp_voices / 'notes.txt').write_bytes(b'a')
+    (tmp_voices / 'emma.wav').write_bytes(b'a')
+    stems = list_voice_stems(voices_dir=tmp_voices, cache_dir=tmp_cache)
+    assert stems == ['emma']
+
+
+def test_cache_is_stale_true_when_source_newer(tmp_voices, tmp_cache):
+    import os
+    import time
+
+    cache = tmp_cache / 'emma.english_2026-04.safetensors'
+    cache.write_bytes(b'old')
+    old_time = time.time() - 100
+    os.utime(cache, (old_time, old_time))
+
+    source = tmp_voices / 'emma.wav'
+    source.write_bytes(b'new')  # mtime = now
+
+    assert cache_is_stale(cache_path=cache, source_path=source) is True
+
+
+def test_cache_is_stale_false_when_cache_newer(tmp_voices, tmp_cache):
+    source = tmp_voices / 'emma.wav'
+    source.write_bytes(b'old')
+    import os
+    import time
+
+    old_time = time.time() - 100
+    os.utime(source, (old_time, old_time))
+
+    cache = tmp_cache / 'emma.english_2026-04.safetensors'
+    cache.write_bytes(b'new')
+
+    assert cache_is_stale(cache_path=cache, source_path=source) is False
+
+
+def test_cache_is_stale_false_when_source_missing(tmp_voices, tmp_cache):
+    cache = tmp_cache / 'emma.english_2026-04.safetensors'
+    cache.write_bytes(b'cached')
+    source = tmp_voices / 'emma.wav'  # does not exist
+    assert cache_is_stale(cache_path=cache, source_path=source) is False