fix(subtitles): enable "N words" and karaoke modes in PyQt

Three related fixes:

- make_subtitle_writer: accept word-count modes ("N words") in
  create_subtitle_writer. SubtitleMode("5 words") raised ValueError,
  which make_subtitle_writer swallowed and returned None, so PyQt never
  created or wrote the subtitle file when an "N words" mode was selected.
  Unknown modes now fall back to SubtitleMode.SENTENCE (writers only
  branch on SENTENCE_HIGHLIGHT). Regression test added.

- gui.py: refresh subtitle combo item availability after initial
  voice/profile selection. update_subtitle_options_availability() ran
  during initUI with selected_lang=None for a profile, taking the
  non-English branch and disabling Highlighting/N-words items; the fix-up
  never re-ran because setCurrentIndex on an already-current index emits
  no signal. Now called once more after the profile/voice language is
  resolved.

- AssWriter: stop discarding per-word karaoke timing. _add_karaoke_tags
  unconditionally replaced entry text with uniform {\\k100} tags,
  destroying the real per-word {\\kf} timings from
  _process_karaoke_highlighting. Only synthesize simplified tags when the
  text has no karaoke tags. Regression test added.

.gitattributes

@@ -0,0 +1,15 @@
+*.py text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.toml text eol=lf
+*.json text eol=lf
+*.txt text eol=lf
+*.html text eol=lf
+*.css text eol=lf
+*.js text eol=lf
+*.sh text eol=lf
+*.cfg text eol=lf
+*.ini text eol=lf
+*.svg text eol=lf
+*.j2 text eol=lf

.github/FUNDING.yml

@@ -1,6 +1,6 @@
 # These are supported funding model platforms
 
-github: [jborza, jeremiahsb, mohangk]
+github: [jborza, jeremiahsb, mohangk, k0sm0naft]
 patreon: # Replace with a single Patreon username
 open_collective: # Replace with a single Open Collective username
 ko_fi: # Replace with a single Ko-fi username

.github/workflows/test_pip.yml

@@ -1,7 +1,9 @@
-name: pip install
-run-name: pip install
-on: 
+name: CI
+run-name: CI
+
+on:
   push:
+    branches: [main]
     paths:
       - '**.py'
       - 'pyproject.toml'
@@ -11,23 +13,41 @@ on:
       - 'pyproject.toml'
       - '.github/workflows/**'
   workflow_dispatch:
+
 jobs:
-  install-and-run:
+  test:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, macos-14, windows-latest]
         python-version: ['3.12']
       fail-fast: false
-    continue-on-error: true
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
+
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install from repository
-        run: python -m pip install .
-      #- name: Run abogen
-      #  run: abogen
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.1
+        with:
+          enable-cache: true
+          prune-cache: false
+          cache-dependency-glob: pyproject.toml
+
+      - name: Install system dependencies (Ubuntu)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y libegl1
+
+      - name: Install dependencies
+        run: uv pip install --system .[dev]
+        env:
+          UV_LINK_MODE: copy
+
+      - name: Run tests
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: pytest tests/ -v --tb=short

.github/workflows/test_publish.yml

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

.gitignore

@@ -39,3 +39,7 @@ dist/
 test_assets/
 dev_notes/
 .claude/
+.coverage
+
+# CodeGraph index (local, machine-specific)
+.codegraph/

AGENTS.md

@@ -0,0 +1,82 @@
+# AGENTS.md — Segmentation & Subtitle System Contract
+
+This document is the source of truth for how text is split for **voice
+processing** (TTS engine segmentation) and **subtitle processing**, across
+languages, TTS engines, and subtitle modes. It was written after a bug where
+sentence modes "processed all text as a whole" (one merged engine segment →
+one giant subtitle). **Do not change this behavior without updating this
+table.**
+
+## Voice processing — split pattern passed to the TTS engine
+
+`get_split_pattern(language, mode)` in `abogen/domain/split_pattern.py` is the
+default; the spaCy pre-TTS path overrides it. Both UIs must stay in sync:
+`spacy_pre_tts_segmentation` (`abogen/domain/conversion_pipeline.py`, WebUI)
+and the inline branch in `abogen/pyqt/conversion.py` (~line 860, PyQt).
+
+| Subtitle mode | English (en-US/en-GB) | Non-English, spaCy ON | Non-English, spaCy OFF | CJK (ja/zh) |
+|---|---|---|---|---|
+| Disabled | `\n` | spaCy pre-split, engine `\n` | `\n+` | `(?<=[.!?؟。！？।])\s*\|\n+` |
+| Line | `\n` | spaCy pre-split, engine `\n` | `\n` | `(?<=[.!?؟。！？।])\s*\|\n+` |
+| Sentence | `\n` | spaCy pre-split, engine `\n` | `(?<=[.!?؟。！？।])\s+\|\n+` | `(?<=[.!?؟。！？।])\s*\|\n+` |
+| Sentence + Comma | `\n` | spaCy pre-split, engine `\n` | `(?<=[.!?,؟。！？،،、।])\s+\|\n+` (commas kept) | `(?<=[.!?,؟。！？،،、।])\s*\|\n+` |
+| Sentence + Highlighting | `\n+` | `\n+` | `\n+` | `\n+` |
+| N words ("5 words") | `\n` (→ Disabled) | `\n+` | `\n+` | Disabled CJK pattern |
+
+Rules baked into this table:
+
+- **English voice splitting is ALWAYS newline-only** for Disabled, Line,
+  Sentence, and Sentence + Comma. English sentence/comma boundaries are
+  produced ONLY at subtitle time (spaCy post-TTS / regex fallback). Never add
+  punctuation to the English engine pattern.
+- **Non-English + spaCy ON**: spaCy pre-segments the text (pre-TTS); the
+  engine pattern is `\n` for Sentence AND Sentence + Comma — **never commas**.
+  spaCy is skipped when the toggle is off, mode is Disabled/Line, or input is
+  a subtitle file.
+- **Non-English + spaCy OFF** (toggle off, spaCy failure, subtitle input): the
+  default pattern is used — Sentence + Comma KEEPS its commas here. This is
+  the intentional fallback, not a bug.
+- CJK: punctuation-based patterns for Disabled/Line (historical); spacing is
+  `\s*` (no spaces needed between CJK chars).
+- Engine-level extra chunking (applies after the pattern): kokoro English
+  re-chunks at ~510 phonemes; kokoro non-English at ~400 chars; supertonic
+  caps each part at 300 chars.
+
+## Subtitle processing — post-TTS, from tokens
+
+| Mode | Behavior |
+|---|---|
+| Disabled | no subtitles |
+| Line | one entry per TTS segment (line) |
+| Sentence | sentence boundaries: English → spaCy; others → regex on `[.!?…]` |
+| Sentence + Comma | sentence + comma boundaries at subtitle time (both languages) — commas never affect voice |
+| Sentence + Highlighting | karaoke `{\kf…}` per word, grouped by sentence |
+| N words | groups of N words by whitespace counting |
+
+Token granularity (timing quality): kokoro English emits **per-word tokens**
+with timestamps; kokoro non-English and supertonic emit **no tokens** → each
+engine segment becomes one FakeToken, split by regex with proportional timing
+when it contains multiple sentences.
+
+## Hard invariants (breaking these reintroduces the original bug)
+
+1. `Pipeline.__call__` (`abogen/tts_plugin/utils.py`) must yield ONE `Segment`
+   per engine segment (with tokens) — never merge segments back into the
+   whole text. `SynthesizedAudio.segments` carries the per-segment data;
+   engines expose it in `plugins/kokoro/engine.py` and
+   `plugins/supertonic/engine.py`.
+2. `tts_segments` (`abogen/domain/conversion_pipeline.py`) restores trailing
+   whitespace on segment-boundary tokens ONLY for real per-word tokens, never
+   for FakeToken fallbacks.
+3. `_to_language_enum` must return `lang_code` as-is when it is already a
+   `Language` enum (`str(Language.ES)` is `"Language.ES"`, which silently
+   resolved to EN_US and disabled spaCy pre-TTS for every language in WebUI).
+4. English must never use spaCy for PRE-TTS segmentation — only for subtitles.
+
+## Guarded by tests
+
+- `tests/test_split_pattern.py` — English newline-only; non-English sentence
+  patterns; CJK behavior.
+- `tests/test_domain_conversion_pipeline.py` — `tts_segments` / spaCy
+  segmentation helpers.
+- Full suite: `python -m pytest tests/ -q` (expect 1566+ passing).

README.md

@@ -721,7 +721,7 @@ This project is available under the MIT License - see the [LICENSE](https://gith
 [Kokoro](https://github.com/hexgrad/kokoro) is licensed under [Apache-2.0](https://github.com/hexgrad/kokoro/blob/main/LICENSE) which allows commercial use, modification, distribution, and private use.
 
 ## `Star History`
-[![Star History Chart](https://api.star-history.com/svg?repos=denizsafak/abogen&type=Date)](https://www.star-history.com/#denizsafak/abogen&Date)
+[![Star History Chart](https://star-history.dera.page/svg?repos=denizsafak/abogen&type=Date)](https://star-history.dera.page/#denizsafak/abogen&Date)
 
 > [!NOTE]
 > Abogen supports subtitle generation for all languages. However, word-level subtitle modes (e.g., "1 word", "2 words", "3 words", etc.) are only available for English because [Kokoro provides timestamp tokens only for English text](https://github.com/hexgrad/kokoro/blob/6d87f4ae7abc2d14dbc4b3ef2e5f19852e861ac2/kokoro/pipeline.py#L383). For non-English languages, Abogen uses a duration-based fallback that supports sentence-level and comma-based subtitle modes ("Line", "Sentence", "Sentence + Comma"). If you need word-level subtitles for other languages, please request that feature in the [Kokoro project](https://github.com/hexgrad/kokoro).

abogen/application/__init__.py

@@ -0,0 +1,8 @@
+"""Application layer for conversion flow unification.
+
+This package contains the application-level orchestration logic
+that bridges UI adapters (PyQt, WebUI) with domain functions.
+
+The main entry point is ConversionService.run() which coordinates
+planning, execution, and finalization of a conversion job.
+"""

abogen/application/chapter_selection.py

@@ -0,0 +1,62 @@
+"""Chapter selection helpers for the application layer.
+
+Builds chapter payloads with smart defaults (preselection based on
+supplement score) and character counts. Used by both WebUI and PyQt.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from abogen.domain.chapter_classification import (
+    ensure_at_least_one_chapter_enabled,
+    should_preselect_chapter,
+)
+from abogen.domain.text_utils import calculate_text_length
+
+
+def build_chapter_payload(
+    chapters: List[Any],
+    source_name: str = "",
+) -> List[Dict[str, Any]]:
+    """Build a chapter payload with preselection and character counts.
+
+    Args:
+        chapters: List of chapter-like objects with ``title`` and ``text`` attributes.
+        source_name: Fallback title for the placeholder chapter when *chapters* is empty.
+
+    Returns:
+        List of chapter dicts ready for ``PendingJob.chapters`` or ``ChapterChunkConfig``.
+    """
+    total = len(chapters)
+    payload: List[Dict[str, Any]] = []
+
+    for index, chapter in enumerate(chapters):
+        title = getattr(chapter, "title", "") or ""
+        text = getattr(chapter, "text", "") or ""
+        enabled = should_preselect_chapter(title, text, index, total)
+        payload.append(
+            {
+                "id": f"{index:04d}",
+                "index": index,
+                "title": title,
+                "text": text,
+                "characters": calculate_text_length(text),
+                "enabled": enabled,
+            }
+        )
+
+    if not payload:
+        payload.append(
+            {
+                "id": "0000",
+                "index": 0,
+                "title": source_name,
+                "text": "",
+                "characters": 0,
+                "enabled": True,
+            }
+        )
+
+    ensure_at_least_one_chapter_enabled(payload)
+    return payload

abogen/application/cleanup.py

@@ -0,0 +1,78 @@
+"""Application-layer cleanup — global resource disposal.
+
+Handles:
+- GPU/CUDA memory flush
+- TTS engine disposal (PluginManager)
+- UI-specific cleanup callbacks (registered by entry points)
+
+Called by shutdown.py at process exit and by run_conversion() per-conversion.
+"""
+
+from __future__ import annotations
+
+import gc
+import sys
+from typing import Callable
+
+_UI_CLEANUPS: list[Callable[[], None]] = []
+
+
+def flush_cuda() -> None:
+    """Run GC and release CUDA cache. Safe to call multiple times."""
+    gc.collect()
+    # Skip entirely if torch was never imported — importing it here just to
+    # check would add several seconds to shutdown with nothing to flush.
+    if "torch" not in sys.modules:
+        return
+    try:
+        torch = sys.modules["torch"]
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+            torch.cuda.ipc_collect()
+    except Exception:
+        pass
+
+
+def dispose_engines() -> None:
+    """Dispose all cached TTS engines via PluginManager."""
+    try:
+        from abogen.tts_plugin.plugin_manager import get_plugin_manager
+        get_plugin_manager().dispose_all()
+    except Exception:
+        pass
+
+
+def _clear_global_voice_cache() -> None:
+    """Reset the global voice download cache state."""
+    try:
+        from abogen.voice_cache import clear_voice_cache
+        clear_voice_cache()
+    except Exception:
+        pass
+
+
+def register_ui_cleanup(fn: Callable[[], None]) -> None:
+    """Register a UI-specific cleanup callback (e.g. preview threads, temp files)."""
+    _UI_CLEANUPS.append(fn)
+
+
+def cleanup() -> None:
+    """Run all application-level cleanups. Idempotent."""
+    dispose_engines()
+    flush_cuda()
+    _clear_global_voice_cache()
+
+    for fn in _UI_CLEANUPS:
+        try:
+            fn()
+        except Exception:
+            pass
+    _UI_CLEANUPS.clear()
+
+
+__all__ = [
+    "flush_cuda",
+    "dispose_engines",
+    "register_ui_cleanup",
+    "cleanup",
+]

abogen/application/conversion_config.py

@@ -0,0 +1,95 @@
+"""Feature config objects for ConversionRequest.
+
+Each config object groups parameters for a specific feature.
+If the object is None, the feature is disabled.
+
+This keeps ConversionRequest clean: no boolean flags for feature toggles,
+no scattered parameters across unrelated fields.
+
+Domain config types (PronunciationConfig, SubtitleConfig) live in
+domain/config_types.py — domain defines the contract, app fills them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from abogen.domain.config_types import CoverConfig, PronunciationConfig, SubtitleConfig
+from abogen.domain.enums import OutputFormat, SaveMode
+
+
+@dataclass(frozen=True)
+class WordSubstitutionConfig:
+    """Word substitution settings.
+
+    When present on ConversionRequest, word substitution is applied
+    to the source text before chapter parsing.
+    """
+    substitutions_list: str = ""
+    case_sensitive: bool = False
+    replace_caps: bool = False
+    replace_numerals: bool = False
+    fix_punctuation: bool = False
+
+
+@dataclass(frozen=True)
+class SubtitleInputConfig:
+    """Subtitle file input settings.
+
+    When present on ConversionRequest, the source is treated as a
+    subtitle file (.srt/.ass/.vtt) or timestamp text, and the
+    subtitle-to-audio pipeline is used instead of normal text conversion.
+    """
+    is_timestamp_text: bool = False
+
+
+@dataclass(frozen=True)
+class Epub3ExportConfig:
+    """EPUB3 export settings.
+
+    When present on ConversionRequest, an EPUB3 package with
+    synchronized audio narration is generated after conversion.
+    """
+    book_id: str = ""
+
+
+@dataclass(frozen=True)
+class ChapterChunkConfig:
+    """Chapter and chunk configuration.
+
+    Groups chapter overrides, chunk data, and speaker settings
+    used by the planner to build segments.
+    """
+    chapter_overrides: List[Dict[str, Any]] = field(default_factory=list)
+    chunks: List[Dict[str, Any]] = field(default_factory=list)
+    chunk_level: str = "paragraph"
+    speaker_mode: str = "single"
+    speakers: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        _VALID_CHUNK_LEVELS = ("paragraph", "sentence")
+        _VALID_SPEAKER_MODES = ("single", "multi")
+        if self.chunk_level not in _VALID_CHUNK_LEVELS:
+            raise ValueError(
+                f"chunk_level must be one of {_VALID_CHUNK_LEVELS}, got {self.chunk_level!r}"
+            )
+        if self.speaker_mode not in _VALID_SPEAKER_MODES:
+            raise ValueError(
+                f"speaker_mode must be one of {_VALID_SPEAKER_MODES}, got {self.speaker_mode!r}"
+            )
+
+
+@dataclass(frozen=True)
+class SaveConfig:
+    """Save/output settings.
+
+    Groups save mode, output folder, chapter splitting, and merge options.
+    """
+    mode: SaveMode = SaveMode.SAVE_NEXT_TO_INPUT
+    output_folder: Optional[Path] = None
+    save_chapters_separately: bool = False
+    merge_chapters_at_end: bool = True
+    separate_chapters_format: OutputFormat = OutputFormat.WAV
+    save_as_project: bool = False

abogen/application/conversion_executor.py

@@ -0,0 +1,660 @@
+"""Unified conversion executor.
+
+Takes a ConversionPlan and ports, executes the TTS conversion,
+and returns a ConversionResult. No UI imports allowed.
+
+This is Stage 6 of the conversion flow unification plan.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from contextlib import ExitStack
+from typing import Any, Callable, Dict, List, Optional, Set, Tuple
+
+from abogen.application.conversion_models import (
+    ConversionPlan,
+)
+from abogen.application.conversion_ports import (
+    AudioSink,
+    ConversionEvents,
+    PipelineProvider,
+    SubtitleWriter,
+    VoiceResolver,
+)
+from abogen.application.conversion_result import ConversionResult
+from abogen.domain.audio_sink import open_audio_sink
+from abogen.domain.conversion_engine import (
+    SegmentStats,
+    SynthParams,
+    process_and_write_subtitles,
+    synthesize_text,
+)
+from abogen.domain.enums import OutputFormat, SubtitleMode
+from abogen.domain.normalization import TTSContext
+from abogen.domain.chapter_titles import (
+    apply_chapter_text_transforms,
+    headings_equivalent as _headings_equivalent,
+)
+from abogen.domain.output_paths import sanitize_filename_for_chapter
+from abogen.infrastructure.subtitle_writer import make_subtitle_writer
+
+
+# ─── MarkerCollector ───
+
+
+class MarkerCollector:
+    """Observes execution events and accumulates chapter/chunk markers.
+
+    Separates marker collection from synthesis logic.
+    """
+
+    def __init__(self) -> None:
+        self._chapter_markers: List[Dict[str, Any]] = []
+        self._chunk_markers: List[Dict[str, Any]] = []
+        self._current_chapter_voices: Set[Tuple[str, str]] = set()
+        self._current_chapter_index: int = 0
+        self._current_chapter_title: str = ""
+        self._current_chapter_start: float = 0.0
+
+    def on_chapter_start(
+        self, index: int, title: str, start_time: float
+    ) -> None:
+        """Record chapter start."""
+        self._current_chapter_index = index
+        self._current_chapter_title = title
+        self._current_chapter_start = start_time
+        self._current_chapter_voices.clear()
+
+    def on_segment(
+        self,
+        provider: str,
+        voice: Any,
+        voice_spec: str,
+        speaker_id: str = "narrator",
+    ) -> None:
+        """Record a voice used in this chapter (for multi-speaker tracking)."""
+        self._current_chapter_voices.add((provider, voice_spec))
+
+    def on_chunk(
+        self,
+        chunk_id: str,
+        chapter_index: int,
+        chunk_index: int,
+        start: float,
+        end: float,
+        speaker_id: str,
+        provider: str,
+        voice_spec: str,
+        level: str,
+        characters: int,
+    ) -> None:
+        """Record a chunk marker."""
+        self._chunk_markers.append({
+            "id": chunk_id,
+            "chapter_index": chapter_index,
+            "chunk_index": chunk_index,
+            "start": start,
+            "end": end,
+            "speaker_id": speaker_id,
+            "voice": {"provider": provider, "voice": voice_spec},
+            "level": level,
+            "characters": characters,
+        })
+
+    def on_chapter_end(self, end_time: float) -> None:
+        """Record chapter end and build chapter marker."""
+        voices = [
+            {"provider": p, "voice": v}
+            for p, v in sorted(self._current_chapter_voices)
+        ]
+        self._chapter_markers.append({
+            "chapter_index": self._current_chapter_index,
+            "index": self._current_chapter_index + 1,
+            "title": self._current_chapter_title,
+            "start": self._current_chapter_start,
+            "end": end_time,
+            "voices": voices,
+        })
+
+    def on_outro(
+        self,
+        start_time: float,
+        end_time: float,
+        provider: str,
+        voice_spec: str,
+    ) -> None:
+        """Record outro chapter marker."""
+        self._chapter_markers.append({
+            "chapter_index": len(self._chapter_markers),
+            "index": len(self._chapter_markers) + 1,
+            "title": "Outro",
+            "start": start_time,
+            "end": end_time,
+            "voices": [{"provider": provider, "voice": voice_spec}],
+        })
+
+    @property
+    def chapter_markers(self) -> List[Dict[str, Any]]:
+        return self._chapter_markers
+
+    @property
+    def chunk_markers(self) -> List[Dict[str, Any]]:
+        return self._chunk_markers
+
+
+def execute_conversion(
+    plan: ConversionPlan,
+    events: ConversionEvents,
+    pipeline_provider: PipelineProvider,
+    voice_resolver: VoiceResolver,
+    tts_context: TTSContext,
+    *,
+    check_cancelled: Optional[Callable[[], None]] = None,
+) -> ConversionResult:
+    """Execute a conversion plan and return the result.
+
+    Args:
+        plan: The conversion plan from build_conversion_plan()
+        events: UI-specific callbacks (log, progress, check_cancelled)
+        pipeline_provider: Provides TTS backends
+        voice_resolver: Resolves voice specs into loaded voices
+        tts_context: Normalization context for text processing
+        check_cancelled: Optional cancellation checker (overrides events.check_cancelled)
+
+    Returns:
+        ConversionResult with paths and markers
+
+    Raises:
+        ConversionCancelled: If conversion is cancelled
+    """
+    request = plan.request
+    result = ConversionResult(metadata=plan.metadata)
+    collector = MarkerCollector()
+
+    logging.info(
+        "[executor] Starting: chapters=%d intro=%s outro=%s merge=%s",
+        len(plan.chapters),
+        bool(plan.intro and plan.intro.enabled),
+        bool(plan.outro and plan.outro.enabled),
+        request.save.merge_chapters_at_end,
+    )
+
+    # Determine cancellation checker
+    if check_cancelled is None:
+        check_cancelled = lambda: events.check_cancelled()
+
+    # Stats for progress tracking
+    total_characters = sum(
+        len(ch.body_text) for ch in plan.chapters
+    )
+    if plan.intro and plan.intro.enabled:
+        total_characters += len(plan.intro.text)
+    if plan.outro and plan.outro.enabled:
+        total_characters += len(plan.outro.text)
+
+    stats = SegmentStats(
+        processed_chars=0,
+        current_time=0.0,
+        etr_start_time=time.time(),
+        total_characters=total_characters,
+    )
+
+    # Compute subtitle flag once (used in every synthesize_text call)
+    use_spacy = request.subtitle.mode not in (SubtitleMode.DISABLED, SubtitleMode.LINE)
+
+    # Output paths
+    output_layout = plan.output_layout
+    if not output_layout:
+        raise ValueError("ConversionPlan must have an output_layout")
+
+    # Determine if merged output is needed
+    merge_chapters = request.save.merge_chapters_at_end or not request.save.save_chapters_separately
+    if request.output_format == OutputFormat.M4B:
+        merge_chapters = True
+
+    # Resolve voices
+    base_voice_spec = request.voice or "M1"
+    logging.info("[executor] Resolving base voice: spec=%s", base_voice_spec)
+    base_provider, base_voice_choice, base_speed, base_steps = _resolve_voice(
+        voice_resolver, base_voice_spec, request,
+        log_callback=lambda msg: events.log(msg, level="warning"),
+    )
+    logging.info("[executor] Base voice resolved: provider=%s voice=%s speed=%.2f", base_provider, base_voice_choice, base_speed)
+
+    # Use ExitStack for resource management
+    with ExitStack() as stack:
+        # Open merged audio sink
+        audio_sink: Optional[AudioSink] = None
+        audio_path = None
+        if merge_chapters:
+            audio_path = output_layout.audio_dir / f"{_base_name(request)}{request.output_format.dot_ext}"
+            meta = plan.metadata if plan.metadata else None
+            audio_sink = stack.enter_context(
+                open_audio_sink(
+                    audio_path,
+                    request.output_format,
+                    metadata=meta,
+                    cancel_check=check_cancelled,
+                )
+            )
+            result.audio_path = audio_path
+
+        # Open subtitle writer if needed
+        subtitle_writer: Optional[SubtitleWriter] = None
+        if request.subtitle.mode != SubtitleMode.DISABLED and audio_sink:
+            subtitle_writer = make_subtitle_writer(
+                audio_path,
+                request.subtitle,
+            )
+            if subtitle_writer:
+                subtitle_writer.open()
+                stack.callback(subtitle_writer.close)
+                result.subtitle_paths.append(subtitle_writer.path)
+
+        effective_subtitle_mode = request.subtitle.mode if subtitle_writer else SubtitleMode.DISABLED
+
+        synth = SynthParams(
+            tts_context=tts_context,
+            stats=stats,
+            check_cancel=check_cancelled,
+            on_progress=lambda pct, etr: events.progress(pct, etr),
+            audio_sink=audio_sink,
+            subtitle_mode=effective_subtitle_mode,
+            max_subtitle_words=request.subtitle.max_words,
+            language=request.language,
+            use_spacy_segmentation=use_spacy,
+        )
+
+        # Chapter directory
+        chapter_dir = None
+        if request.save.save_chapters_separately and len(plan.chapters) > 1:
+            chapter_dir = output_layout.audio_dir / "chapters"
+            chapter_dir.mkdir(parents=True, exist_ok=True)
+
+        # Process intro
+        intro_emitted = False
+        if plan.intro and plan.intro.enabled and merge_chapters:
+            events.log(f"Title intro: {plan.intro.text[:80]}")
+            intro_provider, intro_voice, intro_speed, intro_steps = _resolve_voice(
+                voice_resolver, plan.intro.voice_spec, request,
+                log_callback=lambda msg: events.log(msg, level="warning"),
+            )
+            intro_backend = pipeline_provider.get(intro_provider, request.language, request.use_gpu)
+            synthesize_text(
+                text=plan.intro.text,
+                params=synth,
+                backend=intro_backend,
+                voice=intro_voice,
+                speed=intro_speed or request.speed,
+                total_steps=intro_steps,
+                chapter_sink=None,
+                preview_callback=lambda text: events.log(f"  {text[:80]}"),
+            )
+            intro_emitted = True
+            events.log("Intro synthesized.")
+
+        # Chapter loop
+        for chapter_idx, chapter in enumerate(plan.chapters, 1):
+            check_cancelled()
+
+            chapter_display = f"Chapter {chapter_idx}/{len(plan.chapters)}: {chapter.title}"
+            events.log(f"Processing {chapter_display}")
+            logging.info("[executor] Chapter %d/%d: %s", chapter_idx, len(plan.chapters), chapter.title)
+
+            # Resolve chapter voice
+            chapter_provider, chapter_voice, chapter_speed, chapter_steps = _resolve_voice(
+                voice_resolver, chapter.voice_spec, request,
+                log_callback=lambda msg: events.log(msg, level="warning"),
+            )
+            logging.info("[executor] Chapter %d voice: provider=%s voice=%s speed=%.2f", chapter_idx, chapter_provider, chapter_voice, chapter_speed)
+            chapter_backend = pipeline_provider.get(chapter_provider, request.language, request.use_gpu)
+
+            # Record chapter start for markers
+            collector.on_chapter_start(chapter_idx - 1, chapter.title, stats.current_time)
+
+            # Per-chapter sink
+            chapter_sink: Optional[AudioSink] = None
+            chapter_path = None
+            if chapter_dir:
+                chapter_filename = sanitize_filename_for_chapter(chapter.title, chapter_idx)
+                chapter_path = chapter_dir / f"{chapter_filename}.{request.save.separate_chapters_format}"
+                chapter_sink = stack.enter_context(
+                    open_audio_sink(
+                        chapter_path,
+                        request.save.separate_chapters_format,
+                        cancel_check=check_cancelled,
+                    )
+                )
+                result.chapter_paths.append(chapter_path)
+
+            # Per-chapter subtitle writer
+            chapter_subtitle_writer: Optional[SubtitleWriter] = None
+            if chapter_dir and request.subtitle.mode != SubtitleMode.DISABLED and chapter_sink:
+                from abogen.infrastructure.subtitle_writer import resolve_subtitle_format
+
+                chapter_filename = sanitize_filename_for_chapter(chapter.title, chapter_idx)
+                subtitle_ext, _ = resolve_subtitle_format(
+                    request.subtitle
+                )
+                chapter_subtitle_path = chapter_dir / f"{chapter_filename}.{subtitle_ext}"
+                chapter_subtitle_writer = make_subtitle_writer(
+                    chapter_subtitle_path,
+                    request.subtitle,
+                )
+                if chapter_subtitle_writer:
+                    chapter_subtitle_writer.open()
+                    result.subtitle_paths.append(chapter_subtitle_writer.path)
+
+            # Intro delay before first chapter
+            if not intro_emitted and plan.intro and plan.intro.enabled:
+                # Intro will be emitted with first chapter
+                intro_provider, intro_voice, intro_speed, intro_steps = _resolve_voice(
+                    voice_resolver, plan.intro.voice_spec, request,
+                    log_callback=lambda msg: events.log(msg, level="warning"),
+                )
+                intro_backend = pipeline_provider.get(intro_provider, request.language, request.use_gpu)
+                synthesize_text(
+                    text=plan.intro.text,
+                    params=synth,
+                    backend=intro_backend,
+                    voice=intro_voice,
+                    speed=intro_speed or request.speed,
+                    total_steps=intro_steps,
+                    chapter_sink=chapter_sink,
+                    preview_callback=lambda text: events.log(f"  Intro: {text[:80]}"),
+                )
+                intro_emitted = True
+                if request.chapter_intro_delay > 0:
+                    _append_silence(
+                        request.chapter_intro_delay,
+                        chapter_sink=chapter_sink,
+                        audio_sink=audio_sink,
+                        stats=stats,
+                    )
+
+            # Process heading
+            heading_text = ""
+            if chapter.title:
+                heading_text = _format_heading(chapter.title, chapter_idx, request)
+                if heading_text:
+                    synthesize_text(
+                        text=heading_text,
+                        params=synth,
+                        backend=chapter_backend,
+                        voice=chapter_voice,
+                        speed=chapter_speed or request.speed,
+                        chapter_sink=chapter_sink,
+                        preview_callback=lambda text: events.log(f"  Title: {text[:80]}"),
+                    )
+                    if request.chapter_intro_delay > 0:
+                        _append_silence(
+                            request.chapter_intro_delay,
+                            chapter_sink=chapter_sink,
+                            audio_sink=audio_sink,
+                            stats=stats,
+                        )
+
+            # Heading dedup: check if first line of body matches heading
+            pending_heading_strip = False
+            if heading_text and chapter.body_text:
+                first_line = next(
+                    (line.strip() for line in chapter.body_text.splitlines() if line.strip()),
+                    "",
+                )
+                if first_line and _headings_equivalent(first_line, heading_text):
+                    pending_heading_strip = True
+
+            # Process body segments
+            for seg_idx, segment in enumerate(chapter.segments):
+                check_cancelled()
+
+                # Apply heading dedup to first segment (consume-once)
+                seg_text = segment.text
+                if pending_heading_strip and seg_text.strip():
+                    seg_text, heading_removed, _ = apply_chapter_text_transforms(
+                        seg_text,
+                        heading_text=heading_text,
+                        raw_title=chapter.title,
+                        strip_heading=True,
+                        normalize_caps=False,
+                    )
+                    if heading_removed:
+                        pending_heading_strip = False
+                    if not seg_text.strip():
+                        continue
+
+                # Resolve segment voice (may differ from chapter voice)
+                if segment.voice_spec != chapter.voice_spec:
+                    seg_provider, seg_voice, seg_speed, seg_steps = _resolve_voice(
+                        voice_resolver, segment.voice_spec, request,
+                        log_callback=lambda msg: events.log(msg, level="warning"),
+                    )
+                    seg_backend = pipeline_provider.get(seg_provider, request.language, request.use_gpu)
+                else:
+                    seg_provider = chapter_provider
+                    seg_voice = chapter_voice
+                    seg_speed = chapter_speed
+                    seg_steps = chapter_steps
+                    seg_backend = chapter_backend
+
+                # Track voice for chapter marker
+                collector.on_segment(seg_provider, seg_voice, segment.voice_spec)
+
+                # spaCy pre-TTS segmentation
+                from abogen.domain.conversion_pipeline import spacy_pre_tts_segmentation
+
+                is_subtitle_input = bool(
+                    request.subtitle_input
+                )
+                spacy_segments, active_split = spacy_pre_tts_segmentation(
+                    seg_text,
+                    request.language,
+                    request.subtitle.mode,
+                    is_subtitle_input=is_subtitle_input,
+                    use_spacy_segmentation=use_spacy,
+                    log_callback=lambda msg: events.log(msg),
+                )
+
+                seg_start_time = stats.current_time
+                accumulated_tokens: List[Dict[str, Any]] = []
+                for spacy_seg in spacy_segments:
+                    if not spacy_seg.strip():
+                        continue
+                    _, seg_tokens = synthesize_text(
+                        text=spacy_seg,
+                        params=synth,
+                        backend=seg_backend,
+                        voice=seg_voice,
+                        speed=seg_speed or request.speed,
+                        total_steps=seg_steps,
+                        chapter_sink=chapter_sink,
+                        preview_callback=lambda text: events.log(f"  {text[:80]}"),
+                        split_pattern_override=active_split,
+                    )
+                    accumulated_tokens.extend(seg_tokens)
+
+                # Process subtitles
+                if audio_sink and accumulated_tokens:
+                    if subtitle_writer:
+                        process_and_write_subtitles(
+                            accumulated_tokens,
+                            subtitle_writer,
+                            subtitle=request.subtitle,
+                            language=request.language,
+                            use_spacy_segmentation=use_spacy,
+                            fallback_end_time=stats.current_time,
+                        )
+                    if chapter_subtitle_writer:
+                        process_and_write_subtitles(
+                            accumulated_tokens,
+                            chapter_subtitle_writer,
+                            subtitle=request.subtitle,
+                            language=request.language,
+                            use_spacy_segmentation=use_spacy,
+                            fallback_end_time=stats.current_time,
+                        )
+
+                # Record chunk marker
+                if segment.source in ("chunk", "voice_marker"):
+                    collector.on_chunk(
+                        chunk_id=segment.chunk_id or "",
+                        chapter_index=chapter_idx - 1,
+                        chunk_index=segment.chunk_index or seg_idx,
+                        start=seg_start_time,
+                        end=stats.current_time,
+                        speaker_id=segment.speaker_id or "narrator",
+                        provider=seg_provider,
+                        voice_spec=segment.voice_spec,
+                        level=segment.level or (request.chapter_chunk.chunk_level if request.chapter_chunk else "paragraph"),
+                        characters=len(segment.text),
+                    )
+
+            # Silence between chapters
+            if chapter_idx < len(plan.chapters) and request.silence_between_chapters > 0:
+                _append_silence(
+                    request.silence_between_chapters,
+                    chapter_sink=chapter_sink,
+                    audio_sink=audio_sink,
+                    stats=stats,
+                )
+
+            # Close chapter sink
+            if chapter_sink:
+                chapter_sink.close()
+
+            # Close chapter subtitle writer
+            if chapter_subtitle_writer:
+                chapter_subtitle_writer.close()
+
+            # Record chapter end for markers
+            collector.on_chapter_end(stats.current_time)
+            logging.info("[executor] Chapter %d/%d done: time=%.1fs", chapter_idx, len(plan.chapters), stats.current_time)
+
+        logging.info("[executor] All chapters done: total=%.1fs", stats.current_time)
+
+        # Process outro
+        if plan.outro and plan.outro.enabled and merge_chapters:
+            events.log(f"Closing outro: {plan.outro.text[:80]}")
+            outro_provider, outro_voice, outro_speed, outro_steps = _resolve_voice(
+                voice_resolver, plan.outro.voice_spec, request,
+                log_callback=lambda msg: events.log(msg, level="warning"),
+            )
+            outro_backend = pipeline_provider.get(outro_provider, request.language, request.use_gpu)
+
+            # Silence before outro
+            if request.silence_between_chapters > 0:
+                _append_silence(
+                    request.silence_between_chapters,
+                    chapter_sink=None,
+                    audio_sink=audio_sink,
+                    stats=stats,
+                )
+
+            outro_start = stats.current_time
+            synthesize_text(
+                text=plan.outro.text,
+                params=synth,
+                backend=outro_backend,
+                voice=outro_voice,
+                speed=outro_speed or request.speed,
+                total_steps=outro_steps,
+                chapter_sink=None,
+                preview_callback=lambda text: events.log(f"  {text[:80]}"),
+            )
+            # Record outro marker
+            collector.on_outro(outro_start, stats.current_time, outro_provider, plan.outro.voice_spec)
+            events.log("Outro synthesized.")
+
+    # Set result metadata
+    result.chapter_markers = collector.chapter_markers
+    result.chunk_markers = collector.chunk_markers
+    result.total_chapters = len(plan.chapters)
+    result.total_segments = sum(len(ch.segments) for ch in plan.chapters)
+    result.total_characters = total_characters
+
+    if output_layout.project_root:
+        result.project_root = output_layout.project_root
+
+    return result
+
+
+# ─── Helpers ────────────────────────────────────────────────────────
+
+
+def _resolve_voice(
+    resolver: VoiceResolver,
+    voice_spec: str,
+    request: Any,
+    *,
+    log_callback: Optional[Callable[[str], None]] = None,
+) -> Tuple[str, Any, Optional[float], Optional[int]]:
+    """Resolve a voice spec and return (provider, voice, speed, steps)."""
+    try:
+        resolved = resolver.resolve(voice_spec)
+        return (
+            resolved.provider,
+            resolved.voice,
+            resolved.speed,
+            resolved.supertonic_steps,
+        )
+    except Exception as exc:
+        # Fallback to base voice
+        base_spec = request.voice or "M1"
+        if log_callback:
+            log_callback(
+                f"Voice '{voice_spec}' failed to resolve: {exc}. "
+                f"Falling back to '{base_spec}'."
+            )
+        try:
+            resolved = resolver.resolve(base_spec)
+        except Exception as fallback_exc:
+            raise RuntimeError(
+                f"Both voice '{voice_spec}' and fallback '{base_spec}' failed to resolve. "
+                f"Primary error: {exc}; Fallback error: {fallback_exc}"
+            ) from fallback_exc
+        return (
+            resolved.provider,
+            resolved.voice,
+            resolved.speed,
+            resolved.supertonic_steps,
+        )
+
+
+def _base_name(request: Any) -> str:
+    """Get base name for output file."""
+    from abogen.domain.output_paths import sanitize_output_stem
+
+    if request.original_filename:
+        return sanitize_output_stem(request.original_filename)
+    return "output"
+
+
+def _format_heading(title: str, index: int, request: Any) -> str:
+    """Format chapter heading for TTS."""
+    from abogen.domain.chapter_titles import format_spoken_chapter_title
+
+    if request.auto_prefix_chapter_titles:
+        return format_spoken_chapter_title(title, index, apply_prefix=True)
+    return title
+
+
+def _append_silence(
+    duration: float,
+    *,
+    chapter_sink: Optional[AudioSink],
+    audio_sink: Optional[AudioSink],
+    stats: SegmentStats,
+) -> None:
+    """Append silence to sinks."""
+    from abogen.domain.audio_buffer import create_silence
+
+    silence = create_silence(duration)
+    if silence.size == 0:
+        return
+    if chapter_sink:
+        chapter_sink.write(silence)
+    if audio_sink:
+        audio_sink.write(silence)
+        stats.current_time += duration

abogen/application/conversion_models.py

@@ -0,0 +1,97 @@
+"""Core models for conversion planning.
+
+These dataclasses represent the structured plan for a conversion job.
+They are UI-agnostic and describe WHAT to convert, not HOW to do it.
+
+The planning flow:
+    ConversionRequest -> ConversionPlan -> ConversionResult
+
+    ConversionPlan contains:
+    - ChapterPlan[]: chapters with their segments
+    - SegmentPlan[]: individual text segments with voice specs
+    - OutputLayout: where to write outputs
+    - IntroOutroSpec: optional intro/outro
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from abogen.application.conversion_request import ConversionRequest
+    from abogen.text_extractor import ExtractionResult
+
+
+@dataclass
+class SegmentPlan:
+    """A single text segment with its voice specification.
+
+    This is the unified model for:
+    - Regular chapter body text
+    - PyQt voice markers (<<VOICE:F1>>)
+    - WebUI chunks with per-chunk voice/speaker
+    - Intro/outro text
+    - Chapter headings
+    """
+
+    text: str
+    voice_spec: str
+    kind: str = "body"  # intro, heading, body, outro
+    speaker_id: str = "narrator"
+    chunk_id: Optional[str] = None
+    chunk_index: Optional[int] = None
+    level: Optional[str] = None  # chunk level (paragraph, sentence, etc.)
+    source: str = "chapter"  # chapter, voice_marker, chunk
+
+
+@dataclass
+class ChapterPlan:
+    """A chapter with its metadata and segments."""
+
+    index: int
+    title: str
+    original_title: str
+    body_text: str
+    segments: List[SegmentPlan]
+    voice_spec: str  # default voice for this chapter
+
+
+@dataclass
+class OutputLayout:
+    """Resolved output paths for a conversion job."""
+
+    parent_dir: Path
+    merged_path: Optional[Path] = None
+    chapter_dir: Optional[Path] = None
+    project_root: Optional[Path] = None
+    audio_dir: Optional[Path] = None
+    subtitle_dir: Optional[Path] = None
+    metadata_dir: Optional[Path] = None
+
+
+@dataclass
+class IntroOutroSpec:
+    """Intro/outro specification with resolved text and voice."""
+
+    enabled: bool = False
+    text: str = ""
+    voice_spec: str = ""
+    kind: str = "intro"  # intro or outro
+
+
+@dataclass
+class ConversionPlan:
+    """Complete plan for a conversion job.
+
+    This is the output of the planning phase and input to the executor.
+    """
+
+    request: ConversionRequest
+    metadata: Dict[str, Any]
+    chapters: List[ChapterPlan]
+    intro: Optional[IntroOutroSpec] = None
+    outro: Optional[IntroOutroSpec] = None
+    output_layout: Optional[OutputLayout] = None
+    extraction: Optional[ExtractionResult] = None

abogen/application/conversion_planner.py

@@ -0,0 +1,393 @@
+"""Unified conversion planner.
+
+Pure functions that take a ConversionRequest and produce a ConversionPlan.
+No side effects, no I/O — all complexity from both UIs in one place.
+
+This is Stage 2 of the conversion flow unification plan.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+from abogen.application.conversion_models import (
+    ChapterPlan,
+    ConversionPlan,
+    IntroOutroSpec,
+    SegmentPlan,
+)
+from abogen.application.conversion_request import ConversionRequest
+from abogen.application.output_layout_service import resolve_output_layout
+from abogen.domain.chapter_overrides import apply_chapter_overrides
+from abogen.domain.file_type import auto_select_relevant_chapters
+from abogen.domain.intro_outro import resolve_intro, resolve_outro
+from abogen.domain.metadata_extraction import extract_metadata_for_file
+from abogen.domain.metadata_merge import merge_metadata
+from abogen.domain.voice_markers import split_text_by_voice_markers
+
+
+def build_conversion_plan(request: ConversionRequest) -> ConversionPlan:
+    """Build a complete conversion plan from a request.
+
+    This is the single entry point that both UIs will call.
+    It handles all the planning logic that was previously duplicated
+    in both PyQt and WebUI conversion runners.
+
+    Args:
+        request: Normalized conversion request
+
+    Returns:
+        ConversionPlan with all chapters, segments, and output layout
+
+    Raises:
+        ValueError: If request is invalid (no source, no chapters, etc.)
+    """
+    # 1. Extract and validate source
+    source_text = _extract_source_text(request)
+    if not source_text or not source_text.strip():
+        raise ValueError("No text content to convert")
+
+    # 2. Extract metadata
+    metadata, extraction = _extract_metadata(request)
+
+    # 3. Parse chapters
+    raw_chapters = _parse_chapters(source_text, request)
+
+    # 4. Apply chapter selection/overrides
+    selected_chapters = _apply_selection(raw_chapters, request)
+
+    # 5. Build segments for each chapter
+    chapters = _build_chapters(selected_chapters, request)
+
+    # 6. Build intro/outro
+    intro, outro = _build_intro_outro(metadata, request)
+
+    # 7. Resolve output layout
+    output_layout = resolve_output_layout(request)
+
+    logging.info(
+        "[planner] Plan built: chapters=%d intro=%s outro=%s",
+        len(chapters),
+        bool(intro and intro.enabled),
+        bool(outro and outro.enabled),
+    )
+
+    return ConversionPlan(
+        request=request,
+        metadata=metadata,
+        chapters=chapters,
+        intro=intro,
+        outro=outro,
+        output_layout=output_layout,
+        extraction=extraction,
+    )
+
+
+def _extract_source_text(request: ConversionRequest) -> Optional[str]:
+    """Extract text from request source."""
+    from abogen.subtitle_utils import clean_text
+
+    if request.direct_text:
+        text = clean_text(request.direct_text)
+    elif request.source_path and request.source_path.exists():
+        encoding = "utf-8"
+        try:
+            with open(request.source_path, "r", encoding=encoding, errors="replace") as f:
+                text = f.read()
+        except Exception:
+            return None
+        text = clean_text(text)
+    else:
+        return None
+
+    # Apply word substitutions if configured
+    if request.word_substitution:
+        from abogen.word_substitution import apply_word_substitutions
+
+        ws = request.word_substitution
+        text = apply_word_substitutions(
+            text,
+            ws.substitutions_list,
+            ws.case_sensitive,
+            ws.replace_caps,
+            ws.replace_numerals,
+            ws.fix_punctuation,
+        )
+
+    return text
+
+
+def _extract_metadata(
+    request: ConversionRequest,
+) -> Tuple[Dict[str, Any], Optional[Any]]:
+    """Extract metadata from source file.
+
+    Returns (metadata, extraction) tuple.
+    """
+    if request.direct_text:
+        return dict(request.metadata_tags), None
+
+    if request.source_path and request.source_path.exists():
+        try:
+            extraction = extract_metadata_for_file(
+                str(request.source_path), is_direct_text=False
+            )
+            metadata = dict(extraction.metadata) if extraction.metadata else {}
+        except Exception:
+            extraction = None
+            metadata = {}
+        metadata = merge_metadata(metadata, request.metadata_tags)
+        return metadata, extraction
+
+    return dict(request.metadata_tags), None
+
+
+def _parse_chapters(
+    source_text: str, request: ConversionRequest
+) -> List[Tuple[str, str, str]]:
+    """Parse source text into raw chapters.
+
+    Returns list of (title, body_text, default_voice) tuples.
+    """
+    from abogen.domain.text_chapters import parse_chapters_from_text
+
+    # Text is already cleaned in _extract_source_text, so clean=False here
+    chapters = parse_chapters_from_text(source_text, default_title="text", clean=False)
+
+    # Default voice from request
+    default_voice = request.voice or "M1"
+
+    return [(title, text, default_voice) for title, text in chapters]
+
+
+def _apply_selection(
+    raw_chapters: List[Tuple[str, str, str]], request: ConversionRequest
+) -> List[Tuple[str, str, str]]:
+    """Apply chapter selection and overrides."""
+    from abogen.text_extractor import ExtractedChapter
+
+    # Convert to ExtractedChapter objects for auto_select_relevant_chapters
+    extracted = [
+        ExtractedChapter(title=title, text=text)
+        for title, text, _ in raw_chapters
+    ]
+
+    # If user specified chapters, apply overrides
+    chapter_chunk = request.chapter_chunk
+    if chapter_chunk and chapter_chunk.chapter_overrides:
+        selected, _, diagnostics = apply_chapter_overrides(extracted, chapter_chunk.chapter_overrides)
+        if selected:
+            # Map back to (title, text, voice) tuples
+            result = []
+            for ch in selected:
+                # Find matching original chapter to get voice
+                voice = request.voice or "M1"
+                for orig_title, orig_text, orig_voice in raw_chapters:
+                    if orig_title == ch.title:
+                        voice = orig_voice
+                        break
+                result.append((ch.title, ch.text or "", voice))
+            return result
+        # If no chapters selected, fall through to auto-selection
+
+    # Auto-select relevant chapters
+    from abogen.domain.file_type import infer_file_type
+
+    file_type = infer_file_type(request.source_path) if request.source_path else "text"
+    result = auto_select_relevant_chapters(extracted, file_type)
+    filtered = result.kept
+
+    if filtered:
+        # Map back to (title, text, voice) tuples
+        result = []
+        for ch in filtered:
+            voice = request.voice or "M1"
+            for orig_title, orig_text, orig_voice in raw_chapters:
+                if orig_title == ch.title:
+                    voice = orig_voice
+                    break
+            result.append((ch.title, ch.text or "", voice))
+        return result
+
+    # Fall back to all chapters
+    return raw_chapters
+
+
+def _build_chapters(
+    selected_chapters: List[Tuple[str, str, str]], request: ConversionRequest
+) -> List[ChapterPlan]:
+    """Build ChapterPlan with SegmentPlan for each chapter."""
+    from abogen.domain.chapter_titles import normalize_chapter_opening_caps
+
+    chapters = []
+
+    for idx, (title, body_text, default_voice) in enumerate(selected_chapters, 1):
+        # Apply caps normalization to body text if enabled
+        if request.normalize_chapter_opening_caps and body_text:
+            body_text, _ = normalize_chapter_opening_caps(body_text)
+
+        # Build segments for this chapter (idx is 1-based, chunks use 0-based)
+        segments = _build_segments(body_text, default_voice, request, chapter_index=idx - 1)
+
+        chapter = ChapterPlan(
+            index=idx,
+            title=title,
+            original_title=title,
+            body_text=body_text,
+            segments=segments,
+            voice_spec=default_voice,
+        )
+        chapters.append(chapter)
+
+    return chapters
+
+
+def _build_segments(
+    body_text: str, default_voice: str, request: ConversionRequest,
+    chapter_index: int = 0,
+) -> List[SegmentPlan]:
+    """Build SegmentPlan list for a chapter's body text.
+
+    Handles voice markers (PyQt) and chunks (WebUI).
+    """
+    segments = []
+
+    # Check for chunks (WebUI style)
+    chapter_chunk = request.chapter_chunk
+    if chapter_chunk and chapter_chunk.chunks:
+        # Group chunks by chapter index
+        from abogen.domain.chunk_utils import group_chunks_by_chapter
+
+        chunk_groups = group_chunks_by_chapter(chapter_chunk.chunks)
+        chunks_for_chapter = chunk_groups.get(chapter_index, [])
+
+        for chunk_idx, chunk in enumerate(chunks_for_chapter):
+            chunk_text = chunk.get("normalized_text") or chunk.get("text", "")
+            if not chunk_text or not chunk_text.strip():
+                continue
+
+            chunk_voice = _resolve_chunk_voice(chunk, default_voice, request)
+            speaker_id = chunk.get("speaker_id", "narrator")
+
+            segments.append(
+                SegmentPlan(
+                    text=chunk_text.strip(),
+                    voice_spec=chunk_voice,
+                    kind="body",
+                    speaker_id=speaker_id,
+                    chunk_id=chunk.get("id"),
+                    chunk_index=chunk.get("chunk_index", chunk_idx),
+                    level=chunk.get("level", chapter_chunk.chunk_level),
+                    source="chunk",
+                )
+            )
+        return segments
+
+    # Check for voice markers (PyQt style)
+    # Detect markers even if validation fails (voice names may not be loaded yet)
+    from abogen.domain.voice_markers import _VOICE_MARKER_SEARCH_PATTERN
+
+    has_voice_markers = bool(_VOICE_MARKER_SEARCH_PATTERN.search(body_text))
+    voice_segments, last_voice, valid_count, invalid_count = split_text_by_voice_markers(
+        body_text, default_voice
+    )
+
+    if has_voice_markers or (len(voice_segments) > 1):
+        # Voice markers were used
+        for voice_name, segment_text in voice_segments:
+            if not segment_text or not segment_text.strip():
+                continue
+            segments.append(
+                SegmentPlan(
+                    text=segment_text.strip(),
+                    voice_spec=voice_name,
+                    kind="body",
+                    source="voice_marker",
+                )
+            )
+        return segments
+
+    # No voice markers — single segment for entire body
+    if body_text and body_text.strip():
+        segments.append(
+            SegmentPlan(
+                text=body_text.strip(),
+                voice_spec=default_voice,
+                kind="body",
+                source="chapter",
+            )
+        )
+
+    return segments
+
+
+def _resolve_chunk_voice(
+    chunk: Dict[str, Any], default_voice: str, request: ConversionRequest
+) -> str:
+    """Resolve voice for a chunk."""
+    # Check for speaker-based voice
+    speaker_id = chunk.get("speaker_id", "narrator")
+    speakers = request.chapter_chunk.speakers if request.chapter_chunk else {}
+    if speaker_id and speaker_id != "narrator" and speakers:
+        speaker_config = speakers.get(speaker_id, {})
+        if isinstance(speaker_config, dict):
+            voice = speaker_config.get("voice")
+            if voice:
+                return voice
+
+    # Check for direct voice field
+    voice = chunk.get("voice")
+    if voice:
+        return voice
+
+    return default_voice
+
+
+def _build_intro_outro(
+    metadata: Dict[str, Any], request: ConversionRequest
+) -> Tuple[Optional[IntroOutroSpec], Optional[IntroOutroSpec]]:
+    """Build intro and outro specs."""
+    intro_spec = None
+    outro_spec = None
+
+    # Intro
+    if request.read_title_intro:
+        resolved = resolve_intro(
+            metadata,
+            request.original_filename,
+            True,
+            request.voice or "M1",
+            request.voice or "M1",
+            [],
+        )
+        if resolved.enabled:
+            intro_spec = IntroOutroSpec(
+                enabled=True,
+                text=resolved.text,
+                voice_spec=resolved.voice_spec,
+                kind="intro",
+            )
+
+    # Outro
+    if request.read_closing_outro:
+        resolved = resolve_outro(
+            metadata,
+            request.original_filename,
+            True,
+            request.voice or "M1",
+            request.voice or "M1",
+            [],
+        )
+        if resolved.enabled:
+            outro_spec = IntroOutroSpec(
+                enabled=True,
+                text=resolved.text,
+                voice_spec=resolved.voice_spec,
+                kind="outro",
+            )
+
+    return intro_spec, outro_spec
+
+
+# Output layout resolution is now in application/output_layout_service.py

abogen/application/conversion_ports.py

@@ -0,0 +1,112 @@
+"""Ports / interfaces for the conversion service.
+
+These protocols define how the conversion service communicates with
+the outside world (UI, TTS backends, voice resolvers).
+
+The service ONLY depends on these interfaces, never on concrete
+implementations (PyQt signals, Flask Job, etc.).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+class ConversionCancelled(Exception):
+    """Raised when conversion is cancelled by user."""
+    pass
+
+
+class ConversionEvents(Protocol):
+    """UI-specific actions the conversion service delegates back to the caller.
+
+    Implementations:
+    - PyQt: emits signals (log_updated, progress_updated, etc.)
+    - WebUI: updates Job attributes (job.add_log, job.progress, etc.)
+    """
+
+    def log(self, message: str, level: str = "info") -> None:
+        """Log a message to the UI."""
+        ...
+
+    def progress(self, processed: int, total: int, etr: str) -> None:
+        """Update progress display."""
+        ...
+
+    def check_cancelled(self) -> None:
+        """Check if conversion was cancelled.
+
+        Should raise ConversionCancelled (or UI-specific exception)
+        if cancellation is requested. Normal return means "continue".
+        """
+        ...
+
+
+class PipelineProvider(Protocol):
+    """Provides access to TTS backends (Kokoro, SuperTonic, etc.).
+
+    Implementations:
+    - PyQt: wraps self.backend (single pipeline)
+    - WebUI: wraps PipelinePool (multi-provider)
+    """
+
+    def get(self, provider: str, language: str, use_gpu: bool) -> Any:
+        """Get a TTS backend instance."""
+        ...
+
+    def dispose_all(self) -> None:
+        """Dispose all backend resources."""
+        ...
+
+
+@dataclass
+class ResolvedVoice:
+    """A resolved voice ready for TTS synthesis."""
+
+    provider: str
+    resolved_spec: str
+    voice: Any  # loaded voice tensor or name
+    speed: float
+    supertonic_steps: int
+
+
+class VoiceResolver(Protocol):
+    """Resolves voice specs into loaded voice objects.
+
+    Implementations:
+    - PyQt: wraps load_voice_cached + VoiceCache
+    - WebUI: wraps resolve_voice_choice + PipelinePool + VoiceCache
+    """
+
+    def resolve(self, voice_spec: str) -> ResolvedVoice:
+        """Resolve a voice spec into a loaded voice."""
+        ...
+
+
+class SubtitleWriter(Protocol):
+    """Writes subtitle entries to a file."""
+
+    def open(self) -> None:
+        """Open the subtitle file for writing."""
+        ...
+
+    def write_entry(self, start: float, end: float, text: str) -> None:
+        """Write a single subtitle entry."""
+        ...
+
+    def close(self) -> None:
+        """Close the subtitle file."""
+        ...
+
+
+class AudioSink(Protocol):
+    """Writes audio data to a file."""
+
+    def write(self, audio: Any) -> None:
+        """Write audio samples to the sink."""
+        ...
+
+    def close(self) -> None:
+        """Close the audio file."""
+        ...

abogen/application/conversion_request.py

@@ -0,0 +1,155 @@
+"""ConversionRequest — normalized input for a conversion job.
+
+This is NOT a WebUI Job and NOT a PyQt ConversionThread state.
+It describes the TASK, not the UI.
+
+UI adapters are responsible for converting their respective state
+into a ConversionRequest before calling ConversionService.run().
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from abogen.application.conversion_config import (
+    ChapterChunkConfig,
+    CoverConfig,
+    Epub3ExportConfig,
+    PronunciationConfig,
+    SaveConfig,
+    SubtitleConfig,
+    SubtitleInputConfig,
+    WordSubstitutionConfig,
+)
+from abogen.domain.enums import Language, OutputFormat
+
+
+class ConversionRequestError(ValueError):
+    """Raised when ConversionRequest has invalid field values."""
+
+
+# Numeric field constraints: attr -> (min, max)
+_NUMERIC_CONSTRAINTS: dict[str, tuple[float, float | None]] = {
+    "speed": (0.5, 3.0),
+    "supertonic_total_steps": (2, 15),
+    "silence_between_chapters": (0.0, None),
+    "chapter_intro_delay": (0.0, None),
+}
+
+
+@dataclass
+class ConversionRequest:
+    """Normalized request for a conversion job.
+
+    Only contains fields that describe the conversion task itself.
+    UI-only fields (display, logging, user prompts) stay in adapters.
+
+    Feature toggles use config objects (None = disabled):
+    - word_substitution, subtitle_input, chapter_chunk, epub3_export
+    - pronunciation (raw data, compiled by app layer)
+    - subtitle, save, cover (grouped parameters)
+
+    Validation runs on creation via __post_init__:
+    - None values → replaced with field default (from declaration)
+    - Numeric fields → clamped to valid range
+    """
+
+    # --- Source ---
+    source_path: Optional[Path] = None
+    direct_text: Optional[str] = None
+    original_filename: str = ""
+
+    # --- TTS Settings ---
+    language: Language = Language.EN_US
+    tts_provider: str = "kokoro"
+    voice: str = "M1"
+    voice_profile: Optional[str] = None
+    speed: float = 1.0
+    use_gpu: bool = True
+    supertonic_total_steps: int = 5
+
+    # --- Output Format ---
+    output_format: OutputFormat = OutputFormat.WAV
+
+    # --- Timing ---
+    silence_between_chapters: float = 2.0
+    chapter_intro_delay: float = 0.0
+
+    # --- Content Processing ---
+    replace_single_newlines: bool = False
+    read_title_intro: bool = False
+    read_closing_outro: bool = True
+    auto_prefix_chapter_titles: bool = True
+    normalize_chapter_opening_caps: bool = False
+
+    # --- Metadata ---
+    metadata_tags: Dict[str, Any] = field(default_factory=dict)
+
+    # --- Grouped configs ---
+    subtitle: SubtitleConfig = field(default_factory=SubtitleConfig)
+    save: SaveConfig = field(default_factory=SaveConfig)
+    cover: CoverConfig = field(default_factory=CoverConfig)
+    pronunciation: PronunciationConfig = field(default_factory=PronunciationConfig)
+
+    # --- Feature configs (None = disabled) ---
+    epub3_export: Optional[Epub3ExportConfig] = None
+    word_substitution: Optional[WordSubstitutionConfig] = None
+    subtitle_input: Optional[SubtitleInputConfig] = None
+    chapter_chunk: Optional[ChapterChunkConfig] = None
+
+    def __post_init__(self) -> None:
+        """Resolve None → default, then validate and clamp."""
+        _apply_none_defaults(self)
+        if not self.tts_provider:
+            self.tts_provider = "kokoro"
+        _coerce_enums(self)
+        _clamp_numerics(self)
+
+
+def _apply_none_defaults(obj: ConversionRequest) -> None:
+    """Replace None values with field defaults from dataclass declaration."""
+    for f in dataclasses.fields(obj):
+        if getattr(obj, f.name) is not None:
+            continue
+        if f.default is not dataclasses.MISSING:
+            setattr(obj, f.name, f.default)
+        elif f.default_factory is not dataclasses.MISSING:
+            setattr(obj, f.name, f.default_factory())
+
+
+# Enum fields that accept string coercion: attr -> (enum_class, fallback)
+_ENUM_COERCIONS: dict[str, tuple[type, Any]] = {
+    "language": (Language, Language.EN_US),
+    "output_format": (OutputFormat, OutputFormat.WAV),
+}
+
+
+def _coerce_enums(obj: ConversionRequest) -> None:
+    """Coerce string values to their expected enum types."""
+    for attr, (enum_cls, fallback) in _ENUM_COERCIONS.items():
+        val = getattr(obj, attr)
+        if isinstance(val, enum_cls):
+            continue
+        try:
+            setattr(obj, attr, enum_cls.from_str(str(val)))
+        except (ValueError, AttributeError):
+            setattr(obj, attr, fallback)
+
+
+def _clamp_numerics(obj: ConversionRequest) -> None:
+    """Clamp numeric fields to valid ranges."""
+    for attr, (min_v, max_v) in _NUMERIC_CONSTRAINTS.items():
+        val = getattr(obj, attr)
+        if val is None:
+            continue
+        if not isinstance(val, (int, float)):
+            raise ConversionRequestError(
+                f"{attr} must be a number, got {type(val).__name__}"
+            )
+        clamped = max(min_v, float(val))
+        if max_v is not None:
+            clamped = min(max_v, clamped)
+        setattr(obj, attr, clamped)

abogen/application/conversion_result.py

@@ -0,0 +1,50 @@
+"""ConversionResult — output of a successful conversion.
+
+Returned by ConversionService.run() after all synthesis and finalization.
+UI adapters consume this to update their respective state (Job, signals, etc.).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ConversionResult:
+    """Output of a successful conversion job."""
+
+    # --- Primary outputs ---
+    audio_path: Optional[Path] = None
+    subtitle_paths: List[Path] = field(default_factory=list)
+    chapter_paths: List[Path] = field(default_factory=list)
+
+    # --- Markers (for metadata/audiobookshelf) ---
+    chapter_markers: List[Dict[str, Any]] = field(default_factory=list)
+    chunk_markers: List[Dict[str, Any]] = field(default_factory=list)
+
+    # --- Metadata ---
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    # --- Artifacts ---
+    artifacts: Dict[str, Path] = field(default_factory=dict)
+    project_root: Optional[Path] = None
+    epub_path: Optional[Path] = None
+
+    # --- Stats ---
+    total_chapters: int = 0
+    total_segments: int = 0
+    total_characters: int = 0
+
+    # --- Override usage tracking ---
+    usage_counter: Dict[str, int] = field(default_factory=dict)
+
+
+@dataclass
+class ConversionError:
+    """Error information when conversion fails."""
+
+    message: str
+    details: Optional[str] = None
+    is_cancelled: bool = False

abogen/application/conversion_service.py

@@ -0,0 +1,250 @@
+"""ConversionService — main orchestrator for the conversion flow.
+
+Ties together planner, executor, and finalizers into a single entry point.
+Both UIs (PyQt, WebUI) call ConversionService.run() to execute a conversion.
+
+Responsibilities:
+- Prepare TTSContext (normalization settings, pronunciation rules)
+- Build ConversionPlan via planner
+- Execute conversion via executor
+- Handle lifecycle (cleanup, error handling)
+- Return ConversionResult
+
+The service NEVER imports from PyQt or WebUI.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from typing import Any, Dict
+
+from abogen.application.conversion_executor import execute_conversion
+from abogen.application.conversion_models import ConversionPlan
+from abogen.application.conversion_planner import build_conversion_plan
+from abogen.application.conversion_ports import ConversionEvents
+from abogen.application.conversion_request import ConversionRequest
+from abogen.application.conversion_result import ConversionResult
+from abogen.domain.normalization import build_tts_context
+
+
+def run_conversion(
+    request: ConversionRequest,
+    events: ConversionEvents,
+) -> ConversionResult:
+    """Execute a conversion request and return the result.
+
+    This is the single entry point for both UIs. It orchestrates:
+    1. Voice infrastructure setup (pool, cache, resolver)
+    2. TTS context preparation
+    3. Conversion planning
+    4. Conversion execution
+    5. Resource cleanup
+
+    Args:
+        request: Normalized conversion request
+        events: UI-specific callbacks (log, progress, check_cancelled)
+
+    Returns:
+        ConversionResult with paths and markers
+
+    Raises:
+        ConversionCancelled: If conversion was cancelled
+        ValueError: If request is invalid
+        Exception: On TTS or I/O errors
+    """
+    from abogen.domain.pipeline_factory import PipelinePool
+    from abogen.domain.voice_loader import VoiceCache
+
+    pool = PipelinePool()
+    voice_cache = VoiceCache()
+
+    try:
+        # Stage 0: Create voice resolver
+        events.log("Preparing conversion pipeline")
+        logging.info(
+            "[app] run_conversion: provider=%s language=%s voice=%s speed=%.2f",
+            request.tts_provider, request.language, request.voice, request.speed,
+        )
+        resolver = _create_voice_resolver(request, pool, voice_cache)
+
+        # Stage 1: Prepare TTS context
+        usage_counter: Dict[str, int] = defaultdict(int)
+        tts_context = build_tts_context(
+            language=request.language,
+            subtitle=request.subtitle,
+            pronunciation=request.pronunciation,
+            usage_counter=usage_counter,
+            log_callback=lambda level, msg: events.log(msg, level=level),
+        )
+
+        # Stage 2: Build conversion plan
+        events.log("Building conversion plan")
+        plan = build_conversion_plan(request)
+
+        # Stage 3: Execute conversion
+        events.log("Starting conversion")
+        result = execute_conversion(
+            plan=plan,
+            events=events,
+            pipeline_provider=pool,
+            voice_resolver=resolver,
+            tts_context=tts_context,
+        )
+
+        # Propagate usage counter to result
+        result.usage_counter = dict(usage_counter)
+
+        # Stage 4: Finalize (m4b metadata embedding, EPUB3 generation)
+        _finalize(request, result, plan, events)
+
+        events.log("Conversion complete")
+        logging.info("[app] run_conversion completed successfully")
+        return result
+
+    except Exception as e:
+        events.log(f"Conversion failed: {e}", level="error")
+        logging.exception("[app] run_conversion failed: %s", e)
+        raise
+    finally:
+        pool.dispose_all()
+        voice_cache.clear()
+        from abogen.application.cleanup import flush_cuda
+        flush_cuda()
+
+
+def _create_voice_resolver(
+    request: ConversionRequest,
+    pool: Any,
+    cache: Any,
+) -> Any:
+    """Create AppVoiceResolver with loaded profiles.
+
+    Loads voice profiles from disk, normalizes them, and creates
+    an AppVoiceResolver that can resolve voice specs into loaded voices.
+    """
+    from abogen.application.voice_resolver import AppVoiceResolver
+    from abogen.voice_profiles import load_profiles, normalize_profile_entry
+
+    try:
+        profiles = load_profiles()
+    except Exception:
+        profiles = {}
+
+    normalized_profiles: Dict[str, Dict[str, Any]] = {}
+    for name, entry in (profiles or {}).items():
+        normalized = normalize_profile_entry(entry)
+        if normalized:
+            normalized_profiles[str(name)] = normalized
+
+    return AppVoiceResolver(request, normalized_profiles, pool, cache)
+
+
+def _finalize(
+    request: ConversionRequest,
+    result: ConversionResult,
+    plan: ConversionPlan,
+    events: ConversionEvents,
+) -> None:
+    """Post-conversion finalization (m4b metadata embedding, EPUB3 generation, etc.)."""
+    from abogen.domain.enums import OutputFormat
+
+    # m4b metadata embedding
+    if (
+        result.audio_path
+        and request.output_format == OutputFormat.M4B
+    ):
+
+        from abogen.infrastructure.exporters import ExportService
+
+        export_svc = ExportService()
+
+        try:
+            export_svc.embed_m4b_metadata(
+                audio_path=result.audio_path,
+                metadata=result.metadata or {},
+                chapters=result.chapter_markers or [],
+                cover=request.cover,
+                log_callback=lambda msg, level="info": events.log(msg, level=level),
+            )
+        except Exception as exc:
+            events.log(f"Failed to embed m4b metadata: {exc}", level="error")
+            raise RuntimeError(f"Failed to embed m4b metadata: {exc}") from exc
+
+    # EPUB3 generation
+    if request.epub3_export and plan.extraction:
+        audio_asset = result.audio_path
+        if not audio_asset and result.chapter_paths:
+            audio_asset = result.chapter_paths[0]
+
+        if audio_asset:
+            try:
+
+                from abogen.epub3.exporter import build_epub3_package
+
+                epub_root = result.project_root or plan.output_layout.parent_dir
+                from abogen.domain.output_paths import build_output_path
+
+                epub_output_path = build_output_path(epub_root, request.original_filename, "epub")
+                events.log("Generating EPUB 3 package...")
+                epub_path = build_epub3_package(
+                    output_path=epub_output_path,
+                    book_id=request.epub3_export.book_id,
+                    extraction=plan.extraction,
+                    metadata_tags=result.metadata or {},
+                    chapter_markers=result.chapter_markers or [],
+                    chunk_markers=result.chunk_markers or [],
+                    chunks=request.chapter_chunk.chunks if request.chapter_chunk else [],
+                    audio_path=audio_asset,
+                    speaker_mode=request.chapter_chunk.speaker_mode if request.chapter_chunk else "single",
+                    cover=request.cover,
+                )
+                result.epub_path = epub_path
+                result.artifacts["epub3"] = epub_path
+                events.log(f"EPUB 3 package created at {epub_path}")
+            except Exception as exc:
+                events.log(f"Failed to generate EPUB 3: {exc}", level="error")
+        else:
+            events.log("Skipped EPUB 3 generation: audio output unavailable.", level="warning")
+
+    # Build metadata payload and write metadata.json
+    if plan.output_layout and plan.output_layout.metadata_dir:
+        from abogen.domain.metadata_helpers import build_metadata_payload
+
+        metadata_payload = build_metadata_payload(
+            metadata=result.metadata,
+            chapter_markers=result.chapter_markers,
+            chunk_markers=result.chunk_markers,
+            chunk_level=request.chapter_chunk.chunk_level if request.chapter_chunk else None,
+            speaker_mode=request.chapter_chunk.speaker_mode if request.chapter_chunk else None,
+            speakers=request.chapter_chunk.speakers if request.chapter_chunk else None,
+            generate_epub3=bool(request.epub3_export),
+        )
+
+        metadata_dir = plan.output_layout.metadata_dir
+        metadata_dir.mkdir(parents=True, exist_ok=True)
+        metadata_file = metadata_dir / "metadata.json"
+
+        import json
+
+        metadata_file.write_text(json.dumps(metadata_payload, indent=2), encoding="utf-8")
+        result.artifacts["metadata"] = metadata_file
+        events.log(f"Metadata written to {metadata_file}")
+
+    # Record override usage
+    if result.usage_counter:
+        try:
+            from abogen.normalization_settings import record_override_usage
+
+            record_override_usage(result.usage_counter)
+        except Exception as exc:
+            events.log(f"Failed to record override usage: {exc}", level="debug")
+
+    # Post-conversion hooks (Audiobookshelf, etc.)
+    from abogen.application.integration_hooks import PostConversionHooks
+
+    hooks = PostConversionHooks()
+    hooks.run(request, result, events)
+
+
+

abogen/application/integration_hooks.py

@@ -0,0 +1,164 @@
+"""Post-conversion integration hooks.
+
+Called by ConversionService after finalization.
+Each integration is a method on PostConversionHooks — isolated, testable,
+and easy to extend with new hooks (Plex, Navidrome, etc.).
+
+The service NEVER imports from PyQt or WebUI.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Mapping, Optional
+
+from abogen.application.conversion_ports import ConversionEvents
+from abogen.application.conversion_request import ConversionRequest
+from abogen.application.conversion_result import ConversionResult
+from abogen.domain.metadata_helpers import (
+    build_audiobookshelf_metadata as _build_abs_metadata,
+    load_audiobookshelf_chapters as _load_abs_chapters,
+)
+from abogen.domain.settings_core import (
+    build_audiobookshelf_config,
+    coerce_bool,
+    load_audiobookshelf_config,
+    stored_integration_config,
+)
+from abogen.integrations.audiobookshelf import (
+    AudiobookshelfClient,
+    AudiobookshelfUploadError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PostConversionHooks:
+    """Runs post-conversion integrations (Audiobookshelf, etc.).
+
+    Usage::
+
+        hooks = PostConversionHooks()
+        hooks.run(request, result, events)
+    """
+
+    def run(
+        self,
+        request: ConversionRequest,
+        result: ConversionResult,
+        events: ConversionEvents,
+    ) -> None:
+        """Run all registered post-conversion hooks."""
+        self._maybe_send_to_audiobookshelf(request, result, events)
+
+    # ------------------------------------------------------------------
+    # Audiobookshelf
+    # ------------------------------------------------------------------
+
+    def _maybe_send_to_audiobookshelf(
+        self,
+        request: ConversionRequest,
+        result: ConversionResult,
+        events: ConversionEvents,
+    ) -> None:
+        """Upload finished audiobook to Audiobookshelf if enabled."""
+        abs_settings = stored_integration_config("audiobookshelf")
+        if not abs_settings:
+            return
+
+        enabled = coerce_bool(abs_settings.get("enabled"), False)
+        auto_send = coerce_bool(abs_settings.get("auto_send"), False)
+        if not (enabled and auto_send):
+            return
+
+        config = build_audiobookshelf_config(abs_settings)
+        if config is None:
+            events.log(
+                "Audiobookshelf upload skipped: configure base URL, API token, "
+                "library ID, and folder ID first.",
+                level="warning",
+            )
+            return
+
+        audio_path = result.audio_path
+        if not audio_path or not audio_path.exists():
+            events.log(
+                "Audiobookshelf upload skipped: audio output not found.",
+                level="warning",
+            )
+            return
+
+        # Build metadata
+        filename = request.original_filename or "Audiobook"
+        lang = request.language.value if hasattr(request.language, "value") else str(request.language)
+        metadata = _build_abs_metadata(
+            result.metadata or {},
+            language=lang,
+            filename=Path(filename).stem,
+        )
+
+        # Load chapters from metadata artifact
+        chapters = None
+        if config.send_chapters:
+            metadata_artifact = result.artifacts.get("metadata")
+            if metadata_artifact:
+                metadata_path = (
+                    metadata_artifact
+                    if isinstance(metadata_artifact, Path)
+                    else Path(str(metadata_artifact))
+                )
+                chapters = _load_abs_chapters(metadata_path)
+
+        # Resolve cover
+        cover_path = None
+        if config.send_cover and request.cover and request.cover.path:
+            candidate = request.cover.path
+            if isinstance(candidate, Path) and candidate.exists():
+                cover_path = candidate
+
+        # Resolve subtitles
+        subtitles = None
+        if config.send_subtitles and result.subtitle_paths:
+            subtitles = [
+                p for p in result.subtitle_paths
+                if isinstance(p, Path) and p.exists()
+            ]
+
+        # Upload
+        client = AudiobookshelfClient(config)
+        display_title = metadata.get("title") or audio_path.stem
+
+        try:
+            existing_items = client.find_existing_items(
+                display_title, folder_id=config.folder_id,
+            )
+        except AudiobookshelfUploadError as exc:
+            events.log(f"Audiobookshelf lookup failed: {exc}", level="error")
+            return
+
+        if existing_items:
+            events.log(
+                f"Removing existing Audiobookshelf item(s) for '{display_title}'.",
+                level="info",
+            )
+            try:
+                client.delete_items(existing_items)
+            except Exception as exc:
+                events.log(
+                    f"Failed to remove existing item(s): {exc}", level="warning",
+                )
+
+        try:
+            client.upload_audiobook(
+                audio_path,
+                metadata=metadata,
+                cover_path=cover_path,
+                chapters=chapters,
+                subtitles=subtitles,
+            )
+            events.log("Audiobookshelf upload queued.", level="info")
+        except AudiobookshelfUploadError as exc:
+            events.log(f"Audiobookshelf upload failed: {exc}", level="error")
+        except Exception as exc:
+            events.log(f"Audiobookshelf integration error: {exc}", level="error")

abogen/application/output_layout_service.py

@@ -0,0 +1,149 @@
+"""Output layout resolution service.
+
+Determines where conversion outputs (audio, subtitles, metadata) should be written.
+Extracted from conversion_planner.py as a standalone service per plan Stage 5.
+
+Responsibilities:
+- Resolve base output directory from save_mode and source_path
+- Determine base filename from original_filename
+- Find unique output path to avoid overwrites
+- Resolve project layout (audio_dir, subtitle_dir, metadata_dir)
+- Force merged output for m4b format
+- Return OutputLayout dataclass
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from abogen.application.conversion_models import OutputLayout
+from abogen.application.conversion_request import ConversionRequest
+from abogen.domain.enums import OutputFormat, SaveMode, SubtitleFormat
+from abogen.domain.output_paths import (
+    resolve_project_layout,
+    resolve_unique_path,
+    sanitize_output_stem,
+)
+
+
+def resolve_output_layout(request: ConversionRequest) -> OutputLayout:
+    """Resolve output paths for a conversion request.
+
+    This is the single entry point for output path resolution,
+    used by both UIs and the conversion service.
+
+    Args:
+        request: Normalized conversion request
+
+    Returns:
+        OutputLayout with resolved paths
+    """
+    # Determine base output directory
+    if request.save.mode == SaveMode.CUSTOM_FOLDER and request.save.output_folder:
+        parent_dir = Path(request.save.output_folder)
+    elif request.source_path:
+        parent_dir = request.source_path.parent
+    else:
+        parent_dir = Path.cwd()
+
+    # Determine base name
+    if request.original_filename:
+        base_name = sanitize_output_stem(request.original_filename)
+    elif request.source_path:
+        base_name = sanitize_output_stem(request.source_path.stem)
+    else:
+        base_name = "output"
+
+    # Find unique output path
+    allowed_exts = {request.output_format, SubtitleFormat.SRT, SubtitleFormat.ASS, "vtt", "mp4", OutputFormat.M4B}
+    unique_base = resolve_unique_path(
+        parent_dir, base_name, "", allowed_extensions=allowed_exts
+    )
+
+    # Resolve project layout
+    project_root = None
+    audio_dir = parent_dir
+    subtitle_dir = None
+    metadata_dir = None
+
+    if request.save.save_as_project:
+        project_root, audio_dir, subtitle_dir, metadata_dir = resolve_project_layout(
+            original_filename=request.original_filename,
+            save_as_project=True,
+            base_dir=parent_dir,
+        )
+
+    return OutputLayout(
+        parent_dir=parent_dir,
+        project_root=project_root,
+        audio_dir=audio_dir,
+        subtitle_dir=subtitle_dir,
+        metadata_dir=metadata_dir,
+    )
+
+
+def resolve_merged_path(
+    layout: OutputLayout,
+    request: ConversionRequest,
+) -> Path:
+    """Resolve the merged output audio file path.
+
+    Args:
+        layout: Resolved output layout
+        request: Conversion request
+
+    Returns:
+        Path to the merged output file
+    """
+    base_name = sanitize_output_stem(
+        request.original_filename or "output"
+    )
+    return layout.audio_dir / f"{base_name}{request.output_format.dot_ext}"
+
+
+def resolve_chapter_path(
+    layout: OutputLayout,
+    request: ConversionRequest,
+    chapter_title: str,
+    chapter_index: int,
+) -> Path:
+    """Resolve the output path for a separate chapter file.
+
+    Args:
+        layout: Resolved output layout
+        request: Conversion request
+        chapter_title: Chapter title for filename
+        chapter_index: Chapter number (1-based)
+
+    Returns:
+        Path to the chapter output file
+    """
+    import re
+
+    slug = re.sub(r'[^\w\s-]', '', chapter_title.lower())
+    slug = re.sub(r'[\s_]+', '_', slug).strip('_')
+    if not slug:
+        slug = f"chapter_{chapter_index}"
+    filename = f"{chapter_index:02d}_{slug}.{request.save.separate_chapters_format}"
+    return layout.audio_dir / "chapters" / filename
+
+
+def should_merge_output(request: ConversionRequest) -> bool:
+    """Determine if merged output is required.
+
+    Rules:
+    - m4b format always forces merged output
+    - If save_chapters_separately is False, merged is required
+    - Otherwise, use merge_chapters_at_end setting
+
+    Args:
+        request: Conversion request
+
+    Returns:
+        True if merged output should be created
+    """
+    if request.output_format == OutputFormat.M4B:
+        return True
+    if not request.save.save_chapters_separately:
+        return True
+    return request.save.merge_chapters_at_end

abogen/application/voice_resolver.py

@@ -0,0 +1,81 @@
+"""AppVoiceResolver — voice resolution inside the application layer.
+
+Resolves voice specs into loaded voices using profiles, pipeline pool,
+and voice cache. Replaces UI-specific resolvers (WebUIVoiceResolver,
+PyQtVoiceResolver) with a single app-layer implementation.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+from abogen.application.conversion_ports import ResolvedVoice, VoiceResolver
+from abogen.application.conversion_request import ConversionRequest
+from abogen.domain.pipeline_factory import PipelinePool
+from abogen.domain.voice_loader import VoiceCache, resolve_voice
+from abogen.domain.voice_utils import resolve_voice_target
+
+
+class AppVoiceResolver:
+    """App-layer implementation of VoiceResolver protocol.
+
+    Uses ConversionRequest instead of Job. Loads profiles, creates
+    resolver internally — UIs don't need to manage this.
+    """
+
+    def __init__(
+        self,
+        request: ConversionRequest,
+        normalized_profiles: Dict[str, Dict[str, Any]],
+        pool: PipelinePool,
+        cache: VoiceCache,
+    ):
+        self._request = request
+        self._profiles = normalized_profiles
+        self._cache = cache
+        self._pool = pool
+
+    def resolve(self, voice_spec: str) -> ResolvedVoice:
+        """Resolve a voice spec into a loaded voice."""
+        provider, resolved, speed, steps = resolve_voice_target(
+            voice_spec,
+            self._profiles,
+            job_voice=self._request.voice,
+            job_tts_provider=self._request.tts_provider,
+            job_supertonic_total_steps=self._request.supertonic_total_steps,
+            job_speed=self._request.speed,
+        )
+
+        cache_key = f"{provider}:{resolved}" if resolved else provider
+        cached = self._cache.get(cache_key)
+        if cached is not None:
+            logging.info("[resolver] Cache hit: spec=%s -> provider=%s resolved=%s", voice_spec, provider, resolved)
+            return ResolvedVoice(
+                provider=provider,
+                resolved_spec=resolved,
+                voice=cached,
+                speed=speed,
+                supertonic_steps=steps or 0,
+            )
+
+        if provider == "kokoro":
+            kokoro_backend = self._pool.get(
+                "kokoro", self._request.language, self._request.use_gpu,
+            )
+            loaded = resolve_voice(
+                resolved, kokoro_backend, self._request.use_gpu, cache=self._cache,
+            )
+        else:
+            loaded = resolved
+
+        self._cache.set(cache_key, loaded)
+        logging.info("[resolver] Resolved: spec=%s -> provider=%s resolved=%s speed=%.2f steps=%s",
+                      voice_spec, provider, resolved, speed, steps)
+        return ResolvedVoice(
+            provider=provider,
+            resolved_spec=resolved,
+            voice=loaded,
+            speed=speed,
+            supertonic_steps=steps or 0,
+        )

abogen/assets/settings.svg

@@ -1,31 +1,31 @@
-<?xml version="1.0" encoding="utf-8"?>
-
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
-<svg height="800px" width="800px" version="1.1" id="_x32_" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
-	 viewBox="0 0 512 512"  xml:space="preserve">
-<style type="text/css">
-	.st0{fill:#808080;}
-</style>
-<g>
-	<path class="st0" d="M502.325,307.303l-39.006-30.805c-6.215-4.908-9.665-12.429-9.668-20.348c0-0.084,0-0.168,0-0.252
-		c-0.014-7.936,3.44-15.478,9.667-20.396l39.007-30.806c8.933-7.055,12.093-19.185,7.737-29.701l-17.134-41.366
-		c-4.356-10.516-15.167-16.86-26.472-15.532l-49.366,5.8c-7.881,0.926-15.656-1.966-21.258-7.586
-		c-0.059-0.06-0.118-0.119-0.177-0.178c-5.597-5.602-8.476-13.36-7.552-21.225l5.799-49.363
-		c1.328-11.305-5.015-22.116-15.531-26.472L337.004,1.939c-10.516-4.356-22.646-1.196-29.701,7.736l-30.805,39.005
-		c-4.908,6.215-12.43,9.665-20.349,9.668c-0.084,0-0.168,0-0.252,0c-7.935,0.014-15.477-3.44-20.395-9.667L204.697,9.675
-		c-7.055-8.933-19.185-12.092-29.702-7.736L133.63,19.072c-10.516,4.356-16.86,15.167-15.532,26.473l5.799,49.366
-		c0.926,7.881-1.964,15.656-7.585,21.257c-0.059,0.059-0.118,0.118-0.178,0.178c-5.602,5.598-13.36,8.477-21.226,7.552
-		l-49.363-5.799c-11.305-1.328-22.116,5.015-26.472,15.531L1.939,174.996c-4.356,10.516-1.196,22.646,7.736,29.701l39.006,30.805
-		c6.215,4.908,9.665,12.429,9.668,20.348c0,0.084,0,0.167,0,0.251c0.014,7.935-3.44,15.477-9.667,20.395L9.675,307.303
-		c-8.933,7.055-12.092,19.185-7.736,29.701l17.134,41.365c4.356,10.516,15.168,16.86,26.472,15.532l49.366-5.799
-		c7.882-0.926,15.656,1.965,21.258,7.586c0.059,0.059,0.118,0.119,0.178,0.178c5.597,5.603,8.476,13.36,7.552,21.226l-5.799,49.364
-		c-1.328,11.305,5.015,22.116,15.532,26.472l41.366,17.134c10.516,4.356,22.646,1.196,29.701-7.736l30.804-39.005
-		c4.908-6.215,12.43-9.665,20.348-9.669c0.084,0,0.168,0,0.251,0c7.936-0.014,15.478,3.44,20.396,9.667l30.806,39.007
-		c7.055,8.933,19.185,12.093,29.701,7.736l41.366-17.134c10.516-4.356,16.86-15.168,15.532-26.472l-5.8-49.366
-		c-0.926-7.881,1.965-15.656,7.586-21.257c0.059-0.059,0.119-0.119,0.178-0.178c5.602-5.597,13.36-8.476,21.225-7.552l49.364,5.799
-		c11.305,1.328,22.117-5.015,26.472-15.531l17.134-41.365C514.418,326.488,511.258,314.358,502.325,307.303z M281.292,329.698
-		c-39.68,16.436-85.172-2.407-101.607-42.087c-16.436-39.68,2.407-85.171,42.087-101.608c39.68-16.436,85.172,2.407,101.608,42.088
-		C339.815,267.771,320.972,313.262,281.292,329.698z"/>
-</g>
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
+<svg height="800px" width="800px" version="1.1" id="_x32_" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
+	 viewBox="0 0 512 512"  xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#808080;}
+</style>
+<g>
+	<path class="st0" d="M502.325,307.303l-39.006-30.805c-6.215-4.908-9.665-12.429-9.668-20.348c0-0.084,0-0.168,0-0.252
+		c-0.014-7.936,3.44-15.478,9.667-20.396l39.007-30.806c8.933-7.055,12.093-19.185,7.737-29.701l-17.134-41.366
+		c-4.356-10.516-15.167-16.86-26.472-15.532l-49.366,5.8c-7.881,0.926-15.656-1.966-21.258-7.586
+		c-0.059-0.06-0.118-0.119-0.177-0.178c-5.597-5.602-8.476-13.36-7.552-21.225l5.799-49.363
+		c1.328-11.305-5.015-22.116-15.531-26.472L337.004,1.939c-10.516-4.356-22.646-1.196-29.701,7.736l-30.805,39.005
+		c-4.908,6.215-12.43,9.665-20.349,9.668c-0.084,0-0.168,0-0.252,0c-7.935,0.014-15.477-3.44-20.395-9.667L204.697,9.675
+		c-7.055-8.933-19.185-12.092-29.702-7.736L133.63,19.072c-10.516,4.356-16.86,15.167-15.532,26.473l5.799,49.366
+		c0.926,7.881-1.964,15.656-7.585,21.257c-0.059,0.059-0.118,0.118-0.178,0.178c-5.602,5.598-13.36,8.477-21.226,7.552
+		l-49.363-5.799c-11.305-1.328-22.116,5.015-26.472,15.531L1.939,174.996c-4.356,10.516-1.196,22.646,7.736,29.701l39.006,30.805
+		c6.215,4.908,9.665,12.429,9.668,20.348c0,0.084,0,0.167,0,0.251c0.014,7.935-3.44,15.477-9.667,20.395L9.675,307.303
+		c-8.933,7.055-12.092,19.185-7.736,29.701l17.134,41.365c4.356,10.516,15.168,16.86,26.472,15.532l49.366-5.799
+		c7.882-0.926,15.656,1.965,21.258,7.586c0.059,0.059,0.118,0.119,0.178,0.178c5.597,5.603,8.476,13.36,7.552,21.226l-5.799,49.364
+		c-1.328,11.305,5.015,22.116,15.532,26.472l41.366,17.134c10.516,4.356,22.646,1.196,29.701-7.736l30.804-39.005
+		c4.908-6.215,12.43-9.665,20.348-9.669c0.084,0,0.168,0,0.251,0c7.936-0.014,15.478,3.44,20.396,9.667l30.806,39.007
+		c7.055,8.933,19.185,12.093,29.701,7.736l41.366-17.134c10.516-4.356,16.86-15.168,15.532-26.472l-5.8-49.366
+		c-0.926-7.881,1.965-15.656,7.586-21.257c0.059-0.059,0.119-0.119,0.178-0.178c5.602-5.597,13.36-8.476,21.225-7.552l49.364,5.799
+		c11.305,1.328,22.117-5.015,26.472-15.531l17.134-41.365C514.418,326.488,511.258,314.358,502.325,307.303z M281.292,329.698
+		c-39.68,16.436-85.172-2.407-101.607-42.087c-16.436-39.68,2.407-85.171,42.087-101.608c39.68-16.436,85.172,2.407,101.608,42.088
+		C339.815,267.771,320.972,313.262,281.292,329.698z"/>
+</g>
 </svg>

abogen/book_parser.py

@@ -12,7 +12,8 @@ import fitz  # PyMuPDF
 import markdown
 
 from abogen.utils import detect_encoding
-from abogen.subtitle_utils import clean_text, calculate_text_length
+from abogen.subtitle_utils import clean_text
+from abogen.domain.text_utils import calculate_text_length
 
 # Pre-compile frequently used regex patterns
 _BRACKETED_NUMBERS_PATTERN = re.compile(r"\[\s*\d+\s*\]")

abogen/constants.py

@@ -1,4 +1,5 @@
 from abogen.utils import get_version
+from abogen.domain.enums import Language
 
 # Program Information
 PROGRAM_NAME = "abogen"
@@ -16,8 +17,22 @@ SUBTITLE_FORMATS = [
     ("ass_centered_narrow", "ASS (centered narrow)"),
 ]
 
-# Language description mapping
+# Language description mapping (Language enum → human-readable label).
 LANGUAGE_DESCRIPTIONS = {
+    Language.EN_US: "American English",
+    Language.EN_GB: "British English",
+    Language.ES: "Spanish",
+    Language.FR: "French",
+    Language.HI: "Hindi",
+    Language.IT: "Italian",
+    Language.JA: "Japanese",
+    Language.PT_BR: "Brazilian Portuguese",
+    Language.ZH: "Mandarin Chinese",
+}
+
+# Display-only mapping for kokoro codes → labels.
+# Used by voice catalog and PyQt (legacy) where kokoro codes are still present.
+KOKORO_CODE_LABELS = {
     "a": "American English",
     "b": "British English",
     "e": "Spanish",
@@ -55,83 +70,24 @@ SUPPORTED_INPUT_FORMATS = [
     "vtt",
 ]
 
-# Supported languages for subtitle generation
-# Currently, only 'a (American English)' and 'b (British English)' are supported for subtitle generation.
-# This is because tokens that contain timestamps are not generated for other languages in the Kokoro pipeline.
-# Please refer to: https://github.com/hexgrad/kokoro/blob/6d87f4ae7abc2d14dbc4b3ef2e5f19852e861ac2/kokoro/pipeline.py
-# 383 English processing (unchanged)
-# 384 if self.lang_code in 'ab':
-SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION = list(LANGUAGE_DESCRIPTIONS.keys())
-
-# Voice and sample text constants
-VOICES_INTERNAL = [
-    "af_alloy",
-    "af_aoede",
-    "af_bella",
-    "af_heart",
-    "af_jessica",
-    "af_kore",
-    "af_nicole",
-    "af_nova",
-    "af_river",
-    "af_sarah",
-    "af_sky",
-    "am_adam",
-    "am_echo",
-    "am_eric",
-    "am_fenrir",
-    "am_liam",
-    "am_michael",
-    "am_onyx",
-    "am_puck",
-    "am_santa",
-    "bf_alice",
-    "bf_emma",
-    "bf_isabella",
-    "bf_lily",
-    "bm_daniel",
-    "bm_fable",
-    "bm_george",
-    "bm_lewis",
-    "ef_dora",
-    "em_alex",
-    "em_santa",
-    "ff_siwis",
-    "hf_alpha",
-    "hf_beta",
-    "hm_omega",
-    "hm_psi",
-    "if_sara",
-    "im_nicola",
-    "jf_alpha",
-    "jf_gongitsune",
-    "jf_nezumi",
-    "jf_tebukuro",
-    "jm_kumo",
-    "pf_dora",
-    "pm_alex",
-    "pm_santa",
-    "zf_xiaobei",
-    "zf_xiaoni",
-    "zf_xiaoxiao",
-    "zf_xiaoyi",
-    "zm_yunjian",
-    "zm_yunxi",
-    "zm_yunxia",
-    "zm_yunyang",
-]
+# Supported languages for subtitle generation.
+# All languages are supported: only English emits per-word timestamped tokens
+# in the Kokoro pipeline, but other languages fall back to segment-level fake
+# tokens (see abogen.domain.tokens.FakeToken), so subtitles are still
+# generated at segment granularity.
+SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION = list(Language)
 
 # Voice and sample text mapping
 SAMPLE_VOICE_TEXTS = {
-    "a": "This is a sample of the selected voice.",
-    "b": "This is a sample of the selected voice.",
-    "e": "Este es una muestra de la voz seleccionada.",
-    "f": "Ceci est un exemple de la voix sélectionnée.",
-    "h": "यह चयनित आवाज़ का एक नमूना है।",
-    "i": "Questo è un esempio della voce selezionata.",
-    "j": "これは選択した声のサンプルです。",
-    "p": "Este é um exemplo da voz selecionada.",
-    "z": "这是所选语音的示例。",
+    Language.EN_US: "This is a sample of the selected voice.",
+    Language.EN_GB: "This is a sample of the selected voice.",
+    Language.ES: "Este es una muestra de la voz seleccionada.",
+    Language.FR: "Ceci est un exemple de la voix sélectionnée.",
+    Language.HI: "यह चयनित आवाज़ का एक नमूना है।",
+    Language.IT: "Questo è un esempio della voce selezionata.",
+    Language.JA: "これは選択した声のサンプルです。",
+    Language.PT_BR: "Este é um exemplo da voz selecionada.",
+    Language.ZH: "这是所选语音的示例。",
 }
 
 COLORS = {

abogen/domain/audio_buffer.py

@@ -0,0 +1,239 @@
+"""Audio buffer operations for audiobook generation.
+
+This module provides core audio buffer manipulation functions including:
+- Silence generation
+- Audio mixing
+- Audio normalization
+- Audio buffer resizing
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+# Standard sample rate used throughout the application
+SAMPLE_RATE = 24000
+
+
+def create_silence(duration_seconds: float) -> np.ndarray:
+    """Create a silence audio buffer.
+    
+    Args:
+        duration_seconds: Duration of silence in seconds.
+        
+    Returns:
+        Numpy array of float32 zeros with length = duration_seconds * SAMPLE_RATE.
+        Returns empty array if duration is <= 0.
+    """
+    if duration_seconds <= 0:
+        return np.array([], dtype="float32")
+    
+    samples = int(round(duration_seconds * SAMPLE_RATE))
+    if samples <= 0:
+        return np.array([], dtype="float32")
+    
+    return np.zeros(samples, dtype="float32")
+
+
+def mix_audio(
+    target: np.ndarray,
+    source: np.ndarray,
+    start_sample: int,
+    end_sample: Optional[int] = None,
+) -> np.ndarray:
+    """Mix source audio into target buffer at specified position.
+    
+    This performs additive mixing (target += source). The target buffer
+    is extended if necessary to accommodate the source audio.
+    
+    Args:
+        target: The target audio buffer to mix into.
+        source: The source audio buffer to mix.
+        start_sample: Starting sample index in target buffer.
+        end_sample: Optional end sample index. If None, calculated from source length.
+        
+    Returns:
+        The target buffer (possibly extended). If target was extended, returns new array.
+    """
+    if source.size == 0:
+        return target
+    
+    if end_sample is None:
+        end_sample = start_sample + len(source)
+    
+    # Extend target buffer if needed
+    if end_sample > len(target):
+        new_length = end_sample
+        new_target = np.concatenate([
+            target,
+            np.zeros(new_length - len(target), dtype="float32")
+        ])
+        target = new_target
+    
+    # Perform the mix (additive)
+    target[start_sample:end_sample] += source
+    return target
+
+
+def normalize_audio(
+    audio: np.ndarray,
+    target_peak: float = 1.0,
+) -> np.ndarray:
+    """Normalize audio buffer to prevent clipping.
+    
+    If the audio exceeds the target peak (default 1.0), it is scaled down
+    proportionally to prevent distortion.
+    
+    Args:
+        audio: Input audio buffer.
+        target_peak: Target maximum amplitude (default 1.0).
+        
+    Returns:
+        Normalized audio buffer (new array, original is not modified).
+    """
+    if audio.size == 0:
+        return audio.copy()
+    
+    max_amplitude = float(np.abs(audio).max())
+    
+    if max_amplitude <= target_peak:
+        return audio.copy()
+    
+    # Scale down to prevent clipping
+    scale_factor = target_peak / max_amplitude
+    return (audio * scale_factor).astype("float32")
+
+
+def ensure_buffer_size(
+    buffer: np.ndarray,
+    min_samples: int,
+) -> np.ndarray:
+    """Ensure audio buffer is at least min_samples long.
+    
+    If buffer is shorter, it is extended with zeros.
+    
+    Args:
+        buffer: Input audio buffer.
+        min_samples: Minimum required length in samples.
+        
+    Returns:
+        Buffer of at least min_samples length (new array if extended).
+    """
+    if len(buffer) >= min_samples:
+        return buffer
+    
+    new_buffer = np.zeros(min_samples, dtype="float32")
+    new_buffer[:len(buffer)] = buffer
+    return new_buffer
+
+
+def concatenate_audio(*buffers: np.ndarray) -> np.ndarray:
+    """Concatenate multiple audio buffers.
+    
+    Args:
+        *buffers: Audio buffers to concatenate.
+        
+    Returns:
+        Single concatenated audio buffer.
+    """
+    non_empty = [b for b in buffers if b.size > 0]
+    if not non_empty:
+        return np.array([], dtype="float32")
+    return np.concatenate(non_empty)
+
+
+def audio_duration(audio: np.ndarray, sample_rate: int = SAMPLE_RATE) -> float:
+    """Calculate duration of audio buffer in seconds.
+    
+    Args:
+        audio: Audio buffer.
+        sample_rate: Sample rate in Hz (default SAMPLE_RATE).
+        
+    Returns:
+        Duration in seconds.
+    """
+    return len(audio) / sample_rate
+
+
+def samples_for_duration(duration_seconds: float, sample_rate: int = SAMPLE_RATE) -> int:
+    """Calculate number of samples for a given duration.
+    
+    Args:
+        duration_seconds: Duration in seconds.
+        sample_rate: Sample rate in Hz (default SAMPLE_RATE).
+        
+    Returns:
+        Number of samples (rounded to nearest integer), or 0 if duration is <= 0.
+    """
+    if duration_seconds <= 0:
+        return 0
+    return int(round(duration_seconds * sample_rate))
+
+
+def fit_audio_to_duration(
+    audio: np.ndarray,
+    target_duration: float,
+    sample_rate: int = SAMPLE_RATE,
+) -> np.ndarray:
+    """Pad or trim audio to match target duration.
+
+    Args:
+        audio: Input audio buffer.
+        target_duration: Desired duration in seconds.
+        sample_rate: Sample rate in Hz.
+
+    Returns:
+        Audio buffer of exact length target_duration * sample_rate.
+    """
+    target_samples = int(target_duration * sample_rate)
+    if len(audio) < target_samples:
+        padding = np.zeros(target_samples - len(audio), dtype="float32")
+        return np.concatenate([audio, padding])
+    return audio[:target_samples]
+
+
+def ffmpeg_time_stretch(
+    audio: np.ndarray,
+    speed_factor: float,
+    sample_rate: int = SAMPLE_RATE,
+) -> np.ndarray:
+    """Time-stretch audio using FFmpeg's atempo filter.
+
+    Args:
+        audio: Input audio buffer (float32).
+        speed_factor: Speed multiplier (>1.0 = faster).
+        sample_rate: Sample rate in Hz.
+
+    Returns:
+        Time-stretched audio buffer.
+    """
+    import math
+    import subprocess
+
+    import static_ffmpeg
+
+    if speed_factor <= 1.0 or audio.size == 0:
+        return audio
+
+    static_ffmpeg.add_paths()
+    num_stages = max(1, int(math.ceil(math.log(speed_factor) / math.log(2.0))))
+    tempo = speed_factor ** (1.0 / num_stages)
+    filter_str = ",".join([f"atempo={tempo:.6f}"] * num_stages)
+
+    proc = subprocess.Popen(
+        [
+            "ffmpeg", "-y",
+            "-f", "f32le", "-ar", str(sample_rate), "-ac", "1",
+            "-i", "pipe:0",
+            "-filter:a", filter_str,
+            "-f", "f32le", "-ar", str(sample_rate), "-ac", "1",
+            "pipe:1",
+        ],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    out, _ = proc.communicate(input=audio.tobytes())
+    return np.frombuffer(out, dtype="float32")

abogen/domain/audio_helpers.py

@@ -0,0 +1,118 @@
+"""Audio helper utilities.
+
+Functions for building ffmpeg commands, converting audio formats,
+and applying chapter metadata to MP4 files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+
+
+SAMPLE_RATE = 24000
+
+
+def build_ffmpeg_command(path: Path, fmt: str, metadata: Optional[Dict[str, str]] = None) -> list[str]:
+    from abogen.infrastructure.exporters import ExportService
+
+    base = [
+        "ffmpeg",
+        "-y",
+        "-f",
+        "f32le",
+        "-ar",
+        str(SAMPLE_RATE),
+        "-ac",
+        "1",
+        "-i",
+        "pipe:0",
+    ]
+    if fmt == "mp3":
+        base += ["-c:a", "libmp3lame", "-qscale:a", "2"]
+    elif fmt == "opus":
+        base += ["-c:a", "libopus", "-b:a", "128000"]
+    elif fmt == "m4b":
+        base += ["-c:a", "aac", "-q:a", "2", "-movflags", "+faststart+use_metadata_tags"]
+    else:
+        base += ["-c:a", "copy"]
+
+    if metadata:
+        svc = ExportService()
+        base.extend(svc._metadata_to_ffmpeg_args(metadata))
+    base.append(str(path))
+    return base
+
+
+def to_float32(audio_segment) -> np.ndarray:
+    if audio_segment is None:
+        return np.zeros(0, dtype="float32")
+
+    tensor = audio_segment
+    if hasattr(tensor, "detach"):
+        tensor = tensor.detach()
+    if hasattr(tensor, "cpu"):
+        try:
+            tensor = tensor.cpu()
+        except Exception:
+            pass
+    if hasattr(tensor, "numpy"):
+        return np.asarray(tensor.numpy(), dtype="float32").reshape(-1)
+    return np.asarray(tensor, dtype="float32").reshape(-1)
+
+
+def apply_m4b_chapters_with_mutagen(
+    audio_path: Path,
+    chapters: List[Dict[str, Any]],
+) -> bool:
+    """Apply chapter atoms to an MP4/M4B file using mutagen.
+
+    Returns True if chapters were written, False otherwise.
+    Raises ImportError if mutagen is not installed.
+    """
+    if not chapters:
+        return False
+
+    from fractions import Fraction
+    from mutagen.mp4 import MP4, MP4Chapter  # type: ignore[import]
+
+    mp4 = MP4(str(audio_path))
+
+    chapter_objects: List[MP4Chapter] = []
+    for index, entry in enumerate(sorted(chapters, key=lambda item: float(item.get("start") or 0.0))):
+        start_raw = entry.get("start")
+        if start_raw is None:
+            continue
+        try:
+            start_seconds = max(0.0, float(start_raw))
+        except (TypeError, ValueError):
+            continue
+
+        title_value = entry.get("title")
+        title_text = str(title_value) if title_value else f"Chapter {index + 1}"
+
+        start_fraction = Fraction(int(round(start_seconds * 1000)), 1000)
+        chapter_atom = MP4Chapter(start_fraction, title_text)
+
+        end_raw = entry.get("end")
+        if end_raw is not None:
+            try:
+                end_seconds = float(end_raw)
+            except (TypeError, ValueError):
+                end_seconds = None
+            if end_seconds is not None and end_seconds > start_seconds:
+                chapter_atom.end = Fraction(int(round(end_seconds * 1000)), 1000)
+
+        chapter_objects.append(chapter_atom)
+
+    if not chapter_objects:
+        return False
+
+    from typing import cast
+
+    mp4.chapters = cast(Any, chapter_objects)
+    mp4.save()
+
+    return True

abogen/domain/audio_sink.py

@@ -0,0 +1,131 @@
+"""Audio sink abstraction for unified audio output.
+
+Provides a context-manager-based abstraction for writing audio data
+to various output formats (WAV, FLAC via soundfile; compressed via ffmpeg).
+
+Usage:
+    with open_audio_sink(path, "wav") as sink:
+        sink.write(audio_data)
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+import numpy as np
+
+from abogen.domain.audio_buffer import SAMPLE_RATE
+from abogen.domain.audio_helpers import build_ffmpeg_command
+
+
+@dataclass(frozen=True)
+class AudioSink:
+    """Represents an open audio output target."""
+
+    write: Callable[[np.ndarray], None]
+    close: Callable[[], None]
+
+    def __enter__(self) -> AudioSink:
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+
+def _ensure_ffmpeg() -> None:
+    """Ensure static ffmpeg binaries are on PATH."""
+    import static_ffmpeg  # type: ignore
+
+    ffmpeg_cache_root = _get_ffmpeg_cache_root()
+    platform_cache = os.path.join(ffmpeg_cache_root, sys.platform)
+    os.makedirs(platform_cache, exist_ok=True)
+    try:
+        import static_ffmpeg.run as static_ffmpeg_run  # type: ignore
+
+        static_ffmpeg_run.LOCK_FILE = os.path.join(ffmpeg_cache_root, "lock.file")
+    except Exception:
+        pass
+    static_ffmpeg.add_paths(weak=True, download_dir=platform_cache)
+
+
+def _get_ffmpeg_cache_root() -> str:
+    from abogen.utils import get_internal_cache_path
+
+    return get_internal_cache_path("ffmpeg")
+
+
+def open_audio_sink(
+    path: Path,
+    fmt: str,
+    *,
+    metadata: Optional[dict[str, str]] = None,
+    cancel_check: Optional[Callable[[], bool]] = None,
+    extra_ffmpeg_args: Optional[list[str]] = None,
+    ffmpeg_cmd: Optional[list[str]] = None,
+) -> AudioSink:
+    """Open an audio output sink for writing raw float32 PCM samples.
+
+    Args:
+        path: Output file path.
+        fmt: Output format ("wav", "flac", "mp3", "opus", "m4b").
+        metadata: Optional metadata dict (ignored when ffmpeg_cmd is provided).
+        cancel_check: Optional callable; if it returns True, writes are silently skipped.
+        extra_ffmpeg_args: Optional extra args inserted after ffmpeg header (ignored when ffmpeg_cmd is provided).
+        ffmpeg_cmd: Optional pre-built ffmpeg command list (for m4b with cover art etc.).
+
+    Returns:
+        AudioSink with write() and close() methods.
+    """
+    fmt = fmt.lower()
+
+    if fmt in {"wav", "flac"}:
+        import soundfile as sf
+
+        soundfile_obj = sf.SoundFile(
+            path,
+            mode="w",
+            samplerate=SAMPLE_RATE,
+            channels=1,
+            format=fmt.upper(),
+        )
+
+        def _write_wav(data: np.ndarray) -> None:
+            if cancel_check and cancel_check():
+                return
+            soundfile_obj.write(data)
+
+        def _close_wav() -> None:
+            soundfile_obj.close()
+
+        return AudioSink(write=_write_wav, close=_close_wav)
+
+    # Compressed formats: pipe through ffmpeg
+    _ensure_ffmpeg()
+
+    if ffmpeg_cmd is not None:
+        cmd = list(ffmpeg_cmd)
+    else:
+        cmd = build_ffmpeg_command(path, fmt, metadata=metadata)
+        if extra_ffmpeg_args:
+            cmd[2:2] = extra_ffmpeg_args
+
+    process = subprocess.Popen(
+        cmd, stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
+    )
+
+    def _write_compressed(data: np.ndarray) -> None:
+        if (cancel_check and cancel_check()) or process.stdin is None or process.stdin.closed:
+            return
+        process.stdin.write(data.tobytes())
+
+    def _close_compressed() -> None:
+        if process.stdin and not process.stdin.closed:
+            process.stdin.close()
+        process.wait()
+
+    return AudioSink(write=_write_compressed, close=_close_compressed)

abogen/domain/chapter_classification.py

@@ -0,0 +1,131 @@
+"""Heuristics for classifying chapters as content vs. supplements.
+
+A 'supplement' is any non-story material that a listener would typically
+skip: title page, copyright, table of contents, acknowledgements, etc.
+The scoring functions return a float; higher ⇒ more likely to be a
+supplement.  ``should_preselect_chapter`` turns that score into a
+boolean suitable for a web form default.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Tuple
+
+# Compiled once at module load – these are immutable.
+
+_SUPPLEMENT_TITLE_PATTERNS: List[Tuple[re.Pattern[str], float]] = [
+    (re.compile(r"\btitle\s+page\b"), 3.0),
+    (re.compile(r"\bcopyright\b"), 2.4),
+    (re.compile(r"\btable\s+of\s+contents\b"), 2.8),
+    (re.compile(r"\bcontents\b"), 2.0),
+    (re.compile(r"\backnowledg(e)?ments?\b"), 2.0),
+    (re.compile(r"\bdedication\b"), 2.0),
+    (re.compile(r"\babout\s+the\s+author(s)?\b"), 2.4),
+    (re.compile(r"\balso\s+by\b"), 2.0),
+    (re.compile(r"\bpraise\s+for\b"), 2.0),
+    (re.compile(r"\bcolophon\b"), 2.2),
+    (re.compile(r"\bpublication\s+data\b"), 2.2),
+    (re.compile(r"\btranscriber'?s?\s+note\b"), 2.2),
+    (re.compile(r"\bglossary\b"), 2.2),
+    (re.compile(r"\bindex\b"), 2.0),
+    (re.compile(r"\bbibliograph(y|ies)\b"), 2.0),
+    (re.compile(r"\breferences\b"), 1.8),
+    (re.compile(r"\bappendix\b"), 1.9),
+]
+
+_CONTENT_TITLE_PATTERNS: List[re.Pattern[str]] = [
+    re.compile(r"\bchapter\b"),
+    re.compile(r"\bbook\b"),
+    re.compile(r"\bpart\b"),
+    re.compile(r"\bsection\b"),
+    re.compile(r"\bscene\b"),
+    re.compile(r"\bprologue\b"),
+    re.compile(r"\bepilogue\b"),
+    re.compile(r"\bintroduction\b"),
+    re.compile(r"\bstory\b"),
+]
+
+_SUPPLEMENT_TEXT_KEYWORDS: List[Tuple[str, float]] = [
+    ("copyright", 1.2),
+    ("all rights reserved", 1.1),
+    ("isbn", 0.9),
+    ("library of congress", 1.0),
+    ("table of contents", 1.0),
+    ("dedicated to", 0.8),
+    ("acknowledg", 0.8),
+    ("printed in", 0.6),
+    ("permission", 0.6),
+    ("publisher", 0.5),
+    ("praise for", 0.9),
+    ("also by", 0.9),
+    ("glossary", 0.8),
+    ("index", 0.8),
+    ("newsletter", 3.2),
+    ("mailing list", 2.6),
+    ("sign-up", 2.2),
+]
+
+
+def supplement_score(title: str, text: str, index: int) -> float:
+    """Return a score indicating how likely *title*/*text* is a supplement.
+
+    Higher values ⇒ more likely to be non-story material (title page,
+    copyright, acknowledgements, etc.).
+    """
+    normalized_title = (title or "").lower()
+    score = 0.0
+
+    for pattern, weight in _SUPPLEMENT_TITLE_PATTERNS:
+        if pattern.search(normalized_title):
+            score += weight
+
+    for pattern in _CONTENT_TITLE_PATTERNS:
+        if pattern.search(normalized_title):
+            score -= 2.0
+
+    stripped_text = (text or "").strip()
+    length = len(stripped_text)
+    if length <= 150:
+        score += 0.9
+    elif length <= 400:
+        score += 0.6
+    elif length <= 800:
+        score += 0.35
+
+    lowercase_text = stripped_text.lower()
+    for keyword, weight in _SUPPLEMENT_TEXT_KEYWORDS:
+        if keyword in lowercase_text:
+            score += weight
+
+    if index == 0 and score > 0:
+        score += 0.25
+
+    return score
+
+
+def should_preselect_chapter(
+    title: str,
+    text: str,
+    index: int,
+    total_count: int,
+) -> bool:
+    """Return True if the chapter should be *enabled* by default in the form.
+
+    A single chapter is always preselected.  For multi-chapter books, the
+    chapter is preselected when its supplement score is below 1.9.
+    """
+    if total_count <= 1:
+        return True
+    score = supplement_score(title, text, index)
+    return score < 1.9
+
+
+def ensure_at_least_one_chapter_enabled(chapters: List[Dict[str, Any]]) -> None:
+    """Mutate *chapters* in-place so that at least one has ``enabled=True``."""
+    if not chapters:
+        return
+    if any(chapter.get("enabled") for chapter in chapters):
+        return
+    best_index = max(range(len(chapters)), key=lambda idx: chapters[idx].get("characters", 0))
+    chapters[best_index]["enabled"] = True

abogen/domain/chapter_overrides.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from abogen.text_extractor import ExtractedChapter
+from abogen.domain.voice_utils import coerce_truthy
+
+
+def apply_chapter_overrides(
+    extracted: List[ExtractedChapter],
+    overrides: List[Dict[str, Any]],
+) -> Tuple[List[ExtractedChapter], Dict[str, str], List[str]]:
+    if not overrides:
+        return [], {}, []
+
+    selected: List[ExtractedChapter] = []
+    metadata_updates: Dict[str, str] = {}
+    diagnostics: List[str] = []
+
+    for position, payload in enumerate(overrides):
+        if not isinstance(payload, dict):
+            diagnostics.append(
+                f"Skipped chapter override at position {position + 1}: unsupported payload type {type(payload).__name__}."
+            )
+            continue
+
+        enabled = coerce_truthy(payload.get("enabled", True))
+        payload["enabled"] = enabled
+        if not enabled:
+            continue
+
+        metadata_payload = payload.get("metadata") or {}
+        if isinstance(metadata_payload, dict):
+            for key, value in metadata_payload.items():
+                if value is None:
+                    continue
+                metadata_updates[str(key)] = str(value)
+
+        base: Optional[ExtractedChapter] = None
+        idx_candidate = payload.get("index")
+        idx_normalized: Optional[int] = None
+        if isinstance(idx_candidate, int):
+            idx_normalized = idx_candidate
+        elif isinstance(idx_candidate, str):
+            try:
+                idx_normalized = int(idx_candidate)
+            except ValueError:
+                idx_normalized = None
+        if idx_normalized is not None and 0 <= idx_normalized < len(extracted):
+            base = extracted[idx_normalized]
+            payload["index"] = idx_normalized
+
+        if base is None:
+            source_title = payload.get("source_title")
+            if isinstance(source_title, str):
+                base = next((chapter for chapter in extracted if chapter.title == source_title), None)
+
+        if base is None:
+            candidate_title = payload.get("title")
+            if isinstance(candidate_title, str):
+                base = next((chapter for chapter in extracted if chapter.title == candidate_title), None)
+
+        text_override = payload.get("text")
+        if text_override is not None:
+            text_value = str(text_override)
+        elif base is not None:
+            text_value = base.text
+        else:
+            diagnostics.append(
+                f"Skipped chapter override at position {position + 1}: no text provided and no matching source chapter found."
+            )
+            continue
+
+        title_override = payload.get("title")
+        if title_override is not None:
+            title_value = str(title_override)
+        elif base is not None:
+            title_value = base.title
+        else:
+            title_value = f"Chapter {position + 1}"
+
+        if base and not payload.get("source_title"):
+            payload["source_title"] = base.title
+
+        payload["title"] = title_value
+        payload["text"] = text_value
+        payload["characters"] = len(text_value)
+        payload.setdefault("order", payload.get("order", position))
+
+        selected.append(ExtractedChapter(title=title_value, text=text_value))
+
+    return selected, metadata_updates, diagnostics

abogen/domain/chapter_titles.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import re
+from typing import List, Tuple
+
+
+_HEADING_SANITIZE_RE = re.compile(r"[^a-z0-9]+")
+_HEADING_NUMBER_PREFIX_RE = re.compile(
+    r"^\s*(?P<number>(?:\d+|[ivxlcdm]+))(?P<suffix>(?:[\s.:;-].*)?)$",
+    re.IGNORECASE,
+)
+_ACRONYM_ALLOWLIST = {
+    "AI", "API", "CPU", "DIY", "GPU", "HTML", "HTTP", "HTTPS", "ID",
+    "JSON", "MP3", "MP4", "M4B", "NASA", "OCR", "PDF", "SQL", "TV",
+    "TTS", "UK", "UN", "UFO", "OK", "URL", "USA", "US", "VR",
+}
+_ROMAN_NUMERAL_CHARS = frozenset("IVXLCDM")
+_CAPS_WORD_RE = re.compile(r"[A-Z][A-Z0-9'\u2019-]*")
+
+
+def simplify_heading_text(text: str) -> str:
+    raw = str(text or "").strip().lower()
+    if not raw:
+        return ""
+    simplified = _HEADING_SANITIZE_RE.sub("", raw)
+    if simplified.startswith("chapter"):
+        simplified = simplified[7:]
+    return simplified
+
+
+def headings_equivalent(left: str, right: str) -> bool:
+    simple_left = simplify_heading_text(left)
+    simple_right = simplify_heading_text(right)
+    if not simple_left or not simple_right:
+        return False
+    if simple_left == simple_right:
+        return True
+    if simple_right.startswith(simple_left):
+        return True
+    if simple_left.startswith(simple_right):
+        return True
+    if len(simple_left) > 5 and simple_left in simple_right:
+        return True
+    return False
+
+
+def strip_duplicate_heading_line(text: str, heading: str) -> Tuple[str, bool]:
+    source_text = str(text or "")
+    if not source_text:
+        return source_text, False
+    normalized_heading = simplify_heading_text(heading)
+    if not normalized_heading:
+        return source_text, False
+    lines = source_text.splitlines()
+    new_lines: List[str] = []
+    removed = False
+    for line in lines:
+        stripped = line.strip()
+        if not removed and stripped:
+            if headings_equivalent(stripped, heading):
+                removed = True
+                continue
+        new_lines.append(line)
+    if not removed:
+        return source_text, False
+    while new_lines and not new_lines[0].strip():
+        new_lines.pop(0)
+    return "\n".join(new_lines), True
+
+
+def normalize_caps_word(word: str) -> str:
+    upper = word.upper()
+    letters = [char for char in upper if char.isalpha()]
+    if not letters:
+        return word
+    if upper in _ACRONYM_ALLOWLIST:
+        return word
+    if len(letters) <= 1:
+        return word
+    if all(char in _ROMAN_NUMERAL_CHARS for char in letters) and len(letters) <= 7:
+        return word
+
+    parts = re.split(r"(['\-\u2019])", word)
+    normalized_parts: List[str] = []
+    for part in parts:
+        if part in {"'", "-", "\u2019"}:
+            normalized_parts.append(part)
+            continue
+        if not part:
+            continue
+        normalized_parts.append(part[0].upper() + part[1:].lower())
+    return "".join(normalized_parts) or word
+
+
+def normalize_chapter_opening_caps(text: str) -> Tuple[str, bool]:
+    if not text:
+        return text, False
+
+    leading_len = len(text) - len(text.lstrip())
+    leading = text[:leading_len]
+    working = text[leading_len:]
+    if not working:
+        return text, False
+
+    builder: List[str] = []
+    pos = 0
+    changed = False
+
+    while pos < len(working):
+        char = working[pos]
+        if char in "\r\n":
+            builder.append(working[pos:])
+            pos = len(working)
+            break
+        if char.isspace():
+            builder.append(char)
+            pos += 1
+            continue
+        if char.islower():
+            builder.append(working[pos:])
+            pos = len(working)
+            break
+        if not char.isalpha():
+            builder.append(char)
+            pos += 1
+            continue
+
+        match = _CAPS_WORD_RE.match(working, pos)
+        if not match:
+            builder.append(char)
+            pos += 1
+            continue
+
+        word = match.group(0)
+        if any(ch.islower() for ch in word):
+            builder.append(working[pos:])
+            pos = len(working)
+            break
+
+        normalized = normalize_caps_word(word)
+        if normalized != word:
+            changed = True
+        builder.append(normalized)
+        pos = match.end()
+
+    if pos < len(working):
+        builder.append(working[pos:])
+
+    if not changed:
+        return text, False
+
+    return leading + "".join(builder), True
+
+
+def format_spoken_chapter_title(title: str, index: int, apply_prefix: bool) -> str:
+    base = str(title or "").strip()
+    if not base:
+        return f"Chapter {index}" if apply_prefix else ""
+    if not apply_prefix:
+        return base
+    lowered = base.lower()
+    if lowered.startswith("chapter") and (len(lowered) == 7 or not lowered[7].isalpha()):
+        return base
+    match = _HEADING_NUMBER_PREFIX_RE.match(base)
+    if match:
+        number = match.group("number") or ""
+        suffix = match.group("suffix") or ""
+        cleaned_suffix = suffix.lstrip(" .,:;-_ \t\u2013\u2014\u00b7\u2022")
+        if cleaned_suffix:
+            return f"Chapter {number}. {cleaned_suffix}"
+        return f"Chapter {number}"
+    return base
+
+
+def apply_chapter_text_transforms(
+    text: str,
+    *,
+    heading_text: str,
+    raw_title: str,
+    strip_heading: bool,
+    normalize_caps: bool,
+) -> Tuple[str, bool, bool]:
+    """Strip duplicate heading and normalize opening caps.
+
+    Returns ``(text, heading_removed, caps_changed)``.
+    The caller is responsible for state updates (pending flags, logging,
+    dict mutation, ``continue``).
+    """
+    heading_removed = False
+    caps_changed = False
+
+    if strip_heading and heading_text:
+        text, heading_removed = strip_duplicate_heading_line(text, heading_text)
+        if not heading_removed and raw_title:
+            match = _HEADING_NUMBER_PREFIX_RE.match(raw_title)
+            if match:
+                number = match.group("number")
+                if number:
+                    text, heading_removed = strip_duplicate_heading_line(text, number)
+
+    if normalize_caps and text:
+        text, caps_changed = normalize_chapter_opening_caps(text)
+
+    return text, heading_removed, caps_changed

abogen/domain/chunk_utils.py

@@ -0,0 +1,76 @@
+"""Chunk processing utilities.
+
+Functions for grouping chunks, recording override usage, and selecting
+text for TTS synthesis.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any, Dict, Iterable, Mapping
+
+from abogen.domain.enums import Language
+from abogen.pronunciation_store import increment_usage
+
+
+def safe_int(value: Any, default: int = 0) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def group_chunks_by_chapter(chunks: Iterable[Dict[str, Any]]) -> Dict[int, List[Dict[str, Any]]]:
+    grouped: Dict[int, List[Dict[str, Any]]] = defaultdict(list)
+    for entry in chunks or []:
+        if not isinstance(entry, dict):
+            continue
+        try:
+            chapter_index = int(entry.get("chapter_index", 0))
+        except (TypeError, ValueError):
+            chapter_index = 0
+        grouped[chapter_index].append(dict(entry))
+
+    for chapter_index, items in grouped.items():
+        items.sort(key=lambda payload: safe_int(payload.get("chunk_index")))
+
+    return grouped
+
+
+def record_override_usage(
+    job: Any,
+    usage_counter: Mapping[str, int],
+    token_map: Mapping[str, str],
+) -> None:
+    if not usage_counter:
+        return
+
+    language = getattr(job, "language", Language.EN_US) or Language.EN_US
+    for normalized, amount in usage_counter.items():
+        if amount <= 0:
+            continue
+        token_value = token_map.get(normalized, normalized)
+        try:
+            increment_usage(language=language, token=token_value, amount=int(amount))
+        except Exception:  # pragma: no cover - defensive logging
+            job.add_log(f"Failed to record usage for override {token_value}", level="warning")
+
+
+def chunk_text_for_tts(entry: Mapping[str, Any]) -> str:
+    """Choose the best source text for synthesis.
+
+    We must prefer the raw chunk text (``text`` / ``original_text``) so
+    manual/pronunciation overrides can match against the original tokens
+    (e.g. censored words like ``Unfu*k``).  ``normalized_text`` may have
+    already been run through ``normalize_for_pipeline``, which can remove
+    punctuation and prevent overrides from triggering.
+    """
+
+    if not isinstance(entry, Mapping):
+        return ""
+    return str(
+        entry.get("text")
+        or entry.get("original_text")
+        or entry.get("normalized_text")
+        or ""
+    ).strip()

abogen/domain/config_types.py

@@ -0,0 +1,52 @@
+"""Domain config types — shared contracts for domain functions.
+
+These dataclasses group parameters that domain functions receive.
+Domain defines them, app layer fills them.
+
+Why here (domain) and not application:
+- build_tts_context() is in domain → needs PronunciationConfig
+- make_subtitle_writer() is in infrastructure → needs SubtitleConfig
+- embed_m4b_metadata() is in infrastructure → needs CoverConfig
+- Domain should not depend on application layer (DIP)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from abogen.domain.enums import SubtitleFormat, SubtitleMode
+
+
+@dataclass(frozen=True)
+class PronunciationConfig:
+    """Pronunciation and normalization override settings.
+
+    Used by build_tts_context() to compile override rules.
+    """
+    pronunciation_overrides: List[Dict[str, Any]] = field(default_factory=list)
+    manual_overrides: List[Dict[str, Any]] = field(default_factory=list)
+    heteronym_overrides: List[Dict[str, Any]] = field(default_factory=list)
+    normalization_overrides: Optional[Dict[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class SubtitleConfig:
+    """Subtitle output settings.
+
+    Used by make_subtitle_writer() and process_and_write_subtitles().
+    """
+    mode: SubtitleMode = SubtitleMode.DISABLED
+    format: SubtitleFormat = SubtitleFormat.SRT
+    max_words: int = 50
+
+
+@dataclass(frozen=True)
+class CoverConfig:
+    """Cover image settings.
+
+    Used by embed_m4b_metadata() and build_epub3_package().
+    """
+    path: Optional[Path] = None
+    mime: Optional[str] = None

abogen/domain/conversion_engine.py

@@ -0,0 +1,241 @@
+"""Shared TTS iteration loop used by both WebUI and PyQt conversion runners.
+
+The core pattern is identical across both UIs:
+
+    for seg in tts_segments(text, backend, voice, speed, split_pattern, current_time):
+        check_cancel()
+        update_progress(seg)
+        write_audio(seg, sink)
+        accumulate_subtitles(seg)
+
+After the loop, the caller processes accumulated subtitle tokens.
+
+This module provides ``run_tts_segment_loop`` which encapsulates that
+iteration, and ``synthesize_text`` which adds normalization on top —
+the single entry point both UIs should call for text-to-speech.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Protocol
+
+from abogen.domain.audio_sink import AudioSink
+from abogen.domain.conversion_pipeline import tts_segments
+from abogen.domain.enums import Language, SubtitleMode
+from abogen.domain.normalization import TTSContext
+from abogen.domain.progress import calc_etr_str
+from abogen.domain.subtitle_generation import process_subtitle_tokens
+
+
+class CancelChecker(Protocol):
+    """Returns True if conversion has been cancelled."""
+    def __call__(self) -> bool: ...
+
+
+@dataclass
+class SegmentStats:
+    """Running statistics updated per TTS segment."""
+    processed_chars: int = 0
+    current_time: float = 0.0
+    etr_start_time: float = field(default_factory=time.time)
+    total_characters: int = 0
+
+
+@dataclass
+class SegmentInfo:
+    """Read-only info about a TTS segment, passed to on_segment callback."""
+    graphemes: str
+    audio: Any
+    tokens: list
+    duration: float
+    chunk_start: float
+
+
+def run_tts_segment_loop(
+    *,
+    text: str,
+    params: SynthParams,
+    backend: Any,
+    voice: Any,
+    speed: float,
+    split_pattern: str,
+    total_steps: Optional[int] = None,
+    chapter_sink: Optional[AudioSink] = None,
+    preview_callback: Optional[Callable[[str], None]] = None,
+    on_segment: Optional[Callable[[SegmentInfo], None]] = None,
+) -> tuple[int, list]:
+    """Run the core TTS segment iteration loop.
+
+    Args:
+        text: Normalized text to synthesize.
+        params: Common synthesis parameters (stats, callbacks, sinks, etc.).
+        backend: TTS pipeline instance (Kokoro or Supertonic).
+        voice: Voice name/id for the backend.
+        speed: Speech speed multiplier.
+        split_pattern: Regex pattern used by the TTS engine for sentence splitting.
+        total_steps: Inference quality steps (Supertonic only, ignored by Kokoro).
+        preview_callback: Called with a short preview string per segment.
+        on_segment: Called with a SegmentInfo for each segment *before*
+            audio is written.  Useful for callers that need per-segment
+            subtitle processing (e.g. PyQt dual-writer pattern).
+            When provided, the default subtitle accumulation is skipped.
+
+    Returns:
+        Tuple of (segment_count, accumulated_subtitle_tokens).
+        The caller is responsible for processing subtitle tokens via
+        ``process_subtitle_tokens`` and writing entries to subtitle writers.
+    """
+    local_segments = 0
+    accumulated_tokens: list[dict] = []
+
+    for seg in tts_segments(
+        text,
+        backend=backend,
+        voice=voice,
+        speed=speed,
+        split_pattern=split_pattern,
+        current_time=params.stats.current_time,
+        total_steps=total_steps,
+    ):
+        if params.check_cancel():
+            break
+
+        local_segments += 1
+        params.stats.processed_chars += len(seg.graphemes)
+
+        # Progress
+        if params.stats.total_characters:
+            percent = min(int(params.stats.processed_chars / params.stats.total_characters * 100), 99)
+        else:
+            percent = 0 if params.stats.processed_chars == 0 else 99
+
+        etr_str = calc_etr_str(
+            time.time() - params.stats.etr_start_time,
+            params.stats.processed_chars,
+            params.stats.total_characters,
+        )
+        params.on_progress(percent, etr_str)
+
+        # Preview / log
+        if preview_callback:
+            preview_callback(seg.graphemes or "[silence]")
+
+        # Per-segment callback (for callers needing segment-level access)
+        if on_segment:
+            info = SegmentInfo(
+                graphemes=seg.graphemes,
+                audio=seg.audio,
+                tokens=list(seg.tokens) if seg.tokens else [],
+                duration=seg.duration,
+                chunk_start=getattr(seg, "chunk_start", params.stats.current_time),
+            )
+            on_segment(info)
+
+        # Write audio
+        if chapter_sink:
+            chapter_sink.write(seg.audio)
+        if params.audio_sink:
+            params.audio_sink.write(seg.audio)
+
+        # Accumulate subtitle tokens (default path; skipped if on_segment handles it)
+        if not on_segment and params.subtitle_mode != SubtitleMode.DISABLED and seg.tokens:
+            accumulated_tokens.extend(seg.tokens)
+
+        # Update timing
+        if params.audio_sink:
+            params.stats.current_time += seg.duration
+
+    return local_segments, accumulated_tokens
+
+
+def process_and_write_subtitles(
+    accumulated_tokens: list[dict],
+    subtitle_writer: Any,
+    *,
+    subtitle: "SubtitleConfig | str",
+    max_subtitle_words: int | None = None,
+    language: Language,
+    use_spacy_segmentation: bool,
+    fallback_end_time: float,
+) -> None:
+    """Process accumulated subtitle tokens and write entries to a subtitle writer.
+
+    Accepts a SubtitleConfig object or a subtitle mode string
+    for backward compatibility.
+    """
+    from abogen.domain.config_types import SubtitleConfig
+
+    if isinstance(subtitle, SubtitleConfig):
+        mode_str = subtitle.mode.value
+        words = subtitle.max_words
+    else:
+        mode_str = subtitle
+        words = max_subtitle_words or 50
+
+    if not accumulated_tokens or not subtitle_writer:
+        return
+    new_entries: list[tuple] = []
+    process_subtitle_tokens(
+        accumulated_tokens,
+        new_entries,
+        words,
+        mode_str,
+        language,
+        use_spacy_segmentation=use_spacy_segmentation,
+        fallback_end_time=fallback_end_time,
+    )
+    for start, end, text in new_entries:
+        subtitle_writer.write_entry(start=start, end=end, text=text)
+
+
+@dataclass(frozen=True)
+class SynthParams:
+    """Common parameters for synthesize_text calls.
+
+    Packed once by the executor to avoid repeating identical kwargs.
+    When adding new common params, change only this dataclass.
+    """
+    tts_context: TTSContext
+    stats: SegmentStats
+    check_cancel: CancelChecker
+    on_progress: Callable[[int, str], None]
+    audio_sink: Optional[AudioSink] = None
+    subtitle_mode: str = "Disabled"
+    max_subtitle_words: int = 50
+    language: Language = Language.EN_US
+    use_spacy_segmentation: bool = False
+
+
+def synthesize_text(
+    *,
+    text: str,
+    params: SynthParams,
+    backend: Any,
+    voice: Any,
+    speed: float,
+    total_steps: Optional[int] = None,
+    chapter_sink: Optional[AudioSink] = None,
+    preview_callback: Optional[Callable[[str], None]] = None,
+    on_segment: Optional[Callable[[SegmentInfo], None]] = None,
+    split_pattern_override: Optional[str] = None,
+) -> tuple[int, list]:
+    """Normalize text and run TTS — the single entry point for both UIs.
+
+    Combines TTSContext.normalize() + run_tts_segment_loop() into one call.
+    UI-specific concerns (provider resolution, progress display) stay in the UI.
+    """
+    normalized = params.tts_context.normalize(text)
+    return run_tts_segment_loop(
+        text=normalized,
+        params=params,
+        backend=backend,
+        voice=voice,
+        speed=speed,
+        total_steps=total_steps,
+        split_pattern=split_pattern_override or params.tts_context.split_pattern,
+        chapter_sink=chapter_sink,
+        preview_callback=preview_callback,
+        on_segment=on_segment,
+    )

abogen/domain/conversion_pipeline.py

@@ -0,0 +1,372 @@
+"""Shared TTS emission pipeline.
+
+Provides the core TTS emission loop used by both WebUI and PyQt conversion runners.
+The caller handles audio I/O, progress reporting, and subtitle writing.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from abogen.domain.enums import Language, SubtitleMode
+from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple
+
+import numpy as np
+
+from abogen.domain.audio_helpers import to_float32
+from abogen.domain.normalization import prepare_text_for_tts
+from abogen.domain.tokens import FakeToken
+from abogen.domain.audio_buffer import SAMPLE_RATE
+
+logger = logging.getLogger(__name__)
+
+# Languages where spaCy is used for pre-TTS segmentation
+# English ("a", "b") is excluded — spaCy only used for post-TTS subtitles
+_SPACY_EXCLUDED_LANGS = {Language.EN_US, Language.EN_GB}
+
+# CJK languages — different spacing pattern
+_CJK_LANGS = {Language.ZH, Language.JA}
+
+
+def spacy_pre_tts_segmentation(
+    text: str,
+    lang_code: Any,
+    subtitle_mode: Any,
+    *,
+    is_subtitle_input: bool = False,
+    use_spacy_segmentation: bool = True,
+    log_callback: Optional[Callable[[str], None]] = None,
+) -> Tuple[List[str], str]:
+    """Segment text using spaCy before TTS, with split_pattern override.
+
+    For non-English languages, spaCy sentence segmentation produces better
+    sentence boundaries than regex. This function:
+    1. Checks if spaCy should be used (toggle on, not disabled mode, not subtitle input)
+    2. For non-English: runs spaCy segmentation, computes split_pattern override
+    3. For English: returns single segment with default pattern (spaCy only for subtitles)
+    4. If spaCy fails: falls back to default pattern
+
+    Args:
+        text: Text to segment.
+        lang_code: Language code (Language enum or string like "a", "de", "fr").
+        subtitle_mode: SubtitleMode enum or string.
+        is_subtitle_input: True if source is .srt/.ass/.vtt file.
+        use_spacy_segmentation: User toggle for spaCy segmentation.
+        log_callback: Optional logging function.
+
+    Returns:
+        Tuple of (text_segments, active_split_pattern).
+        text_segments is a list of sentences (always at least one element).
+        active_split_pattern is the regex to use for TTS backend splitting.
+    """
+    from abogen.domain.split_pattern import get_split_pattern
+
+    def _log(msg: str) -> None:
+        if log_callback:
+            log_callback(msg)
+
+    # Normalize language
+    lang_enum = _to_language_enum(lang_code)
+
+    # Default split pattern
+    default_split = get_split_pattern(lang_code, subtitle_mode)
+
+    # Check conditions
+    if not use_spacy_segmentation:
+        return [text], default_split
+
+    subtitle_mode_str = _to_subtitle_mode_str(subtitle_mode)
+    if subtitle_mode_str in ("Disabled", "Line"):
+        return [text], default_split
+
+    if is_subtitle_input:
+        return [text], default_split
+
+    # English: spaCy only for post-TTS subtitles, not pre-TTS
+    if lang_enum in _SPACY_EXCLUDED_LANGS:
+        return [text], default_split
+
+    # Non-English: run spaCy pre-TTS segmentation
+    from abogen.spacy_utils import segment_sentences
+
+    _log("Using spaCy for sentence segmentation (pre-TTS)...")
+    spacy_sentences = segment_sentences(text, lang_code, log_callback=log_callback)
+
+    if not spacy_sentences:
+        _log("spaCy: Fallback to default segmentation...")
+        return [text], default_split
+
+    _log(f"spaCy: Text segmented into {len(spacy_sentences)} sentences...")
+
+    # spaCy already split at sentence boundaries; the engine only needs to
+    # split on newlines. Commas are never used in the engine split pattern
+    # for non-English (Sentence + Comma splits at commas only at subtitle
+    # time, like English).
+    active_split = "\n"
+
+    return spacy_sentences, active_split
+
+
+def _to_language_enum(lang_code: Any) -> Language:
+    """Convert lang_code to Language enum (ISO code or Language enum)."""
+    if isinstance(lang_code, Language):
+        return lang_code
+    try:
+        return Language.from_str(str(lang_code))
+    except ValueError:
+        return Language.EN_US
+
+
+def _to_subtitle_mode_str(subtitle_mode: Any) -> str:
+    """Convert subtitle_mode to string."""
+    if isinstance(subtitle_mode, SubtitleMode):
+        return subtitle_mode.value
+    return str(subtitle_mode)
+
+
+@dataclass
+class SegmentResult:
+    """One TTS segment emitted by the pipeline."""
+    graphemes: str
+    audio: np.ndarray
+    duration: float
+    chunk_start: float
+    tokens: List[Dict[str, Any]] = field(default_factory=list)
+
+
+def tts_segments(
+    text: str,
+    *,
+    backend: Any,
+    voice: Any,
+    speed: float,
+    split_pattern: str,
+    current_time: float = 0.0,
+    total_steps: Optional[int] = None,
+) -> Iterator[SegmentResult]:
+    """Invoke TTS backend on (already normalized) text and yield SegmentResults.
+
+    Use this when you've already normalized the text yourself (e.g. after
+    spaCy sentence segmentation). For raw text, use emit_text_segments() instead.
+
+    Args:
+        text: Already-normalized text to synthesize.
+        backend: TTS pipeline callable.
+        voice: Resolved voice.
+        speed: TTS speed multiplier.
+        split_pattern: Regex pattern for sentence splitting.
+        current_time: Current position in the audio timeline (seconds).
+        total_steps: Inference quality steps (Supertonic only, ignored by Kokoro).
+
+    Yields:
+        SegmentResult for each non-empty TTS segment.
+    """
+    kwargs: dict[str, Any] = dict(
+        voice=voice,
+        speed=speed,
+        split_pattern=split_pattern,
+    )
+    if total_steps is not None:
+        kwargs["total_steps"] = total_steps
+
+    segment_iter = backend(text, **kwargs)
+
+    chunk_start = current_time
+    prev_tokens: Optional[List[Dict[str, Any]]] = None
+    prev_was_fallback = True
+
+    for segment in segment_iter:
+        graphemes_raw = getattr(segment, "graphemes", "") or ""
+        graphemes = graphemes_raw.strip()
+
+        audio = to_float32(getattr(segment, "audio", None))
+        if audio.size == 0:
+            continue
+
+        duration = len(audio) / SAMPLE_RATE
+
+        tokens_list = getattr(segment, "tokens", [])
+        was_fallback = False
+        if not tokens_list and graphemes:
+            tokens_list = [FakeToken(graphemes, 0, duration)]
+            was_fallback = True
+
+        tokens = [
+            {
+                "start": chunk_start + (tok.start_ts or 0),
+                "end": chunk_start + (tok.end_ts or 0),
+                "text": tok.text,
+                "whitespace": tok.whitespace,
+            }
+            for tok in tokens_list
+        ]
+
+        # When the engine splits text on a punctuation pattern, the
+        # whitespace between segments is consumed by the split. Restore a
+        # trailing space on the boundary token of the previous segment so
+        # subtitle processing sees the original spacing (only for real
+        # per-word tokens; FakeToken fallbacks split via their own logic).
+        if (
+            not prev_was_fallback
+            and prev_tokens
+            and not prev_tokens[-1].get("whitespace")
+        ):
+            prev_tokens[-1]["whitespace"] = " "
+
+        yield SegmentResult(
+            graphemes=graphemes,
+            audio=audio,
+            duration=duration,
+            chunk_start=chunk_start,
+            tokens=tokens,
+        )
+
+        prev_tokens = tokens
+        prev_was_fallback = was_fallback
+        chunk_start += duration
+
+
+def emit_text_segments(
+    text: str,
+    *,
+    backend: Any,
+    voice: Any,
+    speed: float,
+    split_pattern: str,
+    current_time: float = 0.0,
+    total_steps: Optional[int] = None,
+    # normalization
+    heteronym_rules: Any = None,
+    pronunciation_rules: Any = None,
+    normalization_overrides: Any = None,
+    usage_counter: Optional[Dict[str, int]] = None,
+) -> Iterator[SegmentResult]:
+    """Normalize text and yield SegmentResults from the TTS backend.
+
+    This is the innermost TTS emission loop shared by both UIs. It handles:
+    1. Text normalization (heteronym + pronunciation rules)
+    2. TTS backend invocation
+    3. Segment iteration with token extraction
+
+    The caller is responsible for:
+    - Writing audio to sinks
+    - Accumulating tokens for subtitle processing
+    - Progress tracking and cancellation
+    - Error handling
+
+    Args:
+        text: Raw text to synthesize.
+        backend: TTS pipeline callable (kokoro or supertonic).
+        voice: Resolved voice for TTS.
+        speed: TTS speed multiplier.
+        split_pattern: Regex pattern for sentence splitting.
+        current_time: Current position in the audio timeline (seconds).
+        heteronym_rules: Compiled heteronym rules.
+        pronunciation_rules: Compiled pronunciation rules.
+        normalization_overrides: User normalization overrides.
+        usage_counter: Counter for normalization statistics.
+
+    Yields:
+        SegmentResult for each non-empty TTS segment.
+    """
+    source_text = str(text or "")
+    normalized = prepare_text_for_tts(
+        source_text,
+        heteronym_rules=heteronym_rules,
+        pronunciation_rules=pronunciation_rules,
+        normalization_overrides=normalization_overrides,
+        usage_counter=usage_counter,
+    )
+
+    yield from tts_segments(
+        normalized,
+        backend=backend,
+        voice=voice,
+        speed=speed,
+        split_pattern=split_pattern,
+        current_time=current_time,
+        total_steps=total_steps,
+    )
+
+
+def emit_text_to_sinks(
+    text: str,
+    *,
+    backend: Any,
+    voice: Any,
+    speed: float,
+    split_pattern: str,
+    current_time: float = 0.0,
+    # sinks
+    audio_sink: Any = None,
+    chapter_sink: Any = None,
+    # subtitle
+    subtitle_writer: Any = None,
+    subtitle_mode: str = "Disabled",
+    subtitle_lang: Language = Language.EN_US,
+    max_subtitle_words: int = 50,
+    use_spacy_segmentation: bool = True,
+    # normalization
+    heteronym_rules: Any = None,
+    pronunciation_rules: Any = None,
+    normalization_overrides: Any = None,
+    usage_counter: Optional[Dict[str, int]] = None,
+) -> tuple[int, float, List[Dict[str, Any]]]:
+    """Emit TTS audio for text, writing to sinks and collecting subtitle tokens.
+
+    Convenience wrapper around emit_text_segments() that handles audio writing
+    and token accumulation. Returns stats for the caller to update progress.
+
+    Returns:
+        Tuple of (segments_emitted, new_current_time, accumulated_tokens).
+    """
+    from abogen.domain.subtitle_generation import process_subtitle_tokens
+
+    segments_emitted = 0
+    accumulated_tokens: List[Dict[str, Any]] = []
+
+    for seg in emit_text_segments(
+        text,
+        backend=backend,
+        voice=voice,
+        speed=speed,
+        split_pattern=split_pattern,
+        current_time=current_time,
+        heteronym_rules=heteronym_rules,
+        pronunciation_rules=pronunciation_rules,
+        normalization_overrides=normalization_overrides,
+        usage_counter=usage_counter,
+    ):
+        segments_emitted += 1
+
+        # Write audio
+        if chapter_sink:
+            chapter_sink.write(seg.audio)
+        if audio_sink:
+            audio_sink.write(seg.audio)
+
+        # Collect tokens
+        accumulated_tokens.extend(seg.tokens)
+
+    # Flush subtitle tokens
+    if subtitle_writer and accumulated_tokens:
+        _use_spacy = subtitle_mode not in (SubtitleMode.DISABLED, SubtitleMode.LINE)
+        new_entries: List[tuple] = []
+        process_subtitle_tokens(
+            accumulated_tokens,
+            new_entries,
+            max_subtitle_words,
+            subtitle_mode,
+            subtitle_lang,
+            use_spacy_segmentation=_use_spacy,
+            fallback_end_time=current_time + sum(t["end"] - t["start"] for t in accumulated_tokens if accumulated_tokens),
+        )
+        for start, end, text_entry in new_entries:
+            subtitle_writer.write_entry(start=start, end=end, text=text_entry)
+
+    new_time = current_time
+    if accumulated_tokens:
+        new_time = max(t["end"] for t in accumulated_tokens)
+
+    return segments_emitted, new_time, accumulated_tokens

abogen/domain/device.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import platform as _platform
+
+
+def select_device() -> str:
+    """Return the best available compute device (``"mps"``, ``"cuda"``, or ``"cpu"``).
+
+    Checks ``torch`` availability at runtime so this can be called from
+    any context without requiring torch at import time.
+    """
+    try:
+        import torch  # type: ignore[import-not-found]
+    except Exception:
+        return "cpu"
+
+    system = _platform.system()
+    if system == "Darwin" and _platform.processor() == "arm":
+        try:
+            if torch.backends.mps.is_available():  # type: ignore[union-attr]
+                return "mps"
+        except Exception:
+            pass
+        return "cpu"
+
+    try:
+        if torch.cuda.is_available():  # type: ignore[union-attr]
+            return "cuda"
+    except Exception:
+        pass
+    return "cpu"

abogen/domain/enums.py

@@ -0,0 +1,231 @@
+"""Domain enums — typed constants for values tied to business logic.
+
+Using Enum instead of bare strings ensures:
+- Invalid values are caught at construction time
+- IDE autocomplete and type checking work
+- Adding new values is explicit (must update Enum)
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+
+
+class SubtitleMode(str, Enum):
+    """Subtitle generation mode."""
+    DISABLED = "Disabled"
+    LINE = "Line"
+    SENTENCE = "Sentence"
+    SENTENCE_COMMA = "Sentence + Comma"
+    SENTENCE_HIGHLIGHT = "Sentence + Highlighting"
+
+    @classmethod
+    def from_str(cls, value: str) -> SubtitleMode:
+        """Parse from user input: case-insensitive, strips whitespace."""
+        normalized = value.strip()
+        for member in cls:
+            if member.value.lower() == normalized.lower():
+                return member
+        raise ValueError(f"Invalid SubtitleMode: {value!r}. Valid: {[m.value for m in cls]}")
+
+
+class OutputFormat(str, Enum):
+    """Audio output format."""
+    WAV = "wav"
+    MP3 = "mp3"
+    FLAC = "flac"
+    OPUS = "opus"
+    M4B = "m4b"
+
+    @property
+    def dot_ext(self) -> str:
+        """File extension with dot: '.wav', '.mp3', etc."""
+        return f".{self.value}"
+
+    @property
+    def is_lossless(self) -> bool:
+        """True for lossless formats."""
+        return self in (self.WAV, self.FLAC)
+
+    @classmethod
+    def from_str(cls, value: str) -> OutputFormat:
+        """Parse from user input: strips dot prefix, case-insensitive."""
+        normalized = value.strip().lstrip(".").lower()
+        for member in cls:
+            if member.value == normalized:
+                return member
+        raise ValueError(f"Invalid OutputFormat: {value!r}. Valid: {[m.value for m in cls]}")
+
+
+class SaveMode(str, Enum):
+    """Where to save the output file."""
+    SAVE_NEXT_TO_INPUT = "save_next_to_input"
+    SAVE_TO_DESKTOP = "save_to_desktop"
+    CHOOSE_OUTPUT_FOLDER = "choose_output_folder"
+    DEFAULT_OUTPUT = "default_output"
+    CUSTOM_FOLDER = "custom_folder"
+
+
+class SubtitleFormat(str, Enum):
+    """Subtitle file format."""
+    SRT = "srt"
+    ASS = "ass"
+    VTT = "vtt"
+
+    @property
+    def dot_ext(self) -> str:
+        """File extension with dot: '.srt', '.ass'."""
+        return f".{self.value}"
+
+    @classmethod
+    def from_str(cls, value: str) -> SubtitleFormat:
+        """Parse from user input: strips dot prefix, case-insensitive."""
+        normalized = value.strip().lstrip(".").lower()
+        for member in cls:
+            if member.value == normalized:
+                return member
+        raise ValueError(f"Invalid SubtitleFormat: {value!r}. Valid: {[m.value for m in cls]}")
+
+
+class InputFormat(str, Enum):
+    """Input file format."""
+    EPUB = "epub"
+    PDF = "pdf"
+    TXT = "txt"
+    MD = "md"
+    SRT = "srt"
+    ASS = "ass"
+    VTT = "vtt"
+
+    @property
+    def is_book(self) -> bool:
+        """True for book/document formats (epub, pdf, txt, md)."""
+        return self in (self.EPUB, self.PDF, self.TXT, self.MD)
+
+    @property
+    def is_subtitle(self) -> bool:
+        """True for subtitle formats (srt, ass, vtt)."""
+        return self in (self.SRT, self.ASS, self.VTT)
+
+    @property
+    def dot_ext(self) -> str:
+        """File extension with dot: '.epub', '.srt', etc."""
+        return f".{self.value}"
+
+    @classmethod
+    def from_path(cls, path: Path) -> InputFormat:
+        """Detect format from file path extension."""
+        suffix = path.suffix.lower().lstrip(".")
+        if suffix == "markdown":
+            return cls.MD
+        try:
+            return cls(suffix)
+        except ValueError:
+            raise ValueError(f"Unsupported input format: {path.suffix!r}. Supported: {[m.value for m in cls]}")
+
+
+class Language(str, Enum):
+    """TTS language code (ISO 639-1 with region where needed).
+
+    Each engine maps these to its own internal language identifiers.
+    Engines report which languages they support via ``supported_languages()``.
+    """
+    EN_US = "en-US"
+    EN_GB = "en-GB"
+    ES = "es"
+    FR = "fr"
+    HI = "hi"
+    IT = "it"
+    JA = "ja"
+    PT_BR = "pt-BR"
+    ZH = "zh"
+    AR = "ar"
+    BG = "bg"
+    CS = "cs"
+    DA = "da"
+    DE = "de"
+    EL = "el"
+    ET = "et"
+    FI = "fi"
+    HR = "hr"
+    HU = "hu"
+    ID = "id"
+    KO = "ko"
+    LT = "lt"
+    LV = "lv"
+    NL = "nl"
+    PL = "pl"
+    RO = "ro"
+    RU = "ru"
+    SK = "sk"
+    SL = "sl"
+    SV = "sv"
+    TR = "tr"
+    UK = "uk"
+    VI = "vi"
+
+    @property
+    def display_name(self) -> str:
+        """Human-readable language name."""
+        _names = {
+            "en-US": "American English",
+            "en-GB": "British English",
+            "es": "Spanish",
+            "fr": "French",
+            "hi": "Hindi",
+            "it": "Italian",
+            "ja": "Japanese",
+            "pt-BR": "Brazilian Portuguese",
+            "zh": "Mandarin Chinese",
+            "ar": "Arabic",
+            "bg": "Bulgarian",
+            "cs": "Czech",
+            "da": "Danish",
+            "de": "German",
+            "el": "Greek",
+            "et": "Estonian",
+            "fi": "Finnish",
+            "hr": "Croatian",
+            "hu": "Hungarian",
+            "id": "Indonesian",
+            "ko": "Korean",
+            "lt": "Lithuanian",
+            "lv": "Latvian",
+            "nl": "Dutch",
+            "pl": "Polish",
+            "ro": "Romanian",
+            "ru": "Russian",
+            "sk": "Slovak",
+            "sl": "Slovenian",
+            "sv": "Swedish",
+            "tr": "Turkish",
+            "uk": "Ukrainian",
+            "vi": "Vietnamese",
+        }
+        return _names[self.value]
+
+    @property
+    def is_cjk(self) -> bool:
+        """True for CJK languages (Chinese, Japanese, Korean)."""
+        return self in (self.ZH, self.JA, self.KO)
+
+    @property
+    def supports_subtitle_tokens(self) -> bool:
+        """True if this language supports subtitle generation.
+
+        All languages are supported: languages without per-word timestamped
+        tokens fall back to segment-level fake tokens in the pipeline.
+        """
+        return True
+
+    @classmethod
+    def from_str(cls, value: str) -> Language:
+        """Parse from user input: ISO code, case-insensitive."""
+        if isinstance(value, Language):
+            return value
+        normalized = value.strip()
+        for member in cls:
+            if member.value.lower() == normalized.lower():
+                return member
+        raise ValueError(f"Invalid Language: {value!r}. Valid: {[m.value for m in cls]}")

abogen/domain/file_type.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+from abogen.text_extractor import ExtractedChapter
+
+
+_SIGNIFICANT_LENGTH_THRESHOLDS: Dict[str, int] = {"epub": 1000, "markdown": 500}
+_MIN_SHORT_CONTENT: Dict[str, int] = {"epub": 240, "markdown": 160}
+_STRUCTURAL_KEYWORDS = (
+    "preface",
+    "prologue",
+    "introduction",
+    "foreword",
+    "epilogue",
+    "afterword",
+    "appendix",
+    "acknowledgment",
+    "acknowledgement",
+)
+_STRUCTURAL_MIN_LENGTH = 120
+_MAX_SHORT_CHAPTERS = 2
+
+
+@dataclass
+class ChapterFilterResult:
+    kept: List[ExtractedChapter]
+    skipped: List[Tuple[str, int]]
+
+
+def infer_file_type(path: Path) -> str:
+    suffix = path.suffix.lower()
+    if suffix == ".epub":
+        return "epub"
+    if suffix in {".md", ".markdown"}:
+        return "markdown"
+    if suffix == ".pdf":
+        return "pdf"
+    if suffix == ".txt":
+        return "text"
+    return suffix.lstrip(".") or "text"
+
+
+def looks_structural(title: str) -> bool:
+    lowered = title.strip().lower()
+    if not lowered:
+        return False
+    return any(keyword in lowered for keyword in _STRUCTURAL_KEYWORDS)
+
+
+def chapter_label(file_type: str) -> str:
+    return "chapters" if file_type.lower() in {"epub", "markdown"} else "pages"
+
+
+def auto_select_relevant_chapters(
+    chapters: List[ExtractedChapter],
+    file_type: str,
+) -> ChapterFilterResult:
+    if not chapters:
+        return ChapterFilterResult(kept=[], skipped=[])
+
+    normalized = file_type.lower()
+    threshold = _SIGNIFICANT_LENGTH_THRESHOLDS.get(normalized, 0)
+    min_short = _MIN_SHORT_CONTENT.get(normalized, 0)
+
+    kept: List[ExtractedChapter] = []
+    skipped: List[Tuple[str, int]] = []
+    short_kept = 0
+
+    for chapter in chapters:
+        stripped = chapter.text.strip()
+        length = len(stripped)
+        if length == 0:
+            skipped.append((chapter.title, length))
+            continue
+
+        keep = False
+        if threshold == 0:
+            keep = True
+        elif length >= threshold:
+            keep = True
+        elif not kept:
+            keep = True
+        elif min_short and length >= min_short and short_kept < _MAX_SHORT_CHAPTERS:
+            keep = True
+            short_kept += 1
+        elif looks_structural(chapter.title) and length >= _STRUCTURAL_MIN_LENGTH:
+            keep = True
+
+        if keep:
+            kept.append(chapter)
+        else:
+            skipped.append((chapter.title, length))
+
+    if kept:
+        return ChapterFilterResult(kept=kept, skipped=skipped)
+
+    longest_idx = None
+    longest_length = 0
+    for idx, chapter in enumerate(chapters):
+        stripped = chapter.text.strip()
+        if stripped and len(stripped) > longest_length:
+            longest_length = len(stripped)
+            longest_idx = idx
+
+    if longest_idx is not None:
+        longest = chapters[longest_idx]
+        fallback_skipped = [
+            (chapter.title, len(chapter.text.strip()))
+            for idx, chapter in enumerate(chapters)
+            if idx != longest_idx and chapter.text.strip()
+        ]
+        return ChapterFilterResult(kept=[longest], skipped=fallback_skipped)
+
+    return ChapterFilterResult(kept=[], skipped=skipped)
+
+
+def update_metadata_for_chapter_count(
+    metadata: Dict[str, Any], count: int, file_type: str
+) -> None:
+    if not metadata or count <= 0:
+        return
+
+    label = "Chapters" if file_type.lower() in {"epub", "markdown"} else "Pages"
+    metadata["chapter_count"] = str(count)
+
+    pattern = re.compile(r"\(\d+\s+(Chapters?|Pages?)\)")
+    replacement = f"({count} {label})"
+    for key in ("album", "ALBUM"):
+        value = metadata.get(key)
+        if not isinstance(value, str):
+            continue
+        metadata[key] = pattern.sub(replacement, value)

abogen/domain/intro_outro.py

@@ -0,0 +1,83 @@
+"""Intro/outro text building and voice resolution for audiobook conversion.
+
+Both UIs (WebUI and Desktop) need to:
+1. Build intro/outro text from book metadata
+2. Resolve which voice to use for intro/outro synthesis
+
+This module provides the shared domain logic. The actual TTS synthesis
+and audio writing remain UI-specific.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from abogen.domain.title_builder import build_title_intro_text, build_outro_text
+from abogen.domain.voice_resolution import resolve_fallback_voice_spec
+
+
+@dataclass
+class IntroOutroSpec:
+    """Resolved intro or outro specification ready for TTS synthesis."""
+    text: str
+    voice_spec: str
+    enabled: bool
+
+
+def resolve_intro(
+    metadata: Optional[Dict[str, Any]],
+    original_filename: str,
+    read_title_intro: bool,
+    base_voice_spec: str,
+    job_voice: str,
+    voice_cache_keys: list[str],
+) -> IntroOutroSpec:
+    """Resolve the intro specification from job settings and metadata.
+
+    Returns an IntroOutroSpec with text and voice_spec populated,
+    or enabled=False if intro is disabled or text cannot be built.
+    """
+    if not read_title_intro:
+        return IntroOutroSpec(text="", voice_spec="", enabled=False)
+
+    text = build_title_intro_text(metadata, original_filename)
+    if not text:
+        return IntroOutroSpec(text="", voice_spec="", enabled=False)
+
+    voice_spec = resolve_fallback_voice_spec(
+        base_voice_spec, job_voice, voice_cache_keys
+    )
+    if not voice_spec:
+        return IntroOutroSpec(text=text, voice_spec="", enabled=False)
+
+    return IntroOutroSpec(text=text, voice_spec=voice_spec, enabled=True)
+
+
+def resolve_outro(
+    metadata: Optional[Dict[str, Any]],
+    original_filename: str,
+    read_closing_outro: bool,
+    base_voice_spec: str,
+    job_voice: str,
+    voice_cache_keys: list[str],
+) -> IntroOutroSpec:
+    """Resolve the outro specification from job settings and metadata.
+
+    Returns an IntroOutroSpec with text and voice_spec populated,
+    or enabled=False if outro is disabled or text cannot be built.
+    """
+    if not read_closing_outro:
+        return IntroOutroSpec(text="", voice_spec="", enabled=False)
+
+    text = build_outro_text(metadata, original_filename)
+    if not text:
+        return IntroOutroSpec(text="", voice_spec="", enabled=False)
+
+    voice_spec = resolve_fallback_voice_spec(
+        base_voice_spec, job_voice, voice_cache_keys
+    )
+    if not voice_spec:
+        return IntroOutroSpec(text=text, voice_spec="", enabled=False)
+
+    return IntroOutroSpec(text=text, voice_spec=voice_spec, enabled=True)

abogen/domain/metadata_extraction.py

@@ -0,0 +1,503 @@
+"""Metadata extraction and processing utilities.
+
+This module provides functions for extracting metadata from text content,
+formatting metadata tags for TTS embedding, and generating ffmpeg metadata arguments.
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+import os
+import re
+import uuid
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+def extract_metadata_from_text(text: str) -> Dict[str, Optional[str]]:
+    """Extract metadata tags from text content.
+    
+    Looks for tags in format: <<METADATA_KEY:value>>
+    
+    Supported tags:
+    - TITLE, ARTIST, ALBUM, YEAR
+    - ALBUM_ARTIST, COMPOSER, GENRE
+    - COVER_PATH
+    
+    Args:
+        text: Text content to search for metadata tags.
+        
+    Returns:
+        Dictionary with extracted metadata values (None if not found).
+    """
+    metadata = {}
+    
+    patterns = {
+        "title": r"<<METADATA_TITLE:([^>]*)>>",
+        "artist": r"<<METADATA_ARTIST:([^>]*)>>",
+        "album": r"<<METADATA_ALBUM:([^>]*)>>",
+        "year": r"<<METADATA_YEAR:([^>]*)>>",
+        "album_artist": r"<<METADATA_ALBUM_ARTIST:([^>]*)>>",
+        "composer": r"<<METADATA_COMPOSER:([^>]*)>>",
+        "genre": r"<<METADATA_GENRE:([^>]*)>>",
+        "cover_path": r"<<METADATA_COVER_PATH:([^>]*)>>",
+    }
+    
+    for key, pattern in patterns.items():
+        match = re.search(pattern, text)
+        if match:
+            metadata[key] = match.group(1).strip()
+        else:
+            metadata[key] = None
+    
+    return metadata
+
+
+def get_filename_from_path(
+    file_path: str,
+    display_path: Optional[str] = None,
+    from_queue: bool = False,
+) -> str:
+    """Extract filename (without extension) from path.
+    
+    Args:
+        file_path: The file path to extract from.
+        display_path: Optional display path (used if from_queue is False).
+        from_queue: Whether the file is from queue.
+        
+    Returns:
+        Filename without extension.
+    """
+    if from_queue:
+        base_path = file_path
+    else:
+        base_path = display_path if display_path else file_path
+    
+    filename = os.path.splitext(os.path.basename(base_path))[0]
+    return filename
+
+
+def build_ffmpeg_metadata_args(
+    metadata: Dict[str, Optional[str]],
+    filename: str,
+) -> List[str]:
+    """Build ffmpeg metadata arguments from metadata dictionary.
+    
+    Args:
+        metadata: Dictionary with metadata keys and values.
+        filename: Fallback filename for title/album if not specified.
+        
+    Returns:
+        List of ffmpeg metadata arguments.
+    """
+    args = []
+    
+    # Default values
+    defaults = {
+        "title": filename,
+        "artist": "Unknown",
+        "album": filename,
+        "date": str(datetime.datetime.now().year),
+        "album_artist": "Unknown",
+        "composer": "Narrator",
+        "genre": "Audiobook",
+    }
+    
+    # Map of metadata keys to ffmpeg metadata keys
+    key_mapping = {
+        "title": "title",
+        "artist": "artist",
+        "album": "album",
+        "year": "date",  # year -> date for ffmpeg
+        "album_artist": "album_artist",
+        "composer": "composer",
+        "genre": "genre",
+    }
+    
+    for metadata_key, ffmpeg_key in key_mapping.items():
+        value = metadata.get(metadata_key)
+        if value is None:
+            value = defaults.get(metadata_key, "")
+        if value:
+            args.extend(["-metadata", f"{ffmpeg_key}={value}"])
+    
+    return args
+
+
+def extract_metadata_and_build_args(
+    text: str,
+    filename: str,
+    display_path: Optional[str] = None,
+    from_queue: bool = False,
+) -> Tuple[List[str], Optional[str]]:
+    """Extract metadata from text and build ffmpeg arguments.
+    
+    Convenience function that combines extract_metadata_from_text and
+    build_ffmpeg_metadata_args.
+    
+    Args:
+        text: Text content to search for metadata tags.
+        filename: Fallback filename for title/album.
+        display_path: Optional display path.
+        from_queue: Whether the file is from queue.
+        
+    Returns:
+        Tuple of (ffmpeg_metadata_args, cover_path).
+    """
+    metadata = extract_metadata_from_text(text)
+    cover_path = metadata.get("cover_path")
+    
+    # Get actual filename from path
+    actual_filename = get_filename_from_path(
+        file_path=filename,
+        display_path=display_path,
+        from_queue=from_queue,
+    )
+    
+    args = build_ffmpeg_metadata_args(metadata, actual_filename)
+    return args, cover_path
+
+
+def read_text_for_metadata(
+    file_path: str,
+    is_direct_text: bool,
+    direct_text: Optional[str] = None,
+    encoding: Optional[str] = None,
+) -> str:
+    """Read text content for metadata extraction.
+    
+    Args:
+        file_path: Path to file (or text if is_direct_text).
+        is_direct_text: Whether file_path contains direct text.
+        direct_text: Optional direct text (used if is_direct_text).
+        encoding: File encoding (detected if not provided).
+        
+    Returns:
+        Text content for metadata extraction.
+    """
+    if is_direct_text:
+        return direct_text or file_path
+    
+    # Read from file
+    actual_path = direct_text if direct_text else file_path
+    
+    try:
+        if encoding is None:
+            from abogen.utils import detect_encoding
+            encoding = detect_encoding(actual_path)
+        
+        with open(actual_path, "r", encoding=encoding, errors="replace") as f:
+            return f.read()
+    except Exception:
+        return ""
+
+
+def extract_metadata_for_file(
+    file_path: str,
+    is_direct_text: bool = False,
+) -> Dict[str, Optional[str]]:
+    """Extract metadata dict from a file or direct text.
+
+    Convenience function combining read_text_for_metadata + extract_metadata_from_text.
+    Returns empty dict on any error.
+    """
+    try:
+        text = read_text_for_metadata(
+            file_path=file_path,
+            is_direct_text=is_direct_text,
+            direct_text=file_path if is_direct_text else None,
+        )
+        if text:
+            return extract_metadata_from_text(text) or {}
+    except Exception:
+        pass
+    return {}
+
+
+def format_metadata_tags(
+    metadata: Dict[str, Any],
+    filename: str,
+    chapter_count: int,
+    file_type: str,
+    cover_bytes: Optional[bytes] = None,
+    cache_dir: Optional[str] = None,
+) -> str:
+    """Format metadata tags for insertion into TTS text.
+
+    Builds <<METADATA_KEY:value>> tags that are later parsed by
+    extract_metadata_from_text() and fed to ffmpeg.
+
+    Args:
+        metadata: Dict with keys like 'title', 'authors' (list),
+            'publication_year', 'description', 'cover_image' (bytes).
+        filename: Fallback filename (without extension) for title/album.
+        chapter_count: Number of chapters/pages.
+        file_type: 'epub', 'pdf', or 'markdown'.
+        cover_bytes: Optional cover image bytes to save to cache.
+        cache_dir: Directory for cover cache (uses default if None).
+
+    Returns:
+        Newline-joined string of <<METADATA_KEY:value>> tags.
+    """
+    title = metadata.get("title") or filename
+    authors = metadata.get("authors") or ["Unknown"]
+    authors_text = ", ".join(authors) if isinstance(authors, list) else str(authors)
+    year = metadata.get("publication_year") or str(datetime.datetime.now().year)
+
+    chapter_label = "Chapters" if file_type in ("epub", "markdown") else "Pages"
+    chapter_text = f"{chapter_count} {chapter_label}"
+
+    tags = [
+        f"<<METADATA_TITLE:{title}>>",
+        f"<<METADATA_ARTIST:{authors_text}>>",
+        f"<<METADATA_ALBUM:{title} ({chapter_text})>>",
+        f"<<METADATA_YEAR:{year}>>",
+        f"<<METADATA_ALBUM_ARTIST:{authors_text}>>",
+        f"<<METADATA_COMPOSER:Narrator>>",
+        f"<<METADATA_GENRE:Audiobook>>",
+    ]
+
+    cover_path = _save_cover_to_cache(cover_bytes, cache_dir)
+    if cover_path:
+        tags.append(f"<<METADATA_COVER_PATH:{cover_path}>>")
+
+    return "\n".join(tags)
+
+
+def _save_cover_to_cache(
+    cover_bytes: Optional[bytes],
+    cache_dir: Optional[str] = None,
+) -> Optional[str]:
+    """Save cover image bytes to cache directory.
+
+    Args:
+        cover_bytes: Raw image bytes (e.g. JPEG/PNG).
+        cache_dir: Directory to save to. If None, returns None.
+
+    Returns:
+        Normalized path to saved cover file, or None on failure.
+    """
+    if not cover_bytes:
+        return None
+    if cache_dir is None:
+        return None
+
+    try:
+        cover_path = os.path.join(cache_dir, f"cover_{uuid.uuid4()}.jpg")
+        cover_path = os.path.normpath(cover_path)
+        with open(cover_path, "wb") as f:
+            f.write(cover_bytes)
+        return cover_path
+    except Exception as e:
+        logger.warning("Failed to save cover image: %s", e)
+        return None
+
+
+def extract_book_metadata_epub(book: Any) -> Dict[str, Any]:
+    """Extract metadata from an opened ebooklib EPUB book.
+
+    Args:
+        book: An opened ebooklib EPUB book object.
+
+    Returns:
+        Dict with keys: title, authors, description, publisher,
+        publication_year, cover_image (bytes or None).
+    """
+    import ebooklib
+
+    metadata: Dict[str, Any] = {
+        "title": None,
+        "authors": [],
+        "description": None,
+        "cover_image": None,
+        "publisher": None,
+        "publication_year": None,
+    }
+
+    try:
+        title_items = book.get_metadata("DC", "title")
+        if title_items and len(title_items) > 0:
+            metadata["title"] = title_items[0][0]
+    except Exception as e:
+        logger.warning("Error extracting title metadata: %s", e)
+
+    try:
+        author_items = book.get_metadata("DC", "creator")
+        if author_items:
+            metadata["authors"] = [
+                author[0] for author in author_items if len(author) > 0
+            ]
+    except Exception as e:
+        logger.warning("Error extracting author metadata: %s", e)
+
+    try:
+        desc_items = book.get_metadata("DC", "description")
+        if desc_items and len(desc_items) > 0:
+            metadata["description"] = desc_items[0][0]
+    except Exception as e:
+        logger.warning("Error extracting description metadata: %s", e)
+
+    try:
+        publisher_items = book.get_metadata("DC", "publisher")
+        if publisher_items and len(publisher_items) > 0:
+            metadata["publisher"] = publisher_items[0][0]
+    except Exception as e:
+        logger.warning("Error extracting publisher metadata: %s", e)
+
+    try:
+        date_items = book.get_metadata("DC", "date")
+        if date_items and len(date_items) > 0:
+            date_str = date_items[0][0]
+            year_match = re.search(r"\b(19|20)\d{2}\b", date_str)
+            if year_match:
+                metadata["publication_year"] = year_match.group(0)
+            else:
+                metadata["publication_year"] = date_str
+    except Exception as e:
+        logger.warning("Error extracting publication date metadata: %s", e)
+
+    for item in book.get_items_of_type(ebooklib.ITEM_COVER):
+        metadata["cover_image"] = item.get_content()
+        break
+
+    if not metadata["cover_image"]:
+        for item in book.get_items_of_type(ebooklib.ITEM_IMAGE):
+            if "cover" in item.get_name().lower():
+                metadata["cover_image"] = item.get_content()
+                break
+
+    return metadata
+
+
+def extract_book_metadata_pdf(pdf_doc: Any) -> Dict[str, Any]:
+    """Extract metadata from an opened PyMuPDF document.
+
+    Args:
+        pdf_doc: An opened fitz.Document object.
+
+    Returns:
+        Dict with keys: title, authors, description, publisher,
+        publication_year, cover_image (bytes or None).
+    """
+    metadata: Dict[str, Any] = {
+        "title": None,
+        "authors": [],
+        "description": None,
+        "cover_image": None,
+        "publisher": None,
+        "publication_year": None,
+    }
+
+    pdf_info = pdf_doc.metadata
+    if pdf_info:
+        metadata["title"] = pdf_info.get("title", None)
+        author = pdf_info.get("author", None)
+        if author:
+            metadata["authors"] = [author]
+        metadata["description"] = pdf_info.get("subject", None)
+        keywords = pdf_info.get("keywords", None)
+        if keywords:
+            if metadata["description"]:
+                metadata["description"] += f"\n\nKeywords: {keywords}"
+            else:
+                metadata["description"] = f"Keywords: {keywords}"
+        metadata["publisher"] = pdf_info.get("creator", None)
+
+        if "creationDate" in pdf_info:
+            date_str = pdf_info["creationDate"]
+            year_match = re.search(r"D:(\d{4})", date_str)
+            if year_match:
+                metadata["publication_year"] = year_match.group(1)
+        elif "modDate" in pdf_info:
+            date_str = pdf_info["modDate"]
+            year_match = re.search(r"D:(\d{4})", date_str)
+            if year_match:
+                metadata["publication_year"] = year_match.group(1)
+
+    if len(pdf_doc) > 0:
+        try:
+            import fitz
+            pix = pdf_doc[0].get_pixmap(matrix=fitz.Matrix(2, 2))
+            metadata["cover_image"] = pix.tobytes("png")
+        except Exception:
+            pass
+
+    return metadata
+
+
+def extract_book_metadata_markdown(
+    markdown_text: str,
+    markdown_toc: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """Extract metadata from markdown frontmatter and first heading.
+
+    Args:
+        markdown_text: Raw markdown text content.
+        markdown_toc: Optional table of contents list (each item has
+            'level' and 'name' keys).
+
+    Returns:
+        Dict with keys: title, authors, description, publication_year.
+        cover_image is always None for markdown.
+    """
+    metadata: Dict[str, Any] = {
+        "title": None,
+        "authors": [],
+        "description": None,
+        "cover_image": None,
+        "publisher": None,
+        "publication_year": None,
+    }
+
+    if not markdown_text:
+        return metadata
+
+    frontmatter_match = re.match(
+        r"^---\s*\n(.*?)\n---\s*\n", markdown_text, re.DOTALL
+    )
+    if frontmatter_match:
+        try:
+            frontmatter = frontmatter_match.group(1)
+            title_match = re.search(
+                r"^title:\s*(.+)$", frontmatter, re.MULTILINE | re.IGNORECASE
+            )
+            if title_match:
+                metadata["title"] = title_match.group(1).strip().strip("\"'")
+
+            author_match = re.search(
+                r"^author:\s*(.+)$", frontmatter, re.MULTILINE | re.IGNORECASE
+            )
+            if author_match:
+                metadata["authors"] = [
+                    author_match.group(1).strip().strip("\"'")
+                ]
+
+            desc_match = re.search(
+                r"^description:\s*(.+)$", frontmatter, re.MULTILINE | re.IGNORECASE
+            )
+            if desc_match:
+                metadata["description"] = (
+                    desc_match.group(1).strip().strip("\"'")
+                )
+
+            date_match = re.search(
+                r"^date:\s*(.+)$", frontmatter, re.MULTILINE | re.IGNORECASE
+            )
+            if date_match:
+                date_str = date_match.group(1).strip().strip("\"'")
+                year_match = re.search(r"\b(19|20)\d{2}\b", date_str)
+                if year_match:
+                    metadata["publication_year"] = year_match.group(0)
+        except Exception as e:
+            logger.warning("Error parsing markdown frontmatter: %s", e)
+
+    if not metadata["title"] and markdown_toc:
+        first_h1 = next(
+            (h for h in markdown_toc if h.get("level") == 1), None
+        )
+        if first_h1:
+            metadata["title"] = first_h1.get("name")
+
+    return metadata

abogen/domain/metadata_helpers.py

@@ -0,0 +1,496 @@
+from __future__ import annotations
+
+import json
+import math
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+
+
+_SERIES_NAME_KEYS = (
+    "series",
+    "series_name",
+    "series_title",
+)
+_SERIES_NUMBER_KEYS = (
+    "series_index",
+    "series_position",
+    "series_sequence",
+    "book_number",
+    "series_number",
+)
+_SERIES_NUMBER_RE = re.compile(r"\d+(?:\.\d+)?")
+
+_SERIES_NAME_ALIASES = ("series", "series_name", "seriesname", "series_title", "seriestitle")
+_SERIES_INDEX_ALIASES = ("series_index", "series_sequence", "series_position", "book_number")
+_AUTHOR_ALIASES = ("author", "authors")
+_DESCRIPTION_ALIASES = ("description", "summary")
+_TAGS_ALIASES = ("tags", "keywords", "genre")
+
+
+def expand_metadata_aliases(tags: Mapping[str, Any]) -> Dict[str, Any]:
+    """Expand concept aliases so each concept has all canonical keys set.
+
+    One input concept fans out to multiple keys so that downstream consumers
+    can look up any variant and find the value.
+
+    Expanded concepts:
+        series     -> series, series_name, seriesname, series_title, seriestitle
+        series_index -> series_index, series_sequence, series_position, book_number
+        author     -> author, authors
+        description -> description, summary
+        tags       -> tags, keywords, genre
+    """
+    if not tags:
+        return {}
+
+    result: Dict[str, Any] = {}
+    for key, value in tags.items():
+        if value is None:
+            continue
+        text = str(value).strip() if not isinstance(value, (list, tuple, set)) else value
+        if not text:
+            continue
+        key_lower = str(key).strip().lower()
+        if not key_lower:
+            continue
+
+        if key_lower in _SERIES_NAME_ALIASES:
+            for alias in _SERIES_NAME_ALIASES:
+                result[alias] = text
+        elif key_lower in _SERIES_INDEX_ALIASES:
+            for alias in _SERIES_INDEX_ALIASES:
+                result[alias] = text
+        elif key_lower in _AUTHOR_ALIASES:
+            for alias in _AUTHOR_ALIASES:
+                result[alias] = text
+        elif key_lower in _DESCRIPTION_ALIASES:
+            for alias in _DESCRIPTION_ALIASES:
+                result[alias] = text
+        elif key_lower in _TAGS_ALIASES:
+            for alias in _TAGS_ALIASES:
+                result[alias] = text
+        else:
+            result[key_lower] = text
+
+    return result
+
+
+def normalize_metadata_map(values: Optional[Mapping[str, Any]]) -> Dict[str, str]:
+    normalized: Dict[str, str] = {}
+    if not values:
+        return normalized
+    for key, value in values.items():
+        if value is None:
+            continue
+        text = str(value).strip()
+        if not text:
+            continue
+        normalized[str(key).casefold()] = text
+    return normalized
+
+
+def format_author_sentence(raw: Optional[str]) -> str:
+    if raw is None:
+        return ""
+    normalized = str(raw).strip()
+    if not normalized:
+        return ""
+    lowered = normalized.casefold()
+    if lowered in {"unknown", "various"}:
+        return ""
+
+    working = normalized.replace("&", " and ")
+    segments = [segment.strip() for segment in working.split(",") if segment.strip()]
+    tokens: List[str] = []
+
+    if segments:
+        for segment in segments:
+            parts = [part.strip() for part in re.split(r"\band\b", segment, flags=re.IGNORECASE) if part.strip()]
+            if parts:
+                tokens.extend(parts)
+            else:
+                tokens.append(segment)
+    else:
+        parts = [part.strip() for part in re.split(r"\band\b", working, flags=re.IGNORECASE) if part.strip()]
+        tokens.extend(parts or [normalized])
+
+    cleaned = [token for token in tokens if token and token.casefold() not in {"unknown", "various"}]
+    if not cleaned:
+        return ""
+    if len(cleaned) == 1:
+        return f"By {cleaned[0]}"
+    if len(cleaned) == 2:
+        return f"By {cleaned[0]} and {cleaned[1]}"
+    return f"By {', '.join(cleaned[:-1])}, and {cleaned[-1]}"
+
+
+def ensure_sentence(text: str) -> str:
+    cleaned = text.strip()
+    if not cleaned:
+        return ""
+    if cleaned[-1] in ".!?":
+        return cleaned
+    return f"{cleaned}."
+
+
+def normalize_series_number(value: Any) -> Optional[str]:
+    text = str(value or "").strip()
+    if not text:
+        return None
+    candidate = text.replace(",", ".")
+    if candidate.replace(".", "", 1).isdigit():
+        if "." in candidate:
+            normalized = candidate.rstrip("0").rstrip(".")
+            return normalized or "0"
+        try:
+            return str(int(candidate))
+        except ValueError:
+            pass
+    match = _SERIES_NUMBER_RE.search(candidate)
+    if not match:
+        return None
+    normalized = match.group(0)
+    if "." in normalized:
+        normalized = normalized.rstrip("0").rstrip(".")
+        return normalized or "0"
+    try:
+        return str(int(normalized))
+    except ValueError:
+        return normalized
+
+
+def extract_series_metadata(values: Mapping[str, str]) -> Tuple[Optional[str], Optional[str]]:
+    series_name: Optional[str] = None
+    for key in _SERIES_NAME_KEYS:
+        raw = values.get(key)
+        if raw:
+            cleaned = str(raw).strip()
+            if cleaned:
+                series_name = cleaned
+                break
+
+    series_number: Optional[str] = None
+    for key in _SERIES_NUMBER_KEYS:
+        raw = values.get(key)
+        if raw is None:
+            continue
+        normalized = normalize_series_number(raw)
+        if normalized:
+            series_number = normalized
+            break
+
+    return series_name, series_number
+
+
+def format_series_sentence(series_name: Optional[str], series_number: Optional[str]) -> str:
+    if not series_name or not series_number:
+        return ""
+    name = series_name.strip()
+    number = series_number.strip()
+    if not name or not number:
+        return ""
+    article = "the " if not name.lower().startswith("the ") else ""
+    phrase = f"Book {number} of {article}{name}"
+    return re.sub(r"\s+", " ", phrase).strip()
+
+
+_PEOPLE_SPLIT_RE = re.compile(r"[;,/&]|\band\b", re.IGNORECASE)
+_LIST_SPLIT_RE = re.compile(r"[;,\n]")
+_SERIES_SEQUENCE_TAG_KEYS: Tuple[str, ...] = (
+    "series_index",
+    "series_position",
+    "series_sequence",
+    "series_number",
+    "seriesnumber",
+    "book_number",
+    "booknumber",
+)
+
+
+def normalize_metadata_casefold(values: Optional[Mapping[str, Any]]) -> Dict[str, Any]:
+    normalized: Dict[str, Any] = {}
+    if not values:
+        return normalized
+    for key, value in values.items():
+        if value is None:
+            continue
+        key_text = str(key).strip().lower()
+        if not key_text:
+            continue
+        if isinstance(value, (list, tuple, set)):
+            normalized[key_text] = value
+        else:
+            text = str(value).strip()
+            if text:
+                normalized[key_text] = text
+    return normalized
+
+
+def split_people_field(raw: Any) -> List[str]:
+    if raw is None:
+        return []
+    if isinstance(raw, (list, tuple, set)):
+        results: List[str] = []
+        for item in raw:
+            results.extend(split_people_field(item))
+        return results
+    text = str(raw or "").strip()
+    if not text:
+        return []
+    tokens = [_token.strip() for _token in _PEOPLE_SPLIT_RE.split(text) if _token.strip()]
+    seen: set[str] = set()
+    ordered: List[str] = []
+    for token in tokens:
+        key = token.casefold()
+        if key in seen:
+            continue
+        seen.add(key)
+        ordered.append(token)
+    return ordered
+
+
+def split_simple_list(raw: Any) -> List[str]:
+    if raw is None:
+        return []
+    if isinstance(raw, (list, tuple, set)):
+        results: List[str] = []
+        for item in raw:
+            results.extend(split_simple_list(item))
+        return results
+    text = str(raw or "").strip()
+    if not text:
+        return []
+    tokens = [_token.strip() for _token in _LIST_SPLIT_RE.split(text) if _token.strip()]
+    seen: set[str] = set()
+    ordered: List[str] = []
+    for token in tokens:
+        key = token.casefold()
+        if key in seen:
+            continue
+        seen.add(key)
+        ordered.append(token)
+    return ordered
+
+
+def first_nonempty(*values: Any) -> Optional[str]:
+    for value in values:
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple, set)):
+            items = list(value)
+            if not items:
+                continue
+            value = items[0]
+        text = str(value).strip()
+        if text:
+            return text
+    return None
+
+
+def extract_year(raw: Optional[str]) -> Optional[int]:
+    if not raw:
+        return None
+    text = str(raw).strip()
+    if not text:
+        return None
+    match = re.search(r"(19|20)\d{2}", text)
+    if match:
+        try:
+            return int(match.group(0))
+        except ValueError:
+            return None
+    try:
+        parsed = int(text)
+    except ValueError:
+        return None
+    if 0 < parsed < 3000:
+        return parsed
+    return None
+
+
+def normalize_series_sequence(raw: Any) -> Optional[str]:
+    if raw is None:
+        return None
+    if isinstance(raw, (int, float)):
+        if isinstance(raw, float) and (math.isnan(raw) or math.isinf(raw)):
+            return None
+        text = str(raw)
+    else:
+        text = str(raw).strip()
+    if not text:
+        return None
+    candidate = text.replace(",", ".")
+    match = _SERIES_NUMBER_RE.search(candidate)
+    if not match:
+        return None
+    normalized = match.group(0)
+    if "." in normalized:
+        normalized = normalized.rstrip("0").rstrip(".")
+        if not normalized:
+            normalized = "0"
+        return normalized
+    try:
+        return str(int(normalized))
+    except ValueError:
+        cleaned = normalized.lstrip("0")
+        return cleaned or "0"
+
+
+def build_audiobookshelf_metadata(
+    tags: Mapping[str, Any],
+    *,
+    language: str = "",
+    filename: str = "",
+) -> Dict[str, Any]:
+    normalized = normalize_metadata_casefold(tags)
+    title = first_nonempty(
+        normalized.get("title"),
+        normalized.get("book_title"),
+        normalized.get("name"),
+        normalized.get("album"),
+        filename,
+    )
+    authors = split_people_field(
+        normalized.get("authors")
+        or normalized.get("author")
+        or normalized.get("album_artist")
+        or normalized.get("artist")
+    )
+    narrators = split_people_field(normalized.get("narrators") or normalized.get("narrator"))
+    description = first_nonempty(
+        normalized.get("description"), normalized.get("summary"), normalized.get("comment")
+    )
+    genres = split_simple_list(normalized.get("genre"))
+    keywords = split_simple_list(normalized.get("tags") or normalized.get("keywords"))
+    lang = first_nonempty(normalized.get("language"), normalized.get("lang")) or language or ""
+    series_name = first_nonempty(
+        normalized.get("series"),
+        normalized.get("series_name"),
+        normalized.get("seriesname"),
+        normalized.get("series_title"),
+        normalized.get("seriestitle"),
+    )
+
+    series_sequence = None
+    for key in _SERIES_SEQUENCE_TAG_KEYS:
+        raw_value = normalized.get(key)
+        seq = normalize_series_sequence(raw_value)
+        if seq:
+            series_sequence = seq
+            break
+    if not series_name:
+        series_sequence = None
+
+    data: Dict[str, Any] = {
+        "title": title,
+        "subtitle": normalized.get("subtitle"),
+        "authors": authors,
+        "narrators": narrators,
+        "description": description,
+        "publisher": normalized.get("publisher"),
+        "genres": genres,
+        "tags": keywords,
+        "language": lang,
+        "publishedYear": extract_year(
+            normalized.get("published")
+            or normalized.get("publication_year")
+            or normalized.get("date")
+            or normalized.get("year")
+        ),
+        "seriesName": series_name,
+        "seriesSequence": series_sequence,
+        "isbn": first_nonempty(normalized.get("isbn"), normalized.get("asin")),
+    }
+    published_date = first_nonempty(
+        normalized.get("published"), normalized.get("publication_date"), normalized.get("date")
+    )
+    if published_date:
+        data["publishedDate"] = published_date
+
+    rating_text = first_nonempty(normalized.get("rating"), normalized.get("my_rating"))
+    if rating_text:
+        try:
+            data["rating"] = float(str(rating_text).strip())
+        except ValueError:
+            pass
+        rating_max_text = first_nonempty(
+            normalized.get("rating_max"), normalized.get("rating_scale")
+        )
+        if rating_max_text:
+            try:
+                data["ratingMax"] = float(str(rating_max_text).strip())
+            except ValueError:
+                pass
+
+    cleaned: Dict[str, Any] = {}
+    for key, value in data.items():
+        if value is None:
+            continue
+        if isinstance(value, str) and not value.strip():
+            continue
+        if isinstance(value, (list, tuple)) and not value:
+            continue
+        cleaned[key] = value
+    return cleaned
+
+
+def load_audiobookshelf_chapters(
+    metadata_path: Path,
+) -> Optional[List[Dict[str, Any]]]:
+    if not metadata_path.exists():
+        return None
+    try:
+        payload = json.loads(metadata_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    chapters = payload.get("chapters")
+    if not isinstance(chapters, list):
+        return None
+    cleaned: List[Dict[str, Any]] = []
+    for entry in chapters:
+        if not isinstance(entry, Mapping):
+            continue
+        title = first_nonempty(entry.get("title"), entry.get("original_title"))
+        start = entry.get("start")
+        end = entry.get("end")
+        if title and start is not None and end is not None:
+            cleaned.append({"title": str(title), "start": start, "end": end})
+    return cleaned or None
+
+
+def build_metadata_payload(
+    metadata: Optional[Dict[str, Any]] = None,
+    chapter_markers: Optional[List[Dict[str, Any]]] = None,
+    chunk_markers: Optional[List[Dict[str, Any]]] = None,
+    chunk_level: Optional[str] = None,
+    speaker_mode: Optional[str] = None,
+    speakers: Optional[Dict[str, Any]] = None,
+    generate_epub3: bool = False,
+) -> Dict[str, Any]:
+    """Build the canonical metadata payload dict for persistence and downstream use.
+
+    This is the single source of truth for metadata assembly. Both PyQt and WebUI
+    runners should call this instead of building the dict manually.
+
+    Args:
+        metadata: Normalized metadata tags dict.
+        chapter_markers: List of chapter marker dicts with title/start/end.
+        chunk_markers: List of chunk marker dicts.
+        chunk_level: Chunk granularity level (e.g. 'chapter', 'chunk').
+        speaker_mode: Speaker mode ('single', 'multi', etc.).
+        speakers: Speaker profile mapping.
+        generate_epub3: Whether EPUB3 generation is enabled.
+
+    Returns:
+        Complete metadata payload dict.
+    """
+    return {
+        "metadata": dict(metadata or {}),
+        "chapters": chapter_markers or [],
+        "chunks": chunk_markers or [],
+        "chunk_level": chunk_level,
+        "speaker_mode": speaker_mode,
+        "speakers": dict(speakers or {}),
+        "generate_epub3": generate_epub3,
+    }

abogen/domain/metadata_merge.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+def merge_metadata(
+    extracted: Optional[Dict[str, Any]],
+    overrides: Optional[Dict[str, Any]],
+) -> Dict[str, str]:
+    merged: Dict[str, str] = {}
+    if extracted:
+        for key, value in extracted.items():
+            if value is None:
+                continue
+            merged[str(key)] = str(value)
+    if overrides:
+        for key, value in overrides.items():
+            key_str = str(key)
+            if value is None:
+                merged.pop(key_str, None)
+            else:
+                merged[key_str] = str(value)
+    return merged

abogen/domain/metadata_overrides.py

@@ -0,0 +1,56 @@
+"""OPDS metadata normalization.
+
+Normalizes metadata keys from various OPDS/Calibre sources into
+a canonical set of overrides for the audiobook conversion pipeline.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping
+
+from abogen.domain.metadata_helpers import expand_metadata_aliases
+
+
+def normalize_opds_metadata(metadata_payload: Mapping[str, Any]) -> Dict[str, Any]:
+    """Normalize OPDS/Calibre metadata into canonical override keys.
+
+    Takes a metadata payload with various key aliases (e.g. 'series'/'series_name',
+    'tags'/'keywords', 'authors'/'creator') and returns a dict with all
+    concept aliases expanded.
+
+    Args:
+        metadata_payload: Raw metadata dict from OPDS/Calibre import.
+
+    Returns:
+        Dict with all canonical metadata key aliases expanded.
+    """
+    def _stringify(value: Any) -> str:
+        if value is None:
+            return ""
+        if isinstance(value, (list, tuple, set)):
+            parts = [str(item).strip() for item in value if item is not None]
+            return ", ".join(part for part in parts if part)
+        return str(value).strip()
+
+    # Map OPDS-specific keys to common concept keys before expansion
+    normalized_input: Dict[str, Any] = {}
+    for key, value in metadata_payload.items():
+        if value is None:
+            continue
+        key_lower = str(key).strip().lower()
+        if not key_lower:
+            continue
+        text = _stringify(value)
+        if not text:
+            continue
+
+        # Map OPDS-specific author aliases
+        if key_lower in ("creator", "dc_creator"):
+            normalized_input["author"] = text
+        # Map OPDS-specific subtitle aliases
+        elif key_lower in ("sub_title", "calibre_subtitle"):
+            normalized_input["subtitle"] = text
+        else:
+            normalized_input[key_lower] = text
+
+    return expand_metadata_aliases(normalized_input)

abogen/domain/normalization.py

@@ -0,0 +1,245 @@
+"""Text normalization convenience helpers.
+
+Provides both the simple ``normalize_text_for_pipeline`` (apostrophe + LLM only)
+and the comprehensive ``prepare_text_for_tts`` that chains all three normalization
+stages used during conversion: heteronym rules → pronunciation rules → pipeline
+normalization.  The latter is the single entry point that both the Web UI and
+PyQt Desktop GUI should use.
+
+Also provides ``TTSContext`` — a dataclass bundling all pre-compiled normalization
+resources so they can be created once and passed as a single object.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+from abogen.domain.enums import Language
+from abogen.kokoro_text_normalization import (
+    ApostropheConfig,
+    normalize_for_pipeline as _normalize_for_pipeline,
+)
+from abogen.normalization_settings import (
+    build_apostrophe_config,
+    get_runtime_settings,
+    apply_overrides as _apply_overrides,
+)
+
+_BASE_APOSTROPHE_CONFIG = ApostropheConfig()
+
+
+@dataclass
+class TTSContext:
+    """Bundles pre-compiled normalization resources for TTS processing.
+
+    Created once per conversion job and passed to ``prepare_text_for_tts``
+    instead of threading 5 separate parameters.
+    """
+
+    split_pattern: str = r"(?<=[.!?\-])\s+"
+    pronunciation_rules: Optional[List[Dict[str, Any]]] = None
+    heteronym_rules: Optional[List[Dict[str, Any]]] = None
+    normalization_overrides: Optional[Mapping[str, Any]] = None
+    usage_counter: Dict[str, int] = field(default_factory=dict)
+
+    def normalize(self, text: str) -> str:
+        """Shorthand: normalize text using this context's compiled rules."""
+        return prepare_text_for_tts(
+            text,
+            heteronym_rules=self.heteronym_rules,
+            pronunciation_rules=self.pronunciation_rules,
+            normalization_overrides=self.normalization_overrides,
+            usage_counter=self.usage_counter,
+        )
+
+
+def normalize_text_for_pipeline(
+    text: str,
+    *,
+    normalization_overrides: Optional[Mapping[str, Any]] = None,
+) -> str:
+    """Normalize text using runtime settings with optional overrides."""
+    runtime_settings = get_runtime_settings()
+    if normalization_overrides:
+        runtime_settings = _apply_overrides(runtime_settings, normalization_overrides)
+    apostrophe_config = build_apostrophe_config(settings=runtime_settings, base=_BASE_APOSTROPHE_CONFIG)
+    return _normalize_for_pipeline(text, config=apostrophe_config, settings=runtime_settings)
+
+
+def prepare_text_for_tts(
+    text: str,
+    *,
+    heteronym_rules: Optional[List[Dict[str, Any]]] = None,
+    pronunciation_rules: Optional[List[Dict[str, Any]]] = None,
+    normalization_overrides: Optional[Mapping[str, Any]] = None,
+    usage_counter: Optional[Dict[str, int]] = None,
+) -> str:
+    """Apply the full text normalization pipeline before TTS synthesis.
+
+    Chains three stages in order:
+      1. Heteronym sentence rules (context-dependent pronunciation)
+      2. Pronunciation rules (token-level replacements)
+      3. Pipeline normalization (apostrophe handling, LLM normalization)
+
+    This is the **single entry point** that both the Web UI conversion runner
+    and the PyQt conversion thread should call before passing text to the TTS
+    backend.
+
+    Parameters
+    ----------
+    text:
+        Raw text to normalize.
+    heteronym_rules:
+        Compiled heteronym rules from ``compile_heteronym_sentence_rules``.
+    pronunciation_rules:
+        Compiled pronunciation rules from ``compile_pronunciation_rules``.
+    normalization_overrides:
+        User-level overrides for normalization settings (apostrophe mode, etc.).
+    usage_counter:
+        Mutable dict that tracks how many times each pronunciation override was
+        applied.  Passed through to ``apply_pronunciation_rules``.
+
+    Returns
+    -------
+    str
+        Fully normalized text ready for TTS.
+    """
+    from abogen.domain.pronunciation import (
+        apply_heteronym_sentence_rules,
+        apply_pronunciation_rules,
+    )
+
+    result = str(text or "")
+
+    if heteronym_rules:
+        result = apply_heteronym_sentence_rules(result, heteronym_rules)
+
+    if pronunciation_rules:
+        result = apply_pronunciation_rules(result, pronunciation_rules, usage_counter)
+
+    runtime_settings = get_runtime_settings()
+    if normalization_overrides:
+        runtime_settings = _apply_overrides(runtime_settings, normalization_overrides)
+    apostrophe_config = build_apostrophe_config(settings=runtime_settings, base=_BASE_APOSTROPHE_CONFIG)
+
+    return _normalize_for_pipeline(result, config=apostrophe_config, settings=runtime_settings)
+
+
+def build_tts_context(
+    *,
+    language: Language,
+    subtitle: "SubtitleConfig | str" = "Disabled",
+    pronunciation: Optional["PronunciationConfig"] = None,
+    speakers: Optional[Dict[str, Any]] = None,
+    usage_counter: Optional[Dict[str, int]] = None,
+    log_callback: Optional[Callable[[str, str], None]] = None,
+) -> TTSContext:
+    """Build a TTSContext from raw data. Single entry point for both UIs.
+
+    Loads normalization settings, applies overrides, validates configuration,
+    merges pronunciation overrides, and compiles all rules.
+
+    Args:
+        language: Language enum value.
+        subtitle: SubtitleConfig object or subtitle mode string.
+        pronunciation: PronunciationConfig with override rules.
+        speakers: Speaker profile mapping.
+        usage_counter: Mutable dict for tracking override usage.
+        log_callback: Callable(level, message) for warnings.
+
+    Returns:
+        TTSContext ready for text normalization.
+    """
+    from abogen.domain.config_types import PronunciationConfig, SubtitleConfig
+    from abogen.domain.enums import SubtitleMode
+    from abogen.domain.pronunciation import (
+        compile_heteronym_sentence_rules,
+        compile_pronunciation_rules,
+        merge_pronunciation_overrides,
+    )
+    from abogen.domain.split_pattern import get_split_pattern
+
+    def _log(msg: str, level: str = "warning") -> None:
+        if log_callback:
+            log_callback(level, msg)
+
+    # Resolve subtitle mode
+    if isinstance(subtitle, SubtitleConfig):
+        resolved_subtitle = subtitle.mode
+    else:
+        try:
+            resolved_subtitle = SubtitleMode.from_str(subtitle) if not isinstance(subtitle, SubtitleMode) else subtitle
+        except ValueError:
+            resolved_subtitle = SubtitleMode.DISABLED
+
+    # Resolve pronunciation config
+    if pronunciation is None:
+        pronunciation = PronunciationConfig()
+
+    # Get runtime normalization settings
+    runtime_settings = get_runtime_settings()
+
+    # Apply per-job normalization overrides
+    if pronunciation.normalization_overrides:
+        runtime_settings = _apply_overrides(runtime_settings, pronunciation.normalization_overrides)
+
+    # Build apostrophe config
+    apostrophe_config = build_apostrophe_config(settings=runtime_settings)
+
+    # Validate LLM apostrophe mode
+    apostrophe_mode = str(runtime_settings.get("normalization_apostrophe_mode", "spacy")).lower()
+    if apostrophe_mode == "llm":
+        from abogen.normalization_settings import build_llm_configuration
+        llm_config = build_llm_configuration(runtime_settings)
+        if not llm_config.is_configured():
+            raise RuntimeError(
+                "LLM-based apostrophe normalization is selected, but the LLM configuration is incomplete."
+            )
+
+    # Check for num2words availability
+    if apostrophe_config.convert_numbers:
+        try:
+            import num2words  # noqa: F401
+        except ImportError:
+            _log(
+                "Number normalization is enabled but 'num2words' library is not available. "
+                "Numbers will NOT be converted to words."
+            )
+
+    # Compute split pattern
+    if not isinstance(language, Language):
+        raise TypeError(f"language must be Language enum, got {type(language).__name__}: {language!r}")
+    split_pattern = get_split_pattern(language, resolved_subtitle)
+
+    # Merge pronunciation overrides
+    source = {
+        "pronunciation_overrides": pronunciation.pronunciation_overrides,
+        "manual_overrides": pronunciation.manual_overrides,
+        "speakers": speakers or {},
+        "language": language,
+    }
+    merged_overrides = merge_pronunciation_overrides(source)
+
+    # Compile rules
+    pronunciation_rules = compile_pronunciation_rules(merged_overrides)
+    heteronym_rules = compile_heteronym_sentence_rules(pronunciation.heteronym_overrides)
+
+    if heteronym_rules:
+        _log(
+            f"Applying {len(heteronym_rules)} heteronym override(s) during conversion.",
+            level="debug",
+        )
+    if pronunciation_rules:
+        _log(
+            f"Applying {len(pronunciation_rules)} pronunciation override(s) during conversion.",
+            level="debug",
+        )
+
+    return TTSContext(
+        split_pattern=split_pattern,
+        pronunciation_rules=pronunciation_rules,
+        heteronym_rules=heteronym_rules,
+        normalization_overrides=pronunciation.normalization_overrides,
+        usage_counter=usage_counter if usage_counter is not None else {},
+    )

abogen/domain/output_paths.py

@@ -0,0 +1,226 @@
+"""Output path resolution utilities.
+
+Pure functions for resolving output directories, building file paths,
+and computing project folder layouts.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Callable, List, Optional, Tuple
+
+from abogen.text_extractor import ExtractedChapter
+
+
+_OUTPUT_SANITIZE_RE = re.compile(r"[^\w\-_.]+")
+
+# OS-specific illegal characters for filenames
+_WINDOWS_ILLEGAL_CHARS_RE = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+_MACOS_ILLEGAL_CHARS_RE = re.compile(r"[:]")
+_LINUX_ILLEGAL_CHARS_RE = re.compile(r"[/\x00]")
+_CONTROL_CHARS_RE = re.compile(r"[\x00-\x1f]")
+_UNIX_CONTROL_CHARS_RE = re.compile(r'[\x00-\x1f]')
+_RESERVED_NAMES = frozenset(
+    {"CON", "PRN", "AUX", "NUL"}
+    | {f"COM{i}" for i in range(1, 10)}
+    | {f"LPT{i}" for i in range(1, 10)}
+)
+
+
+def sanitize_name_for_os(name: str, is_folder: bool = True) -> str:
+    """Sanitize a filename or folder name based on the operating system.
+
+    Args:
+        name: The name to sanitize
+        is_folder: Whether this is a folder name (default: True)
+
+    Returns:
+        Sanitized name safe for the current OS
+    """
+    if not name:
+        return "audiobook"
+
+    system = platform.system()
+
+    if system == "Windows":
+        sanitized = _WINDOWS_ILLEGAL_CHARS_RE.sub("_", name)
+        sanitized = _CONTROL_CHARS_RE.sub("_", sanitized)
+        sanitized = sanitized.rstrip(". ")
+        if sanitized.upper() in _RESERVED_NAMES or sanitized.upper().split(".")[0] in _RESERVED_NAMES:
+            sanitized = f"_{sanitized}"
+    elif system == "Darwin":
+        sanitized = _MACOS_ILLEGAL_CHARS_RE.sub("_", name)
+        sanitized = _CONTROL_CHARS_RE.sub("_", sanitized)
+        if is_folder and sanitized.startswith("."):
+            sanitized = "_" + sanitized[1:]
+    else:
+        sanitized = _LINUX_ILLEGAL_CHARS_RE.sub("_", name)
+        sanitized = _UNIX_CONTROL_CHARS_RE.sub("_", sanitized)
+        if is_folder and sanitized.startswith("."):
+            sanitized = "_" + sanitized[1:]
+
+    if not sanitized or sanitized.strip() == "":
+        sanitized = "audiobook"
+
+    if len(sanitized) > 255:
+        sanitized = sanitized[:255].rstrip(". ")
+
+    return sanitized
+
+
+def slugify(title: str, index: int) -> str:
+    sanitized = re.sub(r"[^\w\-]+", "_", title.lower()).strip("_")
+    if not sanitized:
+        sanitized = f"chapter_{index:02d}"
+    return sanitized[:80]
+
+
+def sanitize_filename_for_chapter(title: str, index: int, max_len: int = 80) -> str:
+    """Sanitize a chapter name for use as a filename component.
+
+    Combines character sanitization, OS safety, and smart truncation
+    at word boundaries. Prepends zero-padded index prefix.
+
+    Args:
+        title: Raw chapter title.
+        index: 1-based chapter number for prefix.
+        max_len: Maximum length of the sanitized portion (excluding prefix).
+
+    Returns:
+        Sanitized string like "01_the_beginning".
+    """
+    # Remove non-word/non-space/non-hyphen chars, then collapse spaces/hyphens
+    sanitized = re.sub(r"[^\w\s\-]", "", title)
+    sanitized = re.sub(r"[\s\-]+", "_", sanitized).strip("_")
+
+    if not sanitized:
+        sanitized = f"chapter_{index:02d}"
+
+    # OS-specific sanitization
+    system = platform.system()
+    if system == "Windows":
+        sanitized = _WINDOWS_ILLEGAL_CHARS_RE.sub("_", sanitized)
+        sanitized = sanitized.rstrip(". ")
+        base = sanitized.split(".")[0].upper()
+        if base in _RESERVED_NAMES:
+            sanitized = f"_{sanitized}"
+    # Linux: only NUL is truly illegal, but control chars are problematic
+    sanitized = _UNIX_CONTROL_CHARS_RE.sub("_", sanitized)
+
+    # Smart truncation at word boundary
+    if len(sanitized) > max_len:
+        pos = sanitized[:max_len].rfind("_")
+        sanitized = sanitized[: pos if pos > 0 else max_len].rstrip("_")
+
+    return f"{index:02d}_{sanitized}"
+
+
+def sanitize_output_stem(name: str, index: int = 0) -> str:
+    base = Path(name or "").stem
+    sanitized = _OUTPUT_SANITIZE_RE.sub("_", base).strip("_")
+    return sanitized or "output"
+
+
+def output_timestamp_token() -> str:
+    return datetime.now().strftime("%Y%m%d-%H%M%S")
+
+
+def build_output_path(directory: Path, original_name: str, extension: str) -> Path:
+    sanitized = sanitize_output_stem(original_name)
+    return directory / f"{sanitized}.{extension}"
+
+
+def apply_newline_policy(chapters: List[ExtractedChapter], replace_single_newlines: bool) -> None:
+    if not replace_single_newlines:
+        return
+    newline_regex = re.compile(r"(?<!\n)\n(?!\n)")
+    for chapter in chapters:
+        chapter.text = newline_regex.sub(" ", chapter.text)
+
+
+from abogen.domain.enums import SaveMode
+
+
+def resolve_output_directory(
+    *,
+    save_mode: str,
+    stored_path: Path,
+    output_folder: Optional[str],
+    desktop_dir: Optional[Path],
+    user_output_path: Optional[Path],
+    user_cache_outputs: Optional[Path],
+) -> Path:
+    if save_mode in (SaveMode.SAVE_TO_DESKTOP, "Save to Desktop") and desktop_dir:
+        return desktop_dir
+    if save_mode in (SaveMode.SAVE_NEXT_TO_INPUT, "Save next to input file"):
+        return stored_path.parent
+    if save_mode in (SaveMode.CHOOSE_OUTPUT_FOLDER, "Choose output folder") and output_folder:
+        return Path(output_folder)
+    if save_mode in (SaveMode.DEFAULT_OUTPUT, "Use default save location") and user_output_path:
+        return user_output_path
+    return user_cache_outputs or Path(".")
+
+
+def resolve_project_layout(
+    *,
+    original_filename: str,
+    save_as_project: bool,
+    base_dir: Path,
+    timestamp_fn: Callable[[], str] = output_timestamp_token,
+    sanitize_fn: Callable[[str, int], str] = sanitize_output_stem,
+) -> Tuple[Path, Path, Path, Optional[Path]]:
+    sanitized = sanitize_fn(original_filename, 0)
+    folder_name = f"{timestamp_fn()}_{sanitized}"
+    project_root = base_dir / folder_name
+    project_root.mkdir(parents=True, exist_ok=True)
+
+    if save_as_project:
+        audio_dir = project_root / "audio"
+        subtitle_dir = project_root / "subtitles"
+        metadata_dir = project_root / "metadata"
+        for directory in (audio_dir, subtitle_dir, metadata_dir):
+            directory.mkdir(parents=True, exist_ok=True)
+        return project_root, audio_dir, subtitle_dir, metadata_dir
+
+    return project_root, project_root, project_root, None
+
+
+def resolve_unique_path(
+    parent_dir: str,
+    base_name: str,
+    extension: str,
+    allowed_extensions: Optional[set] = None,
+) -> str:
+    """Find a unique file path by appending _2, _3, etc. on collision.
+
+    Args:
+        parent_dir: Directory to check for collisions.
+        base_name: Base filename (without extension).
+        extension: File extension (without dot).
+        allowed_extensions: Set of extensions to check against.
+            If None, checks any existing file/dir with same name.
+
+    Returns:
+        Full path without extension (e.g. "/path/to/name_2").
+    """
+    sanitized = sanitize_name_for_os(base_name, is_folder=True)
+    counter = 1
+    while True:
+        suffix = f"_{counter}" if counter > 1 else ""
+        candidate = os.path.join(parent_dir, f"{sanitized}{suffix}")
+        if allowed_extensions is not None:
+            file_parts = (os.path.splitext(f) for f in os.listdir(parent_dir))
+            clash = any(
+                name == f"{sanitized}{suffix}"
+                and ext[1:].lower() in allowed_extensions
+                for name, ext in file_parts
+            )
+        else:
+            clash = os.path.exists(candidate)
+        if not clash:
+            return candidate
+        counter += 1

abogen/domain/pipeline_factory.py

@@ -0,0 +1,117 @@
+"""Pipeline creation, caching and lifecycle management.
+
+Provides a unified interface for creating and managing TTS pipelines
+across all UI layers (WebUI, PyQt, CLI).
+
+Language handling: the engine owns the mapping between Language enum
+and its internal format. Callers pass Language enum; the engine
+converts internally. No engine-specific codes leak outside the engine.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from abogen.domain.device import select_device
+from abogen.domain.enums import Language
+from abogen.domain.voice_resolution import initialize_voice_cache
+from abogen.tts_plugin.utils import create_pipeline, is_plugin_registered
+
+
+def resolve_device(use_gpu: bool) -> str:
+    """Determine compute device from job and global config flags."""
+    from abogen.utils import load_config
+
+    cfg = load_config()
+    if use_gpu and cfg.get("use_gpu", True):
+        return select_device()
+    return "cpu"
+
+
+def create_pipeline_for_job(
+    provider: str,
+    language: Language,
+    use_gpu: bool,
+) -> Any:
+    """Create a TTS pipeline with proper device selection.
+
+    Args:
+        provider: TTS provider name ("kokoro" or "supertonic").
+        language: Language enum (app-layer type, not engine-specific).
+        use_gpu: Whether GPU acceleration is requested.
+    """
+    provider = str(provider or "kokoro").strip().lower() or "kokoro"
+    if not is_plugin_registered(provider):
+        provider = "kokoro"
+
+    if provider == "supertonic":
+        return create_pipeline("supertonic", language=language)
+
+    device = resolve_device(use_gpu)
+    return create_pipeline("kokoro", language=language, device=device)
+
+
+def dispose_pipelines(pipelines: Dict[str, Any]) -> None:
+    """Dispose all pipelines in a dict and clear it."""
+    for p in pipelines.values():
+        try:
+            p.dispose()
+        except Exception:
+            pass
+    pipelines.clear()
+
+
+class PipelinePool:
+    """Cache and manage TTS pipelines by provider.
+
+    Usage::
+
+        pool = PipelinePool()
+        backend = pool.get("kokoro", Language.EN_US, use_gpu=True)
+        # ... use backend ...
+        pool.dispose_all()
+    """
+
+    def __init__(self) -> None:
+        self._pipelines: Dict[str, Any] = {}
+        self._voice_cache_initialized = False
+
+    def get(
+        self,
+        provider: str,
+        language: Language,
+        use_gpu: bool,
+        *,
+        request: Any = None,
+        events: Any = None,
+    ) -> Any:
+        """Get or create a cached pipeline for the given provider.
+
+        Args:
+            provider: TTS provider name ("kokoro" or "supertonic").
+            language: Language enum (app-layer type).
+            use_gpu: Whether GPU acceleration is requested.
+            request: ConversionRequest for voice cache initialization.
+            events: ConversionEvents for logging during cache init.
+        """
+        provider = str(provider or "kokoro").strip().lower() or "kokoro"
+        if not is_plugin_registered(provider):
+            provider = "kokoro"
+
+        existing = self._pipelines.get(provider)
+        if existing is not None:
+            return existing
+
+        pipeline = create_pipeline_for_job(provider, language, use_gpu)
+        self._pipelines[provider] = pipeline
+
+        if provider == "kokoro" and not self._voice_cache_initialized and request is not None:
+            initialize_voice_cache(request, events=events)
+            self._voice_cache_initialized = True
+
+        return pipeline
+
+    def dispose_all(self) -> None:
+        """Dispose all cached pipelines."""
+        dispose_pipelines(self._pipelines)
+        self._voice_cache_initialized = False

abogen/domain/progress.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+"""Progress and ETR (estimated time remaining) calculation.
+
+Shared by Web UI and PyQt desktop GUI. Pure math, no UI dependencies.
+"""
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ProgressTracker:
+    """Tracks character-based progress with ETR calculation.
+
+    Usage:
+        tracker = ProgressTracker(total_chars=50000)
+        # ... as processing occurs:
+        tracker.update(chars_done=5000)
+        print(tracker.etr_str)   # "00:04:30"
+        print(tracker.percent)   # 10
+    """
+    total_chars: int
+    _start_time: float = field(default_factory=time.time, repr=False)
+    _chars_done: int = field(default=0, repr=False)
+
+    def update(self, chars_done: int) -> None:
+        self._chars_done = chars_done
+
+    @property
+    def percent(self) -> int:
+        if self.total_chars <= 0:
+            return 0
+        return min(int(self._chars_done / self.total_chars * 100), 99)
+
+    @property
+    def etr_str(self) -> str:
+        elapsed = time.time() - self._start_time
+        if self._chars_done <= 0 or elapsed <= 0.5:
+            return "Processing..."
+        avg_time_per_char = elapsed / self._chars_done
+        remaining = self.total_chars - self._chars_done
+        if remaining <= 0:
+            return "00:00:00"
+        secs = avg_time_per_char * remaining
+        h = int(secs // 3600)
+        m = int((secs % 3600) // 60)
+        s = int(secs % 60)
+        return f"{h:02d}:{m:02d}:{s:02d}"
+
+
+def calc_etr_str(elapsed: float, done: int, total: int) -> str:
+    """Standalone ETR string calculation (matches PyQt original logic).
+
+    Args:
+        elapsed: seconds since processing started
+        done: items/characters processed so far
+        total: total items/characters to process
+
+    Returns:
+        ETR string like "01:23:45" or "Processing..."
+    """
+    if done <= 0 or elapsed <= 0.5:
+        return "Processing..."
+    avg_time_per_item = elapsed / done
+    remaining = total - done
+    if remaining <= 0:
+        return "00:00:00"
+    secs = avg_time_per_item * remaining
+    h = int(secs // 3600)
+    m = int((secs % 3600) // 60)
+    s = int(secs % 60)
+    return f"{h:02d}:{m:02d}:{s:02d}"

abogen/domain/pronunciation.py

@@ -0,0 +1,270 @@
+"""Pronunciation rule compilation and application.
+
+Pure functions for compiling token-level and sentence-level pronunciation
+overrides into regex patterns, applying them to text, and merging multiple
+override sources with precedence rules.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Iterable, List, Mapping, Optional
+
+from abogen.entity_analysis import normalize_token as normalize_entity_token
+from abogen.entity_analysis import normalize_manual_override_token
+
+
+def compile_pronunciation_rules(
+    overrides: Optional[Iterable[Mapping[str, Any]]],
+) -> List[Dict[str, Any]]:
+    if not overrides:
+        return []
+
+    candidates: List[Dict[str, Any]] = []
+    seen: set[str] = set()
+
+    for entry in overrides:
+        if not isinstance(entry, Mapping):
+            continue
+        pronunciation_value = str(entry.get("pronunciation") or "").strip()
+        if not pronunciation_value:
+            continue
+
+        token_values: List[str] = []
+        token_raw = entry.get("token")
+        if token_raw:
+            token_value = str(token_raw).strip()
+            if token_value:
+                token_values.append(token_value)
+        normalized_raw = entry.get("normalized")
+        if normalized_raw:
+            normalized_value = str(normalized_raw).strip()
+            if normalized_value:
+                token_values.append(normalized_value)
+        if token_raw and not token_values:
+            fallback = normalize_entity_token(str(token_raw))
+            if fallback:
+                token_values.append(fallback)
+
+        if not token_values:
+            continue
+
+        usage_normalized = str(entry.get("normalized") or "").strip()
+        if not usage_normalized and token_values:
+            usage_normalized = normalize_entity_token(token_values[0]) or token_values[0]
+        usage_token = str(entry.get("token") or token_values[0])
+
+        for token_value in token_values:
+            key = token_value.casefold()
+            if key in seen:
+                continue
+            seen.add(key)
+            candidates.append(
+                {
+                    "token": token_value,
+                    "normalized": usage_normalized,
+                    "replacement": pronunciation_value,
+                }
+            )
+
+    if not candidates:
+        return []
+
+    candidates.sort(key=lambda item: len(item["token"]), reverse=True)
+    compiled: List[Dict[str, Any]] = []
+    for candidate in candidates:
+        token_value = candidate["token"]
+        pronunciation_value = candidate["replacement"]
+        escaped = re.escape(token_value)
+        pattern = re.compile(rf"(?i)(?<!\w){escaped}(?P<possessive>'s|\u2019s|\u2019)?(?!\w)")
+        compiled.append(
+            {
+                "pattern": pattern,
+                "replacement": pronunciation_value,
+                "normalized": candidate.get("normalized") or token_value,
+                "token": candidate.get("token") or token_value,
+            }
+        )
+
+    return compiled
+
+
+def compile_heteronym_sentence_rules(
+    overrides: Optional[Iterable[Mapping[str, Any]]],
+) -> List[Dict[str, Any]]:
+    if not overrides:
+        return []
+
+    compiled: List[Dict[str, Any]] = []
+    seen: set[str] = set()
+
+    for entry in overrides:
+        if not isinstance(entry, Mapping):
+            continue
+        sentence = str(entry.get("sentence") or "").strip()
+        if not sentence:
+            continue
+        choice = str(entry.get("choice") or "").strip()
+        if not choice:
+            continue
+
+        replacement_sentence = ""
+        options = entry.get("options")
+        if isinstance(options, list):
+            for opt in options:
+                if not isinstance(opt, Mapping):
+                    continue
+                if str(opt.get("key") or "").strip() == choice:
+                    replacement_sentence = str(opt.get("replacement_sentence") or "").strip()
+                    break
+        if not replacement_sentence:
+            continue
+
+        rule_key = f"{sentence}\n{choice}".casefold()
+        if rule_key in seen:
+            continue
+        seen.add(rule_key)
+
+        parts = [p for p in re.split(r"\s+", sentence) if p]
+        if not parts:
+            continue
+        pattern_text = r"\s+".join(re.escape(p) for p in parts)
+        pattern = re.compile(pattern_text)
+        compiled.append({"pattern": pattern, "replacement": replacement_sentence})
+
+    compiled.sort(key=lambda item: len(item["pattern"].pattern), reverse=True)
+    return compiled
+
+
+def apply_heteronym_sentence_rules(text: str, rules: List[Dict[str, Any]]) -> str:
+    if not text or not rules:
+        return text
+    result = text
+    for rule in rules:
+        pattern = rule["pattern"]
+        replacement = rule["replacement"]
+        result = pattern.sub(replacement, result)
+    return result
+
+
+def apply_pronunciation_rules(
+    text: str,
+    rules: List[Dict[str, Any]],
+    usage_counter: Optional[Dict[str, int]] = None,
+) -> str:
+    if not text or not rules:
+        return text
+
+    result = text
+    for rule in rules:
+        pattern = rule["pattern"]
+        pronunciation_value = rule["replacement"]
+        usage_key = str(rule.get("normalized") or "").strip()
+
+        def _replacement(match: re.Match[str]) -> str:
+            suffix = match.group("possessive") or ""
+            if usage_counter is not None and usage_key:
+                usage_counter[usage_key] = usage_counter.get(usage_key, 0) + 1
+            return pronunciation_value + suffix
+
+        result = pattern.sub(_replacement, result)
+
+    return result
+
+
+def merge_pronunciation_overrides(job: Any) -> List[Dict[str, Any]]:
+    """Return pronunciation override entries, ensuring manual overrides are included.
+
+    Pending jobs keep both ``manual_overrides`` and ``pronunciation_overrides``, but the
+    latter can be stale if the UI didn't resync before enqueue. During conversion,
+    we must merge manual overrides so they always apply (before TTS).
+
+    Precedence: manual overrides win over existing entries for the same normalized key.
+
+    Args:
+        job: Either a job-like object with attributes, or a dict with keys:
+            ``pronunciation_overrides``, ``manual_overrides``, ``speakers``, ``language``.
+    """
+
+    collected: Dict[str, Dict[str, Any]] = {}
+
+    def _get(key: str, default: Any = None) -> Any:
+        if isinstance(job, Mapping):
+            return job.get(key, default)
+        return getattr(job, key, default)
+
+    existing = _get("pronunciation_overrides")
+    if isinstance(existing, list):
+        for entry in existing:
+            if not isinstance(entry, Mapping):
+                continue
+            token_value = str(entry.get("token") or "").strip()
+            pronunciation_value = str(entry.get("pronunciation") or "").strip()
+            if not token_value or not pronunciation_value:
+                continue
+            normalized = str(entry.get("normalized") or "").strip() or normalize_entity_token(token_value)
+            if not normalized:
+                continue
+            collected[normalized] = {
+                "token": token_value,
+                "normalized": normalized,
+                "pronunciation": pronunciation_value,
+                "voice": str(entry.get("voice") or "").strip() or None,
+                "notes": str(entry.get("notes") or "").strip() or None,
+                "context": str(entry.get("context") or "").strip() or None,
+                "source": str(entry.get("source") or "pronunciation"),
+                "language": _get("language"),
+            }
+
+    speakers = _get("speakers")
+    if isinstance(speakers, dict):
+        for payload in speakers.values():
+            if not isinstance(payload, Mapping):
+                continue
+            token_value = str(payload.get("token") or "").strip()
+            pronunciation_value = str(payload.get("pronunciation") or "").strip()
+            if not token_value or not pronunciation_value:
+                continue
+            normalized = normalize_entity_token(token_value)
+            if not normalized:
+                continue
+            collected[normalized] = {
+                "token": token_value,
+                "normalized": normalized,
+                "pronunciation": pronunciation_value,
+                "voice": str(
+                    payload.get("resolved_voice")
+                    or payload.get("voice")
+                    or _get("voice", "")
+                ).strip()
+                or None,
+                "notes": None,
+                "context": None,
+                "source": "speaker",
+                "language": _get("language"),
+            }
+
+    manual = _get("manual_overrides")
+    if isinstance(manual, list):
+        for entry in manual:
+            if not isinstance(entry, Mapping):
+                continue
+            token_value = str(entry.get("token") or "").strip()
+            pronunciation_value = str(entry.get("pronunciation") or "").strip()
+            if not token_value or not pronunciation_value:
+                continue
+            normalized = str(entry.get("normalized") or "").strip() or normalize_manual_override_token(token_value)
+            if not normalized:
+                continue
+            collected[normalized] = {
+                "token": token_value,
+                "normalized": normalized,
+                "pronunciation": pronunciation_value,
+                "voice": str(entry.get("voice") or "").strip() or None,
+                "notes": str(entry.get("notes") or "").strip() or None,
+                "context": str(entry.get("context") or "").strip() or None,
+                "source": str(entry.get("source") or "manual"),
+                "language": _get("language"),
+            }
+
+    return list(collected.values())

abogen/domain/settings_core.py

@@ -0,0 +1,641 @@
+"""Shared settings core.
+
+Defines the SETTINGS_REGISTRY — the single source of truth for all settings.
+Every setting has a key, type, default, validation rules, and UI scope.
+Both Web UI and Desktop GUI must reference this registry.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Mapping, Optional
+
+from abogen.constants import (
+    KOKORO_CODE_LABELS,
+    SUBTITLE_FORMATS,
+    SUPPORTED_SOUND_FORMATS,
+)
+from abogen.tts_plugin.utils import get_default_voice
+from abogen.normalization_settings import (
+    DEFAULT_LLM_PROMPT,
+    environment_llm_defaults,
+)
+
+
+# ── Schema ───────────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class Setting:
+    """Contract for a single setting.
+
+    Attributes:
+        key: Config dict key (e.g. "output_format").
+        type_: Python type (bool, int, float, str, list).
+        default: Default value or callable returning one.
+        min_value: Minimum for numeric types.
+        max_value: Maximum for numeric types.
+        valid_values: Allowed values for str types (None = any).
+        gui_only: True if only used by PyQt Desktop GUI.
+        web_only: True if only used by Web UI.
+        normalizer: Optional callable(value, default) -> normalized_value.
+        description: Human-readable explanation.
+    """
+    key: str
+    type_: type
+    default: Any
+    min_value: float | None = None
+    max_value: float | None = None
+    valid_values: tuple[Any, ...] | None = None
+    gui_only: bool = False
+    web_only: bool = False
+    normalizer: Callable | None = None
+    description: str = ""
+
+    def coerce(self, value: Any, fallback: Any | None = None) -> Any:
+        """Coerce value to the declared type, returning fallback on failure."""
+        fb = fallback if fallback is not None else self.default
+        if self.type_ is bool:
+            if isinstance(value, bool):
+                return value
+            if isinstance(value, str):
+                return value.lower() in {"true", "1", "yes", "on"}
+            if value is None:
+                return fb
+            return bool(value)
+        if self.type_ is int:
+            try:
+                v = int(value)
+            except (TypeError, ValueError):
+                return fb
+            if self.min_value is not None:
+                v = max(int(self.min_value), v)
+            if self.max_value is not None:
+                v = min(int(self.max_value), v)
+            return v
+        if self.type_ is float:
+            try:
+                v = float(value)
+            except (TypeError, ValueError):
+                return fb
+            if self.min_value is not None:
+                v = max(self.min_value, v)
+            if self.max_value is not None:
+                v = min(self.max_value, v)
+            return v
+        if self.type_ is str:
+            if isinstance(value, str):
+                v = value.strip()
+                if self.valid_values and v not in self.valid_values:
+                    return fb
+                return v
+            return fb
+        if self.type_ is list:
+            if isinstance(value, (list, tuple, set)):
+                return list(value)
+            return fb
+        return value
+
+
+# ── Normalizers (used by Setting.normalizer) ─────────────────────────
+
+def _norm_save_mode(value: Any, default: str) -> str:
+    if isinstance(value, str):
+        if value in SAVE_MODE_LABELS:
+            return value
+        if value in LEGACY_SAVE_MODE_MAP:
+            return LEGACY_SAVE_MODE_MAP[value]
+    return default
+
+
+def _norm_voice_spec(value: Any, default: str) -> str:
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return default
+        spec, profile_name = split_profile_spec(text)
+        if profile_name:
+            return f"speaker:{profile_name}"
+        return spec
+    return default
+
+
+def _norm_speaker_spec(value: Any, default: str) -> str:
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return ""
+        spec, profile_name = split_profile_spec(text)
+        if profile_name:
+            return f"speaker:{profile_name}"
+        return spec
+    return ""
+
+
+def _norm_language_list(value: Any, default: list) -> list:
+    if isinstance(value, (list, tuple, set)):
+        return [code for code in value if isinstance(code, str) and code in KOKORO_CODE_LABELS]
+    if isinstance(value, str):
+        parts = [item.strip().lower() for item in value.split(",") if item.strip()]
+        return [code for code in parts if code in KOKORO_CODE_LABELS]
+    return default
+
+
+def _norm_stripped_str(value: Any, default: str) -> str:
+    return str(value or "").strip()
+
+
+def _norm_prompt(value: Any, default: str) -> str:
+    candidate = str(value or "").strip()
+    return candidate if candidate else default
+
+
+# ── Registry ─────────────────────────────────────────────────────────
+
+def _default_output_format() -> str:
+    return "wav"
+
+
+def _default_save_mode() -> str:
+    return "default_output" if has_output_override() else "save_next_to_input"
+
+
+def _default_llm(key: str) -> str:
+    return environment_llm_defaults().get(key, "")
+
+
+SETTINGS_REGISTRY: list[Setting] = [
+    # ── Core output ──────────────────────────────────────────────
+    Setting("output_format", str, "wav",
+            valid_values=tuple(SUPPORTED_SOUND_FORMATS),
+            description="Audio output format"),
+    Setting("subtitle_format", str, "srt",
+            valid_values=tuple(item[0] for item in SUBTITLE_FORMATS),
+            description="Subtitle file format"),
+    Setting("save_mode", str, _default_save_mode,
+            normalizer=_norm_save_mode,
+            description="Where to save output files"),
+    Setting("separate_chapters_format", str, "wav",
+            valid_values=("wav", "flac", "mp3", "opus"),
+            description="Format for separately saved chapters"),
+    Setting("chunk_level", str, "paragraph",
+            valid_values=("paragraph", "sentence"),
+            description="Text chunking granularity"),
+
+    # ── Voice ────────────────────────────────────────────────────
+    Setting("default_speaker", str, "",
+            normalizer=_norm_speaker_spec,
+            description="Default speaker name"),
+    Setting("default_voice", str, lambda: get_default_voice("kokoro"),
+            normalizer=_norm_voice_spec,
+            description="Default TTS voice"),
+    Setting("speed", float, 1.0, min_value=0.5, max_value=3.0,
+            gui_only=True,
+            description="TTS speed multiplier"),
+    Setting("supertonic_total_steps", int, 5, min_value=2, max_value=15,
+            description="SuperTonic processing steps"),
+    Setting("supertonic_speed", float, 1.0, min_value=0.7, max_value=2.0,
+            description="SuperTonic speed"),
+
+    # ── Chapter handling ─────────────────────────────────────────
+    Setting("silence_between_chapters", float, 2.0, min_value=0.0,
+            description="Silence gap between chapters (seconds)"),
+    Setting("chapter_intro_delay", float, 0.5, min_value=0.0,
+            description="Delay after chapter heading (seconds)"),
+    Setting("read_title_intro", bool, False,
+            description="Read chapter title as intro"),
+    Setting("read_closing_outro", bool, True,
+            description="Read closing/outro text"),
+    Setting("normalize_chapter_opening_caps", bool, True,
+            description="Normalize chapter opening caps"),
+    Setting("auto_prefix_chapter_titles", bool, True,
+            description="Auto-prefix chapter titles"),
+    Setting("save_chapters_separately", bool, False,
+            description="Save each chapter as separate file"),
+    Setting("merge_chapters_at_end", bool, True,
+            description="Merge chapters into single file"),
+    Setting("save_as_project", bool, False,
+            description="Save as editable project"),
+    Setting("generate_epub3", bool, False,
+            description="Generate EPUB3 output"),
+
+    # ── GPU / performance ────────────────────────────────────────
+    Setting("use_gpu", bool, True,
+            description="Use GPU acceleration"),
+
+    # ── Text processing ──────────────────────────────────────────
+    Setting("replace_single_newlines", bool, False,
+            description="Replace single newlines with spaces"),
+    Setting("max_subtitle_words", int, 50, min_value=1, max_value=500,
+            description="Max words per subtitle"),
+    Setting("enable_entity_recognition", bool, True,
+            description="Enable entity recognition"),
+
+    # ── Speaker analysis ─────────────────────────────────────────
+    Setting("speaker_analysis_threshold", int, 3, min_value=1, max_value=25,
+            description="Speaker analysis threshold"),
+    Setting("speaker_pronunciation_sentence", str, "This is {{name}} speaking.",
+            description="Template for pronunciation samples"),
+    Setting("speaker_random_languages", list, [],
+            normalizer=_norm_language_list,
+            description="Languages for random speaker assignment"),
+
+    # ── LLM ──────────────────────────────────────────────────────
+    Setting("llm_base_url", str, lambda: _default_llm("llm_base_url"),
+            normalizer=_norm_stripped_str,
+            description="LLM API base URL"),
+    Setting("llm_api_key", str, lambda: _default_llm("llm_api_key"),
+            normalizer=_norm_stripped_str,
+            description="LLM API key"),
+    Setting("llm_model", str, lambda: _default_llm("llm_model"),
+            normalizer=_norm_stripped_str,
+            description="LLM model name"),
+    Setting("llm_timeout", float, lambda: _default_llm("llm_timeout") or 30.0,
+            min_value=1.0,
+            description="LLM request timeout"),
+    Setting("llm_prompt", str, lambda: _default_llm("llm_prompt") or DEFAULT_LLM_PROMPT,
+            normalizer=_norm_prompt,
+            description="LLM normalization prompt"),
+    Setting("llm_context_mode", str, lambda: _default_llm("llm_context_mode") or "sentence",
+            valid_values=("sentence",),
+            description="LLM context mode"),
+
+    # ── Normalization (booleans) ─────────────────────────────────
+    Setting("normalization_numbers", bool, True,
+            description="Convert grouped numbers to words"),
+    Setting("normalization_currency", bool, True,
+            description="Convert currency symbols"),
+    Setting("normalization_footnotes", bool, True,
+            description="Remove footnote indicators"),
+    Setting("normalization_titles", bool, True,
+            description="Expand titles and suffixes"),
+    Setting("normalization_terminal", bool, True,
+            description="Ensure terminal punctuation"),
+    Setting("normalization_phoneme_hints", bool, True,
+            description="Add phoneme hints for possessives"),
+    Setting("normalization_caps_quotes", bool, True,
+            description="Convert ALL CAPS in quotes"),
+    Setting("normalization_internet_slang", bool, False,
+            description="Expand internet slang"),
+    Setting("normalization_apostrophes_contractions", bool, True,
+            description="Expand contractions"),
+    Setting("normalization_apostrophes_plural_possessives", bool, True,
+            description="Collapse plural possessives"),
+    Setting("normalization_apostrophes_sibilant_possessives", bool, True,
+            description="Mark sibilant possessives"),
+    Setting("normalization_apostrophes_decades", bool, True,
+            description="Expand decades"),
+    Setting("normalization_apostrophes_leading_elisions", bool, True,
+            description="Expand leading elisions"),
+    Setting("normalization_contraction_aux_be", bool, True,
+            description="Expand auxiliary 'be'"),
+    Setting("normalization_contraction_aux_have", bool, True,
+            description="Expand auxiliary 'have'"),
+    Setting("normalization_contraction_modal_will", bool, True,
+            description="Expand modal 'will'"),
+    Setting("normalization_contraction_modal_would", bool, True,
+            description="Expand modal 'would'"),
+    Setting("normalization_contraction_negation_not", bool, True,
+            description="Expand negation 'not'"),
+    Setting("normalization_contraction_let_us", bool, True,
+            description="Expand 'let's'"),
+
+    # ── Normalization (strings) ──────────────────────────────────
+    Setting("normalization_apostrophe_mode", str, "spacy",
+            valid_values=("off", "spacy", "llm"),
+            description="Apostrophe handling mode"),
+    Setting("normalization_numbers_year_style", str, "american",
+            valid_values=("american", "off"),
+            description="Year style for number normalization"),
+
+    # ── PyQt GUI-only ────────────────────────────────────────────
+    Setting("theme", str, "system",
+            gui_only=True,
+            description="UI theme"),
+    Setting("check_updates", bool, True,
+            gui_only=True,
+            description="Check for updates on startup"),
+    Setting("subtitle_mode", str, "Sentence",
+            gui_only=True,
+            description="Subtitle display mode"),
+    Setting("selected_format", str, "wav",
+            gui_only=True,
+            description="Last selected audio format"),
+    Setting("selected_voice", str, "af_heart",
+            gui_only=True,
+            description="Last selected voice"),
+    Setting("selected_profile_name", str, None,
+            gui_only=True,
+            description="Last selected profile name"),
+    Setting("log_window_max_lines", int, 2000, min_value=100,
+            gui_only=True,
+            description="Max lines in log window"),
+    Setting("use_silent_gaps", bool, True,
+            gui_only=True,
+            description="Use silent gaps between chunks"),
+    Setting("subtitle_speed_method", str, "tts",
+            gui_only=True,
+            valid_values=("tts", "ffmpeg"),
+            description="Speed adjustment method for subtitles"),
+    Setting("use_spacy_segmentation", bool, True,
+            gui_only=True,
+            description="Use spaCy for sentence segmentation"),
+    Setting("word_substitutions_enabled", bool, False,
+            gui_only=True,
+            description="Enable word substitutions"),
+    Setting("word_substitutions_list", str, "",
+            gui_only=True,
+            description="Word substitutions list"),
+    Setting("case_sensitive_substitutions", bool, False,
+            gui_only=True,
+            description="Case-sensitive substitutions"),
+    Setting("replace_all_caps", bool, False,
+            gui_only=True,
+            description="Replace ALL CAPS text"),
+    Setting("replace_numerals", bool, False,
+            gui_only=True,
+            description="Replace numerals with words"),
+    Setting("fix_nonstandard_punctuation", bool, False,
+            gui_only=True,
+            description="Fix nonstandard punctuation"),
+    Setting("queue_override_settings", bool, False,
+            gui_only=True,
+            description="Override settings per queue item"),
+    Setting("disable_kokoro_internet", bool, False,
+            description="Disable Kokoro internet access"),
+]
+
+
+# ── Registry helpers ─────────────────────────────────────────────────
+
+_REGISTRY_BY_KEY: dict[str, Setting] = {s.key: s for s in SETTINGS_REGISTRY}
+
+SETTING_KEYS: frozenset[str] = frozenset(_REGISTRY_BY_KEY.keys())
+GUI_ONLY_KEYS: frozenset[str] = frozenset(s.key for s in SETTINGS_REGISTRY if s.gui_only)
+WEB_ONLY_KEYS: frozenset[str] = frozenset(s.key for s in SETTINGS_REGISTRY if s.web_only)
+SHARED_KEYS: frozenset[str] = SETTING_KEYS - GUI_ONLY_KEYS - WEB_ONLY_KEYS
+
+BOOLEAN_SETTINGS: frozenset[str] = frozenset(s.key for s in SETTINGS_REGISTRY if s.type_ is bool)
+FLOAT_SETTINGS: frozenset[str] = frozenset(s.key for s in SETTINGS_REGISTRY if s.type_ is float)
+INT_SETTINGS: frozenset[str] = frozenset(s.key for s in SETTINGS_REGISTRY if s.type_ is int)
+
+# Backward-compatible aliases (used by existing code)
+_NORMALIZATION_BOOLEAN_KEYS: frozenset[str] = frozenset(
+    s.key for s in SETTINGS_REGISTRY
+    if s.type_ is bool and s.key.startswith("normalization_")
+)
+_NORMALIZATION_STRING_KEYS: frozenset[str] = frozenset(
+    s.key for s in SETTINGS_REGISTRY
+    if s.type_ is str and s.key.startswith("normalization_")
+)
+
+
+def get_setting(key: str) -> Setting | None:
+    """Look up a setting by key."""
+    return _REGISTRY_BY_KEY.get(key)
+
+
+def has_output_override() -> bool:
+    return bool(os.environ.get("ABOGEN_OUTPUT_DIR") or os.environ.get("ABOGEN_OUTPUT_ROOT"))
+
+
+# ── Defaults ─────────────────────────────────────────────────────────
+
+def settings_defaults() -> Dict[str, Any]:
+    """Default values for all shared settings (excludes gui_only)."""
+    result: Dict[str, Any] = {}
+    for s in SETTINGS_REGISTRY:
+        if s.gui_only:
+            continue
+        result[s.key] = s.default() if callable(s.default) else s.default
+    return result
+
+
+def all_settings_defaults() -> Dict[str, Any]:
+    """Default values for ALL settings (including gui_only)."""
+    result: Dict[str, Any] = {}
+    for s in SETTINGS_REGISTRY:
+        result[s.key] = s.default() if callable(s.default) else s.default
+    return result
+
+
+def load_settings() -> Dict[str, Any]:
+    """Load and normalize settings from config file."""
+    from abogen.utils import load_config
+    defaults = settings_defaults()
+    cfg = load_config() or {}
+    settings: Dict[str, Any] = {}
+    for key, default in defaults.items():
+        raw_value = cfg.get(key, default)
+        settings[key] = normalize_setting_value(key, raw_value, defaults)
+    return settings
+
+
+# ── Normalization (delegates to Setting.coerce) ──────────────────────
+
+def normalize_setting_value(key: str, value: Any, defaults: Dict[str, Any]) -> Any:
+    """Normalize a single setting value using the registry schema."""
+    setting = _REGISTRY_BY_KEY.get(key)
+    if setting is None:
+        return value if value is not None else defaults.get(key)
+
+    fallback = defaults.get(key, setting.default() if callable(setting.default) else setting.default)
+
+    if setting.normalizer is not None:
+        return setting.normalizer(value, fallback)
+
+    return setting.coerce(value, fallback)
+
+
+def validate_setting(key: str, value: Any) -> tuple[bool, str]:
+    """Validate a setting value against its schema. Returns (ok, error_message)."""
+    setting = _REGISTRY_BY_KEY.get(key)
+    if setting is None:
+        return False, f"Unknown setting: {key}"
+    if setting.type_ is str and setting.valid_values is not None:
+        v = str(value or "").strip()
+        if v and v not in setting.valid_values:
+            return False, f"Invalid value '{v}' for {key}. Allowed: {setting.valid_values}"
+    if setting.type_ is int:
+        try:
+            iv = int(value)
+        except (TypeError, ValueError):
+            return False, f"Invalid integer value for {key}: {value!r}"
+        if setting.min_value is not None and iv < setting.min_value:
+            return False, f"{key} must be >= {setting.min_value}, got {iv}"
+        if setting.max_value is not None and iv > setting.max_value:
+            return False, f"{key} must be <= {setting.max_value}, got {iv}"
+    if setting.type_ is float:
+        try:
+            fv = float(value)
+        except (TypeError, ValueError):
+            return False, f"Invalid float value for {key}: {value!r}"
+        if setting.min_value is not None and fv < setting.min_value:
+            return False, f"{key} must be >= {setting.min_value}, got {fv}"
+        if setting.max_value is not None and fv > setting.max_value:
+            return False, f"{key} must be <= {setting.max_value}, got {fv}"
+    return True, ""
+
+
+# ── Constants (backward-compatible) ──────────────────────────────────
+
+SAVE_MODE_LABELS = {
+    "save_next_to_input": "Save next to input file",
+    "save_to_desktop": "Save to Desktop",
+    "choose_output_folder": "Choose output folder",
+    "default_output": "Use default save location",
+}
+
+LEGACY_SAVE_MODE_MAP = {label: key for key, label in SAVE_MODE_LABELS.items()}
+
+CHUNK_LEVEL_OPTIONS = [
+    {"value": "paragraph", "label": "Paragraphs"},
+    {"value": "sentence", "label": "Sentences"},
+]
+
+CHUNK_LEVEL_VALUES = frozenset(option["value"] for option in CHUNK_LEVEL_OPTIONS)
+
+DEFAULT_ANALYSIS_THRESHOLD = 3
+
+
+# ── Coercion helpers (backward-compatible, delegate to Setting.coerce) ──
+
+def coerce_bool(value: Any, default: bool) -> bool:
+    return Setting("_", bool, default).coerce(value, default)
+
+
+def coerce_float(value: Any, default: float) -> float:
+    return Setting("_", float, default).coerce(value, default)
+
+
+def coerce_int(value: Any, default: int, *, minimum: int = 1, maximum: int = 200) -> int:
+    return Setting("_", int, default, min_value=minimum, max_value=maximum).coerce(value, default)
+
+
+def split_profile_spec(value: Any) -> tuple[str, str | None]:
+    """Split 'speaker:Name' or 'profile:Name' into (raw, name)."""
+    text = str(value or "").strip()
+    if not text:
+        return "", None
+    lowered = text.lower()
+    if lowered.startswith("profile:") or lowered.startswith("speaker:"):
+        _, _, remainder = text.partition(":")
+        name = remainder.strip()
+        return "", name or None
+    return text, None
+
+
+def normalize_save_mode(value: Any, default: str) -> str:
+    return _norm_save_mode(value, default)
+
+
+# ── LLM helpers ──────────────────────────────────────────────────────
+
+_PROMPT_TOKEN_RE = re.compile(r"{{\s*([a-zA-Z0-9_]+)\s*}}")
+
+
+def llm_ready(settings: Mapping[str, Any]) -> bool:
+    base_url = str(settings.get("llm_base_url") or "").strip()
+    return bool(base_url)
+
+
+def render_prompt_template(template: str, context: Mapping[str, str]) -> str:
+    if not template:
+        return ""
+
+    def _replace(match: re.Match[str]) -> str:
+        key = match.group(1)
+        return context.get(key, "")
+
+    return _PROMPT_TOKEN_RE.sub(_replace, template)
+
+
+# ── Integration defaults ─────────────────────────────────────────────
+
+def integration_defaults() -> Dict[str, Dict[str, Any]]:
+    """Default values for integration settings."""
+    return {
+        "calibre_opds": {
+            "enabled": False,
+            "base_url": "",
+            "username": "",
+            "password": "",
+            "verify_ssl": True,
+        },
+        "audiobookshelf": {
+            "enabled": False,
+            "base_url": "",
+            "api_token": "",
+            "library_id": "",
+            "collection_id": "",
+            "folder_id": "",
+            "verify_ssl": True,
+            "send_cover": True,
+            "send_chapters": True,
+            "send_subtitles": False,
+            "auto_send": False,
+            "timeout": 30.0,
+        },
+    }
+
+
+def stored_integration_config(name: str) -> Dict[str, Any]:
+    """Read raw integration config from config.json.
+
+    Reads ``config["integrations"][name]``.
+    """
+    from abogen.utils import load_config
+
+    cfg = load_config() or {}
+    integrations = cfg.get("integrations")
+    if isinstance(integrations, Mapping):
+        entry = integrations.get(name)
+        if isinstance(entry, Mapping):
+            return dict(entry)
+    return {}
+
+
+def load_audiobookshelf_config() -> Optional["AudiobookshelfConfig"]:
+    """Read Audiobookshelf settings from config.json and build typed config.
+
+    Returns ``None`` when the integration is not configured or required
+    fields are missing.
+    """
+    raw = stored_integration_config("audiobookshelf")
+    if not raw:
+        return None
+    return build_audiobookshelf_config(raw)
+
+
+def build_audiobookshelf_config(
+    settings: Mapping[str, Any],
+) -> Optional["AudiobookshelfConfig"]:
+    """Build :class:`AudiobookshelfConfig` from a settings dict.
+
+    Returns ``None`` when required fields (base_url, api_token, library_id)
+    are missing.
+    """
+    from abogen.integrations.audiobookshelf import AudiobookshelfConfig
+
+    base_url = str(settings.get("base_url") or "").strip()
+    api_token = str(settings.get("api_token") or "").strip()
+    library_id = str(settings.get("library_id") or "").strip()
+    if not (base_url and api_token and library_id):
+        return None
+    try:
+        timeout = float(settings.get("timeout", 3600.0))
+    except (TypeError, ValueError):
+        timeout = 3600.0
+    return AudiobookshelfConfig(
+        base_url=base_url,
+        api_token=api_token,
+        library_id=library_id,
+        collection_id=(str(settings.get("collection_id") or "").strip() or None),
+        folder_id=(str(settings.get("folder_id") or "").strip() or None),
+        verify_ssl=coerce_bool(settings.get("verify_ssl"), True),
+        send_cover=coerce_bool(settings.get("send_cover"), True),
+        send_chapters=coerce_bool(settings.get("send_chapters"), True),
+        send_subtitles=coerce_bool(settings.get("send_subtitles"), False),
+        timeout=timeout,
+    )

abogen/domain/speaker_metadata.py

@@ -0,0 +1,381 @@
+"""Speaker metadata functions for building and applying speaker rosters.
+
+This module contains the core logic for:
+- Building narrator and speaker rosters from analysis results
+- Matching speakers to configured presets
+- Applying speaker config presets to rosters
+- Preparing full speaker metadata for conversion
+
+Moved from webui/routes/utils/voice.py to be available across all UIs.
+"""
+
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Tuple, cast
+
+from abogen.speaker_analysis import analyze_speakers
+from abogen.speaker_configs import slugify_label
+from abogen.domain.settings_core import load_settings
+
+
+def build_narrator_roster(
+    voice: str,
+    voice_profile: Optional[str],
+    existing: Optional[Mapping[str, Any]] = None,
+) -> Dict[str, Any]:
+    roster: Dict[str, Any] = {
+        "narrator": {
+            "id": "narrator",
+            "label": "Narrator",
+            "voice": voice,
+        }
+    }
+    if voice_profile:
+        roster["narrator"]["voice_profile"] = voice_profile
+    existing_entry: Optional[Mapping[str, Any]] = None
+    if existing is not None:
+        existing_entry = existing.get("narrator") if isinstance(existing, Mapping) else None
+    if isinstance(existing_entry, Mapping):
+        roster_entry = roster["narrator"]
+        for key in ("label", "voice", "voice_profile", "voice_formula", "pronunciation"):
+            value = existing_entry.get(key)
+            if value is not None and value != "":
+                roster_entry[key] = value
+    return roster
+
+
+def build_speaker_roster(
+    analysis: Dict[str, Any],
+    base_voice: str,
+    voice_profile: Optional[str],
+    existing: Optional[Mapping[str, Any]] = None,
+    order: Optional[Iterable[str]] = None,
+) -> Dict[str, Any]:
+    roster = build_narrator_roster(base_voice, voice_profile, existing)
+    existing_map: Dict[str, Any] = dict(existing) if isinstance(existing, Mapping) else {}
+    speakers = analysis.get("speakers", {}) if isinstance(analysis, dict) else {}
+    ordered_ids: Iterable[str]
+    if order is not None:
+        ordered_ids = [sid for sid in order if sid in speakers]
+    else:
+        ordered_ids = speakers.keys()
+
+    for speaker_id in ordered_ids:
+        payload = speakers.get(speaker_id, {})
+        if speaker_id == "narrator":
+            continue
+        if isinstance(payload, Mapping) and payload.get("suppressed"):
+            continue
+        previous = existing_map.get(speaker_id)
+        roster[speaker_id] = {
+            "id": speaker_id,
+            "label": payload.get("label") or speaker_id.replace("_", " ").title(),
+            "analysis_confidence": payload.get("confidence"),
+            "analysis_count": payload.get("count"),
+            "gender": payload.get("gender", "unknown"),
+        }
+        detected_gender = payload.get("detected_gender")
+        if detected_gender:
+            roster[speaker_id]["detected_gender"] = detected_gender
+        samples = payload.get("sample_quotes")
+        if isinstance(samples, list):
+            roster[speaker_id]["sample_quotes"] = samples
+        if isinstance(previous, Mapping):
+            for key in ("voice", "voice_profile", "voice_formula", "resolved_voice", "pronunciation"):
+                value = previous.get(key)
+                if value is not None and value != "":
+                    roster[speaker_id][key] = value
+            if "sample_quotes" not in roster[speaker_id]:
+                prev_samples = previous.get("sample_quotes")
+                if isinstance(prev_samples, list):
+                    roster[speaker_id]["sample_quotes"] = prev_samples
+            if "detected_gender" not in roster[speaker_id]:
+                prev_detected = previous.get("detected_gender")
+                if isinstance(prev_detected, str) and prev_detected:
+                    roster[speaker_id]["detected_gender"] = prev_detected
+    return roster
+
+
+def match_configured_speaker(
+    config_speakers: Mapping[str, Any],
+    roster_id: str,
+    roster_label: str,
+) -> Optional[Mapping[str, Any]]:
+    if not config_speakers:
+        return None
+    entry = config_speakers.get(roster_id)
+    if entry:
+        return cast(Mapping[str, Any], entry)
+    slug = slugify_label(roster_label)
+    if slug != roster_id and slug in config_speakers:
+        return cast(Mapping[str, Any], config_speakers[slug])
+    lower_label = roster_label.strip().lower()
+    for record in config_speakers.values():
+        if not isinstance(record, Mapping):
+            continue
+        if str(record.get("label", "")).strip().lower() == lower_label:
+            return record
+    return None
+
+
+def apply_speaker_config_to_roster(
+    roster: Mapping[str, Any],
+    config: Optional[Mapping[str, Any]],
+    *,
+    persist_changes: bool = False,
+    fallback_languages: Optional[Iterable[str]] = None,
+) -> Tuple[Dict[str, Any], List[str], Optional[Dict[str, Any]]]:
+    if not isinstance(roster, Mapping):
+        effective_languages = [code for code in (fallback_languages or []) if isinstance(code, str) and code]
+        return {}, effective_languages, None
+    updated_roster: Dict[str, Any] = {key: dict(value) for key, value in roster.items() if isinstance(value, Mapping)}
+    if not config:
+        effective_languages = [code for code in (fallback_languages or []) if isinstance(code, str) and code]
+        return updated_roster, effective_languages, None
+
+    speakers_map = config.get("speakers")
+    if not isinstance(speakers_map, Mapping):
+        effective_languages = [code for code in (fallback_languages or []) if isinstance(code, str) and code]
+        return updated_roster, effective_languages, None
+
+    config_languages = config.get("languages")
+    if isinstance(config_languages, list):
+        allowed_languages = [code for code in config_languages if isinstance(code, str) and code]
+    else:
+        allowed_languages = []
+    if not allowed_languages and fallback_languages:
+        allowed_languages = [code for code in fallback_languages if isinstance(code, str) and code]
+
+    default_voice = config.get("default_voice") if isinstance(config.get("default_voice"), str) else ""
+    used_voices = {entry.get("resolved_voice") or entry.get("voice") for entry in updated_roster.values()} - {None}
+    narrator_voice = ""
+    narrator_entry = updated_roster.get("narrator") if isinstance(updated_roster, Mapping) else None
+    if isinstance(narrator_entry, Mapping):
+        narrator_voice = str(
+            narrator_entry.get("resolved_voice")
+            or narrator_entry.get("default_voice")
+            or ""
+        ).strip()
+        if narrator_voice:
+            used_voices.add(narrator_voice)
+
+    config_changed = False
+    new_config_payload: Dict[str, Any] = {
+        "language": config.get("language", "a"),
+        "languages": allowed_languages,
+        "default_voice": default_voice,
+        "speakers": dict(speakers_map),
+        "version": config.get("version", 1),
+        "notes": config.get("notes", ""),
+    }
+
+    speakers_payload = new_config_payload["speakers"]
+
+    for speaker_id, roster_entry in updated_roster.items():
+        if speaker_id == "narrator":
+            continue
+        label = str(roster_entry.get("label") or speaker_id)
+        config_entry = match_configured_speaker(speakers_map, speaker_id, label)
+        if config_entry is None:
+            continue
+        voice_id = str(config_entry.get("voice") or "").strip()
+        voice_profile = str(config_entry.get("voice_profile") or "").strip()
+        voice_formula = str(config_entry.get("voice_formula") or "").strip()
+        resolved_voice = str(config_entry.get("resolved_voice") or "").strip()
+        languages = config_entry.get("languages") if isinstance(config_entry.get("languages"), list) else []
+        chosen_voice = resolved_voice or voice_formula or voice_id or roster_entry.get("voice")
+        usable_languages = languages or allowed_languages
+
+        if chosen_voice:
+            roster_entry["resolved_voice"] = chosen_voice
+            roster_entry["voice"] = chosen_voice if not voice_profile and not voice_formula else roster_entry.get("voice", chosen_voice)
+        if voice_profile:
+            roster_entry["voice_profile"] = voice_profile
+        if voice_formula:
+            roster_entry["voice_formula"] = voice_formula
+            roster_entry["resolved_voice"] = voice_formula
+        if not voice_formula and not voice_profile and resolved_voice:
+            roster_entry["resolved_voice"] = resolved_voice
+        roster_entry["config_languages"] = usable_languages or []
+
+        if chosen_voice:
+            used_voices.add(chosen_voice)
+
+        # persist updates back to config payload if required
+        if persist_changes:
+            slug = config_entry.get("id") or slugify_label(label)
+            speakers_payload[slug] = {
+                "id": slug,
+                "label": label,
+                "gender": config_entry.get("gender", "unknown"),
+                "voice": voice_id,
+                "voice_profile": voice_profile,
+                "voice_formula": voice_formula,
+                "resolved_voice": roster_entry.get("resolved_voice", resolved_voice or voice_id),
+                "languages": usable_languages,
+            }
+
+    new_config = new_config_payload if (persist_changes and config_changed) else None
+    return updated_roster, allowed_languages, new_config
+
+
+def prepare_speaker_metadata(
+    *,
+    chapters: List[Dict[str, Any]],
+    chunks: List[Dict[str, Any]],
+    analysis_chunks: Optional[List[Dict[str, Any]]] = None,
+    voice: str,
+    voice_profile: Optional[str],
+    threshold: int,
+    existing_roster: Optional[Mapping[str, Any]] = None,
+    run_analysis: bool = True,
+    speaker_config: Optional[Mapping[str, Any]] = None,
+    apply_config: bool = False,
+    persist_config: bool = False,
+    inject_recommended: Optional[Any] = None,
+) -> tuple[List[Dict[str, Any]], Dict[str, Any], Dict[str, Any], List[str], Optional[Dict[str, Any]]]:
+    chunk_list = [dict(chunk) for chunk in chunks]
+    analysis_source = [dict(chunk) for chunk in (analysis_chunks or chunks)]
+    threshold_value = max(1, int(threshold))
+    analysis_enabled = run_analysis
+    settings_state = load_settings()
+    global_random_languages = [
+        code
+        for code in settings_state.get("speaker_random_languages", [])
+        if isinstance(code, str) and code
+    ]
+
+    if not analysis_enabled:
+        for chunk in chunk_list:
+            chunk["speaker_id"] = "narrator"
+            chunk["speaker_label"] = "Narrator"
+        analysis_payload = {
+            "version": "1.0",
+            "narrator": "narrator",
+            "assignments": {str(chunk.get("id")): "narrator" for chunk in chunk_list},
+            "speakers": {
+                "narrator": {
+                    "id": "narrator",
+                    "label": "Narrator",
+                    "count": len(chunk_list),
+                    "confidence": "low",
+                    "sample_quotes": [],
+                    "suppressed": False,
+                }
+            },
+            "suppressed": [],
+            "stats": {
+                "total_chunks": len(chunk_list),
+                "explicit_chunks": 0,
+                "active_speakers": 0,
+                "unique_speakers": 1,
+                "suppressed": 0,
+            },
+        }
+        roster = build_narrator_roster(voice, voice_profile, existing_roster)
+        narrator_pron = roster["narrator"].get("pronunciation")
+        if narrator_pron:
+            analysis_payload["speakers"]["narrator"]["pronunciation"] = narrator_pron
+        return chunk_list, roster, analysis_payload, [], None
+
+    analysis_result = analyze_speakers(
+        chapters,
+        analysis_source,
+        threshold=threshold_value,
+        max_speakers=0,
+    )
+    analysis_payload = analysis_result.to_dict()
+    speakers_payload = analysis_payload.get("speakers", {})
+    ordered_ids = [
+        sid
+        for sid, meta in sorted(
+            (
+                (sid, meta)
+                for sid, meta in speakers_payload.items()
+                if sid != "narrator" and isinstance(meta, Mapping) and not meta.get("suppressed")
+            ),
+            key=lambda item: item[1].get("count", 0),
+            reverse=True,
+        )
+    ]
+    analysis_payload["ordered_speakers"] = ordered_ids
+    assignments = analysis_payload.get("assignments", {})
+    suppressed_ids = analysis_payload.get("suppressed", [])
+    suppressed_details: List[Dict[str, Any]] = []
+    speakers_payload = analysis_payload.get("speakers", {})
+    if isinstance(suppressed_ids, Iterable):
+        for suppressed_id in suppressed_ids:
+            speaker_meta = speakers_payload.get(suppressed_id) if isinstance(speakers_payload, dict) else None
+            if isinstance(speaker_meta, dict):
+                suppressed_details.append(
+                    {
+                        "id": suppressed_id,
+                        "label": speaker_meta.get("label")
+                        or str(suppressed_id).replace("_", " ").title(),
+                        "pronunciation": speaker_meta.get("pronunciation"),
+                    }
+                )
+            else:
+                suppressed_details.append(
+                    {
+                        "id": suppressed_id,
+                        "label": str(suppressed_id).replace("_", " ").title(),
+                        "pronunciation": None,
+                    }
+                )
+    analysis_payload["suppressed_details"] = suppressed_details
+    roster = build_speaker_roster(
+        analysis_payload,
+        voice,
+        voice_profile,
+        existing=existing_roster,
+        order=analysis_payload.get("ordered_speakers"),
+    )
+    applied_languages: List[str] = []
+    updated_config: Optional[Dict[str, Any]] = None
+    if apply_config and speaker_config:
+        roster, applied_languages, updated_config = apply_speaker_config_to_roster(
+            roster,
+            speaker_config,
+            persist_changes=persist_config,
+            fallback_languages=global_random_languages,
+        )
+        speakers_payload = analysis_payload.get("speakers")
+        if isinstance(speakers_payload, dict):
+            for roster_id, roster_payload in roster.items():
+                speaker_meta = speakers_payload.get(roster_id)
+                if isinstance(speaker_meta, dict):
+                    for key in ("voice", "voice_profile", "voice_formula", "resolved_voice"):
+                        value = roster_payload.get(key)
+                        if value:
+                            speaker_meta[key] = value
+    effective_languages: List[str] = []
+    if applied_languages:
+        effective_languages = applied_languages
+    elif isinstance(analysis_payload.get("config_languages"), list):
+        effective_languages = [
+            code for code in analysis_payload.get("config_languages", []) if isinstance(code, str) and code
+        ]
+    elif global_random_languages:
+        effective_languages = list(global_random_languages)
+
+    if effective_languages:
+        analysis_payload["config_languages"] = effective_languages
+    speakers_payload = analysis_payload.get("speakers")
+    if isinstance(speakers_payload, dict):
+        for roster_id, roster_payload in roster.items():
+            if roster_id in speakers_payload and isinstance(roster_payload, dict):
+                pronunciation_value = roster_payload.get("pronunciation")
+                if pronunciation_value:
+                    speakers_payload[roster_id]["pronunciation"] = pronunciation_value
+
+    fallback_languages = effective_languages or []
+    if callable(inject_recommended):
+        inject_recommended(roster, fallback_languages=fallback_languages)
+
+    for chunk in chunk_list:
+        chunk_id = str(chunk.get("id"))
+        speaker_id = assignments.get(chunk_id, "narrator")
+        chunk["speaker_id"] = speaker_id
+        speaker_meta = roster.get(speaker_id)
+        chunk["speaker_label"] = speaker_meta.get("label") if isinstance(speaker_meta, dict) else speaker_id
+
+    return chunk_list, roster, analysis_payload, applied_languages, updated_config

abogen/domain/split_pattern.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+"""Unified split pattern logic extracted from 3 copies."""
+
+from abogen.domain.enums import Language, SubtitleMode
+
+# Canonical punctuation sets covering all supported scripts:
+# ASCII (. ! ?), Arabic ؟, CJK (。！？), Devanagari ।
+PUNCTUATION_SENTENCE = r".!?؟。！？।"
+# Commas: ASCII , CJK fullwidth ，CJK ideographic 、
+PUNCTUATION_SENTENCE_COMMA = r".!?,？。！？،，、।"
+PUNCTUATION_COMMAS = ",，、"
+
+
+def get_split_pattern(language: Language, subtitle_mode: str) -> str:
+    """Get the appropriate split pattern based on language and subtitle mode.
+
+    Args:
+        language: Language enum value, ISO code, or kokoro letter code.
+        subtitle_mode: Subtitle mode ("Sentence", "Sentence + Comma", "Line", etc.)
+
+    Returns:
+        Split pattern string
+    """
+    try:
+        mode = SubtitleMode.from_str(subtitle_mode) if not isinstance(subtitle_mode, SubtitleMode) else subtitle_mode
+    except ValueError:
+        mode = SubtitleMode.DISABLED
+
+    # English: spaCy is NOT used for pre-TTS segmentation (it is only used
+    # for post-TTS subtitle boundaries), so sentence boundaries for English
+    # are applied at subtitle time, not in the TTS engine. Disabled, Line,
+    # Sentence, and Sentence + Comma all keep newline-only engine splitting.
+    if language in (Language.EN_US, Language.EN_GB):
+        if mode in (
+            SubtitleMode.DISABLED,
+            SubtitleMode.LINE,
+            SubtitleMode.SENTENCE,
+            SubtitleMode.SENTENCE_COMMA,
+        ):
+            return "\n"
+
+    # Determine spacing pattern based on language
+    spacing = r"\s*" if language.is_cjk else r"\s+"
+
+    # For CJK languages, when subtitle mode is Disabled or Line, prefer
+    # punctuation-based splitting instead of plain newline splitting.
+    if mode in (SubtitleMode.DISABLED, SubtitleMode.LINE) and language.is_cjk:
+        return rf"(?<=[{PUNCTUATION_SENTENCE}]){spacing}|\n+"
+
+    if mode == SubtitleMode.LINE:
+        return "\n"
+    elif mode == SubtitleMode.SENTENCE:
+        return rf"(?<=[{PUNCTUATION_SENTENCE}]){spacing}|\n+"
+    elif mode == SubtitleMode.SENTENCE_COMMA:
+        return rf"(?<=[{PUNCTUATION_SENTENCE_COMMA}]){spacing}|\n+"
+    else:
+        return r"\n+"

abogen/domain/subtitle_generation.py

@@ -0,0 +1,366 @@
+"""Subtitle generation utilities for audiobook generation.
+
+This module provides functions for processing TTS tokens into subtitle entries
+according to various subtitle modes (Line, Sentence, Sentence + Comma,
+Sentence + Highlighting).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Tuple
+
+from abogen.domain.enums import Language, SubtitleMode
+from abogen.domain.split_pattern import PUNCTUATION_SENTENCE, PUNCTUATION_SENTENCE_COMMA
+
+
+def process_subtitle_tokens(
+    tokens_with_timestamps: List[dict],
+    subtitle_entries: List[Tuple[float, float, str]],
+    max_subtitle_words: int,
+    subtitle_mode: str,
+    language: Language,
+    use_spacy_segmentation: bool = False,
+    fallback_end_time: Optional[float] = None,
+) -> None:
+    """Process TTS tokens into subtitle entries according to the subtitle mode.
+    
+    This function modifies subtitle_entries in-place by appending new entries.
+    
+    Args:
+        tokens_with_timestamps: List of token dictionaries with 'start', 'end', 'text',
+            and 'whitespace' keys.
+        subtitle_entries: List to append subtitle entries to (modified in-place).
+            Each entry is a tuple of (start_time, end_time, text).
+        max_subtitle_words: Maximum number of words per subtitle entry.
+        subtitle_mode: One of "Disabled", "Line", "Sentence", "Sentence + Comma",
+            "Sentence + Highlighting", or a string like "5" for word-count mode.
+        language: Language enum value for spaCy processing.
+        use_spacy_segmentation: Whether to use spaCy for sentence boundary detection.
+        fallback_end_time: Fallback end time for the last entry if none is available.
+    """
+    if not tokens_with_timestamps:
+        return
+
+    processed_tokens = tokens_with_timestamps
+
+    # For English with spaCy enabled and sentence-based modes, use spaCy for sentence boundaries
+    # spaCy is disabled when subtitle mode is "Disabled" or "Line"
+    use_spacy_for_english = (
+        use_spacy_segmentation
+        and subtitle_mode not in [SubtitleMode.DISABLED, SubtitleMode.LINE]
+        and language in [Language.EN_US, Language.EN_GB]
+        and subtitle_mode in [SubtitleMode.SENTENCE, SubtitleMode.SENTENCE_COMMA]
+    )
+
+    if subtitle_mode == SubtitleMode.SENTENCE_HIGHLIGHT:
+        _process_karaoke_highlighting(
+            processed_tokens, subtitle_entries, max_subtitle_words, fallback_end_time
+        )
+    elif subtitle_mode in [SubtitleMode.SENTENCE, SubtitleMode.SENTENCE_COMMA, SubtitleMode.LINE]:
+        if use_spacy_for_english and subtitle_mode != SubtitleMode.LINE:
+            _process_spacy_sentences(
+                processed_tokens, subtitle_entries, max_subtitle_words,
+                subtitle_mode, language, fallback_end_time
+            )
+        else:
+            _process_regex_sentences(
+                processed_tokens, subtitle_entries, max_subtitle_words,
+                subtitle_mode, fallback_end_time
+            )
+    else:
+        # Word count-based grouping (e.g., "5" for 5-word groups)
+        _process_word_count(
+            processed_tokens, subtitle_entries, max_subtitle_words,
+            subtitle_mode, fallback_end_time
+        )
+
+
+def _process_karaoke_highlighting(
+    tokens: List[dict],
+    subtitle_entries: List[Tuple[float, float, str]],
+    max_subtitle_words: int,
+    fallback_end_time: Optional[float],
+) -> None:
+    """Process tokens for Sentence + Highlighting mode (karaoke effect)."""
+    separator = rf"[{PUNCTUATION_SENTENCE}]"
+    current_sentence = []
+    word_count = 0
+
+    for token in tokens:
+        current_sentence.append(token)
+        word_count += 1
+
+        # Split sentences based on separator or word count
+        if (
+            re.search(separator, token["text"]) and token.get("whitespace") == " "
+        ) or word_count >= max_subtitle_words:
+            if current_sentence:
+                # Create karaoke subtitle entry for this sentence
+                start_time = current_sentence[0]["start"]
+                end_time = current_sentence[-1]["end"]
+
+                # Generate karaoke text with timing
+                karaoke_text = ""
+                for t in current_sentence:
+                    # Calculate duration in centiseconds
+                    duration = (
+                        t["end"] - t["start"]
+                        if t.get("end") is not None and t.get("start") is not None
+                        else 0.5
+                    )
+                    duration_cs = int(duration * 100)
+                    # Add karaoke effect
+                    karaoke_text += f"{{\\kf{duration_cs}}}{t['text']}{t.get('whitespace', '') or ''}"
+
+                subtitle_entries.append(
+                    (start_time, end_time, karaoke_text.strip())
+                )
+                current_sentence = []
+                word_count = 0
+
+    # Add any remaining tokens as a sentence
+    if current_sentence:
+        start_time = current_sentence[0]["start"]
+        end_time = current_sentence[-1]["end"]
+
+        # Generate karaoke text for remaining tokens
+        karaoke_text = ""
+        for t in current_sentence:
+            duration = t["end"] - t["start"] if t.get("end") and t.get("start") else 0.5
+            duration_cs = int(duration * 100)
+            karaoke_text += f"{{\\kf{duration_cs}}}{t['text']}{t.get('whitespace', '') or ''}"
+        subtitle_entries.append((start_time, end_time, karaoke_text.strip()))
+
+    # Fallback for last entry
+    _apply_fallback_end_time(subtitle_entries, fallback_end_time)
+
+
+def _process_spacy_sentences(
+    tokens: List[dict],
+    subtitle_entries: List[Tuple[float, float, str]],
+    max_subtitle_words: int,
+    subtitle_mode: str,
+    language: Language,
+    fallback_end_time: Optional[float],
+) -> None:
+    """Process tokens using spaCy for sentence boundary detection."""
+    try:
+        from abogen.spacy_utils import get_spacy_model
+    except ImportError:
+        # Fall back to regex if spaCy is not available
+        _process_regex_sentences(
+            tokens, subtitle_entries, max_subtitle_words,
+            subtitle_mode, fallback_end_time
+        )
+        return
+
+    nlp = get_spacy_model(language)
+    if not nlp:
+        _process_regex_sentences(
+            tokens, subtitle_entries, max_subtitle_words,
+            subtitle_mode, fallback_end_time
+        )
+        return
+
+    # Build full text and track character positions to token indices
+    full_text = ""
+    for token in tokens:
+        text_part = token["text"] + (token.get("whitespace") or "")
+        full_text += text_part
+
+    # Get sentence boundaries from spaCy
+    doc = nlp(full_text)
+    sentence_boundaries = [sent.end_char for sent in doc.sents]
+
+    # For "Sentence + Comma" mode, also split on commas
+    if subtitle_mode == SubtitleMode.SENTENCE_COMMA:
+        comma_positions = [
+            i + 1 for i, c in enumerate(full_text) if c == ","
+        ]
+        sentence_boundaries = sorted(
+            set(sentence_boundaries + comma_positions)
+        )
+
+    # Group tokens by sentence boundaries
+    current_sentence = []
+    word_count = 0
+    current_char_pos = 0
+    boundary_idx = 0
+
+    for token in tokens:
+        current_sentence.append(token)
+        word_count += 1
+        text_len = len(token["text"]) + len(token.get("whitespace") or "")
+        current_char_pos += text_len
+
+        # Check if we've hit a sentence boundary or max words
+        at_boundary = (
+            boundary_idx < len(sentence_boundaries)
+            and current_char_pos >= sentence_boundaries[boundary_idx]
+        )
+        if at_boundary or word_count >= max_subtitle_words:
+            if current_sentence:
+                start_time = current_sentence[0]["start"]
+                end_time = current_sentence[-1]["end"]
+                sentence_text = "".join(
+                    t["text"] + (t.get("whitespace") or "")
+                    for t in current_sentence
+                )
+                subtitle_entries.append(
+                    (start_time, end_time, sentence_text.strip())
+                )
+                current_sentence = []
+                word_count = 0
+            if at_boundary:
+                boundary_idx += 1
+
+    # Add remaining tokens
+    if current_sentence:
+        start_time = current_sentence[0]["start"]
+        end_time = current_sentence[-1]["end"]
+        sentence_text = "".join(
+            t["text"] + (t.get("whitespace") or "")
+            for t in current_sentence
+        )
+        subtitle_entries.append(
+            (start_time, end_time, sentence_text.strip())
+        )
+
+    # Fallback for last entry
+    _apply_fallback_end_time(subtitle_entries, fallback_end_time)
+
+
+def _process_regex_sentences(
+    tokens: List[dict],
+    subtitle_entries: List[Tuple[float, float, str]],
+    max_subtitle_words: int,
+    subtitle_mode: str,
+    fallback_end_time: Optional[float],
+) -> None:
+    """Process tokens using regex for sentence boundary detection."""
+    # Define separator pattern based on mode
+    if subtitle_mode == SubtitleMode.LINE:
+        separator = r"\n"
+    elif subtitle_mode == SubtitleMode.SENTENCE:
+        separator = rf"[{PUNCTUATION_SENTENCE}]"
+    else:  # Sentence + Comma
+        separator = rf"[{PUNCTUATION_SENTENCE_COMMA}]"
+
+    current_sentence = []
+    word_count = 0
+
+    for token in tokens:
+        current_sentence.append(token)
+        word_count += 1
+
+        # Split sentences based on separator or word count
+        if (
+            re.search(separator, token["text"]) and token.get("whitespace") == " "
+        ) or word_count >= max_subtitle_words:
+            if current_sentence:
+                # Create subtitle entry for this sentence
+                start_time = current_sentence[0]["start"]
+                end_time = current_sentence[-1]["end"]
+
+                # Simplified text joining logic
+                sentence_text = ""
+                for t in current_sentence:
+                    sentence_text += t["text"] + (t.get("whitespace") or "")
+
+                subtitle_entries.append(
+                    (start_time, end_time, sentence_text.strip())
+                )
+                current_sentence = []
+                word_count = 0
+
+    # Add any remaining tokens as a sentence (split multi-sentence FakeToken)
+    if current_sentence:
+        start_time = current_sentence[0]["start"]
+        end_time = current_sentence[-1]["end"]
+
+        sentence_text = ""
+        for t in current_sentence:
+            sentence_text += t["text"] + (t.get("whitespace") or "")
+        sentence_text = sentence_text.strip()
+
+        if len(current_sentence) == 1:
+            parts = re.split(rf"(?<={separator})\s+", sentence_text)
+            if len(parts) > 1:
+                d = end_time - start_time
+                for i, p in enumerate(parts):
+                    e = end_time if i == len(parts) - 1 else start_time + d * len(p) / len(sentence_text)
+                    subtitle_entries.append((start_time, e, p.strip()))
+                    start_time = e
+                current_sentence = []
+
+        if current_sentence:
+            subtitle_entries.append((start_time, end_time, sentence_text))
+
+    # Fallback for last entry
+    _apply_fallback_end_time(subtitle_entries, fallback_end_time)
+
+
+def _process_word_count(
+    tokens: List[dict],
+    subtitle_entries: List[Tuple[float, float, str]],
+    max_subtitle_words: int,
+    subtitle_mode: str,
+    fallback_end_time: Optional[float],
+) -> None:
+    """Process tokens by counting spaces (word count mode)."""
+    try:
+        word_count = int(subtitle_mode.split()[0])
+        word_count = min(word_count, max_subtitle_words)
+    except (ValueError, IndexError):
+        word_count = 1
+
+    current_group = []
+    space_count = 0
+
+    for token in tokens:
+        current_group.append(token)
+
+        # Count spaces after tokens (in the whitespace field)
+        if token.get("whitespace", "") == " ":
+            space_count += 1
+
+            # Split after counting N spaces
+            if space_count >= word_count:
+                text = "".join(
+                    t["text"] + (t.get("whitespace") or "")
+                    for t in current_group
+                )
+                subtitle_entries.append(
+                    (
+                        current_group[0]["start"],
+                        current_group[-1]["end"],
+                        text.strip(),
+                    )
+                )
+                current_group = []
+                space_count = 0
+
+    # Add any remaining tokens
+    if current_group:
+        text = "".join(
+            t["text"] + (t.get("whitespace") or "") for t in current_group
+        )
+        subtitle_entries.append(
+            (current_group[0]["start"], current_group[-1]["end"], text.strip())
+        )
+
+    # Fallback for last entry
+    _apply_fallback_end_time(subtitle_entries, fallback_end_time)
+
+
+def _apply_fallback_end_time(
+    subtitle_entries: List[Tuple[float, float, str]],
+    fallback_end_time: Optional[float],
+) -> None:
+    """Apply fallback end time to the last entry if needed."""
+    if subtitle_entries and fallback_end_time is not None:
+        last_entry = subtitle_entries[-1]
+        start, end, text = last_entry
+        if end is None or end <= start or end <= 0:
+            subtitle_entries[-1] = (start, fallback_end_time, text)

abogen/domain/subtitle_processor.py

@@ -0,0 +1,278 @@
+"""Subtitle-to-audio processing pipeline.
+
+Converts subtitle files (SRT/ASS/VTT/timestamp text) into audio by
+generating TTS for each entry and mixing into a buffer.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, List, Optional, Tuple
+
+import numpy as np
+
+from abogen.domain.audio_buffer import (
+    fit_audio_to_duration,
+    ffmpeg_time_stretch,
+    mix_audio,
+    normalize_audio,
+    SAMPLE_RATE,
+)
+from abogen.domain.audio_helpers import to_float32
+from abogen.domain.progress import calc_etr_str
+from abogen.subtitle_utils import (
+    parse_ass_file,
+    parse_srt_file,
+    parse_vtt_file,
+    parse_timestamp_text_file,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SubtitleEntry:
+    """A single subtitle entry with timing."""
+    start: float
+    end: Optional[float]
+    text: str
+
+
+def parse_subtitle_file(
+    file_path: str,
+    is_timestamp_text: bool = False,
+) -> List[Tuple[float, Optional[float], str]]:
+    """Parse a subtitle file into (start, end, text) tuples.
+
+    Args:
+        file_path: Path to subtitle file.
+        is_timestamp_text: Whether to treat as timestamp text file.
+
+    Returns:
+        List of (start_time, end_time, text) tuples.
+    """
+    if is_timestamp_text:
+        return parse_timestamp_text_file(file_path)
+
+    import os
+    ext = os.path.splitext(file_path)[1].lower()
+    if ext == ".srt":
+        return parse_srt_file(file_path)
+    elif ext == ".vtt":
+        return parse_vtt_file(file_path)
+    else:
+        return parse_ass_file(file_path)
+
+
+def format_time_range(
+    start: float,
+    end: Optional[float],
+    is_auto_end: bool = False,
+) -> str:
+    """Format a time range for display in logs.
+
+    Args:
+        start: Start time in seconds.
+        end: End time in seconds, or None.
+        is_auto_end: Whether end time is auto-detected.
+
+    Returns:
+        Formatted string like "00:01:23,456 - 00:01:25,789" or "00:01:23 - AUTO".
+    """
+    def _fmt(seconds: float) -> str:
+        h = int(seconds // 3600)
+        m = int(seconds % 3600 // 60)
+        s = int(seconds % 60)
+        ms = int((seconds - int(seconds)) * 1000)
+        result = f"{h:02d}:{m:02d}:{s:02d}"
+        if ms > 0:
+            result += f",{ms:03d}"
+        return result
+
+    if is_auto_end or end is None:
+        return f"{_fmt(start)} - AUTO"
+    return f"{_fmt(start)} - {_fmt(end)}"
+
+
+def speed_up_audio(
+    audio: np.ndarray,
+    speed_factor: float,
+    method: str = "tts",
+    *,
+    backend: Any = None,
+    text: str = "",
+    voice: Any = None,
+    base_speed: float = 1.0,
+    sample_rate: int = SAMPLE_RATE,
+) -> np.ndarray:
+    """Speed up audio to fit a time window.
+
+    Args:
+        audio: Input audio buffer.
+        speed_factor: Required speed multiplier.
+        method: "ffmpeg" for time-stretch, "tts" for regeneration.
+        backend: TTS backend (required if method="tts").
+        text: Text to regenerate (required if method="tts").
+        voice: Voice to use for regeneration.
+        base_speed: Base speed for TTS.
+        sample_rate: Sample rate.
+
+    Returns:
+        Speed-adjusted audio buffer.
+    """
+    if speed_factor <= 1.0:
+        return audio
+
+    if method == "ffmpeg":
+        logger.info("FFmpeg time-stretch: %.2fx", speed_factor)
+        return ffmpeg_time_stretch(audio, speed_factor, sample_rate)
+
+    # TTS regeneration
+    if backend is None:
+        return audio
+    new_speed = base_speed * speed_factor
+    logger.info("Regenerating at %.2fx speed", new_speed)
+    results = [
+        r for r in backend(text, voice=voice, speed=new_speed, split_pattern=None)
+    ]
+    chunks = [r.audio for r in results]
+    if not chunks:
+        return audio
+    return np.concatenate([to_float32(c) for c in chunks])
+
+
+def process_subtitle_entries(
+    subtitles: List[Tuple[float, Optional[float], str]],
+    *,
+    backend: Any,
+    voice: Any,
+    speed: float = 1.0,
+    cancel_check: Callable[[], bool] = lambda: False,
+    log_callback: Optional[Callable[[str], None]] = None,
+    progress_callback: Optional[Callable[[int, str], None]] = None,
+    replace_newlines: bool = True,
+    use_gaps: bool = False,
+    is_timestamp_text: bool = False,
+    subtitle_speed_method: str = "tts",
+    sample_rate: int = SAMPLE_RATE,
+) -> np.ndarray:
+    """Process subtitle entries: generate TTS for each and mix into buffer.
+
+    This is the core domain logic for subtitle-to-audio conversion.
+    UI-specific concerns (signals, widgets) are handled via callbacks.
+
+    Args:
+        subtitles: List of (start, end, text) tuples.
+        backend: TTS pipeline callable.
+        voice: Resolved voice for TTS.
+        speed: TTS speed.
+        cancel_check: Returns True if processing should stop.
+        log_callback: Called with log messages.
+        progress_callback: Called with (percent, etr_string).
+        replace_newlines: Replace \\n with spaces in text.
+        use_gaps: Whether to use silent gaps between subtitles.
+        is_timestamp_text: Whether input is timestamp text.
+        subtitle_speed_method: "ffmpeg" or "tts" for speed adjustment.
+        sample_rate: Audio sample rate.
+
+    Returns:
+        Mixed audio buffer (float32).
+    """
+    if not subtitles:
+        return np.array([], dtype="float32")
+
+    max_end = max((end for _, end, _ in subtitles if end is not None), default=0)
+    buffer_samples = int(max_end * sample_rate) + sample_rate
+    audio_buffer = np.zeros(buffer_samples, dtype="float32")
+    etr_start = time.time()
+    total = len(subtitles)
+
+    for idx, (start_time, end_time, text) in enumerate(subtitles, 1):
+        if cancel_check():
+            break
+
+        processed_text = text.replace("\n", " ") if replace_newlines else text
+        next_start = (
+            subtitles[idx][0]
+            if (use_gaps and idx < total)
+            else float("inf")
+        )
+        subtitle_duration = None if end_time is None else end_time - start_time
+
+        is_auto_end = is_timestamp_text or (use_gaps and idx == total) or end_time is None
+        if log_callback:
+            log_callback(
+                f"\n[{idx}/{total}] {format_time_range(start_time, end_time, is_auto_end)}: {processed_text}"
+            )
+
+        # Generate TTS
+        results = [
+            r for r in backend(
+                processed_text, voice=voice, speed=speed, split_pattern=None
+            )
+            if not cancel_check()
+        ]
+        if cancel_check():
+            break
+
+        audio_chunks = [r.audio for r in results]
+        full_audio = (
+            np.concatenate([to_float32(a) for a in audio_chunks])
+            if audio_chunks
+            else np.zeros(int((subtitle_duration or 0) * sample_rate), dtype="float32")
+        )
+        audio_duration = len(full_audio) / sample_rate
+
+        # Timing adjustment
+        if is_timestamp_text:
+            end_time = start_time + audio_duration
+            subtitle_duration = audio_duration
+        elif use_gaps:
+            end_time = min(start_time + audio_duration, next_start)
+            subtitle_duration = end_time - start_time
+        elif subtitle_duration is None:
+            subtitle_duration = audio_duration
+            end_time = start_time + audio_duration
+
+        # Speed up if needed
+        speedup_threshold = next_start - start_time if use_gaps else subtitle_duration
+        if audio_duration > speedup_threshold and speedup_threshold > 0:
+            speed_factor = audio_duration / speedup_threshold
+            full_audio = speed_up_audio(
+                full_audio, speed_factor,
+                method=subtitle_speed_method,
+                backend=backend, text=processed_text,
+                voice=voice, base_speed=speed,
+                sample_rate=sample_rate,
+            )
+            audio_duration = len(full_audio) / sample_rate
+
+        # Adjust duration after speed change
+        if use_gaps:
+            end_time = min(start_time + audio_duration, next_start)
+            subtitle_duration = end_time - start_time
+        elif subtitle_duration is None:
+            subtitle_duration = audio_duration
+            end_time = start_time + audio_duration
+
+        # Pad or trim to subtitle duration
+        full_audio = fit_audio_to_duration(full_audio, subtitle_duration, sample_rate)
+
+        # Mix into buffer
+        start_sample = int(start_time * sample_rate)
+        audio_buffer = mix_audio(audio_buffer, full_audio, start_sample)
+
+        # Progress
+        if progress_callback:
+            percent = min(int(idx / total * 100), 99)
+            etr = calc_etr_str(time.time() - etr_start, idx, total)
+            progress_callback(percent, etr)
+
+    # Normalize if needed
+    if np.abs(audio_buffer).max() > 1.0:
+        logger.info("Normalizing audio (peak: %.2f)", np.abs(audio_buffer).max())
+        audio_buffer = normalize_audio(audio_buffer)
+
+    return audio_buffer

abogen/domain/text_chapters.py

@@ -0,0 +1,59 @@
+"""Chapter parsing from raw text.
+
+Provides a unified function for splitting text by chapter markers,
+used by both WebUI and PyQt conversion runners.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Tuple
+
+from abogen.subtitle_utils import clean_text
+
+
+_CHAPTER_MARKER_RE = re.compile(r"<<CHAPTER_MARKER:(.*?)>>", re.IGNORECASE)
+
+
+def parse_chapters_from_text(
+    text: str,
+    default_title: str = "text",
+    clean: bool = True,
+) -> List[Tuple[str, str]]:
+    """Split raw text into chapters using chapter marker patterns.
+
+    Preserves content before the first marker as "Introduction" if present.
+    Optionally applies clean_text() to each chapter segment.
+
+    Args:
+        text: Raw text possibly containing <<CHAPTER_MARKER:Title>> markers.
+        default_title: Fallback title when no markers are found.
+        clean: Whether to apply clean_text() to each segment.
+
+    Returns:
+        List of (title, text) tuples.
+    """
+    matches = list(_CHAPTER_MARKER_RE.finditer(text))
+    if not matches:
+        cleaned = clean_text(text) if clean else text
+        return [(default_title, cleaned)]
+
+    chapters: List[Tuple[str, str]] = []
+
+    # Preserve content before first marker as "Introduction"
+    first_start = matches[0].start()
+    if first_start > 0:
+        intro_text = text[:first_start].strip()
+        if intro_text:
+            chapters.append(("Introduction", clean_text(intro_text) if clean else intro_text))
+
+    for idx, match in enumerate(matches):
+        start = match.end()
+        end = matches[idx + 1].start() if idx + 1 < len(matches) else len(text)
+        chapter_name = match.group(1).strip() or default_title
+        chapter_text = text[start:end].strip()
+        if clean:
+            chapter_text = clean_text(chapter_text)
+        chapters.append((chapter_name, chapter_text))
+
+    return chapters

abogen/domain/text_utils.py

@@ -0,0 +1,22 @@
+"""Text utility functions for the domain layer."""
+
+from __future__ import annotations
+
+import re
+
+# Pre-compiled patterns for calculate_text_length
+_METADATA_TAG_PATTERN = re.compile(r"<<METADATA_[^:]+:[^>]*>>")
+_CHAPTER_MARKER_PATTERN = re.compile(r"<<CHAPTER_MARKER:[^>]*>>")
+_VOICE_MARKER_PATTERN = re.compile(r"<<VOICE:[^>]*>>")
+
+
+def calculate_text_length(text: str) -> int:
+    """Calculate character count, ignoring internal markers and newlines.
+
+    Strips chapter markers, voice markers, and metadata tags before counting.
+    """
+    text = _CHAPTER_MARKER_PATTERN.sub("", text)
+    text = _VOICE_MARKER_PATTERN.sub("", text)
+    text = _METADATA_TAG_PATTERN.sub("", text)
+    text = text.replace("\n", "").strip()
+    return len(text)

abogen/domain/title_builder.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, List, Mapping, Optional
+
+from .metadata_helpers import (
+    ensure_sentence,
+    extract_series_metadata,
+    format_author_sentence,
+    format_series_sentence,
+    normalize_metadata_map,
+)
+
+
+def build_title_intro_text(
+    metadata: Optional[Mapping[str, Any]],
+    fallback_basename: str,
+) -> str:
+    """Build the title introduction text from metadata."""
+    normalized = normalize_metadata_map(metadata)
+    fallback_title = Path(fallback_basename).stem if fallback_basename else ""
+    title = (
+        normalized.get("title")
+        or normalized.get("book_title")
+        or normalized.get("album")
+        or fallback_title
+    )
+    if not title:
+        title = fallback_title
+    subtitle = normalized.get("subtitle") or normalized.get("sub_title")
+    if subtitle and title and subtitle.casefold() == title.casefold():
+        subtitle = ""
+
+    author_value = ""
+    for candidate in ("artist", "album_artist", "author", "authors", "writer", "composer"):
+        value = normalized.get(candidate)
+        if value:
+            author_value = value
+            break
+
+    series_name, series_number = extract_series_metadata(normalized)
+    series_sentence = format_series_sentence(series_name, series_number)
+
+    sentences: List[str] = []
+    if series_sentence:
+        sentences.append(ensure_sentence(series_sentence))
+    if title:
+        sentences.append(ensure_sentence(title))
+    if subtitle:
+        sentences.append(ensure_sentence(subtitle))
+    author_sentence = format_author_sentence(author_value)
+    if author_sentence:
+        sentences.append(ensure_sentence(author_sentence))
+    return " ".join(sentences).strip()
+
+
+def build_outro_text(
+    metadata: Optional[Mapping[str, Any]],
+    fallback_basename: str,
+) -> str:
+    """Build the outro/closing text from metadata."""
+    normalized = normalize_metadata_map(metadata)
+    fallback_title = Path(fallback_basename).stem if fallback_basename else ""
+    title = (
+        normalized.get("title")
+        or normalized.get("book_title")
+        or normalized.get("album")
+        or fallback_title
+    )
+    author_value = ""
+    for candidate in ("authors", "author", "album_artist", "artist", "writer", "composer"):
+        value = normalized.get(candidate)
+        if value:
+            author_value = value
+            break
+    author_sentence = format_author_sentence(author_value)
+    authors_fragment = (
+        author_sentence[3:].strip() if author_sentence.lower().startswith("by ") else author_sentence.strip()
+    )
+
+    if title and authors_fragment:
+        closing_line = f"The end of {title} from {authors_fragment}"
+    elif title:
+        closing_line = f"The end of {title}"
+    elif authors_fragment:
+        closing_line = f"The end from {authors_fragment}"
+    else:
+        closing_line = "The end"
+
+    series_name, series_number = extract_series_metadata(normalized)
+    series_sentence = format_series_sentence(series_name, series_number)
+
+    sentences: List[str] = [ensure_sentence(closing_line)]
+    if series_sentence:
+        sentences.append(ensure_sentence(series_sentence))
+
+    return " ".join(sentence for sentence in sentences if sentence).strip()

abogen/domain/tokens.py

@@ -0,0 +1,13 @@
+"""Shared token stubs for TTS processing."""
+
+from __future__ import annotations
+
+
+class FakeToken:
+    """Minimal token stub for languages without per-word token support."""
+
+    def __init__(self, text: str, start: float, end: float):
+        self.text = text
+        self.start_ts = start
+        self.end_ts = end
+        self.whitespace = ""

abogen/domain/voice_catalog.py

@@ -0,0 +1,112 @@
+"""Voice catalog — shared voice metadata for all UIs.
+
+Builds a unified catalog of available voices with metadata (language,
+gender, display name). Used by both WebUI and PyQt for voice selection UIs.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Mapping, Optional
+
+from abogen.constants import LANGUAGE_DESCRIPTIONS
+from abogen.tts_plugin.utils import get_voices
+
+
+def build_voice_catalog() -> List[Dict[str, str]]:
+    """Build voice catalog with metadata for all available voices.
+
+    Returns a list of dicts, each containing:
+        - id: voice ID (e.g. "af_heart")
+        - language: language code (e.g. "a", "e")
+        - language_label: human-readable language name
+        - gender: "Female", "Male", or "Unknown"
+        - gender_code: "f", "m", or ""
+        - display_name: human-readable voice name
+    """
+    from plugins.kokoro.engine import language_for_voice_id
+
+    catalog: List[Dict[str, str]] = []
+    gender_map = {"f": "Female", "m": "Male"}
+    for voice_id in get_voices("kokoro"):
+        prefix, _, rest = voice_id.partition("_")
+        gender_code = prefix[1] if len(prefix) > 1 else ""
+        lang = language_for_voice_id(voice_id)
+        catalog.append(
+            {
+                "id": voice_id,
+                "language": lang.value,
+                "language_label": LANGUAGE_DESCRIPTIONS.get(lang, lang.value.upper()),
+                "gender": gender_map.get(gender_code, "Unknown"),
+                "gender_code": gender_code,
+                "display_name": rest.replace("_", " ").title() if rest else voice_id,
+            }
+        )
+    return catalog
+
+
+def filter_voice_catalog(
+    catalog: Iterable[Mapping[str, Any]],
+    *,
+    gender: str,
+    allowed_languages: Optional[Iterable[str]] = None,
+) -> List[str]:
+    """Filter voice catalog by gender and language.
+
+    Returns voice IDs that match the criteria. Falls back to broader
+    matches if no exact matches are found.
+
+    Args:
+        catalog: Voice catalog entries (from build_voice_catalog).
+        gender: Gender filter ("male", "female", or "unknown").
+        allowed_languages: Optional list of allowed language codes.
+
+    Returns:
+        List of matching voice IDs.
+    """
+    allowed_set = {code.lower() for code in (allowed_languages or []) if isinstance(code, str) and code}
+    gender_normalized = (gender or "unknown").lower()
+    gender_code = ""
+    if gender_normalized == "male":
+        gender_code = "m"
+    elif gender_normalized == "female":
+        gender_code = "f"
+
+    matches: List[str] = []
+    seen: set[str] = set()
+
+    def _consider(entry: Mapping[str, Any]) -> None:
+        voice_id = entry.get("id")
+        if not isinstance(voice_id, str) or not voice_id:
+            return
+        if voice_id in seen:
+            return
+        seen.add(voice_id)
+        matches.append(voice_id)
+
+    primary: List[Mapping[str, Any]] = []
+    fallback: List[Mapping[str, Any]] = []
+    for entry in catalog:
+        if not isinstance(entry, Mapping):
+            continue
+        voice_lang = str(entry.get("language", "")).lower()
+        voice_gender_code = str(entry.get("gender_code", "")).lower()
+        if allowed_set and voice_lang not in allowed_set:
+            continue
+        if gender_code and voice_gender_code != gender_code:
+            fallback.append(entry)
+            continue
+        primary.append(entry)
+
+    for entry in primary:
+        _consider(entry)
+
+    if not matches:
+        for entry in fallback:
+            _consider(entry)
+
+    if not matches:
+        for entry in catalog:
+            if isinstance(entry, Mapping):
+                _consider(entry)
+
+    return matches

abogen/domain/voice_loader.py

@@ -0,0 +1,128 @@
+"""Voice loading and caching utilities.
+
+This module provides unified voice loading with caching support for both
+PyQt and WebUI interfaces.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from abogen.voice_formulas import get_new_voice
+
+
+class VoiceCache:
+    """Thread-safe voice cache for loaded voice tensors."""
+    
+    def __init__(self):
+        self._cache: Dict[str, Any] = {}
+    
+    def get(self, voice_spec: str) -> Optional[Any]:
+        """Get cached voice by spec."""
+        return self._cache.get(voice_spec)
+    
+    def set(self, voice_spec: str, voice: Any) -> None:
+        """Cache a loaded voice."""
+        self._cache[voice_spec] = voice
+    
+    def contains(self, voice_spec: str) -> bool:
+        """Check if voice is in cache."""
+        return voice_spec in self._cache
+    
+    def clear(self) -> None:
+        """Clear all cached voices."""
+        self._cache.clear()
+
+    def keys(self):
+        """Return cached voice specs."""
+        return self._cache.keys()
+
+    def __contains__(self, voice_spec: str) -> bool:
+        return self.contains(voice_spec)
+
+
+def resolve_voice(
+    voice_spec: str,
+    pipeline: Any,
+    use_gpu: bool,
+    cache: Optional[VoiceCache] = None,
+) -> Any:
+    """Resolve voice spec to actual voice tensor or name.
+    
+    If voice_spec contains '*' (formula), loads the voice using get_new_voice.
+    Otherwise, returns the voice_spec as-is (it's a voice name).
+    
+    Uses optional cache to avoid reloading same voice multiple times.
+    
+    Args:
+        voice_spec: Voice specification (name or formula string with '*').
+        pipeline: TTS pipeline instance for loading formula voices.
+        use_gpu: Whether to use GPU for voice loading.
+        cache: Optional VoiceCache instance for caching loaded voices.
+        
+    Returns:
+        Loaded voice tensor (for formulas) or voice name string.
+    """
+    # Check cache first
+    if cache and cache.contains(voice_spec):
+        return cache.get(voice_spec)
+
+    # Load voice
+    if "*" in voice_spec:
+        if pipeline is None or not hasattr(pipeline, "load_single_voice"):
+            return voice_spec
+        loaded_voice = get_new_voice(pipeline, voice_spec, use_gpu)
+    else:
+        loaded_voice = voice_spec
+    
+    # Cache it
+    if cache:
+        cache.set(voice_spec, loaded_voice)
+    
+    return loaded_voice
+
+
+def load_voice_cached(
+    voice_name: str,
+    pipeline: Any,
+    use_gpu: bool,
+    cache: Any = None,
+) -> Any:
+    """Load voice with caching (compatibility wrapper for PyQt).
+
+    This function maintains backward compatibility with the PyQt interface
+    while using the unified voice loading logic.
+
+    Args:
+        voice_name: Voice name or formula string.
+        pipeline: TTS pipeline instance.
+        use_gpu: Whether to use GPU.
+        cache: Optional VoiceCache or dict to use as cache.
+
+    Returns:
+        Loaded voice tensor or voice name string.
+    """
+    # Check cache (supports both VoiceCache and plain dict)
+    if cache is not None:
+        if isinstance(cache, VoiceCache):
+            if cache.contains(voice_name):
+                return cache.get(voice_name)
+        elif voice_name in cache:
+            return cache[voice_name]
+
+    # Load voice
+    if "*" in voice_name:
+        if pipeline is None or not hasattr(pipeline, "load_single_voice"):
+            return voice_name
+        loaded_voice = get_new_voice(pipeline, voice_name, use_gpu)
+    else:
+        loaded_voice = voice_name
+
+    # Cache it
+    if cache is not None:
+        if isinstance(cache, VoiceCache):
+            cache.set(voice_name, loaded_voice)
+        else:
+            cache[voice_name] = loaded_voice
+
+    return loaded_voice

abogen/domain/voice_markers.py

@@ -0,0 +1,117 @@
+"""Voice marker parsing and text splitting.
+
+Handles <<VOICE:name>> markers in text, splitting text into voice-specific
+segments. This is domain logic about text segmentation by voice, not subtitle
+processing.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Tuple
+
+_VOICE_MARKER_PATTERN = re.compile(r"<<VOICE:[^>]*>>")
+_VOICE_MARKER_SEARCH_PATTERN = re.compile(r"<<VOICE:(.*?)>>")
+
+
+def validate_voice_name(voice_name: str) -> Tuple[bool, str | None]:
+    """Validate voice name against available voices (case-insensitive).
+
+    Handles both single voices and formulas like 'af_heart*0.5 + am_echo*0.5'.
+
+    Returns:
+        Tuple of (is_valid, invalid_voice_name):
+            - is_valid: True if all voices in the name/formula are valid
+            - invalid_voice_name: The first invalid voice found, or None if all valid
+    """
+    from abogen.tts_plugin.utils import get_voices
+
+    voice_lookup_lower = {v.lower() for v in get_voices("kokoro")}
+    voice_name = voice_name.strip()
+
+    if "*" in voice_name:
+        voices = voice_name.split("+")
+        for term in voices:
+            if "*" in term:
+                base_voice = term.split("*")[0].strip()
+                if base_voice.lower() not in voice_lookup_lower:
+                    return False, base_voice
+        return True, None
+    else:
+        if voice_name.lower() not in voice_lookup_lower:
+            return False, voice_name
+        return True, None
+
+
+def split_text_by_voice_markers(
+    text: str, default_voice: str
+) -> Tuple[List[Tuple[str, str]], str, int, int]:
+    """Split text by voice markers, returning list of (voice, text) tuples.
+
+    Returns the last voice used so it can persist across chapters.
+    Voice names are normalized to lowercase to match canonical voice names.
+
+    Args:
+        text: Text potentially containing <<VOICE:name>> markers
+        default_voice: Voice to use if no markers found or before first marker
+
+    Returns:
+        Tuple of (segments_list, last_voice_used, valid_count, invalid_count):
+            - segments_list: List of (voice_name, segment_text) tuples
+            - last_voice_used: The voice that should continue into next chapter
+            - valid_count: Number of valid voice markers processed
+            - invalid_count: Number of invalid voice markers skipped
+    """
+    from abogen.tts_plugin.utils import get_voices
+
+    voice_splits = list(_VOICE_MARKER_SEARCH_PATTERN.finditer(text))
+
+    if not voice_splits:
+        return [(default_voice, text)], default_voice, 0, 0
+
+    segments: List[Tuple[str, str]] = []
+    current_voice = default_voice
+    valid_markers = 0
+    invalid_markers = 0
+
+    first_start = voice_splits[0].start()
+    if first_start > 0:
+        intro_text = text[:first_start].strip()
+        if intro_text:
+            segments.append((current_voice, intro_text))
+
+    for idx, match in enumerate(voice_splits):
+        voice_name = match.group(1).strip()
+        start = match.end()
+        end = voice_splits[idx + 1].start() if idx + 1 < len(voice_splits) else len(text)
+        segment_text = text[start:end].strip()
+
+        is_valid, invalid_voice = validate_voice_name(voice_name)
+        if is_valid:
+            if "*" in voice_name:
+                normalized_parts = []
+                for part in voice_name.split("+"):
+                    part = part.strip()
+                    if "*" in part:
+                        voice_part, weight = part.split("*", 1)
+                        voice_part_lower = voice_part.strip().lower()
+                        canonical_voice = next(
+                            (v for v in get_voices("kokoro") if v.lower() == voice_part_lower),
+                            voice_part.strip()
+                        )
+                        normalized_parts.append(f"{canonical_voice}*{weight.strip()}")
+                current_voice = " + ".join(normalized_parts)
+            else:
+                voice_name_lower = voice_name.lower()
+                current_voice = next(
+                    (v for v in get_voices("kokoro") if v.lower() == voice_name_lower),
+                    voice_name
+                )
+            valid_markers += 1
+        else:
+            invalid_markers += 1
+
+        if segment_text:
+            segments.append((current_voice, segment_text))
+
+    return segments, current_voice, valid_markers, invalid_markers

abogen/domain/voice_resolution.py

@@ -0,0 +1,355 @@
+"""Voice resolution helpers.
+
+Functions for resolving voice specifications, collecting required voice IDs,
+and determining the voice to use for chapters and chunks.
+
+All functions accept ConversionRequest (the app-layer contract) instead of
+UI-specific objects. This keeps the domain layer UI-agnostic.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional, Set, Tuple
+
+from abogen.tts_plugin.utils import get_voices, get_default_voice
+from abogen.voice_formulas import extract_voice_ids, pairs_to_formula
+from abogen.voice_cache import ensure_voice_assets
+
+
+def spec_to_voice_ids(spec: Any) -> Set[str]:
+    text = str(spec or "").strip()
+    if not text:
+        return set()
+    if text == "__custom_mix":
+        return set()
+    if "*" in text:
+        try:
+            return set(extract_voice_ids(text))
+        except ValueError:
+            return set()
+    if text in get_voices("kokoro"):
+        return {text}
+    return set()
+
+
+def _get_chapter_overrides(request: Any) -> list:
+    """Extract chapter overrides from ConversionRequest."""
+    cc = getattr(request, "chapter_chunk", None)
+    if cc is not None:
+        return getattr(cc, "chapter_overrides", []) or []
+    return []
+
+
+def _get_chunks(request: Any) -> list:
+    """Extract chunks from ConversionRequest."""
+    cc = getattr(request, "chapter_chunk", None)
+    if cc is not None:
+        return getattr(cc, "chunks", []) or []
+    return []
+
+
+def job_voice_fallback(request: Any) -> str:
+    base = str(getattr(request, "voice", "") or "").strip()
+    if base and base != "__custom_mix":
+        return base
+
+    speakers = getattr(request, "speakers", None)
+    if isinstance(speakers, dict):
+        narrator = speakers.get("narrator")
+        if isinstance(narrator, dict):
+            for key in ("resolved_voice", "voice_formula", "voice"):
+                value = narrator.get(key)
+                candidate = str(value or "").strip()
+                if candidate and candidate != "__custom_mix":
+                    return candidate
+        for payload in speakers.values() or []:
+            if not isinstance(payload, dict):
+                continue
+            for key in ("resolved_voice", "voice_formula", "voice"):
+                value = payload.get(key)
+                candidate = str(value or "").strip()
+                if candidate and candidate != "__custom_mix":
+                    return candidate
+
+    for chapter in _get_chapter_overrides(request):
+        if not isinstance(chapter, dict):
+            continue
+        for key in ("resolved_voice", "voice_formula", "voice"):
+            candidate = str(chapter.get(key) or "").strip()
+            if candidate and candidate != "__custom_mix":
+                return candidate
+
+    return ""
+
+
+def collect_required_voice_ids(request: Any) -> Set[str]:
+    voices: Set[str] = set()
+    voices.update(spec_to_voice_ids(request.voice))
+    voices.update(spec_to_voice_ids(job_voice_fallback(request)))
+
+    for chapter in _get_chapter_overrides(request):
+        if not isinstance(chapter, dict):
+            continue
+        for key in ("resolved_voice", "voice_formula", "voice"):
+            voices.update(spec_to_voice_ids(chapter.get(key)))
+
+    for chunk in _get_chunks(request):
+        if not isinstance(chunk, dict):
+            continue
+        for key in ("resolved_voice", "voice_formula", "voice"):
+            voices.update(spec_to_voice_ids(chunk.get(key)))
+
+    speakers = getattr(request, "speakers", {})
+    if isinstance(speakers, dict):
+        for payload in speakers.values() or []:
+            if not isinstance(payload, dict):
+                continue
+            for key in ("resolved_voice", "voice_formula", "voice"):
+                voices.update(spec_to_voice_ids(payload.get(key)))
+
+    voices.update(get_voices("kokoro"))
+    return voices
+
+
+def initialize_voice_cache(request: Any, events: Any = None) -> None:
+    """Initialize voice cache by downloading required voice assets.
+
+    Args:
+        request: ConversionRequest with voice/chapter/chunk/speaker info.
+        events: ConversionEvents for logging (optional, for backward compat).
+    """
+    log = (lambda msg, level="info": events.log(msg, level=level)) if events else (lambda msg, level="info": None)
+
+    try:
+        targets = collect_required_voice_ids(request)
+        downloaded, errors = ensure_voice_assets(
+            targets,
+            on_progress=lambda message: log(message, level="debug"),
+        )
+    except RuntimeError as exc:
+        log(f"Voice cache unavailable: {exc}", level="warning")
+        return
+
+    if downloaded:
+        log(
+            f"Cached {len(downloaded)} voice asset{'s' if len(downloaded) != 1 else ''} locally.",
+            level="info",
+        )
+
+    for voice_id, error in errors.items():
+        log(f"Failed to cache voice '{voice_id}': {error}", level="warning")
+
+
+def chapter_voice_spec(request: Any, override: Optional[Dict[str, Any]]) -> str:
+    if not override:
+        return job_voice_fallback(request)
+
+    resolved = str(override.get("resolved_voice", "")).strip()
+    if resolved:
+        return resolved
+
+    formula = str(override.get("voice_formula", "")).strip()
+    if formula:
+        return formula
+
+    voice = str(override.get("voice", "")).strip()
+    if voice:
+        return voice
+
+    return job_voice_fallback(request)
+
+
+def chunk_voice_spec(request: Any, chunk: Dict[str, Any], fallback: str) -> str:
+    for key in ("resolved_voice", "voice_formula", "voice"):
+        value = chunk.get(key)
+        if value:
+            return str(value)
+
+    speaker_id = chunk.get("speaker_id")
+    speakers = getattr(request, "speakers", None)
+    if isinstance(speakers, dict) and speaker_id in speakers:
+        speaker_entry = speakers.get(speaker_id) or {}
+        if isinstance(speaker_entry, dict):
+            for key in ("resolved_voice", "voice_formula", "voice"):
+                value = speaker_entry.get(key)
+                if value:
+                    return str(value)
+            profile_formula = speaker_entry.get("voice_formula")
+            if profile_formula:
+                return str(profile_formula)
+
+    profile_name = chunk.get("voice_profile")
+    if profile_name:
+        if isinstance(speakers, dict):
+            speaker_entry = speakers.get(profile_name)
+            if isinstance(speaker_entry, dict):
+                for key in ("resolved_voice", "voice_formula", "voice"):
+                    value = speaker_entry.get(key)
+                    if value:
+                        return str(value)
+
+    if fallback:
+        return fallback
+    return job_voice_fallback(request)
+
+
+def resolve_fallback_voice_spec(
+    base_spec: str,
+    job_voice: str,
+    voice_cache_keys: list[str],
+    provider: str = "kokoro",
+) -> str:
+    """Resolve the voice spec for intro/outro with a priority fallback chain.
+
+    Priority: base_spec → job_voice → first voice_cache key → default voice.
+    ``"__custom_mix"`` is treated as empty (it is not a usable voice spec).
+    """
+    spec = base_spec or job_voice
+    if spec == "__custom_mix":
+        spec = job_voice or ""
+    if not spec:
+        for key in voice_cache_keys:
+            if key and key != "__custom_mix":
+                spec = key.split(":", 1)[-1]
+                break
+    if not spec:
+        spec = get_default_voice(provider)
+    return spec
+
+
+# ---------------------------------------------------------------------------
+# Voice choice resolution (shared by all UIs)
+# ---------------------------------------------------------------------------
+
+
+def formula_from_profile(entry: Dict[str, Any]) -> Optional[str]:
+    """Convert a voice profile entry to a voice formula string.
+
+    Handles both Kokoro (voices list) and SuperTonic (single voice) profiles.
+    Returns None if the entry has no usable voice data.
+    """
+    if not isinstance(entry, dict):
+        return None
+    voices = entry.get("voices") or []
+    if not voices:
+        return None
+    return pairs_to_formula(voices)
+
+
+def resolve_profile_voice(
+    profile_name: Optional[str],
+    *,
+    profiles: Optional[Mapping[str, Any]] = None,
+) -> Tuple[str, Optional[str]]:
+    """Resolve a profile name to (formula, language).
+
+    Args:
+        profile_name: Name of the profile to resolve.
+        profiles: Pre-loaded profiles dict. If None, loads from disk.
+
+    Returns:
+        (formula_string, language_code) or ("", None) if not found.
+    """
+    if not profile_name:
+        return "", None
+    source = profiles if isinstance(profiles, Mapping) else None
+    if source is None:
+        from abogen.voice_profiles import load_profiles
+        source = load_profiles()
+    entry = source.get(profile_name) if isinstance(source, Mapping) else None
+    if not isinstance(entry, Mapping):
+        return "", None
+    formula = formula_from_profile(dict(entry)) or ""
+    language = entry.get("language") if isinstance(entry.get("language"), str) else None
+    if isinstance(language, str):
+        language = language.strip().lower() or None
+    return formula, language
+
+
+def resolve_voice_setting(
+    value: Any,
+    *,
+    profiles: Optional[Mapping[str, Any]] = None,
+) -> Tuple[str, Optional[str], Optional[str]]:
+    """Resolve a raw voice setting value into (spec, profile_name, language).
+
+    Parses 'profile:name' or 'speaker:name' prefixes and resolves
+    the profile to a formula string.
+
+    Args:
+        value: Raw voice value from user input (e.g. "af_heart", "profile:MyMix").
+        profiles: Pre-loaded profiles dict. If None, loads from disk.
+
+    Returns:
+        (resolved_spec, profile_name, language) — profile_name and language
+        are None when the input is a plain voice spec.
+    """
+    from abogen.domain.settings_core import split_profile_spec
+
+    base_spec, profile_name = split_profile_spec(value)
+    if profile_name:
+        formula, language = resolve_profile_voice(profile_name, profiles=profiles)
+        return formula or "", profile_name, language
+    return base_spec, None, None
+
+
+def resolve_voice_choice(
+    language: str,
+    base_voice: str,
+    profile_name: str,
+    custom_formula: str,
+    profiles: Dict[str, Any],
+) -> Tuple[str, str, Optional[str]]:
+    """Resolve a user's voice selection into (resolved_voice, resolved_language, selected_profile).
+
+    Handles three input modes:
+    1. Profile selection → resolves to formula (Kokoro) or speaker reference (SuperTonic)
+    2. Custom formula → used directly
+    3. Plain voice spec → passed through
+
+    Args:
+        language: Current language code (e.g. "a", "e").
+        base_voice: Base voice spec (voice ID or formula).
+        profile_name: Selected profile name (empty string if none).
+        custom_formula: Custom formula string (empty string if none).
+        profiles: Dict of all available profiles.
+
+    Returns:
+        (resolved_voice, resolved_language, selected_profile)
+    """
+    from abogen.voice_profiles import normalize_profile_entry
+
+    resolved_voice = base_voice
+    resolved_language = language
+    selected_profile = None
+
+    if profile_name:
+        entry_raw = profiles.get(profile_name)
+        entry = normalize_profile_entry(entry_raw)
+        provider = str((entry or {}).get("provider") or "").strip().lower()
+
+        # Provider-aware behavior:
+        # - Kokoro profiles typically represent mixes (formula strings).
+        # - SuperTonic profiles represent a discrete voice id + settings.
+        #   In that case, we return a speaker reference so downstream can
+        #   resolve provider per-speaker and allow mixed-provider casting.
+        if provider == "supertonic":
+            resolved_voice = f"speaker:{profile_name}"
+            selected_profile = profile_name
+            profile_language = (entry or {}).get("language")
+            if profile_language:
+                resolved_language = str(profile_language)
+        else:
+            formula = formula_from_profile(entry or {}) if entry else None
+            if formula:
+                resolved_voice = formula
+                selected_profile = profile_name
+                profile_language = (entry or {}).get("language")
+                if profile_language:
+                    resolved_language = profile_language
+
+    if custom_formula:
+        resolved_voice = custom_formula
+        selected_profile = None
+
+    return resolved_voice, resolved_language, selected_profile

abogen/domain/voice_utils.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional, Tuple
+
+from abogen.tts_plugin.utils import get_voices
+
+
+def infer_provider_from_spec(value: Any, fallback: str = "kokoro") -> str:
+    """Infer TTS provider from voice specification."""
+    raw = str(value or "").strip()
+    if not raw:
+        return fallback
+    if raw.upper() == raw and raw.replace("_", "").isalnum():
+        return "supertonic"
+    if raw == "__custom_mix" or "*" in raw or "+" in raw:
+        return "kokoro"
+    if raw in get_voices("kokoro"):
+        return "kokoro"
+    return fallback
+
+
+def supertonic_voice_from_spec(spec: Any, fallback: str) -> str:
+    """Normalize a voice specification for Supertonic.
+
+    This function only performs Supertonic-specific normalization (uppercase conversion
+    and fallback handling). Backend resolution is handled by the registry.
+    """
+    raw = str(spec or "").strip()
+    fallback_raw = str(fallback or "").strip()
+
+    # Normalize to uppercase for Supertonic voice IDs
+    upper = raw.upper() if raw else ""
+
+    # If empty or contains formula characters, use fallback
+    if not upper or "*" in upper or "+" in upper:
+        upper = fallback_raw.upper() if fallback_raw else ""
+
+    # If still empty, use default Supertonic voice
+    if not upper or "*" in upper or "+" in upper:
+        upper = "M1"
+
+    return upper
+
+
+def split_speaker_reference(value: Any) -> Tuple[Optional[str], str]:
+    """Parse speaker/profile reference from string.
+
+    Expected format: "speaker:name" or "profile:name"
+    Returns (name, original) or (None, original) if not a valid reference.
+    """
+    raw = str(value or "").strip()
+    if not raw or ":" not in raw:
+        return None, raw
+    prefix, remainder = raw.split(":", 1)
+    prefix = prefix.strip().lower()
+    if prefix not in {"speaker", "profile"}:
+        return None, raw
+    name = remainder.strip()
+    return (name or None), raw
+
+
+def formula_from_kokoro_entry(entry: Mapping[str, Any]) -> str:
+    """Build voice formula string from kokoro entry."""
+    voices = entry.get("voices") or []
+    if not voices:
+        return ""
+    total = 0.0
+    parts: list[tuple[str, float]] = []
+    for item in voices:
+        if not isinstance(item, (list, tuple)) or len(item) < 2:
+            continue
+        name = str(item[0] or "").strip()
+        try:
+            weight = float(item[1])
+        except (TypeError, ValueError):
+            continue
+        if name and weight > 0:
+            parts.append((name, weight))
+            total += weight
+
+    if not parts:
+        return ""
+
+    normalized = [(name, weight / total) for name, weight in parts]
+    return " + ".join(f"{name}*{weight:.6f}" for name, weight in normalized)
+
+
+def coerce_truthy(value: Any, default: bool = True) -> bool:
+    """Coerce a value to boolean with default."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.lower() not in {"false", "0", "no", "off", ""}
+    if value is None:
+        return default
+    return bool(value)
+
+
+def resolve_voice_target(
+    raw_spec: str,
+    normalized_profiles: Dict[str, Dict[str, Any]],
+    *,
+    job_voice: str = "M1",
+    job_tts_provider: str = "kokoro",
+    job_supertonic_total_steps: int = 5,
+    job_speed: float = 1.0,
+) -> Tuple[str, str, Optional[float], Optional[int]]:
+    """Resolve a raw voice spec into (provider, voice_spec, speed_override, steps_override).
+
+    Pure function — all dependencies are passed as parameters.
+    """
+    spec = str(raw_spec or "").strip()
+    speaker_name, _ = split_speaker_reference(spec)
+    if speaker_name and speaker_name in normalized_profiles:
+        entry = normalized_profiles[speaker_name]
+        provider = str(entry.get("provider") or "kokoro").strip().lower() or "kokoro"
+        if provider == "supertonic":
+            voice = str(entry.get("voice") or job_voice or "M1").strip() or "M1"
+            steps = int(entry.get("total_steps") or job_supertonic_total_steps or 5)
+            speed = float(entry.get("speed") or job_speed or 1.0)
+            return "supertonic", supertonic_voice_from_spec(voice, job_voice), speed, steps
+        formula = formula_from_kokoro_entry(entry)
+        return "kokoro", formula or spec, None, None
+
+    fallback_provider = str(job_tts_provider or "kokoro").strip().lower() or "kokoro"
+    inferred = infer_provider_from_spec(spec, fallback=fallback_provider)
+    if inferred == "supertonic":
+        return "supertonic", supertonic_voice_from_spec(spec, job_voice), None, None
+    return "kokoro", spec, None, None

abogen/entity_analysis.py

@@ -9,15 +9,26 @@ from collections import Counter
 from dataclasses import dataclass, field
 from typing import Any, Dict, Iterable, List, Mapping, Optional, Tuple
 
-try:  # pragma: no cover - fallback when spaCy not available during tests
-    import spacy  # type: ignore[import-not-found]
-except Exception:  # pragma: no cover - spaCy optional during runtime bootstrap
-    spacy = None
-
 _Language = Any  # type: ignore[misc,assignment]
 Doc = Any  # type: ignore[misc,assignment]
 Span = Any  # type: ignore[misc,assignment]
 
+_SPACY: Any = None
+_SPACY_LOADED = False
+
+
+def _get_spacy() -> Any:
+    """Import spaCy lazily (it pulls in torch/thinc, ~2s at startup)."""
+    global _SPACY, _SPACY_LOADED
+    if not _SPACY_LOADED:
+        _SPACY_LOADED = True
+        try:  # pragma: no cover - fallback when spaCy not available during tests
+            import spacy  # type: ignore[import-not-found]
+        except Exception:  # pragma: no cover - spaCy optional during runtime bootstrap
+            spacy = None
+        _SPACY = spacy
+    return _SPACY
+
 
 _TITLE_PREFIXES = (
     "mr",
@@ -167,6 +178,7 @@ def _resolve_model_name(language: str) -> str:
 
 
 def _load_model(language: str) -> Any:
+    spacy = _get_spacy()
     if spacy is None:
         raise EntityModelError(
             "spaCy is not available. Install spaCy to enable entity extraction."

abogen/epub3/exporter.py

@@ -12,6 +12,7 @@ from typing import Any, Dict, Iterable, List, Optional, Pattern, Sequence, Tuple
 import zipfile
 
 from abogen.text_extractor import ExtractedChapter, ExtractionResult
+from abogen.domain.metadata_helpers import normalize_metadata_map
 
 
 @dataclass(slots=True)
@@ -22,7 +23,7 @@ class ChunkOverlay:
     start: Optional[float]
     end: Optional[float]
     speaker_id: str
-    voice: Optional[str]
+    voice: Optional[Dict[str, str]]
     level: Optional[str] = None
     group_id: Optional[str] = None
 
@@ -59,7 +60,7 @@ class EPUB3PackageBuilder:
         self.output_path = output_path
         self.book_id = book_id or str(uuid.uuid4())
         self.extraction = extraction
-        self.metadata_tags = _normalize_metadata(metadata_tags)
+        self.metadata_tags = normalize_metadata_map(metadata_tags)
         self.chapter_markers = list(chapter_markers or [])
         self.chunk_markers = list(chunk_markers or [])
         self.chunks = list(chunks or [])
@@ -273,7 +274,7 @@ class EPUB3PackageBuilder:
                     start=_safe_float(marker.get("start")),
                     end=_safe_float(marker.get("end")),
                     speaker_id=speaker_id,
-                    voice=str(voice) if voice else None,
+                    voice=voice if isinstance(voice, dict) else None,
                     level=str(level) if level else None,
                     group_id=normalized_group_id,
                 )
@@ -516,9 +517,14 @@ def build_epub3_package(
     chunks: Iterable[Dict[str, Any]],
     audio_path: Path,
     speaker_mode: str = "single",
+    cover: "CoverConfig | None" = None,
     cover_image_path: Optional[Path] = None,
     cover_image_mime: Optional[str] = None,
 ) -> Path:
+    from abogen.domain.config_types import CoverConfig
+    if isinstance(cover, CoverConfig):
+        cover_image_path = cover.path
+        cover_image_mime = cover.mime
     builder = EPUB3PackageBuilder(
         output_path=output_path,
         book_id=book_id,
@@ -545,15 +551,6 @@ class ChunkLookup:
     by_chapter: Dict[int, List[Dict[str, Any]]]
 
 
-def _normalize_metadata(metadata: Optional[Dict[str, Any]]) -> Dict[str, str]:
-    normalized: Dict[str, str] = {}
-    for key, value in (metadata or {}).items():
-        if value is None:
-            continue
-        normalized[str(key).lower()] = str(value)
-    return normalized
-
-
 def _combine_metadata(*sources: Dict[str, Any]) -> Dict[str, str]:
     combined: Dict[str, str] = {}
     for source in sources:
@@ -696,7 +693,12 @@ def _group_chunks_for_render(chunks: Sequence[ChunkOverlay]) -> List[Tuple[Optio
 def _render_chunk_inline(chunk: ChunkOverlay) -> str:
     escaped_id = html.escape(chunk.id)
     speaker_attr = f" data-speaker=\"{html.escape(chunk.speaker_id)}\"" if chunk.speaker_id else ""
-    voice_attr = f" data-voice=\"{html.escape(chunk.voice)}\"" if chunk.voice else ""
+    voice_str = None
+    if chunk.voice and isinstance(chunk.voice, dict):
+        name = chunk.voice.get("voice", "")
+        provider = chunk.voice.get("provider", "")
+        voice_str = f"{name}@{provider}" if name and provider else name or None
+    voice_attr = f" data-voice=\"{html.escape(voice_str)}\"" if voice_str else ""
     level_attr = f" data-level=\"{html.escape(chunk.level)}\"" if chunk.level else ""
     raw_text = chunk.text or ""
     escaped_text = html.escape(raw_text)

abogen/heteronym_overrides.py

@@ -5,10 +5,21 @@ import re
 from dataclasses import dataclass
 from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
 
-try:  # pragma: no cover - optional dependency
-    import spacy  # type: ignore
-except Exception:  # pragma: no cover - spaCy may be unavailable in minimal environments
-    spacy = None
+_SPACY: Any = None
+_SPACY_LOADED = False
+
+
+def _get_spacy() -> Any:
+    """Import spaCy lazily (it pulls in torch/thinc, ~2s at startup)."""
+    global _SPACY, _SPACY_LOADED
+    if not _SPACY_LOADED:
+        _SPACY_LOADED = True
+        try:  # pragma: no cover - optional dependency
+            import spacy  # type: ignore
+        except Exception:  # pragma: no cover - spaCy may be unavailable in minimal environments
+            spacy = None
+        _SPACY = spacy
+    return _SPACY
 
 
 @dataclass(frozen=True)
@@ -184,6 +195,7 @@ def _build_replacement_sentence(
 
 
 def _load_spacy(language: str) -> Any:
+    spacy = _get_spacy()
     if spacy is None:
         return None
 
@@ -221,7 +233,7 @@ def extract_heteronym_overrides(
     if not lang.startswith("en"):
         return []
 
-    if spacy is None:
+    if _get_spacy() is None:
         return []
 
     nlp = _load_spacy(lang)

abogen/hf_tracker.py

@@ -19,7 +19,7 @@ def tracked_hf_hub_download(*args, **kwargs):
     try:
         local_kwargs = dict(kwargs)
         local_kwargs["local_files_only"] = True
-        hf_hub_download(*args, **local_kwargs)
+        return hf_hub_download(*args, **local_kwargs)
     except Exception:
         repo_id = kwargs.get("repo_id", "<unknown repo>")
         filename = kwargs.get("filename", "<unknown file>")

abogen/infrastructure/exporters.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import json
+import logging
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Mapping, Sequence
+
+import static_ffmpeg
+
+from abogen.domain.metadata_helpers import (
+    split_people_field,
+    split_simple_list,
+    first_nonempty,
+    extract_year,
+    normalize_series_sequence,
+    _SERIES_SEQUENCE_TAG_KEYS,
+)
+from abogen.epub3.exporter import build_epub3_package
+from abogen.utils import create_process
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ExportConfig:
+    """Configuration for export operations."""
+    ffmpeg_path: str = "ffmpeg"
+    verify_ssl: bool = True
+
+
+class ExportService:
+    """Unified service for audiobook exports (M4B, FFMETADATA, EPUB3, Audiobookshelf)."""
+    
+    def __init__(self, config: Optional[ExportConfig] = None):
+        self.config = config or ExportConfig()
+        static_ffmpeg.add_paths()
+    
+    # ----------------------------------------------------------------------
+    # FFMETADATA
+    # ----------------------------------------------------------------------
+    
+    def render_ffmetadata(
+        self,
+        metadata: Dict[str, Any],
+        chapters: List[Dict[str, Any]],
+    ) -> str:
+        """Render FFMETADATA content."""
+        lines = [";FFMETADATA1"]
+        
+        for key, value in (metadata or {}).items():
+            if value is None:
+                continue
+            key_str = str(key).strip()
+            if not key_str:
+                continue
+            lines.append(f"{key_str}={self._escape_ffmetadata_value(value)}")
+        
+        for chapter in chapters or []:
+            start = chapter.get("start")
+            end = chapter.get("end")
+            if start is None or end is None:
+                continue
+            try:
+                start_ms = max(0, int(round(float(start) * 1000)))
+                end_ms = int(round(float(end) * 1000))
+            except (TypeError, ValueError):
+                continue
+            if end_ms <= start_ms:
+                end_ms = start_ms + 1
+            lines.append("[CHAPTER]")
+            lines.append("TIMEBASE=1/1000")
+            lines.append(f"START={start_ms}")
+            lines.append(f"END={end_ms}")
+            title = chapter.get("title")
+            if title:
+                lines.append(f"title={self._escape_ffmetadata_value(title)}")
+            voices = chapter.get("voices")
+            if voices and isinstance(voices, list):
+                voice_str = ", ".join(
+                    f"{v.get('voice', '')}@{v.get('provider', '')}"
+                    for v in voices if v.get("voice")
+                )
+                if voice_str:
+                    lines.append(f"voice={self._escape_ffmetadata_value(voice_str)}")
+        
+        return "\n".join(lines) + "\n"
+    
+    @staticmethod
+    def _escape_ffmetadata_value(value: Any) -> str:
+        escaped = str(value).replace("\\", "\\\\").replace("\n", "\\n")
+        escaped = escaped.replace("=", "\\=").replace(";", "\\;").replace("#", "\\#")
+        return escaped
+    
+    def write_ffmetadata_file(
+        self,
+        audio_path: Path,
+        metadata: Dict[str, Any],
+        chapters: List[Dict[str, Any]],
+    ) -> Optional[Path]:
+        """Write FFMETADATA file to temp location."""
+        content = self.render_ffmetadata(metadata, chapters)
+        if content.strip() == ";FFMETADATA1":
+            return None
+        
+        directory = audio_path.parent if audio_path.parent.exists() else Path(tempfile.gettempdir())
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            suffix=".ffmeta",
+            delete=False,
+            dir=str(directory),
+        ) as handle:
+            handle.write(content)
+            return Path(handle.name)
+    
+    # ----------------------------------------------------------------------
+    # M4B Export
+    # ----------------------------------------------------------------------
+    
+    def embed_m4b_metadata(
+        self,
+        audio_path: Path,
+        metadata: Dict[str, Any],
+        chapters: List[Dict[str, Any]],
+        cover: "CoverConfig | None" = None,
+        cover_path: Optional[Path] = None,
+        cover_mime: Optional[str] = None,
+        log_callback: Optional[callable] = None,
+    ) -> None:
+        """Embed metadata and chapters into M4B file using FFmpeg + Mutagen."""
+        from abogen.domain.config_types import CoverConfig
+        if isinstance(cover, CoverConfig):
+            cover_path = cover.path
+            cover_mime = cover.mime
+        ffmetadata_path = self.write_ffmetadata_file(audio_path, metadata, chapters)
+        
+        metadata_args = self._metadata_to_ffmpeg_args(metadata)
+        
+        cmd = ["ffmpeg", "-y", "-i", str(audio_path)]
+        
+        if ffmetadata_path:
+            cmd.extend(["-f", "ffmetadata", "-i", str(ffmetadata_path)])
+        
+        if cover_path and cover_path.exists():
+            cmd.extend(["-i", str(cover_path)])
+            cmd.extend(["-map", "0:a"])
+            cmd.extend(["-map", "1:v:0", "-c:v:0", "mjpeg", "-disposition:v:0", "attached_pic"])
+            if cover_mime:
+                cmd.extend(["-metadata:s:v:0", f"mimetype={cover_mime}"])
+            cmd.extend(["-metadata:s:v:0", "title=Cover Art"])
+        else:
+            cmd.extend(["-map", "0:a"])
+        
+        cmd.extend(["-c:a", "copy"])
+        
+        if ffmetadata_path:
+            cmd.extend(["-map_metadata", "1", "-map_chapters", "1"])
+        else:
+            cmd.extend(["-map_metadata", "0"])
+        
+        if metadata_args:
+            cmd.extend(metadata_args)
+        
+        cmd.extend(["-movflags", "+faststart+use_metadata_tags"])
+        
+        temp_output = audio_path.with_suffix(audio_path.suffix + ".tmp")
+        if audio_path.suffix.lower() in {".m4b", ".mp4", ".m4a"}:
+            cmd.extend(["-f", "mp4"])
+        cmd.append(str(temp_output))
+        
+        if log_callback:
+            log_callback("Embedding metadata into M4B output")
+        
+        process = create_process(cmd, text=True)
+        return_code = process.wait()
+        
+        if ffmetadata_path and ffmetadata_path.exists():
+            try:
+                ffmetadata_path.unlink()
+            except OSError:
+                pass
+        
+        if return_code != 0:
+            if temp_output.exists():
+                temp_output.unlink(missing_ok=True)
+            raise RuntimeError(f"ffmpeg failed to embed metadata (exit code {return_code})")
+        
+        temp_output.replace(audio_path)
+        
+        if log_callback:
+            log_callback("Embedded metadata and chapters into M4B output", "info")
+        
+        # Apply chapters via Mutagen for better compatibility
+        self._apply_m4b_chapters_mutagen(audio_path, chapters, log_callback)
+    
+    @staticmethod
+    def _metadata_to_ffmpeg_args(metadata: Dict[str, Any]) -> List[str]:
+        args = []
+        for key, value in (metadata or {}).items():
+            if value in (None, ""):
+                continue
+            key_str = str(key).strip()
+            if not key_str:
+                continue
+            normalized_key = key_str.lower()
+            if normalized_key == "year":
+                ffmpeg_key = "date"
+            else:
+                ffmpeg_key = key_str
+            args.extend(["-metadata", f"{ffmpeg_key}={value}"])
+        return args
+    
+    def _apply_m4b_chapters_mutagen(
+        self,
+        audio_path: Path,
+        chapters: List[Dict[str, Any]],
+        log_callback: Optional[callable] = None,
+    ) -> bool:
+        """Apply chapter atoms using Mutagen."""
+        if not chapters:
+            return False
+        
+        try:
+            from fractions import Fraction
+            from mutagen.mp4 import MP4, MP4Chapter
+        except ImportError:
+            if log_callback:
+                log_callback("Unable to write MP4 chapter atoms because mutagen is not installed.", "warning")
+            return False
+        
+        try:
+            mp4 = MP4(str(audio_path))
+        except Exception as exc:
+            if log_callback:
+                log_callback(f"Failed to open m4b for chapter embedding: {exc}", "warning")
+            return False
+        
+        chapter_objects = []
+        for index, entry in enumerate(sorted(chapters, key=lambda item: float(item.get("start") or 0.0))):
+            start_raw = entry.get("start")
+            if start_raw is None:
+                continue
+            try:
+                start_seconds = max(0.0, float(start_raw))
+            except (TypeError, ValueError):
+                continue
+            
+            title_value = entry.get("title")
+            title_text = str(title_value) if title_value else f"Chapter {index + 1}"
+            
+            start_fraction = Fraction(int(round(start_seconds * 1000)), 1000)
+            chapter_atom = MP4Chapter(start_fraction, title_text)
+            
+            end_raw = entry.get("end")
+            if end_raw is not None:
+                try:
+                    end_seconds = float(end_raw)
+                except (TypeError, ValueError):
+                    end_seconds = None
+                if end_seconds is not None and end_seconds > start_seconds:
+                    chapter_atom.end = Fraction(int(round(end_seconds * 1000)), 1000)
+            
+            chapter_objects.append(chapter_atom)
+        
+        if not chapter_objects:
+            return False
+        
+        try:
+            mp4.chapters = chapter_objects
+            mp4.save()
+        except Exception as exc:
+            if log_callback:
+                log_callback(f"Failed to persist MP4 chapter atoms: {exc}", "warning")
+            return False
+        
+        if log_callback:
+            log_callback(f"Applied {len(chapter_objects)} chapter markers via mutagen", "info")
+        return True
+    
+    # ----------------------------------------------------------------------
+    # EPUB3 Export
+    # ----------------------------------------------------------------------
+    
+    def export_epub3(
+        self,
+        output_path: Path,
+        book_id: str,
+        extraction: Any,  # ExtractionResult
+        metadata_tags: Dict[str, Any],
+        chapter_markers: Sequence[Dict[str, Any]],
+        chunk_markers: Sequence[Dict[str, Any]],
+        chunks: Iterable[Dict[str, Any]],
+        audio_path: Path,
+        speaker_mode: str = "single",
+        cover_path: Optional[Path] = None,
+        cover_mime: Optional[str] = None,
+    ) -> Path:
+        """Export EPUB3 with media overlays."""
+        return build_epub3_package(
+            output_path=output_path,
+            book_id=book_id,
+            extraction=extraction,
+            metadata_tags=metadata_tags,
+            chapter_markers=chapter_markers,
+            chunk_markers=chunk_markers,
+            chunks=chunks,
+            audio_path=audio_path,
+            speaker_mode=speaker_mode,
+            cover_image_path=cover_path,
+            cover_image_mime=cover_mime,
+        )
+    
+
+        if value is None:
+            return default
+        return bool(value)
+
+
+__all__ = [
+    "ExportConfig",
+    "ExportService",
+]

abogen/infrastructure/subtitle_writer.py

@@ -0,0 +1,389 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import List, Optional, TextIO
+
+from abogen.domain.enums import SubtitleFormat, SubtitleMode
+from abogen.subtitle_utils import clean_subtitle_text
+
+
+class SubtitleAlignment(Enum):
+    LEFT = "left"
+    CENTER = "center"
+    NARROW = "narrow"
+    CENTER_NARROW = "center_narrow"
+
+
+@dataclass
+class SubtitleConfig:
+    """Configuration for subtitle writer."""
+    format: SubtitleFormat
+    mode: SubtitleMode
+    alignment: SubtitleAlignment = SubtitleAlignment.LEFT
+    max_words: int = 50
+    highlight_color: str = "&H00FFFF00"  # ASS highlight color
+
+
+class SubtitleWriter(ABC):
+    """Abstract base class for subtitle writers."""
+    
+    def __init__(self, path: Path, config: SubtitleConfig):
+        self.path = path
+        self.config = config
+        self._file: Optional[TextIO] = None
+        self._index = 0
+        self._opened = False
+    
+    def open(self) -> None:
+        """Open the subtitle file and write header."""
+        if self._opened:
+            return
+        self._file = open(self.path, "w", encoding="utf-8", errors="replace")
+        self._write_header()
+        self._opened = True
+    
+    @abstractmethod
+    def _write_header(self) -> None:
+        pass
+    
+    def write_entry(
+        self,
+        start: float,
+        end: float,
+        text: str,
+        voice: Optional[str] = None,
+    ) -> None:
+        """Write a subtitle entry."""
+        if not self._opened:
+            self.open()
+        
+        text = clean_subtitle_text(text)
+        if not text:
+            return
+        
+        self._index += 1
+        self._write_entry(self._index, start, end, text, voice)
+    
+    @abstractmethod
+    def _write_entry(
+        self,
+        index: int,
+        start: float,
+        end: float,
+        text: str,
+        voice: Optional[str],
+    ) -> None:
+        pass
+    
+    def close(self) -> None:
+        """Close the subtitle file."""
+        if self._file:
+            self._file.close()
+            self._file = None
+            self._opened = False
+    
+    def __enter__(self) -> "SubtitleWriter":
+        self.open()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+
+class SrtWriter(SubtitleWriter):
+    """SRT subtitle writer."""
+    
+    def _write_header(self) -> None:
+        pass  # SRT has no header
+    
+    def _write_entry(
+        self,
+        index: int,
+        start: float,
+        end: float,
+        text: str,
+        voice: Optional[str],
+    ) -> None:
+        start_str = self._format_time(start)
+        end_str = self._format_time(end)
+        
+        if voice:
+            text = f"[{voice}] {text}"
+        
+        self._file.write(f"{index}\n")
+        self._file.write(f"{start_str} --> {end_str}\n")
+        self._file.write(f"{text}\n\n")
+    
+    @staticmethod
+    def _format_time(seconds: float) -> str:
+        hours = int(seconds // 3600)
+        minutes = int((seconds % 3600) // 60)
+        secs = int(seconds % 60)
+        millis = int((seconds - int(seconds)) * 1000)
+        return f"{hours:02d}:{minutes:02d}:{secs:02d},{millis:03d}"
+
+
+class VttWriter(SubtitleWriter):
+    """WebVTT subtitle writer."""
+    
+    def _write_header(self) -> None:
+        self._file.write("WEBVTT\n\n")
+    
+    def _write_entry(
+        self,
+        index: int,
+        start: float,
+        end: float,
+        text: str,
+        voice: Optional[str],
+    ) -> None:
+        start_str = self._format_time(start)
+        end_str = self._format_time(end)
+        
+        if voice:
+            text = f"[{voice}] {text}"
+        
+        self._file.write(f"{index}\n")
+        self._file.write(f"{start_str} --> {end_str}\n")
+        self._file.write(f"{text}\n\n")
+    
+    @staticmethod
+    def _format_time(seconds: float) -> str:
+        hours = int(seconds // 3600)
+        minutes = int((seconds % 3600) // 60)
+        secs = seconds % 60
+        return f"{hours:02d}:{minutes:02d}:{secs:06.3f}".replace(".", ".")
+
+
+class AssWriter(SubtitleWriter):
+    """ASS subtitle writer with karaoke highlighting support."""
+    
+    def __init__(self, path: Path, config: SubtitleConfig):
+        super().__init__(path, config)
+        self._is_centered = config.alignment in (SubtitleAlignment.CENTER, SubtitleAlignment.CENTER_NARROW)
+        self._is_narrow = config.alignment in (SubtitleAlignment.NARROW, SubtitleAlignment.CENTER_NARROW)
+    
+    def _write_header(self) -> None:
+        margin = "90" if self._is_narrow else "10"
+        alignment = "5" if self._is_centered else "2"
+        
+        self._file.write("[Script Info]\n")
+        self._file.write("Title: Generated by Abogen\n")
+        self._file.write("ScriptType: v4.00+\n\n")
+        
+        # Styles
+        self._file.write("[V4+ Styles]\n")
+        self._file.write(
+            "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, "
+            "OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, "
+            "ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, "
+            "Alignment, MarginL, MarginR, MarginV, Encoding\n"
+        )
+        
+        if self.config.mode == SubtitleMode.SENTENCE_HIGHLIGHT:
+            # Karaoke style with highlighting
+            self._file.write(
+                f"Style: Default,Arial,24,&H00FFFFFF,&H00808080,&H00000000,&H00404040,"
+                f"0,0,0,0,100,100,0,0,3,2,0,{alignment},{margin},{margin},10,1\n"
+            )
+            self._file.write(
+                f"Style: Highlight,Arial,24,&H0000FFFF,&H00808080,&H00000000,&H00404040,"
+                f"0,0,0,0,100,100,0,0,3,2,0,{alignment},{margin},{margin},10,1\n\n"
+            )
+        else:
+            self._file.write(
+                f"Style: Default,Arial,24,&H00FFFFFF,&H00808080,&H00000000,&H00404040,"
+                f"0,0,0,0,100,100,0,0,3,2,0,{alignment},{margin},{margin},10,1\n\n"
+            )
+        
+        self._file.write("[Events]\n")
+        self._file.write(
+            "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\n"
+        )
+    
+    def _write_entry(
+        self,
+        index: int,
+        start: float,
+        end: float,
+        text: str,
+        voice: Optional[str],
+    ) -> None:
+        start_str = self._format_time(start)
+        end_str = self._format_time(end)
+        
+        if voice:
+            text = f"[{voice}] {text}"
+        
+        style = "Default"
+        if self.config.mode == SubtitleMode.SENTENCE_HIGHLIGHT:
+            # Entries from process_subtitle_tokens already carry per-word
+            # {\kf...} timing; only synthesize simplified tags when absent.
+            if "{\\k" not in text:
+                text = self._add_karaoke_tags(text)
+            style = "Highlight"
+        
+        alignment_tag = r"{\an5}" if self._is_centered else ""
+        self._file.write(
+            f"Dialogue: 0,{start_str},{end_str},{style},,0,0,0,,{alignment_tag}{text}\n"
+        )
+    
+    def _add_karaoke_tags(self, text: str) -> str:
+        """Add karaoke highlighting tags to text."""
+        # Simple word-level karaoke timing
+        words = text.split()
+        if not words:
+            return text
+        
+        # This is a simplified version - real karaoke needs per-word timing
+        # For now, just return the text with the highlight color
+        return r"{\k100}" + r"{\k100}".join(words) + r"{\k0}"
+    
+    @staticmethod
+    def _format_time(seconds: float) -> str:
+        hours = int(seconds // 3600)
+        minutes = int((seconds % 3600) // 60)
+        secs = seconds % 60
+        return f"{hours}:{minutes:02d}:{secs:05.2f}"
+
+
+def _coerce_mode(mode: str) -> SubtitleMode:
+    """Parse a subtitle mode, tolerating word-count strings like "5 words".
+
+    Word-count modes are grouped upstream (subtitle_generation) and the writer
+    only branches on SubtitleMode.SENTENCE_HIGHLIGHT, so any non-highlight
+    fallback is behaviorally equivalent for the writers.
+    """
+    try:
+        return SubtitleMode(mode)
+    except ValueError:
+        return SubtitleMode.SENTENCE
+
+
+def create_subtitle_writer(
+    path: Path,
+    format: str,
+    mode: str,
+    alignment: str = "left",
+    max_words: int = 50,
+) -> SubtitleWriter:
+    """Factory function to create subtitle writer."""
+    fmt = SubtitleFormat(format.lower())
+    mode = _coerce_mode(mode)
+    align = SubtitleAlignment(alignment.lower())
+
+    config = SubtitleConfig(
+        format=fmt,
+        mode=mode,
+        alignment=align,
+        max_words=max_words,
+    )
+
+    if fmt == SubtitleFormat.SRT:
+        return SrtWriter(path, config)
+    elif fmt == SubtitleFormat.VTT:
+        return VttWriter(path, config)
+    elif fmt == SubtitleFormat.ASS:
+        return AssWriter(path, config)
+    else:
+        raise ValueError(f"Unsupported subtitle format: {format}")
+
+
+def resolve_subtitle_format(
+    subtitle: "SubtitleConfig | str | None",
+    subtitle_mode: str | None = None,
+) -> tuple[str, str]:
+    """Resolve a subtitle config to (file_extension, alignment).
+
+    Accepts a SubtitleConfig object or individual format/mode strings
+    for backward compatibility.
+
+    Returns:
+        Tuple of (file_extension, alignment) suitable for
+        :func:`create_subtitle_writer`.
+    """
+    from abogen.domain.config_types import SubtitleConfig
+
+    if isinstance(subtitle, SubtitleConfig):
+        fmt = subtitle.format.value.lower()
+        mode_str = subtitle.mode.value
+    else:
+        fmt = (subtitle or "srt").lower()
+        mode_str = subtitle_mode or "Disabled"
+
+    if mode_str == "Sentence + Highlighting" and fmt == "srt":
+        fmt = "ass"
+
+    if "ass" in fmt:
+        extension = "ass"
+        if "centered_narrow" in fmt:
+            alignment = "center_narrow"
+        elif "centered" in fmt:
+            alignment = "center"
+        elif "narrow" in fmt:
+            alignment = "narrow"
+        else:
+            alignment = "left"
+    else:
+        extension = fmt if fmt in ("srt", "vtt") else "srt"
+        alignment = "left"
+
+    return extension, alignment
+
+
+def make_subtitle_writer(
+    audio_path: Path,
+    subtitle: "SubtitleConfig | str | None",
+    subtitle_mode: str | None = None,
+    max_words: int | None = None,
+) -> SubtitleWriter | None:
+    """Convenience: resolve format and create a writer, or return None if disabled.
+
+    Accepts a SubtitleConfig object or individual format/mode strings
+    for backward compatibility.
+
+    Returns ``None`` when subtitle mode is ``"Disabled"`` or the
+    format is unsupported.
+    """
+    from abogen.domain.config_types import SubtitleConfig
+
+    if isinstance(subtitle, SubtitleConfig):
+        mode_str = subtitle.mode.value
+        if mode_str == "Disabled":
+            return None
+        words = subtitle.max_words
+    else:
+        mode_str = subtitle_mode or subtitle or "Disabled"
+        if mode_str == "Disabled":
+            return None
+        words = max_words or 50
+
+    extension, alignment = resolve_subtitle_format(subtitle, subtitle_mode)
+    try:
+        return create_subtitle_writer(
+            audio_path.with_suffix(f".{extension}"),
+            extension,
+            mode_str,
+            alignment=alignment,
+            max_words=words,
+        )
+    except (ValueError, KeyError):
+        return None
+
+
+__all__ = [
+    "SubtitleFormat",
+    "SubtitleMode",
+    "SubtitleAlignment",
+    "SubtitleConfig",
+    "SubtitleWriter",
+    "SrtWriter",
+    "VttWriter",
+    "AssWriter",
+    "create_subtitle_writer",
+    "resolve_subtitle_format",
+    "make_subtitle_writer",
+]

abogen/integrations/audiobookshelf.py

@@ -2,9 +2,7 @@ from __future__ import annotations
 
 import json
 import logging
-import math
 import mimetypes
-import re
 from contextlib import ExitStack
 from dataclasses import dataclass
 from pathlib import Path
@@ -12,6 +10,8 @@ from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
 
 import httpx
 
+from abogen.domain.metadata_helpers import normalize_series_sequence
+
 logger = logging.getLogger(__name__)
 
 
@@ -641,40 +641,7 @@ class AudiobookshelfClient:
         for key in preferred_keys:
             if key not in metadata:
                 continue
-            normalized = AudiobookshelfClient._normalize_series_sequence(metadata.get(key))
+            normalized = normalize_series_sequence(metadata.get(key))
             if normalized:
                 return normalized
         return ""
-
-    @staticmethod
-    def _normalize_series_sequence(raw: Any) -> str:
-        if raw is None:
-            return ""
-
-        if isinstance(raw, (int, float)):
-            if isinstance(raw, float) and (math.isnan(raw) or math.isinf(raw)):
-                return ""
-            text = str(raw)
-        else:
-            text = str(raw).strip()
-
-        if not text:
-            return ""
-
-        candidate = text.replace(",", ".")
-        match = re.search(r"\d+(?:\.\d+)?", candidate)
-        if not match:
-            return ""
-
-        normalized = match.group(0)
-        if "." in normalized:
-            normalized = normalized.rstrip("0").rstrip(".")
-            if not normalized:
-                normalized = "0"
-            return normalized
-
-        try:
-            return str(int(normalized))
-        except ValueError:
-            cleaned = normalized.lstrip("0")
-            return cleaned or "0"

abogen/main.py

@@ -2,13 +2,14 @@
 
 from __future__ import annotations
 
-import atexit
 import os
 import platform
-import signal
-import sys
 
-from abogen.utils import load_config, prevent_sleep_end
+# Initialise global shutdown handling (atexit, signals, Qt) as early as possible.
+from abogen import shutdown  # noqa: F401
+shutdown.register_shutdown()
+
+from abogen.utils import load_config
 from abogen.webui.app import main as _run_web_ui
 
 # Configure Hugging Face Hub behaviour (mirrors legacy GUI defaults).
@@ -27,17 +28,6 @@ os.environ.setdefault("MIOPEN_CONV_PRECISE_ROCM_TUNING", "0")
 if platform.system() == "Darwin" and platform.processor() == "arm":
     os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")
 
-atexit.register(prevent_sleep_end)
-
-
-def _cleanup_sleep(signum, _frame):
-    prevent_sleep_end()
-    sys.exit(0)
-
-
-signal.signal(signal.SIGINT, _cleanup_sleep)
-signal.signal(signal.SIGTERM, _cleanup_sleep)
-
 
 def main() -> None:
     """Launch the Flask-based web UI."""

abogen/predownload_gui.py

@@ -21,7 +21,8 @@ from PyQt6.QtWidgets import (
 )
 from PyQt6.QtCore import QThread, pyqtSignal
 
-from abogen.constants import COLORS, VOICES_INTERNAL
+from abogen.constants import COLORS
+from abogen.tts_plugin.utils import get_voices
 from abogen.spacy_utils import SPACY_MODELS
 import abogen.hf_tracker
 
@@ -114,7 +115,7 @@ class PreDownloadWorker(QThread):
             self._voices_success = False
             return
 
-        voice_list = VOICES_INTERNAL
+        voice_list = get_voices("kokoro")
         for idx, voice in enumerate(voice_list, start=1):
             if self._cancelled:
                 self._voices_success = False
@@ -462,14 +463,14 @@ class PreDownloadDialog(QDialog):
         try:
             from huggingface_hub import try_to_load_from_cache
 
-            for voice in VOICES_INTERNAL:
+            for voice in get_voices("kokoro"):
                 if not try_to_load_from_cache(
                     repo_id="hexgrad/Kokoro-82M", filename=f"voices/{voice}.pt"
                 ):
                     missing.append(voice)
         except Exception:
             # If HF missing, report all as missing
-            return False, list(VOICES_INTERNAL)
+            return False, list(get_voices("kokoro"))
         return (len(missing) == 0), missing
 
     def _check_kokoro_model(self) -> bool:

abogen/pyqt/book_handler.py

@@ -29,21 +29,25 @@ from abogen.utils import (
     get_resource_path,
 )
 from abogen.book_parser import get_book_parser
-
-from abogen.subtitle_utils import (
-    clean_text,
-    calculate_text_length,
+from abogen.domain.metadata_extraction import (
+    extract_book_metadata_epub,
+    extract_book_metadata_pdf,
+    extract_book_metadata_markdown,
+    format_metadata_tags,
 )
 
+from abogen.subtitle_utils import clean_text
+from abogen.domain.text_utils import calculate_text_length
+
 import os
 import logging
 import urllib.parse
 import textwrap
 
 # Setup logging
-logging.basicConfig(
-    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
-)
+from abogen.utils import setup_console_logging
+
+setup_console_logging()
 
 _HTML_TAG_PATTERN = re.compile(r"<[^>]+>")
 _LEADING_DASH_PATTERN = re.compile(r"^\s*[-–—]\s*")
@@ -948,169 +952,14 @@ class HandlerDialog(QDialog):
         self.previewEdit.setHtml(html_content)
 
     def _extract_book_metadata(self):
-        metadata = {
-            "title": None,
-            "authors": [],
-            "description": None,
-            "cover_image": None,
-            "publisher": None,
-            "publication_year": None,
-        }
-
         if self.parser.file_type == "epub":
-            try:
-                title_items = self.book.get_metadata("DC", "title")
-                if title_items and len(title_items) > 0:
-                    metadata["title"] = title_items[0][0]
-            except Exception as e:
-                logging.warning(f"Error extracting title metadata: {e}")
-
-            try:
-                author_items = self.book.get_metadata("DC", "creator")
-                if author_items:
-                    metadata["authors"] = [
-                        author[0] for author in author_items if len(author) > 0
-                    ]
-            except Exception as e:
-                logging.warning(f"Error extracting author metadata: {e}")
-
-            try:
-                desc_items = self.book.get_metadata("DC", "description")
-                if desc_items and len(desc_items) > 0:
-                    metadata["description"] = desc_items[0][0]
-            except Exception as e:
-                logging.warning(f"Error extracting description metadata: {e}")
-
-            try:
-                publisher_items = self.book.get_metadata("DC", "publisher")
-                if publisher_items and len(publisher_items) > 0:
-                    metadata["publisher"] = publisher_items[0][0]
-            except Exception as e:
-                logging.warning(f"Error extracting publisher metadata: {e}")
-
-            # Try to extract publication year
-            try:
-                date_items = self.book.get_metadata("DC", "date")
-                if date_items and len(date_items) > 0:
-                    date_str = date_items[0][0]
-                    # Try to extract just the year from the date string
-                    year_match = re.search(r"\b(19|20)\d{2}\b", date_str)
-                    if year_match:
-                        metadata["publication_year"] = year_match.group(0)
-                    else:
-                        metadata["publication_year"] = date_str
-            except Exception as e:
-                logging.warning(f"Error extracting publication date metadata: {e}")
-
-            for item in self.book.get_items_of_type(ebooklib.ITEM_COVER):
-                metadata["cover_image"] = item.get_content()
-                break
-
-            if not metadata["cover_image"]:
-                for item in self.book.get_items_of_type(ebooklib.ITEM_IMAGE):
-                    if "cover" in item.get_name().lower():
-                        metadata["cover_image"] = item.get_content()
-                        break
+            return extract_book_metadata_epub(self.book)
         elif self.parser.file_type == "markdown":
-            # Extract metadata from markdown frontmatter or first heading
-            if self.markdown_text:
-                # Try to extract YAML frontmatter
-                frontmatter_match = re.match(
-                    r"^---\s*\n(.*?)\n---\s*\n", self.markdown_text, re.DOTALL
-                )
-                if frontmatter_match:
-                    try:
-                        frontmatter = frontmatter_match.group(1)
-                        # Simple YAML-like parsing for common fields
-                        title_match = re.search(
-                            r"^title:\s*(.+)$",
-                            frontmatter,
-                            re.MULTILINE | re.IGNORECASE,
-                        )
-                        if title_match:
-                            metadata["title"] = (
-                                title_match.group(1).strip().strip("\"'")
-                            )
-
-                        author_match = re.search(
-                            r"^author:\s*(.+)$",
-                            frontmatter,
-                            re.MULTILINE | re.IGNORECASE,
-                        )
-                        if author_match:
-                            metadata["authors"] = [
-                                author_match.group(1).strip().strip("\"'")
-                            ]
-
-                        desc_match = re.search(
-                            r"^description:\s*(.+)$",
-                            frontmatter,
-                            re.MULTILINE | re.IGNORECASE,
-                        )
-                        if desc_match:
-                            metadata["description"] = (
-                                desc_match.group(1).strip().strip("\"'")
-                            )
-
-                        date_match = re.search(
-                            r"^date:\s*(.+)$", frontmatter, re.MULTILINE | re.IGNORECASE
-                        )
-                        if date_match:
-                            date_str = date_match.group(1).strip().strip("\"'")
-                            year_match = re.search(r"\b(19|20)\d{2}\b", date_str)
-                            if year_match:
-                                metadata["publication_year"] = year_match.group(0)
-                    except Exception as e:
-                        logging.warning(f"Error parsing markdown frontmatter: {e}")
-
-                # Fallback: use first H1 header as title if no frontmatter title
-                if not metadata["title"] and self.markdown_toc:
-                    # Find the first level 1 header
-                    first_h1 = next(
-                        (h for h in self.markdown_toc if h["level"] == 1), None
-                    )
-                    if first_h1:
-                        metadata["title"] = first_h1["name"]
+            return extract_book_metadata_markdown(
+                self.markdown_text, self.markdown_toc
+            )
         else:
-            pdf_info = self.pdf_doc.metadata
-            if pdf_info:
-                metadata["title"] = pdf_info.get("title", None)
-
-                author = pdf_info.get("author", None)
-                if author:
-                    metadata["authors"] = [author]
-
-                metadata["description"] = pdf_info.get("subject", None)
-
-                keywords = pdf_info.get("keywords", None)
-                if keywords:
-                    if metadata["description"]:
-                        metadata["description"] += f"\n\nKeywords: {keywords}"
-                    else:
-                        metadata["description"] = f"Keywords: {keywords}"
-
-                metadata["publisher"] = pdf_info.get("creator", None)
-
-                # Try to extract publication date from PDF metadata
-                if "creationDate" in pdf_info:
-                    date_str = pdf_info["creationDate"]
-                    year_match = re.search(r"D:(\d{4})", date_str)
-                    if year_match:
-                        metadata["publication_year"] = year_match.group(1)
-                elif "modDate" in pdf_info:
-                    date_str = pdf_info["modDate"]
-                    year_match = re.search(r"D:(\d{4})", date_str)
-                    if year_match:
-                        metadata["publication_year"] = year_match.group(1)
-
-            if len(self.pdf_doc) > 0:
-                try:
-                    pix = self.pdf_doc[0].get_pixmap(matrix=fitz.Matrix(2, 2))
-                    metadata["cover_image"] = pix.tobytes("png")
-                except Exception:
-                    pass
-
-        return metadata
+            return extract_book_metadata_pdf(self.pdf_doc)
 
     def get_selected_text(self):
         # If a background loader thread is running, wait for it to finish to
@@ -1136,59 +985,21 @@ class HandlerDialog(QDialog):
 
     def _format_metadata_tags(self):
         """Format metadata tags for insertion at the beginning of the text"""
-        import datetime
         from abogen.utils import get_user_cache_path
 
-        metadata = self.book_metadata
         filename = os.path.splitext(os.path.basename(self.book_path))[0]
-        current_year = str(datetime.datetime.now().year)
+        chapter_count = len(self.checked_chapters)
+        cache_dir = get_user_cache_path()
 
-        # Get values with fallbacks
-        title = metadata.get("title") or filename
-        authors = metadata.get("authors") or ["Unknown"]
-        authors_text = ", ".join(authors)
-        album_artist = authors_text or "Unknown"
-        year = (
-            metadata.get("publication_year") or current_year
-        )  # Use publication year if available
-
-        # Count chapters/pages
-        total_chapters = len(self.checked_chapters)
-        chapter_text = (
-            f"{total_chapters} {'Chapters' if self.parser.file_type == 'epub' else 'Pages'}"
+        return format_metadata_tags(
+            self.book_metadata,
+            filename,
+            chapter_count,
+            self.parser.file_type,
+            cover_bytes=self.book_metadata.get("cover_image"),
+            cache_dir=cache_dir,
         )
 
-        # Handle cover image
-        cover_tag = ""
-        if metadata.get("cover_image"):
-            try:
-                import uuid
-
-                cache_dir = get_user_cache_path()
-                cover_path = os.path.join(cache_dir, f"cover_{uuid.uuid4()}.jpg")
-                cover_path = os.path.normpath(cover_path)
-                with open(cover_path, "wb") as f:
-                    f.write(metadata["cover_image"])
-                cover_tag = f"<<METADATA_COVER_PATH:{cover_path}>>"
-            except Exception as e:
-                logging.warning(f"Failed to save cover image: {e}")
-
-        # Format metadata tags
-        metadata_tags = [
-            f"<<METADATA_TITLE:{title}>>",
-            f"<<METADATA_ARTIST:{authors_text}>>",
-            f"<<METADATA_ALBUM:{title} ({chapter_text})>>",
-            f"<<METADATA_YEAR:{year}>>",
-            f"<<METADATA_ALBUM_ARTIST:{album_artist}>>",
-            f"<<METADATA_COMPOSER:Narrator>>",
-            f"<<METADATA_GENRE:Audiobook>>",
-        ]
-
-        if cover_tag:
-            metadata_tags.append(cover_tag)
-
-        return "\n".join(metadata_tags)
-
     def _get_markdown_selected_text(self):
         """Get selected text from markdown chapters"""
         all_checked_identifiers = set()

abogen/pyqt/conversion_adapter.py

@@ -0,0 +1,209 @@
+"""PyQt adapter: ConversionThread -> ConversionRequest.
+
+Converts a PyQt ConversionThread into a ConversionRequest that the application layer can process.
+This adapter is the bridge between the PyQt layer and the application/domain layer.
+
+The adapter is responsible for:
+- Mapping ConversionThread fields to ConversionRequest fields
+- Handling UI-specific state (signals, dialogs, cancellation)
+- Providing PipelineProvider and VoiceResolver implementations
+
+Subtitle file/timestamp special paths remain in ConversionThread.run() early return.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from abogen.application.conversion_config import (
+    ChapterChunkConfig,
+    Epub3ExportConfig,
+    PronunciationConfig,
+    WordSubstitutionConfig,
+)
+from abogen.application.conversion_request import ConversionRequest
+from abogen.application.conversion_ports import ConversionCancelled, ResolvedVoice
+
+
+def build_conversion_request_from_thread(thread: Any) -> ConversionRequest:
+    """Convert a PyQt ConversionThread into a ConversionRequest.
+
+    This is the primary function that maps thread fields to ConversionRequest.
+    All fields are copied — the request is independent of the thread.
+
+    Args:
+        thread: PyQt ConversionThread instance
+
+    Returns:
+        ConversionRequest with all thread data mapped
+    """
+    # Determine source path
+    source_path = None
+    is_direct_text = getattr(thread, "is_direct_text", False)
+    if not is_direct_text and thread.file_name:
+        source_path = Path(thread.file_name)
+
+    # Determine original filename
+    original_filename = ""
+    if getattr(thread, "from_queue", False):
+        base_path = getattr(thread, "save_base_path", None) or thread.file_name
+    else:
+        base_path = getattr(thread, "display_path", None) or thread.file_name
+
+    if base_path:
+        original_filename = os.path.basename(base_path)
+
+    # Determine output folder
+    output_folder = None
+    if thread.output_folder:
+        output_folder = Path(thread.output_folder)
+
+    # Build pronunciation config
+    pronunciation = None
+    pron_overrides = getattr(thread, "pronunciation_overrides", []) or []
+    manual_overrides = getattr(thread, "manual_overrides", []) or []
+    heteronym_overrides = getattr(thread, "heteronym_overrides", []) or []
+    norm_overrides = getattr(thread, "normalization_overrides", None)
+    if pron_overrides or manual_overrides or heteronym_overrides or norm_overrides:
+        pronunciation = PronunciationConfig(
+            pronunciation_overrides=pron_overrides,
+            manual_overrides=manual_overrides,
+            heteronym_overrides=heteronym_overrides,
+            normalization_overrides=norm_overrides,
+        )
+
+    # Build epub3 config
+    epub3_export = None
+    if getattr(thread, "generate_epub3", False):
+        epub3_export = Epub3ExportConfig()
+
+    return ConversionRequest(
+        # Source
+        source_path=source_path,
+        direct_text=thread.file_name if is_direct_text else None,
+        original_filename=original_filename,
+        # TTS Settings
+        language=thread.lang_code,
+        tts_provider="kokoro",  # PyQt uses Kokoro by default
+        voice=thread.voice,
+        voice_profile=getattr(thread, "voice_profile", None),
+        speed=thread.speed,
+        use_gpu=thread.use_gpu,
+        supertonic_total_steps=getattr(thread, "supertonic_total_steps", 5),
+        # Output Format
+        output_format=thread.output_format,
+        subtitle_mode=thread.subtitle_mode,
+        subtitle_format=getattr(thread, "subtitle_format", "srt"),
+        max_subtitle_words=getattr(thread, "max_subtitle_words", 50),
+        # Save Options
+        save_mode=thread.save_option,
+        output_folder=output_folder,
+        save_chapters_separately=getattr(thread, "save_chapters_separately", False),
+        merge_chapters_at_end=getattr(thread, "merge_chapters_at_end", True),
+        separate_chapters_format=getattr(thread, "separate_chapters_format", "wav"),
+        save_as_project=getattr(thread, "save_as_project", False),
+        # Timing
+        silence_between_chapters=getattr(thread, "silence_duration", 2.0),
+        chapter_intro_delay=getattr(thread, "chapter_intro_delay", 0.0),
+        # Content Processing
+        replace_single_newlines=getattr(thread, "replace_single_newlines", False),
+        read_title_intro=getattr(thread, "read_title_intro", False),
+        read_closing_outro=getattr(thread, "read_closing_outro", True),
+        auto_prefix_chapter_titles=getattr(thread, "auto_prefix_chapter_titles", True),
+        normalize_chapter_opening_caps=thread.normalize_chapter_opening_caps,
+        # Metadata
+        metadata_tags=getattr(thread, "metadata_tags", {}) or {},
+        # Artifacts
+        cover_image_path=getattr(thread, "cover_image_path", None),
+        cover_image_mime=getattr(thread, "cover_image_mime", None),
+        # Feature configs
+        pronunciation=pronunciation,
+        epub3_export=epub3_export,
+        chapter_chunk=ChapterChunkConfig(),  # PyQt doesn't use chapter overrides from GUI
+    )
+
+
+class PyQtEvents:
+    """PyQt implementation of ConversionEvents protocol.
+
+    Wraps a ConversionThread to provide logging, progress, and cancellation.
+    """
+
+    def __init__(self, thread: Any):
+        self._thread = thread
+
+    def log(self, message: str, level: str = "info") -> None:
+        """Log a message via signal."""
+        self._thread.log_updated.emit((message, _level_to_color(level)))
+
+    def progress(self, pct: int, etr: str) -> None:
+        """Update progress via signal."""
+        self._thread.progress_updated.emit(pct, etr)
+
+    def check_cancelled(self) -> None:
+        """Check if conversion was cancelled.
+
+        Raises:
+            ConversionCancelled: If cancellation was requested
+        """
+        if self._thread.cancel_requested:
+            raise ConversionCancelled("Conversion cancelled by user")
+
+
+class PyQtPipelineProvider:
+    """PyQt implementation of PipelineProvider protocol.
+
+    Wraps the existing backend from ConversionThread.
+    """
+
+    def __init__(self, backend: Any):
+        self._backend = backend
+
+    def get(self, provider: str, language: str, use_gpu: bool) -> Any:
+        """Get a TTS backend instance.
+
+        For PyQt, this returns the pre-initialized backend.
+        """
+        return self._backend
+
+    def dispose_all(self) -> None:
+        """Dispose all backend resources."""
+        pass  # PyQt manages backend lifecycle in thread
+
+
+class PyQtVoiceResolver:
+    """PyQt implementation of VoiceResolver protocol.
+
+    Wraps load_voice_cached from the ConversionThread.
+    """
+
+    def __init__(self, thread: Any):
+        self._thread = thread
+
+    def resolve(self, voice_spec: str) -> ResolvedVoice:
+        """Resolve a voice spec into a loaded voice."""
+        from abogen.domain.voice_resolution import resolve_fallback_voice_spec
+
+        # Use thread's load_voice_cached method
+        loaded_voice = self._thread.load_voice_cached(voice_spec, self._thread.backend)
+
+        return ResolvedVoice(
+            provider="kokoro",
+            resolved_spec=voice_spec,
+            voice=loaded_voice,
+            speed=self._thread.speed,
+            supertonic_steps=getattr(self._thread, "supertonic_total_steps", 5),
+        )
+
+
+def _level_to_color(level: str) -> str:
+    """Map log level to PyQt color string."""
+    colors = {
+        "info": "grey",
+        "warning": "orange",
+        "error": "red",
+        "debug": "grey",
+    }
+    return colors.get(level, "grey")

abogen/pyqt/gui.py

@@ -5,8 +5,12 @@ import tempfile
 import platform
 import base64
 import re
+import logging
 from abogen.pyqt.queue_manager_gui import QueueManager
 from abogen.pyqt.queued_item import QueuedItem
+
+_log = logging.getLogger("abogen.gui")
+
 import abogen.hf_tracker as hf_tracker
 import hashlib  # Added for cache path generation
 from PyQt6.QtWidgets import (
@@ -69,27 +73,31 @@ from abogen.utils import (
     LoadPipelineThread,
 )
 
-from abogen.subtitle_utils import (
-    clean_text,
-    calculate_text_length,
-)
+from abogen.subtitle_utils import clean_text
+from abogen.domain.text_utils import calculate_text_length
 
 from abogen.pyqt.conversion import ConversionThread, VoicePreviewThread, PlayAudioThread, ChapterOptionsDialog, TimestampDetectionDialog
 from abogen.pyqt.book_handler import HandlerDialog
+from abogen.domain.enums import Language
 from abogen.constants import (
     PROGRAM_NAME,
     VERSION,
     GITHUB_URL,
     PROGRAM_DESCRIPTION,
     LANGUAGE_DESCRIPTIONS,
-    VOICES_INTERNAL,
     SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION,
     COLORS,
     SUBTITLE_FORMATS,
 )
+from abogen.tts_plugin.utils import get_voices
 import threading
 from abogen.pyqt.voice_formula_gui import VoiceFormulaDialog
-from abogen.voice_profiles import load_profiles
+from abogen.voice_profiles import load_profiles, resolve_profile_language
+from abogen.domain.settings_core import all_settings_defaults
+from plugins.kokoro.engine import language_for_code, language_for_voice_id
+
+# Module-level default cache for use outside __init__
+_DEFAULTS = all_settings_defaults()
 
 # Import ctypes for Windows-specific taskbar icon
 if platform.system() == "Windows":
@@ -394,11 +402,7 @@ class InputBox(QLabel):
         # Re-enable subtitle and replace newlines controls when cleared
         window = self.window()
         if hasattr(window, "subtitle_combo"):
-            # Only enable if language supports it
-            current_lang = getattr(window, "selected_lang", "a")
-            window.subtitle_combo.setEnabled(
-                current_lang in SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION
-            )
+            window.subtitle_combo.setEnabled(True)
         if hasattr(window, "replace_newlines_combo"):
             window.replace_newlines_combo.setEnabled(True)
 
@@ -837,7 +841,7 @@ class WordSubstitutionsDialog(QDialog):
             self,
         )
         instructions.setStyleSheet(
-            "padding: 10px; background-color: #f0f0f0; border-radius: 5px;"
+            f"padding: 10px; background-color: {COLORS['GREY_BACKGROUND']}; border-radius: 5px;"
         )
         instructions.setWordWrap(True)
         layout.addWidget(instructions)
@@ -911,9 +915,10 @@ class abogen(QWidget):
     def __init__(self):
         super().__init__()
         self.config = load_config()
-        self.apply_theme(self.config.get("theme", "system"))
+        _d = all_settings_defaults()
+        self.apply_theme(self.config.get("theme", _d["theme"]))
         migrate_subtitle_format(self.config)
-        self.check_updates = self.config.get("check_updates", True)
+        self.check_updates = self.config.get("check_updates", _d["check_updates"])
         self.save_option = self.config.get("save_option", "Save next to input file")
         self.selected_output_folder = self.config.get("selected_output_folder", None)
         self.selected_file = self.selected_file_type = self.selected_book_path = None
@@ -921,7 +926,7 @@ class abogen(QWidget):
             None  # Add new variable to track the displayed file path
         )
         # Max log lines
-        self.log_window_max_lines = self.config.get("log_window_max_lines", 2000)
+        self.log_window_max_lines = self.config.get("log_window_max_lines", _d["log_window_max_lines"])
         self.selected_chapters = set()
         self.last_opened_book_path = None  # Track the last opened book path
         self.last_output_path = None
@@ -936,40 +941,28 @@ class abogen(QWidget):
             self.selected_voice = None
             self.selected_lang = None
         else:
-            self.selected_voice = self.config.get("selected_voice", "af_heart")
-            self.selected_lang = self.selected_voice[0] if self.selected_voice else None
+            self.selected_voice = self.config.get("selected_voice", _d["selected_voice"])
+            self.selected_lang = language_for_voice_id(self.selected_voice)
         self.is_converting = False
-        self.subtitle_mode = self.config.get("subtitle_mode", "Sentence")
-        self.max_subtitle_words = self.config.get(
-            "max_subtitle_words", 50
-        )  # Default max words per subtitle
-        self.silence_duration = self.config.get(
-            "silence_duration", 2.0
-        )  # Default silence duration
-        self.selected_format = self.config.get("selected_format", "wav")
-        self.separate_chapters_format = self.config.get(
-            "separate_chapters_format", "wav"
-        )  # Format for individual chapter files
-        self.use_gpu = self.config.get(
-            "use_gpu", True  # Load GPU setting with default True
-        )
-        self.replace_single_newlines = self.config.get("replace_single_newlines", True)
-        self.use_silent_gaps = self.config.get("use_silent_gaps", True)
-        self.subtitle_speed_method = self.config.get("subtitle_speed_method", "tts")
-        self.use_spacy_segmentation = self.config.get("use_spacy_segmentation", True)
+        self.subtitle_mode = self.config.get("subtitle_mode", _d["subtitle_mode"])
+        self.max_subtitle_words = self.config.get("max_subtitle_words", _d["max_subtitle_words"])
+        self.silence_duration = self.config.get("silence_duration", _d.get("silence_between_chapters", 2.0))
+        self.selected_format = self.config.get("selected_format", _d["selected_format"])
+        self.separate_chapters_format = self.config.get("separate_chapters_format", _d["separate_chapters_format"])
+        self.use_gpu = self.config.get("use_gpu", _d["use_gpu"])
+        self.replace_single_newlines = self.config.get("replace_single_newlines", _d.get("replace_single_newlines", True))
+        self.use_silent_gaps = self.config.get("use_silent_gaps", _d["use_silent_gaps"])
+        self.subtitle_speed_method = self.config.get("subtitle_speed_method", _d["subtitle_speed_method"])
+        self.use_spacy_segmentation = self.config.get("use_spacy_segmentation", _d["use_spacy_segmentation"])
+        self.read_title_intro = self.config.get("read_title_intro", _d.get("read_title_intro", False))
+        self.read_closing_outro = self.config.get("read_closing_outro", _d.get("read_closing_outro", True))
         # Word substitution settings
-        self.word_substitutions_enabled = self.config.get(
-            "word_substitutions_enabled", False
-        )
-        self.word_substitutions_list = self.config.get("word_substitutions_list", "")
-        self.case_sensitive_substitutions = self.config.get(
-            "case_sensitive_substitutions", False
-        )
-        self.replace_all_caps = self.config.get("replace_all_caps", False)
-        self.replace_numerals = self.config.get("replace_numerals", False)
-        self.fix_nonstandard_punctuation = self.config.get(
-            "fix_nonstandard_punctuation", False
-        )
+        self.word_substitutions_enabled = self.config.get("word_substitutions_enabled", _d["word_substitutions_enabled"])
+        self.word_substitutions_list = self.config.get("word_substitutions_list", _d["word_substitutions_list"])
+        self.case_sensitive_substitutions = self.config.get("case_sensitive_substitutions", _d["case_sensitive_substitutions"])
+        self.replace_all_caps = self.config.get("replace_all_caps", _d["replace_all_caps"])
+        self.replace_numerals = self.config.get("replace_numerals", _d["replace_numerals"])
+        self.fix_nonstandard_punctuation = self.config.get("fix_nonstandard_punctuation", _d["fix_nonstandard_punctuation"])
         self._pending_close_event = None
         self.gpu_ok = False  # Initialize GPU availability status
 
@@ -996,8 +989,13 @@ class abogen(QWidget):
         self.queued_items = []
         self.current_queue_index = 0
 
-        self.initUI()
-        self.speed_slider.setValue(int(self.config.get("speed", 1.00) * 100))
+        from abogen.utils import timed_log
+        import logging
+        _startup_log = logging.getLogger("abogen.startup")
+
+        with timed_log("GUI initUI (widget building)", logger=_startup_log):
+            self.initUI()
+        self.speed_slider.setValue(int(self.config.get("speed", _d["speed"]) * 100))
         self.update_speed_label()
         # Set initial selection: prefer profile, else voice
         idx = -1
@@ -1011,13 +1009,17 @@ class abogen(QWidget):
             if self.selected_profile_name:
                 from abogen.voice_profiles import load_profiles
 
-                entry = load_profiles().get(self.selected_profile_name, {})
+                with timed_log("voice profile load", logger=_startup_log):
+                    entry = load_profiles().get(self.selected_profile_name, {})
                 if isinstance(entry, dict):
                     self.mixed_voice_state = entry.get("voices", [])
-                    self.selected_lang = entry.get("language")
+                    self.selected_lang = resolve_profile_language(entry)
                 else:
                     self.mixed_voice_state = entry
-                    self.selected_lang = entry[0][0] if entry and entry[0] else None
+                    self.selected_lang = (
+                        language_for_voice_id(entry[0]) if entry and entry[0] else Language.EN_US
+                    )
+        self.update_subtitle_options_availability()
         if self.save_option == "Choose output folder" and self.selected_output_folder:
             self.save_path_label.setText(self.selected_output_folder)
             self.save_path_row_widget.show()
@@ -1183,6 +1185,7 @@ class abogen(QWidget):
             "Sentence + Comma: Subtitles will be generated for each sentence and comma.\n"
             "Sentence + Highlighting: Subtitles with word-by-word karaoke highlighting.\n"
             "1+ word: Subtitles will be generated for each word(s).\n\n"
+            "Word-count and highlighting modes are only available for English.\n"
             "Supported languages for subtitle generation:\n"
             + "\n".join(
                 f'"{lang}" => {LANGUAGE_DESCRIPTIONS.get(lang, lang)}'
@@ -1761,8 +1764,9 @@ class abogen(QWidget):
 
     def update_subtitle_options_availability(self):
         """
-        Update the enabled state of subtitle options based on the selected language.
-        For non-English languages, only sentence-based and line-based modes are supported.
+        Update the enabled state of subtitle options based on the selected
+        language and input type. Subtitle generation works for every language,
+        but word-count and highlighting modes are only available for English.
         """
         # Check if current file is a subtitle file
         is_subtitle_input = False
@@ -1771,16 +1775,14 @@ class abogen(QWidget):
         ):
             is_subtitle_input = True
 
-        if self.selected_lang not in SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION:
-            self.subtitle_combo.setEnabled(False)
-            self.subtitle_format_combo.setEnabled(False)
-            return
-
         # Only enable subtitle_combo if it's NOT a subtitle input
         self.subtitle_combo.setEnabled(not is_subtitle_input)
         self.subtitle_format_combo.setEnabled(True)
 
-        is_english = self.selected_lang in ["a", "b"]
+        is_english = self.selected_lang in (
+            Language.EN_US,
+            Language.EN_GB,
+        )
 
         # Items to keep enabled for non-English
         allowed_modes = ["Disabled", "Line", "Sentence", "Sentence + Comma"]
@@ -1795,10 +1797,7 @@ class abogen(QWidget):
             if is_english:
                 item.setEnabled(True)
             else:
-                if text in allowed_modes:
-                    item.setEnabled(True)
-                else:
-                    item.setEnabled(False)
+                item.setEnabled(text in allowed_modes)
 
         # If current selection is disabled, switch to a valid one
         current_text = self.subtitle_combo.currentText()
@@ -1817,7 +1816,7 @@ class abogen(QWidget):
 
     def on_voice_changed(self, index):
         voice = self.voice_combo.itemData(index)
-        self.selected_voice, self.selected_lang = voice, voice[0]
+        self.selected_voice, self.selected_lang = voice, language_for_voice_id(voice)
         self.config["selected_voice"] = voice
         save_config(self.config)
         # Enable/disable subtitle options based on language
@@ -1834,10 +1833,12 @@ class abogen(QWidget):
             # set mixed voices and language
             if isinstance(entry, dict):
                 self.mixed_voice_state = entry.get("voices", [])
-                self.selected_lang = entry.get("language")
+                self.selected_lang = resolve_profile_language(entry)
             else:
                 self.mixed_voice_state = entry
-                self.selected_lang = entry[0][0] if entry and entry[0] else None
+                self.selected_lang = (
+                    language_for_voice_id(entry[0]) if entry and entry[0] else Language.EN_US
+                )
             self.selected_voice = None
             self.config["selected_profile_name"] = pname
             self.config.pop("selected_voice", None)
@@ -1847,7 +1848,7 @@ class abogen(QWidget):
         else:
             self.mixed_voice_state = None
             self.selected_profile_name = None
-            self.selected_voice, self.selected_lang = data, data[0]
+            self.selected_voice, self.selected_lang = data, language_for_voice_id(data)
             self.config["selected_voice"] = data
             if "selected_profile_name" in self.config:
                 del self.config["selected_profile_name"]
@@ -1858,8 +1859,9 @@ class abogen(QWidget):
         from abogen.voice_profiles import load_profiles
 
         entry = load_profiles().get(profile_name, {})
-        lang = entry.get("language") if isinstance(entry, dict) else None
-        enable = lang in SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION
+        enable = (
+            resolve_profile_language(entry) in SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION
+        )
         self.subtitle_combo.setEnabled(enable)
         self.subtitle_format_combo.setEnabled(enable)
 
@@ -1873,7 +1875,7 @@ class abogen(QWidget):
         for pname in load_profiles().keys():
             self.voice_combo.addItem(profile_icon, pname, f"profile:{pname}")
         # re-add voices
-        for v in VOICES_INTERNAL:
+        for v in get_voices("kokoro"):
             icon = QIcon()
             flag_path = get_resource_path("abogen.assets.flags", f"{v[0]}.png")
             if flag_path and os.path.exists(flag_path):
@@ -2160,7 +2162,7 @@ class abogen(QWidget):
             )
 
             # CHECK GLOBAL OVERRIDE SETTING
-            if not self.config.get("queue_override_settings", False):
+            if not self.config.get("queue_override_settings", _DEFAULTS["queue_override_settings"]):
                 self.selected_lang = queued_item.lang_code
                 self.speed_slider.setValue(int(queued_item.speed * 100))
                 
@@ -2234,26 +2236,25 @@ class abogen(QWidget):
             self.current_queue_index = 0  # Reset for next time
 
     def get_voice_formula(self) -> str:
+        from abogen.voice_formulas import pairs_to_formula
+
         if self.mixed_voice_state:
-            formula_components = [
-                f"{name}*{weight}" for name, weight in self.mixed_voice_state
-            ]
-            return " + ".join(filter(None, formula_components))
+            return pairs_to_formula(self.mixed_voice_state) or ""
         else:
             return self.selected_voice
 
-    def get_selected_lang(self, voice_formula) -> str:
+    def get_selected_lang(self, voice_formula) -> Language:
         if self.selected_profile_name:
             from abogen.voice_profiles import load_profiles
 
             entry = load_profiles().get(self.selected_profile_name, {})
-            selected_lang = entry.get("language")
+            selected_lang = resolve_profile_language(entry)
         else:
-            selected_lang = self.selected_voice[0] if self.selected_voice else None
+            selected_lang = language_for_voice_id(self.selected_voice)
         # fallback: extract from formula if missing
         if not selected_lang:
             m = re.search(r"\b([a-z])", voice_formula)
-            selected_lang = m.group(1) if m else None
+            selected_lang = language_for_code(m.group(1)) if m else Language.EN_US
         return selected_lang
 
     def get_actual_subtitle_mode(self) -> str:
@@ -2316,9 +2317,9 @@ class abogen(QWidget):
             file_size_str = "Unknown"
 
         # pipeline_loaded_callback remains unchanged
-        def pipeline_loaded_callback(np_module, kpipeline_class, error):
+        def pipeline_loaded_callback(backend, error):
             if error:
-                self.update_log((f"Error loading numpy or KPipeline: {error}", "red"))
+                self.update_log((f"Error loading TTS backend: {error}", "red"))
                 prevent_sleep_end()
                 return
 
@@ -2341,8 +2342,7 @@ class abogen(QWidget):
                 self.selected_output_folder,
                 subtitle_mode=actual_subtitle_mode,
                 output_format=self.selected_format,
-                np_module=np_module,
-                kpipeline_class=kpipeline_class,
+                backend=backend,
                 start_time=self.start_time,
                 total_char_count=self.char_count,
                 use_gpu=self.gpu_ok,
@@ -2403,6 +2403,9 @@ class abogen(QWidget):
                 self.conversion_thread.merge_chapters_at_end = getattr(
                     self, "merge_chapters_at_end", True
                 )
+            # Pass intro/outro settings
+            self.conversion_thread.read_title_intro = self.read_title_intro
+            self.conversion_thread.read_closing_outro = self.read_closing_outro
             self.conversion_thread.progress_updated.connect(self.update_progress)
             self.conversion_thread.log_updated.connect(self.update_log)
             self.conversion_thread.conversion_finished.connect(
@@ -2426,7 +2429,11 @@ class abogen(QWidget):
             self.gpu_ok = gpu_ok
             self.update_log((gpu_msg, gpu_ok))
             self.update_log("Loading modules...")
-            load_thread = LoadPipelineThread(pipeline_loaded_callback)
+
+            lang_code = self.selected_lang or Language.EN_US
+            load_thread = LoadPipelineThread(
+                pipeline_loaded_callback, lang_code=lang_code, use_gpu=gpu_ok
+            )
             load_thread.start()
 
         threading.Thread(target=gpu_and_load, daemon=True).start()
@@ -2437,7 +2444,7 @@ class abogen(QWidget):
             return
 
         # Check if override was active (this determines which settings were ACTUALLY used)
-        override_active = self.config.get("queue_override_settings", False)
+        override_active = self.config.get("queue_override_settings", _DEFAULTS["queue_override_settings"])
 
         # If override is ON, capture the global settings that were used for processing
         if override_active:
@@ -2754,12 +2761,12 @@ class abogen(QWidget):
                 from abogen.voice_profiles import load_profiles
 
                 entry = load_profiles().get(self.selected_profile_name, {})
-                lang_to_cache = entry.get("language")
+                lang_to_cache = resolve_profile_language(entry)
             else:
                 lang_to_cache = self.selected_lang
             if not lang_to_cache and self.mixed_voice_state:
                 lang_to_cache = (
-                    self.mixed_voice_state[0][0][0]
+                    language_for_voice_id(self.mixed_voice_state[0][0])
                     if self.mixed_voice_state and self.mixed_voice_state[0][0]
                     else None
                 )
@@ -2863,18 +2870,18 @@ class abogen(QWidget):
             )
             self.loading_movie.start()
 
-        def pipeline_loaded_callback(np_module, kpipeline_class, error):
-            self._on_pipeline_loaded_for_preview(np_module, kpipeline_class, error)
-
-        load_thread = LoadPipelineThread(pipeline_loaded_callback)
+        lang = self.selected_lang or Language.EN_US
+        load_thread = LoadPipelineThread(
+            self._on_pipeline_loaded_for_preview, lang_code=lang, use_gpu=self.gpu_ok
+        )
         load_thread.start()
 
-    def _on_pipeline_loaded_for_preview(self, np_module, kpipeline_class, error):
+    def _on_pipeline_loaded_for_preview(self, backend, error):
         # stop loading animation and restore icon on error
         if error:
             self.loading_movie.stop()
             self._show_error_message_box(
-                "Loading Error", f"Error loading numpy or KPipeline: {error}"
+                "Loading Error", f"Error loading TTS backend: {error}"
             )
             self.btn_preview.setIcon(self.play_icon)
             self.btn_preview.setEnabled(True)
@@ -2895,24 +2902,24 @@ class abogen(QWidget):
                 from abogen.voice_profiles import load_profiles
 
                 entry = load_profiles().get(self.selected_profile_name, {})
-                lang = entry.get("language")
+                lang = resolve_profile_language(entry)
             else:
                 lang = self.selected_lang
             if not lang and self.mixed_voice_state:
                 lang = (
-                    self.mixed_voice_state[0][0][0]
+                    language_for_voice_id(self.mixed_voice_state[0][0])
                     if self.mixed_voice_state and self.mixed_voice_state[0][0]
                     else None
                 )
         else:
-            lang = self.selected_voice[0]
+            lang = language_for_voice_id(self.selected_voice)
             voice = self.selected_voice
 
         # use same gpu/cpu logic as in conversion
         gpu_msg, gpu_ok = get_gpu_acceleration(self.use_gpu)
 
         self.preview_thread = VoicePreviewThread(
-            np_module, kpipeline_class, lang, voice, speed, gpu_ok
+            backend, lang, voice, speed, gpu_ok
         )
         self.preview_thread.finished.connect(self._play_preview_audio)
         self.preview_thread.error.connect(self._preview_error)
@@ -3166,14 +3173,25 @@ class abogen(QWidget):
             save_config(self.config)
 
     def cleanup_conversion_thread(self):
-        # Stop conversion thread
+        # Stop conversion thread (bounded wait so closing never hangs)
         if (
             hasattr(self, "conversion_thread")
             and self.conversion_thread is not None
             and self.conversion_thread.isRunning()
         ):
+            _log.info("Close: stopping conversion thread")
+            start = time.perf_counter()
             self.conversion_thread.cancel()
-            self.conversion_thread.wait()
+            if not self.conversion_thread.wait(2000):
+                _log.warning("Close: conversion thread did not stop in 2s, terminating")
+                self.conversion_thread.terminate()
+                self.conversion_thread.wait(1000)
+            _log.info(
+                "Close: conversion thread stopped in %.2fs",
+                time.perf_counter() - start,
+            )
+        else:
+            _log.info("Close: no running conversion thread")
 
     def cleanup_preview_threads(self):
         # Stop preview generation thread
@@ -3182,8 +3200,13 @@ class abogen(QWidget):
             and self.preview_thread is not None
             and self.preview_thread.isRunning()
         ):
+            _log.info("Close: terminating preview thread")
+            start = time.perf_counter()
             self.preview_thread.terminate()
-            self.preview_thread.wait()
+            self.preview_thread.wait(1000)
+            _log.info(
+                "Close: preview thread stopped in %.2fs", time.perf_counter() - start
+            )
 
         # Stop audio playback thread
         if (
@@ -3191,8 +3214,13 @@ class abogen(QWidget):
             and self.play_audio_thread is not None
             and self.play_audio_thread.isRunning()
         ):
+            _log.info("Close: stopping audio playback thread")
+            start = time.perf_counter()
             self.play_audio_thread.stop()
-            self.play_audio_thread.wait()
+            self.play_audio_thread.wait(1000)
+            _log.info(
+                "Close: audio thread stopped in %.2fs", time.perf_counter() - start
+            )
 
         # Cleanup pygame mixer if initialized
         try:
@@ -3203,6 +3231,7 @@ class abogen(QWidget):
             pass
 
     def closeEvent(self, event):
+        _log.info("Close: window close requested (converting=%s)", self.is_converting)
         if self.is_converting:
             box = QMessageBox(self)
             box.setIcon(QMessageBox.Icon.Warning)
@@ -3215,10 +3244,12 @@ class abogen(QWidget):
             )
             box.setDefaultButton(QMessageBox.StandardButton.No)
             if box.exec() == QMessageBox.StandardButton.Yes:
+                _log.info("Close: user confirmed exit during conversion")
                 self.cleanup_conversion_thread()
                 self.cleanup_preview_threads()
                 event.accept()
             else:
+                _log.info("Close: user cancelled exit")
                 event.ignore()
         else:
             self.cleanup_conversion_thread()
@@ -3409,7 +3440,7 @@ class abogen(QWidget):
         app.installEventFilter(app._dark_titlebar_event_filter)
 
         # Save config if changed
-        if self.config.get("theme", "system") != theme:
+        if self.config.get("theme", _DEFAULTS["theme"]) != theme:
             self.config["theme"] = theme
             save_config(self.config)
 
@@ -3431,7 +3462,7 @@ class abogen(QWidget):
         ]
 
         # Get current theme from config, default to "system"
-        current_theme = self.config.get("theme", "system")
+        current_theme = self.config.get("theme", _DEFAULTS["theme"])
         for value, text in theme_options:
             theme_action = QAction(text, self)
             theme_action.setCheckable(True)
@@ -3562,6 +3593,27 @@ class abogen(QWidget):
         # Add separator
         menu.addSeparator()
 
+        # Add title intro option
+        self.title_intro_action = QAction("Read title intro before first chapter", self)
+        self.title_intro_action.setCheckable(True)
+        self.title_intro_action.setChecked(self.read_title_intro)
+        self.title_intro_action.triggered.connect(
+            lambda checked: self.toggle_read_title_intro(checked)
+        )
+        menu.addAction(self.title_intro_action)
+
+        # Add closing outro option
+        self.closing_outro_action = QAction("Read closing outro after last chapter", self)
+        self.closing_outro_action.setCheckable(True)
+        self.closing_outro_action.setChecked(self.read_closing_outro)
+        self.closing_outro_action.triggered.connect(
+            lambda checked: self.toggle_read_closing_outro(checked)
+        )
+        menu.addAction(self.closing_outro_action)
+
+        # Add separator
+        menu.addSeparator()
+
         # Add "Pre-download models and voices for offline use" option
         predownload_action = QAction(
             "Pre-download models and voices for offline use", self
@@ -3573,7 +3625,7 @@ class abogen(QWidget):
         disable_kokoro_action = QAction("Disable Kokoro's internet access", self)
         disable_kokoro_action.setCheckable(True)
         disable_kokoro_action.setChecked(
-            self.config.get("disable_kokoro_internet", False)
+            self.config.get("disable_kokoro_internet", _DEFAULTS["disable_kokoro_internet"])
         )
         disable_kokoro_action.triggered.connect(
             lambda checked: self.toggle_kokoro_internet_access(checked)
@@ -3583,7 +3635,7 @@ class abogen(QWidget):
         # Add check for updates option
         check_updates_action = QAction("Check for updates at startup", self)
         check_updates_action.setCheckable(True)
-        check_updates_action.setChecked(self.config.get("check_updates", True))
+        check_updates_action.setChecked(self.config.get("check_updates", _DEFAULTS["check_updates"]))
         check_updates_action.triggered.connect(self.toggle_check_updates)
         menu.addAction(check_updates_action)
 
@@ -3638,6 +3690,16 @@ class abogen(QWidget):
         self.config["use_spacy_segmentation"] = enabled
         save_config(self.config)
 
+    def toggle_read_title_intro(self, enabled):
+        self.read_title_intro = enabled
+        self.config["read_title_intro"] = enabled
+        save_config(self.config)
+
+    def toggle_read_closing_outro(self, enabled):
+        self.read_closing_outro = enabled
+        self.config["read_closing_outro"] = enabled
+        save_config(self.config)
+
     def restart_app(self):
 
         import sys
@@ -3916,7 +3978,9 @@ Categories=AudioVideo;Audio;Utility;
                     initial_state = entry.get("voices", [])
                 else:
                     initial_state = entry
-                    self.selected_lang = entry[0][0] if entry and entry[0] else None
+                    self.selected_lang = (
+                        language_for_voice_id(entry[0]) if entry and entry[0] else Language.EN_US
+                    )
         dialog = VoiceFormulaDialog(
             self, initial_state=initial_state, selected_profile=selected_profile
         )
@@ -4209,7 +4273,7 @@ Categories=AudioVideo;Audio;Utility;
         """Open a dialog to set the maximum words per subtitle"""
         from PyQt6.QtWidgets import QInputDialog
 
-        current_value = self.config.get("max_subtitle_words", 50)
+        current_value = self.config.get("max_subtitle_words", _DEFAULTS["max_subtitle_words"])
 
         value, ok = QInputDialog.getInt(
             self,
@@ -4237,7 +4301,7 @@ Categories=AudioVideo;Audio;Utility;
     def set_silence_between_chapters(self):
         """Open a dialog to set the silence duration between chapters"""
 
-        current_value = self.config.get("silence_duration", 2.0)
+        current_value = self.config.get("silence_duration", _DEFAULTS.get("silence_between_chapters", 2.0))
 
         dlg = QInputDialog(self)
         dlg.setWindowTitle("Silence Duration (seconds)")

abogen/pyqt/main.py

@@ -1,129 +1,124 @@
+import logging
 import os
 import sys
 import platform
-import atexit
-import signal
-from abogen.utils import get_resource_path, load_config, prevent_sleep_end
 
+# Initialise global shutdown handling (atexit, signals, Qt) as early as possible.
+from abogen import shutdown  # noqa: F401
+shutdown.register_shutdown()
+
+from abogen.utils import get_resource_path, setup_console_logging, timed_log  # noqa: E402
+
+_log = logging.getLogger("abogen.startup")
+setup_console_logging()
 
 # Fix PyTorch DLL loading issue ([WinError 1114]) on Windows before importing PyQt6
 if platform.system() == "Windows":
-    import ctypes
-    from importlib.util import find_spec
+    with timed_log("PyTorch DLLs (Windows)", logger=_log):
+        import ctypes
+        from importlib.util import find_spec
 
-    try:
-        if (
-            (spec := find_spec("torch"))
-            and spec.origin
-            and os.path.exists(
-                dll_path := os.path.join(os.path.dirname(spec.origin), "lib", "c10.dll")
-            )
-        ):
-            ctypes.CDLL(os.path.normpath(dll_path))
-    except Exception:
-        pass
+        try:
+            if (
+                (spec := find_spec("torch"))
+                and spec.origin
+                and os.path.exists(
+                    dll_path := os.path.join(os.path.dirname(spec.origin), "lib", "c10.dll")
+                )
+            ):
+                ctypes.CDLL(os.path.normpath(dll_path))
+        except Exception:
+            pass
 
 
 # Qt platform plugin detection (fixes #59)
-try:
-    from PyQt6.QtCore import QLibraryInfo
+with timed_log("Qt platform plugin detection", logger=_log):
+    try:
+        from PyQt6.QtCore import QLibraryInfo
 
-    # Get the path to the plugins directory
-    plugins = QLibraryInfo.path(QLibraryInfo.LibraryPath.PluginsPath)
+        # Get the path to the plugins directory
+        plugins = QLibraryInfo.path(QLibraryInfo.LibraryPath.PluginsPath)
 
-    # Normalize path to use the OS-native separators and absolute path
-    platform_dir = os.path.normpath(os.path.join(plugins, "platforms"))
+        # Normalize path to use the OS-native separators and absolute path
+        platform_dir = os.path.normpath(os.path.join(plugins, "platforms"))
 
-    # Ensure we work with an absolute path for clarity
-    platform_dir = os.path.abspath(platform_dir)
+        # Ensure we work with an absolute path for clarity
+        platform_dir = os.path.abspath(platform_dir)
 
-    if os.path.isdir(platform_dir):
-        os.environ["QT_QPA_PLATFORM_PLUGIN_PATH"] = platform_dir
-        print("QT_QPA_PLATFORM_PLUGIN_PATH set to:", platform_dir)
-    else:
-        print("PyQt6 platform plugins not found at", platform_dir)
-except ImportError:
-    print("PyQt6 not installed.")
+        if os.path.isdir(platform_dir):
+            os.environ["QT_QPA_PLATFORM_PLUGIN_PATH"] = platform_dir
+            _log.info("QT_QPA_PLATFORM_PLUGIN_PATH set to: %s", platform_dir)
+        else:
+            _log.warning("PyQt6 platform plugins not found at %s", platform_dir)
+    except ImportError:
+        _log.warning("PyQt6 not installed.")
 
 
 # Pre-load "libxcb-cursor" on Linux (fixes #101)
 if platform.system() == "Linux":
-    arch = platform.machine().lower()
-    lib_filename = {"x86_64": "libxcb-cursor-amd64.so.0", "amd64": "libxcb-cursor-amd64.so.0", "aarch64": "libxcb-cursor-arm64.so.0", "arm64": "libxcb-cursor-arm64.so.0"}.get(arch)
-    if lib_filename:
-        import ctypes
-        try:
-            # Try to load the system libxcb-cursor.so.0 first
-            ctypes.CDLL('libxcb-cursor.so.0', mode=ctypes.RTLD_GLOBAL)
-        except OSError:
-            # System lib not available, load the bundled version
-            lib_path = get_resource_path('abogen.libs', lib_filename)
-            if lib_path:
-                try:
-                    ctypes.CDLL(lib_path, mode=ctypes.RTLD_GLOBAL)
-                except OSError:
-                    # If it fails (e.g. wrong glibc version on very old systems),
-                    # we simply ignore it and hope the system has the library.
-                    pass
+    with timed_log("libxcb-cursor preload (Linux)", logger=_log):
+        arch = platform.machine().lower()
+        lib_filename = {"x86_64": "libxcb-cursor-amd64.so.0", "amd64": "libxcb-cursor-amd64.so.0", "aarch64": "libxcb-cursor-arm64.so.0", "arm64": "libxcb-cursor-arm64.so.0"}.get(arch)
+        if lib_filename:
+            import ctypes
+            try:
+                # Try to load the system libxcb-cursor.so.0 first
+                ctypes.CDLL('libxcb-cursor.so.0', mode=ctypes.RTLD_GLOBAL)
+            except OSError:
+                # System lib not available, load the bundled version
+                lib_path = get_resource_path('abogen.libs', lib_filename)
+                if lib_path:
+                    try:
+                        ctypes.CDLL(lib_path, mode=ctypes.RTLD_GLOBAL)
+                    except OSError:
+                        # If it fails (e.g. wrong glibc version on very old systems),
+                        # we simply ignore it and hope the system has the library.
+                        pass
 
 
 # Set application ID for Windows taskbar icon
 if platform.system() == "Windows":
-    try:
-        from abogen.constants import PROGRAM_NAME, VERSION
-        import ctypes
+    with timed_log("Windows AppUserModelID", logger=_log):
+        try:
+            from abogen.constants import PROGRAM_NAME, VERSION
+            import ctypes
 
-        app_id = f"{PROGRAM_NAME}.{VERSION}"
-        ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID(app_id)
-    except Exception as e:
-        print("Warning: failed to set AppUserModelID:", e)
+            app_id = f"{PROGRAM_NAME}.{VERSION}"
+            ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID(app_id)
+        except Exception as e:
+            _log.warning("Failed to set AppUserModelID: %s", e)
 
-from PyQt6.QtWidgets import QApplication
-from PyQt6.QtGui import QIcon
-from PyQt6.QtCore import (
-    QLibraryInfo,
-    qInstallMessageHandler,
-    QtMsgType,
-)
+with timed_log("PyQt6 imports", logger=_log):
+    from PyQt6.QtWidgets import QApplication
+    from PyQt6.QtGui import QIcon
+    from PyQt6.QtCore import (
+        QLibraryInfo,
+        qInstallMessageHandler,
+        QtMsgType,
+    )
 
 # Add the directory to Python path
 sys.path.insert(0, os.path.join(os.path.dirname(__file__)))
 
 # Set Hugging Face Hub environment variables
-os.environ["HF_HUB_DISABLE_TELEMETRY"] = "1"  # Disable Hugging Face telemetry
-os.environ["HF_HUB_ETAG_TIMEOUT"] = "10"  # Metadata request timeout (seconds)
-os.environ["HF_HUB_DOWNLOAD_TIMEOUT"] = "10"  # File download timeout (seconds)
-os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"  # Disable symlinks warning
-if load_config().get("disable_kokoro_internet", False):
-    print("INFO: Kokoro's internet access is disabled.")
-    os.environ["HF_HUB_OFFLINE"] = "1"  # Disable Hugging Face Hub internet access
+with timed_log("config load + HF env setup", logger=_log):
+    os.environ["HF_HUB_DISABLE_TELEMETRY"] = "1"  # Disable Hugging Face telemetry
+    os.environ["HF_HUB_ETAG_TIMEOUT"] = "10"  # Metadata request timeout (seconds)
+    os.environ["HF_HUB_DOWNLOAD_TIMEOUT"] = "10"  # File download timeout (seconds)
+    os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"  # Disable symlinks warning
+    from abogen.utils import load_config
+    if load_config().get("disable_kokoro_internet", False):
+        _log.info("Kokoro's internet access is disabled.")
+        os.environ["HF_HUB_OFFLINE"] = "1"  # Disable Hugging Face Hub internet access
 
-from abogen.pyqt.gui import abogen
-from abogen.constants import PROGRAM_NAME, VERSION
+with timed_log("GUI module import (abogen.pyqt.gui)", logger=_log):
+    from abogen.pyqt.gui import abogen
+    from abogen.constants import PROGRAM_NAME, VERSION
 
 # Set environment variables for AMD ROCm
 os.environ["MIOPEN_FIND_MODE"] = "FAST"
 os.environ["MIOPEN_CONV_PRECISE_ROCM_TUNING"] = "0"
 
-# Reset sleep states
-atexit.register(prevent_sleep_end)
-
-
-# Also handle signals (Ctrl+C, kill, etc.)
-def _cleanup_sleep(signum, frame):
-    prevent_sleep_end()
-    sys.exit(0)
-
-
-signal.signal(signal.SIGINT, _cleanup_sleep)
-signal.signal(signal.SIGTERM, _cleanup_sleep)
-
-# Ensure sys.stdout and sys.stderr are valid in GUI mode
-if sys.stdout is None:
-    sys.stdout = open(os.devnull, "w")
-if sys.stderr is None:
-    sys.stderr = open(os.devnull, "w")
-
 # Enable MPS GPU acceleration on Mac Apple Silicon
 if platform.system() == "Darwin" and platform.processor() == "arm":
     os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"
@@ -136,6 +131,8 @@ def qt_message_handler(mode, context, message):
         return  # Suppress this specific message
     if "setGrabPopup called with a parent, QtWaylandClient" in message:
         return
+    if "Failed to register with host portal" in message:
+        return
 
     if mode == QtMsgType.QtWarningMsg:
         print(f"Qt Warning: {message}")
@@ -164,7 +161,11 @@ if platform.system() == "Linux":
 
 def main():
     """Main entry point for console usage."""
-    app = QApplication(sys.argv)
+    with timed_log("QApplication creation", logger=_log):
+        app = QApplication(sys.argv)
+
+    # Qt shutdown hook must be connected AFTER QApplication exists
+    shutdown.install_qt_hook()
 
     # Set application icon using get_resource_path from utils
     icon_path = get_resource_path("abogen.assets", "icon.ico")
@@ -178,10 +179,17 @@ def main():
         except AttributeError:
             pass
 
-    ex = abogen()
-    ex.show()
-    sys.exit(app.exec())
+    with timed_log("main window construction", logger=_log):
+        ex = abogen()
+    with timed_log("window show", logger=_log):
+        ex.show()
+    _log.info("App startup complete. Showing window.")
+    rc = app.exec()
+    # Restore the default Qt message handler BEFORE interpreter shutdown.
+    # A Python message handler invoked during Qt teardown segfaults (SIGSEGV).
+    qInstallMessageHandler(None)
+    sys.exit(rc)
 
 
 if __name__ == "__main__":
-    main()
+    main()

abogen/pyqt/predownload_gui.py

@@ -21,7 +21,8 @@ from PyQt6.QtWidgets import (
 )
 from PyQt6.QtCore import QThread, pyqtSignal
 
-from abogen.constants import COLORS, VOICES_INTERNAL
+from abogen.constants import COLORS
+from abogen.tts_plugin.utils import get_voices
 from abogen.spacy_utils import SPACY_MODELS
 import abogen.hf_tracker
 
@@ -114,7 +115,7 @@ class PreDownloadWorker(QThread):
             self._voices_success = False
             return
 
-        voice_list = VOICES_INTERNAL
+        voice_list = get_voices("kokoro")
         for idx, voice in enumerate(voice_list, start=1):
             if self._cancelled:
                 self._voices_success = False
@@ -462,14 +463,14 @@ class PreDownloadDialog(QDialog):
         try:
             from huggingface_hub import try_to_load_from_cache
 
-            for voice in VOICES_INTERNAL:
+            for voice in get_voices("kokoro"):
                 if not try_to_load_from_cache(
                     repo_id="hexgrad/Kokoro-82M", filename=f"voices/{voice}.pt"
                 ):
                     missing.append(voice)
         except Exception:
             # If HF missing, report all as missing
-            return False, list(VOICES_INTERNAL)
+            return False, list(get_voices("kokoro"))
         return (len(missing) == 0), missing
 
     def _check_kokoro_model(self) -> bool:

abogen/pyqt/queue_manager_gui.py

@@ -523,7 +523,7 @@ class QueueManager(QDialog):
         return attrs
 
     def add_files_from_paths(self, file_paths):
-        from abogen.subtitle_utils import calculate_text_length
+        from abogen.domain.text_utils import calculate_text_length
         from PyQt6.QtWidgets import QMessageBox
         import os
 

abogen/pyqt/voice_formula_gui.py

@@ -28,11 +28,10 @@ from PyQt6.QtWidgets import (
 from PyQt6.QtCore import Qt, QTimer, QPoint, QRect, QSize
 from PyQt6.QtGui import QPixmap, QIcon, QAction
 from abogen.constants import (
-    VOICES_INTERNAL,
-    SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION,
     LANGUAGE_DESCRIPTIONS,
     COLORS,
 )
+from abogen.tts_plugin.utils import get_voices
 import re
 import platform
 from abogen.utils import get_resource_path
@@ -179,7 +178,7 @@ class VoiceMixer(QWidget):
         layout.addWidget(QLabel(name), alignment=Qt.AlignmentFlag.AlignCenter)
 
         # Voice name label with gender icon
-        is_female = self.voice_name in VOICES_INTERNAL and self.voice_name[1] == "f"
+        is_female = self.voice_name in get_voices("kokoro") and self.voice_name[1] == "f"
 
         # Icons layout (flag and gender)
         icons_layout = QHBoxLayout()
@@ -772,7 +771,7 @@ class VoiceFormulaDialog(QDialog):
 
     def add_voices(self, initial_state):
         first_enabled_voice = None
-        for voice in VOICES_INTERNAL:
+        for voice in get_voices("kokoro"):
             language_code = voice[0]  # First character is the language code
             matching_voice = next(
                 (item for item in initial_state if item[0] == voice), None
@@ -949,7 +948,9 @@ class VoiceFormulaDialog(QDialog):
         lang = state.get("language") if isinstance(state, dict) else None
         # apply language selection
         if lang:
-            i = self.language_combo.findData(lang)
+            from abogen.voice_profiles import resolve_profile_language
+
+            i = self.language_combo.findData(resolve_profile_language(state))
             if i >= 0:
                 self.language_combo.blockSignals(True)
                 self.language_combo.setCurrentIndex(i)
@@ -1571,9 +1572,10 @@ class VoiceFormulaDialog(QDialog):
             parent.selected_profile_name = None
             lang = self.language_combo.currentData()
             parent.selected_lang = lang
-            parent.subtitle_combo.setEnabled(
-                lang in SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION
-            )
+            if hasattr(parent, "update_subtitle_options_availability"):
+                parent.update_subtitle_options_availability()
+            else:
+                parent.subtitle_combo.setEnabled(True)
             # Reset start flag and trigger preview
             self._started = False
             parent.preview_voice()

abogen/shutdown.py

@@ -0,0 +1,162 @@
+"""Graceful shutdown — process-level hooks and orchestration.
+
+Responsibilities:
+- Install atexit/signal/Qt hooks
+- Stop WebUI ConversionService (worker thread)
+- Restore sleep prevention
+- Terminate child processes (ffmpeg, etc.)
+- Delegate GPU/engine/UI cleanup to application.cleanup
+
+App-layer cleanup (GPU, engines, UI callbacks) lives in application/cleanup.py.
+Per-conversion cleanup lives in run_conversion() finally block.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import signal
+import sys
+import time
+from typing import Callable
+
+_log = logging.getLogger("abogen.shutdown")
+
+_CLEANUP_FUNCS: list[Callable[[], None]] = []
+_EXECUTED = False
+
+
+def register_cleanup(fn: Callable[[], None]) -> None:
+    """Register a cleanup function to run on shutdown."""
+    _CLEANUP_FUNCS.append(fn)
+
+
+def _run_cleanups() -> None:
+    global _EXECUTED
+    if _EXECUTED:
+        return
+    _EXECUTED = True
+    _log.info("Shutdown: starting %d cleanup hook(s)", len(_CLEANUP_FUNCS))
+    for fn in _CLEANUP_FUNCS:
+        start = time.perf_counter()
+        try:
+            fn()
+        except Exception:
+            pass
+        _log.info(
+            "Shutdown: %s done in %.2fs", fn.__name__, time.perf_counter() - start
+        )
+    _log.info("Shutdown: all cleanups finished")
+
+
+# ---- Process-level cleanup functions ----
+
+
+def _stop_conversion_service() -> None:
+    """Stop WebUI ConversionService worker thread."""
+    try:
+        from abogen.webui.service import get_service
+        svc = get_service()
+        if svc is not None:
+            svc.shutdown()
+    except Exception:
+        pass
+
+
+def _restore_sleep() -> None:
+    """Restore system sleep prevention (caffeinate/systemd-inhibit/Windows)."""
+    try:
+        from abogen.utils import prevent_sleep_end
+        prevent_sleep_end()
+    except Exception:
+        pass
+
+
+def _terminate_subprocesses() -> None:
+    """Terminate all child processes (ffmpeg, etc.)."""
+    try:
+        import psutil
+    except Exception:
+        return
+
+    try:
+        current = psutil.Process()
+        for child in current.children(recursive=True):
+            try:
+                child.terminate()
+            except Exception:
+                pass
+        gone, alive = psutil.wait_procs(current.children(recursive=True), timeout=3)
+        for proc in alive:
+            try:
+                proc.kill()
+            except Exception:
+                pass
+    except Exception:
+        pass
+
+
+def _app_cleanup() -> None:
+    """Delegate to application-layer cleanup (engines, GPU, UI callbacks)."""
+    try:
+        from abogen.application.cleanup import cleanup
+        cleanup()
+    except Exception:
+        pass
+
+
+# Register in execution order
+register_cleanup(_stop_conversion_service)
+register_cleanup(_app_cleanup)
+register_cleanup(_restore_sleep)
+register_cleanup(_terminate_subprocesses)
+
+
+def register_shutdown() -> None:
+    """Install process-wide shutdown hooks (atexit, signals, Qt)."""
+    if register_shutdown._registered:
+        return
+    register_shutdown._registered = True
+
+    atexit.register(_run_cleanups)
+
+    # POSIX signals
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            signal.signal(sig, _on_signal)
+        except Exception:
+            pass
+
+    install_qt_hook()
+
+
+def install_qt_hook() -> None:
+    """Connect Qt aboutToQuit to cleanup. Must run AFTER QApplication is created."""
+    try:
+        from PyQt6.QtWidgets import QApplication
+
+        app = QApplication.instance()
+        if app is not None and not getattr(app, "_abogen_cleanup_connected", False):
+            app.aboutToQuit.connect(_run_cleanups)
+            app._abogen_cleanup_connected = True
+            _log.info("Shutdown: Qt aboutToQuit hook connected")
+    except Exception:
+        pass
+
+
+register_shutdown._registered = False
+
+
+def _on_signal(signum: int, _frame) -> None:
+    _log.info("Shutdown: signal %s received", signum)
+    _run_cleanups()
+    sys.exit(0)
+
+
+def request_shutdown() -> None:
+    """Programmatically trigger cleanup (e.g., from GUI closeEvent)."""
+    _log.info("Shutdown: cleanup requested")
+    _run_cleanups()
+
+
+__all__ = ["register_shutdown", "install_qt_hook", "request_shutdown", "register_cleanup"]

abogen/spacy_contraction_resolver.py

@@ -6,10 +6,9 @@ from dataclasses import dataclass
 from functools import lru_cache
 from typing import Any, Dict, Optional, Tuple
 
-try:  # pragma: no cover - optional dependency
-    import spacy
-except Exception:  # pragma: no cover - spaCy unavailable at runtime
-    spacy = None
+# spaCy is intentionally NOT imported at module level: importing it pulls in
+# thinc -> torch, which costs seconds of startup time. It is imported lazily
+# inside _load_spacy_model below.
 
 # Lazy spaCy type hints to avoid a hard dependency at import time.
 Language = Any  # type: ignore[assignment]
@@ -37,7 +36,9 @@ _DEFAULT_MODEL = os.environ.get("ABOGEN_SPACY_MODEL", "en_core_web_sm")
 
 @lru_cache(maxsize=1)
 def _load_spacy_model(model: str = _DEFAULT_MODEL) -> Optional[Language]:
-    if spacy is None:
+    try:  # pragma: no cover - optional dependency
+        import spacy
+    except Exception:  # pragma: no cover - spaCy unavailable at runtime
         logger.debug("spaCy is not installed; skipping contraction disambiguation")
         return None
 

abogen/spacy_utils.py

@@ -2,24 +2,25 @@
 Lazy-loaded spaCy utilities for sentence segmentation.
 """
 
+from abogen.domain.enums import Language
+
 # Cached spaCy module and models (lazy loaded)
 _spacy = None
 _nlp_cache = {}
 
 # Language code to spaCy model mapping
 SPACY_MODELS = {
-    "a": "en_core_web_sm",  # American English
-    "b": "en_core_web_sm",  # British English
-    "e": "es_core_news_sm",  # Spanish
-    "f": "fr_core_news_sm",  # French
-    "i": "it_core_news_sm",  # Italian
-    "p": "pt_core_news_sm",  # Brazilian Portuguese
-    "z": "zh_core_web_sm",  # Mandarin Chinese
-    "j": "ja_core_news_sm",  # Japanese
-    "h": "xx_sent_ud_sm",  # Hindi (multi-language model)
+    Language.EN_US: "en_core_web_sm",
+    Language.EN_GB: "en_core_web_sm",
+    Language.ES: "es_core_news_sm",
+    Language.FR: "fr_core_news_sm",
+    Language.IT: "it_core_news_sm",
+    Language.PT_BR: "pt_core_news_sm",
+    Language.ZH: "zh_core_web_sm",
+    Language.JA: "ja_core_news_sm",
+    Language.HI: "xx_sent_ud_sm",
 }
 
-
 def _load_spacy():
     """Lazy load spaCy module."""
     global _spacy
@@ -33,13 +34,12 @@ def _load_spacy():
     return _spacy
 
 
-def get_spacy_model(lang_code, log_callback=None):
+def get_spacy_model(language: Language, log_callback=None):
     """
-    Get or load a spaCy model for the given language code.
-    Downloads the model automatically if not available.
+    Get or load a spaCy model for the given language.
 
     Args:
-        lang_code: Language code (a, b, e, f, etc.)
+        language: Language enum value.
         log_callback: Optional function to log messages
 
     Returns:
@@ -47,25 +47,26 @@ def get_spacy_model(lang_code, log_callback=None):
     """
 
     def log(msg, is_error=False):
-        # Prefer GUI log callback when provided to avoid spamming stdout.
         if log_callback:
             color = "red" if is_error else "grey"
             try:
                 log_callback((msg, color))
             except Exception:
-                # Fallback to printing if callback misbehaves
                 print(msg)
         else:
             print(msg)
 
-    # Check if model is cached
-    if lang_code in _nlp_cache:
-        return _nlp_cache[lang_code]
+    if not isinstance(language, Language):
+        raise TypeError(
+            f"language must be Language enum, got {type(language).__name__}: {language!r}"
+        )
 
-    # Check if language is supported
-    model_name = SPACY_MODELS.get(lang_code)
+    if language in _nlp_cache:
+        return _nlp_cache[language]
+
+    model_name = SPACY_MODELS.get(language)
     if not model_name:
-        log(f"\nspaCy: No model mapping for language '{lang_code}'...")
+        log(f"\nspaCy: No model mapping for language '{language}'...")
         return None
 
     # Lazy load spaCy
@@ -89,7 +90,7 @@ def get_spacy_model(lang_code, log_callback=None):
         if "parser" not in nlp.pipe_names and "sentencizer" not in nlp.pipe_names:
             nlp.add_pipe("sentencizer")
 
-        _nlp_cache[lang_code] = nlp
+        _nlp_cache[language] = nlp
         return nlp
     except OSError:
         # Model not found, attempt download
@@ -106,7 +107,7 @@ def get_spacy_model(lang_code, log_callback=None):
             if "parser" not in nlp.pipe_names and "sentencizer" not in nlp.pipe_names:
                 nlp.add_pipe("sentencizer")
 
-            _nlp_cache[lang_code] = nlp
+            _nlp_cache[language] = nlp
             log(f"spaCy model '{model_name}' downloaded and loaded")
             return nlp
         except Exception as e:
@@ -120,19 +121,19 @@ def get_spacy_model(lang_code, log_callback=None):
         return None
 
 
-def segment_sentences(text, lang_code, log_callback=None):
+def segment_sentences(text, language: Language, log_callback=None):
     """
     Segment text into sentences using spaCy.
 
     Args:
         text: Text to segment
-        lang_code: Language code
+        language: Language enum value
         log_callback: Optional function to log messages
 
     Returns:
         List of sentence strings, or None if spaCy unavailable
     """
-    nlp = get_spacy_model(lang_code, log_callback)
+    nlp = get_spacy_model(language, log_callback)
     if nlp is None:
         return None
 

abogen/speaker_configs.py

@@ -4,7 +4,7 @@ import json
 import os
 from typing import Any, Dict, List, Optional
 
-from abogen.constants import LANGUAGE_DESCRIPTIONS
+from abogen.constants import KOKORO_CODE_LABELS
 from abogen.utils import get_user_config_path
 
 _CONFIG_WRAPPER_KEY = "abogen_speaker_configs"
@@ -163,4 +163,4 @@ def list_configs() -> List[Dict[str, Any]]:
 
 def describe_language(code: str) -> str:
     code = (code or "a").lower()
-    return LANGUAGE_DESCRIPTIONS.get(code, code.upper())
+    return KOKORO_CODE_LABELS.get(code, code.upper())

abogen/subtitle_utils.py

@@ -1,7 +1,7 @@
 import re
-import platform
 from abogen.utils import detect_encoding, load_config
 from abogen.constants import SAMPLE_VOICE_TEXTS
+from abogen.domain.enums import Language
 
 # Pre-compile frequently used regex patterns for better performance
 _METADATA_TAG_PATTERN = re.compile(r"<<METADATA_[^:]+:[^>]*>>")
@@ -23,13 +23,6 @@ _VTT_NOTE_PATTERN = re.compile(r"NOTE\s*\n.*?(?=\n\n|$)", re.DOTALL)
 _DOUBLE_NEWLINE_SPLIT_PATTERN = re.compile(r"\n\s*\n")
 _VTT_TIMESTAMP_PATTERN = re.compile(r"([\d:.]+)\s*-->\s*([\d:.]+)")
 _TIMESTAMP_ONLY_PATTERN = re.compile(r"^(\d{1,2}:\d{2}:\d{2}(?:[.,]\d{1,3})?)$")
-_WINDOWS_ILLEGAL_CHARS_PATTERN = re.compile(r'[<>:"/\\|?*]')
-_CONTROL_CHARS_PATTERN = re.compile(r"[\x00-\x1f]")
-_LINUX_CONTROL_CHARS_PATTERN = re.compile(
-    r"[\x01-\x1f]"
-)  # Linux: exclude \x00 for separate handling
-_MACOS_ILLEGAL_CHARS_PATTERN = re.compile(r"[:]")
-_LINUX_ILLEGAL_CHARS_PATTERN = re.compile(r"[/\x00]")
 
 
 def clean_subtitle_text(text):
@@ -41,17 +34,6 @@ def clean_subtitle_text(text):
     return text.strip()
 
 
-def calculate_text_length(text):
-    # Use pre-compiled patterns for better performance
-    # Ignore chapter markers, voice markers, and metadata patterns in a single pass
-    text = _CHAPTER_MARKER_PATTERN.sub("", text)
-    text = _VOICE_MARKER_PATTERN.sub("", text)
-    text = _METADATA_TAG_PATTERN.sub("", text)
-    # Ignore newlines and leading/trailing spaces
-    text = text.replace("\n", "").strip()
-    # Calculate character count
-    char_count = len(text)
-    return char_count
 
 
 def clean_text(text, *args, **kwargs):
@@ -396,189 +378,27 @@ def parse_ass_file(file_path):
     return subtitles
 
 
-def get_sample_voice_text(lang_code):
-    return SAMPLE_VOICE_TEXTS.get(lang_code, SAMPLE_VOICE_TEXTS["a"])
-
-
-def sanitize_name_for_os(name, is_folder=True):
-    """
-    Sanitize a filename or folder name based on the operating system.
+def get_sample_voice_text(language):
+    """Get sample voice text for a language.
 
     Args:
-        name: The name to sanitize
-        is_folder: Whether this is a folder name (default: True)
-
-    Returns:
-        Sanitized name safe for the current OS
+        language: Language enum value or string (for backward compatibility).
     """
-    if not name:
-        return "audiobook"
-
-    system = platform.system()
-
-    if system == "Windows":
-        # Windows illegal characters: < > : " / \ | ? *
-        # Also can't end with space or dot
-        # Use pre-compiled pattern for better performance
-        sanitized = _WINDOWS_ILLEGAL_CHARS_PATTERN.sub("_", name)
-        # Remove control characters (0-31)
-        sanitized = _CONTROL_CHARS_PATTERN.sub("_", sanitized)
-        # Remove trailing spaces and dots
-        sanitized = sanitized.rstrip(". ")
-        # Windows reserved names (CON, PRN, AUX, NUL, COM1-9, LPT1-9)
-        reserved = (
-            ["CON", "PRN", "AUX", "NUL"]
-            + [f"COM{i}" for i in range(1, 10)]
-            + [f"LPT{i}" for i in range(1, 10)]
-        )
-        if sanitized.upper() in reserved or sanitized.upper().split(".")[0] in reserved:
-            sanitized = f"_{sanitized}"
-    elif system == "Darwin":  # macOS
-        # macOS illegal characters: : (colon is converted to / by the system)
-        # Also can't start with dot (hidden file) for folders typically
-        # Use pre-compiled pattern for better performance
-        sanitized = _MACOS_ILLEGAL_CHARS_PATTERN.sub("_", name)
-        # Remove control characters
-        sanitized = _CONTROL_CHARS_PATTERN.sub("_", sanitized)
-        # Avoid leading dot for folders (creates hidden folders)
-        if is_folder and sanitized.startswith("."):
-            sanitized = "_" + sanitized[1:]
-    else:  # Linux and others
-        # Linux illegal characters: / and null character
-        # Though / is illegal, most other chars are technically allowed
-        # Use pre-compiled pattern for better performance
-        sanitized = _LINUX_ILLEGAL_CHARS_PATTERN.sub("_", name)
-        # Remove other control characters for safety (excluding \x00 which is already handled)
-        sanitized = _LINUX_CONTROL_CHARS_PATTERN.sub("_", sanitized)
-        # Avoid leading dot for folders (creates hidden folders)
-        if is_folder and sanitized.startswith("."):
-            sanitized = "_" + sanitized[1:]
-
-    # Ensure the name is not empty after sanitization
-    if not sanitized or sanitized.strip() == "":
-        sanitized = "audiobook"
-
-    # Limit length to 255 characters (common limit across filesystems)
-    if len(sanitized) > 255:
-        sanitized = sanitized[:255].rstrip(". ")
-
-    return sanitized
+    if isinstance(language, str):
+        try:
+            language = Language.from_str(language)
+        except (ValueError, AttributeError):
+            language = Language.EN_US
+    return SAMPLE_VOICE_TEXTS.get(language, SAMPLE_VOICE_TEXTS[Language.EN_US])
 
 
-def validate_voice_name(voice_name):
-    """Validate voice name against VOICES_INTERNAL list (case-insensitive).
-    Handles both single voices and formulas like 'af_heart*0.5 + am_echo*0.5'.
+# Backward-compatible re-exports — canonical location is domain/output_paths.py
+from abogen.domain.output_paths import sanitize_name_for_os  # noqa: E402, F401
 
-    Args:
-        voice_name: Voice name or formula string to validate
-
-    Returns:
-        Tuple of (is_valid, invalid_voice_name):
-            - is_valid: True if all voices in the name/formula are valid
-            - invalid_voice_name: The first invalid voice found, or None if all valid
-    """
-    from abogen.constants import VOICES_INTERNAL
-
-    # Create case-insensitive lookup set (done once per call)
-    voice_lookup_lower = {v.lower() for v in VOICES_INTERNAL}
-    voice_name = voice_name.strip()
-
-    # Check if it's a formula (contains *)
-    if "*" in voice_name:
-        # Extract voice names from formula
-        voices = voice_name.split("+")
-        for term in voices:
-            if "*" in term:
-                base_voice = term.split("*")[0].strip()
-                # Case-insensitive comparison
-                if base_voice.lower() not in voice_lookup_lower:
-                    return False, base_voice
-        return True, None
-    else:
-        # Single voice - case-insensitive comparison
-        if voice_name.lower() not in voice_lookup_lower:
-            return False, voice_name
-        return True, None
-
-
-def split_text_by_voice_markers(text, default_voice):
-    """Split text by voice markers, returning list of (voice, text) tuples.
-
-    IMPORTANT: Returns the last voice used so it can persist across chapters.
-    Voice names are normalized to lowercase to match VOICES_INTERNAL.
-
-    Args:
-        text: Text potentially containing <<VOICE:name>> markers
-        default_voice: Voice to use if no markers found or before first marker
-
-    Returns:
-        Tuple of (segments_list, last_voice_used, valid_count, invalid_count):
-            - segments_list: List of (voice_name, segment_text) tuples
-            - last_voice_used: The voice that should continue into next chapter
-            - valid_count: Number of valid voice markers processed
-            - invalid_count: Number of invalid voice markers skipped
-    """
-    from abogen.constants import VOICES_INTERNAL
-
-    voice_splits = list(_VOICE_MARKER_SEARCH_PATTERN.finditer(text))
-
-    if not voice_splits:
-        # No voice markers, return entire text with default voice
-        return [(default_voice, text)], default_voice, 0, 0
-
-    segments = []
-    current_voice = default_voice
-    valid_markers = 0
-    invalid_markers = 0
-
-    # Text before first marker uses default voice
-    first_start = voice_splits[0].start()
-    if first_start > 0:
-        intro_text = text[:first_start].strip()
-        if intro_text:
-            segments.append((current_voice, intro_text))
-
-    # Process each voice marker
-    for idx, match in enumerate(voice_splits):
-        voice_name = match.group(1).strip()
-        start = match.end()
-        end = voice_splits[idx + 1].start() if idx + 1 < len(voice_splits) else len(text)
-        segment_text = text[start:end].strip()
-
-        # Validate voice name
-        is_valid, invalid_voice = validate_voice_name(voice_name)
-        if is_valid:
-            # Normalize to lowercase to match canonical form
-            # Handle both single voices and formulas
-            if "*" in voice_name:
-                # Normalize each voice in the formula
-                normalized_parts = []
-                for part in voice_name.split("+"):
-                    part = part.strip()
-                    if "*" in part:
-                        voice_part, weight = part.split("*", 1)
-                        # Find the canonical (lowercase) voice name
-                        voice_part_lower = voice_part.strip().lower()
-                        canonical_voice = next(
-                            (v for v in VOICES_INTERNAL if v.lower() == voice_part_lower),
-                            voice_part.strip()
-                        )
-                        normalized_parts.append(f"{canonical_voice}*{weight.strip()}")
-                current_voice = " + ".join(normalized_parts)
-            else:
-                # Find the canonical (lowercase) voice name
-                voice_name_lower = voice_name.lower()
-                current_voice = next(
-                    (v for v in VOICES_INTERNAL if v.lower() == voice_name_lower),
-                    voice_name
-                )
-            valid_markers += 1
-        else:
-            # Invalid voice - stay with previous voice
-            invalid_markers += 1
-
-        if segment_text:
-            segments.append((current_voice, segment_text))
-
-    # Return segments, last voice, and counts
-    return segments, current_voice, valid_markers, invalid_markers
+# Backward-compatible re-exports — canonical location is domain/voice_markers.py
+from abogen.domain.voice_markers import (  # noqa: E402, F401
+    validate_voice_name,
+    split_text_by_voice_markers,
+    _VOICE_MARKER_PATTERN,
+    _VOICE_MARKER_SEARCH_PATTERN,
+)

abogen/text_extractor.py

@@ -16,7 +16,8 @@ import markdown  # type: ignore[import]
 from bs4 import BeautifulSoup, NavigableString  # type: ignore[import]
 from ebooklib import epub  # type: ignore[import]
 
-from .utils import calculate_text_length, clean_text, detect_encoding
+from .utils import clean_text, detect_encoding
+from .domain.text_utils import calculate_text_length
 
 logger = logging.getLogger(__name__)
 

abogen/tts_plugin/__init__.py

@@ -0,0 +1,170 @@
+"""TTS Plugin Architecture - Public API.
+
+This package defines the frozen Plugin API for the TTS Plugin Architecture.
+All public interfaces are fully defined but contain no business logic.
+
+Public modules:
+- types: Core domain value objects (AudioFormat, Duration, VoiceSelection, etc.)
+- errors: Error hierarchy (EngineError and subtypes)
+- manifest: Plugin manifest types (PluginManifest, EngineManifest, etc.)
+- engine: Engine and EngineSession protocols
+- capabilities: Optional capability interfaces (VoiceLister, PreviewGenerator, etc.)
+- host_context: HostContext dataclass
+- plugin: Plugin contract (create_engine function signature)
+- loader: Plugin discovery and loading
+- plugin_manager: Plugin management and engine creation
+- utils: Direct utility functions (get_voices, create_pipeline, etc.)
+
+Usage:
+    from abogen.tts_plugin import (
+        # Types
+        AudioFormat,
+        Duration,
+        VoiceSelection,
+        ParameterValues,
+        SynthesisRequest,
+        SynthesizedAudio,
+        EngineConfig,
+        # Errors
+        EngineError,
+        ModelNotFoundError,
+        ModelLoadError,
+        NetworkError,
+        InvalidInputError,
+        ConfigurationError,
+        CancelledError,
+        InternalError,
+        # Manifest
+        PluginManifest,
+        EngineManifest,
+        VoiceSourceManifest,
+        VoiceManifest,
+        ParameterManifest,
+        AudioFormatManifest,
+        EnumOption,
+        RequirementManifest,
+        GpuRequirement,
+        ModelManifest,
+        # Engine
+        Engine,
+        EngineSession,
+        # Capabilities
+        VoiceLister,
+        PreviewGenerator,
+        StreamingSynthesizer,
+        CancelableSession,
+        # Host Context
+        HostContext,
+        HttpClient,
+        # Plugin Manager
+        get_plugin_manager,
+        reset_plugin_manager,
+        # Utils
+        get_voices,
+        get_default_voice,
+        is_plugin_registered,
+        resolve_voice_to_plugin,
+        create_pipeline,
+    )
+"""
+
+from abogen.tts_plugin.capabilities import (
+    CancelableSession,
+    PreviewGenerator,
+    StreamingSynthesizer,
+    VoiceLister,
+)
+from abogen.tts_plugin.engine import Engine, EngineSession
+from abogen.tts_plugin.errors import (
+    CancelledError,
+    ConfigurationError,
+    EngineError,
+    InternalError,
+    InvalidInputError,
+    ModelLoadError,
+    ModelNotFoundError,
+    NetworkError,
+)
+from abogen.tts_plugin.host_context import HttpClient, HostContext
+from abogen.tts_plugin.manifest import (
+    AudioFormatManifest,
+    EngineManifest,
+    EnumOption,
+    GpuRequirement,
+    ModelManifest,
+    ParameterManifest,
+    PluginManifest,
+    RequirementManifest,
+    VoiceManifest,
+    VoiceSourceManifest,
+)
+from abogen.tts_plugin.types import (
+    AudioFormat,
+    Duration,
+    EngineConfig,
+    ParameterValues,
+    SynthesisRequest,
+    SynthesizedAudio,
+    VoiceSelection,
+)
+
+# Plugin Manager and Utils
+from abogen.tts_plugin.plugin_manager import get_plugin_manager, reset_plugin_manager
+from abogen.tts_plugin.utils import (
+    create_pipeline,
+    get_default_voice,
+    get_voices,
+    is_plugin_registered,
+    resolve_voice_to_plugin,
+)
+
+__all__ = [
+    # Types
+    "AudioFormat",
+    "Duration",
+    "VoiceSelection",
+    "ParameterValues",
+    "SynthesisRequest",
+    "SynthesizedAudio",
+    "EngineConfig",
+    # Errors
+    "EngineError",
+    "ModelNotFoundError",
+    "ModelLoadError",
+    "NetworkError",
+    "InvalidInputError",
+    "ConfigurationError",
+    "CancelledError",
+    "InternalError",
+    # Manifest
+    "PluginManifest",
+    "EngineManifest",
+    "VoiceSourceManifest",
+    "VoiceManifest",
+    "ParameterManifest",
+    "AudioFormatManifest",
+    "EnumOption",
+    "RequirementManifest",
+    "GpuRequirement",
+    "ModelManifest",
+    # Engine
+    "Engine",
+    "EngineSession",
+    # Capabilities
+    "VoiceLister",
+    "PreviewGenerator",
+    "StreamingSynthesizer",
+    "CancelableSession",
+    # Host Context
+    "HostContext",
+    "HttpClient",
+    # Plugin Manager
+    "get_plugin_manager",
+    "reset_plugin_manager",
+    # Utils
+    "get_voices",
+    "get_default_voice",
+    "is_plugin_registered",
+    "resolve_voice_to_plugin",
+    "create_pipeline",
+]

abogen/tts_plugin/capabilities.py

@@ -0,0 +1,103 @@
+"""Capability interfaces for the TTS Plugin Architecture.
+
+This module defines optional capability interfaces that engines can implement.
+Capabilities are additive; implementing new capabilities doesn't break old plugins.
+"""
+
+from __future__ import annotations
+
+from typing import Iterator, Protocol, runtime_checkable
+
+from abogen.tts_plugin.manifest import VoiceManifest
+from abogen.tts_plugin.types import SynthesisRequest, SynthesizedAudio, VoiceSelection
+
+
+@runtime_checkable
+class VoiceLister(Protocol):
+    """Protocol for listing available voices.
+
+    Engines that support voice listing should implement this interface.
+    """
+
+    def listVoices(self, sourceId: str) -> list[VoiceManifest]:
+        """List available voices for a given source.
+
+        Args:
+            sourceId: The voice source identifier.
+
+        Returns:
+            List of VoiceManifest describing available voices.
+
+        Raises:
+            EngineError: On failure.
+        """
+        ...
+
+
+@runtime_checkable
+class PreviewGenerator(Protocol):
+    """Protocol for generating voice previews.
+
+    Engines that support voice preview should implement this interface.
+    """
+
+    def generatePreview(self, voice: VoiceSelection, text: str) -> SynthesizedAudio:
+        """Generate a preview audio for a voice.
+
+        Args:
+            voice: Voice selection for the preview.
+            text: Text to use for the preview.
+
+        Returns:
+            SynthesizedAudio with the preview audio data.
+
+        Raises:
+            EngineError: On failure.
+        """
+        ...
+
+
+@runtime_checkable
+class StreamingSynthesizer(Protocol):
+    """Protocol for streaming synthesis.
+
+    Optional capability of EngineSession, not Engine.
+    Engines that support streaming synthesis should implement this interface.
+    """
+
+    def synthesizeStream(self, request: SynthesisRequest) -> Iterator[bytes]:
+        """Synthesize audio in streaming mode.
+
+        Args:
+            request: The synthesis request.
+
+        Yields:
+            Audio chunks as they become available.
+
+        Raises:
+            CancelledError: If cancel() is called during iteration.
+            EngineError: On synthesis failure.
+        """
+        ...
+        # This is a generator function; implementation will use yield
+        yield b""  # pragma: no cover
+
+
+@runtime_checkable
+class CancelableSession(Protocol):
+    """Protocol for cancellation support.
+
+    Optional capability for engines that support cancellation.
+    cancel() causes synthesize() to raise CancelledError.
+    """
+
+    def cancel(self) -> None:
+        """Cancel in-progress synthesis.
+
+        After cancellation, synthesize() raises CancelledError.
+        The session remains usable after cancellation.
+
+        Raises:
+            EngineError: If called after dispose().
+        """
+        ...

abogen/tts_plugin/engine.py

@@ -0,0 +1,95 @@
+"""Engine interfaces for the TTS Plugin Architecture.
+
+This module defines the core Engine and EngineSession protocols.
+These are the primary interfaces that plugin implementations must satisfy.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from abogen.tts_plugin.types import SynthesisRequest, SynthesizedAudio
+
+
+@runtime_checkable
+class EngineSession(Protocol):
+    """Protocol for a session that owns mutable execution state.
+
+    An EngineSession is created by Engine.createSession() and owns
+    mutable execution state isolated from other concurrent work.
+    It is NOT thread-safe.
+
+    Lifecycle:
+        1. Created by Engine.createSession()
+        2. Used for synthesis via synthesize()
+        3. Disposed via dispose()
+
+    After dispose(), all methods except dispose() raise EngineError.
+    """
+
+    def synthesize(self, request: SynthesisRequest) -> SynthesizedAudio:
+        """Synthesize audio from text.
+
+        Args:
+            request: The synthesis request containing text, voice, parameters, and format.
+
+        Returns:
+            SynthesizedAudio with the synthesized audio data.
+
+        Raises:
+            EngineError: On synthesis failure. Session remains usable after error.
+            EngineError: If called after dispose().
+        """
+        ...
+
+    def dispose(self) -> None:
+        """Release session resources.
+
+        This method is idempotent and safe to call multiple times.
+        It never raises exceptions (catches and logs internally).
+        After dispose(), all methods except dispose() raise EngineError.
+        """
+        ...
+
+
+@runtime_checkable
+class Engine(Protocol):
+    """Protocol for a TTS engine that creates sessions.
+
+    An Engine is a factory for EngineSession instances. It is stateless
+    and thread-safe for createSession().
+
+    Lifecycle:
+        1. Created via create_engine() (plugin contract)
+        2. Sessions created via createSession()
+        3. Disposed via dispose()
+
+    Thread Safety:
+        - createSession() is thread-safe and can be called from any thread.
+        - dispose() must be called after all sessions are disposed.
+        - Disposing engine while sessions are alive violates API contract.
+    """
+
+    def createSession(self) -> EngineSession:
+        """Create a new session for synthesis.
+
+        Returns:
+            A new EngineSession instance. Ownership transfers to caller.
+
+        Raises:
+            EngineError: On failure. No partially initialized session is returned.
+        """
+        ...
+
+    def dispose(self) -> None:
+        """Release engine resources.
+
+        Caller must ensure all sessions created by this engine are disposed
+        before calling dispose(). Disposing an engine while any session is
+        still alive violates the API contract; behavior is undefined.
+
+        This method is idempotent and safe to call multiple times.
+        It never raises exceptions (catches and logs internally).
+        After dispose(), all methods except dispose() raise EngineError.
+        """
+        ...

abogen/tts_plugin/errors.py

@@ -0,0 +1,62 @@
+"""Error hierarchy for the TTS Plugin Architecture.
+
+This module defines typed exceptions that engines raise.
+Engines should never raise raw exceptions; they must use EngineError or its subtypes.
+"""
+
+from __future__ import annotations
+
+
+class EngineError(Exception):
+    """Base exception for all engine errors.
+
+    All engine operations that can fail should raise EngineError or one of its subtypes.
+    After dispose(), all methods except dispose() raise EngineError.
+    """
+
+    pass
+
+
+class ModelNotFoundError(EngineError):
+    """Raised when a required model is not found."""
+
+    pass
+
+
+class ModelLoadError(EngineError):
+    """Raised when a model fails to load."""
+
+    pass
+
+
+class NetworkError(EngineError):
+    """Raised when a network operation fails."""
+
+    pass
+
+
+class InvalidInputError(EngineError):
+    """Raised when invalid input is provided to the engine."""
+
+    pass
+
+
+class ConfigurationError(EngineError):
+    """Raised when there is a configuration error."""
+
+    pass
+
+
+class CancelledError(EngineError):
+    """Raised when an operation is cancelled.
+
+    This is raised by synthesize() when cancel() is called during synthesis.
+    """
+
+    pass
+
+
+class InternalError(EngineError):
+    """Raised when an internal engine error occurs."""
+
+    pass

abogen/tts_plugin/host_context.py

@@ -0,0 +1,46 @@
+"""Host context for the TTS Plugin Architecture.
+
+This module defines the HostContext dataclass that provides minimal
+host services to plugins. It is the only interface through which
+plugins can access host functionality.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class HttpClient(Protocol):
+    """Protocol for HTTP client provided by host.
+
+    Plugins can use this for network requests (e.g., API-based engines).
+    """
+
+    def get(self, url: str, **kwargs: object) -> object:
+        """Perform an HTTP GET request."""
+        ...
+
+    def post(self, url: str, **kwargs: object) -> object:
+        """Perform an HTTP POST request."""
+        ...
+
+
+@dataclass(frozen=True)
+class HostContext:
+    """Minimal host context provided to plugins.
+
+    Contains only essential host services. No business logic.
+
+    Attributes:
+        config_dir: Directory for API keys, preferences, and configuration.
+        logger: Logger for plugin logging.
+        http_client: HTTP client for network requests.
+    """
+
+    config_dir: Path
+    logger: logging.Logger
+    http_client: HttpClient

abogen/tts_plugin/loader.py

@@ -0,0 +1,365 @@
+"""Plugin loader infrastructure for the TTS Plugin Architecture.
+
+This module provides functionality to discover, import, validate, and load
+TTS plugins. It handles both valid and invalid plugins, providing diagnostic
+messages for errors.
+
+The loader does NOT:
+- Create Engine instances (that's the plugin's create_engine() responsibility)
+- Manage plugin lifecycle (that's the Plugin Manager's responsibility)
+- Implement any TTS engine functionality
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import sys
+import types
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+from abogen.tts_plugin.manifest import ModelManifest, PluginManifest
+
+
+# Host API version for compatibility checking
+HOST_API_VERSION = "1.0"
+
+
+@dataclass(frozen=True)
+class PluginLoadError:
+    """Diagnostic information for a failed plugin load.
+
+    Attributes:
+        plugin_id: Plugin identifier if available, otherwise directory name.
+        path: Path to the plugin directory.
+        errors: List of error messages describing what went wrong.
+    """
+
+    plugin_id: str
+    path: Path
+    errors: tuple[str, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class PluginLoadResult:
+    """Result of loading a plugin.
+
+    Attributes:
+        success: Whether the plugin loaded successfully.
+        manifest: The plugin manifest if successful.
+        model_requirements: Model requirements if successful.
+        create_engine: The create_engine function if successful.
+        module: The plugin module if successful.
+        error: Error information if failed.
+    """
+
+    success: bool
+    manifest: PluginManifest | None = None
+    model_requirements: tuple[ModelManifest, ...] | None = None
+    create_engine: Callable[..., Any] | None = None
+    module: types.ModuleType | None = None
+    error: PluginLoadError | None = None
+
+
+def _parse_api_version(version: str) -> tuple[int, int] | None:
+    """Parse an api_version string into (major, minor) tuple.
+
+    Args:
+        version: Version string in format "MAJOR.MINOR".
+
+    Returns:
+        Tuple of (major, minor) or None if invalid format.
+    """
+    match = re.match(r"^(\d+)\.(\d+)$", version)
+    if match:
+        return int(match.group(1)), int(match.group(2))
+    return None
+
+
+def _check_api_version_compatibility(plugin_version: str) -> str | None:
+    """Check if plugin api_version is compatible with host.
+
+    Architecture spec:
+    - Format: semver (MAJOR.MINOR)
+    - Compatibility: Host rejects plugin if major version differs
+    - Minor version: backward compatible, Host accepts higher minor
+
+    Args:
+        plugin_version: Plugin's api_version string.
+
+    Returns:
+        Error message if incompatible, None if compatible.
+    """
+    plugin_ver = _parse_api_version(plugin_version)
+    if plugin_ver is None:
+        return f"Invalid api_version format: '{plugin_version}'. Expected format: MAJOR.MINOR"
+
+    host_ver = _parse_api_version(HOST_API_VERSION)
+    if host_ver is None:
+        return f"Invalid host api_version format: '{HOST_API_VERSION}'"
+
+    if plugin_ver[0] != host_ver[0]:
+        return (
+            f"api_version major mismatch: plugin={plugin_ver[0]}, host={host_ver[0]}. "
+            f"Major version must match for compatibility."
+        )
+
+    return None
+
+
+def _validate_manifest(module: types.ModuleType, plugin_dir: Path) -> list[str]:
+    """Validate that a plugin module has required exports.
+
+    Args:
+        module: The imported plugin module.
+        plugin_dir: Path to the plugin directory.
+
+    Returns:
+        List of error messages (empty if valid).
+    """
+    errors: list[str] = []
+
+    # Check PLUGIN_MANIFEST
+    manifest = getattr(module, "PLUGIN_MANIFEST", None)
+    if manifest is None:
+        errors.append("Missing PLUGIN_MANIFEST export")
+    elif not isinstance(manifest, PluginManifest):
+        errors.append(
+            f"PLUGIN_MANIFEST must be a PluginManifest instance, "
+            f"got {type(manifest).__name__}"
+        )
+
+    # Check MODEL_REQUIREMENTS
+    model_reqs = getattr(module, "MODEL_REQUIREMENTS", None)
+    if model_reqs is None:
+        errors.append("Missing MODEL_REQUIREMENTS export")
+    elif not isinstance(model_reqs, list):
+        errors.append(
+            f"MODEL_REQUIREMENTS must be a list, got {type(model_reqs).__name__}"
+        )
+    else:
+        for i, req in enumerate(model_reqs):
+            if not isinstance(req, ModelManifest):
+                errors.append(
+                    f"MODEL_REQUIREMENTS[{i}] must be a ModelManifest instance, "
+                    f"got {type(req).__name__}"
+                )
+
+    # Check create_engine
+    create_engine = getattr(module, "create_engine", None)
+    if create_engine is None:
+        errors.append("Missing create_engine export")
+    elif not callable(create_engine):
+        errors.append(
+            f"create_engine must be callable, got {type(create_engine).__name__}"
+        )
+
+    return errors
+
+
+def _validate_capabilities(manifest: PluginManifest) -> list[str]:
+    """Validate plugin capabilities.
+
+    Args:
+        manifest: The plugin manifest to validate.
+
+    Returns:
+        List of error messages (empty if valid).
+    """
+    errors: list[str] = []
+
+    # Known capabilities (can be extended)
+    known_capabilities = frozenset({
+        "voice_list",
+        "preview",
+        "voice_clone",
+        "voice_blend",
+        "streaming",
+        "cancel",
+    })
+
+    for cap in manifest.capabilities:
+        if cap not in known_capabilities:
+            errors.append(f"Unknown capability: '{cap}'")
+
+    return errors
+
+
+def _validate_api_version(manifest: PluginManifest) -> list[str]:
+    """Validate api_version compatibility.
+
+    Args:
+        manifest: The plugin manifest to validate.
+
+    Returns:
+        List of error messages (empty if valid).
+    """
+    errors: list[str] = []
+    error = _check_api_version_compatibility(manifest.api_version)
+    if error:
+        errors.append(error)
+    return errors
+
+
+def load_plugin_from_dir(plugin_dir: Path) -> PluginLoadResult:
+    """Load and validate a plugin from a directory.
+
+    The plugin directory must contain an __init__.py that exports:
+    - PLUGIN_MANIFEST: PluginManifest
+    - MODEL_REQUIREMENTS: list[ModelManifest]
+    - create_engine: Callable
+
+    Args:
+        plugin_dir: Path to the plugin directory.
+
+    Returns:
+        PluginLoadResult with success status and either plugin data or error info.
+    """
+    plugin_id = plugin_dir.name
+    errors: list[str] = []
+
+    # Check if directory exists
+    if not plugin_dir.exists():
+        return PluginLoadResult(
+            success=False,
+            error=PluginLoadError(
+                plugin_id=plugin_id,
+                path=plugin_dir,
+                errors=(f"Plugin directory does not exist: {plugin_dir}",),
+            ),
+        )
+
+    # Check for __init__.py
+    init_file = plugin_dir / "__init__.py"
+    if not init_file.exists():
+        return PluginLoadResult(
+            success=False,
+            error=PluginLoadError(
+                plugin_id=plugin_id,
+                path=plugin_dir,
+                errors=("Missing __init__.py in plugin directory",),
+            ),
+        )
+
+    # Import the module
+    module_name = f"abogen.tts_plugin._loaded.{plugin_id}"
+    try:
+        # Remove from cache if already imported (for testing)
+        if module_name in sys.modules:
+            del sys.modules[module_name]
+
+        spec = importlib.util.spec_from_file_location(
+            module_name, init_file, submodule_search_locations=[]
+        )
+        if spec is None or spec.loader is None:
+            return PluginLoadResult(
+                success=False,
+                error=PluginLoadError(
+                    plugin_id=plugin_id,
+                    path=plugin_dir,
+                    errors=(f"Failed to create module spec for {init_file}",),
+                ),
+            )
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+    except Exception as e:
+        # Clean up module from sys.modules on import failure
+        if module_name in sys.modules:
+            del sys.modules[module_name]
+        return PluginLoadResult(
+            success=False,
+            error=PluginLoadError(
+                plugin_id=plugin_id,
+                path=plugin_dir,
+                errors=(f"Failed to import plugin module: {e}",),
+            ),
+        )
+
+    # Validate manifest
+    manifest_errors = _validate_manifest(module, plugin_dir)
+    errors.extend(manifest_errors)
+
+    # If manifest is valid, perform additional validation
+    manifest = getattr(module, "PLUGIN_MANIFEST", None)
+    if isinstance(manifest, PluginManifest):
+        # Validate api_version
+        api_errors = _validate_api_version(manifest)
+        errors.extend(api_errors)
+
+        # Validate capabilities
+        cap_errors = _validate_capabilities(manifest)
+        errors.extend(cap_errors)
+
+        # Use manifest id if available
+        plugin_id = manifest.id
+
+    # Check if any errors occurred
+    if errors:
+        # Clean up module from sys.modules
+        if module_name in sys.modules:
+            del sys.modules[module_name]
+
+        return PluginLoadResult(
+            success=False,
+            error=PluginLoadError(
+                plugin_id=plugin_id,
+                path=plugin_dir,
+                errors=tuple(errors),
+            ),
+        )
+
+    # Get MODEL_REQUIREMENTS
+    model_requirements = tuple(getattr(module, "MODEL_REQUIREMENTS", []))
+    create_engine = getattr(module, "create_engine", None)
+
+    return PluginLoadResult(
+        success=True,
+        manifest=manifest,
+        model_requirements=model_requirements,
+        create_engine=create_engine,
+        module=module,
+    )
+
+
+def discover_plugins(plugin_dirs: list[Path]) -> list[PluginLoadResult]:
+    """Discover and load plugins from multiple directories.
+
+    Args:
+        plugin_dirs: List of directories to scan for plugins.
+
+    Returns:
+        List of PluginLoadResult, one per plugin directory found.
+    """
+    results: list[PluginLoadResult] = []
+
+    for plugin_dir in plugin_dirs:
+        if not plugin_dir.exists():
+            continue
+
+        # Scan for subdirectories (each is a potential plugin)
+        for item in sorted(plugin_dir.iterdir()):
+            if item.is_dir() and not item.name.startswith("."):
+                result = load_plugin_from_dir(item)
+                results.append(result)
+
+    return results
+
+
+def load_plugin(
+    plugin_dir: Path,
+) -> PluginLoadResult:
+    """Load a single plugin from a directory.
+
+    This is the main entry point for loading a plugin.
+
+    Args:
+        plugin_dir: Path to the plugin directory.
+
+    Returns:
+        PluginLoadResult with success status and either plugin data or error info.
+    """
+    return load_plugin_from_dir(plugin_dir)

abogen/tts_plugin/manifest.py

@@ -0,0 +1,189 @@
+"""Plugin manifest types for the TTS Plugin Architecture.
+
+This module contains static metadata types that describe plugins.
+These types have no dependencies and are immutable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AudioFormatManifest:
+    """Manifest describing an audio format.
+
+    Attributes:
+        mime: MIME type of the audio.
+        extension: File extension.
+    """
+
+    mime: str
+    extension: str
+
+
+@dataclass(frozen=True)
+class EnumOption:
+    """Manifest describing an enum option for a parameter.
+
+    Attributes:
+        value: The enum value.
+        label: Human-readable label.
+    """
+
+    value: str
+    label: str
+
+
+@dataclass(frozen=True)
+class ParameterManifest:
+    """Manifest describing a synthesis parameter.
+
+    Attributes:
+        id: Parameter identifier.
+        name: Human-readable name.
+        description: Parameter description.
+        type: Parameter type ("float", "int", "string", "boolean", "enum").
+        default: Default value.
+        min: Minimum value (optional, for numeric types).
+        max: Maximum value (optional, for numeric types).
+        step: Step size (optional, for numeric types).
+        options: Available options (optional, for enum type).
+        unit: Unit of measurement (optional).
+        group: Parameter group (optional).
+    """
+
+    id: str
+    name: str
+    description: str
+    type: str
+    default: Any
+    min: float | None = None
+    max: float | None = None
+    step: float | None = None
+    options: tuple[EnumOption, ...] = field(default_factory=tuple)
+    unit: str | None = None
+    group: str | None = None
+
+
+@dataclass(frozen=True)
+class VoiceManifest:
+    """Manifest describing a voice.
+
+    Attributes:
+        id: Voice identifier.
+        name: Human-readable name.
+        tags: Voice tags (e.g., language, style).
+    """
+
+    id: str
+    name: str
+    tags: tuple[str, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class VoiceSourceManifest:
+    """Manifest describing a voice source.
+
+    Attributes:
+        id: Voice source identifier.
+        name: Human-readable name.
+        type: Source type ("list", "speaker_id", "clone", "blend", "generate", "none").
+        config: Source-specific configuration.
+    """
+
+    id: str
+    name: str
+    type: str
+    config: Any = None
+
+
+@dataclass(frozen=True)
+class EngineManifest:
+    """Manifest describing engine capabilities.
+
+    Attributes:
+        voiceSources: Available voice sources.
+        parameters: Available synthesis parameters.
+        audioFormats: Supported audio formats.
+    """
+
+    voiceSources: tuple[VoiceSourceManifest, ...] = field(default_factory=tuple)
+    parameters: tuple[ParameterManifest, ...] = field(default_factory=tuple)
+    audioFormats: tuple[AudioFormatManifest, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class GpuRequirement:
+    """Manifest describing GPU requirements.
+
+    Attributes:
+        required: Whether GPU is required.
+        type: GPU type (e.g., "cuda", "rocm").
+        memory: Required GPU memory in GB.
+    """
+
+    required: bool = False
+    type: str | None = None
+    memory: float | None = None
+
+
+@dataclass(frozen=True)
+class RequirementManifest:
+    """Manifest describing plugin requirements.
+
+    Attributes:
+        gpu: GPU requirements (optional).
+        memory: Required RAM in GB (optional).
+        internet: Whether internet is required (optional).
+    """
+
+    gpu: GpuRequirement | None = None
+    memory: float | None = None
+    internet: bool | None = None
+
+
+@dataclass(frozen=True)
+class ModelManifest:
+    """Manifest describing a model requirement.
+
+    Attributes:
+        id: Model identifier.
+        name: Human-readable name.
+        size: Model size as string (e.g., "100MB", "2GB").
+    """
+
+    id: str
+    name: str
+    size: str
+
+
+@dataclass(frozen=True)
+class PluginManifest:
+    """Main manifest for a TTS plugin.
+
+    Attributes:
+        id: Plugin identifier (unique).
+        name: Human-readable name.
+        version: Plugin version.
+        api_version: API version (semver format: MAJOR.MINOR).
+        description: Plugin description.
+        author: Plugin author.
+        capabilities: List of capability identifiers.
+        requires: Plugin requirements.
+        engine: Engine manifest.
+        voices: Optional static voice catalog. None = not declared (use VoiceLister),
+            empty tuple = explicitly no static voices, non-empty = static catalog.
+    """
+
+    id: str
+    name: str
+    version: str
+    api_version: str
+    description: str
+    author: str
+    capabilities: tuple[str, ...] = field(default_factory=tuple)
+    requires: RequirementManifest = field(default_factory=RequirementManifest)
+    engine: EngineManifest = field(default_factory=EngineManifest)
+    voices: tuple[VoiceManifest, ...] | None = None

abogen/tts_plugin/plugin.py

@@ -0,0 +1,55 @@
+"""Plugin contract for the TTS Plugin Architecture.
+
+This module defines the plugin contract that all TTS plugins must implement.
+Each plugin must export:
+- PLUGIN_MANIFEST: PluginManifest instance
+- MODEL_REQUIREMENTS: list of ModelManifest instances
+- create_engine(): Factory function that creates an Engine
+
+The create_engine() function is the entry point for plugin activation.
+It must be atomic: succeed fully or raise and clean up.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from abogen.tts_plugin.engine import Engine
+from abogen.tts_plugin.host_context import HostContext
+from abogen.tts_plugin.types import EngineConfig
+
+
+@runtime_checkable
+class Plugin(Protocol):
+    """Protocol defining the plugin contract.
+
+    Every TTS plugin must implement this protocol by exporting:
+    - PLUGIN_MANIFEST: PluginManifest
+    - MODEL_REQUIREMENTS: list[ModelManifest]
+    - create_engine: Callable[[HostContext, Path | None, EngineConfig], Engine]
+    """
+
+    def create_engine(
+        self,
+        context: HostContext,
+        model_path: Path | None,
+        config: EngineConfig,
+    ) -> Engine:
+        """Create an engine instance.
+
+        This is the factory function that creates an Engine from a plugin.
+        It must be atomic: succeed fully or raise EngineError and clean up.
+
+        Args:
+            context: Host services (config dir, logger, http client).
+            model_path: Resolved model path, or None for cloud/no-model engines.
+            config: Engine initialization settings.
+
+        Returns:
+            A fully initialized Engine instance.
+
+        Raises:
+            EngineError: On failure. Cleans up partially created resources.
+        """
+        ...

abogen/tts_plugin/plugin_manager.py

@@ -0,0 +1,156 @@
+"""Plugin Manager
+
+Provides a simple interface for consumers to access TTS engines via the
+new Plugin Architecture. Discovers, loads, and manages plugins from the
+plugins directory.
+
+Usage:
+    from abogen.tts_plugin.plugin_manager import get_plugin_manager
+
+    manager = get_plugin_manager()
+    engine = manager.create_engine("kokoro", language=Language.EN_US, device="cpu")
+    session = engine.create_session()
+    try:
+        result = session.synthesize("Hello world")
+    finally:
+        session.dispose()
+"""
+
+from typing import Any, Dict, List, Optional, Type
+
+from abogen.tts_plugin.engine import Engine, EngineSession
+from abogen.tts_plugin.manifest import PluginManifest
+from abogen.tts_plugin.types import AudioFormat
+
+
+class PluginManager:
+    """Manages TTS plugins and provides a simple interface for consumers."""
+
+    def __init__(self) -> None:
+        self._plugins: Dict[str, dict] = {}
+        self._engines: Dict[str, Engine] = {}
+        self._loaded = False
+
+    def discover(self, plugins_dir: str = "plugins") -> None:
+        """Discover and load all plugins from the given directory."""
+        import os
+        from pathlib import Path
+        from abogen.tts_plugin.loader import load_plugin_from_dir
+
+        self._plugins.clear()
+        self._engines.clear()
+
+        plugins_path = Path(plugins_dir)
+        if not plugins_path.exists():
+            if plugins_dir == "plugins":
+                plugins_path = Path(__file__).resolve().parent.parent.parent / "plugins"
+            if not plugins_path.exists():
+                self._loaded = True
+                return
+
+        for entry in plugins_path.iterdir():
+            if entry.is_dir() and (entry / "__init__.py").exists():
+                try:
+                    result = load_plugin_from_dir(entry)
+                    if result.success and result.manifest is not None:
+                        self._plugins[result.manifest.id] = {
+                            "manifest": result.manifest,
+                            "create_engine": result.create_engine,
+                            "module": result.module,
+                        }
+                except Exception as e:
+                    # Log error but continue with other plugins
+                    print(f"Warning: Failed to load plugin from {entry}: {e}")
+
+        self._loaded = True
+
+    def _ensure_loaded(self) -> None:
+        """Ensure plugins have been discovered."""
+        if not self._loaded:
+            self.discover()
+
+    def list_plugins(self) -> List[PluginManifest]:
+        """Return manifests for all loaded plugins."""
+        self._ensure_loaded()
+        return [info["manifest"] for info in self._plugins.values()]
+
+    def get_plugin(self, plugin_id: str) -> Optional[dict]:
+        """Get plugin info by ID."""
+        self._ensure_loaded()
+        return self._plugins.get(plugin_id)
+
+    def has_plugin(self, plugin_id: str) -> bool:
+        """Check if a plugin is loaded."""
+        self._ensure_loaded()
+        return plugin_id in self._plugins
+
+    def create_engine(self, plugin_id: str, **kwargs: Any) -> Engine:
+        """Create an engine instance for the given plugin.
+
+        Args:
+            plugin_id: The plugin identifier (e.g., "kokoro")
+            **kwargs: Arguments passed to the engine constructor
+
+        Returns:
+            An Engine instance
+
+        Raises:
+            KeyError: If plugin_id is not found
+            Exception: If engine creation fails
+        """
+        self._ensure_loaded()
+
+        if plugin_id not in self._plugins:
+            raise KeyError(f"Plugin not found: {plugin_id}")
+
+        plugin_info = self._plugins[plugin_id]
+        create_engine_func = plugin_info["create_engine"]
+
+        # Create engine using the plugin's factory
+        engine = create_engine_func(**kwargs)
+        return engine
+
+    def get_or_create_engine(self, plugin_id: str, **kwargs: Any) -> Engine:
+        """Get an existing engine or create a new one.
+
+        Engines are cached by plugin_id. If you need multiple instances
+        with different parameters, use create_engine() directly.
+        """
+        self._ensure_loaded()
+
+        cache_key = plugin_id
+        if cache_key in self._engines:
+            return self._engines[cache_key]
+
+        engine = self.create_engine(plugin_id, **kwargs)
+        self._engines[cache_key] = engine
+        return engine
+
+    def dispose_all(self) -> None:
+        """Dispose all cached engines."""
+        for engine in self._engines.values():
+            try:
+                engine.dispose()
+            except Exception:
+                pass  # dispose() should never raise
+        self._engines.clear()
+
+
+# Global singleton
+_manager: Optional[PluginManager] = None
+
+
+def get_plugin_manager() -> PluginManager:
+    """Get the global PluginManager instance."""
+    global _manager
+    if _manager is None:
+        _manager = PluginManager()
+    return _manager
+
+
+def reset_plugin_manager() -> None:
+    """Reset the global PluginManager (for testing)."""
+    global _manager
+    if _manager is not None:
+        _manager.dispose_all()
+    _manager = None

abogen/tts_plugin/types.py

@@ -0,0 +1,155 @@
+"""Core domain types for the TTS Plugin Architecture.
+
+This module contains immutable value objects that form the core domain.
+These types have zero dependencies and are used across the plugin system.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+from abogen.domain.enums import Language
+
+
+@dataclass(frozen=True)
+class AudioFormat:
+    """Immutable value object representing an audio format.
+
+    Attributes:
+        mime: MIME type of the audio (e.g., "audio/wav", "audio/mpeg").
+        extension: File extension (e.g., "wav", "mp3").
+    """
+
+    mime: str
+    extension: str
+
+
+@dataclass(frozen=True)
+class Duration:
+    """Immutable value object representing a time duration.
+
+    Attributes:
+        seconds: Duration in seconds.
+    """
+
+    seconds: float
+
+
+@dataclass(frozen=True)
+class VoiceSelection:
+    """Immutable value object for voice selection. Opaque to engine.
+
+    Attributes:
+        source: Voice source identifier (e.g., "builtin", "clone").
+        key: Voice key within the source.
+        payload: Optional payload for clone/blend sources.
+    """
+
+    source: str
+    key: str
+    payload: Any = None
+
+
+@dataclass(frozen=True)
+class ParameterValues:
+    """Immutable value object for synthesis parameters. Behaves like Mapping[str, Any].
+
+    Attributes:
+        values: Mapping of parameter names to their values.
+    """
+
+    values: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SynthesisRequest:
+    """Immutable value object for a synthesis request.
+
+    Attributes:
+        text: Text to synthesize.
+        voice: Voice selection.
+        parameters: Synthesis parameters.
+        format: Desired audio output format.
+    """
+
+    text: str
+    voice: VoiceSelection
+    parameters: ParameterValues
+    format: AudioFormat
+
+
+@dataclass(frozen=True)
+class TokenTiming:
+    """Per-token timing within a synthesized segment.
+
+    Attributes:
+        text: Token text.
+        whitespace: Whitespace following the token ("" if none).
+        start: Start time in seconds (relative to segment start).
+        end: End time in seconds (relative to segment start).
+    """
+
+    text: str
+    whitespace: str = ""
+    start: float = 0.0
+    end: float = 0.0
+
+
+@dataclass(frozen=True)
+class AudioSegment:
+    """One contiguous synthesized segment (sentence-level chunk).
+
+    Engines that split the input text (via ``split_pattern``) expose each
+    chunk as its own AudioSegment so hosts can report per-sentence progress
+    and build subtitles from per-token timings.
+
+    Attributes:
+        graphemes: The text this segment was synthesized from.
+        audio: Raw float32 PCM audio bytes for this segment.
+        sample_rate: Sample rate of ``audio``.
+        tokens: Per-token timing details, when the engine provides them.
+    """
+
+    graphemes: str
+    audio: bytes
+    sample_rate: int
+    tokens: tuple[TokenTiming, ...] = ()
+
+
+@dataclass(frozen=True)
+class SynthesizedAudio:
+    """Immutable value object for synthesized audio result.
+
+    Attributes:
+        data: Raw audio bytes.
+        format: Audio format of the result.
+        duration: Duration of the audio.
+        segments: Per-segment details when the engine split the text into
+            sentence-level chunks (empty for engines that only produce a
+            single merged result).
+    """
+
+    data: bytes
+    format: AudioFormat
+    duration: Duration
+    segments: tuple[AudioSegment, ...] = ()
+
+
+@dataclass(frozen=True)
+class EngineConfig:
+    """Immutable configuration of an Engine instance.
+
+    Contains parameters that define how a particular Engine instance is
+    created and that remain constant throughout the lifetime of that Engine.
+
+    Plugin implementations may ignore fields that are not applicable to them.
+
+    Attributes:
+        device: Device to use (e.g., "cpu", "cuda:0").
+        language: Language enum value. The engine converts to its internal
+            format internally — callers never see engine-specific codes.
+    """
+
+    device: str = "cpu"
+    language: Language = Language.EN_US

abogen/tts_plugin/utils.py

@@ -0,0 +1,265 @@
+"""TTS Plugin Architecture — direct utility functions.
+
+Provides helpers that replace the former compatibility adapter by
+calling the Plugin Manager directly.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterator
+
+import numpy as np
+
+from abogen.domain.enums import Language
+from abogen.tts_plugin.plugin_manager import get_plugin_manager
+
+
+def get_voices(plugin_id: str) -> tuple[str, ...]:
+    """Return the voice-id tuple for *plugin_id*.
+
+    Uses the official Plugin Architecture: PluginManager → Engine → VoiceLister.
+    First checks plugin manifest for static voice catalog.
+    """
+    import logging
+    import tempfile
+    from pathlib import Path
+
+    from abogen.tts_plugin.host_context import HostContext
+    from abogen.tts_plugin.types import EngineConfig
+
+    manager = get_plugin_manager()
+    if not manager.has_plugin(plugin_id):
+        return ()
+
+    # Check manifest for static voice catalog
+    plugin_info = manager.get_plugin(plugin_id)
+    if plugin_info is not None:
+        manifest = plugin_info.get("manifest")
+        if manifest is not None and manifest.voices is not None:
+            return tuple(v.id for v in manifest.voices)
+
+    ctx = HostContext(
+        config_dir=Path(tempfile.gettempdir()),
+        logger=logging.getLogger(f"abogen.utils.{plugin_id}"),
+        http_client=type("_StubHttpClient", (), {
+            "get": staticmethod(lambda url, **kw: None),
+            "post": staticmethod(lambda url, **kw: None),
+        })(),
+    )
+
+    try:
+        engine = manager.create_engine(
+            plugin_id,
+            context=ctx,
+            model_path=None,
+            config=EngineConfig(device="cpu"),
+        )
+    except Exception:
+        return ()
+
+    try:
+        from abogen.tts_plugin.capabilities import VoiceLister
+
+        if isinstance(engine, VoiceLister):
+            manifests = engine.listVoices("builtin")
+            return tuple(v.id for v in manifests)
+        return ()
+    except Exception:
+        return ()
+    finally:
+        engine.dispose()
+
+
+def get_default_voice(plugin_id: str, fallback: str = "") -> str:
+    """Return the first voice of *plugin_id*, or *fallback*."""
+    voices = get_voices(plugin_id)
+    return voices[0] if voices else fallback
+
+
+def is_plugin_registered(plugin_id: str) -> bool:
+    """Check whether *plugin_id* is loaded by the Plugin Manager."""
+    return get_plugin_manager().has_plugin(plugin_id)
+
+
+def resolve_voice_to_plugin(spec: str, fallback: str = "kokoro") -> str:
+    """Determine which plugin owns the given voice specification.
+
+    Resolution rules:
+    1. Empty spec -> fallback
+    2. Kokoro formula (contains '*' or '+') -> "kokoro"
+    3. Exact voice-id match against loaded plugins -> plugin id
+    4. Unknown voice -> fallback
+    """
+    raw = str(spec or "").strip()
+    if not raw:
+        return fallback
+
+    if "*" in raw or "+" in raw:
+        return "kokoro"
+
+    upper = raw.upper()
+    manager = get_plugin_manager()
+
+    for manifest in manager.list_plugins():
+        for voice_source in manifest.engine.voiceSources:
+            if voice_source.type == "list" and isinstance(voice_source.config, dict):
+                try:
+                    engine = manager.create_engine(manifest.id)
+                    try:
+                        if hasattr(engine, "listVoices"):
+                            voice_manifests = engine.listVoices(voice_source.id)
+                            voice_ids = [v.id.upper() for v in voice_manifests]
+                            if upper in voice_ids:
+                                return manifest.id
+                    finally:
+                        engine.dispose()
+                except Exception:
+                    continue
+
+    return fallback
+
+
+class Pipeline:
+    """Callable wrapper around Engine / EngineSession.
+
+    Presents the same interface that old callers expect::
+
+        pipeline = create_pipeline("kokoro", language=Language.EN_US, device="cpu")
+        for segment in pipeline(text, voice="af_nova", speed=1.0):
+            audio = segment.audio
+    """
+
+    def __init__(self, engine: Any, **engine_kwargs: Any) -> None:
+        self._engine = engine
+        self._engine_kwargs = engine_kwargs
+        self._session: Any = None
+
+    def _ensure_session(self) -> Any:
+        if self._session is None:
+            self._session = self._engine.createSession()
+        return self._session
+
+    def __call__(
+        self,
+        text: str,
+        voice: str = "default",
+        speed: float = 1.0,
+        split_pattern: str | None = None,
+        **kwargs: Any,
+    ) -> Iterator[Any]:
+        from abogen.tts_plugin.types import (
+            AudioFormat,
+            ParameterValues,
+            SynthesisRequest,
+            VoiceSelection,
+        )
+
+        session = self._ensure_session()
+
+        params: dict[str, Any] = {"speed": speed}
+        if split_pattern is not None:
+            params["split_pattern"] = split_pattern
+        params.update(kwargs)
+
+        request = SynthesisRequest(
+            text=text,
+            voice=VoiceSelection(source="builtin", key=voice),
+            parameters=ParameterValues(values=params),
+            format=AudioFormat(mime="audio/wav", extension="wav"),
+        )
+
+        result = session.synthesize(request)
+
+        from dataclasses import dataclass, field
+
+        @dataclass
+        class Token:
+            text: str
+            whitespace: str = ""
+            start_ts: float = 0.0
+            end_ts: float = 0.0
+
+        @dataclass
+        class Segment:
+            graphemes: str
+            audio: np.ndarray
+            tokens: list[Any] = field(default_factory=list)
+
+        if result.segments:
+            for seg in result.segments:
+                audio_array = np.frombuffer(seg.audio, dtype=np.float32)
+                tokens = [
+                    Token(
+                        text=tok.text,
+                        whitespace=tok.whitespace,
+                        start_ts=tok.start,
+                        end_ts=tok.end,
+                    )
+                    for tok in seg.tokens
+                ]
+                yield Segment(graphemes=seg.graphemes, audio=audio_array, tokens=tokens)
+            return
+
+        audio_array = np.frombuffer(result.data, dtype=np.float32)
+        yield Segment(graphemes=text, audio=audio_array)
+
+    def load_single_voice(self, voice_name: str) -> Any:
+        engine_pipeline = getattr(self._engine, '_pipeline', None)
+        if engine_pipeline is not None and hasattr(engine_pipeline, 'load_single_voice'):
+            return engine_pipeline.load_single_voice(voice_name)
+        raise AttributeError(f"load_single_voice not available on {type(self._engine).__name__}")
+
+    def dispose(self) -> None:
+        if self._session is not None:
+            try:
+                self._session.dispose()
+            except Exception:
+                pass
+            self._session = None
+
+    def __del__(self) -> None:
+        self.dispose()
+
+
+def create_pipeline(
+    plugin_id: str,
+    *,
+    language: Language = Language.EN_US,
+    device: str = "cpu",
+) -> Pipeline:
+    """Create a callable TTS pipeline via the Plugin Architecture.
+
+    Builds a proper HostContext and EngineConfig, then delegates to the
+    PluginManager to create the engine. Returns a :class:`Pipeline` whose
+    ``__call__`` interface matches the callable protocol used by consumers.
+
+    Args:
+        plugin_id: Plugin identifier (e.g., "kokoro", "supertonic").
+        language: Language enum value (app-layer type, not engine-specific).
+        device: Device to use (e.g., "cpu", "cuda:0").
+
+    Returns:
+        A callable Pipeline instance.
+    """
+    import logging
+    import tempfile
+    from pathlib import Path
+
+    from abogen.tts_plugin.host_context import HostContext
+    from abogen.tts_plugin.types import EngineConfig
+
+    manager = get_plugin_manager()
+
+    ctx = HostContext(
+        config_dir=Path(tempfile.gettempdir()),
+        logger=logging.getLogger(f"abogen.pipeline.{plugin_id}"),
+        http_client=type("_StubHttpClient", (), {
+            "get": staticmethod(lambda url, **kw: None),
+            "post": staticmethod(lambda url, **kw: None),
+        })(),
+    )
+
+    config = EngineConfig(device=device, language=language)
+
+    engine = manager.create_engine(plugin_id, context=ctx, model_path=None, config=config)
+    return Pipeline(engine)

abogen/utils.py

@@ -6,7 +6,9 @@ import re
 import shutil
 import subprocess
 import sys
+import time
 import warnings
+from contextlib import contextmanager
 from threading import Thread
 from typing import Dict, Optional
 
@@ -14,6 +16,8 @@ from functools import lru_cache
 
 from dotenv import load_dotenv, find_dotenv
 
+logger = logging.getLogger(__name__)
+
 
 def _load_environment() -> None:
     explicit_path = os.environ.get("ABOGEN_ENV_FILE")
@@ -29,6 +33,125 @@ _load_environment()
 
 warnings.filterwarnings("ignore")
 
+# --- Console log colorization via rich (mirrors AutoSubSync's approach) ---
+
+try:  # rich is a declared dependency, but degrade gracefully if unavailable
+    from rich.console import Console
+    from rich.highlighter import NullHighlighter
+    from rich.logging import RichHandler
+
+    _RICH_AVAILABLE = True
+except Exception:  # pragma: no cover - fallback to plain logging
+    Console = None
+    NullHighlighter = None
+    RichHandler = None
+    _RICH_AVAILABLE = False
+
+
+def _console_supports_color() -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    try:
+        return bool(sys.stderr.isatty())
+    except Exception:
+        return False
+
+
+_RICH_CONSOLE = None
+if Console is not None:
+    try:
+        _RICH_CONSOLE = Console(stderr=True, no_color=not _console_supports_color())
+    except Exception:  # pragma: no cover - defensive
+        _RICH_CONSOLE = None
+
+
+_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+
+if RichHandler is not None:
+
+    class RichConsoleHandler(RichHandler):
+        """RichHandler with default settings, except raw ANSI escapes are
+        stripped from messages first (werkzeug colorizes its own log lines
+        when attached to a TTY; without this they render as literal "[36m"
+        fragments)."""
+
+        def emit(self, record):
+            # Werkzeug logs its dev-server banner at INFO but hardcodes a
+            # "WARNING: " prefix into the message text. Promote the record so
+            # the level tag matches the content.
+            try:
+                message = _ANSI_ESCAPE_RE.sub("", record.getMessage())
+            except Exception:  # pragma: no cover - defensive
+                message = ""
+            if record.levelno < logging.WARNING and message.startswith("WARNING: "):
+                record.levelno = logging.WARNING
+                record.levelname = "WARNING"
+            super().emit(record)
+
+        def render_message(self, record, message):
+            message = _ANSI_ESCAPE_RE.sub("", message)
+            if message.startswith("WARNING: "):
+                message = message[len("WARNING: ") :]
+            return super().render_message(record, message)
+
+else:  # pragma: no cover - rich unavailable fallback
+    RichConsoleHandler = None  # type: ignore[assignment, misc]
+
+
+def console_handler(show_level=True):
+    """Build a colored console handler. Rich's RichHandler when available
+    (no timestamps, colored level tags), plain StreamHandler otherwise."""
+    if _RICH_CONSOLE is not None and RichConsoleHandler is not None:
+        return RichConsoleHandler(
+            console=_RICH_CONSOLE,
+            show_path=False,
+            show_time=False,
+            rich_tracebacks=True,
+        )
+    handler = logging.StreamHandler(sys.stderr)
+    prefix = "%(levelname)s - " if show_level else ""
+    handler.setFormatter(logging.Formatter(f"{prefix}%(message)s"))
+    return handler
+
+
+def setup_console_logging(level=logging.INFO):
+    """Configure the root logger once with a colored console handler."""
+    root = logging.getLogger()
+    if not root.handlers:
+        root.addHandler(console_handler())
+    root.setLevel(level)
+
+
+@contextmanager
+def timed_log(label, logger=None, level=logging.INFO):
+    """Context manager that logs the wall-clock time a block of code takes.
+
+    Used to surface which load/startup steps are slow. The elapsed time is
+    colorized: green < 1s, yellow 1-5s, red > 5s.
+    """
+    log = logger or logging.getLogger(__name__)
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        elapsed = time.perf_counter() - start
+        if _RICH_AVAILABLE and _RICH_CONSOLE is not None and not _RICH_CONSOLE.no_color:
+            if elapsed >= 5.0:
+                color = "red"
+            elif elapsed >= 1.0:
+                color = "yellow"
+            else:
+                color = "green"
+            log.log(
+                level,
+                "Loaded %s in %s",
+                f"[cyan]{label}[/cyan]",
+                f"[{color}]{elapsed:.2f}s[/{color}]",
+                extra={"markup": True, "highlighter": NullHighlighter()},
+            )
+        else:
+            log.log(level, "Loaded %s in %.2fs", label, elapsed)
+
 
 def detect_encoding(file_path):
     try:
@@ -320,10 +443,6 @@ default_encoding = sys.getfilesystemencoding()
 
 
 def create_process(cmd, stdin=None, text=True, capture_output=False):
-    import logging
-
-    logger = logging.getLogger(__name__)
-
     # Configure root logger to output to console if not already configured
     root = logging.getLogger()
     if not root.handlers:
@@ -372,8 +491,8 @@ def create_process(cmd, stdin=None, text=True, capture_output=False):
             }
         )
 
-    # Print the command being executed
-    print(f"Executing: {cmd if isinstance(cmd, str) else ' '.join(cmd)}")
+    # Log the command being executed
+    logger.info(f"Executing: {cmd if isinstance(cmd, str) else ' '.join(cmd)}")
 
     proc = subprocess.Popen(cmd, **kwargs)
 
@@ -428,19 +547,6 @@ def save_config(config):
         pass
 
 
-def calculate_text_length(text):
-    # Ignore chapter markers
-    text = re.sub(r"<<CHAPTER_MARKER:.*?>>", "", text)
-    # Ignore metadata patterns
-    text = re.sub(r"<<METADATA_[^:]+:[^>]*>>", "", text)
-    # Ignore newlines
-    text = text.replace("\n", "")
-    # Ignore leading/trailing spaces
-    text = text.strip()
-    # Calculate character count
-    char_count = len(text)
-    return char_count
-
 
 def get_gpu_acceleration(enabled):
     try:
@@ -507,7 +613,7 @@ def prevent_sleep_start():
             )
         else:
             # Non-systemd distro or systemd tools not installed: skip inhibition rather than crash
-            print(
+            logger.warning(
                 "systemd-inhibit not found: skipping sleep inhibition on this Linux system."
             )
 
@@ -529,21 +635,24 @@ def prevent_sleep_end():
                 _sleep_procs[system] = None
 
 
-def load_numpy_kpipeline():
-    import numpy as np
-    from kokoro import KPipeline  # type: ignore[import-not-found]
-
-    return np, KPipeline
-
-
 class LoadPipelineThread(Thread):
-    def __init__(self, callback):
+    def __init__(self, callback, lang_code="a", use_gpu=True):
         super().__init__()
         self.callback = callback
+        self.lang_code = lang_code
+        self.use_gpu = use_gpu
 
     def run(self):
         try:
-            np_module, kpipeline_class = load_numpy_kpipeline()
-            self.callback(np_module, kpipeline_class, None)
+            from abogen.domain.pipeline_factory import create_pipeline_for_job
+
+            with timed_log(
+                f"TTS pipeline (lang={self.lang_code}, gpu={self.use_gpu})",
+                logger=logging.getLogger("abogen.startup"),
+            ):
+                backend = create_pipeline_for_job(
+                    "kokoro", language=self.lang_code, use_gpu=self.use_gpu
+                )
+            self.callback(backend, None)
         except Exception as e:
-            self.callback(None, None, str(e))
+            self.callback(None, str(e))

abogen/voice_cache.py

@@ -17,7 +17,7 @@ if LocalEntryNotFoundError is None:  # pragma: no cover - fallback for tests
         pass
 
 
-from abogen.constants import VOICES_INTERNAL
+from abogen.tts_plugin.utils import get_voices
 
 _CACHE_LOCK = threading.Lock()
 _CACHED_VOICES: Set[str] = set()
@@ -26,8 +26,9 @@ _BOOTSTRAPPED = False
 
 
 def _normalize_targets(voices: Optional[Iterable[str]]) -> Set[str]:
+    kokoro_voices = get_voices("kokoro")
     if not voices:
-        return set(VOICES_INTERNAL)
+        return set(kokoro_voices)
     normalized: Set[str] = set()
     for voice in voices:
         if not voice:
@@ -35,7 +36,7 @@ def _normalize_targets(voices: Optional[Iterable[str]]) -> Set[str]:
         voice_id = str(voice).strip()
         if not voice_id:
             continue
-        if voice_id in VOICES_INTERNAL:
+        if voice_id in kokoro_voices:
             normalized.add(voice_id)
     return normalized
 
@@ -143,3 +144,11 @@ def _ensure_single_voice_asset(
 
     hf_hub_download(resume_download=True, **common_kwargs)
     return True
+
+
+def clear_voice_cache() -> None:
+    """Clear the in‑process voice cache (used during shutdown)."""
+    with _CACHE_LOCK:
+        _CACHED_VOICES.clear()
+    global _BOOTSTRAPPED
+    _BOOTSTRAPPED = False

abogen/voice_formulas.py

@@ -1,7 +1,7 @@
 import re
-from typing import List, Tuple
+from typing import Iterable, List, Optional, Tuple
 
-from abogen.constants import VOICES_INTERNAL
+from abogen.tts_plugin.utils import get_voices
 
 
 # Calls parsing and loads the voice to gpu or cpu
@@ -22,6 +22,7 @@ def parse_formula_terms(formula: str) -> List[Tuple[str, float]]:
         raise ValueError("Empty voice formula")
 
     terms: List[Tuple[str, float]] = []
+    kokoro_voices = get_voices("kokoro")
     for segment in formula.split("+"):
         part = segment.strip()
         if not part:
@@ -30,7 +31,7 @@ def parse_formula_terms(formula: str) -> List[Tuple[str, float]]:
             raise ValueError("Each component must be in the form voice*weight")
         voice_name, raw_weight = part.split("*", 1)
         voice_name = voice_name.strip()
-        if voice_name not in VOICES_INTERNAL:
+        if voice_name not in kokoro_voices:
             raise ValueError(f"Unknown voice: {voice_name}")
         try:
             weight = float(raw_weight.strip())
@@ -71,6 +72,33 @@ def parse_voice_formula(pipeline, formula):
     return weighted_sum
 
 
+def pairs_to_formula(pairs: Iterable[Tuple[str, float]]) -> Optional[str]:
+    """Build a voice formula string from (voice_name, weight) pairs.
+
+    Normalizes weights to sum to 1.0 and formats as "voice1*0.5+voice2*0.5".
+
+    Args:
+        pairs: Iterable of (voice_name, weight) tuples. Zero-weight entries
+            are filtered out.
+
+    Returns:
+        Formula string, or None if no valid entries.
+    """
+    voices = [(voice, float(weight)) for voice, weight in pairs if weight is not None and float(weight) > 0]
+    if not voices:
+        return None
+    total = sum(weight for _, weight in voices)
+    if total <= 0:
+        return None
+
+    def _format_value(value: float) -> str:
+        normalized = value / total if total else 0.0
+        return (f"{normalized:.4f}").rstrip("0").rstrip(".") or "0"
+
+    parts = [f"{voice}*{_format_value(weight)}" for voice, weight in voices]
+    return "+".join(parts)
+
+
 def calculate_sum_from_formula(formula):
     weights = re.findall(r"\* *([\d.]+)", formula)
     total_sum = sum(float(weight) for weight in weights)

abogen/voice_metadata.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class VoiceMetadata:
+    """
+    Immutable metadata describing a voice from a TTS backend.
+
+    This model describes a voice independently of any backend implementation.
+    Backends populate these objects; the application consumes them.
+
+    The ``backend_id`` field is set by the backend itself (via
+    ``self.metadata.id``) — the application never hardcodes it.
+    This ensures renaming a backend does not require touching voice definitions.
+    """
+
+    id: str
+    """Unique voice identifier within the backend (e.g. ``"af_alloy"``, ``"M1"``)."""
+
+    display_name: str
+    """Human-readable display name (e.g. ``"Alloy"``, ``"Male 1"``)."""
+
+    language: str
+    """Language code — backend-specific format is acceptable (e.g. ``"a"``, ``"en"``)."""
+
+    gender: str
+    """Gender category: ``"female"``, ``"male"``, or ``"unknown"``."""
+
+    backend_id: str
+    """Identifier of the backend that owns this voice (e.g. ``"kokoro"``).
+
+    Set automatically by the backend — never hardcoded in voice definitions.
+    """

abogen/voice_profiles.py

@@ -2,8 +2,8 @@ import json
 import os
 from typing import Any, Dict, Iterable, List, Tuple
 
-from abogen.constants import VOICES_INTERNAL
-from abogen.tts_supertonic import DEFAULT_SUPERTONIC_VOICES
+from abogen.domain.enums import Language
+from abogen.tts_plugin.utils import get_voices, is_plugin_registered
 from abogen.utils import get_user_config_path
 
 
@@ -70,7 +70,8 @@ def serialize_profiles() -> Dict[str, Dict[str, Iterable[Tuple[str, float]]]]:
 
 def _normalize_supertonic_voice(value: Any) -> str:
     raw = str(value or "").strip().upper()
-    return raw if raw in DEFAULT_SUPERTONIC_VOICES else "M1"
+    supertonic_voices = get_voices("supertonic")
+    return raw if raw in supertonic_voices else "M1"
 
 
 def _coerce_supertonic_steps(value: Any) -> int:
@@ -101,7 +102,7 @@ def normalize_profile_entry(entry: Any) -> Dict[str, Any]:
         return {}
 
     provider = str(entry.get("provider") or "kokoro").strip().lower()
-    if provider not in {"kokoro", "supertonic"}:
+    if not is_plugin_registered(provider):
         provider = "kokoro"
 
     language = str(entry.get("language") or "a").strip().lower() or "a"
@@ -135,6 +136,7 @@ def normalize_profile_entry(entry: Any) -> Dict[str, Any]:
 
 def _normalize_voice_entries(entries: Iterable) -> List[Tuple[str, float]]:
     normalized: List[Tuple[str, float]] = []
+    kokoro_voices = get_voices("kokoro")
     for item in entries or []:
         if isinstance(item, dict):
             voice = item.get("id") or item.get("voice")
@@ -143,7 +145,7 @@ def _normalize_voice_entries(entries: Iterable) -> List[Tuple[str, float]]:
             voice, weight = item[0], item[1]
         else:
             continue
-        if voice not in VOICES_INTERNAL:
+        if voice not in kokoro_voices:
             continue
         if weight is None:
             continue
@@ -175,13 +177,35 @@ def save_profile(name: str, *, language: str, voices: Iterable) -> None:
         raise ValueError("At least one voice with a weight above zero is required")
 
     if not language:
-        language = "a"
+        language = Language.EN_US
 
     profiles = load_profiles()
     profiles[name] = {"provider": "kokoro", "language": language, "voices": normalized}
     save_profiles(profiles)
 
 
+def resolve_profile_language(entry: Any) -> Language:
+    """Resolve a profile's stored language to a Language enum.
+
+    New profiles store ISO codes (Language enum values); legacy profiles may
+    store kokoro letter codes ("a", "b", ...). Unparseable values fall back
+    to EN_US.
+    """
+
+    raw = entry.get("language") if isinstance(entry, dict) else None
+    if isinstance(raw, Language):
+        return raw
+    text = str(raw or "").strip()
+    if not text:
+        return Language.EN_US
+    try:
+        return Language.from_str(text)
+    except ValueError:
+        from plugins.kokoro.engine import language_for_code
+
+        return language_for_code(text)
+
+
 def remove_profile(name: str) -> None:
     delete_profile(name)