flet ui (experimental)

Fix #152 : preview buttons on webUI

.env.example

@@ -0,0 +1,44 @@
+# Copy this file to `.env` and customize the paths to match your environment.
+# Relative paths are resolved from the repository root when running locally.
+# Each `*_DIR` value below points to a directory on the host. Docker Compose
+# mounts it into the container at the standard path noted in the comment.
+
+# Host directory that stores JSON settings. Mounted to /config in Docker.
+ABOGEN_SETTINGS_DIR=./config
+
+# Host directory for rendered audio/subtitle files. Mounted to /data/outputs
+# in Docker.
+ABOGEN_OUTPUT_DIR=./storage/output
+
+# Temporary working directory. When running in Docker, keep this inside the
+# mounted data volume (or another writable host path) so non-root users can
+# write to it. Only audio conversion scratch files are staged here by default;
+# other library caches remain inside the container volume. For local
+# (non-Docker) usage, change this to a path that makes sense on your machine or
+# comment it out to fall back to the OS cache directory. Mounted to /data/cache
+# in Docker.
+ABOGEN_TEMP_DIR=./storage/tmp
+
+# UID/GID used when running the Docker container. 1000:1000 matches most Linux hosts.
+# Find your current values with:
+#   id -u   # UID
+#   id -g   # GID
+ABOGEN_UID=1000
+ABOGEN_GID=1000
+
+# Network mode for the Docker container. Options:
+#   bridge (default) - Isolated container network, uses port mapping
+#   host             - Container uses host's network directly, required for
+#                      accessing LAN resources like Calibre OPDS servers
+# ABOGEN_NETWORK_MODE=host
+
+# Optional: Seed the web UI with working defaults for the LLM-powered
+# text normalization features. Leave these blank to configure everything
+# from the Settings page.
+ABOGEN_LLM_BASE_URL=http://localhost:11434  # Supply the server root; /v1 is added automatically.
+ABOGEN_LLM_API_KEY=ollama
+ABOGEN_LLM_MODEL=llama3.1:8b
+ABOGEN_LLM_TIMEOUT=45
+ABOGEN_LLM_CONTEXT_MODE=sentence
+# For custom prompts, keep the text on a single line or escape newlines.
+#ABOGEN_LLM_PROMPT=Provide regex replacements for any apostrophes in {{sentence}} using apply_regex_replacements.

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [jborza, jeremiahsb, mohangk]
+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
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/workflows/test_publish.yml

@@ -0,0 +1,63 @@
+name: Build multi-arch Docker Image
+
+on:
+  # Build and push
+  #release:
+  #  types: [published]
+  # Build only
+  #push: it 
+  #  branches: [main]
+  # TODO - enable build on pull requests if build times can be reduced
+  # pull_request:
+  workflow_dispatch:
+
+env:
+  IMAGE_REPOSITORY: ghcr.io/denizsafak/abogen
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Login to Github Container Registry
+      # Only if we need to push an image
+      # if: ${{ github.event_name == 'release' && github.event.action == 'published' }}
+      uses: docker/login-action@v3
+      with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+    # Setup for buildx
+    - name: Set up QEMU
+      uses: docker/setup-qemu-action@v3
+
+    - name: Set up Docker Buildx
+      id: buildx
+      uses: docker/setup-buildx-action@v3
+
+    # Debugging information
+    - name: Docker info
+      run: docker info
+
+    - name: Buildx inspect
+      run: docker buildx inspect
+
+    # Build and (optionally) push the image
+    - name: Build image
+      uses: docker/build-push-action@v6
+      with:
+        context: ./abogen
+        file: ./abogen/Dockerfile
+        # platforms: linux/amd64,linux/arm/v7,linux/arm64,linux/ppc64le,linux/s390x
+        # platforms: linux/amd64,linux/arm64
+        platforms: linux/amd64 # using the solution mentioned in https://github.com/denizsafak/abogen/issues/46
+        # Only push if we are publishing a release
+        # push: ${{ github.event_name == 'release' && github.event.action == 'published' }}
+        push: true
+        # Use a 'temp' tag, that won't be pushed, for non-release builds
+        tags: ${{ env.IMAGE_REPOSITORY }}:${{ github.event.release.tag_name || 'latest' }}
+        # Use a cache to reduce build times
+        cache-to: type=gha,mode=max
+        cache-from: type=gha

.gitignore

@@ -19,6 +19,7 @@ __pycache__/
 env/
 venv/
 .env/
+.env
 .venv/
 test/
 
@@ -30,6 +31,11 @@ python_embedded/
 
 # abogen
 *config.json
+config/
+storage/
 build/
 dist/
 .old/
+test_assets/
+dev_notes/
+.claude/

.python-version

@@ -0,0 +1 @@
+3.12

CHANGELOG.md

@@ -1,6 +1,218 @@
+# 1.3.0
+- Special thanks to [@jeremiahsb](https://github.com/jeremiahsb) for his [massive contribution](https://github.com/denizsafak/abogen/pull/120) (>55k lines!) that brought the Web UI, EPUB 3 pipeline, and core architectural improvements to life.
+- Added an EPUB 3 packaging pipeline that builds media-overlay EPUBs from generated audio and chunk metadata.
+- Persisted chunk timing metadata in job artifacts and exercised the exporter with automated tests.
+- Added Flask-based Web UI (`abogen-web`) for Docker and headless server deployments.
+- Reorganized codebase to support both PyQt6 desktop GUI and Web UI from a shared core.
+- Added Supertonic TTS engine support with GPU acceleration.
+- Added entity analysis and pronunciation override system for proper nouns.
+- Added speaker/role assignment for multi-voice "theatrical" audiobooks.
+- Added Calibre OPDS and Audiobookshelf integration.
+
+# 1.2.5
+- Added new option: `Override item settings with current selection` in the queue manager. When enabled, all items in the queue will be processed using the current global settings selected in the main GUI, overriding their individual settings. When disabled, each item will retain its own specific settings.
+- Fixed `Error "Could not load the Qt platform plugin "xcb"` error that occurred in some Linux distributions due to missing `libxcb-cursor0` library by conditionally loading the bundled library when the system version is unavailable, issue mentioned by @bmcgonag in #101.
+- Fixed the `No module named pip` error that occurred for users who installed Abogen via the [**uv**](https://github.com/astral-sh/uv) installer.
+- Fixed defaults for `replace_single_newlines` not being applied correctly in some cases.
+- Fixed `Save chapters separately for queued epubs is ignored`, issue mentioned by @dymas-cz in #109.
+- Fixed incorrect sentence segmentation when using spaCy, where text would erroneously split after opening parentheses.
+- Improvements in code and documentation.
+
+# 1.2.4
+- **Subtitle generation is now available for all languages!** Abogen now supports subtitle generation for non-English languages using audio duration-based timing. Available modes include `Line`, `Sentence`, and `Sentence + Comma`. (Note: Word-level subtitle modes remain English-only due to Kokoro's timestamp token limitations.)
+- New option: **"Use spaCy for sentence segmentation"** You can now use [spaCy](https://spacy.io/) to automatically detect sentence boundaries and produce cleaner, more readable subtitles. Quick summary:
+    - **What it does:** Splits text into natural sentences so subtitle entries read better and align more naturally with speech.
+    - **Why this helps:** The previous punctuation-based splitting could break sentences incorrectly at common abbreviations (e.g. "Mr.", "Dr.", "Prof.") or initials, producing wrong subtitle breaks. spaCy avoids those false splits by using linguistic rules to detect real sentence boundaries.
+    - **For Non-English:** spaCy runs **before** audio generation to create better sentence chunks for TTS.
+    - **For English:** spaCy runs **during** subtitle generation to find accurate sentence breaks after TTS.
+    - **Note:** spaCy segmentation is only applied when subtitle mode is `Sentence` or `Sentence + Comma`. When turned off, it falls back to simple punctuation-based splitting.
+- New option: **Pre-download models and voices for offline use** You can now pre-download all required Kokoro models, voices, and spaCy language models using this option in the settings menu. Allowing you to use Abogen completely offline without any internet connection.
+- Added support for `.` separator in timestamps (e.g. `HH:MM:SS.ms`) for timestamp-based text files.
+- Optimized regex compilation and eliminated busy-wait loops.
+- Possibly fixed `Silent truncation of long paragraphs` issue mentioned in [#91](https://github.com/denizsafak/abogen/issues/91) by [@xklzlxr](https://github.com/xklzlxr)
+- Fixed unused regex patterns and variable naming conventions.
+- Improvements in code and documentation.
+
+# 1.2.3
+- Same as 1.2.2, re-released to fix an issue with subtitle timing when using timestamp-based text files.
+
+# 1.2.2
+- **You can now voice your subtitle files!** Simply add `.srt`, `.ass` or `.vtt` files to generate timed audio. Alternatively, add a text file with timestamps in `HH:MM:SS` or `HH:MM:SS,ms` format to generate audio that matches the timestamps. See [here](https://github.com/denizsafak/abogen?tab=readme-ov-file#about-timestamp-based-text-files) for detailed instructions.
+    - New option: **"Use silent gaps between subtitles"**: Prevents unnecessary audio speed-up by letting speech continue into the silent gaps between subtitles.
+    - New option: **"Subtitle speed adjustment method"**: Choose how to speed up audio when needed:
+        - **TTS Regeneration (better quality):** Re-generates the audio at a faster speed for more natural sound.
+        - **FFmpeg Time-stretch (better speed):** Quickly speeds up the generated audio.
+- Added support for embedding cover images in M4B files. Abogen now automatically extracts cover images from EPUB and PDF files. You can also manually specify a cover image using the `<<METADATA_COVER_PATH:path>>` tag in your text file. (To prevent MPV from showing the cover image, you can add `audio-display=no` to your MPV config file.)
+- Fixed `[WinError 1114] A dynamic link library (DLL) initialization routine failed` error on Windows, pre-loading PyTorch DLLs before initializing PyQt6 to avoid DLL initialization errors, mentioned in #98 by @ephr0n.
+- Potential fix for `CUDA GPU is not available` issue, by ensuring PyTorch is installed correctly with CUDA support on Windows using the installer script.
+- Improvements in code and documentation.
+
+# 1.2.1
+- Upgraded Abogen's interface from PyQt5 to PyQt6 for better compatibility and long-term support.
+- Added tooltip indicators in queue manager to display book handler options (`Save chapters separately` and `Merge chapters at the end`) for queued items.
+- Added `Open processed file` and `Open input file` options for items in the queue manager, instead of just `Open file` option.
+- Added loading gif animation to book handler window.
+- Fixed light theme slider colors in voice mixer for better visibility (for non-Windows users).
+- Fixed subtitle word-count splitting logic for more accurate segmentation.
+- Improvements in code and documentation.
+
+# 1.2.0
+- Added `Line` option to subtitle generation modes, allowing subtitles to be generated based on line breaks in the text, by @mleg in #94.
+- Added a loading indicator to the book handler window for better user experience during book preprocessing.
+- Fixed `cannot access local variable 'is_narrow'` error when subtitle format `SRT` was selected, mentioned by @Kinasa0096 in #88.
+- Fixed folder and filename sanitization to properly handle OS-specific illegal characters (Windows, Linux, macOS), ensuring compatibility across all platforms when creating chapter folders and files.
+- Fixed `/` and `\` path display by normalizing paths.
+- Fixed book reprocessing issue where books were being processed every time the chapters window was opened, improving performance when reopening the same book.
+- Fixed taskbar icon not appearing correctly in Windows.
+- Fixed "Go to folder" button not opening the chapter output directory when only separate chapters were generated.
+- Improvements in code and documentation.
+
+# 1.1.9
+- Fixed the issue where spaces were deleted before punctuation marks while generating subtitles.
+- Fixed markdown TOC generation breaks when "Replace single newlines" is enabled.
+- Improvements in code and documentation.
+
+# 1.1.8
+- Added `.md` (Markdown) file extension support by @brianxiadong in PR #75
+- Added new option `Configure silence between chapters` that lets you configure the silence between chapters, mentioned by @lfperez1982 in #79
+- Better indicators and options while displaying and managing the input and processing files.
+- Improved the markdown logic to better handle various markdown structures and cases.
+- Fixed subtitle splitting before commas by combining punctuation with preceding words.
+- Fixed save options not working correctly in queue mode, mentioned by @jborza in #78
+- Fixed `No Qt platform plugin could be initialized` error, mentioned by @sunrainxyz in #59
+- Fixed ordered list numbers not being included in EPUB content conversion. The numbers are now properly included in the converted content, mentioned by @jefro108 in #47
+- Potentially fixed subtitle generation stucks at 9:59:59, mentioned by @bolaykim in #73
+- Improvements in code and documentation.
+
+# 1.1.7
+- Added MPS GPU acceleration support for Silicon Mac, mentioned in https://github.com/denizsafak/abogen/issues/32#issuecomment-3155902040 by @jefro108. **Please read the [Mac](https://github.com/denizsafak/abogen?tab=readme-ov-file#mac) section in the documentation again, as it requires additional configuration.**
+- Added word-by-word karaoke highlighting feature by @robmckinnon in PR #65
+- Fixed sleep inhibition error occurring on some Linux systems that do not use systemd, mentioned in #67 by @hendrack
+- Improvements in code and documentation.
+
+# 1.1.6
+- Improved EPUB chapter detection: Now reliably detects chapters from NAV HTML (TOC) files, even in non-standard EPUBs, fixes the issue mentioned by @jefro108 in #33
+- Fixed SRT subtitle numbering issue, mentioned by @page-muncher in #41
+- Fixed missing chapter contents issue in some EPUB files.
+- Windows installer script now prompts the user to install the CUDA version of PyTorch even if no NVIDIA GPU is detected.
+- Abogen now includes Mandarin Chinese (misaki[zh]) by default; manual installation is no longer required.
+
+# 1.1.5
+- Changed the temporary directory path to user's cache directory, which is more appropriate for storing cache files and avoids issues with unintended cleanup.
+- Fixed the isssue where extra metadata information was not being saved to M4B files when they have no chapters, ensuring that all metadata is correctly written to the output file.
+- Fixed sleep prevention process not ending if program exited using Ctrl+C or kill.
+- Improved automatic filename suffixing to better prevent overwriting files with the same name, even if they have different extensions.
+- Improvements in code and documentation.
+
+# 1.1.4
+- Fixed extra metadata information not being saved to M4B files, ensuring that all metadata is correctly written to the output file.
+- Reformatted the code using Black for better readability and consistency.
+
+# 1.1.3
+- `M4B (with chapters)` generation is faster now, as it directly generates `m4b` files instead of converting from `wav`, which significantly reduces processing time, fixes the issue mentioned by @Milor123 in #39 
+- Better sleep state handling for Linux.
+- The app window now tries to fit the screen if its height would exceed the available display area.
+- Fixed issue where the app would not restart properly on Windows.
+- Fixed last sentence/subtitle entry timing in generated subtitles, the end time of the final subtitle entry now correctly matches the end of the audio chunk, preventing zero or invalid timings at the end.
+
+# v1.1.2
+- Now you can play the audio files while they are processing.
+- Audio and subtitle files are now written directly to disk during generation, which significantly reduces memory usage.
+- Added a better logic for detecting chapters from the epub, mentioned by @jefro108 in #33
+- Added a new option: `Reset to default settings`, allowing users to reset all settings to their default values.
+- Added a new option: `Disable Kokoro's internet access`. This lets you prevent Kokoro from downloading models or voices from HuggingFace Hub, which can help avoid long waiting times if your computer is offline.
+- HuggingFace Hub telemetry is now disabled by default for improved privacy. (HuggingFace Hub is used by Kokoro to download its models)
+- cPotential fix for #37 and #38, where the program was becoming slow while processing large files.
+- Fixed `Open folder` and `Open file` buttons in the queue manager GUI.
+- Improvements in code structure.
+
+# v1.1.1
+- Fixed adding wrong file in queue for EPUB and PDF files, ensuring the correct file is added to the queue.
+- Reformatted the code using Black.
+
+# v1.1.0
+- Added queue system for processing multiple items, allowing users to add multiple files and process them in a queue, mentioned by @jborza in #30 (Special thanks to @jborza for implementing this feature in PR #35)
+- Added a feature that allows selecting multiple items in book handler (in right click menu) by @jborza in #31, that fixes #28
+- Added dark theme support, allowing users to switch between light and dark themes in the settings.
+- Added auto-accept system to the chapter options dialog in conversion process, allowing the dialog to auto-accept after a certain time if no action is taken.
+- Added new option: `Configure max lines in log window` that allows configuring the maximum number of lines to display in the log window.
+- Improvements in documentation and code.
+
+# v1.0.9
+- Added chunking/segmenting system that fixes memory outage issues when processing large audio files.
+- Added new option: `Subtitle format`, allowing users to choose between `srt` , `ass (wide)`, `ass (narrow)`, and `ass (centered wide)` and `ass (centered narrow)`
+- Improved chapter filename generation with smart word-boundary truncation at 80 characters, preventing mid-word cuts in filenames.
+- `Composer` and `Genre` metadata fields for M4B files are now editable from the text editor.
+- Improvements in documentation and code.
+
+# v1.0.8
+- Added support for AMD GPUs in Linux (Special thanks to @hg000125 for his contribution in #23)
+- Added voice preview caching system that stores generated previews in the cache folder, mentioned by @jborza in #22
+- Added extra metadata support for chaptered M4B files, ensuring better compatibility with audiobook players.
+- Added new option: `Separate chapters audio format`, allowing to choose between `wav`, `mp4`, `flac` and `opus` formats for chaptered audio files.
+- Added a download tracker that displays informative messages while downloading Kokoro models or voices from HuggingFace.
+- Skipping PyTorch CUDA installation if GPU is not NVIDIA in WINDOWS_INSTALL.bat script, preventing unnecessary installation of PyTorch.
+- Removed `abogen_` prefix that was adding to converted books in temp directory.
+- Fixed voice preview player keeps playing silently at the background after preview ends.
+- Fixed not writing separate chapters audio when output is OPUS.
+- Improved input box background color handling, fixed display issues in Linux.
+- Updated profile and voice mixer icons, better visibility and aesthetics in voice mixer.
+- Better sleep state handling for Linux.
+- Improvements in documentation and code.
+
+# v1.0.7
+- Improve chaptered audio generation by outputting directly as `m4b` instead of converting from `wav`.
+- Ignore chapter markers and single newlines when calculating text length, improving the accuracy of the text length calculation.
+- Prevent cancellation if process is at 99%, ensuring the process is not interrupted at the last moment.
+- Improved process handling for subpprocess calls, ensuring better management of subprocesses.
+- Improved PDF handling, ignoring empty pages/chapters and better chapter handling.
+- Added `Save in a project folder with metadata` option in the book handler, allowing users to save the converted items in a project folder with available metadata files. Useful if you want to work with the converted files in the future, issue mentioned by @Darthagnon in #15
+- Added `Go to folder` button in input box, allowing users to open the folder containing the converted file.
+- Added `.opus` as output format for generated audio files, which is a more efficient format for audio files.
+- Added `Create desktop shortcut and install` option to Linux version, allowing users to create a shortcut and install 
+- Added "Playing..." indicator for "Preview" button in the voice mixer.
+
+# v1.0.6
+- Added `Insert chapter marker` button in text editor to insert chapter markers at the current cursor position.
+- Added `Preview` button in voice mixer to preview the voice mix with the selected settings.
+- Fixed `f-string: unmatched '['` error in Voice preview, mentioned in #14
+- Fixed the issue with the content before first chapter not being included in the output.
+- Fixed m4b chapter generation opens CMD window in Windows.
+
+# v1.0.5
+- Added new output format: `m4b`, enabling chapter metadata in audiobooks. Special thanks to @jborza for implementing this feature in PR #10.
+- Better approach for determining the correct configuration folder for Linux and MacOS, using platformdirs. (Fixes Docker issue #12)
+- Improvements in documentation and code.
+
+# v1.0.4
+- Merge pull request [#7](https://github.com/denizsafak/abogen/pull/7) by @jborza that improves voice preview and documentation.
+- Fixed the issue when a voice is selected, the voice mixer tries to pre-select that voice and ignores existing profiles.
+- Fixed the error while renaming the default "New profile" in the voice mixer.
+- Fixed subtitle_combo enabling/disabling when a voice in the voice mixer is selected.
+- Prevented using special characters in the profile name to avoid conflicts.
+- Improved invalid profile handling in the voice mixer.
+
+# v1.0.3
+- Added voice mixing, allowing multiple voices to be combined into a single "Mixed Voice", a feature mentioned by @PulsarFTW in #1. Special thanks to @jborza for making this possible through his contributions in #5.
+- Added profile system to voice mixer, allowing users to create and manage multiple voice profiles.
+- Improvements in the voice mixer, mostly for organizing controls and enhancing user experience.
+- Added icons for flags and genders in the GUI, making it easier to identify different options.
+- Improved the content and chapter extraction process for EPUB files, ensuring better handling of various structures.
+- Switched to platformdirs for determining the correct desktop path, instead of using old methods.
+- Fixed preview voices was not using GPU acceleration, which was causing performance issues.
+- Improvements in code and documentation.
+
+# v1.0.2
 - Enhanced EPUB handling by treating all items in chapter list (including anchors) as chapters, improving navigation and organization for poorly structured books, mentioned by @Darthagnon in #4
 - Fixed the issue with some chapters in EPUB files had missing content.
 - Fixed the issue with some EPUB files only having one chapter caused the program to ignore the entire book.
 - Fixed "utf-8' codec can't decode byte" error, mentioned by @nigelp in #3
 - Added "Replace single newlines with spaces" option in the menu. This can be useful for texts that have imaginary line breaks.
-- Improvements in code and documentation.
+- Improvements in code and documentation.
+
+# v1.0.1
+- Added abogen-cli command for better troubleshooting and error handling.
+- Switched from setuptools to hatchling for packaging.
+- Added classifiers to the package metadata.
+- Fixed "No module named 'docopt'" and "setuptools.build_meta" import errors while using .bat installer in Windows, mentioned by @nigelp in #2
+- Improvements in code and documentation.

README.md

@@ -2,122 +2,749 @@
 
 [![Build Status](https://github.com/denizsafak/abogen/actions/workflows/test_pip.yml/badge.svg)](https://github.com/denizsafak/abogen/actions)
 [![GitHub Release](https://img.shields.io/github/v/release/denizsafak/abogen)](https://github.com/denizsafak/abogen/releases/latest)
-![abogen PyPi Python Versions](https://img.shields.io/pypi/pyversions/abogen)
+[![Abogen PyPi Python Versions](https://img.shields.io/pypi/pyversions/abogen)](https://pypi.org/project/abogen/)
 [![Operating Systems](https://img.shields.io/badge/os-windows%20%7C%20linux%20%7C%20macos%20-blue)](https://github.com/denizsafak/abogen/releases/latest)
+[![PyPi Total Downloads](https://img.shields.io/pepy/dt/abogen?label=downloads%20(pypi)&color=blue)](https://pypi.org/project/abogen/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![License: MIT](https://img.shields.io/badge/License-MIT-maroon.svg)](https://opensource.org/licenses/MIT)
 
-Abogen is a powerful text-to-speech conversion tool that makes it easy to turn ePub, PDF, or text files into high-quality audio with matching subtitles in seconds. Use it for audiobooks, voiceovers for Instagram, YouTube, TikTok, or any project that needs natural-sounding text-to-speech, using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M).
+<a href="https://trendshift.io/repositories/14433" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14433" alt="denizsafak%2Fabogen | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+
+Abogen is a powerful text-to-speech conversion tool that makes it easy to turn ePub, PDF, text, markdown, or subtitle files into high-quality audio with matching subtitles in seconds. Use it for audiobooks, voiceovers for Instagram, YouTube, TikTok, or any project that needs natural-sounding text-to-speech, using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M).
 
 <img title="Abogen Main" src='https://raw.githubusercontent.com/denizsafak/abogen/refs/heads/main/demo/abogen.png' width="380"> <img title="Abogen Processing" src='https://raw.githubusercontent.com/denizsafak/abogen/refs/heads/main/demo/abogen2.png' width="380">
 
 ## Demo
-https://github.com/user-attachments/assets/cb66512d-0a52-48c3-bda4-f1e6a03fb8d6
 
+https://github.com/user-attachments/assets/094ba3df-7d66-494a-bc31-0e4b41d0b865
 
-> This demo was generated in just 5 seconds, producing ∼1 minute of audio with perfectly synced subtitles. To create a similar video, see [the demo guide](https://github.com/denizsafak/abogen/tree/main/demo).
+> This demo was generated in just 5 seconds, producing ~1 minute of audio with perfectly synced subtitles. To create a similar video, see [the demo guide](https://github.com/denizsafak/abogen/tree/main/demo).
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+  - [Windows](#windows)
+  - [macOS](#macos)
+  - [Linux](#linux)
+- [Interfaces](#interfaces)
+- [Desktop Application (PyQt)](#️-desktop-application-pyqt)
+  - [How to Run](#how-to-run)
+  - [How to Use](#how-to-use)
+  - [Configuration Options](#configuration-options)
+  - [Voice Mixer](#voice-mixer)
+  - [Queue Mode](#queue-mode)
+- [Web Application (WebUI)](#-web-application-webui)
+  - [How to Run](#how-to-run-1)
+  - [How to Use](#how-to-use-1)
+  - [Docker / Container](#container-image)
+  - [LLM Text Normalization](#llm-assisted-text-normalization)
+  - [Audiobookshelf Integration](#audiobookshelf-integration)
+  - [JSON API Endpoints](#json-endpoints)
+- [Core Features](#core-features)
+  - [Chapter Markers](#chapter-markers)
+  - [Metadata Tags](#metadata-tags)
+  - [Timestamp-based Text Files](#timestamp-based-text-files)
+  - [Supported Languages](#supported-languages)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Credits](#credits)
+- [License](#license)
+
+---
+
+## Installation
+
+> **Requirements:** Python 3.10-3.12 is required. [uv](https://docs.astral.sh/uv/getting-started/installation/) is the recommended package manager as it handles Python versions and dependencies automatically.
 
-## `How to install?`
 ### Windows
-Go to [espeak-ng latest release](https://github.com/espeak-ng/espeak-ng/releases/latest) download and run the *.msi file.
+
+#### Step 1: Install espeak-ng
+
+espeak-ng is a required speech synthesis engine. Download the latest `.msi` installer from the [espeak-ng releases page](https://github.com/espeak-ng/espeak-ng/releases/latest) and run it.
+
+#### Step 2: Install Abogen
+
+Choose the method that works best for you:
+
+<details>
+<summary><b>Option A: Automatic installer (easiest, no setup required)</b></summary>
+
+This is the simplest option. It sets up everything automatically, including Python and CUDA support, without touching your system Python installation.
+
+1. [Download the repository as a ZIP](https://github.com/denizsafak/abogen/archive/refs/heads/main.zip) and extract it anywhere you like.
+2. Open the extracted folder and double-click `WINDOWS_INSTALL.bat`.
+3. Wait for the installation to finish. A shortcut to launch Abogen will be created in the folder.
+
+> You do not need to install Python separately. The script handles it for you.
+
+</details>
+
+<details>
+<summary><b>Option B: Install with uv (recommended for developers)</b></summary>
+
+First, [install uv](https://docs.astral.sh/uv/getting-started/installation/) if you have not already. Then run the command that matches your GPU:
+
 ```bash
+# NVIDIA GPU - CUDA 12.8 (most common, recommended)
+uv tool install --python 3.12 abogen[cuda] --extra-index-url https://download.pytorch.org/whl/cu128 --index-strategy unsafe-best-match
+
+# NVIDIA GPU - CUDA 12.6 (if the above does not work with your older drivers)
+uv tool install --python 3.12 abogen[cuda126] --extra-index-url https://download.pytorch.org/whl/cu126 --index-strategy unsafe-best-match
+
+# NVIDIA GPU - CUDA 13.0 (for the newest drivers)
+uv tool install --python 3.12 abogen[cuda130] --extra-index-url https://download.pytorch.org/whl/cu130 --index-strategy unsafe-best-match
+
+# No GPU / CPU only
+uv tool install --python 3.12 abogen
+```
+
+> AMD GPUs are not supported on Windows. If you have an AMD GPU, you can use Linux with ROCm instead.
+
+</details>
+
+<details>
+<summary><b>Option C: Install with pip</b></summary>
+
+It is recommended to use a virtual environment to avoid conflicts with other Python packages.
+
+```bash
+# Create and activate a virtual environment
+mkdir abogen && cd abogen
+python -m venv venv
+venv\Scripts\activate
+
 # For NVIDIA GPUs:
-pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
+# Install PyTorch with CUDA support
+pip install torch==2.8.0+cu128 torchvision==0.23.0+cu128 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128
 
-# Install abogen
+# Install Abogen
 pip install abogen
 ```
-Alternatively, for an easier setup on Windows:
-1. [Download](https://github.com/denizsafak/abogen/archive/refs/heads/main.zip) the repository
-2. Extract the ZIP file
-3. Run `WINDOWS_INSTALL.bat` by double-clicking it
 
-This method handles everything automatically - installing all dependencies including CUDA in a self-contained environment without requiring a separate Python installation. (You still need to install [espeak-ng](https://github.com/espeak-ng/espeak-ng/releases/latest).)
+> If you do not have an NVIDIA GPU, skip the PyTorch step and go straight to `pip install abogen`.
+
+</details>
+
+**Common issues on Windows:**
+- [How to fix "[WinError 1114] A dynamic link library (DLL) initialization routine failed" error?](#winError-1114-a-dynamic-link-library-dll-initialization-routine-failed)
+- [How to fix "CUDA GPU is not available. Using CPU" warning?](#cuda-gpu-is-not-available-using-cpu)
+
+---
+
+### macOS
+
+#### Step 1: Install espeak-ng
+
+Open a terminal and run:
 
-### Mac
 ```bash
-# Install espeak-ng
 brew install espeak-ng
-
-# Install abogen
-pip install abogen # (I have not tested it)
 ```
-### Linux
+
+> If you do not have Homebrew installed, follow the instructions at [brew.sh](https://brew.sh) first.
+
+#### Step 2: Install Abogen
+
+<details>
+<summary><b>Install with uv (recommended)</b></summary>
+
+First, [install uv](https://docs.astral.sh/uv/getting-started/installation/) if you have not already. Then run the command that matches your Mac:
+
 ```bash
-# Install espeak-ng
+# Apple Silicon (M1, M2, M3, M4, etc.)
+uv tool install --python 3.13 abogen --with "kokoro @ git+https://github.com/hexgrad/kokoro.git,numpy<2"
 
-# Ubuntu/Debian
-sudo apt install espeak-ng
-# Arch Linux
-sudo pacman -S espeak-ng
-# Fedora
-sudo dnf install espeak-ng
-
-# Install abogen
-pip install abogen
+# Intel Mac
+uv tool install --python 3.12 abogen --with "kokoro @ git+https://github.com/hexgrad/kokoro.git,numpy<2"
 ```
-> If you get "No matching distribution found" error, try installing it on supported Python (3.10 to 3.12). You can use [pyenv](https://github.com/pyenv/pyenv) to manage multiple Python versions easily in Linux. Watch this [video](https://www.youtube.com/watch?v=MVyb-nI4KyI) by NetworkChuck for a quick guide.
 
-Then simply run by typing:
+</details>
+
+<details>
+<summary><b>Install with pip</b></summary>
+
+```bash
+# Create and activate a virtual environment
+mkdir abogen && cd abogen
+python3 -m venv venv
+source venv/bin/activate
+
+# Install Abogen
+pip3 install abogen
+
+# Apple Silicon only: install the development version of Kokoro for MPS (GPU) support
+pip3 install git+https://github.com/hexgrad/kokoro.git
+```
+
+</details>
+
+---
+
+### Linux
+
+#### Step 1: Install espeak-ng
+
+Open a terminal and run the command for your distro:
+
+```bash
+sudo apt install espeak-ng      # Ubuntu / Debian
+sudo pacman -S espeak-ng        # Arch Linux
+sudo dnf install espeak-ng      # Fedora
+```
+
+#### Step 2: Install Abogen
+
+<details>
+<summary><b>Install with uv (recommended)</b></summary>
+
+First, [install uv](https://docs.astral.sh/uv/getting-started/installation/) if you have not already. Then run the command that matches your GPU:
+
+```bash
+# For NVIDIA GPUs or without GPU - No need to include [cuda] in here.
+uv tool install --python 3.12 abogen
+
+# For AMD GPUs (ROCm 6.4)
+uv tool install --python 3.12 abogen[rocm] --extra-index-url https://download.pytorch.org/whl/nightly/rocm6.4 --index-strategy unsafe-best-match
+```
+
+> Unlike Windows, CUDA support is included automatically on Linux with the standard install. No extra flags are needed for NVIDIA GPUs.
+
+</details>
+
+<details>
+<summary><b>Install with pip</b></summary>
+
+```bash
+# Create and activate a virtual environment
+mkdir abogen && cd abogen
+python3 -m venv venv
+source venv/bin/activate
+
+# Install Abogen (NVIDIA GPU support is included automatically)
+pip3 install abogen
+
+# AMD GPU only: replace the default PyTorch with the ROCm build
+pip3 uninstall torch
+pip3 install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm6.4
+```
+
+</details>
+
+#### Step 3: Add Abogen to your PATH (if needed)
+
+If you installed with uv or pip and the `abogen` command is not found after installation, run:
+
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
+```
+
+**Common issues on Linux:**
+- [How to fix "CUDA GPU is not available. Using CPU" warning?](#cuda-gpu-is-not-available-using-cpu)
+- [How to fix "WARNING: The script abogen-cli is installed in '/home/username/.local/bin' which is not on PATH" error?](#warning-the-script-abogen-cli-is-installed-in-homeusernamelocalbinwhich-is-not-on-path)
+- [How to fix "No matching distribution found" error?](#no-matching-distribution-found)
+
+---
+
+## Interfaces
+
+Abogen offers **two interfaces** with different feature sets. The Web UI includes newer features that are still being integrated into the desktop app.
+
+| Command | Interface | Description |
+|---------|-----------|-------------|
+| `abogen` | PyQt6 Desktop GUI | Stable core features |
+| `abogen-web` | Flask Web UI | Core features + **Supertonic TTS**, **LLM Normalization**, **Audiobookshelf Integration**, and more |
+
+> **Note:** The Web UI is under active development. Until the new features are merged into the desktop app, the Web UI provides the most complete experience. Special thanks to [@jeremiahsb](https://github.com/jeremiahsb) for his [massive contribution](https://github.com/denizsafak/abogen/pull/120) (>55,000 lines!) that brought the entire Web UI to life.
+
+---
+
+## 🖥️ `Desktop Application (PyQt)`
+
+### How to Run
 
 ```bash
 abogen
 ```
 
-## `How to use?`
-1) Drag and drop any ePub, PDF, or text file (or use the built-in text editor)
-2) Configure the settings:
-    - Set speech speed
-    - Select a voice
-    - Select subtitle generation style (by sentence, word, etc.)
-    - Select output format
-    - Select where to save the output
-3) Hit Start
+> If you used the Windows installer, a shortcut was created in the install folder or on your desktop. You can also run `python_embedded/Scripts/abogen.exe` directly.
 
-## `In action`
-<img title="Abogen in action" src='https://raw.githubusercontent.com/denizsafak/abogen/refs/heads/main/demo/abogen.gif'> 
+### How to Use
 
-Here’s Abogen in action: in this demo, it processes ∼3,000 characters of text in just 11 seconds and turns it into 3 minutes and 28 seconds of audio, and I have a low-end **RTX 2060 Mobile laptop GPU**. Your results may vary depending on your hardware.
+1. **Drop a file:** drag and drop an ePub, PDF, `.txt`, `.md`, or subtitle file into the window, or type directly into the built-in text editor.
+2. **Configure:** set the speech speed, voice, subtitle style, output format, and save location.
+3. **Hit Start.**
 
-## `Key Features`
-- **Supported formats**: `ePub`, `PDF`, or `.TXT` files (or use built-in text editor)
-- **Speed**: Adjust speech rate from `0.1x` to `2.0x`
-- **Voices**: First letter of the language code (e.g., `a` for American English, `b` for British English, etc.), second letter is for `m` for male and `f` for female.
-- **Generate subtitles**: `Disabled`, `Sentence`, `Sentence + Comma`, `1 word`, `2 words`, `3 words`, etc. (Represents the number of words in each subtitle entry)
-- **Output formats**: `.WAV`, `.FLAC`, or `.MP3`
-- **Save location**: `Save next to input file`, `Save to desktop`, or `Choose output folder`
-- **Chapter Control**: Select specific `chapters` from ePUBs or `chapters + pages` from PDFs.
-- **Options**:
-    - **Replace single newlines with spaces**: Replaces single newlines with spaces in the text. This is useful for texts that have imaginary line breaks.
-    - **Configure max words per subtitle**: Automatically configures the maximum number of words per subtitle entry.
-    - **Create desktop shortcut**: Creates a shortcut on your desktop for easy access.
-    - **Open config.json directory**: Opens the directory where the configuration file is stored.
-    - **Open temp directory**: Opens the temporary directory where converted text files are stored.
-    - **Clear all teporary files**: Deletes all temporary files created during the conversion process.
-    - **Check for updates at startup**: Automatically checks for updates when the program starts.
-- **After conversion**: `Open file`, `Go to folder`, `New conversion`, or `Go back`.
+<img title="Abogen in action" src='https://raw.githubusercontent.com/denizsafak/abogen/refs/heads/main/demo/abogen.gif'>
 
-## `Supported Languages`
+Here’s Abogen in action: in this demo, it processes ∼3,000 characters of text in just 11 seconds and turns it into 3 minutes and 28 seconds of audio, and I have a low-end **RTX 2060 Mobile laptop GPU**. Your results may vary depending on your hardware.
+
+---
+
+### Configuration Options
+
+#### Input and Output
+
+| Option | Description |
+|--------|-------------|
+| **Input Box** | Drag and drop `ePub`, `PDF`, `.TXT`, `.MD`, `.SRT`, `.ASS`, or `.VTT` files, or use the built-in text editor |
+| **Queue** | Add multiple files and process them in batch with individual settings per file. See [Queue Mode](#queue-mode) |
+| **Speed** | Adjust speech rate from `0.1x` to `2.0x` |
+| **Output voice format** | `.WAV`, `.FLAC`, `.MP3`, `.OPUS` (best compression), or `M4B` (with chapters) |
+| **Output subtitle format** | `SRT (standard)`, `ASS (wide)`, `ASS (narrow)`, `ASS (centered wide)`, `ASS (centered narrow)` |
+| **Save location** | Save next to the input file, to the desktop, or pick a custom folder |
+
+#### Voice
+
+| Option | Description |
+|--------|-------------|
+| **Select Voice** | First letter sets the language (`a` = American English, `b` = British English, etc.), second letter sets the gender (`m` = male, `f` = female) |
+| **Voice Mixer** | Blend multiple voice models together and save the result as a reusable profile. See [Voice Mixer](#voice-mixer) |
+| **Voice Preview** | Listen to the selected voice before starting a full conversion |
+
+#### Subtitles
+
+| Option | Description |
+|--------|-------------|
+| **Generate Subtitles** | `Disabled`, `Line`, `Sentence`, `Sentence + Comma`, `Sentence + Highlighting`, or word-count modes like `1 word`, `2 words`, `3 words`, etc. |
+| **Replace single newlines** | Replaces single newlines with spaces, which is useful for texts that have artificial line breaks |
+
+#### Book and Chapter Options
+
+| Option | Description |
+|--------|-------------|
+| **Chapter Control** | Select specific chapters from ePUBs or markdown files, or chapters and pages from PDFs |
+| **Save each chapter separately** | Output a separate audio file for each chapter |
+| **Create a merged version** | Combine all chapters into a single audio file |
+| **Save in a project folder** | Save the output alongside available metadata files |
+
+#### Advanced Options (Menu)
+
+| Option | Description |
+|--------|-------------|
+| **Theme** | `System`, `Light`, or `Dark` |
+| **Max words per subtitle** | Sets the maximum number of words per subtitle entry |
+| **Silence between chapters** | Sets how many seconds of silence to insert between chapters |
+| **Subtitle speed adjustment** | `TTS Regeneration` (better quality) or `FFmpeg Time-stretch` (faster) for subtitle files |
+| **Use spaCy for segmentation** | Uses [spaCy](https://spacy.io/) for more accurate sentence boundaries. Recommended for `Sentence` and `Sentence + Comma` modes |
+| **Silent gaps between subtitles** | Lets speech naturally continue into the gap instead of speeding up audio to match exact subtitle timing |
+| **Pre-download models** | Downloads all models and voices so Abogen can run fully offline |
+| **Disable Kokoro internet access** | Prevents Kokoro from fetching models from HuggingFace Hub |
+| **Cache / Config** | Open or clear the cache and configuration directories |
+
+---
+
+### Voice Mixer
+
+<img title="Abogen Voice Mixer" src='https://raw.githubusercontent.com/denizsafak/abogen/refs/heads/main/demo/voice_mixer.png'>
+
+The Voice Mixer lets you blend multiple voice models together, control the weight of each one, and save the result as a named profile for future use.
+
+> Thanks to [@jborza](https://github.com/jborza) for making this possible in [#5](https://github.com/denizsafak/abogen/pull/5).
+
+---
+
+### Queue Mode
+
+<img title="Abogen queue mode" src='https://raw.githubusercontent.com/denizsafak/abogen/refs/heads/main/demo/queue.png'>
+
+Queue mode lets you line up multiple files and convert them all in one go:
+
+- Add `.txt`, `.srt`, `.ass`, or `.vtt` files using the **Add files** button or by dragging them in. For PDF, EPUB, or markdown files, use the main input box and click **Add to Queue**.
+- Each file in the queue keeps the settings that were active when it was added.
+- Enable **Override item settings** to apply the current main-window configuration to all queued items.
+- Hover over any item in the queue to see its saved settings.
+
+> Thanks to [@jborza](https://github.com/jborza) for adding queue mode in [#35](https://github.com/denizsafak/abogen/pull/35).
+
+---
+
+## 🌐 `Web Application (WebUI)`
+
+### How to Run
+
+```bash
+abogen-web
 ```
-# 🇺🇸 'a' => American English, 🇬🇧 'b' => British English
-# 🇪🇸 'e' => Spanish es
-# 🇫🇷 'f' => French fr-fr
-# 🇮🇳 'h' => Hindi hi
-# 🇮🇹 'i' => Italian it
-# 🇯🇵 'j' => Japanese: pip install misaki[ja]
-# 🇧🇷 'p' => Brazilian Portuguese pt-br
-# 🇨🇳 'z' => Mandarin Chinese: pip install misaki[zh]
+
+Then open [http://localhost:8808](http://localhost:8808) in your browser. Jobs run in a background worker and the page updates automatically.
+
+<img title="Abogen Web UI" src='https://raw.githubusercontent.com/denizsafak/abogen/refs/heads/main/demo/abogen-webui.png'>
+
+### How to Use
+
+1. Upload a document by dragging and dropping it or using the upload button.
+2. Choose your voice, language, speed, subtitle style, and output format.
+3. Click **Create job**. It will appear in the queue right away.
+4. Watch live progress and logs update as the job runs. Download the audio and subtitle files when done.
+5. Cancel or delete jobs at any time. Logs can be downloaded for troubleshooting.
+
+Jobs are processed one at a time, in the order they were added.
+
+---
+
+### Container Image
+
+```bash
+docker build -t abogen .
+mkdir -p ~/abogen-data/uploads ~/abogen-data/outputs
+docker run --rm \
+  -p 8808:8808 \
+  -v ~/abogen-data:/data \
+  --name abogen \
+  abogen
 ```
+
+Browse to [http://localhost:8808](http://localhost:8808). Uploaded source files are stored in `/data/uploads` and finished audio or subtitle files go to `/data/outputs`.
+
+#### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ABOGEN_HOST` | `0.0.0.0` | Flask bind address |
+| `ABOGEN_PORT` | `8808` | HTTP port |
+| `ABOGEN_DEBUG` | `false` | Enable Flask debug mode |
+| `ABOGEN_UPLOAD_ROOT` | `/data/uploads` | Where uploaded source files are stored |
+| `ABOGEN_OUTPUT_DIR` | `/data/outputs` | Where finished audio and subtitles are saved |
+| `ABOGEN_SETTINGS_DIR` | `/config` | JSON settings and configuration |
+| `ABOGEN_TEMP_DIR` | `/data/cache` | Temporary working files during conversion |
+| `ABOGEN_UID` / `ABOGEN_GID` | `1000` / `1000` | User and group IDs inside the container. Set these to match your host user to avoid file permission issues |
+| `ABOGEN_LLM_BASE_URL` | `""` | Base URL of an OpenAI-compatible LLM endpoint |
+| `ABOGEN_LLM_API_KEY` | `""` | API key for the LLM endpoint |
+| `ABOGEN_LLM_MODEL` | `""` | Default model to use for LLM normalization |
+| `ABOGEN_LLM_TIMEOUT` | `30` | Timeout in seconds for LLM requests |
+| `ABOGEN_LLM_CONTEXT_MODE` | `sentence` | How much context to send to the LLM: `sentence`, `paragraph`, or `document` |
+| `ABOGEN_LLM_PROMPT` | `""` | Custom normalization prompt template |
+
+To find your host UID and GID:
+```bash
+id -u && id -g
+```
+
+#### Docker Compose (GPU)
+
+The repo includes `docker-compose.yaml` set up for GPU hosts. Install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) first, then:
+
+```bash
+docker compose up -d --build
+```
+
+Key build options:
+
+| Variable | Purpose |
+|----------|---------|
+| `TORCH_VERSION` | Pin a specific PyTorch release to match your driver |
+| `TORCH_INDEX_URL` | Use a different PyTorch download index for a specific CUDA build |
+| `ABOGEN_DATA` | Host path for uploads and outputs (default: `./data`) |
+
+For **CPU-only** deployment, comment out the `deploy.resources.reservations.devices` block in the compose file.
+
+---
+
+### LLM-Assisted Text Normalization
+
+Abogen can use an OpenAI-compatible LLM to clean up tricky text before synthesis, such as apostrophes, contractions, and abbreviations. Configure it at **Settings -> LLM**:
+
+1. Enter your endpoint base URL (for example, `http://localhost:11434` for Ollama). Abogen appends `/v1/...` automatically.
+2. Click **Refresh models**, pick a model, and adjust the timeout or prompt template if needed.
+3. Use the preview box to test it, then save.
+
+When running in Docker or a CI pipeline, you can pre-fill the form using `ABOGEN_LLM_*` environment variables. See `.env.example` for sample Ollama values.
+
+---
+
+### Audiobookshelf Integration
+
+Finished audiobooks can be sent directly to your [Audiobookshelf](https://www.audiobookshelf.org/) server from **Settings -> Integrations -> Audiobookshelf**:
+
+| Field | Description |
+|-------|-------------|
+| **Base URL** | Your ABS server address, e.g. `https://abs.example.com`. Do **not** append `/api` |
+| **Library ID** | Found on the library's settings page in ABS |
+| **Folder** | The destination folder name or ID. Click **Browse folders** to pick one from a list |
+| **API Token** | A personal access token from ABS, found under *Account -> API tokens* |
+
+You can enable automatic uploads for all future jobs, or trigger uploads manually from the job queue.
+
+<details>
+<summary><b>Reverse proxy setup for Nginx Proxy Manager</b></summary>
+
+1. Create a **Proxy Host** pointing to your ABS container (default forward port: `13378`).
+2. Under **SSL**, enable your certificate and optionally enable **Force SSL**.
+3. In the **Advanced** tab, paste the following:
+
+```nginx
+proxy_set_header Host $host;
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_set_header X-Forwarded-Host $host;
+proxy_set_header X-Forwarded-Port $server_port;
+proxy_set_header Authorization $http_authorization;
+client_max_body_size 5g;
+proxy_read_timeout 300s;
+proxy_connect_timeout 300s;
+```
+
+4. Disable **Block Common Exploits**, as it strips `Authorization` headers in some NPM versions.
+5. Enable **Websockets Support** on the main proxy screen.
+6. If ABS is served under a path prefix like `/abs`, add a **Custom Location** with `Location: /abs/` and set the **Forward Path** to `/`.
+
+To check that everything is working:
+```bash
+curl -i "https://abs.example.com/api/libraries" \
+  -H "Authorization: Bearer YOUR_API_TOKEN"
+```
+
+A JSON response with library data confirms the proxy is set up correctly. You can then use **Browse folders** and **Test connection** inside Abogen's settings to verify the full integration.
+
+</details>
+
+---
+
+### JSON Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/jobs/<id>` | Returns job metadata, progress, and log lines as JSON |
+| `GET /partials/jobs` | Returns the live job list as HTML (used by htmx for polling) |
+| `GET /partials/jobs/<id>/logs` | Returns the log window for a specific job |
+
+More automation endpoints are planned. Contributions are welcome.
+
+---
+
+## Core Features
+
+### Chapter Markers
+
+When you process ePUB, PDF or markdown files, Abogen converts them into text files stored in your cache directory. When you click "Edit," you're actually modifying these converted text files. In these text files, you'll notice tags that look like this:
+
+```
+<<CHAPTER_MARKER:Chapter Title>>
+```
+These are chapter markers. They are automatically added when you process ePUB, PDF or markdown files, based on the chapters you select. They serve an important purpose:
+-  Allow you to split the text into separate audio files for each chapter
+-  Save time by letting you reprocess only specific chapters if errors occur, rather than the entire file
+
+You can manually add these markers to plain text files for the same benefits. Simply include them in your text like this:
+
+```
+<<CHAPTER_MARKER:Introduction>>
+This is the beginning of my text...
+
+<<CHAPTER_MARKER:Main Content>>
+Here is another section...
+```
+When you process the text file, Abogen will detect these markers automatically and ask if you want to save each chapter separately and create a merged version.
+
+![Abogen Chapter Marker](https://raw.githubusercontent.com/denizsafak/abogen/refs/heads/main/demo/chapter_marker.png)
+
+## Metadata Tags
+Similar to chapter markers, it is possible to add metadata tags for `M4B` files. This is useful for audiobook players that support metadata, allowing you to add information like title, author, year, etc. Abogen automatically adds these tags when you process ePUB, PDF or markdown files, but you can also add them manually to your text files. Add metadata tags **at the beginning of your text file** like this:
+```
+<<METADATA_TITLE:Title>>
+<<METADATA_ARTIST:Author>>
+<<METADATA_ALBUM:Album Title>>
+<<METADATA_YEAR:Year>>
+<<METADATA_ALBUM_ARTIST:Album Artist>>
+<<METADATA_COMPOSER:Narrator>>
+<<METADATA_GENRE:Audiobook>>
+<<METADATA_COVER_PATH:path/to/cover.jpg>>
+```
+> Note: `METADATA_COVER_PATH` is used to embed a cover image into the generated M4B file. Abogen automatically extracts the cover from EPUB and PDF files and adds this tag for you.
+
+---
+
+### Timestamp-based Text Files
+
+Similar to converting subtitle files to audio, Abogen can automatically detect text files that contain timestamps in `HH:MM:SS`, `HH:MM:SS,ms` or `HH:MM:SS.ms` format. When timestamps are found inside your text file, Abogen will ask if you want to use them for audio timing. This is useful for creating timed narrations, scripts, or transcripts where you need exact control over when each segment is spoken.
+
+Format your text file like this:
+```
+00:00:00
+This is the first segment of text.
+
+00:00:15
+This is the second segment, starting at 15 seconds.
+
+00:00:45
+And this is the third segment, starting at 45 seconds.
+```
+
+**Notes:**
+- Timestamps must be in `HH:MM:SS`, `HH:MM:SS,ms` or `HH:MM:SS.ms` format (e.g., `00:05:30` for 5 minutes 30 seconds, or `00:05:30.500` for 5 minutes 30.5 seconds)
+- Milliseconds are optional and provide precision up to 1/1000th of a second
+- Text before the first timestamp (if any) will automatically start at `00:00:00`
+- When using timestamps, the subtitle generation mode setting is ignored
+
+---
+
+### Supported Languages
+
+```
+🇺🇸 'a' - American English      🇬🇧 'b' - British English
+🇪🇸 'e' - Spanish (es)          🇫🇷 'f' - French (fr-fr)
+🇮🇳 'h' - Hindi                 🇮🇹 'i' - Italian
+🇯🇵 'j' - Japanese*             🇧🇷 'p' - Brazilian Portuguese
+🇨🇳 'z' - Mandarin Chinese*
+```
+
+> \* Requires extra packages: `pip install misaki[ja]` for Japanese, `pip install misaki[zh]` for Mandarin.
+
 For a complete list of supported languages and voices, refer to Kokoro's [VOICES.md](https://huggingface.co/hexgrad/Kokoro-82M/blob/main/VOICES.md). To listen to sample audio outputs, see [SAMPLES.md](https://huggingface.co/hexgrad/Kokoro-82M/blob/main/SAMPLES.md).
 
-## `MPV Config`
-I highly recommend using [MPV](https://mpv.io/installation/) to play your audio files, as it supports displaying subtitles even without a video track. Here's my `mpv.conf`:
+> **Note:** Word-level subtitle modes like `1 word` or `2 words` are only available for English, because Kokoro only provides timestamp tokens for English text. For other languages, Abogen falls back to duration-based timing that supports `Line`, `Sentence`, and `Sentence + Comma` modes.
+
+---
+
+## Troubleshooting
+
+For detailed error messages, run Abogen in CLI mode:
+
+```bash
+abogen-cli
+```
+
+If you used the Windows installer, navigate to `python_embedded/Scripts` and run `abogen-cli.exe` from there.
+
+If you cannot resolve the issue, please [open a GitHub issue](https://github.com/denizsafak/abogen/issues) and include the error output along with a description of what you were doing.
+
+---
+
+### Common Issues
+
+<details>
+<summary><b>How to fix "CUDA GPU is not available. Using CPU" warning?</b></summary>
+
+This means PyTorch could not find a supported GPU and fell back to the CPU. Abogen will still work, but conversion will be slower.
+
+**If you have a compatible NVIDIA GPU on Windows,** try reinstalling PyTorch with the right CUDA version:
+
+```bash
+# CUDA 12.8
+python_embedded\python.exe -m pip install --force-reinstall torch==2.8.0+cu128 torchvision==0.23.0+cu128 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128
+
+# CUDA 12.6 (for older GPUs that do not support CUDA 12.8)
+python_embedded\python.exe -m pip install --force-reinstall torch==2.8.0+cu126 torchvision==0.23.0+cu126 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu126
+```
+
+**If you installed with uv,** uninstall and reinstall with a different CUDA version:
+```bash
+uv tool uninstall abogen
+
+# Try CUDA 12.6 for older drivers
+uv tool install --python 3.12 abogen[cuda126] --extra-index-url https://download.pytorch.org/whl/cu126 --index-strategy unsafe-best-match
+
+# Or CUDA 13.0 for newer drivers
+uv tool install --python 3.12 abogen[cuda130] --extra-index-url https://download.pytorch.org/whl/cu130 --index-strategy unsafe-best-match
+```
+
+**If you have an AMD GPU,** you need to use Linux with ROCm. See the [Linux installation instructions](#linux). See [#32](https://github.com/denizsafak/abogen/issues/32) for more details.
+
+</details>
+
+<details>
+<summary><b>How to fix "WARNING: The script abogen-cli is installed in '/home/username/.local/bin' which is not on PATH" error in Linux?</b></summary>
+
+This means the directory where Abogen was installed is not included in your shell's PATH. Run the following command to add it permanently:
+
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
+```
+
+If you are using a different shell like Zsh or Fish, replace `~/.bashrc` with `~/.zshrc` or `~/.config/fish/config.fish` accordingly.
+
+</details>
+
+<details>
+<summary><b>How to fix "No matching distribution found" error?</b></summary>
+
+This usually means your Python version is not supported. Make sure you are using Python 3.10-3.12.
+
+Use [uv](https://docs.astral.sh/uv/getting-started/installation/) to manage Python versions automatically (it will install the right version for you), or use [pyenv](https://github.com/pyenv/pyenv) if you prefer to manage versions manually.
+
+</details>
+
+<details>
+<summary><b>How to fix "[WinError 1114] A dynamic link library (DLL) initialization routine failed" error?</b></summary>
+
+This error usually happens when PyTorch is installed with a CUDA version that does not match your GPU or driver.
+
+**If you used the Windows installer:**
+```bash
+python_embedded\python.exe -m pip install --force-reinstall torch==2.8.0+cu128 torchvision==0.23.0+cu128 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128
+```
+
+**If you used pip:**
+```bash
+pip install --force-reinstall torch==2.8.0 torchaudio==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128
+```
+
+If that does not work, try the CUDA 12.6 version instead by replacing `cu128` with `cu126` in the command above.
+
+</details>
+
+<details>
+<summary><b>How to fix Japanese audio not working?</b></summary>
+
+Japanese audio requires an additional package. Install it with:
+
+```bash
+pip install misaki[ja]
+```
+
+If the issue persists, see [#56](https://github.com/denizsafak/abogen/issues/56) for details and solutions from the community.
+
+</details>
+
+<details>
+<summary><b>How to uninstall Abogen?</b></summary>
+
+1. In the settings menu, open and delete the **configuration directory**.
+2. In the settings menu, open and delete the **cache directory**.
+3. Then uninstall the package:
+
+```bash
+# If installed with pip
+pip uninstall abogen
+pip cache purge
+
+# If installed with uv
+uv tool uninstall abogen
+uv cache clear
+```
+
+If you used the Windows installer, simply delete the Abogen folder. Everything is self-contained inside `python_embedded`, so no other directories are created elsewhere on your system.
+
+If you installed espeak-ng separately, you will need to uninstall it separately as well.
+
+</details>
+
+<details>
+<summary><b>About the name "abogen"</b></summary>
+
+The name is a shortened form of **"audiobook generator"**.
+
+After releasing the project, I learned from [community feedback](https://news.ycombinator.com/item?id=44853064#44857237) that the prefix *"abo"* can be read as an ethnic slur in certain regions, particularly in Australia and New Zealand. This was completely unintentional. English is not my first language, and the name was chosen only for its technical meaning. I am grateful to everyone who pointed this out, as it helps keep this project welcoming to all.
+
+</details>
+
+---
+
+## MPV Recommended Config
+
+[MPV](https://mpv.io/installation/) is highly recommended for playback, since it can display subtitles even for audio-only files. Here is a suggested `mpv.conf`:
+
 ```
 save-position-on-quit
 keep-open=yes
---audio-device=openal
---sub-margin-x=235
---sub-pos=60
+audio-display=no
+# --- Subtitle ---
+sub-ass-override=no
+sub-margin-y=50
+sub-margin-x=50
 # --- Audio Quality ---
 audio-spdif=ac3,dts,eac3,truehd,dts-hd
 audio-channels=auto
@@ -125,50 +752,80 @@ audio-samplerate=48000
 volume-max=200
 ```
 
-## `Similar Projects`
+---
+
+## Similar Projects
 Abogen is a standalone project, but it is inspired by and shares some similarities with other projects. Here are a few:
 - [audiblez](https://github.com/santinic/audiblez): Generate audiobooks from e-books. **(Has CLI and GUI support)**
 - [autiobooks](https://github.com/plusuncold/autiobooks): Automatically convert epubs to audiobooks
 - [pdf-narrator](https://github.com/mateogon/pdf-narrator): Convert your PDFs and EPUBs into audiobooks effortlessly.
 - [epub_to_audiobook](https://github.com/p0n1/epub_to_audiobook): EPUB to audiobook converter, optimized for Audiobookshelf
+- [ebook2audiobook](https://github.com/DrewThomasson/ebook2audiobook): Convert ebooks to audiobooks with chapters and metadata using dynamic AI models and voice cloning
 
-## `Roadmap`
-- [ ] Improve PDF support for better text extraction.
-- [ ] Add chapter metadata for .m4a files using ffmpeg-bin.
-- [ ] Add support for different languages in GUI.
-- [ ] Add voice formula feature that enables mixing different voice models. https://github.com/denizsafak/abogen/issues/1
-- [ ] Add support for kokoro-onnx.
-- [ ] Add dark mode.
+## Roadmap
 
-## `Troubleshooting`
-If you encounter any issues while running Abogen, try launching it from the command line with:
+- [ ] OCR scan support for PDF files (docling/tesseract)
+- [ ] Multi-language GUI support
+- [ ] kokoro-onnx support (if needed)
+- [x] Chapter metadata for `.m4b` files ([#10](https://github.com/denizsafak/abogen/pull/10))
+- [x] Voice mixer for blending voice models ([#5](https://github.com/denizsafak/abogen/pull/5))
+- [x] Dark mode
+
+---
+
+## Contributing
+
+Contributions are welcome. Fork the repository, make your changes, and open a pull request.
+
+To set up a local development environment:
+
+```bash
+pip install -e .[dev]   # Editable install with build dependencies
+python -m build         # Optional: builds the package in the dist folder
+abogen                  # Launch the GUI
 ```
-abogen-cli
-```
-This will start Abogen in command-line mode and display detailed error messages. Please open a new issue on the [Issues](https://github.com/denizsafak/abogen/issues) page with the error message and a description of your problem.
 
-## `Contributing`
-I welcome contributions! If you have ideas for new features, improvements, or bug fixes, please fork the repository and submit a pull request.
-### For developers and contributors
-If you'd like to modify the code and contribute to development, you can [download the repository](https://github.com/denizsafak/abogen/archive/refs/heads/main.zip), extract it and run the following commands to build **or** install the package:
+<details>
+<summary><b>Using uv</b></summary>
+
 ```bash
 # Go to the directory where you extracted the repository and run:
-pip install -e .      # Installs the package in editable mode
-python -m build       # Builds the package in dist folder
-abogen                # Opens the GUI
+uv venv --python 3.12       # Creates a virtual environment with Python 3.12
+# After activating the virtual environment, run:
+uv pip install -e .         # Installs the package in editable mode
+uv build                    # Builds the package in dist folder (optional)
+abogen                      # Opens the GUI
 ```
-Feel free to explore the code and make any changes you like.
 
-## `Credits`
+</details>
+
+> Use Python 3.10-3.12. Create a virtual environment if needed.
+
+---
+
+## Credits
+
+- Web UI implementation by [@jeremiahsb](https://github.com/jeremiahsb)
 - Abogen uses [Kokoro](https://github.com/hexgrad/kokoro) for its high-quality, natural-sounding text-to-speech synthesis. Huge thanks to the Kokoro team for making this possible.
+- Thanks to the [spaCy](https://spacy.io/) project for its sentence-segmentation tools, which help Abogen produce cleaner, more natural sentence segmentation.
 - Thanks to [@wojiushixiaobai](https://github.com/wojiushixiaobai) for [Embedded Python](https://github.com/wojiushixiaobai/Python-Embed-Win64) packages. These modified packages include pip pre-installed, enabling Abogen to function as a standalone application without requiring users to separately install Python in Windows.
+- Thanks to creators of [EbookLib](https://github.com/aerkalov/ebooklib), a Python library for reading and writing ePub files, which is used for extracting text from ePub files.
 - Special thanks to the [PyQt](https://www.riverbankcomputing.com/software/pyqt/) team for providing the cross-platform GUI toolkit that powers Abogen's interface.
+- Icons: [US](https://icons8.com/icon/aRiu1GGi6Aoe/usa), [Great Britain](https://icons8.com/icon/t3NE3BsOAQwq/great-britain), [Spain](https://icons8.com/icon/ly7tzANRt33n/spain), [France](https://icons8.com/icon/3muzEmi4dpD5/france), [India](https://icons8.com/icon/esGVrxg9VCJ1/india), [Italy](https://icons8.com/icon/PW8KZnP7qXzO/italy), [Japan](https://icons8.com/icon/McQbrq9qaQye/japan), [Brazil](https://icons8.com/icon/zHmH8HpOmM90/brazil), [China](https://icons8.com/icon/Ej50Oe3crXwF/china), [Female](https://icons8.com/icon/uI49hxbpxTkp/female), [Male](https://icons8.com/icon/12351/male), [Adjust](https://icons8.com/icon/21698/adjust) and [Voice Id](https://icons8.com/icon/GskSeVoroQ7u/voice-id) icons by [Icons8](https://icons8.com/).
+
+---
+
+## License
 
-## `License`
 This project is available under the MIT License - see the [LICENSE](https://github.com/denizsafak/abogen/blob/main/LICENSE) file for details.
 [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.
 
-> [!IMPORTANT]
-> Subtitle generation currently works only for English. This is because Kokoro provides timestamp tokens only for English text. If you want subtitles in other languages, please request this feature in the [Kokoro project](https://github.com/hexgrad/kokoro). For more technical details, see [this line](https://github.com/hexgrad/kokoro/blob/6d87f4ae7abc2d14dbc4b3ef2e5f19852e861ac2/kokoro/pipeline.py#L383) in the Kokoro's code.
+---
 
-> Tags: audiobook, kokoro, text-to-speech, TTS, audiobook generator, audiobooks, text to speech, audiobook maker, audiobook creator, audiobook generator, voice-synthesis, text to audio, text to audio converter, text to speech converter, text to speech generator, text to speech software, text to speech app, epub to audio, pdf to audio, content-creation, media-generation
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=denizsafak/abogen&type=Date)](https://www.star-history.com/#denizsafak/abogen&Date)
+
+---
+
+> Tags: audiobook, kokoro, text-to-speech, TTS, audiobook generator, audiobooks, text to speech, audiobook maker, audiobook creator, audiobook generator, voice-synthesis, text to audio, text to audio converter, text to speech converter, text to speech generator, text to speech software, text to speech app, epub to audio, pdf to audio, markdown to audio, subtitle to audio, srt to audio, ass to audio, vtt to audio, webvtt to audio, content-creation, media-generation

WINDOWS_INSTALL.bat

@@ -1,5 +1,5 @@
 @echo off
-setlocal
+setlocal EnableDelayedExpansion
 cd /d "%~dp0"
 
 :: Set misaki language
@@ -8,9 +8,6 @@ cd /d "%~dp0"
 :: Japanese: "ja"
 set MISAKI_LANG=en
 
-:: Set PyTorch CUDA version
-set CUDA_VERSION=128
-
 :::
 :::      _    ____   ___   ____  _____ _   _ 
 :::     / \  | __ ) / _ \ / ___|| ____| \ | |
@@ -23,7 +20,7 @@ set CUDA_VERSION=128
 for /f "delims=: tokens=*" %%A in ('findstr /b ::: "%~f0"') do @echo(%%A
 
 set CURRENT_DIR="%CD%"
-setlocal enabledelayedexpansion
+set "UV_CACHE_DIR=%~dp0.uv_cache"
 set NAME=abogen
 set PROJECTFOLDER=abogen
 set RUN=python_embedded\Scripts\abogen.exe
@@ -33,6 +30,28 @@ set refrenv=%PROJECTFOLDER%\refrenv.bat
 set PYTHON_PATH=python_embedded\pythonw.exe
 set PYTHON_CONSOLE_PATH=python_embedded\python.exe
 
+:: ---------------------------------------------------------
+:: Version Selection
+:: ---------------------------------------------------------
+echo.
+echo Select installation version:
+echo [1] Stable (PyPI)  - Safer, recommended for most users.
+echo [2] Dev (Local)    - Install from current folder (may include commits after the latest release).
+echo.
+choice /C 12 /M "Your choice"
+
+if errorlevel 2 (
+    set INSTALL_SOURCE=dev
+    echo.
+    echo Selected: Dev - Local Editable
+) else (
+    set INSTALL_SOURCE=pypi
+    echo.
+    echo Selected: Stable - PyPI
+)
+echo.
+:: ---------------------------------------------------------
+
 :: Check for updates
 echo Checking for updates...
 set VERSION_FILE=%PROJECTFOLDER%\VERSION
@@ -140,10 +159,10 @@ if exist "%VERSION_FILE%" (
 REM Python embedded download configuration for different architectures
 if "%PROCESSOR_ARCHITECTURE%"=="x86" (
     set PYTHON_EMBEDDED_FILE=%PROJECTFOLDER%\python_embedded_win32.zip
-    set PYTHON_EMBEDDED_URL=https://github.com/wojiushixiaobai/Python-Embed-Win64/releases/download/3.12.8/python-3.12.8-embed-win32.zip
+    set PYTHON_EMBEDDED_URL=https://github.com/wojiushixiaobai/Python-Embed-Win64/releases/download/3.12.12/python-3.12.12-embed-win32.zip
 ) else (
     set PYTHON_EMBEDDED_FILE=%PROJECTFOLDER%\python_embedded_amd64.zip
-    set PYTHON_EMBEDDED_URL=https://github.com/wojiushixiaobai/Python-Embed-Win64/releases/download/3.12.8/python-3.12.8-embed-amd64.zip
+    set PYTHON_EMBEDDED_URL=https://github.com/wojiushixiaobai/Python-Embed-Win64/releases/download/3.12.12/python-3.12.12-embed-amd64.zip
 )
 
 :: Check if Python exists
@@ -201,52 +220,82 @@ if not "%~1"=="" (
     echo Open with: "%~1"
 )
 
-:: Update pip
-echo Updating pip...
+:: Update pip and install uv
+echo Updating pip and installing uv...
 %PYTHON_CONSOLE_PATH% -m pip install --upgrade pip --no-warn-script-location
+%PYTHON_CONSOLE_PATH% -m pip install uv --no-warn-script-location
 if errorlevel 1 (
-    echo Failed to update pip.
+    echo Failed to install uv.
     pause
     exit /b
 )
 
 :: Install docopt's fixed version
 echo Installing fixed version of docopt...
-%PYTHON_CONSOLE_PATH% -m pip install --force-reinstall https://github.com/denizsafak/abogen/raw/refs/heads/main/abogen/resources/docopt-0.6.2-py2.py3-none-any.whl --no-warn-script-location
+%PYTHON_CONSOLE_PATH% -m uv pip install --system --force-reinstall https://github.com/denizsafak/abogen/raw/refs/heads/main/abogen/resources/docopt-0.6.2-py2.py3-none-any.whl
 if errorlevel 1 (
     echo Failed to install fixed version of docopt.
     pause
     exit /b
 )
 
+:: Install progress's fixed version
+echo Installing fixed version of progress...
+%PYTHON_CONSOLE_PATH% -m uv pip install --system --force-reinstall https://github.com/denizsafak/abogen/raw/refs/heads/main/abogen/resources/progress-1.6-py3-none-any.whl
+if errorlevel 1 (
+    echo Failed to install fixed version of progress.
+    pause
+    exit /b
+)
+
 :: Install setup requirements
 echo Installing setup requirements...
-%PYTHON_CONSOLE_PATH% -m pip install --upgrade setuptools wheel sphinx hatchling --no-warn-script-location
+%PYTHON_CONSOLE_PATH% -m uv pip install --system --upgrade setuptools setuptools-scm wheel sphinx hatchling editables
 if errorlevel 1 (
     echo Failed to install setup requirements.
     pause
     exit /b
 )
 
-:: Install project and dependencies from pyproject.toml
-echo Checking and installing project dependencies...
-if exist %PYPROJECT_FILE% (
-    echo Installing project from pyproject.toml...
-    %PYTHON_CONSOLE_PATH% -m pip install . --no-warn-script-location
+:: Install gpustat
+echo Installing gpustat...
+%PYTHON_CONSOLE_PATH% -m uv pip install --system gpustat
+if errorlevel 1 (
+    echo Failed to install gpustat.
+    pause
+    exit /b
+)
+
+:: Install project based on user selection
+if "%INSTALL_SOURCE%"=="pypi" (
+    echo Installing stable version from PyPI...
+    %PYTHON_CONSOLE_PATH% -m uv pip install --system abogen
     if errorlevel 1 (
-        echo Failed to install from pyproject.toml.
+        echo Failed to install abogen from PyPI.
         pause
         exit /b
     )
 ) else (
-    echo Warning: pyproject.toml not found in current directory.
-    pause
+    echo Checking and installing project dependencies...
+    if exist %PYPROJECT_FILE% (
+        echo Installing project from pyproject.toml using uv...
+        :: Using uv pip install --system --editable
+        %PYTHON_CONSOLE_PATH% -m uv pip install --system --editable .
+        if errorlevel 1 (
+            echo Failed to install from pyproject.toml.
+            pause
+            exit /b
+        )
+    ) else (
+        echo Warning: pyproject.toml not found in current directory.
+        pause
+    )
 )
 
-:: Install misaki again if MISAKI_LANG is not set to "en"
+:: Install misaki again if MISAKI_LANG is not set to "en" via uv
 if "%MISAKI_LANG%" NEQ "en" (
     echo Configuring language pack: %MISAKI_LANG%
-    %PYTHON_CONSOLE_PATH% -m pip install misaki[lang] --upgrade --no-warn-script-location
+    %PYTHON_CONSOLE_PATH% -m uv pip install --system misaki[%MISAKI_LANG%] --upgrade
     if errorlevel 1 (
         echo Failed to install misaki language pack.
         pause
@@ -254,21 +303,52 @@ if "%MISAKI_LANG%" NEQ "en" (
     )
 )
 
-:: Check if torch is installed with CUDA support
-echo Checking CUDA availability...
-for /f %%i in ('%PYTHON_CONSOLE_PATH% -c "from torch.cuda import is_available; print(is_available())"') do set cuda_available=%%i
+:: Check for NVIDIA GPU via is_nvidia()
+for /f %%i in ('%PYTHON_CONSOLE_PATH% -c "from abogen.is_nvidia import check; print(check())"') do set IS_NVIDIA=%%i
 
-if "%cuda_available%"=="False" (
-    echo Installing PyTorch with CUDA %CUDA_VERSION% support...
-    %PYTHON_CONSOLE_PATH% -m pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu%CUDA_VERSION% --no-warn-script-location
-    echo.
-    if errorlevel 1 (
-        echo Failed to install PyTorch.
-        pause
-        exit /b
+:: Check if torch is installed with CUDA support
+echo.
+echo Checking CUDA availability...
+if /I "%IS_NVIDIA%"=="true" (
+    for /f %%i in ('%PYTHON_CONSOLE_PATH% %PROJECTFOLDER%\check_cuda.py') do set cuda_available=%%i
+
+    if "%cuda_available%"=="False" (
+        echo "Installing PyTorch with CUDA (12.8) support..."
+        :: We need to use an older version of PyTorch (2.8.0) until this issue is fixed: https://github.com/pytorch/pytorch/issues/166628
+        :: Solution mentioned by @mazenemam19 in #99:
+        %PYTHON_CONSOLE_PATH% -m uv pip install --system torch==2.8.0+cu128 torchvision==0.23.0+cu128 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128
+        echo.
+        if errorlevel 1 (
+            echo Failed to install PyTorch.
+            pause
+            exit /b
+        )
+    ) else (
+        echo CUDA is available on NVIDIA GPU.
     )
 ) else (
-    echo CUDA is available.
+    echo.
+    echo Unable to detect an NVIDIA GPU in your system.
+    echo.
+    echo Do you want to install PyTorch anyway?
+    echo.
+    echo If you DO have an NVIDIA GPU, please press Y.
+    echo If you DO NOT have an NVIDIA GPU, please press N.
+    echo.
+    choice /C YN /M "Y=Yes, N=No"
+    if errorlevel 2 (
+        echo Skipping PyTorch installation.
+    ) else (
+        echo "Installing PyTorch with CUDA (12.8) support..."
+        :: We need to use an older version of PyTorch (2.8.0) until this issue is fixed: https://github.com/pytorch/pytorch/issues/166628
+        :: Solution mentioned by @mazenemam19 in #99:
+        %PYTHON_CONSOLE_PATH% -m uv pip install --system torch==2.8.0+cu128 torchvision==0.23.0+cu128 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128
+        if errorlevel 1 (
+            echo Failed to install PyTorch.
+            pause
+            exit /b
+        )
+    )
 )
 
 :: Ask user if they want to create a desktop shortcut

abogen/VERSION

@@ -1 +1 @@
-1.0.2
+1.3.1

abogen/assets/settings.svg

@@ -0,0 +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>
+</svg>

abogen/check_cuda.py

@@ -0,0 +1,30 @@
+import sys
+import os
+import platform
+import ctypes
+import importlib.util
+
+def check_cuda_with_fix():
+    """
+    Check if CUDA is available, with a fix for PyTorch DLL loading issue 
+    ([WinError 1114]) on Windows.
+    """
+    # Fix PyTorch DLL loading issue ([WinError 1114]) on Windows
+    try:
+        if platform.system() == "Windows":
+            spec = importlib.util.find_spec("torch")
+            if spec and spec.origin:
+                dll_path = os.path.join(os.path.dirname(spec.origin), "lib", "c10.dll")
+                if os.path.exists(dll_path):
+                    ctypes.CDLL(os.path.normpath(dll_path))
+    except Exception:
+        pass
+
+    try:
+        from torch.cuda import is_available
+        print(is_available())
+    except ImportError:
+        print("False")
+
+if __name__ == "__main__":
+    check_cuda_with_fix()

abogen/chunking.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterable, Iterator, List, Literal, Optional, Tuple
+from typing import Pattern
+
+import re
+
+from abogen.kokoro_text_normalization import ApostropheConfig, normalize_for_pipeline
+from abogen.normalization_settings import build_apostrophe_config, get_runtime_settings
+
+ChunkLevel = Literal["paragraph", "sentence"]
+
+_SENTENCE_SPLIT_REGEX = re.compile(r"(?<!\b[A-Z])[.!?][\s\n]+")
+_WHITESPACE_REGEX = re.compile(r"\s+")
+_PARAGRAPH_SPLIT_REGEX = re.compile(r"(?:\r?\n){2,}")
+_ABBREVIATION_END_RE = re.compile(
+    r"\b(?:Mr|Mrs|Ms|Dr|Prof|Rev|Sr|Jr|St|Gen|Lt|Col|Sgt|Capt|Adm|Cmdr|vs|etc)\.$",
+    re.IGNORECASE,
+)
+
+_PIPELINE_APOSTROPHE_CONFIG = ApostropheConfig()
+
+
+@dataclass(frozen=True)
+class Chunk:
+    id: str
+    chapter_index: int
+    chunk_index: int
+    level: ChunkLevel
+    text: str
+    speaker_id: str = "narrator"
+    voice: Optional[str] = None
+    voice_profile: Optional[str] = None
+    voice_formula: Optional[str] = None
+    display_text: Optional[str] = None
+
+    def as_dict(self) -> Dict[str, object]:
+        return {
+            "id": self.id,
+            "chapter_index": self.chapter_index,
+            "chunk_index": self.chunk_index,
+            "level": self.level,
+            "text": self.text,
+            "speaker_id": self.speaker_id,
+            "voice": self.voice,
+            "voice_profile": self.voice_profile,
+            "voice_formula": self.voice_formula,
+            "display_text": self.display_text,
+        }
+
+
+def _iter_paragraphs(text: str) -> Iterator[str]:
+    for raw_segment in _PARAGRAPH_SPLIT_REGEX.split(text.strip()):
+        normalized = raw_segment.strip()
+        if normalized:
+            yield normalized
+
+
+def _iter_sentences(paragraph: str) -> Iterator[Tuple[str, str]]:
+    if not paragraph:
+        return
+    start = 0
+    for match in _SENTENCE_SPLIT_REGEX.finditer(paragraph):
+        end = match.end()
+        raw_segment = paragraph[start:end]
+        candidate = raw_segment.strip()
+        if candidate:
+            yield candidate, raw_segment
+        start = match.end()
+    tail_raw = paragraph[start:]
+    tail = tail_raw.strip()
+    if tail:
+        yield tail, tail_raw
+
+
+def _normalize_whitespace(value: str) -> str:
+    return _WHITESPACE_REGEX.sub(" ", value).strip()
+
+
+def _normalize_chunk_text(value: str) -> str:
+    settings = get_runtime_settings()
+    config = build_apostrophe_config(
+        settings=settings, base=_PIPELINE_APOSTROPHE_CONFIG
+    )
+    normalized = normalize_for_pipeline(value, config=config, settings=settings)
+    return _normalize_whitespace(normalized)
+
+
+def _split_sentences(paragraph: str) -> List[Tuple[str, str]]:
+    sentences = list(_iter_sentences(paragraph))
+    if not sentences:
+        return []
+
+    merged: List[Tuple[str, str]] = []
+    buffer_norm: List[str] = []
+    buffer_raw: List[str] = []
+
+    for normalized_sentence, raw_sentence in sentences:
+        if buffer_norm:
+            buffer_norm.append(normalized_sentence)
+            buffer_raw.append(raw_sentence)
+        else:
+            buffer_norm = [normalized_sentence]
+            buffer_raw = [raw_sentence]
+
+        if _ABBREVIATION_END_RE.search(normalized_sentence.rstrip()):
+            continue
+
+        merged.append((" ".join(buffer_norm), "".join(buffer_raw)))
+        buffer_norm = []
+        buffer_raw = []
+
+    if buffer_norm:
+        merged.append((" ".join(buffer_norm), "".join(buffer_raw)))
+
+    return merged
+
+
+def chunk_text(
+    *,
+    chapter_index: int,
+    chapter_title: str,
+    text: str,
+    level: ChunkLevel,
+    speaker_id: str = "narrator",
+    voice: Optional[str] = None,
+    voice_profile: Optional[str] = None,
+    voice_formula: Optional[str] = None,
+    chunk_prefix: Optional[str] = None,
+) -> List[Dict[str, object]]:
+    """Split text into ordered chunk dictionaries."""
+
+    prefix = chunk_prefix or f"chap{chapter_index:04d}"
+    chunks: List[Dict[str, object]] = []
+
+    if level == "paragraph":
+        paragraphs = list(_iter_paragraphs(text)) or [text.strip()]
+        for para_index, paragraph in enumerate(paragraphs):
+            normalized = _normalize_whitespace(paragraph)
+            if not normalized:
+                continue
+            chunk_id = f"{prefix}_p{para_index:04d}"
+            payload = Chunk(
+                id=chunk_id,
+                chapter_index=chapter_index,
+                chunk_index=len(chunks),
+                level=level,
+                text=normalized,
+                speaker_id=speaker_id,
+                voice=voice,
+                voice_profile=voice_profile,
+                voice_formula=voice_formula,
+            ).as_dict()
+            payload["normalized_text"] = _normalize_chunk_text(paragraph)
+            payload["original_text"] = paragraph
+            chunks.append(payload)
+        _attach_display_text(text, chunks)
+        return chunks
+
+    # Sentence level – flatten paragraphs into individual sentences
+    sentence_index = 0
+    for para_index, paragraph in enumerate(
+        list(_iter_paragraphs(text)) or [text.strip()]
+    ):
+        normalized_para = _normalize_whitespace(paragraph)
+        if not normalized_para:
+            continue
+        sentence_pairs = _split_sentences(paragraph) or [(normalized_para, paragraph)]
+        for sent_local_index, (normalized_sentence, raw_sentence) in enumerate(
+            sentence_pairs
+        ):
+            normalized_sentence = _normalize_whitespace(normalized_sentence)
+            if not normalized_sentence:
+                continue
+            chunk_id = f"{prefix}_p{para_index:04d}_s{sent_local_index:04d}"
+            payload = Chunk(
+                id=chunk_id,
+                chapter_index=chapter_index,
+                chunk_index=sentence_index,
+                level=level,
+                text=normalized_sentence,
+                speaker_id=speaker_id,
+                voice=voice,
+                voice_profile=voice_profile,
+                voice_formula=voice_formula,
+            ).as_dict()
+            payload["normalized_text"] = _normalize_chunk_text(raw_sentence)
+            payload["display_text"] = raw_sentence
+            payload["original_text"] = raw_sentence
+            chunks.append(payload)
+            sentence_index += 1
+
+    _attach_display_text(text, chunks)
+    return chunks
+
+
+_DISPLAY_PATTERN_CACHE: Dict[str, Pattern[str]] = {}
+
+
+def _build_display_pattern(text: str) -> Pattern[str]:
+    cached = _DISPLAY_PATTERN_CACHE.get(text)
+    if cached is not None:
+        return cached
+    escaped = re.escape(text)
+    escaped = escaped.replace(r"\ ", r"\s+")
+    pattern = re.compile(r"(\s*" + escaped + r"\s*)", re.DOTALL)
+    _DISPLAY_PATTERN_CACHE[text] = pattern
+    return pattern
+
+
+def _search_source_span(
+    source: str, normalized: str, start: int
+) -> Optional[Tuple[int, int]]:
+    if not normalized:
+        return None
+    pattern = _build_display_pattern(normalized)
+    match = pattern.search(source, start)
+    if not match:
+        return None
+    return match.start(1), match.end(1)
+
+
+def _attach_display_text(source: str, chunks: List[Dict[str, object]]) -> None:
+    if not source or not chunks:
+        return
+    cursor = 0
+    for chunk in chunks:
+        candidate = str(chunk.get("display_text") or chunk.get("text") or "")
+        if not candidate:
+            continue
+        match = _search_source_span(source, candidate, cursor)
+        if match is None and cursor:
+            match = _search_source_span(source, candidate, 0)
+        if match is None:
+            chunk.setdefault("display_text", candidate)
+            chunk.setdefault("original_text", chunk.get("display_text") or candidate)
+            continue
+        start, end = match
+        chunk["display_text"] = source[start:end]
+        chunk["original_text"] = source[start:end]
+        cursor = end
+
+
+def build_chunks_for_chapters(
+    chapters: Iterable[Dict[str, object]],
+    *,
+    level: ChunkLevel,
+    speaker_id: str = "narrator",
+) -> List[Dict[str, object]]:
+    """Generate chunk dictionaries for a sequence of chapter payloads."""
+    all_chunks: List[Dict[str, object]] = []
+    for chapter_index, entry in enumerate(chapters):
+        if not isinstance(entry, dict):  # defensive
+            continue
+        text = str(entry.get("text", "") or "").strip()
+        if not text:
+            continue
+        voice = entry.get("voice")
+        voice_profile = entry.get("voice_profile")
+        voice_formula = entry.get("voice_formula")
+        prefix = entry.get("id") or f"chap{chapter_index:04d}"
+        chapter_chunks = chunk_text(
+            chapter_index=chapter_index,
+            chapter_title=str(entry.get("title") or f"Chapter {chapter_index + 1}"),
+            text=text,
+            level=level,
+            speaker_id=speaker_id,
+            voice=str(voice) if voice else None,
+            voice_profile=str(voice_profile) if voice_profile else None,
+            voice_formula=str(voice_formula) if voice_formula else None,
+            chunk_prefix=str(prefix),
+        )
+        all_chunks.extend(chapter_chunks)
+    return all_chunks

abogen/constants.py

@@ -1,13 +1,21 @@
-from utils import get_version
+from abogen.utils import get_version
 
 # Program Information
 PROGRAM_NAME = "abogen"
-PROGRAM_DESCRIPTION = (
-    "Generate audiobooks from EPUBs, PDFs and text with synchronized captions."
-)
+PROGRAM_DESCRIPTION = "Generate audiobooks from EPUBs, PDFs, text and subtitles with synchronized captions."
 GITHUB_URL = "https://github.com/denizsafak/abogen"
 VERSION = get_version()
 
+# Settings
+CHAPTER_OPTIONS_COUNTDOWN = 30  # Countdown seconds for chapter options
+SUBTITLE_FORMATS = [
+    ("srt", "SRT (standard)"),
+    ("ass_wide", "ASS (wide)"),
+    ("ass_narrow", "ASS (narrow)"),
+    ("ass_centered_wide", "ASS (centered wide)"),
+    ("ass_centered_narrow", "ASS (centered narrow)"),
+]
+
 # Language description mapping
 LANGUAGE_DESCRIPTIONS = {
     "a": "American English",
@@ -21,16 +29,39 @@ LANGUAGE_DESCRIPTIONS = {
     "z": "Mandarin Chinese",
 }
 
+# Supported sound formats
+SUPPORTED_SOUND_FORMATS = [
+    "wav",
+    "mp3",
+    "opus",
+    "m4b",
+    "flac",
+]
+
+# Supported subtitle formats
+SUPPORTED_SUBTITLE_FORMATS = [
+    "srt",
+    "ass",
+    "vtt",
+]
+
+# Supported input formats
+SUPPORTED_INPUT_FORMATS = [
+    "epub",
+    "pdf",
+    "txt",
+    "srt",
+    "ass",
+    "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 = [
-    "a",
-    "b",
-]
+SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION = list(LANGUAGE_DESCRIPTIONS.keys())
 
 # Voice and sample text constants
 VOICES_INTERNAL = [
@@ -103,15 +134,29 @@ SAMPLE_VOICE_TEXTS = {
     "z": "这是所选语音的示例。",
 }
 
-# flags mapping for voice display
-FLAGS = {
-    "a": "🇺🇸",
-    "b": "🇬🇧",
-    "e": "🇪🇸",
-    "f": "🇫🇷",
-    "h": "🇮🇳",
-    "i": "🇮🇹",
-    "j": "🇯🇵",
-    "p": "🇧🇷",
-    "z": "🇨🇳",
+COLORS = {
+    "BLUE": "#007dff",
+    "RED": "#c0392b",
+    "ORANGE": "#FFA500",
+    "GREEN": "#42ad4a",
+    "GREEN_BG": "rgba(66, 173, 73, 0.1)",
+    "GREEN_BG_HOVER": "rgba(66, 173, 73, 0.15)",
+    "GREEN_BORDER": "#42ad4a",
+    "BLUE_BG": "rgba(0, 102, 255, 0.05)",
+    "BLUE_BG_HOVER": "rgba(0, 102, 255, 0.1)",
+    "BLUE_BORDER_HOVER": "#6ab0de",
+    "YELLOW_BACKGROUND": "rgba(255, 221, 51, 0.40)",
+    "GREY_BACKGROUND": "rgba(128, 128, 128, 0.15)",
+    "GREY_BORDER": "#808080",
+    "RED_BACKGROUND": "rgba(232, 78, 60, 0.15)",
+    "RED_BG": "rgba(232, 78, 60, 0.10)",
+    "RED_BG_HOVER": "rgba(232, 78, 60, 0.15)",
+    # Theme palette colors
+    "DARK_BG": "#202326",
+    "DARK_BASE": "#141618",
+    "DARK_ALT": "#2c2f31",
+    "DARK_BUTTON": "#292c30",
+    "DARK_DISABLED": "#535353",
+    "LIGHT_BG": "#eff0f1",
+    "LIGHT_DISABLED": "#9a9999",
 }

abogen/conversion.py

@@ -1,723 +0,0 @@
-import os
-import re
-import tempfile
-import time
-import chardet
-import charset_normalizer
-from PyQt5.QtCore import QThread, pyqtSignal, Qt
-from PyQt5.QtWidgets import QCheckBox, QVBoxLayout, QDialog, QLabel, QDialogButtonBox
-import soundfile as sf
-from utils import clean_text
-from constants import PROGRAM_NAME, LANGUAGE_DESCRIPTIONS, SAMPLE_VOICE_TEXTS
-
-
-def get_sample_voice_text(lang_code):
-    return SAMPLE_VOICE_TEXTS.get(lang_code, SAMPLE_VOICE_TEXTS["a"])
-
-def detect_encoding(file_path):
-    with open(file_path, "rb") as f:
-        raw_data = f.read()
-    detected_encoding = None
-    for detectors in (charset_normalizer, chardet):
-        try:
-            result = detectors.detect(raw_data)["encoding"]
-        except Exception:
-            continue
-        if result is not None:
-            detected_encoding = result
-            break
-    encoding = detected_encoding if detected_encoding else "utf-8"
-    return encoding.lower()
-
-
-class ChapterOptionsDialog(QDialog):
-    def __init__(self, chapter_count, parent=None):
-        super().__init__(parent)
-        self.setWindowTitle("Chapter Options")
-        self.setMinimumWidth(350)
-        # Prevent closing with the X button and remove the help button
-        self.setWindowFlags(
-            self.windowFlags()
-            & ~Qt.WindowCloseButtonHint
-            & ~Qt.WindowContextHelpButtonHint
-        )
-
-        layout = QVBoxLayout(self)
-
-        # Add informational label
-        layout.addWidget(QLabel(f"Detected {chapter_count} chapters in the text file."))
-        layout.addWidget(QLabel("How would you like to process these chapters?"))
-
-        # Add checkboxes
-        self.save_separately_checkbox = QCheckBox("Save each chapter separately")
-        self.merge_at_end_checkbox = QCheckBox("Create a merged version at the end")
-
-        # Set default states
-        self.save_separately_checkbox.setChecked(True)
-        self.merge_at_end_checkbox.setChecked(True)
-
-        # Connect checkbox state change signal
-        self.save_separately_checkbox.stateChanged.connect(
-            self.update_merge_checkbox_state
-        )
-
-        layout.addWidget(self.save_separately_checkbox)
-        layout.addWidget(self.merge_at_end_checkbox)
-
-        # Add OK button
-        button_box = QDialogButtonBox(QDialogButtonBox.Ok)
-        button_box.accepted.connect(self.accept)
-        layout.addWidget(button_box)
-
-        # Initialize merge checkbox state
-        self.update_merge_checkbox_state()
-
-    def update_merge_checkbox_state(self):
-        # Enable merge checkbox only if save separately is checked
-        self.merge_at_end_checkbox.setEnabled(self.save_separately_checkbox.isChecked())
-        # Don't uncheck it, just leave it in its current state
-
-    def get_options(self):
-        save_separately = self.save_separately_checkbox.isChecked()
-        # Consider merge_at_end as false if the checkbox is disabled, regardless of its checked state
-        merge_at_end = (
-            self.merge_at_end_checkbox.isChecked()
-            and self.merge_at_end_checkbox.isEnabled()
-        )
-        return {
-            "save_chapters_separately": save_separately,
-            "merge_chapters_at_end": merge_at_end,
-        }
-
-    # Prevent closing by overriding the closeEvent
-    def closeEvent(self, event):
-        # Ignore all close events
-        event.ignore()
-
-    # Prevent escape key from closing the dialog
-    def keyPressEvent(self, event):
-        if event.key() == Qt.Key_Escape:
-            event.ignore()
-        else:
-            super().keyPressEvent(event)
-
-
-class ConversionThread(QThread):
-    progress_updated = pyqtSignal(int, str)  # Add str for ETR
-    conversion_finished = pyqtSignal(object, object)  # Pass output path as second arg
-    log_updated = pyqtSignal(object)  # Updated signal for log updates
-    chapters_detected = pyqtSignal(int)  # Signal for chapter detection
-
-    def __init__(
-        self,
-        file_name,
-        lang_code,
-        speed,
-        voice,
-        save_option,
-        output_folder,
-        subtitle_mode,
-        output_format,
-        np_module,
-        kpipeline_class,
-        start_time,
-        total_char_count,
-        use_gpu=True,
-    ):  # Add use_gpu parameter
-        super().__init__()
-        self.np = np_module
-        self.KPipeline = kpipeline_class
-        self.file_name = file_name
-        self.lang_code = lang_code
-        self.speed = speed
-        self.voice = voice
-        self.save_option = save_option
-        self.output_folder = output_folder
-        self.subtitle_mode = subtitle_mode
-        self.cancel_requested = False
-        self.output_format = output_format
-        self.start_time = start_time  # Store start_time
-        self.total_char_count = total_char_count  # Use passed total character count
-        self.processed_char_count = 0  # Initialize processed character count
-        self.display_path = None  # Add variable for display path
-        self.is_direct_text = (
-            False  # Flag to indicate if input is from textbox rather than file
-        )
-        self.chapter_options_set = False
-        self.waiting_for_user_input = False
-        self.use_gpu = use_gpu  # Store the GPU setting
-        self.max_subtitle_words = 50  # Default value, will be overridden from GUI
-
-    def run(self):
-        try:
-            # Show configuration
-            self.log_updated.emit("Configuration:")
-            # Use display_path for logs if available, otherwise use the actual file name
-            display_file = self.display_path if self.display_path else self.file_name
-            self.log_updated.emit(f"- Input File: {display_file}")
-
-            # Use file size string passed from GUI
-            if hasattr(self, "file_size_str"):
-                self.log_updated.emit(f"- File size: {self.file_size_str}")
-
-            self.log_updated.emit(f"- Total characters: {self.total_char_count:,}")
-
-            self.log_updated.emit(
-                f"- Language: {self.lang_code} ({LANGUAGE_DESCRIPTIONS.get(self.lang_code, 'Unknown')})"
-            )
-            self.log_updated.emit(f"- Voice: {self.voice}")
-            self.log_updated.emit(f"- Speed: {self.speed}")
-            self.log_updated.emit(f"- Subtitle mode: {self.subtitle_mode}")
-            self.log_updated.emit(f"- Output format: {self.output_format}")
-            self.log_updated.emit(f"- Save option: {self.save_option}")
-            if self.replace_single_newlines:
-                self.log_updated.emit(
-                    f"- Replace single newlines: Yes"
-                )
-
-            # Display save_chapters_separately flag if it's set
-            if hasattr(self, "save_chapters_separately"):
-                self.log_updated.emit(
-                    (
-                        f"- Save chapters separately: {'Yes' if self.save_chapters_separately else 'No'}"
-                    )
-                )
-                # Display merge_chapters_at_end flag if save_chapters_separately is True
-                if self.save_chapters_separately:
-                    merge_at_end = getattr(self, "merge_chapters_at_end", True)
-                    self.log_updated.emit(
-                        f"- Merge chapters at the end: {'Yes' if merge_at_end else 'No'}"
-                    )
-
-            if self.save_option == "Choose output folder":
-                self.log_updated.emit(
-                    f"  - Output folder: {self.output_folder or os.getcwd()}"
-                )
-            self.log_updated.emit("\nInitializing TTS pipeline...")
-
-            # Set device based on use_gpu setting
-            device = "cuda" if self.use_gpu else "cpu"
-            tts = self.KPipeline(
-                lang_code=self.lang_code, repo_id="hexgrad/Kokoro-82M", device=device
-            )
-
-            if self.is_direct_text:
-                text = self.file_name  # Treat file_name as direct text input
-            else:
-                encoding = detect_encoding(self.file_name)
-                with open(self.file_name, "r", encoding=encoding, errors="replace") as file:
-                    text = file.read()
-
-            # Clean up text using utility function
-            text = clean_text(text)
-
-            # --- Chapter splitting logic ---
-            chapter_pattern = r"<<CHAPTER_MARKER:(.*?)>>"
-            chapter_splits = list(re.finditer(chapter_pattern, text))
-            chapters = []
-            if chapter_splits:
-                for idx, match in enumerate(chapter_splits):
-                    start = match.end()
-                    end = (
-                        chapter_splits[idx + 1].start()
-                        if idx + 1 < len(chapter_splits)
-                        else len(text)
-                    )
-                    chapter_name = match.group(1).strip()
-                    chapter_text = text[start:end].strip()
-                    chapters.append((chapter_name, chapter_text))
-            else:
-                chapters = [("text", text)]
-            total_chapters = len(chapters)
-
-            # For text files with chapters, prompt user for options if not already set
-            is_txt_file = not self.is_direct_text and (
-                self.file_name.lower().endswith(".txt")
-                or (self.display_path and self.display_path.lower().endswith(".txt"))
-            )
-
-            if (
-                is_txt_file
-                and total_chapters > 1
-                and (
-                    not hasattr(self, "save_chapters_separately")
-                    or not hasattr(self, "merge_chapters_at_end")
-                )
-                and not self.chapter_options_set
-            ):
-
-                self.waiting_for_user_input = True
-                # Emit signal to main thread to show dialog
-                self.chapters_detected.emit(total_chapters)
-
-                # Wait for chapter options to be set
-                while self.waiting_for_user_input and not self.cancel_requested:
-                    time.sleep(0.1)
-
-                if self.cancel_requested:
-                    self.conversion_finished.emit("Cancelled", None)
-                    return
-
-                self.chapter_options_set = True
-
-            # Log all detected chapters at the beginning
-            if total_chapters > 1:
-                chapter_list = "\n".join(
-                    [f"{i+1}) {c[0]}" for i, c in enumerate(chapters)]
-                )
-                self.log_updated.emit(
-                    (f"\nDetected chapters ({total_chapters}):\n" + chapter_list)
-                )
-            else:
-                self.log_updated.emit((f"\nProcessing {chapters[0][0]}..."))
-
-            # If save_chapters_separately is enabled, find a unique suffix ONCE and use for both folder and merged file
-            save_chapters_separately = getattr(self, "save_chapters_separately", False)
-            chapters_out_dir = None
-            suffix = ""
-            base_path = self.display_path if self.display_path else self.file_name
-            base_name = os.path.splitext(os.path.basename(base_path))[0]
-            if self.save_option == "Save to Desktop":
-                parent_dir = os.path.join(os.path.expanduser("~"), "Desktop")
-            elif self.save_option == "Save next to input file":
-                parent_dir = os.path.dirname(base_path)
-            else:
-                parent_dir = self.output_folder or os.getcwd()
-            # Find a unique suffix for both folder and merged file, always
-            counter = 1
-            while True:
-                suffix = f"_{counter}" if counter > 1 else ""
-                chapters_out_dir_candidate = os.path.join(
-                    parent_dir, f"{base_name}{suffix}_chapters"
-                )
-                merged_file_candidate = os.path.join(
-                    parent_dir, f"{base_name}{suffix}.{self.output_format}"
-                )
-                merged_srt_candidate = (
-                    os.path.splitext(merged_file_candidate)[0] + ".srt"
-                )
-                if (
-                    not os.path.exists(chapters_out_dir_candidate)
-                    and not os.path.exists(merged_file_candidate)
-                    and (
-                        self.subtitle_mode == "Disabled"
-                        or not os.path.exists(merged_srt_candidate)
-                    )
-                ):
-                    break
-                counter += 1
-            if save_chapters_separately and total_chapters > 1:
-                chapters_out_dir = chapters_out_dir_candidate
-                os.makedirs(chapters_out_dir, exist_ok=True)
-                self.log_updated.emit(f"\nChapters output folder: {chapters_out_dir}")
-
-            audio_segments = []
-            subtitle_entries = []
-            current_time = 0.0
-            rate = 24000
-            subtitle_mode = self.subtitle_mode
-            raw_tts_results = []  # Collect all raw tts Result objects
-
-            # ETR timing starts here, after model loading but before processing
-            self.etr_start_time = time.time()
-            self.processed_char_count = 0  # Initialize processed character count
-
-            # Initialize current segment counter
-            current_segment = 0
-
-            # Instead of processing the whole text, process by chapter
-            for chapter_idx, (chapter_name, chapter_text) in enumerate(chapters, 1):
-                if total_chapters > 1:
-                    self.log_updated.emit(
-                        (
-                            f"\nChapter {chapter_idx}/{total_chapters}: {chapter_name}",
-                            "green",
-                        )
-                    )
-
-                # Variables for per-chapter processing when save_chapters_separately is enabled
-                chapter_audio_segments = []
-                chapter_subtitle_entries = []
-                chapter_current_time = 0.0
-
-                # Set split_pattern to \n+ which will split on one or more newlines
-                split_pattern = r"\n+"
-                for result in tts(
-                    chapter_text,
-                    voice=self.voice,
-                    speed=self.speed,
-                    split_pattern=split_pattern,
-                ):
-                    # Print the result for debugging
-                    # print(f"Result: {result}")
-                    if self.cancel_requested:
-                        self.conversion_finished.emit("Cancelled", None)
-                        return
-                    current_segment += 1
-                    grapheme_len = len(result.graphemes)
-                    self.processed_char_count += grapheme_len
-                    # Log progress with both character counts and the graphemes content
-                    self.log_updated.emit(
-                        f"\n{self.processed_char_count:,}/{self.total_char_count:,}: {result.graphemes}"
-                    )
-                    raw_tts_results.append(result)
-
-                    chunk_dur = len(result.audio) / rate
-                    chunk_start = current_time
-                    audio_segments.append(result.audio)
-
-                    # For per-chapter output
-                    if save_chapters_separately and total_chapters > 1:
-                        chapter_audio_segments.append(result.audio)
-                        chapter_chunk_start = chapter_current_time
-
-                    # Process token timestamps for subtitle generation
-                    if self.subtitle_mode != "Disabled":
-                        tokens_list = getattr(result, "tokens", [])
-                        tokens_with_timestamps = []
-                        chapter_tokens_with_timestamps = []
-
-                        # Process every token, regardless of text or timestamps
-                        for tok in tokens_list:
-                            tokens_with_timestamps.append(
-                                {
-                                    "start": chunk_start + (tok.start_ts or 0),
-                                    "end": chunk_start + (tok.end_ts or 0),
-                                    "text": tok.text,
-                                    "whitespace": tok.whitespace,
-                                }
-                            )
-                            if save_chapters_separately and total_chapters > 1:
-                                chapter_tokens_with_timestamps.append(
-                                    {
-                                        "start": chapter_chunk_start
-                                        + (tok.start_ts or 0),
-                                        "end": chapter_chunk_start + (tok.end_ts or 0),
-                                        "text": tok.text,
-                                        "whitespace": tok.whitespace,
-                                    }
-                                )
-
-                        # Process tokens according to subtitle mode
-                        # Global subtitle processing
-                        self._process_subtitle_tokens(
-                            tokens_with_timestamps,
-                            subtitle_entries,
-                            self.max_subtitle_words,
-                        )
-
-                        # Per-chapter subtitle processing if enabled
-                        if save_chapters_separately and total_chapters > 1:
-                            self._process_subtitle_tokens(
-                                chapter_tokens_with_timestamps,
-                                chapter_subtitle_entries,
-                                self.max_subtitle_words,
-                            )
-
-                    current_time += chunk_dur
-
-                    # Update chapter_current_time for per-chapter output
-                    if save_chapters_separately and total_chapters > 1:
-                        chapter_current_time += chunk_dur
-
-                    # Calculate percentage based on characters processed
-                    percent = min(
-                        int(self.processed_char_count / self.total_char_count * 100), 99
-                    )
-
-                    # Calculate ETR based on characters processed
-                    etr_str = "Estimating..."
-                    chars_done = self.processed_char_count
-                    elapsed = time.time() - self.etr_start_time
-
-                    # Calculate ETR if enough data is available
-                    if (
-                        chars_done > 0 and elapsed > 0.5
-                    ):  # Check elapsed > 0.5 to avoid instability
-                        avg_time_per_char = elapsed / chars_done
-                        remaining = self.total_char_count - self.processed_char_count
-                        if remaining > 0:
-                            secs = avg_time_per_char * remaining
-                            h = int(secs // 3600)
-                            m = int((secs % 3600) // 60)
-                            s = int(secs % 60)
-                            etr_str = f"{h:02d}:{m:02d}:{s:02d}"
-
-                    # Update progress more frequently (after each result)
-                    self.progress_updated.emit(percent, etr_str)
-
-                # Save the individual chapter output if save_chapters_separately is enabled
-                if (
-                    save_chapters_separately
-                    and total_chapters > 1
-                    and chapters_out_dir
-                    and chapter_audio_segments
-                ):
-                    # Sanitize chapter name for use in filenames
-                    sanitized_chapter_name = re.sub(r"[^\w\-\. ]", "_", chapter_name)
-                    sanitized_chapter_name = re.sub(
-                        r"_+", "_", sanitized_chapter_name
-                    )  # Replace multiple underscores with one
-                    chapter_filename = f"{chapter_idx:02d}_{sanitized_chapter_name}"
-
-                    # Concatenate chapter audio and save
-                    chapter_audio = self.np.concatenate(chapter_audio_segments)
-                    chapter_out_path = os.path.join(
-                        chapters_out_dir, f"{chapter_filename}.{self.output_format}"
-                    )
-                    sf.write(
-                        chapter_out_path,
-                        chapter_audio,
-                        24000,
-                        format=self.output_format,
-                    )
-
-                    # Generate .srt subtitle file for chapter if not Disabled
-                    if self.subtitle_mode != "Disabled" and chapter_subtitle_entries:
-                        chapter_srt_path = os.path.join(
-                            chapters_out_dir, f"{chapter_filename}.srt"
-                        )
-                        with open(chapter_srt_path, "w", encoding="utf-8", errors="replace") as srt_file:
-                            for i, (start, end, text) in enumerate(
-                                chapter_subtitle_entries, 1
-                            ):
-                                srt_file.write(
-                                    f"{i}\n{self._srt_time(start)} --> {self._srt_time(end)}\n{text}\n\n"
-                                )
-
-                        self.log_updated.emit(
-                            (
-                                f"\nChapter {chapter_idx} saved to: {chapter_out_path}\n\nSubtitle saved to: {chapter_srt_path}",
-                                "green",
-                            )
-                        )
-                    else:
-                        self.log_updated.emit(
-                            (
-                                f"\nChapter {chapter_idx} saved to: {chapter_out_path}",
-                                "green",
-                            )
-                        )
-
-            # Set progress to 100% when processing is complete
-            self.progress_updated.emit(100, "00:00:00")
-
-            # Only generate the merged output file if merge_chapters_at_end is True or save_chapters_separately is False
-            merge_chapters = (
-                not hasattr(self, "save_chapters_separately")
-                or not self.save_chapters_separately
-                or getattr(self, "merge_chapters_at_end", True)
-            )
-            if audio_segments and merge_chapters:
-                self.log_updated.emit("\nFinalizing audio file...\n")
-                audio = self.np.concatenate(audio_segments)
-                out_dir = parent_dir
-                # Use the same suffix as above
-                out_filename = f"{base_name}{suffix}.{self.output_format}"
-                out_path = os.path.join(out_dir, out_filename)
-                srt_path = os.path.splitext(out_path)[0] + ".srt"
-                sf.write(out_path, audio, 24000, format=self.output_format)
-                if self.subtitle_mode != "Disabled":
-                    with open(srt_path, "w", encoding="utf-8", errors="replace") as srt_file:
-                        for i, (start, end, text) in enumerate(subtitle_entries, 1):
-                            srt_file.write(
-                                f"{i}\n{self._srt_time(start)} --> {self._srt_time(end)}\n{text}\n\n"
-                            )
-                    self.conversion_finished.emit(
-                        (
-                            f"Audiobook saved to: {out_path}\n\nSubtitle saved to: {srt_path}",
-                            "green",
-                        ),
-                        out_path,
-                    )
-                else:
-                    self.conversion_finished.emit(
-                        (f"Audiobook saved to: {out_path}", "green"), out_path
-                    )
-            elif audio_segments and not merge_chapters:
-                self.conversion_finished.emit(
-                    (
-                        f"\nAll chapters processed successfully and saved to: {chapters_out_dir}",
-                        "green",
-                    ),
-                    chapters_out_dir,
-                )
-            else:
-                self.log_updated.emit(("No audio segments were generated.", "red"))
-                self.conversion_finished.emit(("Audio generation failed.", "red"), None)
-        except Exception as e:
-            self.log_updated.emit((f"Error occurred: {str(e)}", "red"))
-            self.conversion_finished.emit(("Audio generation failed.", "red"), None)
-
-    def set_chapter_options(self, options):
-        """Set chapter options from the dialog and resume processing"""
-        self.save_chapters_separately = options["save_chapters_separately"]
-        self.merge_chapters_at_end = options["merge_chapters_at_end"]
-        self.waiting_for_user_input = False
-
-    def _srt_time(self, t):
-        """Helper function to format time for SRT files"""
-        h = int(t // 3600)
-        m = int((t % 3600) // 60)
-        s = int(t % 60)
-        ms = int((t - int(t)) * 1000)
-        return f"{h:02}:{m:02}:{s:02},{ms:03}"
-
-    def _process_subtitle_tokens(
-        self, tokens_with_timestamps, subtitle_entries, max_subtitle_words
-    ):
-        """Helper function to process subtitle tokens according to the subtitle mode"""
-        if not tokens_with_timestamps:
-            return
-
-        if self.subtitle_mode == "Sentence" or self.subtitle_mode == "Sentence + Comma":
-            # Define separator pattern based on mode
-            separator = r"[.!?]" if self.subtitle_mode == "Sentence" else r"[.!?,]"
-            current_sentence = []
-            word_count = 0
-
-            for token in tokens_with_timestamps:
-                current_sentence.append(token)
-                word_count += 1
-
-                # Split sentences based on separator or word count
-                if (
-                    re.search(separator, token["text"]) and token["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
-            if current_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()))
-
-        else:
-            # Word count-based grouping
-            try:
-                word_count = int(self.subtitle_mode.split()[0])
-                word_count = min(word_count, max_subtitle_words)
-            except (ValueError, IndexError):
-                word_count = 1
-
-            # Combine punctuation with preceding words
-            processed_tokens = []
-            i = 0
-            while i < len(tokens_with_timestamps):
-                token = tokens_with_timestamps[i].copy()
-
-                # Look ahead for punctuation
-                while i + 1 < len(tokens_with_timestamps) and re.match(
-                    r"^[^\w\s]+$", tokens_with_timestamps[i + 1]["text"]
-                ):
-                    token["text"] += tokens_with_timestamps[i + 1]["text"]
-                    token["end"] = tokens_with_timestamps[i + 1]["end"]
-                    token["whitespace"] = tokens_with_timestamps[i + 1]["whitespace"]
-                    i += 1
-
-                processed_tokens.append(token)
-                i += 1
-
-            # Group words into subtitle entries
-            for i in range(0, len(processed_tokens), word_count):
-                group = processed_tokens[i : i + word_count]
-                if group:
-                    text = "".join(
-                        t["text"] + (t.get("whitespace", "") or "") for t in group
-                    )
-                    subtitle_entries.append(
-                        (group[0]["start"], group[-1]["end"], text.strip())
-                    )
-
-    def cancel(self):
-        self.cancel_requested = True
-        self.waiting_for_user_input = (
-            False  # Also release the wait if we're waiting for input
-        )
-
-
-class VoicePreviewThread(QThread):
-    finished = pyqtSignal()
-    error = pyqtSignal(str)
-
-    def __init__(
-        self, np_module, kpipeline_class, lang_code, voice, speed, parent=None
-    ):
-        super().__init__(parent)
-        self.np_module = np_module
-        self.kpipeline_class = kpipeline_class
-        self.lang_code = lang_code
-        self.voice = voice
-        self.speed = speed
-        self.temp_wav = None
-
-    def run(self):
-        try:
-            tts = self.kpipeline_class(
-                lang_code=self.lang_code, repo_id="hexgrad/Kokoro-82M"
-            )
-            sample_text = get_sample_voice_text(self.lang_code)
-            audio_segments = []
-            for result in tts(
-                sample_text, voice=self.voice, speed=self.speed, split_pattern=None
-            ):
-                audio_segments.append(result.audio)
-            if audio_segments:
-                audio = self.np_module.concatenate(audio_segments)
-                # Create temp wav file in a folder in the system temp directory
-                temp_dir = os.path.join(tempfile.gettempdir(), PROGRAM_NAME)
-                os.makedirs(temp_dir, exist_ok=True)
-                fd, temp_path = tempfile.mkstemp(
-                    prefix="abogen_", suffix=".wav", dir=temp_dir
-                )
-                os.close(fd)
-                sf.write(temp_path, audio, 24000)
-                self.temp_wav = temp_path
-            self.finished.emit()
-        except Exception as e:
-            self.error.emit(f"Voice preview error: {str(e)}")
-
-
-class PlayAudioThread(QThread):
-    finished = pyqtSignal()
-    error = pyqtSignal(str)
-
-    def __init__(self, wav_path, parent=None):
-        super().__init__(parent)
-        self.wav_path = wav_path
-
-    def run(self):
-        try:
-            import pygame
-            import time as _time
-
-            pygame.mixer.init()
-            pygame.mixer.music.load(self.wav_path)
-            pygame.mixer.music.play()
-            # Wait until playback is finished
-            while pygame.mixer.music.get_busy():
-                _time.sleep(0.1)
-            pygame.mixer.music.unload()
-            self.finished.emit()
-        except Exception as e:
-            self.error.emit(f"Audio playback error: {str(e)}")

abogen/debug_tts_samples.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Sequence
+
+
+MARKER_PREFIX = "[[ABOGEN-DBG:"
+MARKER_SUFFIX = "]]"
+
+
+@dataclass(frozen=True)
+class DebugTTSSample:
+    code: str
+    label: str
+    text: str
+
+
+DEBUG_TTS_SAMPLES: Sequence[DebugTTSSample] = (
+    DebugTTSSample(
+        code="APOS_001",
+        label="Apostrophes & contractions (1)",
+        text="It's a beautiful day, isn't it? Let's see what we'll do.",
+    ),
+    DebugTTSSample(
+        code="APOS_002",
+        label="Apostrophes & contractions (2)",
+        text="I'm sure you're ready; we'd better go before it's too late.",
+    ),
+    DebugTTSSample(
+        code="APOS_003",
+        label="Apostrophes & contractions (3)",
+        text="He'll say it's fine, but I can't promise it'll work.",
+    ),
+    DebugTTSSample(
+        code="APOS_004",
+        label="Apostrophes & contractions (4)",
+        text="They've done it, and I'd agree they've earned it.",
+    ),
+    DebugTTSSample(
+        code="APOS_005",
+        label="Apostrophes & contractions (5)",
+        text="She's here, we're late, they're waiting, and you're right.",
+    ),
+    DebugTTSSample(
+        code="POS_001",
+        label="Plural possessives (1)",
+        text="The dogs' bowls were empty, but the boss's office was quiet.",
+    ),
+    DebugTTSSample(
+        code="POS_002",
+        label="Plural possessives (2)",
+        text="The teachers' lounge was closed during the students' exams.",
+    ),
+    DebugTTSSample(
+        code="POS_003",
+        label="Plural possessives (3)",
+        text="The actresses' roles changed, and the directors' notes piled up.",
+    ),
+    DebugTTSSample(
+        code="POS_004",
+        label="Plural possessives (4)",
+        text="The Joneses' car was parked by the neighbors' fence.",
+    ),
+    DebugTTSSample(
+        code="POS_005",
+        label="Plural possessives (5)",
+        text="The bosses' meeting ended before the witnesses' statements began.",
+    ),
+    DebugTTSSample(
+        code="NUM_001",
+        label="Grouped numbers (1)",
+        text="There are 1,234 apples, 56 oranges, and 7.89 liters of juice.",
+    ),
+    DebugTTSSample(
+        code="NUM_002",
+        label="Grouped numbers (2)",
+        text="The population is 10,000,000 and the area is 123.45 square miles.",
+    ),
+    DebugTTSSample(
+        code="NUM_003",
+        label="Grouped numbers (3)",
+        text="Set the timer for 0.5 seconds, then wait 2.0 minutes.",
+    ),
+    DebugTTSSample(
+        code="NUM_004",
+        label="Grouped numbers (4)",
+        text="We measured 3.1415 radians and wrote down 2,718.28 as well.",
+    ),
+    DebugTTSSample(
+        code="NUM_005",
+        label="Grouped numbers (5)",
+        text="The sequence is 1, 2, 3, 4, 5, and then 13.",
+    ),
+    DebugTTSSample(
+        code="YEAR_001",
+        label="Years and decades (1)",
+        text="In 1999, people said the '90s were over.",
+    ),
+    DebugTTSSample(
+        code="YEAR_002",
+        label="Years and decades (2)",
+        text="In 2001, the show premiered; by 2010 it was everywhere.",
+    ),
+    DebugTTSSample(
+        code="YEAR_003",
+        label="Years and decades (3)",
+        text="The 1980s were loud, and the 1970s were groovy.",
+    ),
+    DebugTTSSample(
+        code="YEAR_004",
+        label="Years and decades (4)",
+        text="She loved the '80s, but he preferred the '60s.",
+    ),
+    DebugTTSSample(
+        code="YEAR_005",
+        label="Years and decades (5)",
+        text="In 2024, we looked back at 2020 and planned for 2030.",
+    ),
+    DebugTTSSample(
+        code="DATE_001",
+        label="Dates (1)",
+        text="On 2023-01-01, we celebrated the new year.",
+    ),
+    DebugTTSSample(
+        code="DATE_002",
+        label="Dates (2)",
+        text="The deadline is 1999-12-31 at midnight.",
+    ),
+    DebugTTSSample(
+        code="DATE_003",
+        label="Dates (3)",
+        text="Leap day happens on 2024-02-29.",
+    ),
+    DebugTTSSample(
+        code="DATE_004",
+        label="Dates (4)",
+        text="Some formats look like 01/02/2003 and can be ambiguous.",
+    ),
+    DebugTTSSample(
+        code="DATE_005",
+        label="Dates (5)",
+        text="We met on March 5, 2020 and again on Apr. 7, 2021.",
+    ),
+    DebugTTSSample(
+        code="CUR_001",
+        label="Currency symbols (1)",
+        text="The price is $10.50, but it was £8.00 yesterday.",
+    ),
+    DebugTTSSample(
+        code="CUR_002",
+        label="Currency symbols (2)",
+        text="Tickets cost €12, and the fine was $0.99.",
+    ),
+    DebugTTSSample(
+        code="CUR_003",
+        label="Currency symbols (3)",
+        text="The bill was ¥500 and the refund was $-3.25.",
+    ),
+    DebugTTSSample(
+        code="CUR_004",
+        label="Currency symbols (4)",
+        text="He paid £1,234.56 for the instrument.",
+    ),
+    DebugTTSSample(
+        code="CUR_005",
+        label="Currency symbols (5)",
+        text="The subscription is $5 per month, or $50 per year.",
+    ),
+    DebugTTSSample(
+        code="TITLE_001",
+        label="Titles and abbreviations (1)",
+        text="Dr. Smith lives on Elm St. near the U.S. border.",
+    ),
+    DebugTTSSample(
+        code="TITLE_002",
+        label="Titles and abbreviations (2)",
+        text="Mr. and Mrs. Doe met Prof. Adams at 5 p.m.",
+    ),
+    DebugTTSSample(
+        code="TITLE_003",
+        label="Titles and abbreviations (3)",
+        text="Gen. Smith spoke to Sgt. Rivera on Main St.",
+    ),
+    DebugTTSSample(
+        code="TITLE_004",
+        label="Titles and abbreviations (4)",
+        text="The report came from the U.K. office, not the U.S.A. team.",
+    ),
+    DebugTTSSample(
+        code="TITLE_005",
+        label="Titles and abbreviations (5)",
+        text="St. John's is different from St. Louis.",
+    ),
+    DebugTTSSample(
+        code="PUNC_001",
+        label="Terminal punctuation (1)",
+        text="This sentence ends without punctuation",
+    ),
+    DebugTTSSample(
+        code="PUNC_002",
+        label="Terminal punctuation (2)",
+        text="An ellipsis is already present...",
+    ),
+    DebugTTSSample(
+        code="PUNC_003",
+        label="Terminal punctuation (3)",
+        text="A question without a mark",
+    ),
+    DebugTTSSample(
+        code="PUNC_004",
+        label="Terminal punctuation (4)",
+        text="An exclamation without a bang",
+    ),
+    DebugTTSSample(
+        code="PUNC_005",
+        label="Terminal punctuation (5)",
+        text='A quote ends here"',
+    ),
+    DebugTTSSample(
+        code="QUOTE_001",
+        label="ALL CAPS inside quotes (1)",
+        text='He shouted, "THIS IS IMPORTANT!" and then whispered, "ok."',
+    ),
+    DebugTTSSample(
+        code="QUOTE_002",
+        label="ALL CAPS inside quotes (2)",
+        text='She said, "NO WAY", but he replied, "maybe".',
+    ),
+    DebugTTSSample(
+        code="QUOTE_003",
+        label="ALL CAPS inside quotes (3)",
+        text='The sign read "DO NOT ENTER" and the note read "pls knock".',
+    ),
+    DebugTTSSample(
+        code="QUOTE_004",
+        label="ALL CAPS inside quotes (4)",
+        text='He muttered, "OK", then yelled, "STOP!"',
+    ),
+    DebugTTSSample(
+        code="QUOTE_005",
+        label="ALL CAPS inside quotes (5)",
+        text='They chanted, "USA!" and someone wrote "idk".',
+    ),
+    DebugTTSSample(
+        code="FOOT_001",
+        label="Footnote indicators (1)",
+        text="This is a sentence with a footnote[1] and another[12].",
+    ),
+    DebugTTSSample(
+        code="FOOT_002",
+        label="Footnote indicators (2)",
+        text="Some books use multiple footnotes like this[2][3] in a row.",
+    ),
+    DebugTTSSample(
+        code="FOOT_003",
+        label="Footnote indicators (3)",
+        text="A footnote can appear mid-sentence[4] and continue afterward.",
+    ),
+    DebugTTSSample(
+        code="FOOT_004",
+        label="Footnote indicators (4)",
+        text="Edge cases include [0] or very large indices like [1234].",
+    ),
+    DebugTTSSample(
+        code="FOOT_005",
+        label="Footnote indicators (5)",
+        text="Sometimes a footnote follows punctuation.[5] Sometimes it doesn't[6]",
+    ),
+)
+
+
+def marker_for(code: str) -> str:
+    return f"{MARKER_PREFIX}{code}{MARKER_SUFFIX}"
+
+
+def build_debug_epub(dest_path: Path, *, title: str = "abogen debug samples") -> Path:
+    """Create a tiny EPUB containing all debug samples.
+
+    The text includes stable marker codes so developers can report failures
+    precisely.
+    """
+
+    dest_path = Path(dest_path)
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+    chapter_lines: List[str] = [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        "<!DOCTYPE html>",
+        '<html xmlns="http://www.w3.org/1999/xhtml">',
+        "<head>",
+        f"  <title>{title}</title>",
+        '  <meta charset="utf-8" />',
+        "</head>",
+        "<body>",
+        f"  <h1>{title}</h1>",
+        "  <p>Each paragraph begins with a stable debug code marker.</p>",
+    ]
+
+    for sample in DEBUG_TTS_SAMPLES:
+        safe_label = sample.label.replace("&", "and")
+        chapter_lines.append(f"  <h2>{safe_label}</h2>")
+        chapter_lines.append(
+            "  <p><strong>"
+            + marker_for(sample.code)
+            + "</strong> "
+            + sample.text
+            + "</p>"
+        )
+
+    chapter_lines += ["</body>", "</html>"]
+    chapter_xhtml = "\n".join(chapter_lines)
+
+    container_xml = """<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+  <rootfiles>
+    <rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
+  </rootfiles>
+</container>
+"""
+
+    content_opf = """<?xml version="1.0" encoding="utf-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" unique-identifier="bookid" version="3.0">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:identifier id="bookid">abogen-debug-samples</dc:identifier>
+    <dc:title>abogen debug samples</dc:title>
+    <dc:language>en</dc:language>
+  </metadata>
+  <manifest>
+    <item id="chapter" href="chapter.xhtml" media-type="application/xhtml+xml" />
+    <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav" />
+  </manifest>
+  <spine>
+    <itemref idref="chapter" />
+  </spine>
+</package>
+"""
+
+    nav_xhtml = """<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+  <title>Navigation</title>
+  <meta charset="utf-8" />
+</head>
+<body>
+  <nav epub:type="toc" id="toc">
+    <h2>Table of Contents</h2>
+    <ol>
+      <li><a href="chapter.xhtml">Debug samples</a></li>
+    </ol>
+  </nav>
+</body>
+</html>
+"""
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        (tmp_path / "mimetype").write_text("application/epub+zip", encoding="utf-8")
+        meta_inf = tmp_path / "META-INF"
+        meta_inf.mkdir(parents=True, exist_ok=True)
+        (meta_inf / "container.xml").write_text(container_xml, encoding="utf-8")
+        oebps = tmp_path / "OEBPS"
+        oebps.mkdir(parents=True, exist_ok=True)
+        (oebps / "content.opf").write_text(content_opf, encoding="utf-8")
+        (oebps / "chapter.xhtml").write_text(chapter_xhtml, encoding="utf-8")
+        (oebps / "nav.xhtml").write_text(nav_xhtml, encoding="utf-8")
+
+        # Per EPUB spec: mimetype must be the first entry and stored (no compression).
+        with zipfile.ZipFile(dest_path, "w") as zf:
+            zf.write(
+                tmp_path / "mimetype", "mimetype", compress_type=zipfile.ZIP_STORED
+            )
+            for source in (
+                meta_inf / "container.xml",
+                oebps / "content.opf",
+                oebps / "chapter.xhtml",
+                oebps / "nav.xhtml",
+            ):
+                arcname = str(source.relative_to(tmp_path)).replace("\\", "/")
+                zf.write(source, arcname, compress_type=zipfile.ZIP_DEFLATED)
+
+    return dest_path
+
+
+def iter_expected_codes() -> Iterable[str]:
+    for sample in DEBUG_TTS_SAMPLES:
+        yield sample.code

abogen/entity_analysis.py

@@ -0,0 +1,489 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import threading
+import time
+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]
+
+
+_TITLE_PREFIXES = (
+    "mr",
+    "mrs",
+    "ms",
+    "miss",
+    "dr",
+    "prof",
+    "sir",
+    "madam",
+    "lady",
+    "lord",
+    "capt",
+    "captain",
+    "col",
+    "colonel",
+    "maj",
+    "major",
+    "sgt",
+    "sergeant",
+    "rev",
+    "father",
+    "mother",
+    "brother",
+    "sister",
+)
+
+_STOP_LABELS = {
+    "the",
+    "that",
+    "this",
+    "those",
+    "these",
+    "there",
+    "here",
+    "then",
+    "and",
+    "but",
+    "or",
+    "nor",
+    "so",
+    "yet",
+    "dr",
+    "mr",
+    "mrs",
+    "ms",
+    "miss",
+    "sir",
+    "madam",
+    "lady",
+    "lord",
+}
+
+_EXCLUDED_NER_LABELS = {
+    "CARDINAL",
+    "DATE",
+    "ORDINAL",
+    "PERCENT",
+    "TIME",
+    "LAW",
+    "MONEY",
+    "QUANTITY",
+}
+
+_TITLE_PATTERN = re.compile(
+    r"^(?:" + "|".join(re.escape(prefix) for prefix in _TITLE_PREFIXES) + r")\.?\s+",
+    re.IGNORECASE,
+)
+_POSSESSIVE_PATTERN = re.compile(r"(?:'s|’s|\u2019s)$", re.IGNORECASE)
+_NON_WORD_PATTERN = re.compile(r"[^\w\s'-]+")
+_MULTI_SPACE_PATTERN = re.compile(r"\s+")
+_SUFFIX_PATTERN = re.compile(
+    r",?\s+(?:jr|sr|ii|iii|iv|v|vi|md|phd|esq|esquire|dds|dvm)\.?$",
+    re.IGNORECASE,
+)
+
+
+@dataclass(slots=True)
+class EntityRecord:
+    key: Tuple[str, str]
+    label: str
+    kind: str
+    category: str
+    count: int = 0
+    samples: List[Dict[str, Any]] = field(default_factory=list)
+    chapter_indices: set[int] = field(default_factory=set)
+    forms: Counter = field(default_factory=Counter)
+    first_position: Optional[Tuple[int, int]] = None
+
+    def register(
+        self, *, chapter_index: int, position: int, text: str, sentence: Optional[str]
+    ) -> None:
+        self.count += 1
+        self.chapter_indices.add(chapter_index)
+        self.forms[text] += 1
+        if self.first_position is None:
+            self.first_position = (chapter_index, position)
+        if sentence and len(self.samples) < 5:
+            payload = {
+                "excerpt": sentence.strip(),
+                "chapter_index": chapter_index,
+            }
+            if payload not in self.samples:
+                self.samples.append(payload)
+
+    def as_dict(self, ordinal: int) -> Dict[str, Any]:
+        chapter_indices = sorted(self.chapter_indices)
+        first_chapter = chapter_indices[0] if chapter_indices else None
+        return {
+            "id": f"{self.category}_{ordinal}",
+            "label": self.label,
+            "normalized": self.key[1],
+            "category": self.category,
+            "kind": self.kind,
+            "count": self.count,
+            "samples": list(self.samples),
+            "chapter_indices": chapter_indices,
+            "first_chapter": first_chapter,
+            "forms": self.forms.most_common(6),
+        }
+
+
+@dataclass(slots=True)
+class EntityExtractionResult:
+    summary: Dict[str, Any]
+    cache_key: str
+    elapsed: float
+    errors: List[str]
+
+
+class EntityModelError(RuntimeError):
+    pass
+
+
+_MODEL_CACHE: Dict[str, Any] = {}
+_MODEL_LOCK = threading.RLock()
+
+
+def _resolve_model_name(language: str) -> str:
+    override = os.environ.get("ABOGEN_SPACY_MODEL")
+    if override:
+        return override.strip()
+    lowered = language.strip().lower()
+    if lowered.startswith("en"):
+        return "en_core_web_sm"
+    return "en_core_web_sm"
+
+
+def _load_model(language: str) -> Any:
+    if spacy is None:
+        raise EntityModelError(
+            "spaCy is not available. Install spaCy to enable entity extraction."
+        )
+
+    model_name = _resolve_model_name(language)
+    cache_key = model_name.lower()
+    with _MODEL_LOCK:
+        if cache_key in _MODEL_CACHE:
+            return _MODEL_CACHE[cache_key]
+        try:
+            nlp = spacy.load(model_name)  # type: ignore[arg-type]
+        except OSError as exc:  # pragma: no cover - external dependency failure
+            raise EntityModelError(
+                f"spaCy model '{model_name}' is not installed. Download it with "
+                "`python -m spacy download en_core_web_sm`."
+            ) from exc
+        nlp.max_length = max(nlp.max_length, 2_000_000)
+        _MODEL_CACHE[cache_key] = nlp
+        return nlp
+
+
+def _normalize_label(text: str) -> str:
+    if not text:
+        return ""
+    stripped = text.strip().strip("\"'`“”’")
+    if not stripped:
+        return ""
+    stripped = _TITLE_PATTERN.sub("", stripped)
+    stripped = _SUFFIX_PATTERN.sub("", stripped)
+    stripped = _POSSESSIVE_PATTERN.sub("", stripped)
+    stripped = _NON_WORD_PATTERN.sub(" ", stripped)
+    stripped = _MULTI_SPACE_PATTERN.sub(" ", stripped)
+    stripped = stripped.strip()
+    if not stripped or stripped.lower() in _STOP_LABELS:
+        return ""
+    parts = stripped.split()
+    if not parts:
+        return ""
+    if len(parts) == 1 and len(parts[0]) <= 1:
+        return ""
+    # Normalise casing: preserve uppercase abbreviations, otherwise title case.
+    normalized_parts = []
+    for index, part in enumerate(parts):
+        if part.isupper():
+            normalized_parts.append(part)
+        elif part[:1].isupper():
+            normalized_parts.append(part[:1].upper() + part[1:])
+        elif index == 0:
+            normalized_parts.append(part[:1].upper() + part[1:])
+        else:
+            normalized_parts.append(part)
+    normalized = " ".join(normalized_parts).strip()
+    if normalized.lower() in _STOP_LABELS:
+        return ""
+    return normalized
+
+
+def _token_key(value: str) -> str:
+    return _MULTI_SPACE_PATTERN.sub(" ", value.lower().strip()).strip()
+
+
+def _iter_named_entities(doc: Any) -> Iterable[Any]:  # type: ignore[override]
+    for ent in getattr(doc, "ents", ()):
+        if ent.label_ == "":
+            continue
+        yield ent
+
+
+def _extract_propn_tokens(doc: Any) -> Iterable[Any]:  # type: ignore[override]
+    seen: set[Tuple[int, int]] = set()
+    for ent in getattr(doc, "ents", ()):  # guard multi-token spans
+        seen.add((ent.start, ent.end))
+    for token in doc:
+        if token.pos_ != "PROPN":
+            continue
+        span_key = (token.i, token.i + 1)
+        if span_key in seen:
+            continue
+        if token.is_stop:
+            continue
+        text = token.text.strip()
+        if not text:
+            continue
+        if token.ent_type_:
+            continue
+        yield doc[token.i : token.i + 1]
+
+
+def _empty_result(
+    cache_key: str, error: Optional[str] = None
+) -> EntityExtractionResult:
+    payload = {
+        "people": [],
+        "entities": [],
+        "index": {"tokens": []},
+        "stats": {
+            "tokens": 0,
+            "chapters": 0,
+            "processed": False,
+        },
+        "model": None,
+    }
+    errors = [error] if error else []
+    return EntityExtractionResult(
+        summary=payload, cache_key=cache_key, elapsed=0.0, errors=errors
+    )
+
+
+def extract_entities(
+    chapters: Iterable[Mapping[str, Any]],
+    *,
+    language: str = "en",
+) -> EntityExtractionResult:
+    start = time.perf_counter()
+    normalized_language = language or "en"
+    combined_hasher = hashlib.sha1()
+    chapter_texts: List[Tuple[int, str]] = []
+    for idx, chapter in enumerate(chapters):
+        text = chapter.get("text") if isinstance(chapter, Mapping) else None
+        text_value = str(text or "")
+        original_index = idx
+        if isinstance(chapter, Mapping):
+            try:
+                original_index = int(chapter.get("index", idx))
+            except (TypeError, ValueError):
+                original_index = idx
+        chapter_texts.append((original_index, text_value))
+        if text_value:
+            combined_hasher.update(text_value.encode("utf-8", "ignore"))
+            combined_hasher.update(str(original_index).encode("utf-8", "ignore"))
+    cache_key = combined_hasher.hexdigest()
+
+    if not chapter_texts:
+        return _empty_result(cache_key)
+
+    try:
+        nlp = _load_model(normalized_language)
+    except EntityModelError as exc:
+        return _empty_result(cache_key, str(exc))
+
+    records: Dict[Tuple[str, str], EntityRecord] = {}
+    tokens_for_index: Dict[str, Dict[str, Any]] = {}
+    processed_tokens = 0
+
+    for chapter_index, text in chapter_texts:
+        trimmed = text.strip()
+        if not trimmed:
+            continue
+        if len(trimmed) + 1024 > nlp.max_length:
+            nlp.max_length = len(trimmed) + 1024
+        doc = nlp(trimmed)
+
+        def _register_span(span: Any, category_hint: Optional[str] = None) -> None:
+            nonlocal processed_tokens
+            if category_hint is None and span.label_ in _EXCLUDED_NER_LABELS:
+                return
+            cleaned = _normalize_label(span.text)
+            if not cleaned:
+                return
+            key = _token_key(cleaned)
+            if not key:
+                return
+            category = category_hint or (
+                "people" if span.label_ == "PERSON" else "entities"
+            )
+            record_key = (category, key)
+            record = records.get(record_key)
+            if record is None:
+                record = EntityRecord(
+                    key=record_key,
+                    label=cleaned,
+                    kind=span.label_
+                    or ("PROPN" if category == "entities" else "PERSON"),
+                    category=category,
+                )
+                records[record_key] = record
+            sentence = (
+                span.sent.text
+                if hasattr(span, "sent") and span.sent is not None
+                else None
+            )
+            record.register(
+                chapter_index=chapter_index,
+                position=span.start,
+                text=span.text,
+                sentence=sentence,
+            )
+            processed_tokens += 1
+            index_entry = tokens_for_index.get(key)
+            if index_entry is None:
+                index_entry = {
+                    "token": record.label,
+                    "normalized": key,
+                    "category": category,
+                    "count": 0,
+                    "samples": [],
+                }
+                tokens_for_index[key] = index_entry
+            index_entry["count"] += 1
+            if sentence and len(index_entry["samples"]) < 3:
+                if sentence not in index_entry["samples"]:
+                    index_entry["samples"].append(sentence)
+
+        for ent in _iter_named_entities(doc):
+            _register_span(ent)
+
+        for span in _extract_propn_tokens(doc):
+            _register_span(span, category_hint="entities")
+
+    elapsed = time.perf_counter() - start
+
+    people_records = [
+        record for record in records.values() if record.category == "people"
+    ]
+    people_keys = {record.key[1] for record in people_records}
+    entity_records = [
+        record
+        for record in records.values()
+        if record.category == "entities"
+        and record.key[1] not in people_keys
+        and record.kind != "PERSON"
+    ]
+
+    people_records.sort(key=lambda rec: (-rec.count, rec.label))
+    entity_records.sort(key=lambda rec: (-rec.count, rec.label))
+
+    people_payload = [
+        record.as_dict(index + 1) for index, record in enumerate(people_records)
+    ]
+    entity_payload = [
+        record.as_dict(index + 1) for index, record in enumerate(entity_records)
+    ]
+
+    index_payload = sorted(
+        tokens_for_index.values(), key=lambda item: (-item["count"], item["token"])
+    )
+
+    summary = {
+        "people": people_payload,
+        "entities": entity_payload,
+        "index": {"tokens": index_payload},
+        "stats": {
+            "tokens": processed_tokens,
+            "chapters": len(chapter_texts),
+            "processed": True,
+            "people": len(people_payload),
+            "entities": len(entity_payload),
+        },
+        "model": {
+            "name": getattr(nlp, "meta", {}).get("name", "unknown"),
+            "version": getattr(nlp, "meta", {}).get("version", "unknown"),
+            "lang": getattr(nlp, "meta", {}).get("lang", normalized_language),
+        },
+    }
+
+    return EntityExtractionResult(
+        summary=summary, cache_key=cache_key, elapsed=elapsed, errors=[]
+    )
+
+
+def search_tokens(
+    index: Mapping[str, Any], query: str, *, limit: int = 15
+) -> List[Dict[str, Any]]:
+    tokens = index.get("tokens") if isinstance(index, Mapping) else None
+    if not isinstance(tokens, list) or not query:
+        return []
+    normalized = query.strip().lower()
+    if not normalized:
+        return tokens[:limit]
+    results: List[Dict[str, Any]] = []
+    for entry in tokens:
+        token_label = str(entry.get("token", ""))
+        normalized_label = token_label.lower()
+        if normalized in normalized_label or normalized in str(
+            entry.get("normalized", "")
+        ):
+            results.append(entry)
+        if len(results) >= limit:
+            break
+    return results
+
+
+def merge_override(
+    summary: Mapping[str, Any], overrides: Mapping[str, Mapping[str, Any]]
+) -> Dict[str, Any]:
+    if not isinstance(summary, Mapping):
+        return {"people": [], "entities": []}
+    merged_summary: Dict[str, Any] = dict(summary)
+    for key in ("people", "entities"):
+        items = summary.get(key)
+        if not isinstance(items, list):
+            continue
+        merged_items: List[Dict[str, Any]] = []
+        for entry in items:
+            if not isinstance(entry, Mapping):
+                continue
+            normalized = _token_key(
+                str(entry.get("normalized") or entry.get("label") or "")
+            )
+            merged = dict(entry)
+            if normalized and normalized in overrides:
+                merged_override = dict(overrides[normalized])
+                merged["override"] = merged_override
+            merged_items.append(merged)
+        merged_summary[key] = merged_items
+    return merged_summary
+
+
+def normalize_token(token: str) -> str:
+    return _token_key(_normalize_label(token))
+
+
+def normalize_manual_override_token(token: str) -> str:
+    if not token:
+        return ""
+    stripped = token.strip().strip("\"'`“”’")
+    if not stripped:
+        return ""
+    return _MULTI_SPACE_PATTERN.sub(" ", stripped.lower()).strip()

abogen/epub3/__init__.py

@@ -0,0 +1,3 @@
+from .exporter import EPUB3PackageBuilder, build_epub3_package
+
+__all__ = ["EPUB3PackageBuilder", "build_epub3_package"]

abogen/epub3/exporter.py

@@ -0,0 +1,910 @@
+from __future__ import annotations
+
+import html
+import re
+import shutil
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Any, Dict, Iterable, List, Optional, Pattern, Sequence, Tuple
+import zipfile
+
+from abogen.text_extractor import ExtractedChapter, ExtractionResult
+
+
+@dataclass(slots=True)
+class ChunkOverlay:
+    id: str
+    text: str
+    original_text: Optional[str]
+    start: Optional[float]
+    end: Optional[float]
+    speaker_id: str
+    voice: Optional[str]
+    level: Optional[str] = None
+    group_id: Optional[str] = None
+
+
+@dataclass(slots=True)
+class ChapterDocument:
+    index: int  # zero-based
+    title: str
+    xhtml_name: str
+    smil_name: str
+    chunks: List[ChunkOverlay]
+    start: Optional[float]
+    end: Optional[float]
+
+
+class EPUB3PackageBuilder:
+    """Constructs an EPUB 3 package with media overlays."""
+
+    def __init__(
+        self,
+        *,
+        output_path: Path,
+        book_id: str,
+        extraction: 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_image_path: Optional[Path] = None,
+        cover_image_mime: Optional[str] = None,
+    ) -> None:
+        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.chapter_markers = list(chapter_markers or [])
+        self.chunk_markers = list(chunk_markers or [])
+        self.chunks = list(chunks or [])
+        self.audio_path = audio_path
+        self.speaker_mode = speaker_mode or "single"
+        self.cover_image_path = cover_image_path if cover_image_path and cover_image_path.exists() else None
+        self.cover_image_mime = cover_image_mime
+
+        self._combined_metadata = _combine_metadata(extraction.metadata, self.metadata_tags)
+        self._title = self._combined_metadata.get("title") or self._fallback_title()
+        self._authors = _split_authors(self._combined_metadata)
+        self._language = self._determine_language()
+        self._publisher = self._combined_metadata.get("publisher") or ""
+        self._description = self._combined_metadata.get("comment")
+        self._duration = _calculate_total_duration(self.chunk_markers, self.chapter_markers)
+        self._modified = _utc_now_iso()
+
+    def build(self) -> Path:
+        if not self.audio_path or not self.audio_path.exists():
+            raise FileNotFoundError(f"Audio asset missing: {self.audio_path}")
+
+        chapter_documents = self._build_chapter_documents()
+
+        with TemporaryDirectory() as tmp_dir:
+            root = Path(tmp_dir)
+            oebps = root / "OEBPS"
+            text_dir = oebps / "text"
+            smil_dir = oebps / "smil"
+            audio_dir = oebps / "audio"
+            image_dir = oebps / "images"
+            stylesheet_dir = oebps / "styles"
+
+            for directory in (oebps, text_dir, smil_dir, audio_dir, stylesheet_dir):
+                directory.mkdir(parents=True, exist_ok=True)
+            if self.cover_image_path:
+                image_dir.mkdir(parents=True, exist_ok=True)
+
+            _write_mimetype(root)
+            _write_container_xml(root)
+
+            audio_filename = self.audio_path.name
+            embedded_audio = audio_dir / audio_filename
+            shutil.copy2(self.audio_path, embedded_audio)
+
+            if self.cover_image_path:
+                shutil.copy2(self.cover_image_path, image_dir / self.cover_image_path.name)
+
+            stylesheet_path = stylesheet_dir / "style.css"
+            stylesheet_path.write_text(_DEFAULT_STYLESHEET, encoding="utf-8")
+
+            for chapter in chapter_documents:
+                chapter_path = text_dir / chapter.xhtml_name
+                chapter_path.write_text(
+                    self._render_chapter_xhtml(chapter),
+                    encoding="utf-8",
+                )
+                smil_path = smil_dir / chapter.smil_name
+                smil_path.write_text(
+                    self._render_chapter_smil(chapter, f"audio/{audio_filename}"),
+                    encoding="utf-8",
+                )
+
+            nav_path = oebps / "nav.xhtml"
+            nav_path.write_text(self._render_nav(chapter_documents), encoding="utf-8")
+
+            opf_path = oebps / "content.opf"
+            opf_path.write_text(
+                self._render_opf(
+                    chapter_documents,
+                    audio_filename,
+                    has_cover=self.cover_image_path is not None,
+                    stylesheet_path=stylesheet_path.relative_to(oebps),
+                ),
+                encoding="utf-8",
+            )
+
+            self.output_path.parent.mkdir(parents=True, exist_ok=True)
+            with zipfile.ZipFile(self.output_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+                # Ensure mimetype is the first entry and stored without compression
+                mimetype_path = root / "mimetype"
+                info = zipfile.ZipInfo("mimetype")
+                info.compress_type = zipfile.ZIP_STORED
+                archive.writestr(info, mimetype_path.read_bytes())
+
+                for file_path in sorted(root.rglob("*")):
+                    if file_path == mimetype_path or file_path.is_dir():
+                        continue
+                    archive.write(file_path, file_path.relative_to(root))
+
+        return self.output_path
+
+    # ------------------------------------------------------------------
+    def _build_chapter_documents(self) -> List[ChapterDocument]:
+        chunk_lookup = _build_chunk_lookup(self.chunks)
+        markers_by_chapter = _group_markers_by_chapter(self.chunk_markers)
+        chapter_meta = {int(entry.get("index", idx + 1)) - 1: dict(entry) for idx, entry in enumerate(self.chapter_markers)}
+
+        documents: List[ChapterDocument] = []
+        for chapter_index, chapter in enumerate(self.extraction.chapters):
+            markers = markers_by_chapter.get(chapter_index, [])
+            if not markers and chunk_lookup.by_chapter.get(chapter_index):
+                markers = [
+                    {
+                        "id": item.get("id"),
+                        "chapter_index": chapter_index,
+                        "chunk_index": item.get("chunk_index"),
+                        "start": None,
+                        "end": None,
+                        "speaker_id": item.get("speaker_id", "narrator"),
+                        "voice": item.get("voice"),
+                    }
+                    for item in chunk_lookup.by_chapter.get(chapter_index, [])
+                ]
+
+            if not markers:
+                markers = [
+                    {
+                        "id": f"chap{chapter_index:04d}_auto0000",
+                        "chapter_index": chapter_index,
+                        "chunk_index": 0,
+                        "start": chapter_meta.get(chapter_index, {}).get("start"),
+                        "end": chapter_meta.get(chapter_index, {}).get("end"),
+                        "speaker_id": "narrator",
+                        "voice": None,
+                    }
+                ]
+
+            overlays = self._build_overlays_for_chapter(
+                chapter_index,
+                markers,
+                chunk_lookup,
+            )
+
+            xhtml_name = f"chapter_{chapter_index + 1:04d}.xhtml"
+            smil_name = f"chapter_{chapter_index + 1:04d}.smil"
+
+            chapter_start = chapter_meta.get(chapter_index, {}).get("start")
+            chapter_end = chapter_meta.get(chapter_index, {}).get("end")
+
+            documents.append(
+                ChapterDocument(
+                    index=chapter_index,
+                    title=chapter.title or f"Chapter {chapter_index + 1}",
+                    xhtml_name=xhtml_name,
+                    smil_name=smil_name,
+                    chunks=overlays,
+                    start=chapter_start,
+                    end=chapter_end,
+                )
+            )
+
+        return documents
+
+    def _build_overlays_for_chapter(
+        self,
+        chapter_index: int,
+        markers: Sequence[Dict[str, Any]],
+        chunk_lookup: "ChunkLookup",
+    ) -> List[ChunkOverlay]:
+        overlays: List[ChunkOverlay] = []
+        used_ids: set[str] = set()
+
+        chapter_chunks = list(chunk_lookup.by_chapter.get(chapter_index, []))
+        chapter_chunks.sort(key=lambda entry: _safe_int(entry.get("chunk_index")))
+
+        for position, marker in enumerate(markers):
+            chunk_id = marker.get("id")
+            chunk_entry = None
+            if chunk_id and chunk_id in chunk_lookup.by_id:
+                chunk_entry = chunk_lookup.by_id[chunk_id]
+            else:
+                candidate_index = _safe_int(marker.get("chunk_index"))
+                chunk_entry = _find_chunk_by_index(chapter_chunks, candidate_index)
+                if chunk_entry is None and chapter_chunks and position < len(chapter_chunks):
+                    chunk_entry = chapter_chunks[position]
+
+            level = None
+            if chunk_entry is None:
+                text = self.extraction.chapters[chapter_index].text
+                speaker_id = str(marker.get("speaker_id") or "narrator")
+                voice = marker.get("voice")
+            else:
+                display_text = chunk_entry.get("display_text")
+                text = str(chunk_entry.get("text") or "")
+                speaker_id = str(chunk_entry.get("speaker_id") or marker.get("speaker_id") or "narrator")
+                voice = chunk_entry.get("voice") or chunk_entry.get("resolved_voice") or marker.get("voice")
+                level = chunk_entry.get("level") or None
+            if chunk_entry is None:
+                level = None
+
+            normalized_id = _normalize_chunk_id(chunk_id) if chunk_id else None
+            if not normalized_id:
+                normalized_id = f"chap{chapter_index:04d}_chunk{position:04d}"
+            while normalized_id in used_ids:
+                normalized_id = f"{normalized_id}_dup"
+            used_ids.add(normalized_id)
+
+            raw_group_key = chunk_entry.get("id") if chunk_entry else chunk_id
+            group_id = _derive_group_id(raw_group_key, level)
+            normalized_group_id = _normalize_chunk_id(group_id) if group_id else None
+
+            original_text = None
+            if chunk_entry is not None:
+                original_text = chunk_entry.get("original_text") or chunk_entry.get("display_text")
+
+            overlays.append(
+                ChunkOverlay(
+                    id=normalized_id,
+                    text=text or self.extraction.chapters[chapter_index].text,
+                    original_text=str(original_text) if original_text is not None else None,
+                    start=_safe_float(marker.get("start")),
+                    end=_safe_float(marker.get("end")),
+                    speaker_id=speaker_id,
+                    voice=str(voice) if voice else None,
+                    level=str(level) if level else None,
+                    group_id=normalized_group_id,
+                )
+            )
+
+        chapter_text = ""
+        if 0 <= chapter_index < len(self.extraction.chapters):
+            chapter_entry = self.extraction.chapters[chapter_index]
+            chapter_text = getattr(chapter_entry, "text", "") or ""
+
+        _restore_original_chunk_text(chapter_text, overlays)
+
+        return overlays
+
+    def _render_chapter_xhtml(self, chapter: ChapterDocument) -> str:
+        language = html.escape(self._language or "en")
+        title = html.escape(chapter.title)
+        grouped_chunks = _group_chunks_for_render(chapter.chunks)
+        chunk_html = "\n".join(
+            _render_chunk_group_html(group_id, items) for group_id, items in grouped_chunks
+        )
+        if not chunk_html:
+            chunk_html = "<p></p>"
+        original_block = ""
+        if chapter.chunks:
+            original_text = "".join((chunk.original_text if chunk.original_text is not None else (chunk.text or "")) for chunk in chapter.chunks)
+            if original_text:
+                safe_original = html.escape(original_text)
+                original_block = (
+                    "      <pre class=\"chapter-original\" hidden=\"hidden\" aria-hidden=\"true\">\n"
+                    f"{safe_original}\n"
+                    "      </pre>"
+                )
+
+        return (
+            "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n"
+            "<html xmlns=\"http://www.w3.org/1999/xhtml\" xmlns:epub=\"http://www.idpf.org/2007/ops\" xml:lang=\"{lang}\" lang=\"{lang}\">\n"
+            "  <head>\n"
+            "    <title>{title}</title>\n"
+            "    <meta charset=\"utf-8\"/>\n"
+            "    <link rel=\"stylesheet\" type=\"text/css\" href=\"styles/style.css\"/>\n"
+            "  </head>\n"
+            "  <body>\n"
+            "    <section epub:type=\"chapter\" id=\"chapter-{index:04d}\">\n"
+            "      <h1>{title}</h1>\n"
+            "      {chunks}\n"
+            "{original_block}"
+            "    </section>\n"
+            "  </body>\n"
+            "</html>\n"
+        ).format(
+            lang=language,
+            title=title,
+            index=chapter.index + 1,
+            chunks=chunk_html,
+            original_block=("" if not original_block else f"{original_block}\n"),
+        )
+
+    def _render_chapter_smil(self, chapter: ChapterDocument, audio_href: str) -> str:
+        par_lines = []
+        for chunk in chapter.chunks:
+            par_lines.append(
+                "      <par id=\"par-{chunk_id}\">\n"
+                "        <text src=\"text/{xhtml}#{chunk_id}\"/>\n"
+                "        <audio src=\"{audio}\" clipBegin=\"{start}\" clipEnd=\"{end}\"/>\n"
+                "      </par>".format(
+                    chunk_id=html.escape(chunk.id),
+                    xhtml=html.escape(chapter.xhtml_name),
+                    audio=html.escape(audio_href),
+                    start=_format_smil_time(chunk.start),
+                    end=_format_smil_time(chunk.end),
+                )
+            )
+
+        return (
+            "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n"
+            "<smil xmlns=\"http://www.w3.org/2001/SMIL20/Language\" xmlns:epub=\"http://www.idpf.org/2007/ops\">\n"
+            "  <head>\n"
+            "    <meta name=\"dc:title\" content=\"{title}\"/>\n"
+            "    <meta name=\"dtb:uid\" content=\"{book_id}\"/>\n"
+            "    <meta name=\"dtb:generator\" content=\"Abogen\"/>\n"
+            "  </head>\n"
+            "  <body>\n"
+            "    <seq id=\"seq-{index:04d}\" epub:textref=\"text/{xhtml}\">\n"
+            "{pars}\n"
+            "    </seq>\n"
+            "  </body>\n"
+            "</smil>\n"
+        ).format(
+            title=html.escape(chapter.title),
+            book_id=html.escape(self.book_id),
+            index=chapter.index + 1,
+            xhtml=html.escape(chapter.xhtml_name),
+            pars="\n".join(par_lines) if par_lines else "      <par/>",
+        )
+
+    def _render_nav(self, chapters: Sequence[ChapterDocument]) -> str:
+        items = []
+        for chapter in chapters:
+            href = f"text/{chapter.xhtml_name}"
+            items.append(
+                "        <li><a href=\"{href}\">{title}</a></li>".format(
+                    href=html.escape(href),
+                    title=html.escape(chapter.title),
+                )
+            )
+
+        return (
+            "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n"
+            "<html xmlns=\"http://www.w3.org/1999/xhtml\" xmlns:epub=\"http://www.idpf.org/2007/ops\" xml:lang=\"{lang}\">\n"
+            "  <head>\n"
+            "    <title>Navigation</title>\n"
+            "    <meta charset=\"utf-8\"/>\n"
+            "  </head>\n"
+            "  <body>\n"
+            "    <nav epub:type=\"toc\" id=\"toc\">\n"
+            "      <h1>{title}</h1>\n"
+            "      <ol>\n"
+            "{items}\n"
+            "      </ol>\n"
+            "    </nav>\n"
+            "  </body>\n"
+            "</html>\n"
+        ).format(
+            lang=html.escape(self._language or "en"),
+            title=html.escape(self._title),
+            items="\n".join(items) if items else "        <li><a href=\"text/chapter_0001.xhtml\">Chapter 1</a></li>",
+        )
+
+    def _render_opf(
+        self,
+        chapters: Sequence[ChapterDocument],
+        audio_filename: str,
+        *,
+        has_cover: bool,
+        stylesheet_path: Path,
+    ) -> str:
+        manifest_items = []
+        spine_refs = []
+        for chapter in chapters:
+            item_id = f"chap{chapter.index + 1:04d}"
+            overlay_id = f"mo-{chapter.index + 1:04d}"
+            manifest_items.append(
+                "    <item id=\"{item_id}\" href=\"text/{href}\" media-type=\"application/xhtml+xml\" media-overlay=\"{overlay_id}\"/>".format(
+                    item_id=item_id,
+                    href=html.escape(chapter.xhtml_name),
+                    overlay_id=overlay_id,
+                )
+            )
+            manifest_items.append(
+                "    <item id=\"{overlay_id}\" href=\"smil/{smil}\" media-type=\"application/smil+xml\"/>".format(
+                    overlay_id=overlay_id,
+                    smil=html.escape(chapter.smil_name),
+                )
+            )
+            spine_refs.append(f"    <itemref idref=\"{item_id}\"/>")
+
+        audio_item_id = "primary-audio"
+        manifest_items.append(
+            "    <item id=\"{item_id}\" href=\"audio/{href}\" media-type=\"{mime}\"/>".format(
+                item_id=audio_item_id,
+                href=html.escape(audio_filename),
+                mime=_detect_audio_mime(audio_filename),
+            )
+        )
+
+        manifest_items.append(
+            "    <item id=\"nav\" href=\"nav.xhtml\" media-type=\"application/xhtml+xml\" properties=\"nav\"/>"
+        )
+
+        manifest_items.append(
+            "    <item id=\"style\" href=\"{href}\" media-type=\"text/css\"/>".format(
+                href=html.escape(str(stylesheet_path).replace("\\", "/")),
+            )
+        )
+
+        if has_cover and self.cover_image_path:
+            cover_id = "cover-image"
+            manifest_items.append(
+                "    <item id=\"{item_id}\" href=\"images/{href}\" media-type=\"{mime}\" properties=\"cover-image\"/>".format(
+                    item_id=cover_id,
+                    href=html.escape(self.cover_image_path.name),
+                    mime=self.cover_image_mime or _detect_image_mime(self.cover_image_path.suffix),
+                )
+            )
+
+        metadata_elements = _render_metadata_xml(
+            self._title,
+            self._authors,
+            self._language,
+            self.book_id,
+            duration=self._duration,
+            publisher=self._publisher,
+            description=self._description,
+            speaker_mode=self.speaker_mode,
+            modified=self._modified,
+        )
+
+        return (
+            "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n"
+            "<package xmlns=\"http://www.idpf.org/2007/opf\" version=\"3.0\" unique-identifier=\"book-id\">\n"
+            "  <metadata xmlns:dc=\"http://purl.org/dc/elements/1.1/\" xmlns:opf=\"http://www.idpf.org/2007/opf\" xmlns:media=\"http://www.idpf.org/epub/vocab/mediaoverlays/#\" xmlns:abogen=\"https://abogen.app/ns#\" xmlns:dcterms=\"http://purl.org/dc/terms/\">\n"
+            "{metadata}\n"
+            "  </metadata>\n"
+            "  <manifest>\n"
+            "{manifest}\n"
+            "  </manifest>\n"
+            "  <spine>\n"
+            "{spine}\n"
+            "  </spine>\n"
+            "</package>\n"
+        ).format(
+            metadata="\n".join(metadata_elements),
+            manifest="\n".join(manifest_items),
+            spine="\n".join(spine_refs) if spine_refs else "    <itemref idref=\"chap0001\"/>",
+        )
+
+    def _fallback_title(self) -> str:
+        if self.extraction.chapters:
+            first_title = self.extraction.chapters[0].title
+            if first_title:
+                return first_title
+        return "Generated Audiobook"
+
+    def _determine_language(self) -> str:
+        language = self._combined_metadata.get("language")
+        if language:
+            return language
+        return "en"
+
+
+def build_epub3_package(
+    *,
+    output_path: Path,
+    book_id: str,
+    extraction: 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_image_path: Optional[Path] = None,
+    cover_image_mime: Optional[str] = None,
+) -> Path:
+    builder = EPUB3PackageBuilder(
+        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_image_path,
+        cover_image_mime=cover_image_mime,
+    )
+    return builder.build()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+
+
+@dataclass
+class ChunkLookup:
+    by_id: Dict[str, Dict[str, Any]]
+    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:
+        for key, value in (source or {}).items():
+            if value is None:
+                continue
+            combined[str(key).lower()] = str(value)
+    return combined
+
+
+def _split_authors(metadata: Dict[str, str]) -> List[str]:
+    candidates = []
+    for key in ("artist", "author", "authors", "album_artist", "creator"):
+        value = metadata.get(key)
+        if value:
+            candidates.extend(part.strip() for part in value.replace(";", ",").split(","))
+    return [author for author in candidates if author]
+
+
+def _calculate_total_duration(
+    chunk_markers: Sequence[Dict[str, Any]],
+    chapter_markers: Sequence[Dict[str, Any]],
+) -> Optional[float]:
+    candidates: List[float] = []
+    for marker in chunk_markers or []:
+        end_value = _safe_float(marker.get("end"))
+        if end_value is not None:
+            candidates.append(end_value)
+    for marker in chapter_markers or []:
+        end_value = _safe_float(marker.get("end"))
+        if end_value is not None:
+            candidates.append(end_value)
+    if not candidates:
+        return None
+    return max(candidates)
+
+
+def _write_mimetype(root: Path) -> None:
+    (root / "mimetype").write_text("application/epub+zip", encoding="utf-8")
+
+
+def _write_container_xml(root: Path) -> None:
+    meta_inf = root / "META-INF"
+    meta_inf.mkdir(parents=True, exist_ok=True)
+    container = meta_inf / "container.xml"
+    container.write_text(
+        (
+            "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"
+            "<container version=\"1.0\" xmlns=\"urn:oasis:names:tc:opendocument:xmlns:container\">\n"
+            "  <rootfiles>\n"
+            "    <rootfile full-path=\"OEBPS/content.opf\" media-type=\"application/oebps-package+xml\"/>\n"
+            "  </rootfiles>\n"
+            "</container>\n"
+        ),
+        encoding="utf-8",
+    )
+
+
+def _build_chunk_lookup(chunks: Iterable[Dict[str, Any]]) -> ChunkLookup:
+    by_id: Dict[str, Dict[str, Any]] = {}
+    by_chapter: Dict[int, List[Dict[str, Any]]] = {}
+    for entry in chunks or []:
+        if not isinstance(entry, dict):
+            continue
+        chunk_id = entry.get("id")
+        if chunk_id:
+            by_id[str(chunk_id)] = dict(entry)
+        chapter_index = _safe_int(entry.get("chapter_index"))
+        by_chapter.setdefault(chapter_index, []).append(dict(entry))
+    return ChunkLookup(by_id=by_id, by_chapter=by_chapter)
+
+
+def _group_markers_by_chapter(markers: Iterable[Dict[str, Any]]) -> Dict[int, List[Dict[str, Any]]]:
+    grouped: Dict[int, List[Dict[str, Any]]] = {}
+    for entry in markers or []:
+        if not isinstance(entry, dict):
+            continue
+        chapter_index = _safe_int(entry.get("chapter_index"))
+        grouped.setdefault(chapter_index, []).append(dict(entry))
+    for chapter_index, items in grouped.items():
+        items.sort(key=lambda payload: (_safe_int(payload.get("chunk_index")), _safe_float(payload.get("start")) or 0.0))
+    return grouped
+
+
+def _find_chunk_by_index(
+    chapter_chunks: Sequence[Dict[str, Any]],
+    chunk_index: Optional[int],
+) -> Optional[Dict[str, Any]]:
+    if chunk_index is None:
+        return None
+    for entry in chapter_chunks:
+        if _safe_int(entry.get("chunk_index")) == chunk_index:
+            return entry
+    return None
+
+
+def _normalize_chunk_id(chunk_id: Optional[Any]) -> Optional[str]:
+    if chunk_id is None:
+        return None
+    text = str(chunk_id).strip()
+    if not text:
+        return None
+    safe = "".join(ch if ch.isalnum() or ch in {"_", "-"} else "_" for ch in text)
+    return safe[:120]
+
+
+def _derive_group_id(chunk_id: Optional[Any], level: Optional[Any]) -> Optional[str]:
+    if chunk_id is None:
+        return None
+    text = str(chunk_id).strip()
+    if not text:
+        return None
+    if str(level or "").lower() == "sentence":
+        match = re.match(r"(.+?)_s\d+(?:_.*)?$", text)
+        if match:
+            return match.group(1)
+    return text
+
+
+def _group_chunks_for_render(chunks: Sequence[ChunkOverlay]) -> List[Tuple[Optional[str], List[ChunkOverlay]]]:
+    groups: List[Tuple[Optional[str], List[ChunkOverlay]]] = []
+    current_key: Optional[str] = None
+    current_items: List[ChunkOverlay] = []
+
+    for chunk in chunks:
+        key = chunk.group_id or chunk.id
+        if current_items and key != current_key:
+            groups.append((current_key, current_items))
+            current_items = []
+        if not current_items:
+            current_key = key
+        current_items.append(chunk)
+
+    if current_items:
+        groups.append((current_key, current_items))
+
+    return groups
+
+
+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 ""
+    level_attr = f" data-level=\"{html.escape(chunk.level)}\"" if chunk.level else ""
+    raw_text = chunk.text or ""
+    escaped_text = html.escape(raw_text)
+    if not escaped_text:
+        escaped_text = "&nbsp;"
+    return (
+        f"<span class=\"chunk\" id=\"{escaped_id}\"{speaker_attr}{voice_attr}{level_attr}>"
+        f"{escaped_text}"
+        "</span>"
+    )
+
+
+def _render_chunk_group_html(group_id: Optional[str], chunks: Sequence[ChunkOverlay]) -> str:
+    if not chunks:
+        return ""
+    group_attr = f" data-group=\"{html.escape(group_id)}\"" if group_id else ""
+    inline_html = "".join(_render_chunk_inline(chunk) for chunk in chunks)
+    if not inline_html:
+        inline_html = "&nbsp;"
+    return f"      <p class=\"chunk-group\"{group_attr}>{inline_html}</p>"
+
+
+def _format_smil_time(value: Optional[float]) -> str:
+    if value is None or value < 0:
+        value = 0.0
+    total_ms = int(round(value * 1000))
+    hours, remainder = divmod(total_ms, 3600_000)
+    minutes, remainder = divmod(remainder, 60_000)
+    seconds, milliseconds = divmod(remainder, 1000)
+    return f"{hours:02d}:{minutes:02d}:{seconds:02d}.{milliseconds:03d}"
+
+
+def _safe_int(value: Any, default: int = 0) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _safe_float(value: Any) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _restore_original_chunk_text(chapter_text: str, overlays: List[ChunkOverlay]) -> None:
+    if not chapter_text or not overlays:
+        return
+
+    cursor = 0
+    for chunk in overlays:
+        if chunk.original_text is not None:
+            prepared = _prepare_display_text(chunk.original_text)
+            chunk.text = prepared
+            continue
+        candidate = chunk.text or ""
+        if not candidate:
+            continue
+        match = _search_original_span(chapter_text, candidate, cursor)
+        if match is None and cursor:
+            match = _search_original_span(chapter_text, candidate, 0)
+        if match is None:
+            if chunk.original_text is None:
+                chunk.original_text = chunk.text
+            chunk.text = _prepare_display_text(chunk.text or "")
+            continue
+        start, end = match
+        segment = chapter_text[start:end]
+        chunk.original_text = segment
+        chunk.text = _prepare_display_text(segment)
+        cursor = end
+
+
+def _prepare_display_text(value: str) -> str:
+    if not value:
+        return ""
+    cleaned = re.sub(r"(?:[ \t]*\r?\n)+\Z", "", value)
+    return cleaned if cleaned else ""
+
+
+def _search_original_span(source: str, normalized: str, start: int) -> Optional[Tuple[int, int]]:
+    if not normalized:
+        return None
+    pattern = _build_chunk_pattern(normalized)
+    match = pattern.search(source, start)
+    if not match:
+        return None
+    return match.start(1), match.end(1)
+
+
+_CHUNK_REGEX_CACHE: Dict[str, Pattern[str]] = {}
+
+
+def _build_chunk_pattern(text: str) -> Pattern[str]:
+    cached = _CHUNK_REGEX_CACHE.get(text)
+    if cached is not None:
+        return cached
+    escaped = re.escape(text)
+    escaped = escaped.replace(r"\ ", r"\s+")
+    pattern = re.compile(r"(\s*" + escaped + r"\s*)", re.DOTALL)
+    _CHUNK_REGEX_CACHE[text] = pattern
+    return pattern
+
+
+def _render_metadata_xml(
+    title: str,
+    authors: Sequence[str],
+    language: str,
+    book_id: str,
+    *,
+    duration: Optional[float],
+    publisher: Optional[str],
+    description: Optional[str],
+    speaker_mode: Optional[str],
+    modified: Optional[str],
+) -> List[str]:
+    elements = [
+        f"    <dc:identifier id=\"book-id\">{html.escape(book_id)}</dc:identifier>",
+        f"    <dc:title>{html.escape(title)}</dc:title>",
+        f"    <dc:language>{html.escape(language or 'en')}</dc:language>",
+    ]
+
+    for author in authors or ["Unknown"]:
+        elements.append(f"    <dc:creator>{html.escape(author)}</dc:creator>")
+
+    if publisher:
+        elements.append(f"    <dc:publisher>{html.escape(publisher)}</dc:publisher>")
+
+    if description:
+        elements.append(f"    <dc:description>{html.escape(description)}</dc:description>")
+
+    if duration is not None:
+        elements.append(f"    <meta property=\"media:duration\">{_format_iso_duration(duration)}</meta>")
+
+    if speaker_mode:
+        elements.append(
+            "    <meta property=\"abogen:speakerMode\">{}</meta>".format(
+                html.escape(str(speaker_mode))
+            )
+        )
+
+    if modified:
+        elements.append(f"    <meta property=\"dcterms:modified\">{html.escape(modified)}</meta>")
+    return elements
+
+
+def _format_iso_duration(value: float) -> str:
+    total_seconds = int(value)
+    remainder = value - total_seconds
+    hours, remainder_seconds = divmod(total_seconds, 3600)
+    minutes, seconds = divmod(remainder_seconds, 60)
+    seconds_with_fraction = seconds + remainder
+    if seconds_with_fraction.is_integer():
+        seconds_text = f"{int(seconds_with_fraction)}"
+    else:
+        seconds_text = f"{seconds_with_fraction:.3f}".rstrip("0").rstrip(".")
+    return f"PT{hours}H{minutes}M{seconds_text}S"
+
+
+def _detect_audio_mime(audio_filename: str) -> str:
+    suffix = Path(audio_filename).suffix.lower()
+    return {
+        ".mp3": "audio/mpeg",
+        ".m4a": "audio/mp4",
+        ".m4b": "audio/mp4",
+        ".aac": "audio/aac",
+        ".wav": "audio/wav",
+        ".flac": "audio/flac",
+        ".ogg": "audio/ogg",
+        ".opus": "audio/ogg",
+    }.get(suffix, "audio/mpeg")
+
+
+def _detect_image_mime(suffix: str) -> str:
+    normalized = suffix.lower()
+    return {
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".png": "image/png",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+    }.get(normalized, "image/jpeg")
+
+
+def _utc_now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+_DEFAULT_STYLESHEET = """
+body {
+  font-family: 'Georgia', serif;
+  line-height: 1.6;
+  margin: 1.5em;
+}
+
+h1 {
+  font-size: 1.5em;
+  margin-bottom: 0.5em;
+}
+
+.chunk-group {
+    margin: 0.5em 0;
+}
+
+.chunk-group .chunk {
+    white-space: pre-wrap;
+}
+"""

abogen/frontend/__init__.py

@@ -0,0 +1,8 @@
+"""
+Abogen Flet Frontend Package.
+
+This package provides a unified, dual-target (desktop + web) user interface
+for the Abogen audiobook generation application, built with the Flet framework.
+"""
+
+__all__ = ["main"]

abogen/frontend/components/__init__.py

@@ -0,0 +1,32 @@
+"""Components sub-package."""
+from .widgets import (
+    resolve_icon,
+    build_drop_zone,
+    build_log_terminal,
+    log_entry,
+    build_progress_row,
+    build_primary_button,
+    build_secondary_button,
+    build_card,
+    build_section_header,
+    build_status_badge,
+    labelled_row,
+    show_snack,
+    build_divider,
+)
+
+__all__ = [
+    "build_drop_zone",
+    "resolve_icon",
+    "build_log_terminal",
+    "log_entry",
+    "build_progress_row",
+    "build_primary_button",
+    "build_secondary_button",
+    "build_card",
+    "build_section_header",
+    "build_status_badge",
+    "labelled_row",
+    "show_snack",
+    "build_divider",
+]

abogen/frontend/components/widgets.py

@@ -0,0 +1,630 @@
+"""
+Reusable UI components for the Abogen Flet frontend.
+
+Each function in this module returns a standalone Flet control or small
+widget tree.  Components read the current palette from the page's theme
+mode and should not hold any mutable state themselves – state lives in the
+session's ``AppState`` object.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, List, Optional
+
+import flet as ft
+
+from ..utils.theme import get_palette, RADIUS_MD, RADIUS_SM, SPACE_SM, SPACE_MD, SPACE_LG
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def resolve_icon(icon: Any) -> Any:
+    """Convert a snake_case icon name to Flet IconData when possible."""
+    if isinstance(icon, str):
+        return getattr(ft.Icons, icon.upper(), icon)
+    return icon
+
+
+# ---------------------------------------------------------------------------
+# Drop-zone (file input area)
+# ---------------------------------------------------------------------------
+
+
+def build_drop_zone(
+    *,
+    on_pick: Callable[[], None],
+    label: str = "Drag & drop your file here or click to browse",
+    sub_label: str = "Supports: .txt · .epub · .pdf · .md · .srt · .ass · .vtt",
+    accent: bool = False,
+    error: bool = False,
+    filename: Optional[str] = None,
+    file_size: Optional[str] = None,
+    char_count: Optional[str] = None,
+    page: Optional[ft.Page] = None,
+) -> ft.GestureDetector:
+    """
+    Build an interactive file drop-zone widget.
+
+    The zone shows a dashed border and centred instructions by default,
+    switching to an 'active' green style when a file is loaded and a red
+    style when an error has occurred.
+
+    Args:
+        on_pick: Callback invoked when the user clicks or activates the zone.
+        label: Primary instruction text.
+        sub_label: Secondary hint text shown beneath the label.
+        accent: When True, renders the 'active/success' green style.
+        error: When True, renders the 'error/red' style.
+        filename: When provided, replaces the instruction text with file info.
+        file_size: Human-readable file size to display alongside the filename.
+        char_count: Character count to display alongside file info.
+        page: The current Flet ``Page``; used to derive the active palette.
+
+    Returns:
+        A ``ft.GestureDetector`` wrapping the visual drop-zone container.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    p = get_palette(page) if page else None
+
+    # Colour scheme
+    if error:
+        border_color = "#e84e3c" if dark else "#c0392b"
+        bg_color = "#1a0a08" if dark else "#fff5f5"
+        text_color = "#e84e3c" if dark else "#c0392b"
+        icon_name = "error_outline"
+    elif accent:
+        border_color = "#42ad4a" if dark else "#2e9437"
+        bg_color = "#091810" if dark else "#f0fff1"
+        text_color = "#42ad4a" if dark else "#2e9437"
+        icon_name = "check_circle_outline"
+    else:
+        border_color = "#3a4466" if dark else "#a8b4d0"
+        bg_color = "#151928" if dark else "#f7f8fd"
+        text_color = "#9ba3b8" if dark else "#5a6172"
+        icon_name = "upload_file"
+
+    if filename:
+        # Compact file-info display
+        info_rows: List[ft.Control] = [
+            ft.Row(
+                [
+                    ft.Icon(resolve_icon("insert_drive_file"), color=text_color, size=28),
+                    ft.Column(
+                        [
+                            ft.Text(
+                                filename,
+                                weight=ft.FontWeight.W_600,
+                                size=13,
+                                color=text_color,
+                                no_wrap=False,
+                                max_lines=2,
+                                overflow=ft.TextOverflow.ELLIPSIS,
+                            ),
+                        ],
+                        tight=True,
+                        expand=True,
+                    ),
+                ],
+                alignment=ft.MainAxisAlignment.CENTER,
+                spacing=SPACE_SM,
+            )
+        ]
+        if file_size or char_count:
+            chips: List[ft.Control] = []
+            if file_size:
+                chips.append(
+                    ft.Text(f"📄 {file_size}", size=11, color=text_color, italic=True)
+                )
+            if char_count:
+                chips.append(
+                    ft.Text(f"🔤 {char_count} chars", size=11, color=text_color, italic=True)
+                )
+            info_rows.append(
+                ft.Row(chips, alignment=ft.MainAxisAlignment.CENTER, spacing=SPACE_MD)
+            )
+        content = ft.Column(
+            info_rows,
+            alignment=ft.MainAxisAlignment.CENTER,
+            horizontal_alignment=ft.CrossAxisAlignment.CENTER,
+            spacing=SPACE_SM,
+        )
+    else:
+        content = ft.Column(
+            [
+                ft.Icon(resolve_icon(icon_name), size=48, color=border_color, opacity=0.8),
+                ft.Text(
+                    label,
+                    size=14,
+                    weight=ft.FontWeight.W_500,
+                    color=text_color,
+                    text_align=ft.TextAlign.CENTER,
+                ),
+                ft.Text(
+                    sub_label,
+                    size=11,
+                    color=text_color,
+                    opacity=0.6,
+                    text_align=ft.TextAlign.CENTER,
+                ),
+            ],
+            alignment=ft.MainAxisAlignment.CENTER,
+            horizontal_alignment=ft.CrossAxisAlignment.CENTER,
+            spacing=SPACE_SM,
+        )
+
+    inner = ft.Container(
+        content=content,
+        border=ft.Border.all(2, border_color),
+        border_radius=RADIUS_MD,
+        bgcolor=bg_color,
+        padding=ft.Padding.all(SPACE_LG),
+        height=160,
+        alignment=ft.Alignment.CENTER,
+        expand=True,
+    )
+
+    return ft.GestureDetector(
+        content=ft.Row([inner], spacing=0),
+        on_tap=lambda _: on_pick(),
+        mouse_cursor=ft.MouseCursor.CLICK,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Log terminal
+# ---------------------------------------------------------------------------
+
+
+def build_log_terminal(
+    *,
+    ref: Optional[ft.Ref] = None,
+    max_height: int = 260,
+    page: Optional[ft.Page] = None,
+) -> ft.Container:
+    """
+    Build a scrollable, read-only log terminal widget.
+
+    Args:
+        ref: Optional ``ft.Ref[ft.ListView]`` to bind the inner list-view so
+             callers can append entries programmatically.
+        max_height: Maximum pixel height before vertical scrolling activates.
+        page: Current Flet ``Page`` for palette derivation.
+
+    Returns:
+        A styled ``ft.Container`` wrapping a ``ft.ListView``.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    bg = "#0d1117" if dark else "#f8f9fc"
+    text_color = "#b0b8cc" if dark else "#3d4358"
+    border_color = "#252a38" if dark else "#dce0ea"
+
+    list_view = ft.ListView(
+        expand=True,
+        auto_scroll=True,
+        spacing=1,
+        padding=ft.Padding.all(SPACE_SM),
+    )
+    if ref is not None:
+        ref.current = list_view
+
+    return ft.Container(
+        content=list_view,
+        bgcolor=bg,
+        border=ft.Border.all(1, border_color),
+        border_radius=RADIUS_SM,
+        height=max_height,
+        clip_behavior=ft.ClipBehavior.HARD_EDGE,
+    )
+
+
+def log_entry(message: str, level: str = "info", page: Optional[ft.Page] = None) -> ft.Text:
+    """
+    Create a single log-line ``ft.Text`` widget with appropriate colour coding.
+
+    Args:
+        message: The log message string.
+        level: Severity string: ``'info'``, ``'success'``, ``'error'``,
+               ``'warning'``, ``'debug'``, ``'critical'``.
+        page: Current Flet ``Page`` for dark/light mode detection.
+
+    Returns:
+        A styled ``ft.Text`` control.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    palette: dict[str, str] = {
+        "info": "#9ba3b8" if dark else "#5a6172",
+        "success": "#42ad4a" if dark else "#2e9437",
+        "error": "#e84e3c" if dark else "#c0392b",
+        "warning": "#f5a623" if dark else "#d4870a",
+        "debug": "#5a6172" if dark else "#9ba3b8",
+        "critical": "#ff5722",
+        "trace": "#4e5568" if dark else "#b0b8cc",
+    }
+    color = palette.get(level.lower(), palette["info"])
+    return ft.Text(message, size=12, color=color, selectable=True, no_wrap=False)
+
+
+# ---------------------------------------------------------------------------
+# Progress row
+# ---------------------------------------------------------------------------
+
+
+def build_progress_row(
+    *,
+    progress_value: float = 0.0,
+    etr_text: str = "",
+    page: Optional[ft.Page] = None,
+) -> ft.Column:
+    """
+    Build a progress-bar + ETR-label column.
+
+    Args:
+        progress_value: Float in [0.0, 1.0].
+        etr_text: Pre-formatted estimated-time-remaining string.
+        page: Current ``Page`` for palette derivation.
+
+    Returns:
+        A ``ft.Column`` containing the progress bar and label.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    fill = "#5b8af5" if dark else "#3a5fc4"
+    bg = "#1e2230" if dark else "#e4e8f0"
+
+    bar = ft.ProgressBar(
+        value=progress_value,
+        color=fill,
+        bgcolor=bg,
+        height=8,
+        border_radius=ft.BorderRadius.all(4),
+        expand=True,
+    )
+    label = ft.Text(
+        etr_text,
+        size=11,
+        color="#9ba3b8" if dark else "#5a6172",
+        text_align=ft.TextAlign.CENTER,
+    )
+    return ft.Column(
+        [bar, label],
+        spacing=SPACE_SM,
+        horizontal_alignment=ft.CrossAxisAlignment.CENTER,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Primary action button
+# ---------------------------------------------------------------------------
+
+
+def build_primary_button(
+    text: str,
+    *,
+    icon: Optional[str] = None,
+    on_click: Optional[Callable] = None,
+    disabled: bool = False,
+    width: Optional[int] = None,
+    page: Optional[ft.Page] = None,
+) -> ft.ElevatedButton:
+    """
+    Build a prominent, styled primary action button.
+
+    Args:
+        text: Button label.
+        icon: Optional Flet icon name (e.g. ``'play_arrow'``).
+        on_click: Click callback.
+        disabled: Whether the button is non-interactive.
+        width: Optional fixed pixel width.
+        page: Current ``Page`` for accent colour derivation.
+
+    Returns:
+        A styled ``ft.ElevatedButton``.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    bg = "#5b8af5" if dark else "#3a5fc4"
+    on_bg = "#ffffff"
+
+    style = ft.ButtonStyle(
+        bgcolor={
+            ft.ControlState.DEFAULT: bg,
+            ft.ControlState.HOVERED: "#3a5fc4" if dark else "#2a4fae",
+            ft.ControlState.DISABLED: "#2a2f3f" if dark else "#c0c8d8",
+        },
+        color={
+            ft.ControlState.DEFAULT: on_bg,
+            ft.ControlState.DISABLED: "#4e5568" if dark else "#9ba3b8",
+        },
+        elevation={"default": 2, "hovered": 4},
+        padding=ft.Padding.symmetric(horizontal=SPACE_LG, vertical=SPACE_MD),
+        shape=ft.RoundedRectangleBorder(radius=RADIUS_SM),
+        animation_duration=150,
+    )
+
+    return ft.ElevatedButton(
+        content=text,
+        icon=resolve_icon(icon),
+        on_click=on_click,
+        disabled=disabled,
+        width=width,
+        style=style,
+        height=48,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Secondary / ghost button
+# ---------------------------------------------------------------------------
+
+
+def build_secondary_button(
+    text: str,
+    *,
+    icon: Optional[str] = None,
+    on_click: Optional[Callable] = None,
+    disabled: bool = False,
+    page: Optional[ft.Page] = None,
+) -> ft.OutlinedButton:
+    """
+    Build a secondary outlined button.
+
+    Args:
+        text: Button label.
+        icon: Optional Flet icon name.
+        on_click: Click callback.
+        disabled: Whether the button is non-interactive.
+        page: Current ``Page`` for border colour derivation.
+
+    Returns:
+        A styled ``ft.OutlinedButton``.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    border_clr = "#3a4466" if dark else "#a8b4d0"
+    text_clr = "#e8eaf0" if dark else "#1a1d27"
+
+    style = ft.ButtonStyle(
+        side={
+            ft.ControlState.DEFAULT: ft.BorderSide(1.5, border_clr),
+            ft.ControlState.HOVERED: ft.BorderSide(1.5, "#5b8af5" if dark else "#3a5fc4"),
+        },
+        color={
+            ft.ControlState.DEFAULT: text_clr,
+            ft.ControlState.HOVERED: "#5b8af5" if dark else "#3a5fc4",
+            ft.ControlState.DISABLED: "#4e5568" if dark else "#9ba3b8",
+        },
+        padding=ft.Padding.symmetric(horizontal=SPACE_LG, vertical=SPACE_MD),
+        shape=ft.RoundedRectangleBorder(radius=RADIUS_SM),
+        animation_duration=150,
+    )
+
+    return ft.OutlinedButton(
+        content=text,
+        icon=resolve_icon(icon),
+        on_click=on_click,
+        disabled=disabled,
+        style=style,
+        height=44,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Section card
+# ---------------------------------------------------------------------------
+
+
+def build_card(
+    content: ft.Control,
+    *,
+    padding: int = SPACE_LG,
+    page: Optional[ft.Page] = None,
+) -> ft.Container:
+    """
+    Wrap a control in a styled card container.
+
+    Args:
+        content: The child control to embed.
+        padding: Internal padding in pixels.
+        page: Current ``Page`` for palette derivation.
+
+    Returns:
+        A styled ``ft.Container``.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    bg = "#181b23" if dark else "#ffffff"
+    border_clr = "#2c3147" if dark else "#dce0ea"
+
+    return ft.Container(
+        content=content,
+        bgcolor=bg,
+        border=ft.Border.all(1, border_clr),
+        border_radius=RADIUS_MD,
+        padding=ft.Padding.all(padding),
+        shadow=ft.BoxShadow(
+            spread_radius=0,
+            blur_radius=12,
+            color=ft.Colors.with_opacity(0.12 if dark else 0.06, ft.Colors.BLACK),
+            offset=ft.Offset(0, 2),
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Section header
+# ---------------------------------------------------------------------------
+
+
+def build_section_header(
+    title: str,
+    *,
+    subtitle: Optional[str] = None,
+    icon: Optional[str] = None,
+    page: Optional[ft.Page] = None,
+) -> ft.Row:
+    """
+    Build a consistent section header row with an optional icon.
+
+    Args:
+        title: Section heading text.
+        subtitle: Optional explanatory sub-text.
+        icon: Optional Flet icon name.
+        page: Current ``Page`` for palette derivation.
+
+    Returns:
+        A ``ft.Row`` containing the icon and text column.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    title_color = "#e8eaf0" if dark else "#1a1d27"
+    sub_color = "#9ba3b8" if dark else "#5a6172"
+    accent = "#5b8af5" if dark else "#3a5fc4"
+
+    children: List[ft.Control] = []
+    if icon:
+        children.append(ft.Icon(resolve_icon(icon), size=20, color=accent))
+
+    text_parts: List[ft.Control] = [
+        ft.Text(title, size=15, weight=ft.FontWeight.W_600, color=title_color)
+    ]
+    if subtitle:
+        text_parts.append(ft.Text(subtitle, size=11, color=sub_color))
+
+    children.append(
+        ft.Column(text_parts, spacing=1, tight=True, expand=True)
+    )
+
+    return ft.Row(children, spacing=SPACE_SM, vertical_alignment=ft.CrossAxisAlignment.START)
+
+
+# ---------------------------------------------------------------------------
+# Status badge
+# ---------------------------------------------------------------------------
+
+
+def build_status_badge(
+    label: str,
+    *,
+    variant: str = "info",
+    page: Optional[ft.Page] = None,
+) -> ft.Container:
+    """
+    Build a small status badge chip.
+
+    Args:
+        label: Badge text.
+        variant: Colour variant: ``'info'``, ``'success'``, ``'error'``,
+                 ``'warning'``, ``'neutral'``.
+        page: Current ``Page`` for theme derivation.
+
+    Returns:
+        A pill-shaped ``ft.Container``.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    palette = {
+        "info":    ("#1a2a5e" if dark else "#dde8ff", "#5b8af5" if dark else "#3a5fc4"),
+        "success": ("#0d2010" if dark else "#d4f4d7", "#42ad4a" if dark else "#2e9437"),
+        "error":   ("#2a0a08" if dark else "#ffe0dc", "#e84e3c" if dark else "#c0392b"),
+        "warning": ("#2a1a00" if dark else "#fff4d8", "#f5a623" if dark else "#d4870a"),
+        "neutral": ("#1e2230" if dark else "#edf0f5", "#9ba3b8" if dark else "#5a6172"),
+    }
+    bg, fg = palette.get(variant, palette["info"])
+
+    return ft.Container(
+        content=ft.Text(label, size=10, weight=ft.FontWeight.W_600, color=fg),
+        bgcolor=bg,
+        border_radius=999,
+        padding=ft.Padding.symmetric(horizontal=8, vertical=3),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Labelled control row
+# ---------------------------------------------------------------------------
+
+
+def labelled_row(
+    label: str,
+    control: ft.Control,
+    *,
+    label_width: int = 200,
+    tooltip: Optional[str] = None,
+    page: Optional[ft.Page] = None,
+) -> ft.Row:
+    """
+    Lay a label and a control side-by-side in a consistent row.
+
+    Args:
+        label: Human-readable label text.
+        control: The UI control placed to the right of the label.
+        label_width: Fixed pixel width of the label column.
+        tooltip: Optional tooltip text on the label.
+        page: Current ``Page`` for palette derivation.
+
+    Returns:
+        A ``ft.Row`` with the label pinned to a fixed width.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    lbl_color = "#9ba3b8" if dark else "#5a6172"
+
+    lbl = ft.Text(label, size=13, color=lbl_color, weight=ft.FontWeight.W_500, width=label_width)
+    if tooltip:
+        lbl.tooltip = tooltip
+
+    return ft.Row(
+        [lbl, ft.Container(content=control, expand=True)],
+        alignment=ft.MainAxisAlignment.START,
+        vertical_alignment=ft.CrossAxisAlignment.CENTER,
+        spacing=SPACE_MD,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Snack-bar helper
+# ---------------------------------------------------------------------------
+
+
+def show_snack(
+    page: ft.Page,
+    message: str,
+    *,
+    error: bool = False,
+    duration: int = 3000,
+) -> None:
+    """
+    Display a brief snack-bar notification.
+
+    Args:
+        page: The Flet ``Page`` instance.
+        message: Text to display.
+        error: When True, colours the bar red instead of the default accent.
+        duration: Visible duration in milliseconds.
+    """
+    dark = page.theme_mode == ft.ThemeMode.DARK
+    bg = "#e84e3c" if error else ("#5b8af5" if dark else "#3a5fc4")
+    page.snack_bar = ft.SnackBar(
+        content=ft.Text(message, color="#ffffff", size=13),
+        bgcolor=bg,
+        duration=duration,
+        show_close_icon=True,
+        close_icon_color="#ffffff",
+    )
+    page.snack_bar.open = True
+    page.update()
+
+
+# ---------------------------------------------------------------------------
+# Divider helper
+# ---------------------------------------------------------------------------
+
+
+def build_divider(page: Optional[ft.Page] = None) -> ft.Divider:
+    """
+    Build a styled horizontal rule divider.
+
+    Args:
+        page: Current ``Page`` for palette derivation.
+
+    Returns:
+        A ``ft.Divider``.
+    """
+    dark = page is not None and page.theme_mode == ft.ThemeMode.DARK
+    return ft.Divider(color="#252a38" if dark else "#e8ebf2", height=1, thickness=1)

abogen/frontend/main.py

@@ -0,0 +1,365 @@
+"""
+Abogen Flet Frontend – main entry point.
+
+Run as desktop app:
+    python -m abogen.frontend.main
+
+Run as web app (binds to port 8080 by default):
+    python -m abogen.frontend.main --web --port 8080
+
+Architecture
+------------
+One ``ft.app()`` call launches the server.  For every new browser tab (or the
+desktop window) Flet invokes ``_app_entry(page)`` in its own coroutine, which
+creates a fresh ``AppState`` and wires together the navigation rail and views.
+This guarantees complete per-session isolation in multi-user web deployments.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+import flet as ft
+
+from .state import AppState
+from .components import resolve_icon
+from .views.dashboard import DashboardView
+from .views.settings import SettingsView
+from .views.queue_view import QueueView
+from .utils.theme import make_theme, DARK, LIGHT, SPACE_SM, SPACE_MD, SPACE_LG, RADIUS_MD
+from abogen.constants import PROGRAM_NAME as APP_NAME
+
+
+# ---------------------------------------------------------------------------
+# Navigation destinations
+# ---------------------------------------------------------------------------
+
+_NAV_ITEMS = [
+    ("Convert", "swap_horiz", "swap_horiz"),
+    ("Queue",   "list_alt",   "list_alt"),
+    ("Settings", "settings",  "settings"),
+]
+
+_ASSETS_DIR = Path(__file__).resolve().parents[1] / "assets"
+
+
+def _build_sidebar_item(
+    *,
+    label: str,
+    icon: str,
+    selected: bool,
+    palette,
+    on_click,
+) -> ft.Container:
+    accent = palette.accent if selected else palette.text_secondary
+    bg = palette.sidebar_selected_bg if selected else palette.sidebar_bg
+    return ft.Container(
+        content=ft.Row(
+            [
+                ft.Icon(resolve_icon(icon), size=20, color=accent),
+                ft.Text(
+                    label,
+                    size=13,
+                    weight=ft.FontWeight.W_600 if selected else ft.FontWeight.W_500,
+                    color=accent,
+                ),
+            ],
+            spacing=SPACE_MD,
+            vertical_alignment=ft.CrossAxisAlignment.CENTER,
+        ),
+        bgcolor=bg,
+        border_radius=RADIUS_MD,
+        padding=ft.Padding.symmetric(horizontal=SPACE_MD, vertical=10),
+        ink=True,
+        on_click=on_click,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Per-session entry point
+# ---------------------------------------------------------------------------
+
+def _app_entry(page: ft.Page) -> None:
+    try:
+        # ── State ────────────────────────────────────────────────────────────
+        state = AppState()
+        state.load_from_config()
+
+        # ── Page basics ──────────────────────────────────────────────────────
+        page.title = APP_NAME
+        page.padding = 0
+        page.spacing = 0
+        page.bgcolor = DARK.bg_base
+        page.theme_mode = ft.ThemeMode.DARK
+        page.theme = make_theme(dark=True)
+        page.dark_theme = make_theme(dark=True)
+        page.fonts = {}
+        page.window.min_width = 520
+        page.window.min_height = 600
+        page.update()
+
+        # ── Content area ref ─────────────────────────────────────────────────
+        content_area = ft.Column(expand=True, spacing=0)
+        sidebar_body = ft.Column(spacing=SPACE_SM)
+        theme_button_host = ft.Container()
+        brand_title = ft.Text(
+            APP_NAME,
+            size=18,
+            weight=ft.FontWeight.W_700,
+            color=DARK.text_primary,
+        )
+        brand_fallback_icon = ft.Icon(resolve_icon("speaker_notes"), size=32, color=DARK.accent)
+        divider = ft.VerticalDivider(width=1, color=DARK.border)
+
+        # ── Views ────────────────────────────────────────────────────────────
+        dashboard_view = DashboardView(page, state)
+        settings_view = SettingsView(page, state)
+        queue_view = QueueView(page, state)
+
+        views = [
+            dashboard_view.build,
+            queue_view.build,
+            settings_view.build,
+        ]
+        _selected_index = [0]
+
+        def _refresh_sidebar() -> None:
+            dark = page.theme_mode == ft.ThemeMode.DARK
+            pal = DARK if dark else LIGHT
+            sidebar_body.controls = [
+                _build_sidebar_item(
+                    label=label,
+                    icon=icon,
+                    selected=index == _selected_index[0],
+                    palette=pal,
+                    on_click=lambda _, i=index: _navigate(i),
+                )
+                for index, (label, icon, _) in enumerate(_NAV_ITEMS)
+            ]
+            sidebar.bgcolor = pal.sidebar_bg
+            divider.color = pal.border
+            brand_title.color = pal.text_primary
+            brand_fallback_icon.color = pal.accent
+            theme_button_host.content = ft.Container(
+                content=ft.Icon(
+                    resolve_icon("dark_mode" if dark else "light_mode"),
+                    size=20,
+                    color=pal.text_secondary,
+                ),
+                tooltip="Toggle theme",
+                border_radius=RADIUS_MD,
+                padding=8,
+                ink=True,
+                on_click=lambda _: _toggle_theme(page, _refresh_sidebar),
+            )
+
+        def _navigate(index: int) -> None:
+            _selected_index[0] = index
+            content_area.controls.clear()
+            built = views[index]()
+            content_area.controls.append(
+                ft.Container(
+                    content=built,
+                    expand=True,
+                    padding=ft.Padding.symmetric(horizontal=SPACE_LG, vertical=SPACE_LG),
+                )
+            )
+            _refresh_sidebar()
+            page.update()
+
+        # ── Sidebar ──────────────────────────────────────────────────────────
+        pal = DARK
+        sidebar = ft.Container(
+            width=220,
+            bgcolor=pal.sidebar_bg,
+            padding=ft.Padding.all(SPACE_MD),
+            content=ft.Column(
+                [
+                    ft.Container(
+                        content=ft.Row(
+                            [
+                                ft.Image(
+                                    src="icon.png",
+                                    width=36,
+                                    height=36,
+                                    fit=ft.BoxFit.CONTAIN,
+                                    error_content=brand_fallback_icon,
+                                ),
+                                brand_title,
+                            ],
+                            spacing=SPACE_MD,
+                            vertical_alignment=ft.CrossAxisAlignment.CENTER,
+                        ),
+                        padding=ft.Padding.only(top=SPACE_SM, bottom=SPACE_LG),
+                    ),
+                    sidebar_body,
+                    ft.Container(expand=True),
+                    ft.Row([theme_button_host], alignment=ft.MainAxisAlignment.END),
+                ],
+                expand=True,
+                spacing=SPACE_SM,
+            ),
+        )
+        _refresh_sidebar()
+
+        # ── Page handle for pubsub (queue → dashboard) ───────────────────────
+        def _handle_pubsub(topic: str) -> None:
+            if topic == "start_queue":
+                _navigate(0)
+
+        page.pubsub.subscribe(_handle_pubsub)
+
+        # ── Layout ────────────────────────────────────────────────────────────
+        page.add(
+            ft.Row(
+                [
+                    sidebar,
+                    divider,
+                    ft.Container(content=content_area, expand=True),
+                ],
+                expand=True,
+                spacing=0,
+                vertical_alignment=ft.CrossAxisAlignment.START,
+            )
+        )
+
+        # Show dashboard by default
+        _navigate(0)
+        page.update()
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        print(f"ERROR IN _app_entry: {e}")
+        raise
+
+
+def _toggle_theme(page: ft.Page, refresh_sidebar) -> None:
+    """Switch between dark and light theme modes."""
+    if page.theme_mode == ft.ThemeMode.DARK:
+        page.theme_mode = ft.ThemeMode.LIGHT
+        page.bgcolor = LIGHT.bg_base
+    else:
+        page.theme_mode = ft.ThemeMode.DARK
+        page.bgcolor = DARK.bg_base
+
+    page.theme = make_theme(page.theme_mode == ft.ThemeMode.DARK)
+    refresh_sidebar()
+    page.update()
+
+
+# ---------------------------------------------------------------------------
+# CLI helpers & entry point
+# ---------------------------------------------------------------------------
+
+def _is_port_free(host: str, port: int) -> bool:
+    import socket
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind((host, port))
+            return True
+    except OSError:
+        return False
+
+
+def _find_free_port(host: str, start_port: int) -> int:
+    import socket
+    port = start_port
+    while port < 65535:
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                s.bind((host, port))
+                return port
+        except OSError:
+            port += 1
+    return start_port
+
+
+def main() -> None:
+    """
+    Start the Abogen Flet frontend.
+
+    Parses ``--web`` and ``--port`` CLI arguments to choose desktop vs. web
+    mode, then hands control to ``ft.app()``.
+    """
+    import logging
+    logging.basicConfig(level=logging.INFO)
+    logging.getLogger("flet").setLevel(logging.INFO)
+
+    parser = argparse.ArgumentParser(description=f"{APP_NAME} – Flet frontend")
+    parser.add_argument(
+        "--web", action="store_true",
+        help="Run as a web server instead of a desktop window.",
+    )
+    parser.add_argument(
+        "--port", type=int, default=8080,
+        help="Port for the web server (default: 8080). Ignored in desktop mode.",
+    )
+    parser.add_argument(
+        "--host", default="127.0.0.1",
+        help="Host for the web server (default: 127.0.0.1). Use 0.0.0.0 to expose publicly.",
+    )
+    args = parser.parse_args()
+
+    if args.web:
+        port_specified = "--port" in sys.argv
+        target_port = args.port
+
+        if not port_specified:
+            target_port = _find_free_port(args.host, 8080)
+            if target_port != 8080:
+                print(f"Port 8080 is in use. Automatically routed to free port: {target_port}")
+        else:
+            if not _is_port_free(args.host, target_port):
+                print(f"Error: Port {target_port} is already in use on {args.host}.", file=sys.stderr)
+                print("Please select a different port or omit the --port flag to find one automatically.", file=sys.stderr)
+                sys.exit(1)
+
+        print(f"Starting Abogen WebUI on http://{args.host}:{target_port} ...")
+        ft.app(
+            target=_app_entry,
+            view=ft.AppView.WEB_BROWSER,
+            port=target_port,
+            host=args.host,
+            assets_dir=str(_ASSETS_DIR) if _ASSETS_DIR.exists() else None,
+            no_cdn=True,
+            web_renderer="canvaskit",
+        )
+    else:
+        try:
+            ft.app(
+                target=_app_entry,
+                view=ft.AppView.FLET_APP,
+                assets_dir=str(_ASSETS_DIR) if _ASSETS_DIR.exists() else None,
+            )
+        except Exception as e:
+            print(f"Warning: Failed to launch native desktop window: {e}", file=sys.stderr)
+            print("Falling back to running as a web application in your default browser...", file=sys.stderr)
+            target_port = _find_free_port("127.0.0.1", 8080)
+            print(f"Starting Abogen WebUI on http://127.0.0.1:{target_port} ...")
+            ft.app(
+                target=_app_entry,
+                view=ft.AppView.WEB_BROWSER,
+                port=target_port,
+                host="127.0.0.1",
+                assets_dir=str(_ASSETS_DIR) if _ASSETS_DIR.exists() else None,
+                no_cdn=True,
+                web_renderer="canvaskit",
+            )
+
+
+def main_web() -> None:
+    """
+    Start the Abogen Flet frontend as a web server.
+    """
+    import sys
+    if "--web" not in sys.argv:
+        sys.argv.insert(1, "--web")
+    main()
+
+
+if __name__ == "__main__":
+    main()

abogen/frontend/state/__init__.py

@@ -0,0 +1,4 @@
+"""State sub-package – exports AppState and ConversionJob."""
+from .app_state import AppState, ConversionJob
+
+__all__ = ["AppState", "ConversionJob"]

abogen/frontend/state/app_state.py

@@ -0,0 +1,451 @@
+"""
+Centralized, per-session application state for the Abogen Flet frontend.
+
+Each Flet page (session) gets its own instance of AppState, which guarantees
+complete isolation between simultaneous web-browser clients and the desktop
+window. The class carries every configuration variable, file buffer reference,
+and generation progress field that the rest of the UI reads or writes.
+
+This module intentionally has no Flet imports so it can be unit-tested without
+a running Flet server.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from abogen.utils import load_config, save_config
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _default_config() -> Dict[str, Any]:
+    """Load the persisted user config dict, returning an empty dict on failure."""
+    try:
+        return load_config() or {}
+    except Exception:
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Per-session state
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ConversionJob:
+    """Lightweight descriptor of a single queued conversion job."""
+
+    file_path: str
+    """Absolute path to the text/epub/pdf/txt input file."""
+
+    display_name: str
+    """User-visible filename (may be the original epub/pdf path)."""
+
+    voice: str
+    """Voice formula string (e.g. 'af_heart' or 'af_heart*0.5+am_adam*0.5')."""
+
+    lang_code: str
+    """Single-char language prefix used by Kokoro (e.g. 'a', 'b', 'e')."""
+
+    speed: float = 1.0
+    """Playback speed multiplier, range 0.1 – 2.0."""
+
+    output_format: str = "mp3"
+    """Output audio container format."""
+
+    subtitle_mode: str = "Disabled"
+    """Subtitle generation mode."""
+
+    save_option: str = "Save next to input file"
+    """Save location strategy."""
+
+    output_folder: Optional[str] = None
+    """Absolute path when save_option is 'Choose output folder'."""
+
+    char_count: int = 0
+    """Pre-computed character count for ETR estimation."""
+
+    replace_single_newlines: bool = True
+    save_chapters_separately: Optional[bool] = None
+    merge_chapters_at_end: Optional[bool] = None
+
+
+@dataclass
+class AppState:
+    """
+    Single source of truth for one Flet session.
+
+    Instantiated once per ``ft.app()`` call on desktop, and once per browser
+    tab on web.  All UI components receive a reference to this object and
+    read/write it to keep themselves in sync.
+
+    Thread-safety: mutation from background threads should be done via the
+    provided ``_lock``.  The UI update callbacks (``on_log``,
+    ``on_progress``, etc.) are always invoked on the Flet event loop via
+    ``page.run_task()`` and must be set by the view layer.
+    """
+
+    # -----------------------------------------------------------------------
+    # Runtime identity
+    # -----------------------------------------------------------------------
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
+
+    # -----------------------------------------------------------------------
+    # Persisted user config (loaded once, written on every change)
+    # -----------------------------------------------------------------------
+    config: Dict[str, Any] = field(default_factory=_default_config)
+
+    # -----------------------------------------------------------------------
+    # File / input state
+    # -----------------------------------------------------------------------
+    selected_file: Optional[str] = None
+    """Path to the processed text file (may be a temp cache copy for epub/pdf)."""
+
+    selected_file_type: Optional[str] = None
+    """'txt' | 'epub' | 'pdf' | 'markdown' | None"""
+
+    selected_book_path: Optional[str] = None
+    """Original epub/pdf path before being converted to txt."""
+
+    displayed_file_path: Optional[str] = None
+    """Path shown in the UI drop-zone (original book or txt file)."""
+
+    selected_chapters: List[str] = field(default_factory=list)
+    """Ordered list of selected chapter href tokens (or page numbers for PDFs)."""
+
+    save_chapters_separately: Optional[bool] = None
+    merge_chapters_at_end: Optional[bool] = None
+    save_as_project: bool = False
+    char_count: int = 0
+
+    # -----------------------------------------------------------------------
+    # Voice / language
+    # -----------------------------------------------------------------------
+    selected_voice: str = "af_heart"
+    selected_lang: str = "a"
+    selected_profile_name: Optional[str] = None
+    mixed_voice_state: Optional[List[Any]] = None
+    """List of [voice_id, weight] pairs when the formula mixer is in use."""
+
+    # -----------------------------------------------------------------------
+    # Conversion parameters
+    # -----------------------------------------------------------------------
+    speed: float = 1.0
+    use_gpu: bool = True
+    selected_format: str = "wav"
+    subtitle_mode: str = "Sentence"
+    subtitle_format: str = "ass_centered_narrow"
+    replace_single_newlines: bool = True
+    save_option: str = "Save next to input file"
+    selected_output_folder: Optional[str] = None
+    silence_duration: float = 2.0
+    max_subtitle_words: int = 50
+    separate_chapters_format: str = "wav"
+    use_silent_gaps: bool = True
+    subtitle_speed_method: str = "tts"
+    use_spacy_segmentation: bool = True
+    chunk_level: str = "paragraph"
+    generate_epub3: bool = False
+
+    # TTS provider
+    tts_provider: str = "kokoro"
+    supertonic_total_steps: int = 5
+
+    # Chapter options
+    chapter_intro_delay: float = 0.5
+    read_title_intro: bool = False
+    read_closing_outro: bool = True
+    auto_prefix_chapter_titles: bool = True
+    normalize_chapter_opening_caps: bool = True
+
+    # Speaker analysis
+    speaker_analysis_threshold: int = 3
+
+    # Word substitutions
+    word_substitutions_enabled: bool = False
+    word_substitutions_list: str = ""
+    case_sensitive_substitutions: bool = False
+    replace_all_caps: bool = False
+    replace_numerals: bool = False
+    fix_nonstandard_punctuation: bool = False
+
+    # -----------------------------------------------------------------------
+    # Conversion runtime state
+    # -----------------------------------------------------------------------
+    is_converting: bool = False
+    is_cancelled: bool = False
+    progress: float = 0.0
+    """Fractional progress 0.0 – 1.0."""
+    etr_seconds: Optional[float] = None
+    """Estimated seconds remaining, or None if unknown."""
+    last_output_path: Optional[str] = None
+    log_lines: List[str] = field(default_factory=list)
+    """Buffered log messages, capped at LOG_MAX_LINES."""
+
+    LOG_MAX_LINES: int = 2000
+
+    # -----------------------------------------------------------------------
+    # Queue
+    # -----------------------------------------------------------------------
+    queued_items: List[ConversionJob] = field(default_factory=list)
+    current_queue_index: int = 0
+
+    # -----------------------------------------------------------------------
+    # Callbacks (set by the view layer, not serialised)
+    # -----------------------------------------------------------------------
+    on_log: Optional[Callable[[str, str], None]] = field(default=None, repr=False, compare=False)
+    """Called from any thread: ``on_log(message, level)``."""
+
+    on_progress: Optional[Callable[[float, Optional[float]], None]] = field(
+        default=None, repr=False, compare=False
+    )
+    """Called from any thread: ``on_progress(fraction, etr_seconds)``."""
+
+    on_conversion_finished: Optional[Callable[[str, Optional[str]], None]] = field(
+        default=None, repr=False, compare=False
+    )
+    """Called from any thread: ``on_conversion_finished(message, output_path)``."""
+
+    # -----------------------------------------------------------------------
+    # Integrations
+    # -----------------------------------------------------------------------
+    audiobookshelf_enabled: bool = False
+    audiobookshelf_base_url: str = ""
+    audiobookshelf_api_token: str = ""
+    audiobookshelf_library_id: str = ""
+    audiobookshelf_folder_id: str = ""
+    audiobookshelf_verify_ssl: bool = True
+    audiobookshelf_auto_send: bool = False
+    audiobookshelf_send_cover: bool = True
+    audiobookshelf_send_chapters: bool = True
+    audiobookshelf_send_subtitles: bool = False
+    audiobookshelf_timeout: float = 30.0
+
+    calibre_opds_enabled: bool = False
+    calibre_opds_base_url: str = ""
+    calibre_opds_username: str = ""
+    calibre_opds_password: str = ""
+    calibre_opds_verify_ssl: bool = True
+
+    # -----------------------------------------------------------------------
+    # Public helpers
+    # -----------------------------------------------------------------------
+
+    def load_from_config(self) -> None:
+        """
+        Populate all fields from the persisted JSON config file.
+
+        Called once at startup and whenever the settings page is saved.
+        Thread-safe.
+        """
+        with self._lock:
+            cfg = _default_config()
+            self.config = cfg
+
+            self.selected_voice = cfg.get("selected_voice", "af_heart")
+            self.selected_lang = self.selected_voice[0] if self.selected_voice else "a"
+            self.selected_profile_name = cfg.get("selected_profile_name")
+            self.speed = cfg.get("speed", 1.0)
+            self.use_gpu = cfg.get("use_gpu", True)
+            self.selected_format = cfg.get("selected_format", "wav")
+            self.subtitle_mode = cfg.get("subtitle_mode", "Sentence")
+            self.subtitle_format = cfg.get("subtitle_format", "ass_centered_narrow")
+            self.replace_single_newlines = cfg.get("replace_single_newlines", True)
+            self.save_option = cfg.get("save_option", "Save next to input file")
+            self.selected_output_folder = cfg.get("selected_output_folder")
+            self.silence_duration = cfg.get("silence_duration", 2.0)
+            self.max_subtitle_words = cfg.get("max_subtitle_words", 50)
+            self.separate_chapters_format = cfg.get("separate_chapters_format", "wav")
+            self.use_silent_gaps = cfg.get("use_silent_gaps", True)
+            self.subtitle_speed_method = cfg.get("subtitle_speed_method", "tts")
+            self.use_spacy_segmentation = cfg.get("use_spacy_segmentation", True)
+            self.chunk_level = cfg.get("chunk_level", "paragraph")
+            self.generate_epub3 = cfg.get("generate_epub3", False)
+            self.tts_provider = cfg.get("tts_provider", "kokoro")
+            self.supertonic_total_steps = cfg.get("supertonic_total_steps", 5)
+            self.chapter_intro_delay = cfg.get("chapter_intro_delay", 0.5)
+            self.read_title_intro = cfg.get("read_title_intro", False)
+            self.read_closing_outro = cfg.get("read_closing_outro", True)
+            self.auto_prefix_chapter_titles = cfg.get("auto_prefix_chapter_titles", True)
+            self.normalize_chapter_opening_caps = cfg.get("normalize_chapter_opening_caps", True)
+            self.speaker_analysis_threshold = cfg.get("speaker_analysis_threshold", 3)
+            self.word_substitutions_enabled = cfg.get("word_substitutions_enabled", False)
+            self.word_substitutions_list = cfg.get("word_substitutions_list", "")
+            self.case_sensitive_substitutions = cfg.get("case_sensitive_substitutions", False)
+            self.replace_all_caps = cfg.get("replace_all_caps", False)
+            self.replace_numerals = cfg.get("replace_numerals", False)
+            self.fix_nonstandard_punctuation = cfg.get("fix_nonstandard_punctuation", False)
+
+            # Integrations
+            integrations: Dict[str, Any] = cfg.get("integrations", {})
+            abs_cfg = integrations.get("audiobookshelf", {})
+            self.audiobookshelf_enabled = bool(abs_cfg.get("enabled", False))
+            self.audiobookshelf_base_url = str(abs_cfg.get("base_url", ""))
+            self.audiobookshelf_api_token = str(abs_cfg.get("api_token", ""))
+            self.audiobookshelf_library_id = str(abs_cfg.get("library_id", ""))
+            self.audiobookshelf_folder_id = str(abs_cfg.get("folder_id", ""))
+            self.audiobookshelf_verify_ssl = bool(abs_cfg.get("verify_ssl", True))
+            self.audiobookshelf_auto_send = bool(abs_cfg.get("auto_send", False))
+            self.audiobookshelf_send_cover = bool(abs_cfg.get("send_cover", True))
+            self.audiobookshelf_send_chapters = bool(abs_cfg.get("send_chapters", True))
+            self.audiobookshelf_send_subtitles = bool(abs_cfg.get("send_subtitles", False))
+            self.audiobookshelf_timeout = float(abs_cfg.get("timeout", 30.0))
+
+            cal_cfg = integrations.get("calibre_opds", {})
+            self.calibre_opds_enabled = bool(cal_cfg.get("enabled", False))
+            self.calibre_opds_base_url = str(cal_cfg.get("base_url", ""))
+            self.calibre_opds_username = str(cal_cfg.get("username", ""))
+            self.calibre_opds_password = str(cal_cfg.get("password", ""))
+            self.calibre_opds_verify_ssl = bool(cal_cfg.get("verify_ssl", True))
+
+    def persist_config(self) -> None:
+        """
+        Write the current config snapshot back to disk.
+
+        Only the fields that map to the JSON config are written; runtime state
+        (progress, log_lines, callbacks) is not persisted.
+        Thread-safe.
+        """
+        with self._lock:
+            cfg = self.config.copy()
+            cfg["selected_voice"] = self.selected_voice
+            cfg["selected_profile_name"] = self.selected_profile_name
+            cfg["speed"] = self.speed
+            cfg["use_gpu"] = self.use_gpu
+            cfg["selected_format"] = self.selected_format
+            cfg["subtitle_mode"] = self.subtitle_mode
+            cfg["subtitle_format"] = self.subtitle_format
+            cfg["replace_single_newlines"] = self.replace_single_newlines
+            cfg["save_option"] = self.save_option
+            cfg["selected_output_folder"] = self.selected_output_folder
+            cfg["silence_duration"] = self.silence_duration
+            cfg["max_subtitle_words"] = self.max_subtitle_words
+            cfg["separate_chapters_format"] = self.separate_chapters_format
+            cfg["use_silent_gaps"] = self.use_silent_gaps
+            cfg["subtitle_speed_method"] = self.subtitle_speed_method
+            cfg["use_spacy_segmentation"] = self.use_spacy_segmentation
+            cfg["chunk_level"] = self.chunk_level
+            cfg["generate_epub3"] = self.generate_epub3
+            cfg["tts_provider"] = self.tts_provider
+            cfg["supertonic_total_steps"] = self.supertonic_total_steps
+            cfg["chapter_intro_delay"] = self.chapter_intro_delay
+            cfg["read_title_intro"] = self.read_title_intro
+            cfg["read_closing_outro"] = self.read_closing_outro
+            cfg["auto_prefix_chapter_titles"] = self.auto_prefix_chapter_titles
+            cfg["normalize_chapter_opening_caps"] = self.normalize_chapter_opening_caps
+            cfg["speaker_analysis_threshold"] = self.speaker_analysis_threshold
+            cfg["word_substitutions_enabled"] = self.word_substitutions_enabled
+            cfg["word_substitutions_list"] = self.word_substitutions_list
+            cfg["case_sensitive_substitutions"] = self.case_sensitive_substitutions
+            cfg["replace_all_caps"] = self.replace_all_caps
+            cfg["replace_numerals"] = self.replace_numerals
+            cfg["fix_nonstandard_punctuation"] = self.fix_nonstandard_punctuation
+            # Integrations
+            cfg.setdefault("integrations", {})
+            cfg["integrations"]["audiobookshelf"] = {
+                "enabled": self.audiobookshelf_enabled,
+                "base_url": self.audiobookshelf_base_url,
+                "api_token": self.audiobookshelf_api_token,
+                "library_id": self.audiobookshelf_library_id,
+                "folder_id": self.audiobookshelf_folder_id,
+                "verify_ssl": self.audiobookshelf_verify_ssl,
+                "auto_send": self.audiobookshelf_auto_send,
+                "send_cover": self.audiobookshelf_send_cover,
+                "send_chapters": self.audiobookshelf_send_chapters,
+                "send_subtitles": self.audiobookshelf_send_subtitles,
+                "timeout": self.audiobookshelf_timeout,
+            }
+            cfg["integrations"]["calibre_opds"] = {
+                "enabled": self.calibre_opds_enabled,
+                "base_url": self.calibre_opds_base_url,
+                "username": self.calibre_opds_username,
+                "password": self.calibre_opds_password,
+                "verify_ssl": self.calibre_opds_verify_ssl,
+            }
+            self.config = cfg
+            try:
+                save_config(cfg)
+            except Exception:
+                pass
+
+    def append_log(self, message: str, level: str = "info") -> None:
+        """
+        Thread-safely append a log line and trigger the UI callback.
+
+        Caps the internal buffer at ``LOG_MAX_LINES`` to prevent unbounded
+        memory growth during very long conversion tasks.
+        """
+        with self._lock:
+            self.log_lines.append(f"[{level.upper()}] {message}")
+            if len(self.log_lines) > self.LOG_MAX_LINES:
+                # Trim oldest 10 % to amortise the cost of trimming
+                trim = self.LOG_MAX_LINES // 10
+                self.log_lines = self.log_lines[trim:]
+
+        cb = self.on_log
+        if cb is not None:
+            try:
+                cb(message, level)
+            except Exception:
+                pass
+
+    def update_progress(self, fraction: float, etr: Optional[float] = None) -> None:
+        """
+        Update fractional progress and ETR, then notify the UI callback.
+
+        Args:
+            fraction: Value in [0.0, 1.0].
+            etr: Estimated seconds remaining, or None.
+        """
+        with self._lock:
+            self.progress = max(0.0, min(1.0, fraction))
+            self.etr_seconds = etr
+
+        cb = self.on_progress
+        if cb is not None:
+            try:
+                cb(fraction, etr)
+            except Exception:
+                pass
+
+    def get_voice_formula(self) -> str:
+        """
+        Return the effective voice formula string.
+
+        Uses the mixed_voice_state if the formula mixer is active, otherwise
+        returns the raw selected_voice.
+        """
+        if self.mixed_voice_state:
+            parts = [f"{name}*{weight}" for name, weight in self.mixed_voice_state]
+            return " + ".join(filter(None, parts))
+        return self.selected_voice or "af_heart"
+
+    def reset_file_state(self) -> None:
+        """Clear all file-related fields without touching voice/settings."""
+        with self._lock:
+            self.selected_file = None
+            self.selected_file_type = None
+            self.selected_book_path = None
+            self.displayed_file_path = None
+            self.selected_chapters = []
+            self.save_chapters_separately = None
+            self.merge_chapters_at_end = None
+            self.save_as_project = False
+            self.char_count = 0
+
+    def reset_conversion_state(self) -> None:
+        """Clear all runtime conversion fields to start fresh."""
+        with self._lock:
+            self.is_converting = False
+            self.is_cancelled = False
+            self.progress = 0.0
+            self.etr_seconds = None
+            self.last_output_path = None
+            self.log_lines = []

abogen/frontend/utils/__init__.py

@@ -0,0 +1,38 @@
+"""Utils sub-package."""
+from .helpers import (
+    human_readable_size,
+    format_duration,
+    format_etr,
+    detect_file_type,
+    is_supported_file,
+    is_book_type,
+    voice_lang_code,
+    language_label,
+    grouped_voices,
+    voice_display_name,
+    parse_voice_formula,
+    format_number,
+    safe_basename,
+    output_format_label,
+    subtitle_format_label,
+    SUPPORTED_EXTENSIONS,
+)
+
+__all__ = [
+    "human_readable_size",
+    "format_duration",
+    "format_etr",
+    "detect_file_type",
+    "is_supported_file",
+    "is_book_type",
+    "voice_lang_code",
+    "language_label",
+    "grouped_voices",
+    "voice_display_name",
+    "parse_voice_formula",
+    "format_number",
+    "safe_basename",
+    "output_format_label",
+    "subtitle_format_label",
+    "SUPPORTED_EXTENSIONS",
+]

abogen/frontend/utils/conversion_bridge.py

@@ -0,0 +1,462 @@
+"""
+Background conversion bridge for the Abogen Flet frontend.
+
+This module wraps the existing ``abogen.webui.conversion_runner`` (and its
+``ConversionService`` / ``Job`` machinery) in an async-friendly interface that
+can push real-time progress and log updates back to the Flet event loop without
+blocking the UI thread.
+
+Key design decisions
+--------------------
+* All heavy work is offloaded to daemon threads. The Flet page event loop
+  is never blocked.
+* Progress and log callbacks are scheduled back onto the Flet page via
+  ``page.run_task()`` so Flet's session isolation remains intact.
+* Cancellation is cooperative: the underlying job's ``cancel_requested``
+  flag is set, and the runner checks it at chunk boundaries.
+* The module is a pure adapter – it does NOT duplicate any processing logic
+  from the core pipeline.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import tempfile
+import threading
+import time
+import traceback
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+import flet as ft
+
+from abogen.utils import (
+    get_gpu_acceleration,
+    get_user_cache_path,
+    get_user_output_path,
+    load_numpy_kpipeline,
+    prevent_sleep_end,
+    prevent_sleep_start,
+)
+from abogen.webui.service import (
+    ConversionService,
+    Job,
+    JobStatus,
+    PendingJob,
+    build_service,
+)
+from abogen.webui.conversion_runner import run_conversion_job
+
+from ..state import AppState
+
+# ---------------------------------------------------------------------------
+# Module-level singleton ConversionService (shared across sessions, as in the
+# web UI – but each job carries its own output folder keyed by session).
+# ---------------------------------------------------------------------------
+
+_SERVICE_LOCK = threading.Lock()
+_SERVICE: Optional[ConversionService] = None
+
+
+def _get_service() -> ConversionService:
+    """
+    Return (creating if necessary) the module-level ConversionService.
+
+    The service manages the background worker thread and persistent job state.
+    Thread-safe via a module-level lock.
+    """
+    global _SERVICE
+    with _SERVICE_LOCK:
+        if _SERVICE is None:
+            output_root = Path(get_user_output_path("frontend"))
+            uploads_root = Path(get_user_cache_path("frontend/uploads"))
+            _SERVICE = build_service(
+                runner=run_conversion_job,
+                output_root=output_root,
+                uploads_root=uploads_root,
+            )
+    return _SERVICE
+
+
+# ---------------------------------------------------------------------------
+# Public conversion bridge
+# ---------------------------------------------------------------------------
+
+
+class ConversionBridge:
+    """
+    Thin adapter between the Flet UI session and the core conversion pipeline.
+
+    One ``ConversionBridge`` instance is created per Flet page (session) and
+    is responsible for:
+    1. Accepting a conversion request from the UI.
+    2. Writing the input text to a temp file if needed.
+    3. Submitting the job to ``ConversionService``.
+    4. Polling the job from a daemon thread and forwarding progress/logs to
+       the Flet page via ``page.run_task()``.
+    5. Providing a ``cancel()`` method that sets the cooperative flag.
+    """
+
+    def __init__(self, page: ft.Page, state: AppState) -> None:
+        """
+        Initialise the bridge.
+
+        Args:
+            page: The Flet ``Page`` for this session. Used to schedule
+                  UI callbacks on the correct event loop.
+            state: The session's ``AppState`` instance.
+        """
+        self._page = page
+        self._state = state
+        self._current_job: Optional[Job] = None
+        self._poll_thread: Optional[threading.Thread] = None
+        self._stop_poll = threading.Event()
+        self._seen_log_count = 0
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def start(
+        self,
+        *,
+        input_file: str,
+        voice: str,
+        lang_code: str,
+        speed: float,
+        output_format: str,
+        subtitle_mode: str,
+        subtitle_format: str,
+        use_gpu: bool,
+        save_option: str,
+        output_folder: Optional[str],
+        replace_single_newlines: bool,
+        char_count: int,
+        chapters: Optional[List[Dict[str, Any]]] = None,
+        save_chapters_separately: bool = False,
+        merge_chapters_at_end: bool = True,
+        separate_chapters_format: str = "wav",
+        silence_between_chapters: float = 2.0,
+        max_subtitle_words: int = 50,
+        chapter_intro_delay: float = 0.5,
+        read_title_intro: bool = False,
+        read_closing_outro: bool = True,
+        auto_prefix_chapter_titles: bool = True,
+        normalize_chapter_opening_caps: bool = True,
+        tts_provider: str = "kokoro",
+        supertonic_total_steps: int = 5,
+        chunk_level: str = "paragraph",
+        generate_epub3: bool = False,
+        word_substitutions_enabled: bool = False,
+        word_substitutions_list: str = "",
+        case_sensitive_substitutions: bool = False,
+        replace_all_caps: bool = False,
+        replace_numerals: bool = False,
+        fix_nonstandard_punctuation: bool = False,
+    ) -> None:
+        """
+        Submit a conversion job and begin the progress-polling loop.
+
+        This method returns immediately; all heavy work runs on daemon threads.
+        UI callbacks (``state.on_log``, ``state.on_progress``,
+        ``state.on_conversion_finished``) are scheduled on the Flet event loop.
+
+        Args:
+            input_file: Absolute path to the text/epub/pdf input file.
+            voice: Kokoro voice formula string.
+            lang_code: Single-char language code.
+            speed: Playback speed multiplier (0.1 – 2.0).
+            output_format: Audio container key (``'wav'``, ``'mp3'``, …).
+            subtitle_mode: Subtitle generation mode string.
+            subtitle_format: Subtitle container key (``'srt'``, ``'ass_wide'``, …).
+            use_gpu: Whether to request GPU acceleration.
+            save_option: Save-location strategy string.
+            output_folder: Explicit output folder or None.
+            replace_single_newlines: Pre-processing flag.
+            char_count: Pre-computed character count for ETR estimation.
+            chapters: Optional list of chapter dicts for epub/pdf.
+            save_chapters_separately: Split chapters into separate files.
+            merge_chapters_at_end: Merge chapter files into one after generation.
+            separate_chapters_format: Format for individual chapter files.
+            silence_between_chapters: Silence gap (seconds) between chapters.
+            max_subtitle_words: Maximum words per subtitle block.
+            chapter_intro_delay: Silence before chapter title announcement (s).
+            read_title_intro: Announce book title at the start.
+            read_closing_outro: Announce book title at the end.
+            auto_prefix_chapter_titles: Prepend "Chapter N." to titles.
+            normalize_chapter_opening_caps: Fix ALL-CAPS opening lines.
+            tts_provider: ``'kokoro'`` or ``'supertonic'``.
+            supertonic_total_steps: Quality steps for the Supertonic pipeline.
+            chunk_level: ``'paragraph'`` or ``'sentence'`` chunking granularity.
+            generate_epub3: Also produce an EPUB3 audiobook package.
+            word_substitutions_enabled: Toggle word-substitution pre-processing.
+            word_substitutions_list: Newline-delimited ``word|replacement`` rules.
+            case_sensitive_substitutions: Case-sensitive matching for substitutions.
+            replace_all_caps: Lowercase ALL-CAPS words.
+            replace_numerals: Convert digits to spoken words.
+            fix_nonstandard_punctuation: Normalise curly quotes etc.
+        """
+        if self._state.is_converting:
+            return
+
+        # Resolve the effective output folder
+        resolved_output: Optional[Path] = self._resolve_output_folder(
+            save_option=save_option,
+            output_folder=output_folder,
+            input_file=input_file,
+        )
+
+        # Store the input file as a Path
+        stored_path = Path(input_file)
+        original_filename = stored_path.name
+
+        # Block signals until the job is submitted
+        prevent_sleep_start()
+        self._state.is_converting = True
+        self._state.is_cancelled = False
+        self._state.progress = 0.0
+        self._state.etr_seconds = None
+        self._state.log_lines = []
+        self._seen_log_count = 0
+
+        # Enqueue the job on the service
+        service = _get_service()
+        job = service.enqueue(
+            original_filename=original_filename,
+            stored_path=stored_path,
+            language=lang_code,
+            voice=voice,
+            speed=speed,
+            tts_provider=tts_provider,
+            supertonic_total_steps=supertonic_total_steps,
+            use_gpu=use_gpu,
+            subtitle_mode=subtitle_mode,
+            output_format=output_format,
+            save_mode=self._save_mode_key(save_option),
+            output_folder=resolved_output,
+            replace_single_newlines=replace_single_newlines,
+            subtitle_format=subtitle_format,
+            total_characters=char_count,
+            chapters=chapters or [],
+            save_chapters_separately=save_chapters_separately,
+            merge_chapters_at_end=merge_chapters_at_end,
+            separate_chapters_format=separate_chapters_format,
+            silence_between_chapters=silence_between_chapters,
+            max_subtitle_words=max_subtitle_words,
+            chapter_intro_delay=chapter_intro_delay,
+            read_title_intro=read_title_intro,
+            read_closing_outro=read_closing_outro,
+            auto_prefix_chapter_titles=auto_prefix_chapter_titles,
+            normalize_chapter_opening_caps=normalize_chapter_opening_caps,
+            chunk_level=chunk_level,
+            generate_epub3=generate_epub3,
+        )
+        self._current_job = job
+
+        # Persist word-substitution settings to config so the runner picks them up
+        self._state.word_substitutions_enabled = word_substitutions_enabled
+        self._state.word_substitutions_list = word_substitutions_list
+        self._state.case_sensitive_substitutions = case_sensitive_substitutions
+        self._state.replace_all_caps = replace_all_caps
+        self._state.replace_numerals = replace_numerals
+        self._state.fix_nonstandard_punctuation = fix_nonstandard_punctuation
+        self._state.persist_config()
+
+        # Start the poll thread
+        self._stop_poll.clear()
+        self._poll_thread = threading.Thread(
+            target=self._poll_job_loop, daemon=True, name="abogen-poll"
+        )
+        self._poll_thread.start()
+
+    def cancel(self) -> None:
+        """
+        Request cancellation of the currently running job.
+
+        Sets the cooperative flag on the underlying ``Job`` object; the runner
+        will stop after completing the current text chunk.
+        """
+        if self._current_job is not None:
+            self._state.is_cancelled = True
+            try:
+                _get_service().cancel(self._current_job.id)
+            except Exception:
+                pass
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _save_mode_key(option: str) -> str:
+        """
+        Convert the human-readable save option to the service's internal key.
+
+        Args:
+            option: UI-facing string (``'Save next to input file'``, …).
+
+        Returns:
+            Service key string.
+        """
+        mapping = {
+            "Save next to input file": "save_next_to_input",
+            "Save to Desktop": "save_to_desktop",
+            "Choose output folder": "custom",
+        }
+        return mapping.get(option, "save_next_to_input")
+
+    @staticmethod
+    def _resolve_output_folder(
+        save_option: str,
+        output_folder: Optional[str],
+        input_file: str,
+    ) -> Optional[Path]:
+        """
+        Return the output ``Path`` based on the save option, or None for
+        the "next to input" strategy (the runner handles that internally).
+
+        Args:
+            save_option: UI-facing save strategy string.
+            output_folder: Explicit path when ``save_option`` is ``'Choose output folder'``.
+            input_file: Path to the source file for the ``'Save to Desktop'`` strategy.
+
+        Returns:
+            Resolved ``Path`` or ``None``.
+        """
+        if save_option == "Choose output folder" and output_folder:
+            p = Path(output_folder)
+            p.mkdir(parents=True, exist_ok=True)
+            return p
+        if save_option == "Save to Desktop":
+            desktop = Path.home() / "Desktop"
+            desktop.mkdir(exist_ok=True)
+            return desktop
+        # "Save next to input file" – let the runner decide
+        return None
+
+    def _poll_job_loop(self) -> None:
+        """
+        Background daemon loop that polls the current Job for updates.
+
+        Runs until the job enters a terminal state or until ``_stop_poll``
+        is set.  Uses ``page.run_task()`` to schedule UI updates on the Flet
+        event loop without triggering thread-safety violations.
+        """
+        job = self._current_job
+        if job is None:
+            return
+
+        service = _get_service()
+        POLL_INTERVAL = 0.25  # seconds
+
+        while not self._stop_poll.is_set():
+            # Re-fetch the current job state (it's mutated in-place by the runner)
+            current = service.get_job(job.id)
+            if current is None:
+                break
+
+            # Forward new log lines
+            new_logs = current.logs[self._seen_log_count:]
+            self._seen_log_count += len(new_logs)
+            for log_entry in new_logs:
+                level = getattr(log_entry, "level", "info")
+                message = getattr(log_entry, "message", str(log_entry))
+                self._schedule_log(message, level)
+
+            # Forward progress
+            if current.progress is not None:
+                etr = getattr(current, "estimated_time_remaining", None)
+                self._schedule_progress(float(current.progress), etr)
+
+            # Check for terminal states
+            status = current.status
+            if status in (
+                JobStatus.COMPLETED,
+                JobStatus.FAILED,
+                JobStatus.CANCELLED,
+            ):
+                output_path: Optional[str] = None
+                if current.result and current.result.audio_path:
+                    output_path = str(current.result.audio_path)
+                if status == JobStatus.COMPLETED:
+                    finish_msg = "Conversion completed successfully."
+                elif status == JobStatus.CANCELLED:
+                    finish_msg = "Cancelled"
+                else:
+                    finish_msg = f"Conversion failed: {current.error or 'Unknown error'}"
+
+                self._schedule_finished(finish_msg, output_path)
+                break
+
+            time.sleep(POLL_INTERVAL)
+
+        prevent_sleep_end()
+        self._state.is_converting = False
+
+    def _schedule_log(self, message: str, level: str) -> None:
+        """Schedule a log update on the Flet event loop."""
+        state = self._state
+        page = self._page
+        state.append_log(message, level)
+
+        async def _update() -> None:
+            cb = state.on_log
+            if cb:
+                cb(message, level)
+            try:
+                page.update()
+            except Exception:
+                pass
+
+        try:
+            page.run_task(_update)
+        except Exception:
+            pass
+
+    def _schedule_progress(self, fraction: float, etr: Optional[float]) -> None:
+        """Schedule a progress update on the Flet event loop."""
+        state = self._state
+        page = self._page
+        state.progress = max(0.0, min(1.0, fraction))
+        state.etr_seconds = etr
+
+        async def _update() -> None:
+            cb = state.on_progress
+            if cb:
+                cb(fraction, etr)
+            try:
+                page.update()
+            except Exception:
+                pass
+
+        try:
+            page.run_task(_update)
+        except Exception:
+            pass
+
+    def _schedule_finished(
+        self, message: str, output_path: Optional[str]
+    ) -> None:
+        """Schedule a completion notification on the Flet event loop."""
+        state = self._state
+        page = self._page
+        state.last_output_path = output_path
+        self._stop_poll.set()
+
+        async def _update() -> None:
+            state.is_converting = False
+            state.progress = 1.0
+            state.last_output_path = output_path
+            cb = state.on_conversion_finished
+            if cb:
+                cb(message, output_path)
+            try:
+                page.update()
+            except Exception:
+                pass
+
+        try:
+            page.run_task(_update)
+        except Exception:
+            pass

abogen/frontend/utils/helpers.py

@@ -0,0 +1,313 @@
+"""
+Frontend-specific utilities for the Abogen Flet application.
+
+Contains helpers for:
+- Human-readable size / duration formatting
+- Voice formula parsing and display
+- File-type detection
+- ETR (Estimated Time Remaining) formatting
+- Path resolution that adapts to desktop vs. web context
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from abogen.constants import (
+    LANGUAGE_DESCRIPTIONS,
+    SUPPORTED_INPUT_FORMATS,
+    SUPPORTED_SOUND_FORMATS,
+    SUBTITLE_FORMATS,
+    VOICES_INTERNAL,
+)
+
+
+# ---------------------------------------------------------------------------
+# Size / duration helpers
+# ---------------------------------------------------------------------------
+
+
+def human_readable_size(size_bytes: int, decimal_places: int = 2) -> str:
+    """
+    Convert a byte count into a human-readable string.
+
+    Args:
+        size_bytes: Number of bytes.
+        decimal_places: Significant decimal digits in the output.
+
+    Returns:
+        A string like ``"3.14 MB"`` or ``"1.00 KB"``.
+    """
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if size_bytes < 1024.0:
+            return f"{size_bytes:.{decimal_places}f} {unit}"
+        size_bytes /= 1024.0  # type: ignore[assignment]
+    return f"{size_bytes:.{decimal_places}f} PB"
+
+
+def format_duration(seconds: float) -> str:
+    """
+    Format a duration in seconds as ``HH:MM:SS``.
+
+    Args:
+        seconds: Non-negative floating-point duration.
+
+    Returns:
+        A colon-delimited time string, e.g. ``"00:03:42"``.
+    """
+    total = max(0, int(seconds))
+    h, remainder = divmod(total, 3600)
+    m, s = divmod(remainder, 60)
+    return f"{h:02d}:{m:02d}:{s:02d}"
+
+
+def format_etr(etr_seconds: Optional[float]) -> str:
+    """
+    Format an estimated time remaining value for the UI.
+
+    Args:
+        etr_seconds: Seconds remaining, or None when unknown.
+
+    Returns:
+        Human-readable string such as ``"~3 min 42 sec"`` or ``"Calculating…"``.
+    """
+    if etr_seconds is None:
+        return "Calculating…"
+    total = max(0, int(etr_seconds))
+    if total < 60:
+        return f"~{total} sec"
+    m, s = divmod(total, 60)
+    if m < 60:
+        return f"~{m} min {s} sec"
+    h, m = divmod(m, 60)
+    return f"~{h} h {m} min"
+
+
+# ---------------------------------------------------------------------------
+# File helpers
+# ---------------------------------------------------------------------------
+
+
+SUPPORTED_EXTENSIONS: Tuple[str, ...] = (
+    ".txt",
+    ".epub",
+    ".pdf",
+    ".md",
+    ".markdown",
+    ".srt",
+    ".ass",
+    ".vtt",
+)
+"""All file extensions that the drop-zone accepts."""
+
+
+def detect_file_type(file_path: str) -> str:
+    """
+    Return a normalised file-type token for the given path.
+
+    Args:
+        file_path: Absolute or relative path to the input file.
+
+    Returns:
+        One of ``'txt'``, ``'epub'``, ``'pdf'``, ``'markdown'``,
+        ``'subtitle'``, or ``'unknown'``.
+    """
+    ext = Path(file_path).suffix.lower()
+    if ext == ".epub":
+        return "epub"
+    if ext == ".pdf":
+        return "pdf"
+    if ext in (".md", ".markdown"):
+        return "markdown"
+    if ext in (".srt", ".ass", ".vtt"):
+        return "subtitle"
+    if ext == ".txt":
+        return "txt"
+    return "unknown"
+
+
+def is_supported_file(file_path: str) -> bool:
+    """
+    Return True when the file extension is in the supported set.
+
+    Args:
+        file_path: Path whose extension is inspected.
+    """
+    return Path(file_path).suffix.lower() in SUPPORTED_EXTENSIONS
+
+
+def is_book_type(file_type: str) -> bool:
+    """
+    Return True for file types that contain chapters / pages.
+
+    Args:
+        file_type: Token from ``detect_file_type()``.
+    """
+    return file_type in ("epub", "pdf", "markdown")
+
+
+# ---------------------------------------------------------------------------
+# Voice helpers
+# ---------------------------------------------------------------------------
+
+
+def voice_lang_code(voice: str) -> str:
+    """
+    Extract the language code character from a Kokoro voice name.
+
+    The first character of every internal voice name encodes the language
+    (e.g. ``'a'`` for American English, ``'b'`` for British English).
+
+    Args:
+        voice: Raw voice string like ``'af_heart'`` or a formula.
+
+    Returns:
+        Single lowercase character, defaulting to ``'a'`` on failure.
+    """
+    if not voice:
+        return "a"
+    # For plain voice IDs the first char is the language
+    if voice[0].isalpha() and "_" in voice[:4]:
+        return voice[0].lower()
+    # Formula: extract first alpha char
+    match = re.search(r"\b([a-z])", voice)
+    return match.group(1) if match else "a"
+
+
+def language_label(lang_code: str) -> str:
+    """
+    Return the human-readable label for a language code.
+
+    Args:
+        lang_code: Single-character code (``'a'``, ``'b'``, …).
+
+    Returns:
+        Display string, e.g. ``"American English"``.
+    """
+    return LANGUAGE_DESCRIPTIONS.get(lang_code, lang_code.upper())
+
+
+def grouped_voices() -> List[Tuple[str, List[str]]]:
+    """
+    Return the internal voice list grouped by language for display.
+
+    Returns:
+        List of ``(language_label, [voice_id, …])`` tuples.
+    """
+    groups: dict[str, List[str]] = {}
+    for v in VOICES_INTERNAL:
+        lang = language_label(v[0])
+        groups.setdefault(lang, []).append(v)
+    return sorted(groups.items())
+
+
+def voice_display_name(voice_id: str) -> str:
+    """
+    Convert a raw voice ID like ``'af_heart'`` to a prettier display name.
+
+    Args:
+        voice_id: Raw internal voice identifier.
+
+    Returns:
+        Formatted string, e.g. ``"af_heart"`` (unchanged; may be enhanced later).
+    """
+    return voice_id
+
+
+def parse_voice_formula(formula: str) -> List[Tuple[str, float]]:
+    """
+    Parse a Kokoro voice mix formula into a list of ``(voice_id, weight)`` tuples.
+
+    Example:
+        ``"af_heart*0.7+am_adam*0.3"`` → ``[('af_heart', 0.7), ('am_adam', 0.3)]``
+
+    Args:
+        formula: Space- or ``+``-joined mix formula string.
+
+    Returns:
+        Parsed list; empty if parsing fails.
+    """
+    parts: List[Tuple[str, float]] = []
+    for token in re.split(r"[+\s]+", formula.strip()):
+        token = token.strip()
+        if not token:
+            continue
+        if "*" in token:
+            name, _, weight_str = token.partition("*")
+            try:
+                parts.append((name.strip(), float(weight_str.strip())))
+            except ValueError:
+                pass
+        else:
+            # Bare voice id — assume full weight
+            if token in VOICES_INTERNAL:
+                parts.append((token, 1.0))
+    return parts
+
+
+# ---------------------------------------------------------------------------
+# Number formatting
+# ---------------------------------------------------------------------------
+
+
+def format_number(n: int) -> str:
+    """
+    Format an integer with thousands separators.
+
+    Args:
+        n: Integer value.
+
+    Returns:
+        Formatted string, e.g. ``"1,234,567"``.
+    """
+    return f"{n:,}"
+
+
+# ---------------------------------------------------------------------------
+# Path helpers
+# ---------------------------------------------------------------------------
+
+
+def safe_basename(path: Optional[str]) -> str:
+    """
+    Return the basename of a path, or an empty string when path is None/empty.
+
+    Args:
+        path: Optional file-system path.
+    """
+    if not path:
+        return ""
+    return os.path.basename(path)
+
+
+def output_format_label(fmt: str) -> str:
+    """
+    Return a display label for an audio output format key.
+
+    Args:
+        fmt: Lowercase format key (``'wav'``, ``'mp3'``, …).
+    """
+    labels = {
+        "wav": "WAV (lossless)",
+        "flac": "FLAC (lossless compressed)",
+        "mp3": "MP3",
+        "opus": "Opus (best compression)",
+        "m4b": "M4B (with chapters)",
+    }
+    return labels.get(fmt, fmt.upper())
+
+
+def subtitle_format_label(key: str) -> str:
+    """
+    Return the display label for a subtitle format key.
+
+    Args:
+        key: Internal subtitle format key (e.g. ``'ass_centered_narrow'``).
+    """
+    for k, label in SUBTITLE_FORMATS:
+        if k == key:
+            return label
+    return key

abogen/frontend/utils/theme.py

@@ -0,0 +1,264 @@
+"""
+Design tokens and theme configuration for the Abogen Flet frontend.
+
+This module defines the application's complete colour palette, typography
+scale, spacing constants, and border radii in one canonical place.
+All component modules import from here; changing a value here propagates
+instantly across the entire UI.
+
+Flet's ``ft.Theme`` uses ``ColorScheme``, but for custom widgets we paint
+directly with hex colours drawn from ``LIGHT`` and ``DARK`` palettes.
+"""
+
+from __future__ import annotations
+
+import flet as ft
+from dataclasses import dataclass
+
+
+# ---------------------------------------------------------------------------
+# Colour palettes
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _Palette:
+    """A complete colour palette for one theme mode."""
+
+    # Backgrounds
+    bg_base: str        # Deepest background (window / page)
+    bg_surface: str     # Cards, panels, dialogs
+    bg_elevated: str    # Slightly raised elements (toolbar, sidebar)
+    bg_input: str       # Text-field / dropdown backgrounds
+
+    # Brand accent
+    accent: str         # Primary interactive colour (buttons, links)
+    accent_muted: str   # Hover tint over accents
+    accent_on: str      # Text drawn on top of accent fills
+
+    # Semantic
+    success: str
+    error: str
+    warning: str
+    info: str
+
+    # Text hierarchy
+    text_primary: str
+    text_secondary: str
+    text_disabled: str
+    text_on_accent: str
+
+    # Borders / dividers
+    border: str
+    border_focused: str
+    divider: str
+
+    # Specific UI atoms
+    drop_zone_border: str
+    drop_zone_bg: str
+    drop_zone_active_border: str
+    drop_zone_active_bg: str
+    log_bg: str
+    log_text: str
+    progress_bar_bg: str
+    progress_bar_fill: str
+    sidebar_bg: str
+    sidebar_selected_bg: str
+    sidebar_selected_text: str
+    nav_indicator: str
+
+
+DARK = _Palette(
+    bg_base="#0f1117",
+    bg_surface="#181b23",
+    bg_elevated="#1e2230",
+    bg_input="#252a38",
+
+    accent="#5b8af5",
+    accent_muted="#3a5fc4",
+    accent_on="#ffffff",
+
+    success="#42ad4a",
+    error="#e84e3c",
+    warning="#f5a623",
+    info="#5b8af5",
+
+    text_primary="#e8eaf0",
+    text_secondary="#9ba3b8",
+    text_disabled="#4e5568",
+    text_on_accent="#ffffff",
+
+    border="#2c3147",
+    border_focused="#5b8af5",
+    divider="#252a38",
+
+    drop_zone_border="#3a4466",
+    drop_zone_bg="#151928",
+    drop_zone_active_border="#42ad4a",
+    drop_zone_active_bg="#0d1f10",
+    log_bg="#0d1117",
+    log_text="#b0b8cc",
+    progress_bar_bg="#1e2230",
+    progress_bar_fill="#5b8af5",
+    sidebar_bg="#13161f",
+    sidebar_selected_bg="#252a38",
+    sidebar_selected_text="#5b8af5",
+    nav_indicator="#5b8af5",
+)
+
+LIGHT = _Palette(
+    bg_base="#f4f5f8",
+    bg_surface="#ffffff",
+    bg_elevated="#edf0f5",
+    bg_input="#f0f2f7",
+
+    accent="#3a5fc4",
+    accent_muted="#2a4fae",
+    accent_on="#ffffff",
+
+    success="#2e9437",
+    error="#c0392b",
+    warning="#d4870a",
+    info="#3a5fc4",
+
+    text_primary="#1a1d27",
+    text_secondary="#5a6172",
+    text_disabled="#9ba3b8",
+    text_on_accent="#ffffff",
+
+    border="#dce0ea",
+    border_focused="#3a5fc4",
+    divider="#e8ebf2",
+
+    drop_zone_border="#a8b4d0",
+    drop_zone_bg="#f7f8fd",
+    drop_zone_active_border="#2e9437",
+    drop_zone_active_bg="#f0fff1",
+    log_bg="#f8f9fc",
+    log_text="#3d4358",
+    progress_bar_bg="#e4e8f0",
+    progress_bar_fill="#3a5fc4",
+    sidebar_bg="#eff1f5",
+    sidebar_selected_bg="#dde3f2",
+    sidebar_selected_text="#3a5fc4",
+    nav_indicator="#3a5fc4",
+)
+
+
+# ---------------------------------------------------------------------------
+# Typography
+# ---------------------------------------------------------------------------
+
+FONT_FAMILY = "Inter, Segoe UI, Roboto, system-ui, sans-serif"
+FONT_SIZE_XS = 11
+FONT_SIZE_SM = 12
+FONT_SIZE_BASE = 14
+FONT_SIZE_MD = 16
+FONT_SIZE_LG = 20
+FONT_SIZE_XL = 26
+FONT_SIZE_DISPLAY = 34
+
+
+# ---------------------------------------------------------------------------
+# Spacing scale (pixels)
+# ---------------------------------------------------------------------------
+
+SPACE_XS = 4
+SPACE_SM = 8
+SPACE_MD = 12
+SPACE_LG = 16
+SPACE_XL = 24
+SPACE_2XL = 32
+SPACE_3XL = 48
+
+
+# ---------------------------------------------------------------------------
+# Border radii
+# ---------------------------------------------------------------------------
+
+RADIUS_SM = 6
+RADIUS_MD = 10
+RADIUS_LG = 16
+RADIUS_FULL = 999  # Pill-shaped
+
+
+# ---------------------------------------------------------------------------
+# Flet ColorScheme builders
+# ---------------------------------------------------------------------------
+
+
+def build_color_scheme(palette: _Palette) -> ft.ColorScheme:
+    """
+    Construct a ``ft.ColorScheme`` from a ``_Palette`` object.
+
+    Args:
+        palette: The ``DARK`` or ``LIGHT`` palette.
+
+    Returns:
+        A fully-populated Flet ``ColorScheme``.
+    """
+    return ft.ColorScheme(
+        primary=palette.accent,
+        on_primary=palette.accent_on,
+        primary_container=palette.accent_muted,
+        secondary=palette.accent,
+        on_secondary=palette.text_on_accent,
+        surface=palette.bg_surface,
+        on_surface=palette.text_primary,
+        on_surface_variant=palette.text_secondary,
+        error=palette.error,
+        on_error=palette.text_on_accent,
+        outline=palette.border,
+    )
+
+
+def build_text_theme() -> ft.TextTheme:
+    """
+    Construct a ``ft.TextTheme`` using the application's type scale.
+
+    Returns:
+        A Flet ``TextTheme`` with consistent font-size assignments.
+    """
+    return ft.TextTheme(
+        display_large=ft.TextStyle(size=FONT_SIZE_DISPLAY, weight=ft.FontWeight.W_700),
+        headline_large=ft.TextStyle(size=FONT_SIZE_XL, weight=ft.FontWeight.W_700),
+        headline_medium=ft.TextStyle(size=FONT_SIZE_LG, weight=ft.FontWeight.W_600),
+        title_large=ft.TextStyle(size=FONT_SIZE_MD, weight=ft.FontWeight.W_600),
+        title_medium=ft.TextStyle(size=FONT_SIZE_BASE, weight=ft.FontWeight.W_500),
+        body_large=ft.TextStyle(size=FONT_SIZE_BASE),
+        body_medium=ft.TextStyle(size=FONT_SIZE_SM),
+        label_large=ft.TextStyle(size=FONT_SIZE_SM, weight=ft.FontWeight.W_500),
+        label_medium=ft.TextStyle(size=FONT_SIZE_XS),
+    )
+
+
+def make_theme(dark: bool) -> ft.Theme:
+    """
+    Build a complete Flet ``Theme`` for the requested mode.
+
+    Args:
+        dark: True for dark-mode theme, False for light-mode theme.
+
+    Returns:
+        A configured ``ft.Theme`` instance.
+    """
+    palette = DARK if dark else LIGHT
+    return ft.Theme(
+        color_scheme=build_color_scheme(palette),
+        text_theme=build_text_theme(),
+        color_scheme_seed=palette.accent,
+        use_material3=True,
+    )
+
+
+def get_palette(page: ft.Page) -> _Palette:
+    """
+    Return the active colour palette for the given page.
+
+    Args:
+        page: The Flet ``Page`` instance.
+
+    Returns:
+        ``DARK`` or ``LIGHT`` depending on the page's theme mode.
+    """
+    return DARK if page.theme_mode == ft.ThemeMode.DARK else LIGHT

abogen/frontend/views/__init__.py

@@ -0,0 +1,6 @@
+"""Views sub-package for the Abogen Flet frontend."""
+from .dashboard import DashboardView
+from .settings import SettingsView
+from .queue_view import QueueView
+
+__all__ = ["DashboardView", "SettingsView", "QueueView"]

abogen/frontend/views/dashboard.py

@@ -0,0 +1,587 @@
+"""
+Dashboard view – the primary conversion screen.
+
+Hosts the file drop-zone, voice/speed/format controls, real-time log
+terminal, progress bar, and the Start/Cancel/Finish action row.
+
+All heavy work is delegated to ConversionBridge which runs on daemon
+threads and schedules UI updates back onto the Flet event loop.
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+import flet as ft
+
+from ..state import AppState
+from ..utils.helpers import (
+    detect_file_type, human_readable_size, format_number,
+    format_etr, grouped_voices, output_format_label,
+    subtitle_format_label, is_book_type, voice_lang_code, SUPPORTED_EXTENSIONS
+)
+from ..utils.theme import get_palette, RADIUS_MD, RADIUS_SM, SPACE_SM, SPACE_MD, SPACE_LG, SPACE_XL
+from ..utils.conversion_bridge import ConversionBridge
+from ..components import (
+    build_drop_zone, build_log_terminal, log_entry,
+    build_primary_button, build_secondary_button,
+    build_card, build_section_header, labelled_row, show_snack,
+)
+from abogen.constants import (
+    SUBTITLE_FORMATS, SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION,
+    LANGUAGE_DESCRIPTIONS, VOICES_INTERNAL,
+)
+from abogen.utils import get_gpu_acceleration, get_user_cache_path, calculate_text_length, clean_text
+
+
+class DashboardView:
+    """
+    The main conversion dashboard.
+
+    Instantiated once per Flet session and mounted as a ``ft.Column``
+    inside the page's content area.
+    """
+
+    def __init__(self, page: ft.Page, state: AppState) -> None:
+        self._page = page
+        self._state = state
+        self._bridge = ConversionBridge(page, state)
+
+        # Internal refs
+        self._log_list: Optional[ft.ListView] = None
+        self._progress_bar: Optional[ft.ProgressBar] = None
+        self._etr_label: Optional[ft.Text] = None
+        self._drop_zone_ref: Optional[ft.GestureDetector] = None
+        self._drop_zone_container: Optional[ft.Container] = None
+        self._file_picker: Optional[ft.FilePicker] = None
+
+        # Wire state callbacks
+        state.on_log = self._on_log
+        state.on_progress = self._on_progress
+        state.on_conversion_finished = self._on_finished
+
+        # Build UI refs
+        self._voice_dd: Optional[ft.Dropdown] = None
+        self._speed_slider: Optional[ft.Slider] = None
+        self._speed_label: Optional[ft.Text] = None
+        self._format_dd: Optional[ft.Dropdown] = None
+        self._subtitle_dd: Optional[ft.Dropdown] = None
+        self._subtitle_fmt_dd: Optional[ft.Dropdown] = None
+        self._gpu_switch: Optional[ft.Switch] = None
+        self._start_btn: Optional[ft.ElevatedButton] = None
+        self._cancel_btn: Optional[ft.OutlinedButton] = None
+        self._finish_col: Optional[ft.Column] = None
+        self._controls_col: Optional[ft.Column] = None
+        self._log_section: Optional[ft.Container] = None
+        self._progress_col: Optional[ft.Column] = None
+
+    # ------------------------------------------------------------------
+    # Build
+    # ------------------------------------------------------------------
+
+    def build(self) -> ft.Column:
+        """Return the complete dashboard column."""
+        p = self._page
+        dark = p.theme_mode == ft.ThemeMode.DARK
+        pal = get_palette(p)
+        if self._file_picker is None:
+            self._file_picker = ft.FilePicker()
+
+        # --- Drop zone ---
+        self._drop_zone_container = ft.Container()
+        self._refresh_drop_zone()
+
+        # --- Voice selector ---
+        voice_items = []
+        for lang_label, voices in grouped_voices():
+            voice_items.append(ft.dropdown.Option(key=f"__hdr_{lang_label}", text=f"── {lang_label} ──", disabled=True))
+            for v in voices:
+                voice_items.append(ft.dropdown.Option(key=v, text=v))
+
+        self._voice_dd = ft.Dropdown(
+            options=voice_items,
+            value=self._state.selected_voice,
+            on_select=self._on_voice_changed,
+            dense=True,
+            expand=True,
+            border_radius=RADIUS_SM,
+        )
+
+        # --- Speed slider ---
+        self._speed_label = ft.Text(f"{self._state.speed:.2f}", size=13, width=40)
+        self._speed_slider = ft.Slider(
+            min=0.1, max=2.0, value=self._state.speed,
+            divisions=190, label="{value}",
+            on_change=self._on_speed_changed,
+            expand=True,
+        )
+
+        # --- Format ---
+        self._format_dd = ft.Dropdown(
+            options=[ft.dropdown.Option(key=k, text=output_format_label(k))
+                     for k in ("wav", "flac", "mp3", "opus", "m4b")],
+            value=self._state.selected_format,
+            on_select=lambda e: self._set_field("selected_format", e.control.value),
+            dense=True, expand=True, border_radius=RADIUS_SM,
+        )
+
+        # --- Subtitle mode ---
+        sub_modes = ["Disabled", "Line", "Sentence", "Sentence + Comma",
+                     "Sentence + Highlighting"] + [f"{i} word{'s' if i > 1 else ''}" for i in range(1, 11)]
+        self._subtitle_dd = ft.Dropdown(
+            options=[ft.dropdown.Option(m) for m in sub_modes],
+            value=self._state.subtitle_mode,
+            on_select=lambda e: self._set_field("subtitle_mode", e.control.value),
+            dense=True, expand=True, border_radius=RADIUS_SM,
+        )
+
+        # --- Subtitle format ---
+        self._subtitle_fmt_dd = ft.Dropdown(
+            options=[ft.dropdown.Option(key=k, text=lbl) for k, lbl in SUBTITLE_FORMATS],
+            value=self._state.subtitle_format,
+            on_select=lambda e: self._set_field("subtitle_format", e.control.value),
+            dense=True, expand=True, border_radius=RADIUS_SM,
+        )
+
+        # --- GPU ---
+        self._gpu_switch = ft.Switch(
+            value=self._state.use_gpu, label="",
+            on_change=lambda e: self._set_field("use_gpu", e.control.value),
+            active_color="#5b8af5" if dark else "#3a5fc4",
+        )
+
+        # --- Log ---
+        log_lv = ft.ListView(expand=True, auto_scroll=True, spacing=1, padding=ft.Padding.all(8))
+        self._log_list = log_lv
+        bg_log = "#0d1117" if dark else "#f8f9fc"
+        bd_log = "#252a38" if dark else "#dce0ea"
+        self._log_section = ft.Container(
+            content=log_lv, bgcolor=bg_log,
+            border=ft.Border.all(1, bd_log),
+            border_radius=RADIUS_SM, height=220,
+            clip_behavior=ft.ClipBehavior.HARD_EDGE,
+            visible=False,
+        )
+
+        # --- Progress ---
+        fill = "#5b8af5" if dark else "#3a5fc4"
+        bg_p = "#1e2230" if dark else "#e4e8f0"
+        self._progress_bar = ft.ProgressBar(
+            value=0, color=fill, bgcolor=bg_p, height=8,
+            border_radius=ft.BorderRadius.all(4), expand=True,
+        )
+        self._etr_label = ft.Text("", size=11, color=pal.text_secondary, text_align=ft.TextAlign.CENTER)
+        self._progress_col = ft.Column([
+            ft.Row([self._progress_bar], spacing=0),
+            self._etr_label,
+        ], spacing=SPACE_SM, horizontal_alignment=ft.CrossAxisAlignment.CENTER, visible=False)
+
+        # --- Buttons ---
+        self._start_btn = build_primary_button(
+            "Start Conversion",
+            icon="play_arrow",
+            on_click=self._on_start,
+            page=p,
+        )
+        self._cancel_btn = build_secondary_button(
+            "Cancel", icon="stop",
+            on_click=self._on_cancel, page=p,
+        )
+        self._cancel_btn.visible = False
+
+        # --- Finish row ---
+        self._finish_col = ft.Column([
+            ft.Row([
+                build_secondary_button("Open File", icon="open_in_new",
+                                       on_click=self._on_open_file, page=p),
+                build_secondary_button("Go to Folder", icon="folder_open",
+                                       on_click=self._on_go_folder, page=p),
+                build_secondary_button("New Conversion", icon="refresh",
+                                       on_click=self._on_reset, page=p),
+            ], wrap=True, spacing=SPACE_SM, run_spacing=SPACE_SM),
+        ], visible=False)
+
+        # --- Controls column ---
+        self._controls_col = ft.Column([
+            build_section_header("Voice & Speed", icon="record_voice_over", page=p),
+            labelled_row("Voice", self._voice_dd, page=p),
+            labelled_row("Speed", ft.Row([self._speed_slider, self._speed_label], expand=True, spacing=SPACE_SM), page=p),
+            ft.Divider(height=1, color=pal.divider),
+            build_section_header("Output", icon="audio_file", page=p),
+            labelled_row("Format", self._format_dd, page=p),
+            labelled_row("Subtitles", self._subtitle_dd, page=p),
+            labelled_row("Subtitle Format", self._subtitle_fmt_dd, page=p),
+            ft.Divider(height=1, color=pal.divider),
+            build_section_header("Processing", icon="memory", page=p),
+            labelled_row("GPU Acceleration", self._gpu_switch, page=p),
+        ], spacing=SPACE_MD)
+
+        outer = ft.Column([
+            self._drop_zone_container,
+            ft.Container(height=SPACE_MD),
+            build_card(self._controls_col, page=p),
+            ft.Container(height=SPACE_SM),
+            self._log_section,
+            self._progress_col,
+            ft.Row([self._start_btn, self._cancel_btn], spacing=SPACE_SM, wrap=True),
+            self._finish_col,
+        ], spacing=SPACE_MD, expand=True, scroll=ft.ScrollMode.AUTO)
+
+        return outer
+
+    # ------------------------------------------------------------------
+    # Drop-zone management
+    # ------------------------------------------------------------------
+
+    def _refresh_drop_zone(self, *, accent: bool = False, error: bool = False, err_msg: str = "") -> None:
+        """Rebuild the drop-zone widget and update its container."""
+        p = self._page
+        s = self._state
+        fname = None; fsize = None; fchars = None
+        if s.selected_file and os.path.exists(s.selected_file):
+            disp = s.displayed_file_path or s.selected_file
+            fname = os.path.basename(disp)
+            try:
+                fsize = human_readable_size(os.path.getsize(s.selected_file))
+            except Exception:
+                fsize = ""
+            if s.char_count:
+                fchars = format_number(s.char_count)
+
+        label = err_msg if error else "Drag & drop your file here or click to browse"
+        sub = "Supports .txt · .epub · .pdf · .md · .srt · .ass · .vtt"
+
+        dz = build_drop_zone(
+            on_pick=self._open_file_picker,
+            label=label, sub_label=sub,
+            accent=accent, error=error,
+            filename=fname, file_size=fsize, char_count=fchars,
+            page=p,
+        )
+        if self._drop_zone_container is not None:
+            self._drop_zone_container.content = dz
+        self._drop_zone_ref = dz
+
+    # ------------------------------------------------------------------
+    # File picking
+    # ------------------------------------------------------------------
+
+    def _open_file_picker(self) -> None:
+        """Open the native file picker dialog."""
+        self._page.run_task(self._pick_files_async)
+
+    async def _pick_files_async(self) -> None:
+        """Run the file picker using Flet's async service API."""
+        picker = self._file_picker
+        if picker is None:
+            picker = ft.FilePicker()
+            self._file_picker = picker
+
+        try:
+            files = await picker.pick_files(
+                dialog_title="Select Input File",
+                file_type=ft.FilePickerFileType.CUSTOM,
+                allowed_extensions=["txt", "epub", "pdf", "md", "markdown", "srt", "ass", "vtt"],
+                allow_multiple=False,
+            )
+        except Exception as ex:
+            self._refresh_drop_zone(error=True, err_msg="Could not open file picker.")
+            show_snack(self._page, f"File picker error: {ex}", error=True)
+            self._page.update()
+            return
+        if not files:
+            return
+        file_path = files[0].path
+        if not file_path or not os.path.exists(file_path):
+            return
+        self._load_file(file_path)
+
+    def _load_file(self, file_path: str) -> None:
+        """Validate and load a file into the session state."""
+        from pathlib import Path as _Path
+        ext = _Path(file_path).suffix.lower()
+        if ext not in SUPPORTED_EXTENSIONS:
+            self._state.reset_file_state()
+            self._refresh_drop_zone(error=True, err_msg=f"Unsupported file type: {ext}")
+            self._page.update()
+            return
+
+        ftype = detect_file_type(file_path)
+        s = self._state
+
+        if ftype in ("epub", "pdf", "markdown"):
+            # For book types: extract text to temp cache
+            self._handle_book_file(file_path, ftype)
+        else:
+            # Plain text / subtitle files
+            s.selected_file = file_path
+            s.selected_file_type = ftype
+            s.displayed_file_path = file_path
+            try:
+                with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+                    text = f.read()
+                s.char_count = calculate_text_length(clean_text(text))
+            except Exception:
+                s.char_count = 0
+            self._refresh_drop_zone(accent=True)
+            self._update_subtitle_availability()
+            self._page.update()
+
+    def _handle_book_file(self, book_path: str, ftype: str) -> None:
+        """Extract text from epub/pdf/markdown and store as temp txt."""
+        import threading as _t
+        s = self._state
+
+        def _extract():
+            try:
+                from abogen.text_extractor import extract_from_path
+                chapters = extract_from_path(book_path, file_type=ftype)
+                combined = "\n\n".join(ch.text for ch in chapters if ch.text.strip())
+                cache_dir = get_user_cache_path()
+                base = os.path.splitext(os.path.basename(book_path))[0]
+                fd, tmp = tempfile.mkstemp(prefix=f"{base}_", suffix=".txt", dir=cache_dir)
+                os.close(fd)
+                with open(tmp, "w", encoding="utf-8") as f:
+                    f.write(combined)
+
+                s.selected_file = tmp
+                s.selected_file_type = ftype
+                s.selected_book_path = book_path
+                s.displayed_file_path = book_path
+                s.char_count = calculate_text_length(clean_text(combined))
+                s.selected_chapters = [f"ch_{i}" for i in range(len(chapters))]
+
+                self._refresh_drop_zone(accent=True)
+                self._update_subtitle_availability()
+                self._page.update()
+            except Exception as ex:
+                s.reset_file_state()
+                self._refresh_drop_zone(error=True, err_msg=f"Could not parse file: {ex}")
+                self._page.update()
+
+        _t.Thread(target=_extract, daemon=True).start()
+
+    # ------------------------------------------------------------------
+    # Control event handlers
+    # ------------------------------------------------------------------
+
+    def _set_field(self, attr: str, value) -> None:
+        setattr(self._state, attr, value)
+        self._state.persist_config()
+
+    def _on_voice_changed(self, e: ft.ControlEvent) -> None:
+        v = e.control.value or "af_heart"
+        self._state.selected_voice = v
+        self._state.selected_lang = voice_lang_code(v)
+        self._state.persist_config()
+        self._update_subtitle_availability()
+        self._page.update()
+
+    def _on_speed_changed(self, e: ft.ControlEvent) -> None:
+        val = round(float(e.control.value), 2)
+        self._state.speed = val
+        if self._speed_label:
+            self._speed_label.value = f"{val:.2f}"
+        self._state.persist_config()
+        self._page.update()
+
+    def _update_subtitle_availability(self) -> None:
+        """Enable or disable subtitle controls based on selected language."""
+        lang = self._state.selected_lang
+        enabled = lang in SUPPORTED_LANGUAGES_FOR_SUBTITLE_GENERATION
+        if self._subtitle_dd:
+            self._subtitle_dd.disabled = not enabled
+        if self._subtitle_fmt_dd:
+            self._subtitle_fmt_dd.disabled = not enabled
+
+    # ------------------------------------------------------------------
+    # Conversion control
+    # ------------------------------------------------------------------
+
+    def _on_start(self, _: ft.ControlEvent) -> None:
+        """Validate inputs and kick off conversion."""
+        s = self._state
+        if not s.selected_file or not os.path.exists(s.selected_file):
+            self._refresh_drop_zone(error=True, err_msg="Please select an input file first.")
+            self._page.update()
+            return
+
+        # Transition UI to converting state
+        self._set_converting_ui(True)
+
+        self._bridge.start(
+            input_file=s.selected_file,
+            voice=s.get_voice_formula(),
+            lang_code=s.selected_lang,
+            speed=s.speed,
+            output_format=s.selected_format,
+            subtitle_mode=s.subtitle_mode,
+            subtitle_format=s.subtitle_format,
+            use_gpu=s.use_gpu,
+            save_option=s.save_option,
+            output_folder=s.selected_output_folder,
+            replace_single_newlines=s.replace_single_newlines,
+            char_count=s.char_count,
+            save_chapters_separately=s.save_chapters_separately or False,
+            merge_chapters_at_end=True if s.merge_chapters_at_end is None else s.merge_chapters_at_end,
+            separate_chapters_format=s.separate_chapters_format,
+            silence_between_chapters=s.silence_duration,
+            max_subtitle_words=s.max_subtitle_words,
+            chapter_intro_delay=s.chapter_intro_delay,
+            read_title_intro=s.read_title_intro,
+            read_closing_outro=s.read_closing_outro,
+            auto_prefix_chapter_titles=s.auto_prefix_chapter_titles,
+            normalize_chapter_opening_caps=s.normalize_chapter_opening_caps,
+            tts_provider=s.tts_provider,
+            supertonic_total_steps=s.supertonic_total_steps,
+            chunk_level=s.chunk_level,
+            generate_epub3=s.generate_epub3,
+            word_substitutions_enabled=s.word_substitutions_enabled,
+            word_substitutions_list=s.word_substitutions_list,
+            case_sensitive_substitutions=s.case_sensitive_substitutions,
+            replace_all_caps=s.replace_all_caps,
+            replace_numerals=s.replace_numerals,
+            fix_nonstandard_punctuation=s.fix_nonstandard_punctuation,
+        )
+
+    def _on_cancel(self, _: ft.ControlEvent) -> None:
+        self._bridge.cancel()
+
+    def _set_converting_ui(self, converting: bool) -> None:
+        """Toggle UI between idle and converting states."""
+        if self._start_btn:
+            self._start_btn.visible = not converting
+        if self._cancel_btn:
+            self._cancel_btn.visible = converting
+        if self._controls_col:
+            self._controls_col.visible = not converting
+        if self._log_section:
+            self._log_section.visible = converting
+            if self._log_list:
+                self._log_list.controls.clear()
+        if self._progress_col:
+            self._progress_col.visible = converting
+            if self._progress_bar:
+                self._progress_bar.value = 0
+            if self._etr_label:
+                self._etr_label.value = "Estimating…"
+        if self._finish_col:
+            self._finish_col.visible = False
+        self._page.update()
+
+    # ------------------------------------------------------------------
+    # State callbacks (called from background thread via page.run_task)
+    # ------------------------------------------------------------------
+
+    def _on_log(self, message: str, level: str) -> None:
+        if self._log_list is None:
+            return
+        entry = log_entry(message, level, self._page)
+        self._log_list.controls.append(entry)
+        # Cap log lines
+        if len(self._log_list.controls) > 2000:
+            self._log_list.controls = self._log_list.controls[-1800:]
+        try:
+            self._page.update()
+        except Exception:
+            pass
+
+    def _on_progress(self, fraction: float, etr: Optional[float]) -> None:
+        if self._progress_bar:
+            self._progress_bar.value = min(fraction, 0.99)
+        if self._etr_label:
+            self._etr_label.value = format_etr(etr)
+        try:
+            self._page.update()
+        except Exception:
+            pass
+
+    def _on_finished(self, message: str, output_path: Optional[str]) -> None:
+        if self._progress_bar:
+            self._progress_bar.value = 1.0
+        if self._cancel_btn:
+            self._cancel_btn.visible = False
+
+        if message == "Cancelled":
+            # Restore idle state
+            self._set_converting_ui(False)
+            show_snack(self._page, "Conversion cancelled.", error=True)
+            return
+
+        if "failed" in message.lower() or "error" in message.lower():
+            self._log_on_log(message, "error")
+            self._set_converting_ui(False)
+            show_snack(self._page, f"Error: {message}", error=True)
+            return
+
+        # Success
+        if self._log_section:
+            self._log_section.visible = True
+        if self._progress_col:
+            self._progress_col.visible = False
+        if self._controls_col:
+            self._controls_col.visible = False
+        if self._finish_col:
+            self._finish_col.visible = True
+        if self._start_btn:
+            self._start_btn.visible = False
+        show_snack(self._page, "Conversion completed!")
+        try:
+            self._page.update()
+        except Exception:
+            pass
+
+    def _log_on_log(self, message: str, level: str) -> None:
+        self._on_log(message, level)
+
+    # ------------------------------------------------------------------
+    # Finish actions
+    # ------------------------------------------------------------------
+
+    def _on_open_file(self, _: ft.ControlEvent) -> None:
+        path = self._state.last_output_path
+        if path and os.path.exists(path):
+            import subprocess, platform
+            try:
+                if platform.system() == "Darwin":
+                    subprocess.Popen(["open", path])
+                elif platform.system() == "Windows":
+                    os.startfile(path)
+                else:
+                    subprocess.Popen(["xdg-open", path])
+            except Exception as ex:
+                show_snack(self._page, f"Cannot open file: {ex}", error=True)
+        else:
+            show_snack(self._page, "Output file not found.", error=True)
+
+    def _on_go_folder(self, _: ft.ControlEvent) -> None:
+        path = self._state.last_output_path
+        folder = os.path.dirname(path) if path and os.path.isfile(path) else path
+        if folder and os.path.isdir(folder):
+            import subprocess, platform
+            try:
+                if platform.system() == "Darwin":
+                    subprocess.Popen(["open", folder])
+                elif platform.system() == "Windows":
+                    subprocess.Popen(["explorer", folder])
+                else:
+                    subprocess.Popen(["xdg-open", folder])
+            except Exception as ex:
+                show_snack(self._page, f"Cannot open folder: {ex}", error=True)
+        else:
+            show_snack(self._page, "Output folder not found.", error=True)
+
+    def _on_reset(self, _: ft.ControlEvent) -> None:
+        self._state.reset_file_state()
+        self._state.reset_conversion_state()
+        self._refresh_drop_zone()
+        self._set_converting_ui(False)
+        if self._finish_col:
+            self._finish_col.visible = False
+        if self._controls_col:
+            self._controls_col.visible = True
+        if self._start_btn:
+            self._start_btn.visible = True
+        self._page.update()

abogen/frontend/views/queue_view.py

@@ -0,0 +1,154 @@
+"""
+Queue management view.
+
+Displays the current conversion queue, allowing the user to reorder,
+remove, and inspect queued items before starting batch processing.
+"""
+from __future__ import annotations
+from typing import Optional
+
+import flet as ft
+
+from ..state import AppState, ConversionJob
+from ..utils.theme import get_palette, RADIUS_SM, SPACE_SM, SPACE_MD, SPACE_LG
+from ..utils.helpers import safe_basename, output_format_label, format_number
+from ..components import (
+    build_card, build_section_header, build_primary_button,
+    build_secondary_button, show_snack, build_divider,
+    resolve_icon,
+)
+
+
+class QueueView:
+    """Queue manager view."""
+
+    def __init__(self, page: ft.Page, state: AppState) -> None:
+        self._page = page
+        self._state = state
+        self._list_col: Optional[ft.Column] = None
+
+    def build(self) -> ft.Column:
+        p = self._page
+        s = self._state
+        pal = get_palette(p)
+        dark = p.theme_mode == ft.ThemeMode.DARK
+
+        self._list_col = ft.Column(spacing=SPACE_SM)
+        self._refresh_list()
+
+        header = build_section_header("Conversion Queue",
+                                      icon="list_alt", page=p)
+
+        action_row = ft.Row([
+            build_primary_button(
+                "Start Queue",
+                icon="play_arrow",
+                on_click=self._on_start_queue,
+                page=p,
+                disabled=not s.queued_items,
+            ),
+            build_secondary_button(
+                "Clear All",
+                icon="delete_sweep",
+                on_click=self._on_clear_queue,
+                page=p,
+            ),
+        ], spacing=SPACE_SM, wrap=True)
+
+        queue_card = build_card(ft.Column([
+            header,
+            ft.Divider(height=1, color=pal.divider),
+            self._list_col,
+            ft.Container(height=SPACE_SM),
+            action_row,
+        ], spacing=SPACE_MD), page=p)
+
+        return ft.Column([queue_card], scroll=ft.ScrollMode.AUTO, expand=True)
+
+    # ------------------------------------------------------------------
+
+    def _refresh_list(self) -> None:
+        if self._list_col is None:
+            return
+        self._list_col.controls.clear()
+        s = self._state
+        pal = get_palette(self._page)
+        dark = self._page.theme_mode == ft.ThemeMode.DARK
+
+        if not s.queued_items:
+            self._list_col.controls.append(
+                ft.Text("No items in the queue.", size=13,
+                        color=pal.text_secondary,
+                        text_align=ft.TextAlign.CENTER)
+            )
+            return
+
+        for idx, job in enumerate(s.queued_items):
+            tile = self._build_job_tile(idx, job, dark, pal)
+            self._list_col.controls.append(tile)
+
+        try:
+            self._page.update()
+        except Exception:
+            pass
+
+    def _build_job_tile(self, idx: int, job: ConversionJob, dark: bool, pal) -> ft.Container:
+        """Build a single queue-item tile."""
+        bg = pal.bg_elevated
+        border_clr = pal.border
+        accent = "#5b8af5" if dark else "#3a5fc4"
+        text_primary = pal.text_primary
+        text_secondary = pal.text_secondary
+
+        def _remove(_):
+            self._state.queued_items.pop(idx)
+            self._refresh_list()
+
+        name = safe_basename(job.display_name or job.file_path)
+        details = (
+            f"Voice: {job.voice}  ·  Format: {output_format_label(job.output_format)}"
+            f"  ·  Speed: {job.speed:.2f}x  ·  Chars: {format_number(job.char_count)}"
+        )
+
+        return ft.Container(
+            content=ft.Row([
+                ft.Container(
+                    content=ft.Text(str(idx + 1), size=12, weight=ft.FontWeight.W_700,
+                                    color=accent),
+                    width=32,
+                ),
+                ft.Column([
+                    ft.Text(name, size=13, weight=ft.FontWeight.W_600, color=text_primary,
+                            no_wrap=True, overflow=ft.TextOverflow.ELLIPSIS),
+                    ft.Text(details, size=11, color=text_secondary),
+                ], expand=True, tight=True, spacing=2),
+                ft.IconButton(
+                    icon=resolve_icon("delete_outline"),
+                    icon_color=pal.error if hasattr(pal, "error") else "#e84e3c",
+                    icon_size=18,
+                    tooltip="Remove",
+                    on_click=_remove,
+                ),
+            ], vertical_alignment=ft.CrossAxisAlignment.CENTER, spacing=SPACE_SM),
+            bgcolor=bg,
+            border=ft.Border.all(1, border_clr),
+            border_radius=RADIUS_SM,
+            padding=ft.Padding.symmetric(horizontal=SPACE_MD, vertical=SPACE_SM),
+        )
+
+    # ------------------------------------------------------------------
+
+    def _on_start_queue(self, _: ft.ControlEvent) -> None:
+        if not self._state.queued_items:
+            show_snack(self._page, "Queue is empty.", error=True)
+            return
+        # Navigate to dashboard and trigger queue start
+        # This is wired in main.py via the nav controller
+        self._page.pubsub.send_all("start_queue")
+
+    def _on_clear_queue(self, _: ft.ControlEvent) -> None:
+        if not self._state.queued_items:
+            return
+        self._state.queued_items.clear()
+        self._refresh_list()
+        show_snack(self._page, "Queue cleared.")

abogen/frontend/views/settings.py

@@ -0,0 +1,305 @@
+"""
+Settings view – a categorised, scrollable settings page.
+
+Groups settings into collapsible cards:
+  - Output (format, save location, chapters)
+  - Text processing (newlines, caps, substitutions, numerals)
+  - Subtitle options
+  - TTS pipeline (provider, GPU, chunking)
+  - Integrations (Audiobookshelf, Calibre OPDS)
+"""
+from __future__ import annotations
+from typing import Optional
+
+import flet as ft
+
+from ..state import AppState
+from ..utils.theme import get_palette, RADIUS_MD, RADIUS_SM, SPACE_SM, SPACE_MD, SPACE_LG
+from ..utils.helpers import output_format_label, subtitle_format_label, SUPPORTED_EXTENSIONS
+from ..components import (
+    build_card, build_section_header, labelled_row, show_snack, build_divider,
+    build_primary_button,
+)
+from abogen.constants import SUBTITLE_FORMATS
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _dd(options, value, on_change, **kw):
+    """Compact dropdown factory."""
+    return ft.Dropdown(
+        options=[ft.dropdown.Option(key=k, text=v) for k, v in options],
+        value=value, on_select=on_change, dense=True,
+        border_radius=RADIUS_SM, expand=True, **kw
+    )
+
+
+def _sw(value, on_change, label=""):
+    return ft.Switch(value=value, on_change=on_change, label=label)
+
+
+class SettingsView:
+    """The full settings panel."""
+
+    def __init__(self, page: ft.Page, state: AppState) -> None:
+        self._page = page
+        self._state = state
+
+    def build(self) -> ft.Column:
+        p = self._page
+        s = self._state
+        pal = get_palette(p)
+
+        # ── Output card ──────────────────────────────────────────────
+        format_dd = _dd(
+            [(k, output_format_label(k)) for k in ("wav", "flac", "mp3", "opus", "m4b")],
+            s.selected_format,
+            lambda e: self._save("selected_format", e.control.value),
+        )
+        save_dd = _dd(
+            [
+                ("Save next to input file", "Save next to input file"),
+                ("Save to Desktop", "Save to Desktop"),
+                ("Choose output folder", "Choose output folder"),
+            ],
+            s.save_option,
+            lambda e: self._save("save_option", e.control.value),
+        )
+        chapters_sw = _sw(s.save_chapters_separately or False,
+                          lambda e: self._save("save_chapters_separately", e.control.value))
+        merge_sw = _sw(True if s.merge_chapters_at_end is None else s.merge_chapters_at_end,
+                       lambda e: self._save("merge_chapters_at_end", e.control.value))
+        sep_fmt_dd = _dd(
+            [(k, output_format_label(k)) for k in ("wav", "flac", "mp3", "opus")],
+            s.separate_chapters_format,
+            lambda e: self._save("separate_chapters_format", e.control.value),
+        )
+        epub3_sw = _sw(s.generate_epub3, lambda e: self._save("generate_epub3", e.control.value))
+
+        output_card = build_card(ft.Column([
+            build_section_header("Output", icon="audio_file", page=p),
+            labelled_row("Audio Format", format_dd, page=p),
+            labelled_row("Save Location", save_dd, page=p),
+            build_divider(p),
+            labelled_row("Save Chapters Separately", chapters_sw, page=p),
+            labelled_row("Merge at End", merge_sw, page=p),
+            labelled_row("Chapter Format", sep_fmt_dd, page=p),
+            labelled_row("Generate EPUB3", epub3_sw, page=p),
+        ], spacing=SPACE_MD), page=p)
+
+        # ── Text processing card ─────────────────────────────────────
+        newlines_sw = _sw(s.replace_single_newlines,
+                          lambda e: self._save("replace_single_newlines", e.control.value))
+        caps_sw = _sw(s.replace_all_caps, lambda e: self._save("replace_all_caps", e.control.value))
+        norm_sw = _sw(s.normalize_chapter_opening_caps,
+                      lambda e: self._save("normalize_chapter_opening_caps", e.control.value))
+        numerals_sw = _sw(s.replace_numerals, lambda e: self._save("replace_numerals", e.control.value))
+        punct_sw = _sw(s.fix_nonstandard_punctuation,
+                       lambda e: self._save("fix_nonstandard_punctuation", e.control.value))
+        wordsub_sw = _sw(s.word_substitutions_enabled,
+                         lambda e: self._save("word_substitutions_enabled", e.control.value))
+        wordsub_tf = ft.TextField(
+            value=s.word_substitutions_list,
+            multiline=True, min_lines=3, max_lines=6,
+            hint_text="word|replacement  (one per line)",
+            on_change=lambda e: self._save("word_substitutions_list", e.control.value),
+            expand=True, border_radius=RADIUS_SM, text_size=12,
+        )
+        case_sw = _sw(s.case_sensitive_substitutions,
+                      lambda e: self._save("case_sensitive_substitutions", e.control.value))
+        spacy_sw = _sw(s.use_spacy_segmentation,
+                       lambda e: self._save("use_spacy_segmentation", e.control.value))
+        chunk_dd = _dd(
+            [("paragraph", "Paragraph"), ("sentence", "Sentence")],
+            s.chunk_level,
+            lambda e: self._save("chunk_level", e.control.value),
+        )
+        title_intro_sw = _sw(s.read_title_intro, lambda e: self._save("read_title_intro", e.control.value))
+        outro_sw = _sw(s.read_closing_outro, lambda e: self._save("read_closing_outro", e.control.value))
+        prefix_sw = _sw(s.auto_prefix_chapter_titles,
+                        lambda e: self._save("auto_prefix_chapter_titles", e.control.value))
+
+        text_card = build_card(ft.Column([
+            build_section_header("Text Processing", icon="text_fields", page=p),
+            labelled_row("Replace Single Newlines", newlines_sw,
+                         tooltip="Replace single newlines with spaces before processing.", page=p),
+            labelled_row("Replace ALL CAPS Words", caps_sw, page=p),
+            labelled_row("Normalize Opening CAPS", norm_sw, page=p),
+            labelled_row("Replace Numerals (spoken)", numerals_sw, page=p),
+            labelled_row("Fix Non-standard Punctuation", punct_sw, page=p),
+            build_divider(p),
+            labelled_row("Word Substitutions", wordsub_sw, page=p),
+            labelled_row("Case Sensitive", case_sw, page=p),
+            ft.Text("Substitution rules  (word|replacement, one per line):",
+                    size=12, color=pal.text_secondary),
+            wordsub_tf,
+            build_divider(p),
+            build_section_header("Chapter Options", icon="library_books", page=p),
+            labelled_row("Announce Book Title (intro)", title_intro_sw, page=p),
+            labelled_row("Announce Book Title (outro)", outro_sw, page=p),
+            labelled_row("Auto-prefix Chapter Titles", prefix_sw, page=p),
+            labelled_row("Chunk Level", chunk_dd, page=p),
+            labelled_row("Use spaCy Segmentation", spacy_sw, page=p),
+        ], spacing=SPACE_MD), page=p)
+
+        # ── Subtitle card ─────────────────────────────────────────────
+        sub_modes = ["Disabled", "Line", "Sentence", "Sentence + Comma",
+                     "Sentence + Highlighting"] + [f"{i} word{'s' if i > 1 else ''}" for i in range(1, 11)]
+        sub_mode_dd = _dd(
+            [(m, m) for m in sub_modes],
+            s.subtitle_mode,
+            lambda e: self._save("subtitle_mode", e.control.value),
+        )
+        sub_fmt_dd = _dd(
+            [(k, lbl) for k, lbl in SUBTITLE_FORMATS],
+            s.subtitle_format,
+            lambda e: self._save("subtitle_format", e.control.value),
+        )
+
+        def _mk_mw_slider():
+            lbl = ft.Text(str(s.max_subtitle_words), size=12, width=36)
+            sl = ft.Slider(
+                min=1, max=200, value=s.max_subtitle_words, divisions=199, label="{value}",
+                expand=True,
+                on_change=lambda e: (self._save("max_subtitle_words", int(e.control.value)),
+                                     setattr(lbl, "value", str(int(e.control.value))),
+                                     self._page.update()),
+            )
+            return ft.Row([sl, lbl], expand=True, spacing=SPACE_SM)
+
+        sub_speed_dd = _dd(
+            [("tts", "TTS duration"), ("silence", "Silence detection")],
+            s.subtitle_speed_method,
+            lambda e: self._save("subtitle_speed_method", e.control.value),
+        )
+        silent_gaps_sw = _sw(s.use_silent_gaps,
+                             lambda e: self._save("use_silent_gaps", e.control.value))
+
+        subtitle_card = build_card(ft.Column([
+            build_section_header("Subtitles", icon="subtitles", page=p),
+            labelled_row("Mode", sub_mode_dd, page=p),
+            labelled_row("Format", sub_fmt_dd, page=p),
+            labelled_row("Max Words / Block", _mk_mw_slider(), page=p),
+            labelled_row("Speed Method", sub_speed_dd, page=p),
+            labelled_row("Silent Gaps", silent_gaps_sw, page=p),
+        ], spacing=SPACE_MD), page=p)
+
+        # ── Pipeline card ─────────────────────────────────────────────
+        provider_dd = _dd(
+            [("kokoro", "Kokoro (default)"), ("supertonic", "Supertonic")],
+            s.tts_provider,
+            lambda e: self._save("tts_provider", e.control.value),
+        )
+        gpu_sw = _sw(s.use_gpu, lambda e: self._save("use_gpu", e.control.value),
+                     label="GPU acceleration (if available)")
+
+        def _mk_steps_slider():
+            lbl = ft.Text(str(s.supertonic_total_steps), size=12, width=28)
+            sl = ft.Slider(
+                min=2, max=15, value=s.supertonic_total_steps, divisions=13,
+                label="{value}", expand=True,
+                on_change=lambda e: (self._save("supertonic_total_steps", int(e.control.value)),
+                                     setattr(lbl, "value", str(int(e.control.value))),
+                                     self._page.update()),
+            )
+            return ft.Row([sl, lbl], expand=True, spacing=SPACE_SM)
+
+        thresh_tf = ft.TextField(
+            value=str(s.speaker_analysis_threshold), width=80,
+            keyboard_type=ft.KeyboardType.NUMBER, border_radius=RADIUS_SM,
+            on_change=lambda e: self._save_int("speaker_analysis_threshold", e.control.value, 1, 25),
+        )
+        silence_tf = ft.TextField(
+            value=str(s.silence_duration), width=80,
+            keyboard_type=ft.KeyboardType.NUMBER, border_radius=RADIUS_SM,
+            on_change=lambda e: self._save_float("silence_duration", e.control.value, 0.0),
+        )
+        intro_tf = ft.TextField(
+            value=str(s.chapter_intro_delay), width=80,
+            keyboard_type=ft.KeyboardType.NUMBER, border_radius=RADIUS_SM,
+            on_change=lambda e: self._save_float("chapter_intro_delay", e.control.value, 0.0),
+        )
+
+        pipeline_card = build_card(ft.Column([
+            build_section_header("TTS Pipeline", icon="settings", page=p),
+            labelled_row("Provider", provider_dd, page=p),
+            labelled_row("GPU Acceleration", gpu_sw, page=p),
+            labelled_row("Supertonic Steps", _mk_steps_slider(), page=p),
+            build_divider(p),
+            labelled_row("Speaker Analysis Threshold", thresh_tf, page=p),
+            labelled_row("Silence Between Chapters (s)", silence_tf, page=p),
+            labelled_row("Chapter Intro Delay (s)", intro_tf, page=p),
+        ], spacing=SPACE_MD), page=p)
+
+        # ── Integration card (Audiobookshelf) ─────────────────────────
+        abs_enabled_sw = _sw(s.audiobookshelf_enabled,
+                             lambda e: self._save("audiobookshelf_enabled", e.control.value))
+        abs_url_tf = ft.TextField(value=s.audiobookshelf_base_url, hint_text="http://abs-server:13378",
+                                  expand=True, border_radius=RADIUS_SM, text_size=12,
+                                  on_change=lambda e: self._save("audiobookshelf_base_url", e.control.value))
+        abs_token_tf = ft.TextField(value=s.audiobookshelf_api_token, password=True,
+                                    can_reveal_password=True, expand=True,
+                                    border_radius=RADIUS_SM, text_size=12,
+                                    on_change=lambda e: self._save("audiobookshelf_api_token", e.control.value))
+        abs_lib_tf = ft.TextField(value=s.audiobookshelf_library_id, hint_text="Library ID",
+                                  expand=True, border_radius=RADIUS_SM, text_size=12,
+                                  on_change=lambda e: self._save("audiobookshelf_library_id", e.control.value))
+        abs_auto_sw = _sw(s.audiobookshelf_auto_send,
+                          lambda e: self._save("audiobookshelf_auto_send", e.control.value))
+
+        integ_card = build_card(ft.Column([
+            build_section_header("Audiobookshelf Integration",
+                                 icon="cloud_upload", page=p),
+            labelled_row("Enabled", abs_enabled_sw, page=p),
+            labelled_row("Server URL", abs_url_tf, page=p),
+            labelled_row("API Token", abs_token_tf, page=p),
+            labelled_row("Library ID", abs_lib_tf, page=p),
+            labelled_row("Auto-upload on finish", abs_auto_sw, page=p),
+        ], spacing=SPACE_MD), page=p)
+
+        save_btn = build_primary_button(
+            "Save Settings", icon="save",
+            on_click=self._on_save, page=p,
+        )
+
+        return ft.Column([
+            output_card,
+            ft.Container(height=SPACE_MD),
+            text_card,
+            ft.Container(height=SPACE_MD),
+            subtitle_card,
+            ft.Container(height=SPACE_MD),
+            pipeline_card,
+            ft.Container(height=SPACE_MD),
+            integ_card,
+            ft.Container(height=SPACE_LG),
+            save_btn,
+            ft.Container(height=SPACE_LG),
+        ], spacing=0, scroll=ft.ScrollMode.AUTO, expand=True)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _save(self, attr: str, value) -> None:
+        setattr(self._state, attr, value)
+
+    def _save_int(self, attr: str, raw: str, lo: int, hi: int) -> None:
+        try:
+            v = max(lo, min(hi, int(raw)))
+            setattr(self._state, attr, v)
+        except ValueError:
+            pass
+
+    def _save_float(self, attr: str, raw: str, lo: float) -> None:
+        try:
+            v = max(lo, float(raw))
+            setattr(self._state, attr, v)
+        except ValueError:
+            pass
+
+    def _on_save(self, _: ft.ControlEvent) -> None:
+        self._state.persist_config()
+        show_snack(self._page, "Settings saved.")

abogen/heteronym_overrides.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import hashlib
+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
+
+
+@dataclass(frozen=True)
+class HeteronymVariant:
+    key: str
+    label: str
+    replacement_token: str
+    example_sentence: str
+
+
+@dataclass(frozen=True)
+class HeteronymSpec:
+    token: str
+    variants: Tuple[HeteronymVariant, HeteronymVariant]
+
+    def default_choice_for_token(self, spacy_token: Any) -> str:
+        """Return the most likely variant key for this token."""
+        pos = (getattr(spacy_token, "pos_", "") or "").upper()
+        tag = (getattr(spacy_token, "tag_", "") or "").upper()
+
+        token_lower = self.token.casefold()
+        if token_lower == "wind":
+            # VERB => /waɪnd/, NOUN => /wɪnd/
+            return "verb" if pos == "VERB" else "noun"
+        if token_lower == "read":
+            # VBD/VBN => /rɛd/
+            return "past" if tag in {"VBD", "VBN"} else "present"
+        if token_lower == "tear":
+            return "verb" if pos == "VERB" else "noun"
+        if token_lower == "close":
+            return "verb" if pos == "VERB" else "adj"
+        if token_lower == "lead":
+            # Default to verb unless POS suggests noun.
+            return "metal" if pos == "NOUN" else "verb"
+        return self.variants[0].key
+
+
+# Minimal, high-confidence starter set.
+# NOTE: These replacements intentionally prioritize speech output.
+# Some replacements may not be appropriate for subtitles/text exports.
+_HETERONYM_SPECS: Dict[str, HeteronymSpec] = {
+    "wind": HeteronymSpec(
+        token="wind",
+        variants=(
+            HeteronymVariant(
+                key="noun",
+                label="Noun (the wind)",
+                replacement_token="wind",
+                example_sentence="Listen to the wind.",
+            ),
+            HeteronymVariant(
+                key="verb",
+                label="Verb (to wind)",
+                replacement_token="wynd",
+                example_sentence="I need to wind the watch.",
+            ),
+        ),
+    ),
+    "read": HeteronymSpec(
+        token="read",
+        variants=(
+            HeteronymVariant(
+                key="present",
+                label="Present (I read every day)",
+                replacement_token="read",
+                example_sentence="I read every day.",
+            ),
+            HeteronymVariant(
+                key="past",
+                label="Past (I read it yesterday)",
+                replacement_token="red",
+                example_sentence="I read it yesterday.",
+            ),
+        ),
+    ),
+    "tear": HeteronymSpec(
+        token="tear",
+        variants=(
+            HeteronymVariant(
+                key="noun",
+                label="Noun (a tear /crying/)",
+                replacement_token="tier",
+                example_sentence="A tear rolled down her cheek.",
+            ),
+            HeteronymVariant(
+                key="verb",
+                label="Verb (to tear /rip/)",
+                replacement_token="tear",
+                example_sentence="Please don't tear the page.",
+            ),
+        ),
+    ),
+    "close": HeteronymSpec(
+        token="close",
+        variants=(
+            HeteronymVariant(
+                key="adj",
+                label="Adjective (close /near/)",
+                replacement_token="close",
+                example_sentence="We are close to the station.",
+            ),
+            HeteronymVariant(
+                key="verb",
+                label="Verb (close /klohz/)",
+                replacement_token="cloze",
+                example_sentence="Please close the door.",
+            ),
+        ),
+    ),
+    "lead": HeteronymSpec(
+        token="lead",
+        variants=(
+            HeteronymVariant(
+                key="verb",
+                label="Verb (to lead)",
+                replacement_token="lead",
+                example_sentence="They will lead the way.",
+            ),
+            HeteronymVariant(
+                key="metal",
+                label="Noun (lead /metal/)",
+                replacement_token="led",
+                example_sentence="The pipe was made of lead.",
+            ),
+        ),
+    ),
+}
+
+
+def _hash_id(*parts: str) -> str:
+    digest = hashlib.sha1("\n".join(parts).encode("utf-8")).hexdigest()
+    return digest[:12]
+
+
+_WORD_BOUNDARY_CACHE: Dict[str, re.Pattern[str]] = {}
+
+
+def _word_boundary_pattern(token: str) -> re.Pattern[str]:
+    key = token.casefold()
+    cached = _WORD_BOUNDARY_CACHE.get(key)
+    if cached is not None:
+        return cached
+    escaped = re.escape(token)
+    pattern = re.compile(
+        rf"(?i)(?<!\w){escaped}(?P<possessive>'s|\u2019s|\u2019)?(?!\w)"
+    )
+    _WORD_BOUNDARY_CACHE[key] = pattern
+    return pattern
+
+
+def _preserve_case(replacement: str, original: str) -> str:
+    if not replacement:
+        return replacement
+    if original.isupper():
+        return replacement.upper()
+    if original[:1].isupper():
+        return replacement[:1].upper() + replacement[1:]
+    return replacement
+
+
+def _build_replacement_sentence(
+    sentence: str, token: str, replacement_token: str
+) -> str:
+    pattern = _word_boundary_pattern(token)
+
+    def _repl(match: re.Match[str]) -> str:
+        matched = match.group(0) or ""
+        suffix = match.group("possessive") or ""
+        base = matched[: len(matched) - len(suffix)] if suffix else matched
+        return _preserve_case(replacement_token, base) + suffix
+
+    return pattern.sub(_repl, sentence)
+
+
+def _load_spacy(language: str) -> Any:
+    if spacy is None:
+        return None
+
+    # English only for now.
+    # Use installed small model; keep it simple.
+    lang = (language or "en").lower()
+    if lang.startswith("en"):
+        try:
+            return spacy.load("en_core_web_sm")
+        except Exception:
+            return spacy.blank("en")
+    return spacy.blank("xx")
+
+
+def extract_heteronym_overrides(
+    chapters: Sequence[Mapping[str, Any]],
+    *,
+    language: str,
+    existing: Optional[Iterable[Mapping[str, Any]]] = None,
+) -> List[Dict[str, Any]]:
+    """Extract distinct heteronym-containing sentences from chapters.
+
+    Returns entries shaped for persistence + UI.
+
+    Each entry contains:
+    - id
+    - token
+    - sentence
+    - options: [{key,label,replacement_token,replacement_sentence,example_sentence}]
+    - default_choice
+    - choice
+    """
+
+    lang = (language or "en").lower()
+    if not lang.startswith("en"):
+        return []
+
+    if spacy is None:
+        return []
+
+    nlp = _load_spacy(lang)
+    if nlp is None:
+        return []
+
+    previous_choices: Dict[str, str] = {}
+    if existing:
+        for item in existing:
+            if not isinstance(item, Mapping):
+                continue
+            entry_id = str(item.get("id") or "").strip()
+            choice = str(item.get("choice") or "").strip()
+            if entry_id and choice:
+                previous_choices[entry_id] = choice
+
+    results: List[Dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+
+    for chapter in chapters:
+        if not isinstance(chapter, Mapping):
+            continue
+        text = str(chapter.get("text") or "")
+        if not text.strip():
+            continue
+
+        doc = nlp(text)
+        for sent in getattr(doc, "sents", []):
+            sentence = str(getattr(sent, "text", "") or "").strip()
+            if not sentence:
+                continue
+
+            for token in sent:
+                token_text = str(getattr(token, "text", "") or "")
+                if not token_text:
+                    continue
+                token_key = token_text.casefold()
+                spec = _HETERONYM_SPECS.get(token_key)
+                if not spec:
+                    continue
+
+                dedupe_key = (token_key, sentence)
+                if dedupe_key in seen:
+                    continue
+                seen.add(dedupe_key)
+
+                entry_id = _hash_id(token_key, sentence)
+                default_choice = spec.default_choice_for_token(token)
+                choice = previous_choices.get(entry_id, default_choice)
+
+                options: List[Dict[str, Any]] = []
+                for variant in spec.variants:
+                    replacement_sentence = _build_replacement_sentence(
+                        sentence,
+                        token=spec.token,
+                        replacement_token=variant.replacement_token,
+                    )
+                    options.append(
+                        {
+                            "key": variant.key,
+                            "label": variant.label,
+                            "replacement_token": variant.replacement_token,
+                            "replacement_sentence": replacement_sentence,
+                            "example_sentence": variant.example_sentence,
+                        }
+                    )
+
+                results.append(
+                    {
+                        "id": entry_id,
+                        "token": token_text,
+                        "token_lower": token_key,
+                        "sentence": sentence,
+                        "options": options,
+                        "default_choice": default_choice,
+                        "choice": choice,
+                    }
+                )
+
+    return results

abogen/hf_tracker.py

@@ -0,0 +1,45 @@
+log_callback = None
+show_warning_signal_emitter = None  # Renamed for clarity
+
+
+def set_log_callback(cb):
+    global log_callback
+    log_callback = cb
+
+
+def set_show_warning_signal_emitter(emitter):  # Renamed for clarity
+    global show_warning_signal_emitter
+    show_warning_signal_emitter = emitter
+
+
+from huggingface_hub import hf_hub_download
+
+
+def tracked_hf_hub_download(*args, **kwargs):
+    try:
+        local_kwargs = dict(kwargs)
+        local_kwargs["local_files_only"] = True
+        hf_hub_download(*args, **local_kwargs)
+    except Exception:
+        repo_id = kwargs.get("repo_id", "<unknown repo>")
+        filename = kwargs.get("filename", "<unknown file>")
+        if filename.endswith(".pth"):
+            msg = f"\nDownloading model '{filename}' from Hugging Face ({repo_id}). This may take a while. Please wait..."
+            if show_warning_signal_emitter:  # Check if the emitter is set
+                show_warning_signal_emitter.emit(
+                    "Downloading Model",
+                    f"Downloading model '{filename}' from Hugging Face repository '{repo_id}'. This may take a while, please wait.",
+                )
+        else:
+            msg = f"\nDownloading '{filename}' from Hugging Face ({repo_id}). Please wait..."
+        if log_callback:
+            print(msg, flush=True)
+            log_callback(msg)
+        else:
+            print(msg, flush=True)
+    return hf_hub_download(*args, **kwargs)
+
+
+import huggingface_hub
+
+huggingface_hub.hf_hub_download = tracked_hf_hub_download

abogen/integrations/__init__.py

@@ -0,0 +1 @@
+"""Integration clients for external services."""

abogen/integrations/audiobookshelf.py

@@ -0,0 +1,680 @@
+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
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class AudiobookshelfUploadError(RuntimeError):
+    """Raised when an upload to Audiobookshelf fails."""
+
+
+@dataclass(frozen=True)
+class AudiobookshelfConfig:
+    base_url: str
+    api_token: str
+    library_id: Optional[str] = None
+    collection_id: Optional[str] = None
+    folder_id: Optional[str] = None
+    verify_ssl: bool = True
+    send_cover: bool = True
+    send_chapters: bool = True
+    send_subtitles: bool = True
+    timeout: float = 3600.0
+
+    def normalized_base_url(self) -> str:
+        base = (self.base_url or "").strip()
+        if not base:
+            raise ValueError("Audiobookshelf base URL is required")
+        normalized = base.rstrip("/")
+        # The web UI historically suggested including '/api' in the base URL; trim
+        # it here so we can safely append `/api/...` endpoints below.
+        if normalized.lower().endswith("/api"):
+            normalized = normalized[:-4]
+        return normalized or base
+
+
+class AudiobookshelfClient:
+    """Client for the legacy Audiobookshelf multipart upload endpoint."""
+
+    def __init__(self, config: AudiobookshelfConfig) -> None:
+        if not config.api_token:
+            raise ValueError("Audiobookshelf API token is required")
+        # library_id is now optional for discovery
+        self._config = config
+        normalized = config.normalized_base_url() or ""
+        self._base_url = normalized.rstrip("/") or normalized
+        self._client_base_url = f"{self._base_url}/"
+        self._folder_cache: Optional[Tuple[str, str, str]] = None
+
+    def get_libraries(self) -> List[Dict[str, Any]]:
+        """Fetch all libraries from the Audiobookshelf server."""
+        route = self._api_path("libraries")
+        try:
+            with self._open_client() as client:
+                response = client.get(route)
+                response.raise_for_status()
+                data = response.json()
+                # data['libraries'] is a list of library objects
+                return data.get("libraries", [])
+        except httpx.HTTPError as exc:
+            raise AudiobookshelfUploadError(f"Failed to fetch libraries: {exc}") from exc
+
+    def _api_path(self, suffix: str = "") -> str:
+        """Join the API prefix with the provided suffix without losing proxies."""
+        clean_suffix = suffix.lstrip("/")
+        return f"api/{clean_suffix}" if clean_suffix else "api"
+
+    def upload_audiobook(
+        self,
+        audio_path: Path,
+        *,
+        metadata: Dict[str, Any],
+        cover_path: Optional[Path] = None,
+        chapters: Optional[Iterable[Dict[str, Any]]] = None,
+        subtitles: Optional[Iterable[Path]] = None,
+    ) -> Dict[str, Any]:
+        if not audio_path.exists():
+            raise AudiobookshelfUploadError(f"Audio path does not exist: {audio_path}")
+
+        form_fields = self._build_upload_fields(audio_path, metadata, chapters)
+        file_entries = self._build_file_entries(audio_path, cover_path, subtitles)
+
+        route = self._api_path("upload")
+        try:
+            with self._open_client() as client, ExitStack() as stack:
+                files_payload = self._open_file_handles(file_entries, stack)
+                response = client.post(route, data=form_fields, files=files_payload)
+                response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            detail = (exc.response.text or "").strip()
+            if detail:
+                detail = detail[:200]
+                message = f"Audiobookshelf upload failed with status {status}: {detail}"
+            else:
+                message = f"Audiobookshelf upload failed with status {status}"
+            raise AudiobookshelfUploadError(
+                message
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise AudiobookshelfUploadError(f"Audiobookshelf upload failed: {exc}") from exc
+
+        return {}
+
+    def _open_client(self) -> httpx.Client:
+        headers = {
+            "Authorization": f"Bearer {self._config.api_token}",
+            "Accept": "application/json",
+        }
+        return httpx.Client(
+            base_url=self._client_base_url,
+            headers=headers,
+            timeout=self._config.timeout,
+            verify=self._config.verify_ssl,
+        )
+
+    def _build_upload_fields(
+        self,
+        audio_path: Path,
+        metadata: Dict[str, Any],
+        chapters: Optional[Iterable[Dict[str, Any]]],
+    ) -> Dict[str, str]:
+        folder_id, _, _ = self._ensure_folder()
+        title = self._extract_title(metadata, audio_path)
+        author = self._extract_author(metadata)
+        series = self._extract_series(metadata)
+        series_sequence = self._extract_series_sequence(metadata)
+
+        fields: Dict[str, str] = {
+            "library": self._config.library_id,
+            "folder": folder_id,
+            "title": title,
+        }
+        if author:
+            fields["author"] = author
+        if series:
+            fields["series"] = series
+        if series_sequence:
+            fields["seriesSequence"] = series_sequence
+        if self._config.collection_id:
+            fields["collectionId"] = self._config.collection_id
+
+        metadata_payload: Dict[str, Any] = metadata or {}
+        if chapters and self._config.send_chapters:
+            metadata_payload = dict(metadata_payload)
+            metadata_payload["chapters"] = list(chapters)
+
+        if metadata_payload:
+            # Ensure authors is a list of strings in the JSON payload if it exists
+            if "authors" in metadata_payload:
+                authors_val = metadata_payload["authors"]
+                if isinstance(authors_val, str):
+                    metadata_payload["authors"] = [a.strip() for a in authors_val.split(",") if a.strip()]
+                elif isinstance(authors_val, list):
+                    metadata_payload["authors"] = [str(a).strip() for a in authors_val if str(a).strip()]
+
+            try:
+                fields["metadata"] = json.dumps(metadata_payload, ensure_ascii=False)
+            except (TypeError, ValueError):
+                logger.debug("Failed to serialize Audiobookshelf metadata payload")
+
+        return fields
+
+    def _build_file_entries(
+        self,
+        audio_path: Path,
+        cover_path: Optional[Path],
+        subtitles: Optional[Iterable[Path]],
+    ) -> List[Tuple[str, Path]]:
+        entries: List[Tuple[str, Path]] = [("file0", audio_path)]
+        index = 1
+
+        if cover_path and self._config.send_cover and cover_path.exists():
+            entries.append((f"file{index}", cover_path))
+            index += 1
+
+        if subtitles and self._config.send_subtitles:
+            for subtitle in subtitles:
+                if subtitle.exists():
+                    entries.append((f"file{index}", subtitle))
+                    index += 1
+
+        return entries
+
+    def _open_file_handles(
+        self,
+        entries: Sequence[Tuple[str, Path]],
+        stack: ExitStack,
+    ) -> List[Tuple[str, Tuple[str, Any, str]]]:
+        files: List[Tuple[str, Tuple[str, Any, str]]] = []
+        for field_name, path in entries:
+            mime_type, _ = mimetypes.guess_type(path.name)
+            mime_type = mime_type or "application/octet-stream"
+            handle = stack.enter_context(path.open("rb"))
+            files.append((field_name, (path.name, handle, mime_type)))
+        return files
+
+    def find_existing_items(
+        self,
+        title: str,
+        *,
+        folder_id: Optional[str] = None,
+    ) -> List[Mapping[str, Any]]:
+        normalized_title = self._normalize_title_value(title)
+        if not normalized_title:
+            return []
+
+        folder_hint = folder_id or self._config.folder_id
+        target_folders = set()
+        if folder_hint:
+            folder_token = str(folder_hint).strip().lower()
+            if folder_token:
+                target_folders.add(folder_token)
+
+        requests = self._candidate_search_requests(title, folder_hint)
+        if not requests:
+            return []
+
+        matches: List[Mapping[str, Any]] = []
+
+        try:
+            with self._open_client() as client:
+                for route, params in requests:
+                    try:
+                        response = client.get(route, params=params)
+                    except httpx.HTTPError as exc:
+                        logger.debug("Audiobookshelf lookup failed for %s: %s", route, exc)
+                        continue
+
+                    if response.status_code == 404:
+                        continue
+
+                    try:
+                        response.raise_for_status()
+                    except httpx.HTTPStatusError as exc:
+                        status = exc.response.status_code
+                        if status in {401, 403}:
+                            raise AudiobookshelfUploadError(
+                                "Audiobookshelf authentication failed while checking for existing items."
+                            ) from exc
+                        logger.debug("Audiobookshelf lookup error %s for %s", status, route)
+                        continue
+
+                    try:
+                        payload = response.json()
+                    except ValueError:
+                        continue
+
+                    candidates = self._extract_candidate_items(payload)
+                    for item in candidates:
+                        item_title = self._normalize_item_title(item)
+                        if not item_title or item_title != normalized_title:
+                            continue
+                        if target_folders:
+                            item_folder = self._normalize_folder_id(item)
+                            if item_folder and item_folder not in target_folders:
+                                continue
+                        matches.append(item)
+                    if matches:
+                        break
+        except AudiobookshelfUploadError:
+            raise
+        except Exception:
+            logger.debug(
+                "Unexpected error while checking Audiobookshelf for existing items",
+                exc_info=True,
+            )
+
+        return matches
+
+    def delete_items(self, items: Iterable[Mapping[str, Any] | str]) -> None:
+        to_delete: List[str] = []
+        for entry in items:
+            if isinstance(entry, Mapping):
+                item_id = self._extract_item_id(entry)
+            else:
+                item_id = str(entry).strip()
+            if item_id:
+                to_delete.append(item_id)
+
+        if not to_delete:
+            return
+
+        with self._open_client() as client:
+            for item_id in to_delete:
+                self._delete_single_item(client, item_id)
+
+    def _candidate_search_requests(
+        self,
+        title: str,
+        folder_id: Optional[str],
+    ) -> List[Tuple[str, Dict[str, Any]]]:
+        query = (title or "").strip()
+        if not query:
+            return []
+
+        library_id = self._config.library_id
+        folder_token = (folder_id or self._config.folder_id or "").strip()
+
+        requests: List[Tuple[str, Dict[str, Any]]] = []
+        seen_routes: set[str] = set()
+
+        def _append(route: str, params: Dict[str, Any]) -> None:
+            if route in seen_routes:
+                return
+            seen_routes.add(route)
+            requests.append((route, params))
+
+        if folder_token:
+            _append(
+                self._api_path(f"folders/{folder_token}/items"),
+                {"library": library_id, "search": query},
+            )
+
+        _append(self._api_path(f"libraries/{library_id}/items"), {"search": query})
+        _append(self._api_path("items"), {"library": library_id, "search": query})
+        _append(
+            self._api_path("search"),
+            {"query": query, "library": library_id, "media": "audiobook"},
+        )
+
+        return requests
+
+    def _delete_single_item(self, client: httpx.Client, item_id: str) -> None:
+        routes = [
+            self._api_path(f"items/{item_id}"),
+            self._api_path(f"libraries/{self._config.library_id}/items/{item_id}"),
+        ]
+
+        for route in routes:
+            try:
+                response = client.delete(route)
+            except httpx.HTTPError as exc:
+                logger.debug("Audiobookshelf delete failed for %s: %s", route, exc)
+                continue
+
+            if response.status_code in (200, 202, 204):
+                return
+            if response.status_code == 404:
+                continue
+
+            try:
+                response.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                raise AudiobookshelfUploadError(
+                    f"Failed to delete Audiobookshelf item '{item_id}': {exc}"
+                ) from exc
+
+        logger.debug("Audiobookshelf item %s could not be confirmed deleted", item_id)
+
+    def resolve_folder(self) -> Tuple[str, str, str]:
+        """Return the resolved folder (id, name, library name)."""
+        return self._ensure_folder()
+
+    def list_folders(self) -> List[Dict[str, str]]:
+        """Return all folders for the configured library."""
+        library_name, folders = self._load_library_metadata()
+        results: List[Dict[str, str]] = []
+        for folder in folders:
+            folder_id = str(folder.get("id") or "").strip()
+            if not folder_id:
+                continue
+            name = self._folder_display_name(folder)
+            path = self._select_folder_path(folder)
+            results.append(
+                {
+                    "id": folder_id,
+                    "name": name,
+                    "path": path,
+                    "library": library_name,
+                }
+            )
+        results.sort(key=lambda entry: (entry.get("path") or entry.get("name") or entry.get("id") or "").lower())
+        return results
+
+    def _ensure_folder(self) -> Tuple[str, str, str]:
+        if self._folder_cache:
+            return self._folder_cache
+
+        identifier = (self._config.folder_id or "").strip()
+        if not identifier:
+            raise AudiobookshelfUploadError(
+                "Audiobookshelf folder is required; enter the folder name or ID in Settings."
+            )
+
+        identifier_norm = self._normalize_identifier(identifier)
+        library_name, folders = self._load_library_metadata()
+
+        # direct ID match
+        for folder in folders:
+            folder_id = str(folder.get("id") or "").strip()
+            if folder_id and folder_id == identifier:
+                folder_name = self._folder_display_name(folder) or folder_id
+                self._folder_cache = (folder_id, folder_name, library_name)
+                return self._folder_cache
+
+        has_path_component = "/" in identifier_norm
+
+        for folder in folders:
+            folder_id = str(folder.get("id") or "").strip()
+            if not folder_id:
+                continue
+            folder_name = self._folder_display_name(folder)
+            name_norm = self._normalize_identifier(folder_name)
+            if name_norm and name_norm == identifier_norm:
+                self._folder_cache = (folder_id, folder_name or folder_id, library_name)
+                return self._folder_cache
+
+            for candidate in self._folder_path_candidates(folder):
+                candidate_norm = self._normalize_identifier(candidate)
+                if not candidate_norm:
+                    continue
+                if candidate_norm == identifier_norm:
+                    self._folder_cache = (folder_id, folder_name or folder_id, library_name)
+                    return self._folder_cache
+                if has_path_component and candidate_norm.endswith(identifier_norm):
+                    self._folder_cache = (folder_id, folder_name or folder_id, library_name)
+                    return self._folder_cache
+                if not has_path_component:
+                    tail = candidate_norm.split("/")[-1]
+                    if tail and tail == identifier_norm:
+                        self._folder_cache = (folder_id, folder_name or folder_id, library_name)
+                        return self._folder_cache
+
+        raise AudiobookshelfUploadError(
+            f"Folder '{identifier}' was not found in library '{library_name}'. "
+            "Enter the folder name exactly as it appears in Audiobookshelf, a trailing path segment, or paste the folder ID."
+        )
+
+    def _load_library_metadata(self) -> Tuple[str, List[Mapping[str, Any]]]:
+        try:
+            with self._open_client() as client:
+                response = client.get(self._api_path(f"libraries/{self._config.library_id}"))
+                response.raise_for_status()
+                payload = response.json()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 404:
+                message = f"Audiobookshelf library '{self._config.library_id}' not found."
+            else:
+                detail = (exc.response.text or "").strip()
+                if detail:
+                    detail = detail[:200]
+                    message = (
+                        f"Failed to load Audiobookshelf library '{self._config.library_id}' "
+                        f"(status {status}): {detail}"
+                    )
+                else:
+                    message = (
+                        f"Failed to load Audiobookshelf library '{self._config.library_id}' "
+                        f"(status {status})."
+                    )
+            raise AudiobookshelfUploadError(message) from exc
+        except httpx.HTTPError as exc:
+            raise AudiobookshelfUploadError(
+                f"Failed to reach Audiobookshelf library '{self._config.library_id}': {exc}"
+            ) from exc
+
+        if not isinstance(payload, Mapping):
+            return self._config.library_id, []
+
+        library_name = str(payload.get("name") or payload.get("label") or self._config.library_id)
+        raw_folders = payload.get("libraryFolders") or payload.get("folders") or []
+        folders = [entry for entry in raw_folders if isinstance(entry, Mapping)]
+        return library_name, folders
+
+    @staticmethod
+    def _folder_path_candidates(folder: Mapping[str, Any]) -> List[str]:
+        candidates: List[str] = []
+        for key in ("fullPath", "fullpath", "path", "folderPath", "virtualPath"):
+            value = folder.get(key)
+            if isinstance(value, str) and value.strip():
+                candidates.append(value)
+        return candidates
+
+    @staticmethod
+    def _folder_display_name(folder: Mapping[str, Any]) -> str:
+        name = str(folder.get("name") or folder.get("label") or "").strip()
+        if name:
+            return name
+        path = AudiobookshelfClient._select_folder_path(folder)
+        if path:
+            tail = path.strip("/ ")
+            tail = tail.split("/")[-1] if tail else ""
+            if tail:
+                return tail
+        return str(folder.get("id") or "").strip()
+
+    @staticmethod
+    def _select_folder_path(folder: Mapping[str, Any]) -> str:
+        for candidate in AudiobookshelfClient._folder_path_candidates(folder):
+            normalized = candidate.replace("\\", "/").strip()
+            if normalized:
+                return normalized
+        return ""
+
+    @staticmethod
+    def _normalize_identifier(value: str) -> str:
+        token = (value or "").strip()
+        token = token.replace("\\", "/")
+        if len(token) > 1 and token[1] == ":":
+            token = token[2:]
+        token = token.strip("/ ")
+        return token.lower()
+
+    @staticmethod
+    def _normalize_title_value(value: Optional[str]) -> str:
+        if not isinstance(value, str):
+            return ""
+        normalized = re.sub(r"\s+", " ", value).strip()
+        return normalized.casefold() if normalized else ""
+
+    @staticmethod
+    def _normalize_item_title(item: Mapping[str, Any]) -> str:
+        if not isinstance(item, Mapping):
+            return ""
+        for key in ("title", "name", "label"):
+            candidate = item.get(key)
+            if isinstance(candidate, str) and candidate.strip():
+                return AudiobookshelfClient._normalize_title_value(candidate)
+        library_item = item.get("libraryItem")
+        if isinstance(library_item, Mapping):
+            return AudiobookshelfClient._normalize_item_title(library_item)
+        return ""
+
+    @staticmethod
+    def _normalize_folder_id(item: Mapping[str, Any]) -> Optional[str]:
+        if not isinstance(item, Mapping):
+            return None
+        for key in ("folderId", "libraryFolderId", "folder_id", "folder"):
+            value = item.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip().lower()
+            if isinstance(value, (int, float)):
+                return str(value).strip().lower()
+        library_item = item.get("libraryItem")
+        if isinstance(library_item, Mapping):
+            return AudiobookshelfClient._normalize_folder_id(library_item)
+        return None
+
+    @staticmethod
+    def _extract_item_id(item: Mapping[str, Any]) -> Optional[str]:
+        if not isinstance(item, Mapping):
+            return None
+        for key in ("id", "libraryItemId", "itemId"):
+            value = item.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+            if isinstance(value, (int, float)):
+                return str(value).strip()
+        library_item = item.get("libraryItem")
+        if isinstance(library_item, Mapping):
+            return AudiobookshelfClient._extract_item_id(library_item)
+        return None
+
+    @staticmethod
+    def _extract_candidate_items(payload: Any) -> List[Mapping[str, Any]]:
+        items: List[Mapping[str, Any]] = []
+        seen_ids: set[str] = set()
+        visited: set[int] = set()
+
+        def _visit(obj: Any) -> None:
+            if isinstance(obj, Mapping):
+                obj_id = id(obj)
+                if obj_id in visited:
+                    return
+                visited.add(obj_id)
+
+                title = AudiobookshelfClient._normalize_item_title(obj)
+                item_id = AudiobookshelfClient._extract_item_id(obj)
+                if title and item_id:
+                    key = item_id.strip().lower()
+                    if key not in seen_ids:
+                        seen_ids.add(key)
+                        items.append(obj)
+
+                for value in obj.values():
+                    _visit(value)
+
+            elif isinstance(obj, list):
+                for entry in obj:
+                    _visit(entry)
+
+        _visit(payload)
+        return items
+
+    @staticmethod
+    def _extract_title(metadata: Mapping[str, Any], audio_path: Path) -> str:
+        title = metadata.get("title") if isinstance(metadata, Mapping) else None
+        candidate = str(title).strip() if isinstance(title, str) else ""
+        if candidate:
+            return candidate
+        return audio_path.stem or audio_path.name
+
+    @staticmethod
+    def _extract_author(metadata: Mapping[str, Any]) -> str:
+        authors = metadata.get("authors") if isinstance(metadata, Mapping) else None
+        if isinstance(authors, str):
+            candidate = authors.strip()
+            return candidate
+        if isinstance(authors, Iterable) and not isinstance(authors, (str, Mapping)):
+            names = [str(entry).strip() for entry in authors if isinstance(entry, str) and entry.strip()]
+            if names:
+                # ABS expects a comma-separated string for multiple authors.
+                return ", ".join(names)
+        return ""
+
+    @staticmethod
+    def _extract_series(metadata: Mapping[str, Any]) -> str:
+        series_name = metadata.get("seriesName") if isinstance(metadata, Mapping) else None
+        if isinstance(series_name, str) and series_name.strip():
+            return series_name.strip()
+        return ""
+
+    @staticmethod
+    def _extract_series_sequence(metadata: Mapping[str, Any]) -> str:
+        if not isinstance(metadata, Mapping):
+            return ""
+
+        preferred_keys = (
+            "seriesSequence",
+            "series_sequence",
+            "seriesIndex",
+            "series_index",
+            "seriesNumber",
+            "series_number",
+            "bookNumber",
+            "book_number",
+        )
+
+        for key in preferred_keys:
+            if key not in metadata:
+                continue
+            normalized = AudiobookshelfClient._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/is_nvidia.py

@@ -0,0 +1,22 @@
+import gpustat
+
+
+def check():
+    try:
+        stats = gpustat.new_query()
+    except Exception:
+        return False
+
+    nvidia_keywords = ["nvidia", "rtx", "gtx", "quadro", "tesla", "titan", "mx"]
+    for gpu in stats.gpus:
+        name = gpu.name.lower()
+        if any(keyword in name for keyword in nvidia_keywords):
+            return True
+    return False
+
+
+if __name__ == "__main__":
+    stats = gpustat.new_query()
+    for gpu in stats.gpus:
+        print(gpu.name)
+    print(check())

abogen/llm_client.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
+from urllib import error, parse, request
+
+
+class LLMClientError(RuntimeError):
+    """Raised when an LLM request fails."""
+
+
+@dataclass(frozen=True)
+class LLMConfiguration:
+    base_url: str
+    api_key: str
+    model: str
+    timeout: float = 30.0
+
+    def is_configured(self) -> bool:
+        return bool(self.base_url.strip() and self.model.strip())
+
+
+@dataclass(frozen=True)
+class LLMToolCall:
+    name: str
+    arguments: str
+
+
+@dataclass(frozen=True)
+class LLMCompletion:
+    content: Optional[str]
+    tool_calls: Tuple[LLMToolCall, ...]
+
+
+_DEFAULT_HEADERS = {
+    "Content-Type": "application/json",
+    "Accept": "application/json",
+}
+
+
+def _normalized_base_url(base_url: str) -> str:
+    trimmed = (base_url or "").strip()
+    if not trimmed:
+        raise LLMClientError("LLM base URL is required")
+    if not trimmed.endswith("/"):
+        trimmed += "/"
+    return trimmed
+
+
+def _build_url(base_url: str, path: str) -> str:
+    normalized = _normalized_base_url(base_url)
+    trimmed_path = path.lstrip("/")
+    parsed = parse.urlparse(normalized)
+    if parsed.path.rstrip("/").lower().endswith("/v1") and trimmed_path.startswith(
+        "v1/"
+    ):
+        trimmed_path = trimmed_path[len("v1/") :]
+    return parse.urljoin(normalized, trimmed_path)
+
+
+def _build_headers(api_key: str) -> Dict[str, str]:
+    headers = dict(_DEFAULT_HEADERS)
+    token = (api_key or "").strip()
+    if token and token.lower() != "ollama":
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def _perform_request(
+    method: str,
+    url: str,
+    *,
+    headers: Optional[Mapping[str, str]] = None,
+    payload: Optional[Mapping[str, Any]] = None,
+    timeout: float = 30.0,
+) -> Any:
+    data_bytes: Optional[bytes] = None
+    if payload is not None:
+        data_bytes = json.dumps(payload).encode("utf-8")
+    request_headers = dict(headers or {})
+    req = request.Request(
+        url, data=data_bytes, headers=request_headers, method=method.upper()
+    )
+    try:
+        with request.urlopen(req, timeout=timeout) as response:
+            body = response.read()
+    except error.HTTPError as exc:  # pragma: no cover - defensive network guard
+        message = exc.read().decode("utf-8", "ignore") if exc.fp else exc.reason
+        raise LLMClientError(f"LLM request failed ({exc.code}): {message}") from exc
+    except error.URLError as exc:  # pragma: no cover - defensive network guard
+        raise LLMClientError(f"LLM request failed: {exc.reason}") from exc
+    except Exception as exc:  # pragma: no cover - defensive network guard
+        raise LLMClientError("LLM request failed") from exc
+
+    if not body:
+        return None
+    try:
+        return json.loads(body.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise LLMClientError("LLM response was not valid JSON") from exc
+
+
+def list_models(configuration: LLMConfiguration) -> List[Dict[str, str]]:
+    if not configuration.is_configured() and not configuration.base_url.strip():
+        raise LLMClientError("LLM configuration is incomplete")
+    url = _build_url(configuration.base_url, "v1/models")
+    headers = _build_headers(configuration.api_key)
+    payload = _perform_request(
+        "GET", url, headers=headers, timeout=configuration.timeout
+    )
+    if not isinstance(payload, Mapping):
+        raise LLMClientError("Unexpected response when listing models")
+    data = payload.get("data")
+    if not isinstance(data, list):
+        return []
+    models: List[Dict[str, str]] = []
+    for entry in data:
+        if not isinstance(entry, Mapping):
+            continue
+        identifier = str(entry.get("id") or "").strip()
+        if not identifier:
+            continue
+        description = str(entry.get("name") or entry.get("description") or identifier)
+        models.append({"id": identifier, "label": description})
+    return models
+
+
+def generate_completion(
+    configuration: LLMConfiguration,
+    *,
+    system_message: str,
+    user_message: str,
+    temperature: float = 0.2,
+    max_tokens: Optional[int] = None,
+    tools: Optional[Sequence[Mapping[str, Any]]] = None,
+    tool_choice: Optional[Mapping[str, Any]] = None,
+    response_format: Optional[Mapping[str, Any]] = None,
+) -> LLMCompletion:
+    if not configuration.is_configured():
+        raise LLMClientError("LLM configuration is incomplete")
+
+    url = _build_url(configuration.base_url, "v1/chat/completions")
+    headers = _build_headers(configuration.api_key)
+    payload: Dict[str, Any] = {
+        "model": configuration.model,
+        "messages": [
+            {"role": "system", "content": system_message},
+            {"role": "user", "content": user_message},
+        ],
+        "temperature": temperature,
+    }
+    if max_tokens is not None:
+        payload["max_tokens"] = max_tokens
+    if tools:
+        payload["tools"] = list(tools)
+    if tool_choice:
+        payload["tool_choice"] = dict(tool_choice)
+    if response_format:
+        payload["response_format"] = dict(response_format)
+
+    response = _perform_request(
+        "POST", url, headers=headers, payload=payload, timeout=configuration.timeout
+    )
+    if not isinstance(response, Mapping):
+        raise LLMClientError("Unexpected response from LLM")
+    choices = response.get("choices")
+    if not isinstance(choices, list) or not choices:
+        raise LLMClientError("LLM response did not include choices")
+    first = choices[0]
+    if not isinstance(first, Mapping):
+        raise LLMClientError("LLM response choice was invalid")
+    message = first.get("message")
+    content: Optional[str] = None
+    tool_calls: List[LLMToolCall] = []
+    if isinstance(message, Mapping):
+        content = message.get("content")
+        if isinstance(content, str):
+            stripped = content.strip()
+            if stripped:
+                content = stripped
+            else:
+                content = None
+        tool_call_entries = message.get("tool_calls")
+        if isinstance(tool_call_entries, list):
+            for entry in tool_call_entries:
+                if not isinstance(entry, Mapping):
+                    continue
+                fn = entry.get("function")
+                if not isinstance(fn, Mapping):
+                    continue
+                name = str(fn.get("name") or "").strip()
+                if not name:
+                    continue
+                args = fn.get("arguments", "")
+                if isinstance(args, (dict, list)):
+                    arguments = json.dumps(args)
+                else:
+                    arguments = str(args)
+                tool_calls.append(LLMToolCall(name=name, arguments=arguments))
+    if content:
+        return LLMCompletion(content=content, tool_calls=tuple(tool_calls))
+    text = first.get("text")
+    if isinstance(text, str):
+        stripped = text.strip()
+        if stripped:
+            content = stripped
+    if content or tool_calls:
+        return LLMCompletion(content=content, tool_calls=tuple(tool_calls))
+    raise LLMClientError("LLM response did not include text content")

abogen/main.py

@@ -1,57 +1,49 @@
+"""Backwards-compatible entry point that now launches the web UI."""
+
+from __future__ import annotations
+
+import atexit
 import os
-import sys
 import platform
-from PyQt5.QtWidgets import QApplication
-from PyQt5.QtGui import QIcon
+import signal
+import sys
 
-# Add the directory to Python path
-sys.path.insert(0, os.path.join(os.path.dirname(__file__)))
-from gui import abogen
-from utils import get_resource_path
-from constants import PROGRAM_NAME, VERSION
+from abogen.utils import load_config, prevent_sleep_end
+from abogen.webui.app import main as _run_web_ui
 
-# 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")
+# Configure Hugging Face Hub behaviour (mirrors legacy GUI defaults).
+os.environ.setdefault("HF_HUB_DISABLE_TELEMETRY", "1")
+os.environ.setdefault("HF_HUB_ETAG_TIMEOUT", "10")
+os.environ.setdefault("HF_HUB_DOWNLOAD_TIMEOUT", "10")
+os.environ.setdefault("HF_HUB_DISABLE_SYMLINKS_WARNING", "1")
+if load_config().get("disable_kokoro_internet", False):
+    os.environ["HF_HUB_OFFLINE"] = "1"
 
-# Enable MPS GPU acceleration on Mac Apple Silicon
+# Prefer faster ROCm tuning defaults when available.
+os.environ.setdefault("MIOPEN_FIND_MODE", "FAST")
+os.environ.setdefault("MIOPEN_CONV_PRECISE_ROCM_TUNING", "0")
+
+# Enable MPS GPU acceleration on Apple Silicon.
 if platform.system() == "Darwin" and platform.processor() == "arm":
-    os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"
+    os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")
 
-# Set application ID for Windows taskbar icon
-if platform.system() == "Windows":
-    import ctypes
-
-    app_id = f"{PROGRAM_NAME}.{VERSION}"
-    ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID(app_id)
-
-# Handle Wayland on Linux GNOME
-if platform.system() == "Linux":
-    xdg_session = os.environ.get("XDG_SESSION_TYPE", "").lower()
-    desktop = os.environ.get("XDG_CURRENT_DESKTOP", "").lower()
-    if (
-        "gnome" in desktop
-        and xdg_session == "wayland"
-        and "QT_QPA_PLATFORM" not in os.environ
-    ):
-        os.environ["QT_QPA_PLATFORM"] = "wayland"
+atexit.register(prevent_sleep_end)
 
 
-def main():
-    """Main entry point for console usage."""
-    app = QApplication(sys.argv)
-
-    # Set application icon using get_resource_path from utils
-    icon_path = get_resource_path("abogen.assets", "icon.ico")
-    if icon_path:
-        app.setWindowIcon(QIcon(icon_path))
-
-    ex = abogen()
-    ex.show()
-    sys.exit(app.exec_())
+def _cleanup_sleep(signum, _frame):
+    prevent_sleep_end()
+    sys.exit(0)
 
 
-if __name__ == "__main__":
+signal.signal(signal.SIGINT, _cleanup_sleep)
+signal.signal(signal.SIGTERM, _cleanup_sleep)
+
+
+def main() -> None:
+    """Launch the Flask-based web UI."""
+
+    _run_web_ui()
+
+
+if __name__ == "__main__":  # pragma: no cover - manual execution hook
     main()

abogen/normalization_settings.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import os
+from dataclasses import replace
+from functools import lru_cache
+from typing import Any, Dict, Mapping, Optional
+
+from abogen.kokoro_text_normalization import (
+    ApostropheConfig,
+    CONTRACTION_CATEGORY_DEFAULTS,
+)
+from abogen.llm_client import LLMConfiguration
+from abogen.utils import load_config
+
+DEFAULT_LLM_PROMPT = (
+    "You are assisting with audiobook preparation. Analyze the sentence and identify any apostrophes or "
+    "contractions that should be expanded for clarity. Call the apply_regex_replacements tool with precise "
+    "regex substitutions for only the words that need adjustment. If no changes are required, return an empty list.\n"
+    "Sentence: {{ sentence }}"
+)
+
+_LEGACY_REWRITE_ONLY_PROMPT = (
+    "You are assisting with audiobook preparation. Rewrite the provided sentence so apostrophes and "
+    "contractions are unambiguous for text-to-speech. Respond with only the rewritten sentence.\n"
+    "Sentence: {{ sentence }}\n"
+    "Context: {{ paragraph }}"
+)
+
+_SETTINGS_DEFAULTS: Dict[str, Any] = {
+    "llm_base_url": "",
+    "llm_api_key": "",
+    "llm_model": "",
+    "llm_timeout": 30.0,
+    "llm_prompt": DEFAULT_LLM_PROMPT,
+    "llm_context_mode": "sentence",
+    "normalization_numbers": True,
+    "normalization_numbers_year_style": "american",
+    "normalization_currency": True,
+    "normalization_footnotes": True,
+    "normalization_titles": True,
+    "normalization_terminal": True,
+    "normalization_phoneme_hints": True,
+    "normalization_caps_quotes": True,
+    "normalization_internet_slang": False,
+    "normalization_apostrophes_contractions": True,
+    "normalization_apostrophes_plural_possessives": True,
+    "normalization_apostrophes_sibilant_possessives": True,
+    "normalization_apostrophes_decades": True,
+    "normalization_apostrophes_leading_elisions": True,
+    "normalization_apostrophe_mode": "spacy",
+    "normalization_contraction_aux_be": True,
+    "normalization_contraction_aux_have": True,
+    "normalization_contraction_modal_will": True,
+    "normalization_contraction_modal_would": True,
+    "normalization_contraction_negation_not": True,
+    "normalization_contraction_let_us": True,
+}
+
+_CONTRACTION_SETTING_MAP: Dict[str, str] = {
+    "normalization_contraction_aux_be": "contraction_aux_be",
+    "normalization_contraction_aux_have": "contraction_aux_have",
+    "normalization_contraction_modal_will": "contraction_modal_will",
+    "normalization_contraction_modal_would": "contraction_modal_would",
+    "normalization_contraction_negation_not": "contraction_negation_not",
+    "normalization_contraction_let_us": "contraction_let_us",
+}
+
+_ENVIRONMENT_KEYS: Dict[str, str] = {
+    "llm_base_url": "ABOGEN_LLM_BASE_URL",
+    "llm_api_key": "ABOGEN_LLM_API_KEY",
+    "llm_model": "ABOGEN_LLM_MODEL",
+    "llm_timeout": "ABOGEN_LLM_TIMEOUT",
+    "llm_prompt": "ABOGEN_LLM_PROMPT",
+    "llm_context_mode": "ABOGEN_LLM_CONTEXT_MODE",
+}
+
+NORMALIZATION_SAMPLE_TEXTS: Dict[str, str] = {
+    "apostrophes": "I've heard the captain'll arrive by dusk, but they'd said the same yesterday.",
+    "numbers": "The ledger listed 1,204 outstanding debts totaling $57,890.",
+    "titles": "Dr. Smith met Mr. O'Leary outside St. John's Church on Jan. 4th.",
+    "punctuation": "Meet me at the docks tonight We'll decide then",  # missing punctuation
+}
+
+
+@lru_cache(maxsize=1)
+def _environment_defaults() -> Dict[str, Any]:
+    overrides: Dict[str, Any] = {}
+    for key, env_var in _ENVIRONMENT_KEYS.items():
+        default = _SETTINGS_DEFAULTS.get(key)
+        if default is None:
+            continue
+        value = os.environ.get(env_var)
+        if value is None or value == "":
+            continue
+        if isinstance(default, bool):
+            overrides[key] = _coerce_bool(value, default)
+        elif isinstance(default, float):
+            overrides[key] = _coerce_float(value, float(default))
+        else:
+            overrides[key] = value
+    return overrides
+
+
+def environment_llm_defaults() -> Dict[str, Any]:
+    defaults = dict(_environment_defaults())
+    if defaults:
+        _apply_llm_migrations(defaults)
+    return defaults
+
+
+def _coerce_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"1", "true", "yes", "on"}:
+            return True
+        if lowered in {"0", "false", "no", "off"}:
+            return False
+    return default
+
+
+def _coerce_float(value: Any, default: float) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _apply_llm_migrations(settings: Dict[str, Any]) -> None:
+    prompt_value = str(settings.get("llm_prompt") or "")
+    if prompt_value.strip() == _LEGACY_REWRITE_ONLY_PROMPT.strip():
+        settings["llm_prompt"] = DEFAULT_LLM_PROMPT
+
+    context_mode = str(settings.get("llm_context_mode") or "").strip().lower()
+    if context_mode != "sentence":
+        settings["llm_context_mode"] = "sentence"
+
+
+def _extract_settings(source: Mapping[str, Any]) -> Dict[str, Any]:
+    env_defaults = _environment_defaults()
+    extracted: Dict[str, Any] = {}
+    for key, default in _SETTINGS_DEFAULTS.items():
+        if key in source:
+            raw_value = source.get(key)
+        elif key in env_defaults:
+            raw_value = env_defaults[key]
+        else:
+            raw_value = default
+        if isinstance(default, bool):
+            extracted[key] = _coerce_bool(raw_value, default)
+        elif isinstance(default, float):
+            extracted[key] = _coerce_float(raw_value, default)
+        else:
+            extracted[key] = (
+                str(raw_value or "") if isinstance(default, str) else raw_value
+            )
+    _apply_llm_migrations(extracted)
+    return extracted
+
+
+@lru_cache(maxsize=1)
+def _cached_settings() -> Dict[str, Any]:
+    config = load_config() or {}
+    return _extract_settings(config)
+
+
+def get_runtime_settings() -> Dict[str, Any]:
+    return dict(_cached_settings())
+
+
+def clear_cached_settings() -> None:
+    _cached_settings.cache_clear()
+
+
+def build_apostrophe_config(
+    *,
+    settings: Mapping[str, Any],
+    base: Optional[ApostropheConfig] = None,
+) -> ApostropheConfig:
+    config = replace(base or ApostropheConfig())
+    config.convert_numbers = bool(settings.get("normalization_numbers", True))
+    config.convert_currency = bool(settings.get("normalization_currency", True))
+    config.remove_footnotes = bool(settings.get("normalization_footnotes", True))
+    config.year_pronunciation_mode = (
+        str(settings.get("normalization_numbers_year_style", "american") or "")
+        .strip()
+        .lower()
+    )
+    config.add_phoneme_hints = bool(settings.get("normalization_phoneme_hints", True))
+    config.contraction_mode = (
+        "expand"
+        if settings.get("normalization_apostrophes_contractions", True)
+        else "keep"
+    )
+    config.plural_possessive_mode = (
+        "collapse"
+        if settings.get("normalization_apostrophes_plural_possessives", True)
+        else "keep"
+    )
+    config.sibilant_possessive_mode = (
+        "mark"
+        if settings.get("normalization_apostrophes_sibilant_possessives", True)
+        else "keep"
+    )
+    config.decades_mode = (
+        "expand" if settings.get("normalization_apostrophes_decades", True) else "keep"
+    )
+    config.leading_elision_mode = (
+        "expand"
+        if settings.get("normalization_apostrophes_leading_elisions", True)
+        else "keep"
+    )
+    config.ambiguous_past_modal_mode = (
+        "contextual" if config.contraction_mode == "expand" else "keep"
+    )
+    category_flags = dict(CONTRACTION_CATEGORY_DEFAULTS)
+    for setting_key, category in _CONTRACTION_SETTING_MAP.items():
+        default_value = bool(_SETTINGS_DEFAULTS.get(setting_key, True))
+        raw_value = settings.get(setting_key, default_value)
+        category_flags[category] = _coerce_bool(raw_value, default_value)
+    config.contraction_categories = category_flags
+    return config
+
+
+def build_llm_configuration(settings: Mapping[str, Any]) -> LLMConfiguration:
+    return LLMConfiguration(
+        base_url=str(settings.get("llm_base_url") or ""),
+        api_key=str(settings.get("llm_api_key") or ""),
+        model=str(settings.get("llm_model") or ""),
+        timeout=_coerce_float(
+            settings.get("llm_timeout"), float(_SETTINGS_DEFAULTS["llm_timeout"])
+        ),
+    )
+
+
+def apply_overrides(
+    base: Mapping[str, Any], overrides: Mapping[str, Any]
+) -> Dict[str, Any]:
+    merged: Dict[str, Any] = dict(base)
+    for key, value in overrides.items():
+        if key not in _SETTINGS_DEFAULTS:
+            continue
+        merged[key] = value
+    _apply_llm_migrations(merged)
+    return merged

abogen/predownload_gui.py

@@ -0,0 +1,590 @@
+"""
+Pre-download dialog and worker for Abogen
+
+This module consolidates pre-download logic for Kokoro voices and model
+and spaCy language models. The code favors clarity, avoids duplication,
+and handles optional dependencies gracefully.
+"""
+
+from typing import List, Optional, Tuple
+import importlib
+import importlib.util
+
+from PyQt6.QtWidgets import (
+    QDialog,
+    QVBoxLayout,
+    QHBoxLayout,
+    QLabel,
+    QPushButton,
+    QSpacerItem,
+    QSizePolicy,
+)
+from PyQt6.QtCore import QThread, pyqtSignal
+
+from abogen.constants import COLORS, VOICES_INTERNAL
+from abogen.spacy_utils import SPACY_MODELS
+import abogen.hf_tracker
+
+
+# Helpers
+def _unique_sorted_models() -> List[str]:
+    """Return a sorted list of unique spaCy model package names."""
+    return sorted(set(SPACY_MODELS.values()))
+
+
+def _is_package_installed(pkg_name: str) -> bool:
+    """Return True if a package with the given name can be imported (site-packages)."""
+    try:
+        return importlib.util.find_spec(pkg_name) is not None
+    except Exception:
+        return False
+
+
+# NOTE: explicit HF cache helper removed; we use try_to_load_from_cache in-scope where needed
+
+
+class PreDownloadWorker(QThread):
+    """Worker thread to download required models/voices.
+
+    Emits human-readable messages via `progress`. Uses `category_done` to indicate
+    a category (voices/model/spacy) finished successfully. Emits `error` on exception
+    and `finished` after all work completes.
+    """
+
+    # Emit (category, status, message)
+    progress = pyqtSignal(str, str, str)
+    category_done = pyqtSignal(str)
+    finished = pyqtSignal()
+    error = pyqtSignal(str)
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self._cancelled = False
+        # repo and filenames used for Kokoro model
+        self._repo_id = "hexgrad/Kokoro-82M"
+        self._model_files = ["kokoro-v1_0.pth", "config.json"]
+        # Track download success per category
+        self._voices_success = False
+        self._model_success = False
+        self._spacy_success = False
+        # Suppress HF tracker warnings during downloads
+        self._original_emitter = abogen.hf_tracker.show_warning_signal_emitter
+
+    def cancel(self) -> None:
+        self._cancelled = True
+
+    def run(self) -> None:
+        # Suppress HF tracker warnings during downloads
+        abogen.hf_tracker.show_warning_signal_emitter = None
+        try:
+            self._download_kokoro_voices()
+            if self._cancelled:
+                return
+            if self._voices_success:
+                self.category_done.emit("voices")
+
+            self._download_kokoro_model()
+            if self._cancelled:
+                return
+            if self._model_success:
+                self.category_done.emit("model")
+
+            self._download_spacy_models()
+            if self._cancelled:
+                return
+            if self._spacy_success:
+                self.category_done.emit("spacy")
+
+            self.finished.emit()
+        except Exception as exc:  # pragma: no cover - best-effort reporting
+            self.error.emit(str(exc))
+        finally:
+            # Restore original emitter
+            abogen.hf_tracker.show_warning_signal_emitter = self._original_emitter
+
+    # Kokoro voices
+    def _download_kokoro_voices(self) -> None:
+        self._voices_success = True
+        try:
+            from huggingface_hub import hf_hub_download, try_to_load_from_cache
+        except Exception:
+            self.progress.emit(
+                "voice", "warning", "huggingface_hub not installed, skipping voices..."
+            )
+            self._voices_success = False
+            return
+
+        voice_list = VOICES_INTERNAL
+        for idx, voice in enumerate(voice_list, start=1):
+            if self._cancelled:
+                self._voices_success = False
+                return
+            filename = f"voices/{voice}.pt"
+            if try_to_load_from_cache(repo_id=self._repo_id, filename=filename):
+                self.progress.emit(
+                    "voice",
+                    "installed",
+                    f"{idx}/{len(voice_list)}: {voice} already present",
+                )
+                continue
+            self.progress.emit(
+                "voice", "downloading", f"{idx}/{len(voice_list)}: {voice}..."
+            )
+            try:
+                hf_hub_download(repo_id=self._repo_id, filename=filename)
+                self.progress.emit("voice", "downloaded", f"{voice} downloaded")
+            except Exception as exc:
+                self.progress.emit(
+                    "voice", "warning", f"could not download {voice}: {exc}"
+                )
+                self._voices_success = False
+
+    # Kokoro model
+    def _download_kokoro_model(self) -> None:
+        self._model_success = True
+        try:
+            from huggingface_hub import hf_hub_download, try_to_load_from_cache
+        except Exception:
+            self.progress.emit(
+                "model", "warning", "huggingface_hub not installed, skipping model..."
+            )
+            self._model_success = False
+            return
+        for fname in self._model_files:
+            if self._cancelled:
+                self._model_success = False
+                return
+            category = "config" if fname == "config.json" else "model"
+            if try_to_load_from_cache(repo_id=self._repo_id, filename=fname):
+                self.progress.emit(
+                    category, "installed", f"file {fname} already present"
+                )
+                continue
+            self.progress.emit(category, "downloading", f"file {fname}...")
+            try:
+                hf_hub_download(repo_id=self._repo_id, filename=fname)
+                self.progress.emit(category, "downloaded", f"file {fname} downloaded")
+            except Exception as exc:
+                self.progress.emit(
+                    category, "warning", f"could not download file {fname}: {exc}"
+                )
+                self._model_success = False
+
+    # spaCy models
+    def _download_spacy_models(self) -> None:
+        """Download spaCy models. Prefer missing models provided by parent.
+
+        Parent dialog will populate _spacy_models_missing during checking.
+        """
+        self._spacy_success = True
+        # Determine which models to process: prefer parent-provided missing list to avoid
+        # re-checking everything; otherwise use the full unique list.
+        parent = self.parent()
+        models_to_process: List[str] = _unique_sorted_models()
+        try:
+            if (
+                parent is not None
+                and hasattr(parent, "_spacy_models_missing")
+                and parent._spacy_models_missing
+            ):
+                models_to_process = list(dict.fromkeys(parent._spacy_models_missing))
+        except Exception:
+            pass
+
+        # If spaCy is not available to run the CLI, skip gracefully
+        try:
+            import spacy.cli as _spacy_cli
+        except Exception:
+            self.progress.emit(
+                "spacy", "warning", "spaCy not available, skipping spaCy models..."
+            )
+            self._spacy_success = False
+            return
+
+        for idx, model_name in enumerate(models_to_process, start=1):
+            if self._cancelled:
+                self._spacy_success = False
+                return
+            if _is_package_installed(model_name):
+                self.progress.emit(
+                    "spacy",
+                    "installed",
+                    f"{idx}/{len(models_to_process)}: {model_name} already installed",
+                )
+                continue
+            self.progress.emit(
+                "spacy",
+                "downloading",
+                f"{idx}/{len(models_to_process)}: {model_name}...",
+            )
+            try:
+                _spacy_cli.download(model_name)
+                self.progress.emit("spacy", "downloaded", f"{model_name} downloaded")
+            except Exception as exc:
+                self.progress.emit(
+                    "spacy", "warning", f"could not download {model_name}: {exc}"
+                )
+                self._spacy_success = False
+
+
+class PreDownloadDialog(QDialog):
+    """Dialog to show and control pre-download process."""
+
+    VOICE_PREFIX = "Kokoro voices: "
+    MODEL_PREFIX = "Kokoro model: "
+    CONFIG_PREFIX = "Kokoro config: "
+    SPACY_PREFIX = "spaCy models: "
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self.setWindowTitle("Pre-download Models and Voices")
+        self.setMinimumWidth(500)
+        self.worker: Optional[PreDownloadWorker] = None
+        self.has_missing = False
+        self._spacy_models_checked: List[tuple] = []
+        self._spacy_models_missing: List[str] = []
+        self._status_worker = None
+
+        # Map keywords to (label, prefix) - labels filled after UI creation
+        self.status_map = {
+            "voice": (None, self.VOICE_PREFIX),
+            "spacy": (None, self.SPACY_PREFIX),
+            "model": (None, self.MODEL_PREFIX),
+            "config": (None, self.CONFIG_PREFIX),
+        }
+
+        self.category_map = {
+            "voices": ["voice"],
+            "model": ["model", "config"],
+            "spacy": ["spacy"],
+        }
+
+        self._setup_ui()
+        self._start_status_check()
+
+    def _setup_ui(self) -> None:
+        layout = QVBoxLayout(self)
+        layout.setSpacing(0)
+        layout.setContentsMargins(15, 0, 15, 15)
+
+        desc = QLabel(
+            "You can pre-download all required models and voices for offline use.\n"
+            "This includes Kokoro voices, Kokoro model (and config), and spaCy models."
+        )
+        desc.setWordWrap(True)
+        layout.addWidget(desc)
+
+        # Status rows
+        status_layout = QVBoxLayout()
+        status_title = QLabel("<b>Current Status:</b>")
+        status_layout.addWidget(status_title)
+
+        self.voices_status = QLabel(self.VOICE_PREFIX + "⏳ Checking...")
+        row = QHBoxLayout()
+        row.addWidget(self.voices_status)
+        row.addStretch()
+        status_layout.addLayout(row)
+
+        self.model_status = QLabel(self.MODEL_PREFIX + "⏳ Checking...")
+        row = QHBoxLayout()
+        row.addWidget(self.model_status)
+        row.addStretch()
+        status_layout.addLayout(row)
+
+        self.config_status = QLabel(self.CONFIG_PREFIX + "⏳ Checking...")
+        row = QHBoxLayout()
+        row.addWidget(self.config_status)
+        row.addStretch()
+        status_layout.addLayout(row)
+
+        self.spacy_status = QLabel(self.SPACY_PREFIX + "⏳ Checking...")
+        row = QHBoxLayout()
+        row.addWidget(self.spacy_status)
+        row.addStretch()
+        status_layout.addLayout(row)
+
+        # register labels
+        self.status_map["voice"] = (self.voices_status, self.VOICE_PREFIX)
+        self.status_map["model"] = (self.model_status, self.MODEL_PREFIX)
+        self.status_map["config"] = (self.config_status, self.CONFIG_PREFIX)
+        self.status_map["spacy"] = (self.spacy_status, self.SPACY_PREFIX)
+
+        layout.addLayout(status_layout)
+
+        layout.addItem(
+            QSpacerItem(0, 20, QSizePolicy.Policy.Minimum, QSizePolicy.Policy.Fixed)
+        )
+
+        # Buttons
+        button_row = QHBoxLayout()
+        button_row.setSpacing(10)
+        self.download_btn = QPushButton("Download all")
+        self.download_btn.setMinimumWidth(100)
+        self.download_btn.setMinimumHeight(35)
+        self.download_btn.setEnabled(False)
+        self.download_btn.clicked.connect(self._start_download)
+        button_row.addWidget(self.download_btn)
+
+        self.close_btn = QPushButton("Close")
+        self.close_btn.setMinimumWidth(100)
+        self.close_btn.setMinimumHeight(35)
+        self.close_btn.clicked.connect(self._handle_close)
+        button_row.addWidget(self.close_btn)
+
+        layout.addLayout(button_row)
+        self.adjustSize()
+
+    # Status checking worker
+    class StatusCheckWorker(QThread):
+        voices_checked = pyqtSignal(bool, list)
+        model_checked = pyqtSignal(bool)
+        config_checked = pyqtSignal(bool)
+        spacy_model_checking = pyqtSignal(str)
+        spacy_model_result = pyqtSignal(str, bool)
+        spacy_checked = pyqtSignal(bool, list)
+
+        def run(self):
+            parent = self.parent()
+            if parent is None:
+                return
+
+            voices_ok, missing_voices = parent._check_kokoro_voices()
+            self.voices_checked.emit(voices_ok, missing_voices)
+
+            model_ok = parent._check_kokoro_model()
+            self.model_checked.emit(model_ok)
+
+            config_ok = parent._check_kokoro_config()
+            self.config_checked.emit(config_ok)
+
+            # Check spaCy models by package name to detect site-package installs
+            unique = _unique_sorted_models()
+            missing: List[str] = []
+            for name in unique:
+                self.spacy_model_checking.emit(name)
+                ok = _is_package_installed(name)
+                self.spacy_model_result.emit(name, ok)
+                if not ok:
+                    missing.append(name)
+            parent._spacy_models_missing = missing
+            self.spacy_checked.emit(len(missing) == 0, missing)
+
+    def _start_status_check(self) -> None:
+        self._status_worker = self.StatusCheckWorker(self)
+        self._status_worker.voices_checked.connect(self._update_voices_status)
+        self._status_worker.model_checked.connect(self._update_model_status)
+        self._status_worker.config_checked.connect(self._update_config_status)
+        self._status_worker.spacy_model_checking.connect(self._spacy_model_checking)
+        self._status_worker.spacy_model_result.connect(self._spacy_model_result)
+        self._status_worker.spacy_checked.connect(self._update_spacy_status)
+
+        # These are initialized in __init__ to keep consistent object state
+
+        # Set checking visual state
+        for lbl in (
+            self.voices_status,
+            self.model_status,
+            self.config_status,
+            self.spacy_status,
+        ):
+            lbl.setStyleSheet(f"color: {COLORS['ORANGE']};")
+
+        self.spacy_status.setText(self.SPACY_PREFIX + "⏳ Checking...")
+        self._status_worker.start()
+
+    # UI update callbacks
+    def _spacy_model_checking(self, name: str) -> None:
+        self.spacy_status.setText(f"{self.SPACY_PREFIX}Checking {name}...")
+
+    def _spacy_model_result(self, name: str, ok: bool) -> None:
+        self._spacy_models_checked.append((name, ok))
+        if not ok and name not in self._spacy_models_missing:
+            self._spacy_models_missing.append(name)
+        checked = len(self._spacy_models_checked)
+        missing_count = len(self._spacy_models_missing)
+        if missing_count:
+            self.spacy_status.setText(
+                f"{self.SPACY_PREFIX}{checked} checked, {missing_count} missing..."
+            )
+        else:
+            self.spacy_status.setText(f"{self.SPACY_PREFIX}{checked} checked...")
+
+    def _update_voices_status(self, ok: bool, missing: List[str]) -> None:
+        if ok:
+            self._set_status("voice", "✓ Downloaded", COLORS["GREEN"])
+        else:
+            self.has_missing = True
+            if missing:
+                self._set_status(
+                    "voice", f"✗ Missing {len(missing)} voices", COLORS["RED"]
+                )
+            else:
+                self._set_status("voice", "✗ Not downloaded", COLORS["RED"])
+
+    def _update_model_status(self, ok: bool) -> None:
+        if ok:
+            self._set_status("model", "✓ Downloaded", COLORS["GREEN"])
+        else:
+            self.has_missing = True
+            self._set_status("model", "✗ Not downloaded", COLORS["RED"])
+
+    def _update_config_status(self, ok: bool) -> None:
+        if ok:
+            self._set_status("config", "✓ Downloaded", COLORS["GREEN"])
+        else:
+            self.has_missing = True
+            self._set_status("config", "✗ Not downloaded", COLORS["RED"])
+
+    def _update_spacy_status(self, ok: bool, missing: List[str]) -> None:
+        if ok:
+            self._set_status("spacy", "✓ Downloaded", COLORS["GREEN"])
+        else:
+            self.has_missing = True
+            if missing:
+                self._set_status(
+                    "spacy", f"✗ Missing {len(missing)} model(s)", COLORS["RED"]
+                )
+            else:
+                self._set_status("spacy", "✗ Not downloaded", COLORS["RED"])
+        self.download_btn.setEnabled(self.has_missing)
+
+    def _set_status(self, key: str, text: str, color: str) -> None:
+        lbl, prefix = self.status_map.get(key, (None, ""))
+        if not lbl:
+            return
+        lbl.setText(prefix + text)
+        lbl.setStyleSheet(f"color: {color};")
+
+    # Helper checks
+    def _check_kokoro_voices(self) -> Tuple[bool, List[str]]:
+        """Return (ok, missing_list) for Kokoro voices check."""
+        missing = []
+        try:
+            from huggingface_hub import try_to_load_from_cache
+
+            for voice in VOICES_INTERNAL:
+                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 (len(missing) == 0), missing
+
+    def _check_kokoro_model(self) -> bool:
+        try:
+            from huggingface_hub import try_to_load_from_cache
+
+            return (
+                try_to_load_from_cache(
+                    repo_id="hexgrad/Kokoro-82M", filename="kokoro-v1_0.pth"
+                )
+                is not None
+            )
+        except Exception:
+            return False
+
+    def _check_kokoro_config(self) -> bool:
+        try:
+            from huggingface_hub import try_to_load_from_cache
+
+            return (
+                try_to_load_from_cache(
+                    repo_id="hexgrad/Kokoro-82M", filename="config.json"
+                )
+                is not None
+            )
+        except Exception:
+            return False
+
+    def _check_spacy_models(self) -> bool:
+        unique = _unique_sorted_models()
+        missing = [m for m in unique if not _is_package_installed(m)]
+        self._spacy_models_missing = missing
+        return len(missing) == 0
+
+    # Download control
+    def _start_download(self) -> None:
+        self.download_btn.setEnabled(False)
+        self.download_btn.setText("Downloading...")
+        # mark the start of downloads; this triggers the labels
+        self._on_progress("system", "starting", "Processing, please wait...")
+        self.worker = PreDownloadWorker(self)
+        self.worker.progress.connect(self._on_progress)
+        self.worker.category_done.connect(self._on_category_done)
+        self.worker.finished.connect(self._on_download_finished)
+        self.worker.error.connect(self._on_download_error)
+        self.worker.start()
+
+    def _on_progress(self, category: str, status: str, message: str) -> None:
+        """Map worker (category, status, message) to UI label updates.
+
+        Status is one of: 'downloading', 'installed', 'downloaded', 'warning', 'starting'.
+        Category is one of: 'voice', 'model', 'spacy', 'config', or 'system'.
+        """
+        try:
+            # If the category targets a specific label, update directly
+            if category in self.status_map:
+                lbl, prefix = self.status_map[category]
+                if not lbl:
+                    return
+                # Compose message and set color based on status token
+                full_text = prefix + message
+                if len(full_text) > 60:
+                    display_text = full_text[:57] + "..."
+                    lbl.setText(display_text)
+                    lbl.setToolTip(full_text)
+                else:
+                    lbl.setText(full_text)
+                    lbl.setToolTip("")  # Clear tooltip if not needed
+                if status == "downloading":
+                    lbl.setStyleSheet(f"color: {COLORS['ORANGE']};")
+                elif status in ("installed", "downloaded"):
+                    lbl.setStyleSheet(f"color: {COLORS['GREEN']};")
+                elif status == "warning":
+                    lbl.setStyleSheet(f"color: {COLORS['RED']};")
+                elif status == "error":
+                    lbl.setStyleSheet(f"color: {COLORS['RED']};")
+                return
+
+            # System-level messages
+            if category == "system":
+                if status == "starting":
+                    for k in self.status_map:
+                        lbl, prefix = self.status_map[k]
+                        if lbl:
+                            lbl.setText(prefix + "Processing, please wait...")
+                            lbl.setStyleSheet(f"color: {COLORS['ORANGE']};")
+                # other system statuses don't require action
+                return
+        except Exception:
+            # Do not let UI thread crash on unexpected worker message
+            pass
+
+    def _on_category_done(self, category: str) -> None:
+        for key in self.category_map.get(category, []):
+            self._set_status(key, "✓ Downloaded", COLORS["GREEN"])
+
+    def _on_download_finished(self) -> None:
+        self.has_missing = False
+        self.download_btn.setText("Download all")
+        self.download_btn.setEnabled(False)
+
+    def _on_download_error(self, error_msg: str) -> None:
+        self.download_btn.setText("Download all")
+        self.download_btn.setEnabled(True)
+        for key in self.status_map:
+            self._set_status(key, f"✗ Error - {error_msg}", COLORS["RED"])
+
+    def _handle_close(self) -> None:
+        if self.worker and self.worker.isRunning():
+            self.worker.cancel()
+            self.worker.wait(2000)
+        self.accept()
+
+    def closeEvent(self, event) -> None:
+        if self.worker and self.worker.isRunning():
+            self.worker.cancel()
+            self.worker.wait(2000)
+        super().closeEvent(event)

abogen/pronunciation_store.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import shutil
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Mapping, Optional
+
+from .entity_analysis import normalize_token
+from .utils import get_internal_cache_path, get_user_settings_dir
+
+_DB_LOCK = threading.RLock()
+_SCHEMA_VERSION = 1
+
+
+def _store_path() -> Path:
+    try:
+        base_dir = Path(get_user_settings_dir())
+    except ModuleNotFoundError:
+        base_dir = Path(get_internal_cache_path("pronunciations"))
+    target = base_dir / "overrides.json"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    return target
+
+
+def _migrate_legacy_sqlite(target_json_path: Path) -> None:
+    try:
+        base_dir = Path(get_user_settings_dir())
+    except ModuleNotFoundError:
+        base_dir = Path(get_internal_cache_path("pronunciations"))
+
+    sqlite_path = base_dir / "pronunciations.db"
+    if not sqlite_path.exists():
+        return
+
+    try:
+        conn = sqlite3.connect(sqlite_path)
+        conn.row_factory = sqlite3.Row
+
+        # Check if table exists
+        cursor = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='overrides'"
+        )
+        if not cursor.fetchone():
+            conn.close()
+            return
+
+        cursor = conn.execute("SELECT * FROM overrides")
+        rows = cursor.fetchall()
+
+        data = {"version": _SCHEMA_VERSION, "overrides": {}}
+
+        for row in rows:
+            lang = row["language"]
+            if lang not in data["overrides"]:
+                data["overrides"][lang] = {}
+
+            entry = {
+                "id": str(row["id"]),
+                "normalized": row["normalized"],
+                "token": row["token"],
+                "language": row["language"],
+                "pronunciation": row["pronunciation"],
+                "voice": row["voice"],
+                "notes": row["notes"],
+                "context": row["context"],
+                "usage_count": row["usage_count"],
+                "created_at": row["created_at"],
+                "updated_at": row["updated_at"],
+            }
+            data["overrides"][lang][row["normalized"]] = entry
+
+        conn.close()
+
+        # Save to JSON
+        with open(target_json_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+        # Rename old DB
+        sqlite_path.rename(sqlite_path.with_suffix(".db.bak"))
+
+    except Exception:
+        pass
+
+
+def _load_db() -> Dict[str, Any]:
+    path = _store_path()
+    if not path.exists():
+        _migrate_legacy_sqlite(path)
+        if not path.exists():
+            return {"version": _SCHEMA_VERSION, "overrides": {}}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {"version": _SCHEMA_VERSION, "overrides": {}}
+
+
+def _save_db(data: Dict[str, Any]) -> None:
+    path = _store_path()
+    # Atomic write
+    temp_path = path.with_suffix(".tmp")
+    with open(temp_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+    shutil.move(str(temp_path), str(path))
+
+
+def load_overrides(language: str, tokens: Iterable[str]) -> Dict[str, Dict[str, Any]]:
+    normalized_tokens = {normalize_token(token) for token in tokens if token}
+    if not normalized_tokens:
+        return {}
+
+    with _DB_LOCK:
+        db = _load_db()
+        lang_overrides = db.get("overrides", {}).get(language, {})
+
+        results: Dict[str, Dict[str, Any]] = {}
+        for normalized in normalized_tokens:
+            if normalized in lang_overrides:
+                results[normalized] = lang_overrides[normalized]
+        return results
+
+
+def search_overrides(
+    language: str, query: str, *, limit: int = 15
+) -> List[Dict[str, Any]]:
+    if not query:
+        return []
+
+    query = query.lower()
+    with _DB_LOCK:
+        db = _load_db()
+        lang_overrides = db.get("overrides", {}).get(language, {})
+
+        matches = []
+        for entry in lang_overrides.values():
+            if query in entry["normalized"] or query in entry["token"].lower():
+                matches.append(entry)
+
+        # Sort by usage count desc, then updated_at desc
+        matches.sort(
+            key=lambda x: (x.get("usage_count", 0), x.get("updated_at", 0)),
+            reverse=True,
+        )
+        return matches[:limit]
+
+
+def save_override(
+    *,
+    language: str,
+    token: str,
+    pronunciation: Optional[str] = None,
+    voice: Optional[str] = None,
+    notes: Optional[str] = None,
+    context: Optional[str] = None,
+) -> Dict[str, Any]:
+    normalized = normalize_token(token)
+    if not normalized:
+        raise ValueError("Provide a token to override")
+
+    timestamp = time.time()
+    with _DB_LOCK:
+        db = _load_db()
+        overrides = db.setdefault("overrides", {})
+        lang_overrides = overrides.setdefault(language, {})
+
+        existing = lang_overrides.get(normalized)
+
+        if existing:
+            entry = existing
+            entry["token"] = token
+            entry["pronunciation"] = pronunciation
+            entry["voice"] = voice
+            entry["notes"] = notes
+            entry["context"] = context
+            entry["updated_at"] = timestamp
+        else:
+            entry = {
+                "id": str(uuid.uuid4()),
+                "normalized": normalized,
+                "token": token,
+                "language": language,
+                "pronunciation": pronunciation,
+                "voice": voice,
+                "notes": notes,
+                "context": context,
+                "usage_count": 0,
+                "created_at": timestamp,
+                "updated_at": timestamp,
+            }
+            lang_overrides[normalized] = entry
+
+        _save_db(db)
+        return entry
+
+
+def delete_override(*, language: str, token: str) -> None:
+    normalized = normalize_token(token)
+    if not normalized:
+        return
+
+    with _DB_LOCK:
+        db = _load_db()
+        lang_overrides = db.get("overrides", {}).get(language, {})
+
+        if normalized in lang_overrides:
+            del lang_overrides[normalized]
+            _save_db(db)
+
+
+def all_overrides(language: str) -> List[Dict[str, Any]]:
+    with _DB_LOCK:
+        db = _load_db()
+        lang_overrides = db.get("overrides", {}).get(language, {})
+
+        results = list(lang_overrides.values())
+        results.sort(key=lambda x: x.get("updated_at", 0), reverse=True)
+        return results
+
+
+def increment_usage(*, language: str, token: str, amount: int = 1) -> None:
+    normalized = normalize_token(token)
+    if not normalized:
+        return
+
+    with _DB_LOCK:
+        db = _load_db()
+        lang_overrides = db.get("overrides", {}).get(language, {})
+
+        if normalized in lang_overrides:
+            entry = lang_overrides[normalized]
+            entry["usage_count"] = entry.get("usage_count", 0) + amount
+            entry["updated_at"] = time.time()
+            _save_db(db)
+
+
+def get_override_stats(language: str) -> Dict[str, int]:
+    with _DB_LOCK:
+        db = _load_db()
+        lang_overrides = db.get("overrides", {}).get(language, {})
+
+        total = len(lang_overrides)
+        with_pronunciation = sum(
+            1 for x in lang_overrides.values() if x.get("pronunciation")
+        )
+        with_voice = sum(1 for x in lang_overrides.values() if x.get("voice"))
+
+        return {
+            "total": total,
+            "filtered": total,
+            "with_pronunciation": with_pronunciation,
+            "with_voice": with_voice,
+        }

abogen/pyqt/__init__.py

@@ -0,0 +1,7 @@
+"""PyQt6 Desktop GUI for abogen.
+
+This package contains the traditional PyQt6-based desktop interface.
+For the web-based interface, see abogen.webui.
+"""
+
+from __future__ import annotations

abogen/pyqt/main.py

@@ -0,0 +1,187 @@
+import os
+import sys
+import platform
+import atexit
+import signal
+from abogen.utils import get_resource_path, load_config, prevent_sleep_end
+
+
+# Fix PyTorch DLL loading issue ([WinError 1114]) on Windows before importing PyQt6
+if platform.system() == "Windows":
+    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
+
+
+# Qt platform plugin detection (fixes #59)
+try:
+    from PyQt6.QtCore import QLibraryInfo
+
+    # 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"))
+
+    # 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.")
+
+
+# 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
+
+
+# Set application ID for Windows taskbar icon
+if platform.system() == "Windows":
+    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)
+
+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
+
+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"
+
+
+# Custom message handler to filter out specific Qt warnings
+def qt_message_handler(mode, context, message):
+    # In PyQt6, the mode is an enum, so we compare with the enum members
+    if "Wayland does not support QWindow::requestActivate()" in message:
+        return  # Suppress this specific message
+    if "setGrabPopup called with a parent, QtWaylandClient" in message:
+        return
+
+    if mode == QtMsgType.QtWarningMsg:
+        print(f"Qt Warning: {message}")
+    elif mode == QtMsgType.QtCriticalMsg:
+        print(f"Qt Critical: {message}")
+    elif mode == QtMsgType.QtFatalMsg:
+        print(f"Qt Fatal: {message}")
+    elif mode == QtMsgType.QtInfoMsg:
+        print(f"Qt Info: {message}")
+
+
+# Install the custom message handler
+qInstallMessageHandler(qt_message_handler)
+
+# Handle Wayland on Linux GNOME
+if platform.system() == "Linux":
+    xdg_session = os.environ.get("XDG_SESSION_TYPE", "").lower()
+    desktop = os.environ.get("XDG_CURRENT_DESKTOP", "").lower()
+    if (
+        "gnome" in desktop
+        and xdg_session == "wayland"
+        and "QT_QPA_PLATFORM" not in os.environ
+    ):
+        os.environ["QT_QPA_PLATFORM"] = "wayland"
+
+
+def main():
+    """Main entry point for console usage."""
+    app = QApplication(sys.argv)
+
+    # Set application icon using get_resource_path from utils
+    icon_path = get_resource_path("abogen.assets", "icon.ico")
+    if icon_path:
+        app.setWindowIcon(QIcon(icon_path))
+
+    # Set the .desktop name on Linux
+    if platform.system() == "Linux":
+        try:
+            app.setDesktopFileName("abogen")
+        except AttributeError:
+            pass
+
+    ex = abogen()
+    ex.show()
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()

abogen/pyqt/predownload_gui.py

@@ -0,0 +1,590 @@
+"""
+Pre-download dialog and worker for Abogen
+
+This module consolidates pre-download logic for Kokoro voices and model
+and spaCy language models. The code favors clarity, avoids duplication,
+and handles optional dependencies gracefully.
+"""
+
+from typing import List, Optional, Tuple
+import importlib
+import importlib.util
+
+from PyQt6.QtWidgets import (
+    QDialog,
+    QVBoxLayout,
+    QHBoxLayout,
+    QLabel,
+    QPushButton,
+    QSpacerItem,
+    QSizePolicy,
+)
+from PyQt6.QtCore import QThread, pyqtSignal
+
+from abogen.constants import COLORS, VOICES_INTERNAL
+from abogen.spacy_utils import SPACY_MODELS
+import abogen.hf_tracker
+
+
+# Helpers
+def _unique_sorted_models() -> List[str]:
+    """Return a sorted list of unique spaCy model package names."""
+    return sorted(set(SPACY_MODELS.values()))
+
+
+def _is_package_installed(pkg_name: str) -> bool:
+    """Return True if a package with the given name can be imported (site-packages)."""
+    try:
+        return importlib.util.find_spec(pkg_name) is not None
+    except Exception:
+        return False
+
+
+# NOTE: explicit HF cache helper removed; we use try_to_load_from_cache in-scope where needed
+
+
+class PreDownloadWorker(QThread):
+    """Worker thread to download required models/voices.
+
+    Emits human-readable messages via `progress`. Uses `category_done` to indicate
+    a category (voices/model/spacy) finished successfully. Emits `error` on exception
+    and `finished` after all work completes.
+    """
+
+    # Emit (category, status, message)
+    progress = pyqtSignal(str, str, str)
+    category_done = pyqtSignal(str)
+    finished = pyqtSignal()
+    error = pyqtSignal(str)
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self._cancelled = False
+        # repo and filenames used for Kokoro model
+        self._repo_id = "hexgrad/Kokoro-82M"
+        self._model_files = ["kokoro-v1_0.pth", "config.json"]
+        # Track download success per category
+        self._voices_success = False
+        self._model_success = False
+        self._spacy_success = False
+        # Suppress HF tracker warnings during downloads
+        self._original_emitter = abogen.hf_tracker.show_warning_signal_emitter
+
+    def cancel(self) -> None:
+        self._cancelled = True
+
+    def run(self) -> None:
+        # Suppress HF tracker warnings during downloads
+        abogen.hf_tracker.show_warning_signal_emitter = None
+        try:
+            self._download_kokoro_voices()
+            if self._cancelled:
+                return
+            if self._voices_success:
+                self.category_done.emit("voices")
+
+            self._download_kokoro_model()
+            if self._cancelled:
+                return
+            if self._model_success:
+                self.category_done.emit("model")
+
+            self._download_spacy_models()
+            if self._cancelled:
+                return
+            if self._spacy_success:
+                self.category_done.emit("spacy")
+
+            self.finished.emit()
+        except Exception as exc:  # pragma: no cover - best-effort reporting
+            self.error.emit(str(exc))
+        finally:
+            # Restore original emitter
+            abogen.hf_tracker.show_warning_signal_emitter = self._original_emitter
+
+    # Kokoro voices
+    def _download_kokoro_voices(self) -> None:
+        self._voices_success = True
+        try:
+            from huggingface_hub import hf_hub_download, try_to_load_from_cache
+        except Exception:
+            self.progress.emit(
+                "voice", "warning", "huggingface_hub not installed, skipping voices..."
+            )
+            self._voices_success = False
+            return
+
+        voice_list = VOICES_INTERNAL
+        for idx, voice in enumerate(voice_list, start=1):
+            if self._cancelled:
+                self._voices_success = False
+                return
+            filename = f"voices/{voice}.pt"
+            if try_to_load_from_cache(repo_id=self._repo_id, filename=filename):
+                self.progress.emit(
+                    "voice",
+                    "installed",
+                    f"{idx}/{len(voice_list)}: {voice} already present",
+                )
+                continue
+            self.progress.emit(
+                "voice", "downloading", f"{idx}/{len(voice_list)}: {voice}..."
+            )
+            try:
+                hf_hub_download(repo_id=self._repo_id, filename=filename)
+                self.progress.emit("voice", "downloaded", f"{voice} downloaded")
+            except Exception as exc:
+                self.progress.emit(
+                    "voice", "warning", f"could not download {voice}: {exc}"
+                )
+                self._voices_success = False
+
+    # Kokoro model
+    def _download_kokoro_model(self) -> None:
+        self._model_success = True
+        try:
+            from huggingface_hub import hf_hub_download, try_to_load_from_cache
+        except Exception:
+            self.progress.emit(
+                "model", "warning", "huggingface_hub not installed, skipping model..."
+            )
+            self._model_success = False
+            return
+        for fname in self._model_files:
+            if self._cancelled:
+                self._model_success = False
+                return
+            category = "config" if fname == "config.json" else "model"
+            if try_to_load_from_cache(repo_id=self._repo_id, filename=fname):
+                self.progress.emit(
+                    category, "installed", f"file {fname} already present"
+                )
+                continue
+            self.progress.emit(category, "downloading", f"file {fname}...")
+            try:
+                hf_hub_download(repo_id=self._repo_id, filename=fname)
+                self.progress.emit(category, "downloaded", f"file {fname} downloaded")
+            except Exception as exc:
+                self.progress.emit(
+                    category, "warning", f"could not download file {fname}: {exc}"
+                )
+                self._model_success = False
+
+    # spaCy models
+    def _download_spacy_models(self) -> None:
+        """Download spaCy models. Prefer missing models provided by parent.
+
+        Parent dialog will populate _spacy_models_missing during checking.
+        """
+        self._spacy_success = True
+        # Determine which models to process: prefer parent-provided missing list to avoid
+        # re-checking everything; otherwise use the full unique list.
+        parent = self.parent()
+        models_to_process: List[str] = _unique_sorted_models()
+        try:
+            if (
+                parent is not None
+                and hasattr(parent, "_spacy_models_missing")
+                and parent._spacy_models_missing
+            ):
+                models_to_process = list(dict.fromkeys(parent._spacy_models_missing))
+        except Exception:
+            pass
+
+        # If spaCy is not available to run the CLI, skip gracefully
+        try:
+            import spacy.cli as _spacy_cli
+        except Exception:
+            self.progress.emit(
+                "spacy", "warning", "spaCy not available, skipping spaCy models..."
+            )
+            self._spacy_success = False
+            return
+
+        for idx, model_name in enumerate(models_to_process, start=1):
+            if self._cancelled:
+                self._spacy_success = False
+                return
+            if _is_package_installed(model_name):
+                self.progress.emit(
+                    "spacy",
+                    "installed",
+                    f"{idx}/{len(models_to_process)}: {model_name} already installed",
+                )
+                continue
+            self.progress.emit(
+                "spacy",
+                "downloading",
+                f"{idx}/{len(models_to_process)}: {model_name}...",
+            )
+            try:
+                _spacy_cli.download(model_name)
+                self.progress.emit("spacy", "downloaded", f"{model_name} downloaded")
+            except Exception as exc:
+                self.progress.emit(
+                    "spacy", "warning", f"could not download {model_name}: {exc}"
+                )
+                self._spacy_success = False
+
+
+class PreDownloadDialog(QDialog):
+    """Dialog to show and control pre-download process."""
+
+    VOICE_PREFIX = "Kokoro voices: "
+    MODEL_PREFIX = "Kokoro model: "
+    CONFIG_PREFIX = "Kokoro config: "
+    SPACY_PREFIX = "spaCy models: "
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self.setWindowTitle("Pre-download Models and Voices")
+        self.setMinimumWidth(500)
+        self.worker: Optional[PreDownloadWorker] = None
+        self.has_missing = False
+        self._spacy_models_checked: List[tuple] = []
+        self._spacy_models_missing: List[str] = []
+        self._status_worker = None
+
+        # Map keywords to (label, prefix) - labels filled after UI creation
+        self.status_map = {
+            "voice": (None, self.VOICE_PREFIX),
+            "spacy": (None, self.SPACY_PREFIX),
+            "model": (None, self.MODEL_PREFIX),
+            "config": (None, self.CONFIG_PREFIX),
+        }
+
+        self.category_map = {
+            "voices": ["voice"],
+            "model": ["model", "config"],
+            "spacy": ["spacy"],
+        }
+
+        self._setup_ui()
+        self._start_status_check()
+
+    def _setup_ui(self) -> None:
+        layout = QVBoxLayout(self)
+        layout.setSpacing(0)
+        layout.setContentsMargins(15, 0, 15, 15)
+
+        desc = QLabel(
+            "You can pre-download all required models and voices for offline use.\n"
+            "This includes Kokoro voices, Kokoro model (and config), and spaCy models."
+        )
+        desc.setWordWrap(True)
+        layout.addWidget(desc)
+
+        # Status rows
+        status_layout = QVBoxLayout()
+        status_title = QLabel("<b>Current Status:</b>")
+        status_layout.addWidget(status_title)
+
+        self.voices_status = QLabel(self.VOICE_PREFIX + "⏳ Checking...")
+        row = QHBoxLayout()
+        row.addWidget(self.voices_status)
+        row.addStretch()
+        status_layout.addLayout(row)
+
+        self.model_status = QLabel(self.MODEL_PREFIX + "⏳ Checking...")
+        row = QHBoxLayout()
+        row.addWidget(self.model_status)
+        row.addStretch()
+        status_layout.addLayout(row)
+
+        self.config_status = QLabel(self.CONFIG_PREFIX + "⏳ Checking...")
+        row = QHBoxLayout()
+        row.addWidget(self.config_status)
+        row.addStretch()
+        status_layout.addLayout(row)
+
+        self.spacy_status = QLabel(self.SPACY_PREFIX + "⏳ Checking...")
+        row = QHBoxLayout()
+        row.addWidget(self.spacy_status)
+        row.addStretch()
+        status_layout.addLayout(row)
+
+        # register labels
+        self.status_map["voice"] = (self.voices_status, self.VOICE_PREFIX)
+        self.status_map["model"] = (self.model_status, self.MODEL_PREFIX)
+        self.status_map["config"] = (self.config_status, self.CONFIG_PREFIX)
+        self.status_map["spacy"] = (self.spacy_status, self.SPACY_PREFIX)
+
+        layout.addLayout(status_layout)
+
+        layout.addItem(
+            QSpacerItem(0, 20, QSizePolicy.Policy.Minimum, QSizePolicy.Policy.Fixed)
+        )
+
+        # Buttons
+        button_row = QHBoxLayout()
+        button_row.setSpacing(10)
+        self.download_btn = QPushButton("Download all")
+        self.download_btn.setMinimumWidth(100)
+        self.download_btn.setMinimumHeight(35)
+        self.download_btn.setEnabled(False)
+        self.download_btn.clicked.connect(self._start_download)
+        button_row.addWidget(self.download_btn)
+
+        self.close_btn = QPushButton("Close")
+        self.close_btn.setMinimumWidth(100)
+        self.close_btn.setMinimumHeight(35)
+        self.close_btn.clicked.connect(self._handle_close)
+        button_row.addWidget(self.close_btn)
+
+        layout.addLayout(button_row)
+        self.adjustSize()
+
+    # Status checking worker
+    class StatusCheckWorker(QThread):
+        voices_checked = pyqtSignal(bool, list)
+        model_checked = pyqtSignal(bool)
+        config_checked = pyqtSignal(bool)
+        spacy_model_checking = pyqtSignal(str)
+        spacy_model_result = pyqtSignal(str, bool)
+        spacy_checked = pyqtSignal(bool, list)
+
+        def run(self):
+            parent = self.parent()
+            if parent is None:
+                return
+
+            voices_ok, missing_voices = parent._check_kokoro_voices()
+            self.voices_checked.emit(voices_ok, missing_voices)
+
+            model_ok = parent._check_kokoro_model()
+            self.model_checked.emit(model_ok)
+
+            config_ok = parent._check_kokoro_config()
+            self.config_checked.emit(config_ok)
+
+            # Check spaCy models by package name to detect site-package installs
+            unique = _unique_sorted_models()
+            missing: List[str] = []
+            for name in unique:
+                self.spacy_model_checking.emit(name)
+                ok = _is_package_installed(name)
+                self.spacy_model_result.emit(name, ok)
+                if not ok:
+                    missing.append(name)
+            parent._spacy_models_missing = missing
+            self.spacy_checked.emit(len(missing) == 0, missing)
+
+    def _start_status_check(self) -> None:
+        self._status_worker = self.StatusCheckWorker(self)
+        self._status_worker.voices_checked.connect(self._update_voices_status)
+        self._status_worker.model_checked.connect(self._update_model_status)
+        self._status_worker.config_checked.connect(self._update_config_status)
+        self._status_worker.spacy_model_checking.connect(self._spacy_model_checking)
+        self._status_worker.spacy_model_result.connect(self._spacy_model_result)
+        self._status_worker.spacy_checked.connect(self._update_spacy_status)
+
+        # These are initialized in __init__ to keep consistent object state
+
+        # Set checking visual state
+        for lbl in (
+            self.voices_status,
+            self.model_status,
+            self.config_status,
+            self.spacy_status,
+        ):
+            lbl.setStyleSheet(f"color: {COLORS['ORANGE']};")
+
+        self.spacy_status.setText(self.SPACY_PREFIX + "⏳ Checking...")
+        self._status_worker.start()
+
+    # UI update callbacks
+    def _spacy_model_checking(self, name: str) -> None:
+        self.spacy_status.setText(f"{self.SPACY_PREFIX}Checking {name}...")
+
+    def _spacy_model_result(self, name: str, ok: bool) -> None:
+        self._spacy_models_checked.append((name, ok))
+        if not ok and name not in self._spacy_models_missing:
+            self._spacy_models_missing.append(name)
+        checked = len(self._spacy_models_checked)
+        missing_count = len(self._spacy_models_missing)
+        if missing_count:
+            self.spacy_status.setText(
+                f"{self.SPACY_PREFIX}{checked} checked, {missing_count} missing..."
+            )
+        else:
+            self.spacy_status.setText(f"{self.SPACY_PREFIX}{checked} checked...")
+
+    def _update_voices_status(self, ok: bool, missing: List[str]) -> None:
+        if ok:
+            self._set_status("voice", "✓ Downloaded", COLORS["GREEN"])
+        else:
+            self.has_missing = True
+            if missing:
+                self._set_status(
+                    "voice", f"✗ Missing {len(missing)} voices", COLORS["RED"]
+                )
+            else:
+                self._set_status("voice", "✗ Not downloaded", COLORS["RED"])
+
+    def _update_model_status(self, ok: bool) -> None:
+        if ok:
+            self._set_status("model", "✓ Downloaded", COLORS["GREEN"])
+        else:
+            self.has_missing = True
+            self._set_status("model", "✗ Not downloaded", COLORS["RED"])
+
+    def _update_config_status(self, ok: bool) -> None:
+        if ok:
+            self._set_status("config", "✓ Downloaded", COLORS["GREEN"])
+        else:
+            self.has_missing = True
+            self._set_status("config", "✗ Not downloaded", COLORS["RED"])
+
+    def _update_spacy_status(self, ok: bool, missing: List[str]) -> None:
+        if ok:
+            self._set_status("spacy", "✓ Downloaded", COLORS["GREEN"])
+        else:
+            self.has_missing = True
+            if missing:
+                self._set_status(
+                    "spacy", f"✗ Missing {len(missing)} model(s)", COLORS["RED"]
+                )
+            else:
+                self._set_status("spacy", "✗ Not downloaded", COLORS["RED"])
+        self.download_btn.setEnabled(self.has_missing)
+
+    def _set_status(self, key: str, text: str, color: str) -> None:
+        lbl, prefix = self.status_map.get(key, (None, ""))
+        if not lbl:
+            return
+        lbl.setText(prefix + text)
+        lbl.setStyleSheet(f"color: {color};")
+
+    # Helper checks
+    def _check_kokoro_voices(self) -> Tuple[bool, List[str]]:
+        """Return (ok, missing_list) for Kokoro voices check."""
+        missing = []
+        try:
+            from huggingface_hub import try_to_load_from_cache
+
+            for voice in VOICES_INTERNAL:
+                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 (len(missing) == 0), missing
+
+    def _check_kokoro_model(self) -> bool:
+        try:
+            from huggingface_hub import try_to_load_from_cache
+
+            return (
+                try_to_load_from_cache(
+                    repo_id="hexgrad/Kokoro-82M", filename="kokoro-v1_0.pth"
+                )
+                is not None
+            )
+        except Exception:
+            return False
+
+    def _check_kokoro_config(self) -> bool:
+        try:
+            from huggingface_hub import try_to_load_from_cache
+
+            return (
+                try_to_load_from_cache(
+                    repo_id="hexgrad/Kokoro-82M", filename="config.json"
+                )
+                is not None
+            )
+        except Exception:
+            return False
+
+    def _check_spacy_models(self) -> bool:
+        unique = _unique_sorted_models()
+        missing = [m for m in unique if not _is_package_installed(m)]
+        self._spacy_models_missing = missing
+        return len(missing) == 0
+
+    # Download control
+    def _start_download(self) -> None:
+        self.download_btn.setEnabled(False)
+        self.download_btn.setText("Downloading...")
+        # mark the start of downloads; this triggers the labels
+        self._on_progress("system", "starting", "Processing, please wait...")
+        self.worker = PreDownloadWorker(self)
+        self.worker.progress.connect(self._on_progress)
+        self.worker.category_done.connect(self._on_category_done)
+        self.worker.finished.connect(self._on_download_finished)
+        self.worker.error.connect(self._on_download_error)
+        self.worker.start()
+
+    def _on_progress(self, category: str, status: str, message: str) -> None:
+        """Map worker (category, status, message) to UI label updates.
+
+        Status is one of: 'downloading', 'installed', 'downloaded', 'warning', 'starting'.
+        Category is one of: 'voice', 'model', 'spacy', 'config', or 'system'.
+        """
+        try:
+            # If the category targets a specific label, update directly
+            if category in self.status_map:
+                lbl, prefix = self.status_map[category]
+                if not lbl:
+                    return
+                # Compose message and set color based on status token
+                full_text = prefix + message
+                if len(full_text) > 60:
+                    display_text = full_text[:57] + "..."
+                    lbl.setText(display_text)
+                    lbl.setToolTip(full_text)
+                else:
+                    lbl.setText(full_text)
+                    lbl.setToolTip("")  # Clear tooltip if not needed
+                if status == "downloading":
+                    lbl.setStyleSheet(f"color: {COLORS['ORANGE']};")
+                elif status in ("installed", "downloaded"):
+                    lbl.setStyleSheet(f"color: {COLORS['GREEN']};")
+                elif status == "warning":
+                    lbl.setStyleSheet(f"color: {COLORS['RED']};")
+                elif status == "error":
+                    lbl.setStyleSheet(f"color: {COLORS['RED']};")
+                return
+
+            # System-level messages
+            if category == "system":
+                if status == "starting":
+                    for k in self.status_map:
+                        lbl, prefix = self.status_map[k]
+                        if lbl:
+                            lbl.setText(prefix + "Processing, please wait...")
+                            lbl.setStyleSheet(f"color: {COLORS['ORANGE']};")
+                # other system statuses don't require action
+                return
+        except Exception:
+            # Do not let UI thread crash on unexpected worker message
+            pass
+
+    def _on_category_done(self, category: str) -> None:
+        for key in self.category_map.get(category, []):
+            self._set_status(key, "✓ Downloaded", COLORS["GREEN"])
+
+    def _on_download_finished(self) -> None:
+        self.has_missing = False
+        self.download_btn.setText("Download all")
+        self.download_btn.setEnabled(False)
+
+    def _on_download_error(self, error_msg: str) -> None:
+        self.download_btn.setText("Download all")
+        self.download_btn.setEnabled(True)
+        for key in self.status_map:
+            self._set_status(key, f"✗ Error - {error_msg}", COLORS["RED"])
+
+    def _handle_close(self) -> None:
+        if self.worker and self.worker.isRunning():
+            self.worker.cancel()
+            self.worker.wait(2000)
+        self.accept()
+
+    def closeEvent(self, event) -> None:
+        if self.worker and self.worker.isRunning():
+            self.worker.cancel()
+            self.worker.wait(2000)
+        super().closeEvent(event)

abogen/pyqt/queue_manager_gui.py

@@ -0,0 +1,881 @@
+# a simple window with a list of items in the queue, no checkboxes
+# button to remove an item from the queue
+# button to clear the queue
+
+from PyQt6.QtWidgets import (
+    QDialog,
+    QVBoxLayout,
+    QHBoxLayout,
+    QDialogButtonBox,
+    QPushButton,
+    QListWidget,
+    QListWidgetItem,
+    QFileIconProvider,
+    QLabel,
+    QWidget,
+    QSizePolicy,
+    QAbstractItemView,
+    QCheckBox,
+)
+from PyQt6.QtCore import QFileInfo, Qt
+from abogen.constants import COLORS
+from copy import deepcopy
+from PyQt6.QtGui import QFontMetrics
+from abogen.utils import load_config, save_config
+
+# Define attributes that are safe to override with global settings
+OVERRIDE_FIELDS = [
+    "lang_code",
+    "speed",
+    "voice",
+    "save_option",
+    "output_folder",
+    "subtitle_mode",
+    "output_format",
+    "replace_single_newlines",
+    "use_silent_gaps",
+    "subtitle_speed_method",
+    "word_substitutions_enabled",
+    "word_substitutions_list",
+    "case_sensitive_substitutions",
+    "replace_all_caps",
+    "replace_numerals",
+    "fix_nonstandard_punctuation",
+]
+
+
+class ElidedLabel(QLabel):
+    def __init__(self, text):
+        super().__init__(text)
+        self._full_text = text
+        self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)
+        self.setTextFormat(Qt.TextFormat.PlainText)
+
+    def setText(self, text):
+        self._full_text = text
+        super().setText(text)
+        self.update()
+
+    def resizeEvent(self, event):
+        metrics = QFontMetrics(self.font())
+        elided = metrics.elidedText(
+            self._full_text, Qt.TextElideMode.ElideRight, self.width()
+        )
+        super().setText(elided)
+        super().resizeEvent(event)
+
+    def fullText(self):
+        return self._full_text
+
+
+class QueueListItemWidget(QWidget):
+    def __init__(self, file_name, char_count):
+        super().__init__()
+        layout = QHBoxLayout()
+        layout.setContentsMargins(12, 0, 6, 0)
+        layout.setSpacing(0)
+        import os
+
+        name_label = ElidedLabel(os.path.basename(file_name))
+        char_label = QLabel(f"Chars: {char_count}")
+        char_label.setStyleSheet(f"color: {COLORS['LIGHT_DISABLED']};")
+        char_label.setAlignment(
+            Qt.AlignmentFlag.AlignRight | Qt.AlignmentFlag.AlignVCenter
+        )
+        char_label.setSizePolicy(
+            QSizePolicy.Policy.Minimum, QSizePolicy.Policy.Preferred
+        )
+        layout.addWidget(name_label, 1)
+        layout.addWidget(char_label, 0)
+        self.setLayout(layout)
+
+
+class DroppableQueueListWidget(QListWidget):
+    def __init__(self, parent_dialog):
+        super().__init__()
+        self.parent_dialog = parent_dialog
+        self.setAcceptDrops(True)
+        # Overlay for drag hover
+        self.drag_overlay = QLabel("", self)
+        self.drag_overlay.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.drag_overlay.setStyleSheet(
+            f"border:2px dashed {COLORS['BLUE_BORDER_HOVER']}; border-radius:5px; padding:20px; background:{COLORS['BLUE_BG_HOVER']};"
+        )
+        self.drag_overlay.setVisible(False)
+        self.drag_overlay.setAttribute(
+            Qt.WidgetAttribute.WA_TransparentForMouseEvents, True
+        )
+
+    def dragEnterEvent(self, event):
+        if event.mimeData().hasUrls():
+            for url in event.mimeData().urls():
+                file_path = url.toLocalFile().lower()
+                if url.isLocalFile() and (
+                    file_path.endswith(".txt")
+                    or file_path.endswith((".srt", ".ass", ".vtt"))
+                ):
+                    self.drag_overlay.resize(self.size())
+                    self.drag_overlay.setVisible(True)
+                    event.acceptProposedAction()
+                    return
+        self.drag_overlay.setVisible(False)
+        event.ignore()
+
+    def dragMoveEvent(self, event):
+        if event.mimeData().hasUrls():
+            for url in event.mimeData().urls():
+                file_path = url.toLocalFile().lower()
+                if url.isLocalFile() and (
+                    file_path.endswith(".txt")
+                    or file_path.endswith((".srt", ".ass", ".vtt"))
+                ):
+                    event.acceptProposedAction()
+                    return
+        event.ignore()
+
+    def dragLeaveEvent(self, event):
+        self.drag_overlay.setVisible(False)
+        event.accept()
+
+    def dropEvent(self, event):
+        self.drag_overlay.setVisible(False)
+        if event.mimeData().hasUrls():
+            file_paths = [
+                url.toLocalFile()
+                for url in event.mimeData().urls()
+                if url.isLocalFile()
+                and (
+                    url.toLocalFile().lower().endswith(".txt")
+                    or url.toLocalFile().lower().endswith((".srt", ".ass", ".vtt"))
+                )
+            ]
+            if file_paths:
+                self.parent_dialog.add_files_from_paths(file_paths)
+                event.acceptProposedAction()
+            else:
+                event.ignore()
+        else:
+            event.ignore()
+
+    def resizeEvent(self, event):
+        super().resizeEvent(event)
+        if hasattr(self, "drag_overlay"):
+            self.drag_overlay.resize(self.size())
+
+
+class QueueManager(QDialog):
+    def __init__(self, parent, queue: list, title="Queue Manager", size=(600, 700)):
+        super().__init__()
+        self.queue = queue
+        self._original_queue = deepcopy(
+            queue
+        )  # Store a deep copy of the original queue
+        self.parent = parent
+        self.config = load_config()  # Load config for persistence
+
+        layout = QVBoxLayout()
+        layout.setContentsMargins(15, 15, 15, 15)  # set main layout margins
+        layout.setSpacing(12)  # set spacing between widgets in main layout
+        # list of queued items
+        self.listwidget = DroppableQueueListWidget(self)
+        self.listwidget.setSelectionMode(
+            QAbstractItemView.SelectionMode.ExtendedSelection
+        )
+        self.listwidget.setAlternatingRowColors(True)
+        self.listwidget.setContextMenuPolicy(Qt.ContextMenuPolicy.CustomContextMenu)
+        self.listwidget.customContextMenuRequested.connect(self.show_context_menu)
+        # Add informative instructions at the top
+        instructions = QLabel(
+            "<h2>How Queue Works?</h2>"
+            "You can add text and subtitle files (.txt, .srt, .ass, .vtt) directly using the '<b>Add files</b>' button below. "
+            "To add PDF, EPUB or markdown files, use the input box in the main window and click the <b>'Add to Queue'</b> button. "
+            "By default, each file in the queue keeps the configuration settings active when they were added. "
+            "Enabling the <b>'Override item settings with current selection'</b> option below will force all items to use the configuration currently selected in the main window. "
+            "You can view each file's configuration by hovering over them."
+        )
+        instructions.setAlignment(Qt.AlignmentFlag.AlignLeft)
+        instructions.setWordWrap(True)
+        layout.addWidget(instructions)
+
+        # Override Checkbox
+        self.override_chk = QCheckBox("Override item settings with current selection")
+        self.override_chk.setToolTip(
+            "If checked, all items in the queue will be processed using the \n"
+            "settings currently selected in the main window, ignoring their saved state."
+        )
+        # Load saved state (default to False)
+        self.override_chk.setChecked(self.config.get("queue_override_settings", False))
+        # Trigger process_queue to update tooltips immediately when toggled
+        self.override_chk.stateChanged.connect(self.process_queue)
+        self.override_chk.setStyleSheet("margin-bottom: 8px;")
+        layout.addWidget(self.override_chk)
+
+        # Overlay label for empty queue
+        self.empty_overlay = QLabel(
+            "Drag and drop your text or subtitle files here or use the 'Add files' button.",
+            self.listwidget,
+        )
+        self.empty_overlay.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.empty_overlay.setStyleSheet(
+            f"color: {COLORS['LIGHT_DISABLED']}; background: transparent; padding: 20px;"
+        )
+        self.empty_overlay.setWordWrap(True)
+        self.empty_overlay.setAttribute(
+            Qt.WidgetAttribute.WA_TransparentForMouseEvents, True
+        )
+        self.empty_overlay.hide()
+        # add queue items to the list
+        self.process_queue()
+
+        button_row = QHBoxLayout()
+        button_row.setContentsMargins(0, 0, 0, 0)  # optional: no margins for button row
+        button_row.setSpacing(7)  # set spacing between buttons
+        # Add files button
+        add_files_button = QPushButton("Add files")
+        add_files_button.setFixedHeight(40)
+        add_files_button.clicked.connect(self.add_more_files)
+        button_row.addWidget(add_files_button)
+
+        # Remove button
+        self.remove_button = QPushButton("Remove selected")
+        self.remove_button.setFixedHeight(40)
+        self.remove_button.clicked.connect(self.remove_item)
+        button_row.addWidget(self.remove_button)
+
+        # Clear button
+        self.clear_button = QPushButton("Clear Queue")
+        self.clear_button.setFixedHeight(40)
+        self.clear_button.clicked.connect(self.clear_queue)
+        button_row.addWidget(self.clear_button)
+
+        layout.addLayout(button_row)
+        layout.addWidget(self.listwidget)
+
+        # Connect selection change to update button state
+        self.listwidget.currentItemChanged.connect(self.update_button_states)
+        self.listwidget.itemSelectionChanged.connect(self.update_button_states)
+
+        buttons = QDialogButtonBox(
+            QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel,
+            self,
+        )
+        buttons.accepted.connect(self.accept)
+        buttons.rejected.connect(self.reject)
+
+        layout.addWidget(buttons)
+
+        self.setLayout(layout)
+
+        self.setWindowTitle(title)
+        self.resize(*size)
+
+        self.update_button_states()
+
+    def process_queue(self):
+        """Process the queue items."""
+        import os
+
+        self.listwidget.clear()
+        if not self.queue:
+            self.empty_overlay.show()
+            self.update_button_states()
+            return
+        else:
+            self.empty_overlay.hide()
+
+        # Get current global settings and checkbox state for overrides
+        current_global_settings = self.get_current_attributes()
+        is_override_active = self.override_chk.isChecked()
+
+        icon_provider = QFileIconProvider()
+        for item in self.queue:
+            # Dynamic Attribute Retrieval Helper
+            def get_val(attr, default=""):
+                # If override is ON and attr is overrideable, use global setting
+                if is_override_active and attr in OVERRIDE_FIELDS:
+                    return current_global_settings.get(attr, default)
+                # Otherwise return the item's saved attribute
+                return getattr(item, attr, default)
+
+            # Determine display file path (prefer save_base_path for original file)
+            display_file_path = getattr(item, "save_base_path", None) or item.file_name
+            processing_file_path = item.file_name
+
+            # Normalize paths for consistent display (fixes Windows path separator issues)
+            display_file_path = (
+                os.path.normpath(display_file_path)
+                if display_file_path
+                else display_file_path
+            )
+            processing_file_path = (
+                os.path.normpath(processing_file_path)
+                if processing_file_path
+                else processing_file_path
+            )
+
+            # Only show the file name, not the full path
+            display_name = display_file_path
+
+            if os.path.sep in display_file_path:
+                display_name = os.path.basename(display_file_path)
+            # Get icon for the display file
+            icon = icon_provider.icon(QFileInfo(display_file_path))
+            list_item = QListWidgetItem()
+
+            # Tooltip Generation
+            tooltip = ""
+            # If override is active, add the warning header on its own line
+            if is_override_active:
+                tooltip += "<b style='color: #ff9900;'>(Global Override Active)</b><br>"
+
+            output_folder = get_val("output_folder")
+            # For plain .txt inputs we don't need to show a separate processing file
+            show_processing = True
+            try:
+                if isinstance(
+                    display_file_path, str
+                ) and display_file_path.lower().endswith(".txt"):
+                    show_processing = False
+            except Exception:
+                show_processing = True
+
+            tooltip += f"<b>Input File:</b> {display_file_path}<br>"
+            if (
+                show_processing
+                and processing_file_path
+                and processing_file_path != display_file_path
+            ):
+                tooltip += f"<b>Processing File:</b> {processing_file_path}<br>"
+
+            tooltip += (
+                f"<b>Language:</b> {get_val('lang_code')}<br>"
+                f"<b>Speed:</b> {get_val('speed')}<br>"
+                f"<b>Voice:</b> {get_val('voice')}<br>"
+                f"<b>Save Option:</b> {get_val('save_option')}<br>"
+            )
+            if output_folder not in (None, "", "None"):
+                tooltip += f"<b>Output Folder:</b> {output_folder}<br>"
+            tooltip += (
+                f"<b>Subtitle Mode:</b> {get_val('subtitle_mode')}<br>"
+                f"<b>Output Format:</b> {get_val('output_format')}<br>"
+                f"<b>Characters:</b> {getattr(item, 'total_char_count', '')}<br>"
+                f"<b>Replace Single Newlines:</b> {get_val('replace_single_newlines', True)}<br>"
+                f"<b>Use Silent Gaps:</b> {get_val('use_silent_gaps', False)}<br>"
+                f"<b>Speed Method:</b> {get_val('subtitle_speed_method', 'tts')}"
+            )
+            # Add book handler options if present (Preserve logic: specific to file structure)
+            save_chapters_separately = getattr(item, "save_chapters_separately", None)
+            merge_chapters_at_end = getattr(item, "merge_chapters_at_end", None)
+            if save_chapters_separately is not None:
+                tooltip += f"<br><b>Save chapters separately:</b> {'Yes' if save_chapters_separately else 'No'}"
+                # Only show merge option if saving chapters separately
+                if save_chapters_separately and merge_chapters_at_end is not None:
+                    tooltip += f"<br><b>Merge chapters at the end:</b> {'Yes' if merge_chapters_at_end else 'No'}"
+            list_item.setToolTip(tooltip)
+            list_item.setIcon(icon)
+            # Store both paths for context menu
+            list_item.setData(
+                Qt.ItemDataRole.UserRole,
+                {
+                    "display_path": display_file_path,
+                    "processing_path": processing_file_path,
+                },
+            )
+            # Use custom widget for display
+            char_count = getattr(item, "total_char_count", 0)
+            widget = QueueListItemWidget(display_file_path, char_count)
+            self.listwidget.addItem(list_item)
+            self.listwidget.setItemWidget(list_item, widget)
+        self.update_button_states()
+
+    def remove_item(self):
+        items = self.listwidget.selectedItems()
+        if not items:
+            return
+        from PyQt6.QtWidgets import QMessageBox
+
+        # Remove by index to ensure correct mapping
+        rows = sorted([self.listwidget.row(item) for item in items], reverse=True)
+        # Warn user if removing multiple files
+        if len(rows) > 1:
+            reply = QMessageBox.question(
+                self,
+                "Confirm Remove",
+                f"Are you sure you want to remove {len(rows)} selected items from the queue?",
+                QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No,
+                QMessageBox.StandardButton.No,
+            )
+            if reply != QMessageBox.StandardButton.Yes:
+                return
+        for row in rows:
+            if 0 <= row < len(self.queue):
+                del self.queue[row]
+        self.process_queue()
+        self.update_button_states()
+
+    def clear_queue(self):
+        from PyQt6.QtWidgets import QMessageBox
+
+        if len(self.queue) > 1:
+            reply = QMessageBox.question(
+                self,
+                "Confirm Clear Queue",
+                f"Are you sure you want to clear {len(self.queue)} items from the queue?",
+                QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No,
+                QMessageBox.StandardButton.No,
+            )
+            if reply != QMessageBox.StandardButton.Yes:
+                return
+        self.queue.clear()
+        self.listwidget.clear()
+        self.empty_overlay.resize(
+            self.listwidget.size()
+        )  # Ensure overlay is sized correctly
+        self.empty_overlay.show()  # Show the overlay when queue is empty
+        self.update_button_states()
+
+    def get_queue(self):
+        return self.queue
+
+    def get_current_attributes(self):
+        # Fetch current attribute values from the parent abogen GUI
+        attrs = {}
+        parent = self.parent
+        if parent is not None:
+            # lang_code: use parent's get_voice_formula and get_selected_lang
+            if hasattr(parent, "get_voice_formula") and hasattr(
+                parent, "get_selected_lang"
+            ):
+                voice_formula = parent.get_voice_formula()
+                attrs["lang_code"] = parent.get_selected_lang(voice_formula)
+                attrs["voice"] = voice_formula
+            else:
+                attrs["lang_code"] = getattr(parent, "selected_lang", "")
+                attrs["voice"] = getattr(parent, "selected_voice", "")
+            # speed
+            if hasattr(parent, "speed_slider"):
+                attrs["speed"] = parent.speed_slider.value() / 100.0
+            else:
+                attrs["speed"] = getattr(parent, "speed", 1.0)
+            # save_option
+            attrs["save_option"] = getattr(parent, "save_option", "")
+            # output_folder
+            attrs["output_folder"] = getattr(parent, "selected_output_folder", "")
+            # subtitle_mode
+            if hasattr(parent, "get_actual_subtitle_mode"):
+                attrs["subtitle_mode"] = parent.get_actual_subtitle_mode()
+            else:
+                attrs["subtitle_mode"] = getattr(parent, "subtitle_mode", "")
+            # output_format
+            attrs["output_format"] = getattr(parent, "selected_format", "")
+            # total_char_count
+            attrs["total_char_count"] = getattr(parent, "char_count", "")
+            # replace_single_newlines
+            attrs["replace_single_newlines"] = getattr(
+                parent, "replace_single_newlines", True
+            )
+            # use_silent_gaps
+            attrs["use_silent_gaps"] = getattr(parent, "use_silent_gaps", False)
+            # subtitle_speed_method
+            attrs["subtitle_speed_method"] = getattr(
+                parent, "subtitle_speed_method", "tts"
+            )
+            # word substitutions
+            attrs["word_substitutions_enabled"] = getattr(
+                parent, "word_substitutions_enabled", False
+            )
+            attrs["word_substitutions_list"] = getattr(
+                parent, "word_substitutions_list", ""
+            )
+            attrs["case_sensitive_substitutions"] = getattr(
+                parent, "case_sensitive_substitutions", False
+            )
+            attrs["replace_all_caps"] = getattr(parent, "replace_all_caps", False)
+            attrs["replace_numerals"] = getattr(parent, "replace_numerals", False)
+            attrs["fix_nonstandard_punctuation"] = getattr(
+                parent, "fix_nonstandard_punctuation", False
+            )
+            # book handler options
+            attrs["save_chapters_separately"] = getattr(
+                parent, "save_chapters_separately", None
+            )
+            attrs["merge_chapters_at_end"] = getattr(
+                parent, "merge_chapters_at_end", None
+            )
+        else:
+            # fallback: empty values
+            attrs = {
+                k: ""
+                for k in [
+                    "lang_code",
+                    "speed",
+                    "voice",
+                    "save_option",
+                    "output_folder",
+                    "subtitle_mode",
+                    "output_format",
+                    "total_char_count",
+                    "replace_single_newlines",
+                ]
+            }
+            attrs["save_chapters_separately"] = None
+            attrs["merge_chapters_at_end"] = None
+        return attrs
+
+    def add_files_from_paths(self, file_paths):
+        from abogen.subtitle_utils import calculate_text_length
+        from PyQt6.QtWidgets import QMessageBox
+        import os
+
+        current_attrs = self.get_current_attributes()
+        duplicates = []
+        for file_path in file_paths:
+
+            class QueueItem:
+                pass
+
+            item = QueueItem()
+            item.file_name = file_path
+            item.save_base_path = (
+                file_path  # For .txt files, processing and save paths are the same
+            )
+            for attr, value in current_attrs.items():
+                setattr(item, attr, value)
+            # Override subtitle_mode to "Disabled" for subtitle files
+            if file_path.lower().endswith((".srt", ".ass", ".vtt")):
+                item.subtitle_mode = "Disabled"
+            # Read file content and calculate total_char_count using calculate_text_length
+            try:
+                with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+                    file_content = f.read()
+                item.total_char_count = calculate_text_length(file_content)
+            except Exception:
+                item.total_char_count = 0
+            # Prevent adding duplicate items to the queue (check all attributes)
+            is_duplicate = False
+            for queued_item in self.queue:
+                if (
+                    getattr(queued_item, "file_name", None)
+                    == getattr(item, "file_name", None)
+                    and getattr(queued_item, "lang_code", None)
+                    == getattr(item, "lang_code", None)
+                    and getattr(queued_item, "speed", None)
+                    == getattr(item, "speed", None)
+                    and getattr(queued_item, "voice", None)
+                    == getattr(item, "voice", None)
+                    and getattr(queued_item, "save_option", None)
+                    == getattr(item, "save_option", None)
+                    and getattr(queued_item, "output_folder", None)
+                    == getattr(item, "output_folder", None)
+                    and getattr(queued_item, "subtitle_mode", None)
+                    == getattr(item, "subtitle_mode", None)
+                    and getattr(queued_item, "output_format", None)
+                    == getattr(item, "output_format", None)
+                    and getattr(queued_item, "total_char_count", None)
+                    == getattr(item, "total_char_count", None)
+                    and getattr(queued_item, "replace_single_newlines", True)
+                    == getattr(item, "replace_single_newlines", True)
+                    and getattr(queued_item, "use_silent_gaps", False)
+                    == getattr(item, "use_silent_gaps", False)
+                    and getattr(queued_item, "subtitle_speed_method", "tts")
+                    == getattr(item, "subtitle_speed_method", "tts")
+                    and getattr(queued_item, "save_base_path", None)
+                    == getattr(item, "save_base_path", None)
+                    and getattr(queued_item, "save_chapters_separately", None)
+                    == getattr(item, "save_chapters_separately", None)
+                    and getattr(queued_item, "merge_chapters_at_end", None)
+                    == getattr(item, "merge_chapters_at_end", None)
+                ):
+                    is_duplicate = True
+                    break
+            if is_duplicate:
+                duplicates.append(os.path.basename(file_path))
+                continue
+            self.queue.append(item)
+        if duplicates:
+            QMessageBox.warning(
+                self,
+                "Duplicate Item(s)",
+                f"Skipping {len(duplicates)} file(s) with the same attributes, already in the queue.",
+            )
+        self.process_queue()
+        self.update_button_states()
+
+    def add_more_files(self):
+        from PyQt6.QtWidgets import QFileDialog
+
+        # Allow .txt, .srt, .ass, and .vtt files
+        files, _ = QFileDialog.getOpenFileNames(
+            self,
+            "Select text or subtitle files",
+            "",
+            "Supported Files (*.txt *.srt *.ass *.vtt)",
+        )
+        if not files:
+            return
+        self.add_files_from_paths(files)
+
+    def resizeEvent(self, event):
+        super().resizeEvent(event)
+        if hasattr(self, "empty_overlay"):
+            self.empty_overlay.resize(self.listwidget.size())
+
+    def update_button_states(self):
+        # Enable Remove if at least one item is selected, else disable
+        if hasattr(self, "remove_button"):
+            selected_count = len(self.listwidget.selectedItems())
+            self.remove_button.setEnabled(selected_count > 0)
+            if selected_count > 1:
+                self.remove_button.setText(f"Remove selected ({selected_count})")
+            else:
+                self.remove_button.setText("Remove selected")
+        # Disable Clear if queue is empty
+        if hasattr(self, "clear_button"):
+            self.clear_button.setEnabled(bool(self.queue))
+
+    def show_context_menu(self, pos):
+        from PyQt6.QtWidgets import QMenu
+        from PyQt6.QtGui import QAction, QDesktopServices
+        from PyQt6.QtCore import QUrl
+        import os
+
+        global_pos = self.listwidget.viewport().mapToGlobal(pos)
+        selected_items = self.listwidget.selectedItems()
+        menu = QMenu(self)
+        if len(selected_items) == 1:
+            # Add Remove action
+            remove_action = QAction("Remove this item", self)
+            remove_action.triggered.connect(self.remove_item)
+            menu.addAction(remove_action)
+
+            # Get paths for determining if it's a document input
+            item = selected_items[0]
+            paths = item.data(Qt.ItemDataRole.UserRole)
+            if isinstance(paths, dict):
+                display_path = paths.get("display_path", "")
+                processing_path = paths.get("processing_path", "")
+            else:
+                display_path = paths
+                processing_path = paths
+
+            doc_exts = (".md", ".markdown", ".pdf", ".epub")
+            is_document_input = (
+                isinstance(display_path, str)
+                and display_path.lower().endswith(doc_exts)
+            ) or (
+                isinstance(processing_path, str)
+                and processing_path.lower().endswith(doc_exts)
+            )
+
+            # Add Open file action(s)
+            def open_file_by_path(path_label: str):
+                from PyQt6.QtWidgets import QMessageBox
+
+                p = display_path if path_label == "display" else processing_path
+                if not p:
+                    QMessageBox.warning(
+                        self, "File Not Found", "Path is not available."
+                    )
+                    return
+
+                # Find the queue item and resolve the target path
+                target_path = None
+                for q in self.queue:
+                    if (
+                        getattr(q, "save_base_path", None) == display_path
+                        or q.file_name == display_path
+                    ):
+                        if path_label == "display":
+                            target_path = (
+                                getattr(q, "save_base_path", None) or q.file_name
+                            )
+                        else:
+                            target_path = q.file_name
+                        break
+                    if (
+                        getattr(q, "save_base_path", None) == processing_path
+                        or q.file_name == processing_path
+                    ):
+                        if path_label == "display":
+                            target_path = (
+                                getattr(q, "save_base_path", None) or q.file_name
+                            )
+                        else:
+                            target_path = q.file_name
+                        break
+
+                # Fallback to the raw path if resolution failed
+                if not target_path:
+                    target_path = p
+
+                if not os.path.exists(target_path):
+                    QMessageBox.warning(
+                        self, "File Not Found", f"The file does not exist."
+                    )
+                    return
+                QDesktopServices.openUrl(QUrl.fromLocalFile(target_path))
+
+            if is_document_input:
+                # For documents, show two open options
+                open_processed_action = QAction("Open processed file", self)
+                open_processed_action.triggered.connect(
+                    lambda: open_file_by_path("processing")
+                )
+                menu.addAction(open_processed_action)
+
+                open_input_action = QAction("Open input file", self)
+                open_input_action.triggered.connect(
+                    lambda: open_file_by_path("display")
+                )
+                menu.addAction(open_input_action)
+            else:
+                # For plain text files, show single open option
+                open_file_action = QAction("Open file", self)
+                open_file_action.triggered.connect(lambda: open_file_by_path("display"))
+                menu.addAction(open_file_action)
+
+            # Add Go to folder action
+            # If the queued item represents a converted document (markdown, pdf, epub)
+            # show two actions: Go to processed file (the cached .txt) and Go to input file (original source)
+
+            from PyQt6.QtWidgets import QMessageBox
+
+            def open_folder_for(path_label: str):
+                # path_label should be either 'display' or 'processing'
+                p = display_path if path_label == "display" else processing_path
+                if not p:
+                    QMessageBox.warning(
+                        self, "File Not Found", "Path is not available."
+                    )
+                    return
+                # If the stored path is the display path (original) but the actual file may be
+                # stored on the queue object differently, try to resolve via the queue entry.
+                target_path = None
+                for q in self.queue:
+                    if (
+                        getattr(q, "save_base_path", None) == display_path
+                        or q.file_name == display_path
+                    ):
+                        if path_label == "display":
+                            target_path = (
+                                getattr(q, "save_base_path", None) or q.file_name
+                            )
+                        else:
+                            target_path = q.file_name
+                        break
+                    if (
+                        getattr(q, "save_base_path", None) == processing_path
+                        or q.file_name == processing_path
+                    ):
+                        if path_label == "display":
+                            target_path = (
+                                getattr(q, "save_base_path", None) or q.file_name
+                            )
+                        else:
+                            target_path = q.file_name
+                        break
+                # Fallback to the raw path if resolution failed
+                if not target_path:
+                    target_path = p
+
+                if not os.path.exists(target_path):
+                    QMessageBox.warning(
+                        self,
+                        "File Not Found",
+                        f"The file does not exist: {target_path}",
+                    )
+                    return
+                folder = os.path.dirname(target_path)
+                if os.path.exists(folder):
+                    QDesktopServices.openUrl(QUrl.fromLocalFile(folder))
+
+            if is_document_input:
+                processed_action = QAction("Go to processed file", self)
+                processed_action.triggered.connect(
+                    lambda: open_folder_for("processing")
+                )
+                menu.addAction(processed_action)
+
+                input_action = QAction("Go to input file", self)
+                input_action.triggered.connect(lambda: open_folder_for("display"))
+                menu.addAction(input_action)
+            else:
+                # Default behavior for non-document inputs: single "Go to folder" action
+                go_to_folder_action = QAction("Go to folder", self)
+
+                def go_to_folder():
+                    item = selected_items[0]
+                    paths = item.data(Qt.ItemDataRole.UserRole)
+                    if isinstance(paths, dict):
+                        file_path = paths.get(
+                            "display_path", paths.get("processing_path", "")
+                        )
+                    else:
+                        file_path = paths  # Fallback for old format
+                    # Find the queue item
+                    for q in self.queue:
+                        if (
+                            getattr(q, "save_base_path", None) == file_path
+                            or q.file_name == file_path
+                        ):
+                            target_path = (
+                                getattr(q, "save_base_path", None) or q.file_name
+                            )
+                            if not os.path.exists(target_path):
+                                QMessageBox.warning(
+                                    self, "File Not Found", f"The file does not exist."
+                                )
+                                return
+                            folder = os.path.dirname(target_path)
+                            if os.path.exists(folder):
+                                QDesktopServices.openUrl(QUrl.fromLocalFile(folder))
+                            break
+
+                go_to_folder_action.triggered.connect(go_to_folder)
+                menu.addAction(go_to_folder_action)
+
+        elif len(selected_items) > 1:
+            remove_action = QAction(f"Remove selected ({len(selected_items)})", self)
+            remove_action.triggered.connect(self.remove_item)
+            menu.addAction(remove_action)
+        # Always add Clear Queue
+        clear_action = QAction("Clear Queue", self)
+        clear_action.triggered.connect(self.clear_queue)
+        menu.addAction(clear_action)
+        menu.exec(global_pos)
+
+    def accept(self):
+        # Save the override state to config so it persists globally
+        self.config["queue_override_settings"] = self.override_chk.isChecked()
+        save_config(self.config)
+        
+        super().accept()
+
+    def reject(self):
+        # Cancel: restore original queue
+        from PyQt6.QtWidgets import QMessageBox
+
+        # Warn if user changed a lot (e.g., more than 1 items difference)
+        original_count = len(self._original_queue)
+        current_count = len(self.queue)
+        if abs(original_count - current_count) > 1:
+            reply = QMessageBox.question(
+                self,
+                "Confirm Cancel",
+                f"Are you sure you want to cancel and discard all changes?",
+                QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No,
+                QMessageBox.StandardButton.No,
+            )
+            if reply != QMessageBox.StandardButton.Yes:
+                return
+        self.queue.clear()
+        self.queue.extend(deepcopy(self._original_queue))
+        super().reject()
+
+    def keyPressEvent(self, event):
+        from PyQt6.QtCore import Qt
+
+        if event.key() == Qt.Key.Key_Delete:
+            self.remove_item()
+        else:
+            super().keyPressEvent(event)

abogen/pyqt/queued_item.py

@@ -0,0 +1,28 @@
+# represents a queued item - book, chapters, voice, etc.
+from dataclasses import dataclass
+
+
+@dataclass
+class QueuedItem:
+    file_name: str
+    lang_code: str
+    speed: float
+    voice: str
+    save_option: str
+    output_folder: str
+    subtitle_mode: str
+    output_format: str
+    total_char_count: int
+    replace_single_newlines: bool = True
+    use_silent_gaps: bool = False
+    subtitle_speed_method: str = "tts"
+    save_base_path: str = None
+    save_chapters_separately: bool = None
+    merge_chapters_at_end: bool = None
+    # Word Substitution fields
+    word_substitutions_enabled: bool = False
+    word_substitutions_list: str = ""
+    case_sensitive_substitutions: bool = False
+    replace_all_caps: bool = False
+    replace_numerals: bool = False
+    fix_nonstandard_punctuation: bool = False

abogen/queue_manager_gui.py

@@ -0,0 +1,11 @@
+"""Backwards-compatible re-export of the PyQt queue manager.
+
+The actual implementation lives in abogen.pyqt.queue_manager_gui.
+"""
+
+from __future__ import annotations
+
+from abogen.pyqt.queue_manager_gui import *  # noqa: F401, F403
+from abogen.pyqt.queue_manager_gui import QueueManager
+
+__all__ = ["QueueManager"]

abogen/queued_item.py

@@ -0,0 +1,21 @@
+# represents a queued item - book, chapters, voice, etc.
+from dataclasses import dataclass
+
+
+@dataclass
+class QueuedItem:
+    file_name: str
+    lang_code: str
+    speed: float
+    voice: str
+    save_option: str
+    output_folder: str
+    subtitle_mode: str
+    output_format: str
+    total_char_count: int
+    replace_single_newlines: bool = True
+    use_silent_gaps: bool = False
+    subtitle_speed_method: str = "tts"
+    save_base_path: str = None
+    save_chapters_separately: bool = None
+    merge_chapters_at_end: bool = None

abogen/spacy_contraction_resolver.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import os
+import logging
+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
+
+# Lazy spaCy type hints to avoid a hard dependency at import time.
+Language = Any  # type: ignore[assignment]
+Token = Any  # type: ignore[assignment]
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ContractionResolution:
+    start: int
+    end: int
+    surface: str
+    expansion: str
+    category: str
+    lemma: str
+
+    @property
+    def span(self) -> Tuple[int, int]:
+        return self.start, self.end
+
+
+_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:
+        logger.debug("spaCy is not installed; skipping contraction disambiguation")
+        return None
+
+    try:
+        nlp = spacy.load(model)
+    except Exception as exc:  # pragma: no cover - depends on environment
+        logger.warning("Failed to load spaCy model '%s': %s", model, exc)
+        return None
+    return nlp
+
+
+def resolve_ambiguous_contractions(
+    text: str, *, model: Optional[str] = None
+) -> Dict[Tuple[int, int], ContractionResolution]:
+    """Use spaCy to disambiguate ambiguous contractions in *text*.
+
+    Returns a mapping from (start, end) spans to their resolved expansion.
+    Only ambiguous `'s` and `'d` contractions are considered.
+    """
+    if not text:
+        return {}
+
+    nlp = _load_spacy_model(model or _DEFAULT_MODEL)
+    if nlp is None:
+        return {}
+
+    doc = nlp(text)
+    resolutions: Dict[Tuple[int, int], ContractionResolution] = {}
+    for token in doc:
+        if token.text == "'s":
+            resolution = _resolve_apostrophe_s(token)
+        elif token.text == "'d":
+            resolution = _resolve_apostrophe_d(token)
+        else:
+            resolution = None
+
+        if resolution is None:
+            continue
+
+        if resolution.span not in resolutions:
+            resolutions[resolution.span] = resolution
+    return resolutions
+
+
+def _resolution(
+    prev: Token, token: Token, expansion_word: str, category: str, lemma_hint: str
+) -> Optional[ContractionResolution]:
+    if token is None or prev is None:
+        return None
+
+    if prev.idx + len(prev.text) != token.idx:
+        # Not a contiguous contraction (whitespace or punctuation in between)
+        return None
+
+    surface_start = prev.idx
+    surface_end = token.idx + len(token.text)
+    surface_text = token.doc.text[surface_start:surface_end]
+
+    expansion = _assemble_expansion(prev.text, surface_text, expansion_word)
+    return ContractionResolution(
+        start=surface_start,
+        end=surface_end,
+        surface=surface_text,
+        expansion=expansion,
+        category=category,
+        lemma=lemma_hint,
+    )
+
+
+def _assemble_expansion(base_text: str, surface_text: str, expansion_word: str) -> str:
+    """Combine *base_text* with *expansion_word*, preserving coarse casing."""
+    if not expansion_word:
+        return base_text
+
+    if surface_text.isupper() and expansion_word.isalpha():
+        adjusted = expansion_word.upper()
+    elif len(surface_text) > 2 and surface_text[:-2].istitle() and expansion_word:
+        # Surface like "It's" -> keep appended word lowercase
+        adjusted = expansion_word.lower()
+    else:
+        adjusted = expansion_word
+
+    return f"{base_text} {adjusted}".strip()
+
+
+def _resolve_apostrophe_s(token: Token) -> Optional[ContractionResolution]:
+    prev = token.nbor(-1) if token.i > 0 else None
+    if prev is None:
+        return None
+
+    # Possessive marker e.g., dog's
+    if token.tag_ == "POS" or token.lemma_ == "'s":
+        return None
+
+    prev_lower = prev.lemma_.lower()
+    surface = token.doc.text[prev.idx : token.idx + len(token.text)]
+
+    if prev_lower == "let":
+        return _resolution(prev, token, "us", "contraction_let_us", "us")
+
+    # Special check for 's been -> has been, overriding lemma
+    next_content = _next_content_token(token)
+    if next_content and next_content.text.lower() == "been":
+        return _resolution(prev, token, "has", "contraction_aux_have", "have")
+
+    lemma = token.lemma_.lower()
+    if not lemma:
+        lemma = "be" if _favors_be(token) else "have" if _favors_have(token) else "be"
+
+    if lemma == "be":
+        return _resolution(prev, token, "is", "contraction_aux_be", "be")
+    if lemma == "have":
+        return _resolution(prev, token, "has", "contraction_aux_have", "have")
+
+    if _favors_have(token):
+        return _resolution(prev, token, "has", "contraction_aux_have", "have")
+
+    if _favors_be(token):
+        return _resolution(prev, token, "is", "contraction_aux_be", "be")
+
+    # Default to copula expansion.
+    return _resolution(prev, token, "is", "contraction_aux_be", lemma or "be")
+
+
+def _resolve_apostrophe_d(token: Token) -> Optional[ContractionResolution]:
+    prev = token.nbor(-1) if token.i > 0 else None
+    if prev is None:
+        return None
+
+    if token.morph.get("VerbForm") == ["Part"]:
+        # spaCy sometimes tags possessives oddly; guard anyway
+        return None
+
+    lemma = token.lemma_.lower()
+    tense = set(token.morph.get("Tense"))
+    next_content = _next_content_token(token)
+    prefers_had = _context_prefers_had(token)
+
+    if prefers_had:
+        return _resolution(prev, token, "had", "contraction_aux_have", "have")
+
+    if "Past" in tense and lemma in {"have", "had"}:
+        return _resolution(prev, token, "had", "contraction_aux_have", "have")
+
+    if next_content is not None:
+        next_tag = next_content.tag_
+        next_lemma = next_content.lemma_.lower()
+    else:
+        next_tag = ""
+        next_lemma = ""
+
+    if next_tag == "VB":
+        return _resolution(
+            prev, token, "would", "contraction_modal_would", lemma or "will"
+        )
+
+    if token.tag_ == "MD" or lemma in {"will", "would", "shall"}:
+        return _resolution(
+            prev, token, "would", "contraction_modal_would", lemma or "will"
+        )
+
+    if next_lemma in {"been", "gone", "had", "better"} or next_tag in {"VBN", "VBD"}:
+        return _resolution(prev, token, "had", "contraction_aux_have", "have")
+
+    if lemma in {"have", "had"}:
+        return _resolution(prev, token, "had", "contraction_aux_have", lemma)
+
+    return _resolution(prev, token, "would", "contraction_modal_would", lemma or "will")
+
+
+def _next_content_token(token: Token) -> Optional[Token]:
+    doc = token.doc
+    for candidate in doc[token.i + 1 :]:
+        if candidate.is_space:
+            continue
+        if candidate.is_punct and candidate.text not in {"-"}:
+            break
+        if candidate.text in {"'", ""}:
+            continue
+        return candidate
+    return None
+
+
+def _favors_have(token: Token) -> bool:
+    next_content = _next_content_token(token)
+    if next_content is None:
+        return False
+    if next_content.tag_ in {"VBN"}:
+        return True
+    if next_content.lemma_.lower() in {"been", "gone", "had"}:
+        return True
+    return False
+
+
+def _favors_be(token: Token) -> bool:
+    next_content = _next_content_token(token)
+    if next_content is None:
+        return True
+    if next_content.tag_ in {"VBG", "JJ", "RB", "DT", "IN"}:
+        return True
+    return False
+
+
+def _context_prefers_had(token: Token) -> bool:
+    head = token.head if token.head is not None else None
+    if head is not None and head.i > token.i:
+        head_tag = head.tag_
+        head_lemma = head.lemma_.lower()
+        if head_tag in {"VBN", "VBD"} or head_lemma in {"gone", "been", "had"}:
+            return True
+        if head_lemma == "better":
+            return True
+
+    next_content = _next_content_token(token)
+    if next_content is None:
+        return False
+    next_tag = next_content.tag_
+    next_lemma = next_content.lemma_.lower()
+    if next_tag in {"VBN", "VBD"}:
+        return True
+    if next_lemma in {"been", "gone", "had"}:
+        return True
+    if next_lemma == "better":
+        return True
+    return False

abogen/spacy_utils.py

@@ -0,0 +1,161 @@
+"""
+Lazy-loaded spaCy utilities for sentence segmentation.
+"""
+
+# 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)
+}
+
+
+def _load_spacy():
+    """Lazy load spaCy module."""
+    global _spacy
+    if _spacy is None:
+        try:
+            import spacy
+
+            _spacy = spacy
+        except ImportError:
+            return None
+    return _spacy
+
+
+def get_spacy_model(lang_code, log_callback=None):
+    """
+    Get or load a spaCy model for the given language code.
+    Downloads the model automatically if not available.
+
+    Args:
+        lang_code: Language code (a, b, e, f, etc.)
+        log_callback: Optional function to log messages
+
+    Returns:
+        Loaded spaCy model or None if unavailable
+    """
+
+    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]
+
+    # Check if language is supported
+    model_name = SPACY_MODELS.get(lang_code)
+    if not model_name:
+        log(f"\nspaCy: No model mapping for language '{lang_code}'...")
+        return None
+
+    # Lazy load spaCy
+    spacy = _load_spacy()
+    if spacy is None:
+        log("\nspaCy: Module not installed, falling back to default segmentation...")
+        return None
+
+    # Try to load the model
+    try:
+        log(f"\nLoading spaCy model '{model_name}'...")
+        # sentence segmentation involving parentheses, quotes, and complex structure.
+        # We only disable heavier components we don't need like NER.
+        nlp = spacy.load(
+            model_name,
+            disable=["ner", "tagger", "lemmatizer", "attribute_ruler"],
+        )
+
+        # Ensure a sentence segmentation strategy is in place
+        # The parser provides sents, but if it's missing (unlikely for core models), fallback to sentencizer
+        if "parser" not in nlp.pipe_names and "sentencizer" not in nlp.pipe_names:
+            nlp.add_pipe("sentencizer")
+
+        _nlp_cache[lang_code] = nlp
+        return nlp
+    except OSError:
+        # Model not found, attempt download
+        log(f"\nspaCy: Downloading model '{model_name}'...")
+        try:
+            from spacy.cli import download
+
+            download(model_name)
+            # Retry loading with the same fix
+            nlp = spacy.load(
+                model_name,
+                disable=["ner", "tagger", "lemmatizer", "attribute_ruler"],
+            )
+            if "parser" not in nlp.pipe_names and "sentencizer" not in nlp.pipe_names:
+                nlp.add_pipe("sentencizer")
+
+            _nlp_cache[lang_code] = nlp
+            log(f"spaCy model '{model_name}' downloaded and loaded")
+            return nlp
+        except Exception as e:
+            log(
+                f"\nspaCy: Failed to download model '{model_name}': {e}...",
+                is_error=True,
+            )
+            return None
+    except Exception as e:
+        log(f"\nspaCy: Error loading model '{model_name}': {e}...", is_error=True)
+        return None
+
+
+def segment_sentences(text, lang_code, log_callback=None):
+    """
+    Segment text into sentences using spaCy.
+
+    Args:
+        text: Text to segment
+        lang_code: Language code
+        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)
+    if nlp is None:
+        return None
+
+    # Ensure spaCy can handle large texts by adjusting max_length if necessary
+    try:
+        text_len = len(text or "")
+        if text_len and hasattr(nlp, "max_length") and text_len > nlp.max_length:
+            # increase a bit beyond the text length to be safe
+            nlp.max_length = text_len + 1000
+    except Exception:
+        pass
+
+    # Process text and extract sentences
+    doc = nlp(text)
+    return [sent.text.strip() for sent in doc.sents if sent.text.strip()]
+
+
+def is_spacy_available():
+    """Check if spaCy can be imported."""
+    return _load_spacy() is not None
+
+
+def clear_cache():
+    """Clear the model cache to free memory."""
+    global _nlp_cache
+    _nlp_cache.clear()

abogen/speaker_analysis.py

@@ -0,0 +1,762 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+import unicodedata
+
+_DIALOGUE_VERBS = (
+    "said",
+    "asked",
+    "replied",
+    "whispered",
+    "shouted",
+    "cried",
+    "muttered",
+    "answered",
+    "hissed",
+    "called",
+    "added",
+    "continued",
+    "insisted",
+    "remarked",
+    "yelled",
+    "breathed",
+    "murmured",
+    "exclaimed",
+    "explained",
+    "noted",
+)
+
+_VERB_PATTERN = "(?:" + "|".join(_DIALOGUE_VERBS) + ")"
+_NAME_FRAGMENT = r"[A-ZÀ-ÖØ-Þ][\w'’\-]*"
+_NAME_PATTERN = rf"{_NAME_FRAGMENT}(?:\s+{_NAME_FRAGMENT})*"
+
+_COLON_PATTERN = re.compile(rf"^\s*({_NAME_PATTERN})\s*:\s*(.+)$")
+_NAME_BEFORE_VERB = re.compile(rf"({_NAME_PATTERN})\s+{_VERB_PATTERN}\b", re.IGNORECASE)
+_VERB_BEFORE_NAME = re.compile(rf"{_VERB_PATTERN}\s+({_NAME_PATTERN})", re.IGNORECASE)
+_PRONOUN_PATTERN = re.compile(r"\b(?:he|she|they)\b", re.IGNORECASE)
+_QUOTE_PATTERN = re.compile(r'["“”]([^"“”\\]*(?:\\.[^"“”\\]*)*)["”]')
+_MALE_PRONOUN_PATTERN = re.compile(r"\b(?:he|him|his|himself)\b", re.IGNORECASE)
+_FEMALE_PRONOUN_PATTERN = re.compile(r"\b(?:she|her|hers|herself)\b", re.IGNORECASE)
+_PRONOUN_LABELS = {
+    "he",
+    "she",
+    "they",
+    "them",
+    "theirs",
+    "their",
+    "themselves",
+    "him",
+    "his",
+    "himself",
+    "her",
+    "hers",
+    "herself",
+    "we",
+    "us",
+    "our",
+    "ours",
+    "ourselves",
+    "i",
+    "me",
+    "my",
+    "mine",
+    "myself",
+    "you",
+    "your",
+    "yours",
+    "yourself",
+    "yourselves",
+}
+
+_CONFIDENCE_RANK = {"low": 1, "medium": 2, "high": 3}
+
+_FEMALE_TITLE_HINTS = (
+    "madame",
+    "mme",
+    "madam",
+    "mrs",
+    "miss",
+    "ms",
+    "lady",
+    "countess",
+    "baroness",
+    "princess",
+    "queen",
+    "mademoiselle",
+)
+
+_MALE_TITLE_HINTS = (
+    "monsieur",
+    "m.",
+    "mr",
+    "sir",
+    "lord",
+    "count",
+    "baron",
+    "prince",
+    "king",
+    "abbé",
+    "abbe",
+)
+
+_MALE_TOKEN_WEIGHTS = {
+    "he": 1.0,
+    "him": 0.6,
+    "his": 0.75,
+    "himself": 1.0,
+}
+
+_FEMALE_TOKEN_WEIGHTS = {
+    "she": 1.0,
+    "her": 0.4,
+    "hers": 0.75,
+    "herself": 1.0,
+}
+
+_STOP_LABELS = {
+    "and",
+    "but",
+    "then",
+    "though",
+    "meanwhile",
+    "therefore",
+    "after",
+    "before",
+    "when",
+    "while",
+    "because",
+    "as",
+    "yet",
+    "nor",
+    "so",
+    "thus",
+    "suddenly",
+    "eventually",
+    "finally",
+    "until",
+    "unless",
+}
+
+
+@dataclass(slots=True)
+class SpeakerGuess:
+    speaker_id: str
+    label: str
+    count: int = 0
+    confidence: str = "low"
+    sample_quotes: List[Dict[str, str]] = field(default_factory=list)
+    suppressed: bool = False
+    gender: str = "unknown"
+    detected_gender: str = "unknown"
+    male_votes: int = 0
+    female_votes: int = 0
+
+    def register_occurrence(
+        self,
+        confidence: str,
+        text: str,
+        quote: Optional[str],
+        male_votes: int,
+        female_votes: int,
+        sample_excerpt: Optional[str] = None,
+    ) -> None:
+        self.count += 1
+        if _CONFIDENCE_RANK.get(confidence, 0) > _CONFIDENCE_RANK.get(
+            self.confidence, 0
+        ):
+            self.confidence = confidence
+
+        excerpt = (
+            sample_excerpt
+            if sample_excerpt is not None
+            else _build_excerpt(text, quote)
+        )
+        gender_hint = _format_gender_hint(male_votes, female_votes)
+        if excerpt:
+            payload = {"excerpt": excerpt, "gender_hint": gender_hint}
+            if payload not in self.sample_quotes:
+                self.sample_quotes.append(payload)
+                if len(self.sample_quotes) > 3:
+                    self.sample_quotes = self.sample_quotes[:3]
+
+        if male_votes:
+            self.male_votes += male_votes
+        if female_votes:
+            self.female_votes += female_votes
+        self.detected_gender = _derive_gender(
+            self.male_votes, self.female_votes, self.detected_gender
+        )
+        if self.gender in {"unknown", "male", "female"}:
+            self.gender = _derive_gender(
+                self.male_votes, self.female_votes, self.gender
+            )
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.speaker_id,
+            "label": self.label,
+            "count": self.count,
+            "confidence": self.confidence,
+            "sample_quotes": [dict(sample) for sample in self.sample_quotes],
+            "suppressed": self.suppressed,
+            "gender": self.gender,
+            "detected_gender": self.detected_gender,
+        }
+
+
+@dataclass(slots=True)
+class SpeakerAnalysis:
+    assignments: Dict[str, str]
+    speakers: Dict[str, SpeakerGuess]
+    suppressed: List[str]
+    narrator: str = "narrator"
+    version: str = "1.0"
+    stats: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "version": self.version,
+            "narrator": self.narrator,
+            "assignments": dict(self.assignments),
+            "speakers": {
+                speaker_id: guess.as_dict()
+                for speaker_id, guess in self.speakers.items()
+            },
+            "suppressed": list(self.suppressed),
+            "stats": dict(self.stats),
+        }
+
+
+def analyze_speakers(
+    chapters: Sequence[Dict[str, Any]] | Iterable[Dict[str, Any]],
+    chunks: Sequence[Dict[str, Any]] | Iterable[Dict[str, Any]],
+    *,
+    threshold: int = 3,
+    max_speakers: int = 8,
+) -> SpeakerAnalysis:
+    narrator_id = "narrator"
+    speaker_guesses: Dict[str, SpeakerGuess] = {
+        narrator_id: SpeakerGuess(
+            speaker_id=narrator_id, label="Narrator", confidence="low"
+        )
+    }
+    label_index: Dict[str, str] = {"Narrator": narrator_id}
+    assignments: Dict[str, str] = {}
+    suppressed: List[str] = []
+
+    ordered_chunks = sorted(
+        (dict(chunk) for chunk in chunks),
+        key=lambda entry: (
+            _safe_int(entry.get("chapter_index")),
+            _safe_int(entry.get("chunk_index")),
+        ),
+    )
+    last_explicit: Optional[str] = None
+    explicit_assignments = 0
+    unique_speakers: set[str] = set()
+
+    for index, chunk in enumerate(ordered_chunks):
+        chunk_id = str(chunk.get("id") or "")
+        text = _get_chunk_text(chunk)
+        speaker_id, confidence, quote = _infer_chunk_speaker(text, last_explicit)
+        if speaker_id is None:
+            speaker_id = last_explicit or narrator_id
+            confidence = "medium" if last_explicit else "low"
+            quote = quote or _extract_quote(text)
+        if speaker_id != narrator_id:
+            last_explicit = speaker_id
+            explicit_assignments += 1
+
+        if speaker_id in speaker_guesses:
+            record_id = speaker_id
+            guess = speaker_guesses[record_id]
+            label = guess.label
+        else:
+            label = _normalize_label(speaker_id)
+            record_id = label_index.get(label)
+            if record_id is None:
+                record_id = _dedupe_slug(_slugify(label), speaker_guesses)
+                label_index[label] = record_id
+                speaker_guesses[record_id] = SpeakerGuess(
+                    speaker_id=record_id, label=label
+                )
+            guess = speaker_guesses[record_id]
+        assignments[chunk_id] = record_id
+        unique_speakers.add(record_id)
+
+        if (
+            record_id != narrator_id
+            and record_id != speaker_id
+            and speaker_id == last_explicit
+        ):
+            last_explicit = record_id
+
+        sample_excerpt = None
+        if record_id != narrator_id:
+            sample_excerpt = _select_sample_excerpt(
+                ordered_chunks, index, guess.label, quote, confidence
+            )
+
+        male_votes, female_votes = _count_gender_votes(text, guess.label)
+
+        guess.register_occurrence(
+            confidence, text, quote, male_votes, female_votes, sample_excerpt
+        )
+
+    active_speakers = [sid for sid in speaker_guesses if sid != narrator_id]
+    # Apply minimum occurrence threshold.
+    for speaker_id in list(active_speakers):
+        guess = speaker_guesses[speaker_id]
+        if guess.count < max(1, threshold):
+            guess.suppressed = True
+            suppressed.append(speaker_id)
+            _reassign(assignments, speaker_id, narrator_id)
+            active_speakers.remove(speaker_id)
+
+    # Apply maximum active speaker cap.
+    if max_speakers and len(active_speakers) > max_speakers:
+        active_speakers.sort(key=lambda sid: (-speaker_guesses[sid].count, sid))
+        for speaker_id in active_speakers[max_speakers:]:
+            guess = speaker_guesses[speaker_id]
+            guess.suppressed = True
+            suppressed.append(speaker_id)
+            _reassign(assignments, speaker_id, narrator_id)
+        active_speakers = active_speakers[:max_speakers]
+
+    narrator_guess = speaker_guesses[narrator_id]
+    narrator_guess.count = sum(
+        1 for value in assignments.values() if value == narrator_id
+    )
+    narrator_guess.confidence = "low"
+
+    stats = {
+        "total_chunks": len(ordered_chunks),
+        "explicit_chunks": explicit_assignments,
+        "active_speakers": len(active_speakers),
+        "unique_speakers": len(unique_speakers),
+        "suppressed": len(suppressed),
+    }
+
+    return SpeakerAnalysis(
+        assignments=assignments,
+        speakers=speaker_guesses,
+        suppressed=suppressed,
+        narrator=narrator_id,
+        stats=stats,
+    )
+
+
+def _infer_chunk_speaker(
+    text: str, last_explicit: Optional[str]
+) -> Tuple[Optional[str], str, Optional[str]]:
+    normalized = text.strip()
+    if not normalized:
+        return None, "low", None
+
+    colon_match = _COLON_PATTERN.match(normalized)
+    if colon_match:
+        raw_label = colon_match.group(1)
+        cleaned = _normalize_candidate_name(raw_label)
+        if cleaned is None:
+            return None, "low", colon_match.group(2).strip()
+        quote = colon_match.group(2).strip()
+        return cleaned, "high", quote
+
+    quote = _extract_quote(normalized)
+    if not quote:
+        return None, "low", None
+
+    before, after = _split_around_quote(normalized, quote)
+
+    candidate = _match_name_near_quote(before, after)
+    if candidate:
+        cleaned = _normalize_candidate_name(candidate)
+        if cleaned:
+            return cleaned, "high", quote
+
+    if last_explicit:
+        pronoun_after = _PRONOUN_PATTERN.search(after)
+        pronoun_before = _PRONOUN_PATTERN.search(before)
+        if pronoun_after or pronoun_before:
+            return last_explicit, "medium", quote
+
+    return None, "low", quote
+
+
+def _split_around_quote(text: str, quote: str) -> Tuple[str, str]:
+    quote_index = text.find(quote)
+    if quote_index == -1:
+        return text, ""
+    before = text[:quote_index]
+    after = text[quote_index + len(quote) :]
+    return before, after
+
+
+def _match_name_near_quote(before: str, after: str) -> Optional[str]:
+    trailing = before[-120:]
+    leading = after[:120]
+
+    match = _NAME_BEFORE_VERB.search(trailing)
+    if match:
+        name = match.group(1)
+        if _looks_like_name(name):
+            return name
+
+    match = re.search(
+        rf"({_NAME_PATTERN})\s*,?\s*{_VERB_PATTERN}", leading, flags=re.IGNORECASE
+    )
+    if match:
+        name = match.group(1)
+        if _looks_like_name(name):
+            return name
+
+    match = _VERB_BEFORE_NAME.search(leading)
+    if match:
+        name = match.group(1)
+        if _looks_like_name(name):
+            return name
+
+    return None
+
+
+def _looks_like_name(value: str) -> bool:
+    normalized = _normalize_candidate_name(value)
+    if not normalized:
+        return False
+    parts = normalized.split()
+    if not parts:
+        return False
+    return all(part and part[0].isupper() for part in parts)
+
+
+def _extract_quote(text: str) -> Optional[str]:
+    match = _QUOTE_PATTERN.search(text)
+    if not match:
+        return None
+    return match.group(0)
+
+
+def _slugify(label: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "_", label.lower()).strip("_")
+    return slug or "speaker"
+
+
+def _dedupe_slug(slug: str, existing: Dict[str, SpeakerGuess]) -> str:
+    candidate = slug
+    index = 2
+    while candidate in existing:
+        candidate = f"{slug}_{index}"
+        index += 1
+    return candidate
+
+
+def _normalize_label(label: str) -> str:
+    words = re.split(r"\s+", label.strip())
+    return " ".join(word.capitalize() for word in words if word)
+
+
+def _safe_int(value: Any, default: int = 0) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _reassign(assignments: Dict[str, str], old: str, new: str) -> None:
+    for key, value in list(assignments.items()):
+        if value == old:
+            assignments[key] = new
+
+
+def _strip_diacritics(value: str) -> str:
+    normalized = unicodedata.normalize("NFKD", value)
+    return "".join(char for char in normalized if not unicodedata.combining(char))
+
+
+def _count_gender_votes(text: str, label: Optional[str]) -> Tuple[int, int]:
+    if not text:
+        return 0, 0
+
+    search_text = text
+    windows: List[Tuple[int, int]] = []
+    degrade_factor = 1.0
+
+    if label:
+        pattern = re.compile(re.escape(label), re.IGNORECASE)
+        matches = list(pattern.finditer(search_text))
+        if not matches:
+            alt_label = _strip_diacritics(label)
+            if alt_label and alt_label != label:
+                ascii_text = _strip_diacritics(search_text)
+                pattern_alt = re.compile(re.escape(alt_label), re.IGNORECASE)
+                windows = [match.span() for match in pattern_alt.finditer(ascii_text)]
+                # Map spans back roughly using proportional index
+                if windows:
+                    mapped: List[Tuple[int, int]] = []
+                    for start, end in windows:
+                        start_idx = min(
+                            len(search_text) - 1,
+                            int(start * len(search_text) / max(len(ascii_text), 1)),
+                        )
+                        end_idx = min(
+                            len(search_text),
+                            int(end * len(search_text) / max(len(ascii_text), 1)),
+                        )
+                        mapped.append((start_idx, end_idx))
+                    windows = mapped
+        else:
+            windows = [match.span() for match in matches]
+
+    if not windows:
+        windows = [(0, len(search_text))]
+        degrade_factor = 0.25
+
+    radius = 60
+    quote_spans: List[Tuple[int, int, str]] = []
+    for match in _QUOTE_PATTERN.finditer(search_text):
+        try:
+            content_start, content_end = match.span(1)
+        except IndexError:
+            content_start, content_end = match.span()
+        if content_start < content_end:
+            quote_spans.append(
+                (content_start, content_end, search_text[content_start:content_end])
+            )
+
+    normalized_label = _normalize_candidate_name(label) if label else None
+    normalized_label_lower = normalized_label.lower() if normalized_label else None
+
+    def _window_weight(position: int) -> float:
+        for start, end in windows:
+            if position < start - radius or position > end + radius:
+                continue
+            if position >= end:
+                return 1.0
+            if position <= start:
+                return 0.2
+            return 1.0
+        return 0.0
+
+    def _quote_weight(position: int) -> float:
+        for start, end, content in quote_spans:
+            if position < start or position >= end:
+                continue
+            local_index = position - start
+            prefix = content[:local_index]
+            tail = prefix[-80:]
+            name_matches = list(re.finditer(_NAME_PATTERN, tail))
+            if name_matches:
+                last_name = _normalize_candidate_name(name_matches[-1].group(0))
+                if (
+                    normalized_label_lower
+                    and last_name
+                    and last_name.lower() == normalized_label_lower
+                ):
+                    return 0.6
+                return 0.05
+            if re.search(r"[.!?]\s", prefix):
+                return 0.2
+            if prefix.strip():
+                return 0.15
+            return 0.1
+        return 1.0
+
+    male_score = 0.0
+    for match in _MALE_PRONOUN_PATTERN.finditer(search_text):
+        base_weight = _window_weight(match.start())
+        if not base_weight:
+            continue
+        quote_modifier = _quote_weight(match.start())
+        weight = base_weight * quote_modifier
+        if not weight:
+            continue
+        token = match.group(0).lower()
+        male_score += _MALE_TOKEN_WEIGHTS.get(token, 0.6) * weight
+
+    female_score = 0.0
+    for match in _FEMALE_PRONOUN_PATTERN.finditer(search_text):
+        base_weight = _window_weight(match.start())
+        if not base_weight:
+            continue
+        quote_modifier = _quote_weight(match.start())
+        weight = base_weight * quote_modifier
+        if not weight:
+            continue
+        if quote_modifier >= 0.95:
+            weight = max(weight, 0.4)
+        token = match.group(0).lower()
+        female_score += _FEMALE_TOKEN_WEIGHTS.get(token, 0.4) * weight
+
+    for start, end in windows:
+        span_start = max(0, start - 40)
+        span_end = min(len(search_text), end + 40)
+        span_text = search_text[span_start:span_end].lower()
+        if any(title in span_text for title in _FEMALE_TITLE_HINTS):
+            female_score += 2.5
+        if any(title in span_text for title in _MALE_TITLE_HINTS):
+            male_score += 2.5
+
+    male_votes = int(round(male_score * degrade_factor))
+    female_votes = int(round(female_score * degrade_factor))
+    return male_votes, female_votes
+
+
+def _derive_gender(male_votes: int, female_votes: int, current: str) -> str:
+    if male_votes == 0 and female_votes == 0:
+        return current if current != "unknown" else "unknown"
+
+    male_threshold = max(2, female_votes + 1)
+    female_threshold = max(2, male_votes + 1)
+
+    if male_votes >= male_threshold:
+        return "male"
+    if female_votes >= female_threshold:
+        return "female"
+
+    if current in {"male", "female"}:
+        return current
+    return "unknown"
+
+
+def _get_chunk_text(chunk: Dict[str, Any]) -> str:
+    if not isinstance(chunk, dict):
+        return ""
+    value = chunk.get("normalized_text") or chunk.get("text") or ""
+    return str(value)
+
+
+def _trim_paragraph(paragraph: str, limit: int = 600) -> str:
+    normalized = (paragraph or "").strip()
+    if not normalized:
+        return ""
+    if len(normalized) <= limit:
+        return normalized
+    return normalized[: limit - 1].rstrip() + "…"
+
+
+def _compose_context_excerpt(before: str, current: str, after: str) -> str:
+    segments = []
+    for value in (before, current, after):
+        trimmed = _trim_paragraph(value)
+        if trimmed:
+            segments.append(trimmed)
+    return "\n\n".join(segments)
+
+
+def _contains_dialogue_attribution(label: str, text: str, quote: Optional[str]) -> bool:
+    if not label or not text:
+        return False
+    escaped_label = re.escape(label)
+    direct_pattern = re.compile(
+        rf"\b{escaped_label}\b\s+(?:{_VERB_PATTERN})\b", re.IGNORECASE
+    )
+    reverse_pattern = re.compile(
+        rf"(?:{_VERB_PATTERN})\s+\b{escaped_label}\b", re.IGNORECASE
+    )
+    colon_pattern = re.compile(rf"^\s*{escaped_label}\s*:\s*", re.IGNORECASE)
+
+    if colon_pattern.search(text):
+        return True
+    if direct_pattern.search(text) or reverse_pattern.search(text):
+        return True
+    if quote:
+        before, after = _split_around_quote(text, quote)
+        if direct_pattern.search(before) or reverse_pattern.search(after):
+            return True
+    return False
+
+
+def _select_sample_excerpt(
+    chunks: Sequence[Dict[str, Any]],
+    index: int,
+    label: str,
+    quote: Optional[str],
+    confidence: str,
+) -> Optional[str]:
+    if confidence != "high" or not label:
+        return None
+    if index < 0 or index >= len(chunks):
+        return None
+    current = _get_chunk_text(chunks[index])
+    if not current or not _contains_dialogue_attribution(label, current, quote):
+        return None
+    previous = _get_chunk_text(chunks[index - 1]) if index > 0 else ""
+    following = _get_chunk_text(chunks[index + 1]) if index + 1 < len(chunks) else ""
+    excerpt = _compose_context_excerpt(previous, current, following)
+    return excerpt or None
+
+
+def _build_excerpt(text: str, quote: Optional[str]) -> str:
+    normalized = (text or "").strip()
+    if not normalized:
+        return ""
+    if quote:
+        location = normalized.find(quote)
+        if location != -1:
+            start = max(0, location - 120)
+            end = min(len(normalized), location + len(quote) + 120)
+            snippet = normalized[start:end].strip()
+            if start > 0:
+                snippet = "…" + snippet
+            if end < len(normalized):
+                snippet = snippet + "…"
+            return snippet
+    if len(normalized) > 240:
+        return normalized[:240].rstrip() + "…"
+    return normalized
+
+
+def _format_gender_hint(male_votes: int, female_votes: int) -> str:
+    if male_votes and female_votes:
+        return "Context mentions both male and female pronouns."
+    if male_votes:
+        if male_votes >= 3:
+            return "Multiple male pronouns detected nearby."
+        return "Some male pronouns detected in the surrounding text."
+    if female_votes:
+        if female_votes >= 3:
+            return "Multiple female pronouns detected nearby."
+        return "Some female pronouns detected in the surrounding text."
+    return "No clear pronoun signal detected."
+
+
+def _normalize_candidate_name(raw: str) -> Optional[str]:
+    if not raw:
+        return None
+    cleaned = raw.strip().strip("\"“”'’.,:;!")
+    cleaned = re.sub(r"\s+", " ", cleaned).strip()
+    if not cleaned:
+        return None
+    parts = cleaned.split()
+    filtered: List[str] = []
+    for part in parts:
+        if not part:
+            continue
+        if not filtered and part.lower() in _STOP_LABELS:
+            continue
+        filtered.append(part)
+    while filtered and filtered[-1].lower() in _STOP_LABELS:
+        filtered.pop()
+    if not filtered:
+        return None
+    if all(part.lower() in _STOP_LABELS for part in filtered):
+        return None
+    contiguous: List[str] = []
+    for part in filtered:
+        if part and part[0].isupper():
+            contiguous.append(part)
+        else:
+            break
+    if contiguous:
+        candidate = " ".join(contiguous)
+    else:
+        candidate = ""
+    if not candidate:
+        return None
+    lowered = candidate.lower()
+    if lowered in _PRONOUN_LABELS or lowered in _STOP_LABELS:
+        return None
+    return candidate

abogen/speaker_configs.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, List, Optional
+
+from abogen.constants import LANGUAGE_DESCRIPTIONS
+from abogen.utils import get_user_config_path
+
+_CONFIG_WRAPPER_KEY = "abogen_speaker_configs"
+
+
+def _config_path() -> str:
+    config_path = get_user_config_path()
+    config_dir = os.path.dirname(config_path)
+    os.makedirs(config_dir, exist_ok=True)
+    return os.path.join(config_dir, "speaker_configs.json")
+
+
+def load_configs() -> Dict[str, Dict[str, Any]]:
+    path = _config_path()
+    if not os.path.exists(path):
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except Exception:
+        return {}
+    if isinstance(payload, dict) and _CONFIG_WRAPPER_KEY in payload:
+        payload = payload[_CONFIG_WRAPPER_KEY]
+    if not isinstance(payload, dict):
+        return {}
+    sanitized: Dict[str, Dict[str, Any]] = {}
+    for name, entry in payload.items():
+        if not isinstance(name, str) or not isinstance(entry, dict):
+            continue
+        sanitized[name] = _sanitize_config(entry)
+    return sanitized
+
+
+def save_configs(configs: Dict[str, Dict[str, Any]]) -> None:
+    path = _config_path()
+    sanitized: Dict[str, Dict[str, Any]] = {}
+    for name, entry in configs.items():
+        if not isinstance(name, str) or not name.strip():
+            continue
+        sanitized[name] = _sanitize_config(entry)
+    with open(path, "w", encoding="utf-8") as handle:
+        json.dump({_CONFIG_WRAPPER_KEY: sanitized}, handle, indent=2, sort_keys=True)
+
+
+def get_config(name: str) -> Optional[Dict[str, Any]]:
+    name = (name or "").strip()
+    if not name:
+        return None
+    configs = load_configs()
+    data = configs.get(name)
+    return dict(data) if isinstance(data, dict) else None
+
+
+def upsert_config(name: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+    name = (name or "").strip()
+    if not name:
+        raise ValueError("Configuration name is required")
+    configs = load_configs()
+    configs[name] = _sanitize_config(payload or {})
+    save_configs(configs)
+    return configs[name]
+
+
+def delete_config(name: str) -> None:
+    name = (name or "").strip()
+    if not name:
+        return
+    configs = load_configs()
+    if name in configs:
+        del configs[name]
+        save_configs(configs)
+
+
+def _sanitize_config(entry: Dict[str, Any]) -> Dict[str, Any]:
+    language = str(entry.get("language") or "a").strip() or "a"
+    speakers_raw = entry.get("speakers")
+    if not isinstance(speakers_raw, dict):
+        speakers_raw = {}
+    speakers: Dict[str, Any] = {}
+    for speaker_id, payload in speakers_raw.items():
+        if not isinstance(speaker_id, str) or not isinstance(payload, dict):
+            continue
+        record = _sanitize_speaker({"id": speaker_id, **payload})
+        speakers[record["id"]] = record
+    allowed_languages = entry.get("languages") or entry.get("allowed_languages") or []
+    if not isinstance(allowed_languages, list):
+        allowed_languages = []
+    normalized_langs = []
+    for code in allowed_languages:
+        if isinstance(code, str) and code:
+            normalized_langs.append(code.lower())
+    default_voice = entry.get("default_voice")
+    if not isinstance(default_voice, str):
+        default_voice = ""
+    return {
+        "language": language.lower(),
+        "languages": normalized_langs,
+        "default_voice": default_voice,
+        "speakers": speakers,
+        "version": int(entry.get("version", 1)),
+        "notes": entry.get("notes") if isinstance(entry.get("notes"), str) else "",
+    }
+
+
+def slugify_label(label: str) -> str:
+    normalized = (label or "").strip().lower()
+    if not normalized:
+        return "speaker"
+    slug = "".join(ch if ch.isalnum() else "_" for ch in normalized)
+    slug = "_".join(filter(None, slug.split("_")))
+    return slug or "speaker"
+
+
+def _sanitize_speaker(entry: Dict[str, Any]) -> Dict[str, Any]:
+    label = (entry.get("label") or entry.get("name") or "").strip()
+    gender = (entry.get("gender") or "unknown").strip().lower()
+    if gender not in {"male", "female", "unknown"}:
+        gender = "unknown"
+    voice = entry.get("voice")
+    voice_profile = entry.get("voice_profile")
+    voice_formula = entry.get("voice_formula")
+    voice_languages = entry.get("languages") or []
+    if not isinstance(voice_languages, list):
+        voice_languages = []
+    normalized_langs = []
+    for code in voice_languages:
+        if isinstance(code, str) and code:
+            normalized_langs.append(code.lower())
+    resolved_voice = entry.get("resolved_voice") or voice_formula or voice
+    resolved_label = label or entry.get("id") or ""
+    slug = (
+        entry.get("id")
+        if isinstance(entry.get("id"), str)
+        else slugify_label(resolved_label)
+    )
+    return {
+        "id": slug,
+        "label": resolved_label,
+        "gender": gender,
+        "voice": voice if isinstance(voice, str) else "",
+        "voice_profile": voice_profile if isinstance(voice_profile, str) else "",
+        "voice_formula": voice_formula if isinstance(voice_formula, str) else "",
+        "resolved_voice": resolved_voice if isinstance(resolved_voice, str) else "",
+        "languages": normalized_langs,
+    }
+
+
+def list_configs() -> List[Dict[str, Any]]:
+    configs = load_configs()
+    ordered = []
+    for name in sorted(configs):
+        entry = configs[name]
+        ordered.append({"name": name, **entry})
+    return ordered
+
+
+def describe_language(code: str) -> str:
+    code = (code or "a").lower()
+    return LANGUAGE_DESCRIPTIONS.get(code, code.upper())

abogen/subtitle_utils.py

@@ -0,0 +1,584 @@
+import re
+import platform
+from abogen.utils import detect_encoding, load_config
+from abogen.constants import SAMPLE_VOICE_TEXTS
+
+# Pre-compile frequently used regex patterns for better performance
+_METADATA_TAG_PATTERN = re.compile(r"<<METADATA_[^:]+:[^>]*>>")
+_WHITESPACE_PATTERN = re.compile(r"[^\S\n]+")
+_MULTIPLE_NEWLINES_PATTERN = re.compile(r"\n{3,}")
+_SINGLE_NEWLINE_PATTERN = re.compile(r"(?<!\n)\n(?!\n)")
+_CHAPTER_MARKER_PATTERN = re.compile(r"<<CHAPTER_MARKER:[^>]*>>")
+_HTML_TAG_PATTERN = re.compile(r"<[^>]+>")
+_VOICE_TAG_PATTERN = re.compile(r"{[^}]+}")
+_ASS_STYLING_PATTERN = re.compile(r"\{[^}]+\}")
+_ASS_NEWLINE_N_PATTERN = re.compile(r"\\N")
+_ASS_NEWLINE_LOWER_N_PATTERN = re.compile(r"\\n")
+_CHAPTER_MARKER_SEARCH_PATTERN = re.compile(r"<<CHAPTER_MARKER:(.*?)>>")
+_VOICE_MARKER_PATTERN = re.compile(r"<<VOICE:[^>]*>>")
+_VOICE_MARKER_SEARCH_PATTERN = re.compile(r"<<VOICE:(.*?)>>")
+_WEBVTT_HEADER_PATTERN = re.compile(r"^WEBVTT.*?\n", re.MULTILINE)
+_VTT_STYLE_PATTERN = re.compile(r"STYLE\s*\n.*?(?=\n\n|$)", re.DOTALL)
+_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):
+    """Remove chapter markers, voice markers, and metadata tags from subtitle text."""
+    # Use pre-compiled patterns for better performance
+    text = _METADATA_TAG_PATTERN.sub("", text)
+    text = _CHAPTER_MARKER_PATTERN.sub("", text)
+    text = _VOICE_MARKER_PATTERN.sub("", 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):
+    # Remove metadata tags first
+    text = _METADATA_TAG_PATTERN.sub("", text)
+    # Load replace_single_newlines from config
+    cfg = load_config()
+    replace_single_newlines = cfg.get("replace_single_newlines", True)
+    # Collapse all whitespace (excluding newlines) into single spaces per line and trim edges
+    # Use pre-compiled pattern for better performance
+    lines = [_WHITESPACE_PATTERN.sub(" ", line).strip() for line in text.splitlines()]
+    text = "\n".join(lines)
+    # Standardize paragraph breaks (multiple newlines become exactly two) and trim overall whitespace
+    # Use pre-compiled pattern for better performance
+    text = _MULTIPLE_NEWLINES_PATTERN.sub("\n\n", text).strip()
+    # Optionally replace single newlines with spaces, but preserve double newlines
+    if replace_single_newlines:
+        # Use pre-compiled pattern for better performance
+        text = _SINGLE_NEWLINE_PATTERN.sub(" ", text)
+    return text
+
+
+def parse_srt_file(file_path):
+    """
+    Parse an SRT subtitle file and return a list of subtitle entries.
+
+    Args:
+        file_path: Path to the SRT file
+
+    Returns:
+        List of tuples: [(start_time_seconds, end_time_seconds, text), ...]
+    """
+    encoding = detect_encoding(file_path)
+    with open(file_path, "r", encoding=encoding, errors="replace") as f:
+        content = f.read()
+
+    # Split by double newlines to get individual subtitle blocks
+    blocks = re.split(r"\n\s*\n", content.strip())
+
+    subtitles = []
+    for block in blocks:
+        if not block.strip():
+            continue
+
+        lines = block.strip().split("\n")
+        if len(lines) < 3:
+            continue
+
+        # First line is index, second line is timestamp, rest is text
+        try:
+            timestamp_line = lines[1]
+            match = re.match(
+                r"(\d{2}:\d{2}:\d{2},\d{3})\s*-->\s*(\d{2}:\d{2}:\d{2},\d{3})",
+                timestamp_line,
+            )
+            if not match:
+                continue
+
+            start_str = match.group(1)
+            end_str = match.group(2)
+            text = "\n".join(lines[2:])
+
+            # Convert timestamp to seconds
+            def time_to_seconds(t):
+                h, m, s_ms = t.split(":")
+                s, ms = s_ms.split(",")
+                return int(h) * 3600 + int(m) * 60 + int(s) + int(ms) / 1000.0
+
+            start_sec = time_to_seconds(start_str)
+            end_sec = time_to_seconds(end_str)
+
+            # Clean text of any styling tags using pre-compiled pattern
+            text = _HTML_TAG_PATTERN.sub("", text)
+            # Remove chapter markers and metadata tags
+            text = clean_subtitle_text(text)
+
+            if text:  # Only add non-empty subtitles
+                subtitles.append((start_sec, end_sec, text))
+        except (ValueError, IndexError):
+            continue
+
+    return subtitles
+
+
+def parse_vtt_file(file_path):
+    """
+    Parse a VTT (WebVTT) subtitle file and return a list of subtitle entries.
+
+    Args:
+        file_path: Path to the VTT file
+
+    Returns:
+        List of tuples: [(start_time_seconds, end_time_seconds, text), ...]
+    """
+    encoding = detect_encoding(file_path)
+    with open(file_path, "r", encoding=encoding, errors="replace") as f:
+        content = f.read()
+
+    # Remove WEBVTT header and any style/note blocks using pre-compiled patterns
+    content = _WEBVTT_HEADER_PATTERN.sub("", content)
+    content = _VTT_STYLE_PATTERN.sub("", content)
+    content = _VTT_NOTE_PATTERN.sub("", content)
+
+    # Split by double newlines to get individual subtitle blocks using pre-compiled pattern
+    blocks = _DOUBLE_NEWLINE_SPLIT_PATTERN.split(content.strip())
+
+    subtitles = []
+    for block in blocks:
+        if not block.strip():
+            continue
+
+        lines = block.strip().split("\n")
+        if len(lines) < 2:
+            continue
+
+        # VTT can have optional identifier on first line, timestamp on second or first
+        timestamp_line = None
+        text_start_idx = 0
+
+        # Check if first line is timestamp
+        if "-->" in lines[0]:
+            timestamp_line = lines[0]
+            text_start_idx = 1
+        elif len(lines) > 1 and "-->" in lines[1]:
+            timestamp_line = lines[1]
+            text_start_idx = 2
+        else:
+            continue
+
+        try:
+            # VTT format: 00:00:00.000 --> 00:00:05.000 or 00:00.000 --> 00:05.000
+            # Use pre-compiled pattern
+            match = _VTT_TIMESTAMP_PATTERN.match(timestamp_line)
+            if not match:
+                continue
+
+            start_str = match.group(1)
+            end_str = match.group(2)
+            text = "\n".join(lines[text_start_idx:])
+
+            # Convert timestamp to seconds
+            def time_to_seconds(t):
+                parts = t.split(":")
+                if len(parts) == 3:  # HH:MM:SS.mmm
+                    h, m, s = parts
+                    s, ms = s.split(".")
+                    return int(h) * 3600 + int(m) * 60 + int(s) + int(ms) / 1000.0
+                elif len(parts) == 2:  # MM:SS.mmm
+                    m, s = parts
+                    s, ms = s.split(".")
+                    return int(m) * 60 + int(s) + int(ms) / 1000.0
+                return 0
+
+            start_sec = time_to_seconds(start_str)
+            end_sec = time_to_seconds(end_str)
+
+            # Clean text of any styling tags and cue settings using pre-compiled patterns
+            text = _HTML_TAG_PATTERN.sub("", text)
+            text = _VOICE_TAG_PATTERN.sub("", text)  # Remove voice tags
+            # Remove chapter markers and metadata tags
+            text = clean_subtitle_text(text)
+
+            if text:  # Only add non-empty subtitles
+                subtitles.append((start_sec, end_sec, text))
+        except (ValueError, IndexError, AttributeError):
+            continue
+
+    return subtitles
+
+
+def detect_timestamps_in_text(file_path):
+    """Detect if text file contains timestamp markers (HH:MM:SS or HH:MM:SS,ms format) on separate lines."""
+    try:
+        encoding = detect_encoding(file_path)
+        with open(file_path, "r", encoding=encoding, errors="replace") as f:
+            lines = [
+                line.strip() for line in f.readlines()[:50] if line.strip()
+            ]  # Check first 50 non-empty lines
+
+        # Count lines that are ONLY timestamps (no other text)
+        # Supports HH:MM:SS or HH:MM:SS,ms format
+        # Use pre-compiled pattern for better performance
+        timestamp_lines = sum(
+            1 for line in lines if _TIMESTAMP_ONLY_PATTERN.match(line)
+        )
+
+        # Must have at least 2 timestamp-only lines and they should be >5% of total lines
+        return timestamp_lines >= 2 and (timestamp_lines / max(len(lines), 1)) > 0.05
+    except Exception:
+        return False
+
+
+def parse_timestamp_text_file(file_path):
+    """Parse text file with timestamps. Returns list of (start_time, end_time, text) tuples.
+    Supports HH:MM:SS or HH:MM:SS,ms format. Returns time in seconds as float."""
+    encoding = detect_encoding(file_path)
+    with open(file_path, "r", encoding=encoding, errors="replace") as f:
+        content = f.read()
+
+    # Split by timestamp pattern (supports HH:MM:SS or HH:MM:SS,ms)
+    pattern = r"^(\d{1,2}:\d{2}:\d{2}(?:[.,]\d{1,3})?)$"
+    lines = content.split("\n")
+
+    def parse_time(time_str):
+        """Convert HH:MM:SS or HH:MM:SS,ms to seconds as float."""
+        time_str = time_str.replace(",", ".")
+        parts = time_str.split(":")
+        return float(int(parts[0]) * 3600 + int(parts[1]) * 60 + float(parts[2]))
+
+    entries = []
+    current_time = None
+    current_text = []
+    pre_timestamp_text = []  # Text before first timestamp
+
+    for line in lines:
+        match = re.match(pattern, line.strip())
+        if match:
+            # Save previous entry
+            if current_time is not None and current_text:
+                text = "\n".join(current_text).strip()
+                if text:
+                    entries.append((current_time, text))
+            elif current_time is None and pre_timestamp_text:
+                # First timestamp found, save pre-timestamp text with time 0
+                text = "\n".join(pre_timestamp_text).strip()
+                if text:
+                    entries.append((0.0, text))
+                pre_timestamp_text = []
+
+            # Start new entry
+            time_str = match.group(1)
+            current_time = parse_time(time_str)
+            current_text = []
+        elif current_time is not None:
+            current_text.append(line)
+        else:
+            # Text before first timestamp
+            pre_timestamp_text.append(line)
+
+    # Save last entry
+    if current_time is not None and current_text:
+        text = "\n".join(current_text).strip()
+        if text:
+            entries.append((current_time, text))
+    elif not entries and pre_timestamp_text:
+        # No timestamps found at all, treat entire file as starting at 0
+        text = "\n".join(pre_timestamp_text).strip()
+        if text:
+            entries.append((0.0, text))
+
+    # Convert to subtitle format with end times
+    subtitles = []
+    for i, (start_time, text) in enumerate(entries):
+        end_time = entries[i + 1][0] if i + 1 < len(entries) else None
+        # Remove chapter markers and metadata tags
+        text = clean_subtitle_text(text)
+        if text:  # Only add non-empty entries
+            subtitles.append((start_time, end_time, text))
+
+    return subtitles
+
+
+def parse_ass_file(file_path):
+    """
+    Parse an ASS/SSA subtitle file and return a list of subtitle entries.
+
+    Args:
+        file_path: Path to the ASS/SSA file
+
+    Returns:
+        List of tuples: [(start_time_seconds, end_time_seconds, text), ...]
+    """
+    encoding = detect_encoding(file_path)
+    with open(file_path, "r", encoding=encoding, errors="replace") as f:
+        lines = f.readlines()
+
+    subtitles = []
+    in_events = False
+    format_indices = {}
+
+    for line in lines:
+        line = line.strip()
+
+        if line.startswith("[Events]"):
+            in_events = True
+            continue
+
+        if line.startswith("[") and in_events:
+            # New section, stop processing
+            break
+
+        if in_events and line.startswith("Format:"):
+            # Parse format line to know column positions
+            parts = line.split(":", 1)[1].strip().split(",")
+            for i, part in enumerate(parts):
+                format_indices[part.strip().lower()] = i
+            continue
+
+        if in_events and (line.startswith("Dialogue:") or line.startswith("Comment:")):
+            if line.startswith("Comment:"):
+                continue  # Skip comments
+
+            parts = line.split(":", 1)[1].strip().split(",", len(format_indices) - 1)
+
+            if (
+                "start" in format_indices
+                and "end" in format_indices
+                and "text" in format_indices
+            ):
+                start_str = parts[format_indices["start"]].strip()
+                end_str = parts[format_indices["end"]].strip()
+                text = parts[format_indices["text"]].strip()
+
+                # Convert timestamp to seconds (ASS format: H:MM:SS.CS where CS is centiseconds)
+                def ass_time_to_seconds(t):
+                    parts = t.split(":")
+                    if len(parts) == 3:
+                        h, m, s = parts
+                        s_parts = s.split(".")
+                        seconds = float(s_parts[0])
+                        centiseconds = float(s_parts[1]) if len(s_parts) > 1 else 0
+                        return (
+                            int(h) * 3600 + int(m) * 60 + seconds + centiseconds / 100.0
+                        )
+                    return 0
+
+                start_sec = ass_time_to_seconds(start_str)
+                end_sec = ass_time_to_seconds(end_str)
+
+                # Clean text of ASS styling tags using pre-compiled patterns
+                text = _ASS_STYLING_PATTERN.sub("", text)  # Remove {tags}
+                text = _ASS_NEWLINE_N_PATTERN.sub("\n", text)  # Convert \N to newline
+                text = _ASS_NEWLINE_LOWER_N_PATTERN.sub(
+                    "\n", text
+                )  # Convert \n to newline
+                # Remove chapter markers and metadata tags
+                text = clean_subtitle_text(text)
+
+                if text:  # Only add non-empty subtitles
+                    subtitles.append((start_sec, end_sec, text))
+
+    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.
+
+    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":
+        # 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
+
+
+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'.
+
+    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

abogen/tts_supertonic.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+import logging
+import math
+import re
+from typing import Any, Iterable, Iterator, Optional
+
+import numpy as np
+
+
+logger = logging.getLogger(__name__)
+
+
+DEFAULT_SUPERTONIC_VOICES = ("M1", "M2", "M3", "M4", "M5", "F1", "F2", "F3", "F4", "F5")
+
+
+@dataclass
+class SupertonicSegment:
+    graphemes: str
+    audio: np.ndarray
+
+
+def _ensure_float32_mono(wav: Any) -> np.ndarray:
+    arr = np.asarray(wav, dtype="float32")
+    if arr.ndim == 2:
+        # (n, 1) or (1, n) or (n, channels)
+        if arr.shape[0] == 1 and arr.shape[1] > 1:
+            arr = arr.reshape(-1)
+        else:
+            arr = arr[:, 0]
+    return arr.reshape(-1)
+
+
+def _resample_linear(audio: np.ndarray, src_rate: int, dst_rate: int) -> np.ndarray:
+    if src_rate == dst_rate:
+        return audio
+    if audio.size == 0:
+        return audio
+    ratio = dst_rate / float(src_rate)
+    new_len = int(round(audio.size * ratio))
+    if new_len <= 1:
+        return np.zeros(0, dtype="float32")
+    x_old = np.linspace(0.0, 1.0, num=audio.size, endpoint=False)
+    x_new = np.linspace(0.0, 1.0, num=new_len, endpoint=False)
+    return np.interp(x_new, x_old, audio).astype("float32", copy=False)
+
+
+def _split_text(
+    text: str, *, split_pattern: Optional[str], max_chunk_length: int
+) -> list[str]:
+    stripped = (text or "").strip()
+    if not stripped:
+        return []
+    parts: list[str]
+    if split_pattern:
+        try:
+            parts = [p.strip() for p in re.split(split_pattern, stripped) if p.strip()]
+        except re.error:
+            parts = [stripped]
+    else:
+        parts = [stripped]
+
+    # Enforce max length by hard-splitting long parts.
+    result: list[str] = []
+    for part in parts:
+        if len(part) <= max_chunk_length:
+            result.append(part)
+            continue
+        start = 0
+        while start < len(part):
+            end = min(len(part), start + max_chunk_length)
+            # Try to split at whitespace.
+            if end < len(part):
+                ws = part.rfind(" ", start, end)
+                if ws > start + 40:
+                    end = ws
+            chunk = part[start:end].strip()
+            if chunk:
+                result.append(chunk)
+            start = end
+    return result
+
+
+_UNSUPPORTED_CHARS_RE = re.compile(
+    r"unsupported character\(s\):\s*(\[[^\]]*\])", re.IGNORECASE
+)
+
+
+def _parse_unsupported_characters(error: BaseException) -> list[str]:
+    """Best-effort extraction of unsupported characters from SuperTonic errors."""
+
+    message = " ".join(
+        str(part) for part in getattr(error, "args", ()) if part is not None
+    ) or str(error)
+    match = _UNSUPPORTED_CHARS_RE.search(message)
+    if not match:
+        return []
+
+    raw = match.group(1)
+    try:
+        value = ast.literal_eval(raw)
+    except Exception:
+        return []
+
+    if isinstance(value, (list, tuple)):
+        out: list[str] = []
+        for item in value:
+            if item is None:
+                continue
+            s = str(item)
+            if s:
+                out.append(s)
+        return out
+
+    if isinstance(value, str) and value:
+        return [value]
+
+    return []
+
+
+def _remove_unsupported_characters(text: str, unsupported: Iterable[str]) -> str:
+    result = text
+    for item in unsupported:
+        if not item:
+            continue
+        result = result.replace(item, "")
+    return result
+
+
+def _configure_supertonic_gpu() -> None:
+    """Patch supertonic's config to enable GPU acceleration if available."""
+    try:
+        import onnxruntime as ort
+
+        available = ort.get_available_providers()
+
+        # Use CUDA if available, skip TensorRT (requires extra libs not always present)
+        # TensorrtExecutionProvider may be listed as available but fail at runtime
+        # if TensorRT libraries (libnvinfer.so) are not installed
+        providers = []
+        if "CUDAExecutionProvider" in available:
+            providers.append("CUDAExecutionProvider")
+        providers.append("CPUExecutionProvider")
+
+        # Patch supertonic's config and loader before TTS import
+        # We must patch both because loader imports the value at module load time
+        import supertonic.config as supertonic_config
+        import supertonic.loader as supertonic_loader
+
+        supertonic_config.DEFAULT_ONNX_PROVIDERS = providers
+        supertonic_loader.DEFAULT_ONNX_PROVIDERS = providers
+        logger.info("Supertonic ONNX providers configured: %s", providers)
+    except Exception as exc:
+        logger.warning("Could not configure supertonic GPU providers: %s", exc)
+
+
+class SupertonicPipeline:
+    """Minimal adapter that mimics Kokoro's pipeline iteration interface."""
+
+    def __init__(
+        self,
+        *,
+        sample_rate: int,
+        auto_download: bool = True,
+        total_steps: int = 5,
+        max_chunk_length: int = 300,
+    ) -> None:
+        self.sample_rate = int(sample_rate)
+        self.total_steps = int(total_steps)
+        self.max_chunk_length = int(max_chunk_length)
+
+        # Configure GPU providers before importing TTS
+        _configure_supertonic_gpu()
+
+        try:
+            from supertonic import TTS  # type: ignore[import-not-found]
+        except Exception as exc:  # pragma: no cover
+            raise RuntimeError(
+                "Supertonic is not installed. Install it with `pip install supertonic`."
+            ) from exc
+
+        self._tts = TTS(auto_download=auto_download)
+
+    def __call__(
+        self,
+        text: str,
+        *,
+        voice: str,
+        speed: float,
+        split_pattern: Optional[str] = None,
+        total_steps: Optional[int] = None,
+    ) -> Iterator[SupertonicSegment]:
+        voice_name = (voice or "").strip() or "M1"
+        steps = int(total_steps) if total_steps is not None else self.total_steps
+        steps = max(2, min(15, steps))
+        speed_value = float(speed) if speed is not None else 1.0
+        speed_value = max(0.7, min(2.0, speed_value))
+
+        style = self._tts.get_voice_style(voice_name=voice_name)
+        chunks = _split_text(
+            text, split_pattern=split_pattern, max_chunk_length=self.max_chunk_length
+        )
+        for chunk in chunks:
+            chunk_to_speak = chunk
+            removed: set[str] = set()
+            last_exc: Exception | None = None
+
+            # SuperTonic can raise ValueError for unsupported characters; strip and retry.
+            for attempt in range(3):
+                try:
+                    wav, duration = self._tts.synthesize(
+                        text=chunk_to_speak,
+                        voice_style=style,
+                        total_steps=steps,
+                        speed=speed_value,
+                        max_chunk_length=self.max_chunk_length,
+                        silence_duration=0.0,
+                        verbose=False,
+                    )
+                    break
+                except ValueError as exc:
+                    last_exc = exc
+                    unsupported = _parse_unsupported_characters(exc)
+                    if not unsupported:
+                        raise
+
+                    removed.update(unsupported)
+                    sanitized = _remove_unsupported_characters(
+                        chunk_to_speak, unsupported
+                    ).strip()
+
+                    # If we didn't change anything, don't loop forever.
+                    if sanitized == chunk_to_speak.strip():
+                        raise
+
+                    chunk_to_speak = sanitized
+                    if not chunk_to_speak:
+                        logger.warning(
+                            "SuperTonic: dropped a chunk after removing unsupported characters: %s",
+                            sorted(removed),
+                        )
+                        break
+
+                    if attempt == 0:
+                        logger.warning(
+                            "SuperTonic: removed unsupported characters %s and retried.",
+                            sorted(removed),
+                        )
+            else:
+                # Exhausted retries.
+                assert last_exc is not None
+                raise last_exc
+
+            if not chunk_to_speak:
+                continue
+
+            audio = _ensure_float32_mono(wav)
+
+            # If duration is present, infer the source sample rate and resample if needed.
+            src_rate = self.sample_rate
+            try:
+                dur = float(duration)
+                if dur > 0 and audio.size > 0:
+                    inferred = int(round(audio.size / dur))
+                    if 8000 <= inferred <= 96000:
+                        src_rate = inferred
+            except Exception:
+                pass
+
+            if src_rate != self.sample_rate:
+                audio = _resample_linear(audio, src_rate, self.sample_rate)
+
+            yield SupertonicSegment(graphemes=chunk_to_speak, audio=audio)

abogen/utils.py

@@ -1,16 +1,63 @@
-import os
 import json
-import warnings
+import logging
+import os
 import platform
-import subprocess
 import re
+import shutil
+import subprocess
+import sys
+import warnings
 from threading import Thread
+from typing import Dict, Optional
+
+from functools import lru_cache
+
+from dotenv import load_dotenv, find_dotenv
+
+
+def _load_environment() -> None:
+    explicit_path = os.environ.get("ABOGEN_ENV_FILE")
+    if explicit_path:
+        load_dotenv(explicit_path, override=False)
+        return
+    dotenv_path = find_dotenv(usecwd=True)
+    if dotenv_path:
+        load_dotenv(dotenv_path, override=False)
+
+
+_load_environment()
 
-# suppress warnings and disable HF hub symlink warnings
-os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"
 warnings.filterwarnings("ignore")
 
 
+def detect_encoding(file_path):
+    try:
+        import chardet  # type: ignore[import-not-found]
+    except ImportError:  # pragma: no cover - optional dependency
+        chardet = None  # type: ignore[assignment]
+
+    try:
+        import charset_normalizer  # type: ignore[import-not-found]
+    except ImportError:  # pragma: no cover - optional dependency
+        charset_normalizer = None  # type: ignore[assignment]
+
+    with open(file_path, "rb") as f:
+        raw_data = f.read()
+    detected_encoding = None
+    for detectors in (charset_normalizer, chardet):
+        if detectors is None:
+            continue
+        try:
+            result = detectors.detect(raw_data)["encoding"]
+        except Exception:
+            continue
+        if result is not None:
+            detected_encoding = result
+            break
+    encoding = detected_encoding if detected_encoding else "utf-8"
+    return encoding.lower()
+
+
 def get_resource_path(package, resource):
     """
     Get the path to a resource file, with fallback to local file system.
@@ -32,6 +79,14 @@ def get_resource_path(package, resource):
     except (ImportError, FileNotFoundError):
         pass
 
+    # Always try to resolve as a relative path from this file
+    parts = package.split(".")
+    rel_path = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), *parts[1:], resource
+    )
+    if os.path.exists(rel_path):
+        return rel_path
+
     # Fallback to local file system
     try:
         # Extract the subdirectory from package name (e.g., 'assets' from 'abogen.assets')
@@ -50,23 +105,200 @@ def get_resource_path(package, resource):
 def get_version():
     """Return the current version of the application."""
     try:
-        with open(get_resource_path("abogen", "VERSION"), "r") as f:
+        version_path = get_resource_path("/", "VERSION")
+        if not version_path:
+            raise FileNotFoundError("VERSION resource missing")
+        with open(version_path, "r") as f:
             return f.read().strip()
     except Exception:
         return "Unknown"
 
 
 # Define config path
+def ensure_directory(path):
+    resolved = os.path.abspath(os.path.expanduser(str(path)))
+    os.makedirs(resolved, exist_ok=True)
+    return resolved
+
+
+@lru_cache(maxsize=1)
+def get_user_settings_dir():
+    override = os.environ.get("ABOGEN_SETTINGS_DIR")
+    if override:
+        return ensure_directory(override)
+
+    data_root = os.environ.get("ABOGEN_DATA") or os.environ.get("ABOGEN_DATA_DIR")
+    if data_root:
+        try:
+            return ensure_directory(os.path.join(data_root, "settings"))
+        except OSError:
+            pass
+
+    data_mount = "/data"
+    if os.path.isdir(data_mount):
+        try:
+            return ensure_directory(os.path.join(data_mount, "settings"))
+        except OSError:
+            pass
+
+    from platformdirs import user_config_dir
+
+    if platform.system() != "Windows":
+        legacy_dir = os.path.join(os.path.expanduser("~"), ".config", "abogen")
+        if os.path.exists(legacy_dir):
+            return ensure_directory(legacy_dir)
+
+    config_dir = user_config_dir(
+        "abogen", appauthor=False, roaming=True, ensure_exists=True
+    )
+    return ensure_directory(config_dir)
+
+
 def get_user_config_path():
-    if os.name == "nt":
-        config_dir = os.path.join(os.environ["APPDATA"], "abogen")
-    else:
-        config_dir = os.path.join(os.path.expanduser("~"), ".config", "abogen")
-    os.makedirs(config_dir, exist_ok=True)
-    return os.path.join(config_dir, "config.json")
+    return os.path.join(get_user_settings_dir(), "config.json")
 
 
-_sleep_procs = {"Darwin": None, "Linux": None}  # Store sleep prevention processes
+# Define cache path
+@lru_cache(maxsize=1)
+def get_user_cache_root():
+    logger = logging.getLogger(__name__)
+
+    def _try_paths(*paths):
+        last_error = None
+        for candidate in paths:
+            if not candidate:
+                continue
+            try:
+                return ensure_directory(candidate)
+            except OSError as exc:
+                last_error = exc
+                logger.debug("Unable to use cache directory %s: %s", candidate, exc)
+        if last_error is not None:
+            raise last_error
+
+    def _configure_cache_env(root: Optional[str]) -> None:
+        temp_root = None
+        if root:
+            try:
+                temp_root = ensure_directory(root)
+            except OSError:
+                temp_root = None
+
+        home_dir = os.environ.get("HOME")
+        if not home_dir:
+            home_dir = ensure_directory(os.path.join("/tmp", "abogen-home"))
+            os.environ["HOME"] = home_dir
+        else:
+            home_dir = ensure_directory(home_dir)
+
+        cache_base = os.environ.get("XDG_CACHE_HOME")
+        if cache_base:
+            cache_base = ensure_directory(cache_base)
+        elif temp_root:
+            cache_base = temp_root
+            os.environ["XDG_CACHE_HOME"] = cache_base
+        else:
+            cache_base = ensure_directory(os.path.join(home_dir, ".cache"))
+            os.environ["XDG_CACHE_HOME"] = cache_base
+
+        hf_cache = os.environ.get("HF_HOME")
+        if hf_cache:
+            hf_cache = ensure_directory(hf_cache)
+        elif temp_root:
+            hf_cache = ensure_directory(os.path.join(temp_root, "huggingface"))
+            os.environ["HF_HOME"] = hf_cache
+        else:
+            hf_cache = ensure_directory(os.path.join(cache_base, "huggingface"))
+            os.environ["HF_HOME"] = hf_cache
+
+        for env_var in ("HUGGINGFACE_HUB_CACHE", "TRANSFORMERS_CACHE"):
+            os.environ.setdefault(env_var, hf_cache)
+
+        os.environ.setdefault("ABOGEN_INTERNAL_CACHE_ROOT", cache_base)
+
+    cache_root: Optional[str] = None
+
+    override = os.environ.get("ABOGEN_TEMP_DIR")
+    if override:
+        try:
+            cache_root = ensure_directory(override)
+        except OSError as exc:
+            logger.warning("ABOGEN_TEMP_DIR=%s is not writable: %s", override, exc)
+
+    if cache_root is None:
+        from platformdirs import user_cache_dir
+
+        default_cache = user_cache_dir("abogen", appauthor=False, opinion=True)
+
+        data_root = os.environ.get("ABOGEN_DATA") or os.environ.get("ABOGEN_DATA_DIR")
+        fallback_paths = [
+            default_cache,
+            os.path.join(data_root, "cache") if data_root else None,
+            "/data/cache",
+            "/tmp/abogen-cache",
+        ]
+
+        try:
+            cache_root = _try_paths(*fallback_paths)
+        except OSError:
+            # Final safety net – attempt a tmp directory unique to this process.
+            tmp_candidate = os.path.join("/tmp", f"abogen-cache-{os.getpid()}")
+            logger.warning("Falling back to temp cache directory %s", tmp_candidate)
+            cache_root = ensure_directory(tmp_candidate)
+
+    if cache_root is None:
+        raise RuntimeError("Unable to determine cache directory")
+
+    _configure_cache_env(cache_root)
+    return cache_root
+
+
+def get_internal_cache_root():
+    root = os.environ.get("ABOGEN_INTERNAL_CACHE_ROOT") or os.environ.get(
+        "XDG_CACHE_HOME"
+    )
+    if root:
+        return ensure_directory(root)
+    home_dir = os.environ.get("HOME") or os.path.join("/tmp", "abogen-home")
+    home_dir = ensure_directory(home_dir)
+    return ensure_directory(os.path.join(home_dir, ".cache"))
+
+
+def get_internal_cache_path(folder=None):
+    base = get_internal_cache_root()
+    if folder:
+        return ensure_directory(os.path.join(base, folder))
+    return base
+
+
+def get_user_cache_path(folder=None):
+    base = get_user_cache_root()
+    if folder:
+        return ensure_directory(os.path.join(base, folder))
+    return base
+
+
+@lru_cache(maxsize=1)
+def get_user_output_root():
+    override = os.environ.get("ABOGEN_OUTPUT_DIR") or os.environ.get(
+        "ABOGEN_OUTPUT_ROOT"
+    )
+    if override:
+        return ensure_directory(override)
+    return ensure_directory(os.path.join(get_user_cache_root(), "outputs"))
+
+
+def get_user_output_path(folder=None):
+    base = get_user_output_root()
+    if folder:
+        return ensure_directory(os.path.join(base, folder))
+    return base
+
+
+_sleep_procs: Dict[str, Optional[subprocess.Popen[str]]] = {
+    "Darwin": None,
+    "Linux": None,
+}  # Store sleep prevention processes
 
 
 def clean_text(text, *args, **kwargs):
@@ -84,6 +316,102 @@ def clean_text(text, *args, **kwargs):
     return text
 
 
+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:
+        handler = logging.StreamHandler(sys.stdout)
+        formatter = logging.Formatter("%(message)s")
+        handler.setFormatter(formatter)
+        root.addHandler(handler)
+        root.setLevel(logging.INFO)
+
+    # Determine shell usage: use shell only for string commands
+    use_shell = isinstance(cmd, str)
+    if use_shell:
+        logger.warning(
+            "Security Warning: create_process called with string command. Prefer using a list of arguments to avoid shell injection risks."
+        )
+
+    kwargs = {
+        "shell": use_shell,
+        "stdout": subprocess.PIPE,
+        "stderr": subprocess.STDOUT,
+        "bufsize": 1,  # Line buffered
+    }
+
+    if text:
+        # Configure for text I/O
+        kwargs["text"] = True
+        kwargs["encoding"] = default_encoding
+        kwargs["errors"] = "replace"
+    else:
+        # Configure for binary I/O
+        kwargs["text"] = False
+        # For binary mode, 'encoding' and 'errors' arguments must not be passed to Popen
+        kwargs["bufsize"] = 0  # Use unbuffered mode for binary data
+
+    if stdin is not None:
+        kwargs["stdin"] = stdin
+
+    if platform.system() == "Windows":
+        startupinfo = subprocess.STARTUPINFO()  # type: ignore[attr-defined]
+        startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW  # type: ignore[attr-defined]
+        startupinfo.wShowWindow = subprocess.SW_HIDE  # type: ignore[attr-defined]
+        kwargs.update(
+            {
+                "startupinfo": startupinfo,
+                "creationflags": subprocess.CREATE_NO_WINDOW,  # type: ignore[attr-defined]
+            }
+        )
+
+    # Print the command being executed
+    print(f"Executing: {cmd if isinstance(cmd, str) else ' '.join(cmd)}")
+
+    proc = subprocess.Popen(cmd, **kwargs)
+
+    # Stream output to console in real-time if not capturing
+    if proc.stdout and not capture_output:
+
+        def _stream_output(stream):
+            if text:
+                # For text mode, read character by character for real-time output
+                while True:
+                    char = stream.read(1)
+                    if not char:
+                        break
+                    # Direct write to stdout for immediate feedback
+                    sys.stdout.write(char)
+                    sys.stdout.flush()
+            else:
+                # For binary mode, read small chunks
+                while True:
+                    chunk = stream.read(1)  # Read byte by byte for real-time output
+                    if not chunk:
+                        break
+                    try:
+                        # Try to decode binary data for display
+                        sys.stdout.write(
+                            chunk.decode(default_encoding, errors="replace")
+                        )
+                        sys.stdout.flush()
+                    except Exception:
+                        pass
+            stream.close()
+
+        # Start a daemon thread to handle output streaming
+        Thread(target=_stream_output, args=(proc.stdout,), daemon=True).start()
+
+    return proc
+
+
 def load_config():
     try:
         with open(get_user_config_path(), "r", encoding="utf-8") as f:
@@ -101,50 +429,87 @@ def save_config(config):
 
 
 def calculate_text_length(text):
-    # Remove double newlines (replace them with single newlines)
-    cleaned_text = text.replace("\n\n", "")
+    # 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(cleaned_text)
+    char_count = len(text)
     return char_count
 
 
 def get_gpu_acceleration(enabled):
-    from torch.cuda import is_available
+    try:
+        import torch  # type: ignore[import-not-found]
+        from torch.cuda import is_available as cuda_available  # type: ignore[import-not-found]
 
-    if not enabled:
-        return "CUDA GPU available but using CPU.", False
+        if not enabled:
+            return "GPU available but using CPU.", False
 
-    if is_available():
-        return "CUDA GPU available and enabled.", True
-    return "CUDA GPU is not available. Using CPU.", False
+        # Check for Apple Silicon MPS
+        if platform.system() == "Darwin" and platform.processor() == "arm":
+            if torch.backends.mps.is_available():
+                return "MPS GPU available and enabled.", True
+            else:
+                return "MPS GPU not available on Apple Silicon. Using CPU.", False
+
+        # Check for CUDA
+        if cuda_available():
+            return "CUDA GPU available and enabled.", True
+
+        # Gather CUDA diagnostic info if not available
+        try:
+            cuda_devices = torch.cuda.device_count()
+            cuda_error = (
+                torch.cuda.get_device_name(0)
+                if cuda_devices > 0
+                else "No devices found"
+            )
+        except Exception as e:
+            cuda_error = str(e)
+        return f"CUDA GPU is not available. Using CPU. ({cuda_error})", False
+    except Exception as e:
+        return f"Error checking GPU: {e}", False
 
 
 def prevent_sleep_start():
+    from abogen.constants import PROGRAM_NAME
+
     system = platform.system()
     if system == "Windows":
         import ctypes
 
-        ctypes.windll.kernel32.SetThreadExecutionState(
+        ctypes.windll.kernel32.SetThreadExecutionState(  # type: ignore[attr-defined]
             0x80000000 | 0x00000001 | 0x00000040
-        )  # ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_AWAYMODE_REQUIRED
+        )
     elif system == "Darwin":
-        _sleep_procs["Darwin"] = subprocess.Popen(["caffeinate"])
+        _sleep_procs["Darwin"] = create_process(["caffeinate"])
     elif system == "Linux":
-        try:
-            _sleep_procs["Linux"] = subprocess.Popen(
+        # Add program name and reason for inhibition
+        program_name = PROGRAM_NAME
+        reason = "Prevent sleep during abogen process"
+        # Only attempt to use systemd-inhibit if it's available on the system.
+        if shutil.which("systemd-inhibit"):
+            _sleep_procs["Linux"] = create_process(
                 [
                     "systemd-inhibit",
+                    f"--who={program_name}",
+                    f"--why={reason}",
                     "--what=sleep",
-                    "--why=TextToAudiobook conversion",
+                    "--mode=block",
                     "sleep",
-                    "999999",
+                    "infinity",
                 ]
             )
-        except Exception:
-            try:
-                subprocess.Popen(["xdg-screensaver", "reset"])
-            except Exception:
-                pass
+        else:
+            # Non-systemd distro or systemd tools not installed: skip inhibition rather than crash
+            print(
+                "systemd-inhibit not found: skipping sleep inhibition on this Linux system."
+            )
 
 
 def prevent_sleep_end():
@@ -152,18 +517,21 @@ def prevent_sleep_end():
     if system == "Windows":
         import ctypes
 
-        ctypes.windll.kernel32.SetThreadExecutionState(0x80000000)  # ES_CONTINUOUS
-    elif system in ("Darwin", "Linux") and _sleep_procs[system]:
-        try:
-            _sleep_procs[system].terminate()
-            _sleep_procs[system] = None
-        except Exception:
-            pass
+        ctypes.windll.kernel32.SetThreadExecutionState(0x80000000)  # type: ignore[attr-defined]
+    elif system in ("Darwin", "Linux"):
+        proc = _sleep_procs.get(system)
+        if proc:
+            try:
+                proc.terminate()
+            except Exception:
+                pass
+            finally:
+                _sleep_procs[system] = None
 
 
 def load_numpy_kpipeline():
     import numpy as np
-    from kokoro import KPipeline
+    from kokoro import KPipeline  # type: ignore[import-not-found]
 
     return np, KPipeline
 

abogen/voice_cache.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import os
+import threading
+from typing import Callable, Dict, Iterable, Optional, Set, Tuple
+
+try:  # pragma: no cover - optional dependency guard
+    from huggingface_hub import hf_hub_download  # type: ignore
+    from huggingface_hub.utils import LocalEntryNotFoundError  # type: ignore
+except Exception:  # pragma: no cover - import fallback
+    hf_hub_download = None  # type: ignore[assignment]
+    LocalEntryNotFoundError = None  # type: ignore[assignment]
+
+if LocalEntryNotFoundError is None:  # pragma: no cover - fallback for tests
+
+    class LocalEntryNotFoundError(Exception):
+        pass
+
+
+from abogen.constants import VOICES_INTERNAL
+
+_CACHE_LOCK = threading.Lock()
+_CACHED_VOICES: Set[str] = set()
+_BOOTSTRAP_LOCK = threading.Lock()
+_BOOTSTRAPPED = False
+
+
+def _normalize_targets(voices: Optional[Iterable[str]]) -> Set[str]:
+    if not voices:
+        return set(VOICES_INTERNAL)
+    normalized: Set[str] = set()
+    for voice in voices:
+        if not voice:
+            continue
+        voice_id = str(voice).strip()
+        if not voice_id:
+            continue
+        if voice_id in VOICES_INTERNAL:
+            normalized.add(voice_id)
+    return normalized
+
+
+def ensure_voice_assets(
+    voices: Optional[Iterable[str]] = None,
+    *,
+    repo_id: str = "hexgrad/Kokoro-82M",
+    cache_dir: Optional[str] = None,
+    on_progress: Optional[Callable[[str], None]] = None,
+) -> Tuple[Set[str], Dict[str, str]]:
+    """Ensure Kokoro voice weight files are present locally.
+
+    Returns a tuple of (downloaded voices, errors) where errors maps the
+    voice id to the underlying exception message.
+    """
+
+    if hf_hub_download is None:
+        raise RuntimeError("huggingface_hub is required to cache voices")
+
+    effective_cache_dir = cache_dir
+    if effective_cache_dir is None:
+        env_cache_dir = os.environ.get("ABOGEN_VOICE_CACHE_DIR", "").strip()
+        effective_cache_dir = env_cache_dir or None
+
+    targets = _normalize_targets(voices)
+    if not targets:
+        return set(), {}
+
+    with _CACHE_LOCK:
+        missing = [voice for voice in targets if voice not in _CACHED_VOICES]
+
+    downloaded: Set[str] = set()
+    errors: Dict[str, str] = {}
+
+    for voice_id in missing:
+        if on_progress:
+            on_progress(f"Fetching voice asset '{voice_id}'")
+        try:
+            downloaded_flag = _ensure_single_voice_asset(
+                voice_id,
+                repo_id=repo_id,
+                cache_dir=effective_cache_dir,
+            )
+        except Exception as exc:  # pragma: no cover - network variance
+            errors[voice_id] = str(exc)
+            continue
+
+        if downloaded_flag:
+            downloaded.add(voice_id)
+        with _CACHE_LOCK:
+            _CACHED_VOICES.add(voice_id)
+
+    return downloaded, errors
+
+
+def bootstrap_voice_cache(
+    voices: Optional[Iterable[str]] = None,
+    *,
+    repo_id: str = "hexgrad/Kokoro-82M",
+    cache_dir: Optional[str] = None,
+    on_progress: Optional[Callable[[str], None]] = None,
+) -> Tuple[Set[str], Dict[str, str]]:
+    """Ensure voices are cached once per process.
+
+    Subsequent calls are no-ops and return empty structures.
+    """
+
+    global _BOOTSTRAPPED
+    with _BOOTSTRAP_LOCK:
+        if _BOOTSTRAPPED:
+            return set(), {}
+        downloaded, errors = ensure_voice_assets(
+            voices,
+            repo_id=repo_id,
+            cache_dir=cache_dir,
+            on_progress=on_progress,
+        )
+        _BOOTSTRAPPED = True
+        return downloaded, errors
+
+
+def _ensure_single_voice_asset(
+    voice_id: str,
+    *,
+    repo_id: str,
+    cache_dir: Optional[str],
+) -> bool:
+    if hf_hub_download is None:
+        raise RuntimeError("huggingface_hub is required to cache voices")
+
+    filename = f"voices/{voice_id}.pt"
+    common_kwargs = {
+        "repo_id": repo_id,
+        "filename": filename,
+    }
+    if cache_dir is not None:
+        common_kwargs["cache_dir"] = cache_dir
+
+    try:
+        hf_hub_download(local_files_only=True, **common_kwargs)
+        return False
+    except LocalEntryNotFoundError:
+        pass
+
+    hf_hub_download(resume_download=True, **common_kwargs)
+    return True

abogen/voice_formula_gui.py

@@ -0,0 +1,11 @@
+"""Backwards-compatible re-export of the PyQt voice formula dialog.
+
+The actual implementation lives in abogen.pyqt.voice_formula_gui.
+"""
+
+from __future__ import annotations
+
+from abogen.pyqt.voice_formula_gui import *  # noqa: F401, F403
+from abogen.pyqt.voice_formula_gui import VoiceFormulaDialog
+
+__all__ = ["VoiceFormulaDialog"]

abogen/voice_formulas.py

@@ -0,0 +1,81 @@
+import re
+from typing import List, Tuple
+
+from abogen.constants import VOICES_INTERNAL
+
+
+# Calls parsing and loads the voice to gpu or cpu
+def get_new_voice(pipeline, formula, use_gpu):
+    try:
+        weighted_voice = parse_voice_formula(pipeline, formula)
+        # device = "cuda" if use_gpu else "cpu"
+        # Setting the device "cuda" gives "Error occurred: split_with_sizes(): argument 'split_sizes' (position 2)"
+        # error when the device is gpu. So disabling this for now.
+        device = "cpu"
+        return weighted_voice.to(device)
+    except Exception as e:
+        raise ValueError(f"Failed to create voice: {str(e)}")
+
+
+def parse_formula_terms(formula: str) -> List[Tuple[str, float]]:
+    if not formula or not formula.strip():
+        raise ValueError("Empty voice formula")
+
+    terms: List[Tuple[str, float]] = []
+    for segment in formula.split("+"):
+        part = segment.strip()
+        if not part:
+            continue
+        if "*" not in part:
+            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:
+            raise ValueError(f"Unknown voice: {voice_name}")
+        try:
+            weight = float(raw_weight.strip())
+        except ValueError as exc:
+            raise ValueError(f"Invalid weight for {voice_name}") from exc
+        if weight <= 0:
+            raise ValueError(f"Weight for {voice_name} must be positive")
+        terms.append((voice_name, weight))
+
+    if not terms:
+        raise ValueError("Voice weights must sum to a positive value")
+
+    return terms
+
+
+def parse_voice_formula(pipeline, formula):
+    terms = parse_formula_terms(formula)
+
+    total_weight = sum(weight for _, weight in terms)
+    if total_weight <= 0:
+        raise ValueError("Voice weights must sum to a positive value")
+
+    weighted_sum = None
+
+    for voice_name, weight in terms:
+        normalized_weight = weight / total_weight if total_weight > 0 else weight
+
+        voice_tensor = pipeline.load_single_voice(voice_name)
+
+        if weighted_sum is None:
+            weighted_sum = normalized_weight * voice_tensor
+        else:
+            weighted_sum += normalized_weight * voice_tensor
+
+    if weighted_sum is None:
+        raise ValueError("Voice formula produced no components")
+
+    return weighted_sum
+
+
+def calculate_sum_from_formula(formula):
+    weights = re.findall(r"\* *([\d.]+)", formula)
+    total_sum = sum(float(weight) for weight in weights)
+    return total_sum
+
+
+def extract_voice_ids(formula: str) -> List[str]:
+    return [voice for voice, _ in parse_formula_terms(formula)]

abogen/voice_profiles.py

@@ -0,0 +1,229 @@
+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.utils import get_user_config_path
+
+
+def _get_profiles_path():
+    config_path = get_user_config_path()
+    config_dir = os.path.dirname(config_path)
+    return os.path.join(config_dir, "voice_profiles.json")
+
+
+def load_profiles():
+    """Load all voice profiles from JSON file."""
+    path = _get_profiles_path()
+    if os.path.exists(path):
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                # always expect abogen_voice_profiles wrapper
+                if isinstance(data, dict) and "abogen_voice_profiles" in data:
+                    return data["abogen_voice_profiles"]
+                # fallback: treat as profiles dict
+                if isinstance(data, dict):
+                    return data
+        except Exception:
+            return {}
+    return {}
+
+
+def save_profiles(profiles):
+    """Save all voice profiles to JSON file."""
+    path = _get_profiles_path()
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        # always save with abogen_voice_profiles wrapper
+        json.dump({"abogen_voice_profiles": profiles}, f, indent=2)
+
+
+def delete_profile(name):
+    """Remove a profile by name."""
+    profiles = load_profiles()
+    if name in profiles:
+        del profiles[name]
+        save_profiles(profiles)
+
+
+def duplicate_profile(src, dest):
+    """Duplicate an existing profile."""
+    profiles = load_profiles()
+    if src in profiles and dest:
+        profiles[dest] = profiles[src]
+        save_profiles(profiles)
+
+
+def export_profiles(export_path):
+    """Export all profiles to specified JSON file."""
+    profiles = load_profiles()
+    with open(export_path, "w", encoding="utf-8") as f:
+        json.dump({"abogen_voice_profiles": profiles}, f, indent=2)
+
+
+def serialize_profiles() -> Dict[str, Dict[str, Iterable[Tuple[str, float]]]]:
+    """Return profiles in canonical dictionary form."""
+    return load_profiles()
+
+
+def _normalize_supertonic_voice(value: Any) -> str:
+    raw = str(value or "").strip().upper()
+    return raw if raw in DEFAULT_SUPERTONIC_VOICES else "M1"
+
+
+def _coerce_supertonic_steps(value: Any) -> int:
+    try:
+        steps = int(value)
+    except (TypeError, ValueError):
+        return 5
+    return max(2, min(15, steps))
+
+
+def _coerce_supertonic_speed(value: Any) -> float:
+    try:
+        speed = float(value)
+    except (TypeError, ValueError):
+        return 1.0
+    return max(0.7, min(2.0, speed))
+
+
+def normalize_profile_entry(entry: Any) -> Dict[str, Any]:
+    """Normalize a stored profile entry.
+
+    Backwards compatible:
+    - Legacy Kokoro-only entries: {language, voices}
+    - New entries: include provider.
+    """
+
+    if not isinstance(entry, dict):
+        return {}
+
+    provider = str(entry.get("provider") or "kokoro").strip().lower()
+    if provider not in {"kokoro", "supertonic"}:
+        provider = "kokoro"
+
+    language = str(entry.get("language") or "a").strip().lower() or "a"
+
+    if provider == "supertonic":
+        return {
+            "provider": "supertonic",
+            "language": language,
+            "voice": _normalize_supertonic_voice(
+                entry.get("voice") or entry.get("voice_name") or entry.get("name")
+            ),
+            "total_steps": _coerce_supertonic_steps(
+                entry.get("total_steps")
+                or entry.get("supertonic_total_steps")
+                or entry.get("quality")
+            ),
+            "speed": _coerce_supertonic_speed(
+                entry.get("speed") or entry.get("supertonic_speed")
+            ),
+        }
+
+    voices = _normalize_voice_entries(entry.get("voices", []))
+    if not voices:
+        return {}
+    return {
+        "provider": "kokoro",
+        "language": language,
+        "voices": voices,
+    }
+
+
+def _normalize_voice_entries(entries: Iterable) -> List[Tuple[str, float]]:
+    normalized: List[Tuple[str, float]] = []
+    for item in entries or []:
+        if isinstance(item, dict):
+            voice = item.get("id") or item.get("voice")
+            weight = item.get("weight")
+        elif isinstance(item, (list, tuple)) and len(item) >= 2:
+            voice, weight = item[0], item[1]
+        else:
+            continue
+        if voice not in VOICES_INTERNAL:
+            continue
+        if weight is None:
+            continue
+        try:
+            weight_val = float(weight)
+        except (TypeError, ValueError):
+            continue
+        if weight_val <= 0:
+            continue
+        normalized.append((voice, weight_val))
+    return normalized
+
+
+def normalize_voice_entries(entries: Iterable) -> List[Tuple[str, float]]:
+    """Public helper to normalize voice-weight pairs from arbitrary payloads."""
+
+    return _normalize_voice_entries(entries)
+
+
+def save_profile(name: str, *, language: str, voices: Iterable) -> None:
+    """Persist a single profile after validating its data."""
+
+    name = (name or "").strip()
+    if not name:
+        raise ValueError("Profile name is required")
+
+    normalized = _normalize_voice_entries(voices)
+    if not normalized:
+        raise ValueError("At least one voice with a weight above zero is required")
+
+    if not language:
+        language = "a"
+
+    profiles = load_profiles()
+    profiles[name] = {"provider": "kokoro", "language": language, "voices": normalized}
+    save_profiles(profiles)
+
+
+def remove_profile(name: str) -> None:
+    delete_profile(name)
+
+
+def import_profiles_data(data: Dict, *, replace_existing: bool = False) -> List[str]:
+    """Merge profiles from a dictionary structure and persist them.
+
+    Returns the list of profile names that were added or updated.
+    """
+
+    if not isinstance(data, dict):
+        raise ValueError("Invalid profile payload")
+
+    if "abogen_voice_profiles" in data:
+        data = data["abogen_voice_profiles"]
+
+    if not isinstance(data, dict):
+        raise ValueError("Invalid profile payload")
+
+    current = load_profiles()
+    updated: List[str] = []
+    for name, entry in data.items():
+        normalized = normalize_profile_entry(entry)
+        if not normalized:
+            continue
+        if name in current and not replace_existing:
+            # skip duplicates unless explicit replacement is requested
+            continue
+        current[name] = normalized
+        updated.append(name)
+
+    if updated:
+        save_profiles(current)
+    return updated
+
+
+def export_profiles_payload(names: Iterable[str] | None = None) -> Dict[str, Dict]:
+    """Return profiles limited to the provided names for download/export."""
+
+    profiles = load_profiles()
+    if names is None:
+        subset = profiles
+    else:
+        subset = {name: profiles[name] for name in names if name in profiles}
+    return {"abogen_voice_profiles": subset}

abogen/webui/Dockerfile

@@ -0,0 +1,74 @@
+FROM nvidia/cuda:12.6.3-cudnn-runtime-ubuntu22.04
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+  PYTHONUNBUFFERED=1 \
+  PIP_NO_CACHE_DIR=1 \
+  VIRTUAL_ENV=/opt/venv \
+  PATH=/opt/venv/bin:$PATH
+
+ARG TORCH_INDEX_URL=https://download.pytorch.org/whl/cu126
+ARG TORCH_VERSION=
+ARG USE_GPU=true
+
+RUN apt-get update \
+  && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+    python3 \
+    python3-venv \
+    python3-pip \
+    ffmpeg \
+    libsndfile1 \
+    libgl1 \
+    libglib2.0-0 \
+  && apt-get clean \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN python3 -m venv "$VIRTUAL_ENV"
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY abogen ./abogen
+
+RUN pip install --upgrade pip \
+  && if [ -n "$TORCH_VERSION" ]; then \
+       pip install torch=="$TORCH_VERSION" torchvision=="$TORCH_VERSION" torchaudio=="$TORCH_VERSION" --index-url "$TORCH_INDEX_URL"; \
+     else \
+       pip install torch torchvision torchaudio --index-url "$TORCH_INDEX_URL"; \
+     fi \
+  && pip install --no-cache-dir . \
+    https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl \
+  && pip install --no-cache-dir "mutagen>=1.47.0"
+
+# Install onnxruntime-gpu for CUDA acceleration (supertonic uses ONNX Runtime)
+# Set USE_GPU=false to skip this for CPU-only deployments
+RUN if [ "$USE_GPU" = "true" ]; then \
+      pip install --no-cache-dir onnxruntime-gpu; \
+    fi
+
+ENV ABOGEN_HOST=0.0.0.0 \
+  ABOGEN_PORT=8808
+
+EXPOSE 8808
+
+VOLUME ["/data"]
+
+ENV ABOGEN_UPLOAD_ROOT=/data/uploads \
+  ABOGEN_OUTPUT_ROOT=/data/outputs \
+  ABOGEN_TEMP_DIR=/data/cache \
+  ABOGEN_VOICE_CACHE_DIR=/data/voice-cache \
+  HF_HOME=/data/huggingface \
+  HUGGINGFACE_HUB_CACHE=/data/huggingface/hub
+
+# Copy and setup entrypoint script
+COPY abogen/webui/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# Create non-root user and setup permissions
+RUN useradd -m -u 1000 abogen \
+    && mkdir -p /data/uploads /data/outputs /data/cache /data/voice-cache /data/huggingface \
+    && chown -R abogen:abogen /data /app
+
+USER abogen
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["abogen-web"]

abogen/webui/__init__.py

@@ -0,0 +1,9 @@
+__all__ = ["create_app"]
+
+
+def __getattr__(name: str):
+	if name == "create_app":
+		from .app import create_app
+
+		return create_app
+	raise AttributeError(name)

abogen/webui/app.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+from flask import Flask
+
+from abogen.utils import get_user_cache_path, get_user_output_path, get_user_settings_dir
+
+from .conversion_runner import run_conversion_job
+from .service import build_service
+
+
+class _SuppressSuccessfulAccessFilter(logging.Filter):
+    """Filter out successful (HTTP 200) werkzeug access logs."""
+
+    def filter(self, record: logging.LogRecord) -> bool:  # pragma: no cover - small utility
+        try:
+            message = record.getMessage()
+        except Exception:  # pragma: no cover - defensive
+            return True
+        # Werkzeug access logs include the status code near the end, e.g.
+        # "GET /path HTTP/1.1" 200 -
+        # Treat any 2xx response as success to suppress.
+        return " 200 " not in message and " 201 " not in message and " 204 " not in message
+
+
+_access_log_filter_attached = False
+
+
+def _default_dirs() -> tuple[Path, Path]:
+    uploads_override = os.environ.get("ABOGEN_UPLOAD_ROOT")
+    outputs_override = os.environ.get("ABOGEN_OUTPUT_ROOT")
+
+    if uploads_override:
+        uploads = Path(os.path.expanduser(uploads_override)).resolve()
+    else:
+        uploads = Path(get_user_cache_path("web/uploads"))
+
+    if outputs_override:
+        outputs = Path(os.path.expanduser(outputs_override)).resolve()
+    else:
+        outputs = Path(get_user_output_path("web"))
+
+    uploads.mkdir(parents=True, exist_ok=True)
+    outputs.mkdir(parents=True, exist_ok=True)
+    return uploads, outputs
+
+
+def _get_secret_key() -> str:
+    env_key = os.environ.get("ABOGEN_SECRET_KEY")
+    if env_key:
+        return env_key
+
+    try:
+        settings_dir = Path(get_user_settings_dir())
+        settings_dir.mkdir(parents=True, exist_ok=True)
+        secret_file = settings_dir / ".secret_key"
+        if secret_file.exists():
+            return secret_file.read_text(encoding="utf-8").strip()
+
+        key = os.urandom(24).hex()
+        secret_file.write_text(key, encoding="utf-8")
+        return key
+    except Exception:
+        # Fallback if we can't write to settings dir
+        return os.urandom(24).hex()
+
+
+def create_app(config: Optional[dict[str, Any]] = None) -> Flask:
+    uploads_dir, outputs_dir = _default_dirs()
+
+    app = Flask(
+        __name__,
+        static_folder="static",
+        template_folder="templates",
+    )
+    base_config = {
+        "SECRET_KEY": _get_secret_key(),
+        "UPLOAD_FOLDER": str(uploads_dir),
+        "OUTPUT_FOLDER": str(outputs_dir),
+        "MAX_CONTENT_LENGTH": 1024 * 1024 * 400,  # 400 MB uploads
+    }
+    if config:
+        base_config.update(config)
+    app.config.update(base_config)
+
+    service = build_service(
+        runner=run_conversion_job,
+        output_root=Path(app.config["OUTPUT_FOLDER"]),
+        uploads_root=Path(app.config["UPLOAD_FOLDER"]),
+    )
+    app.extensions["conversion_service"] = service
+
+    from abogen.webui.routes import (
+        main_bp,
+        jobs_bp,
+        settings_bp,
+        voices_bp,
+        entities_bp,
+        books_bp,
+        api_bp,
+    )
+
+    app.register_blueprint(main_bp)
+    app.register_blueprint(jobs_bp, url_prefix="/jobs")
+    app.register_blueprint(settings_bp, url_prefix="/settings")
+    app.register_blueprint(voices_bp, url_prefix="/voices")
+    app.register_blueprint(entities_bp, url_prefix="/overrides")
+    app.register_blueprint(books_bp, url_prefix="/find-books")
+    app.register_blueprint(api_bp, url_prefix="/api")
+
+    atexit.register(service.shutdown)
+
+    global _access_log_filter_attached
+    if not _access_log_filter_attached:
+        logging.getLogger("werkzeug").addFilter(_SuppressSuccessfulAccessFilter())
+        _access_log_filter_attached = True
+
+    return app
+
+
+def main() -> None:
+    app = create_app()
+    host = os.environ.get("ABOGEN_HOST", "0.0.0.0")
+    port = int(os.environ.get("ABOGEN_PORT", "8808"))
+    debug = os.environ.get("ABOGEN_DEBUG", "false").lower() == "true"
+    app.run(host=host, port=port, debug=debug)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

abogen/webui/debug_tts_runner.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
+
+import numpy as np
+
+from abogen.debug_tts_samples import MARKER_PREFIX, MARKER_SUFFIX, build_debug_epub, iter_expected_codes
+from abogen.kokoro_text_normalization import normalize_for_pipeline
+from abogen.normalization_settings import build_apostrophe_config
+from abogen.text_extractor import extract_from_path
+from abogen.voice_cache import ensure_voice_assets
+from abogen.webui.conversion_runner import SAMPLE_RATE, SPLIT_PATTERN, _select_device, _to_float32, _resolve_voice, _spec_to_voice_ids
+from abogen.utils import load_numpy_kpipeline
+
+
+_MARKER_RE = re.compile(re.escape(MARKER_PREFIX) + r"(?P<code>[A-Z0-9_]+)" + re.escape(MARKER_SUFFIX))
+
+
+@dataclass(frozen=True)
+class DebugWavArtifact:
+    label: str
+    filename: str
+    code: Optional[str] = None
+    text: Optional[str] = None
+
+
+def _resolve_voice_setting(value: str) -> tuple[str, Optional[str], Optional[str]]:
+    """Resolve settings voice strings into a pipeline-ready voice spec.
+
+    Supports "profile:<name>" by converting it into a concrete voice formula.
+    Returns (resolved_voice_spec, profile_name, profile_language).
+    """
+
+    from abogen.webui.routes.utils.voice import resolve_voice_setting
+
+    return resolve_voice_setting(value)
+
+
+def _load_pipeline(language: str, use_gpu: bool) -> Any:
+    device = "cpu"
+    if use_gpu:
+        device = _select_device()
+    _np, KPipeline = load_numpy_kpipeline()
+    return KPipeline(lang_code=language, repo_id="hexgrad/Kokoro-82M", device=device)
+
+
+def _extract_cases_from_text(text: str) -> List[Tuple[str, str]]:
+    raw = str(text or "")
+    matches = list(_MARKER_RE.finditer(raw))
+    cases: List[Tuple[str, str]] = []
+    if not matches:
+        return cases
+    for idx, match in enumerate(matches):
+        code = match.group("code")
+        start = match.end()
+        end = matches[idx + 1].start() if idx + 1 < len(matches) else len(raw)
+        snippet = raw[start:end]
+        # Keep it small and predictable: collapse whitespace.
+        snippet = " ".join(snippet.strip().split())
+        cases.append((code, snippet))
+    return cases
+
+
+def _spoken_id(code: str) -> str:
+    # Make IDs pronounceable and stable (avoid reading as a word).
+    out: List[str] = []
+    for ch in str(code or ""):
+        if ch == "_":
+            out.append(" ")
+        elif ch.isalnum():
+            out.append(ch)
+        else:
+            out.append(" ")
+    # Add spaces between alnum to encourage letter-by-letter reading.
+    spaced = " ".join("".join(out).split())
+    return spaced
+
+
+def run_debug_tts_wavs(
+    *,
+    output_root: Path,
+    settings: Mapping[str, Any],
+    epub_path: Optional[Path] = None,
+) -> Dict[str, Any]:
+    """Generate WAV artifacts for the debug EPUB samples.
+
+    Writes:
+    - overall.wav: concatenation of all samples
+    - case_<CODE>.wav: each sample rendered separately
+    - manifest.json: metadata + file list
+    """
+
+    output_root = Path(output_root)
+    output_root.mkdir(parents=True, exist_ok=True)
+
+    run_id = uuid.uuid4().hex
+    run_dir = output_root / "debug" / run_id
+    run_dir.mkdir(parents=True, exist_ok=True)
+
+    if epub_path is None:
+        epub_path = run_dir / "abogen_debug_samples.epub"
+        build_debug_epub(epub_path)
+    else:
+        epub_path = Path(epub_path)
+
+    extraction = extract_from_path(epub_path)
+    combined_text = extraction.combined_text or "\n\n".join((c.text or "") for c in extraction.chapters)
+    cases = _extract_cases_from_text(combined_text)
+
+    # Prefer the canonical sample catalog for text (EPUB extraction may include headings).
+    try:
+        from abogen.debug_tts_samples import DEBUG_TTS_SAMPLES
+
+        sample_text_by_code = {sample.code: sample.text for sample in DEBUG_TTS_SAMPLES}
+    except Exception:
+        sample_text_by_code = {}
+
+    expected = list(iter_expected_codes())
+    found_codes = {code for code, _ in cases}
+    missing = [code for code in expected if code not in found_codes]
+    if missing:
+        raise RuntimeError(f"Debug EPUB missing expected codes: {', '.join(missing)}")
+
+    language = str(settings.get("language") or "a").strip() or "a"
+    # Kokoro's KPipeline expects short language codes like "a" (American English),
+    # but older settings may store ISO-like values such as "en".
+    language_aliases = {
+        "en": "a",
+        "en-us": "a",
+        "en_us": "a",
+        "en-gb": "b",
+        "en_gb": "b",
+        "es": "e",
+        "es-es": "e",
+        "fr": "f",
+        "fr-fr": "f",
+        "hi": "h",
+        "it": "i",
+        "pt": "p",
+        "pt-br": "p",
+        "ja": "j",
+        "jp": "j",
+        "zh": "z",
+        "zh-cn": "z",
+    }
+    language = language_aliases.get(language.lower(), language)
+    voice_spec = str(settings.get("default_voice") or "").strip()
+    use_gpu = bool(settings.get("use_gpu", False))
+    speed = float(settings.get("default_speed", 1.0) or 1.0)
+
+    # Settings may store "profile:<name>" which is not a Kokoro voice ID.
+    # Resolve it to a concrete voice formula (e.g. "af_heart*0.5+...") so Kokoro
+    # doesn't attempt to download a non-existent "voices/profile:<name>.pt".
+    try:
+        resolved_voice, _profile_name, profile_language = _resolve_voice_setting(voice_spec)
+        if resolved_voice:
+            voice_spec = resolved_voice
+        if profile_language:
+            language = str(profile_language).strip() or language
+    except Exception:
+        # Voice profile resolution is best-effort; fall back to raw voice_spec.
+        pass
+
+    # Best-effort voice caching (only for known Kokoro internal voices).
+    voice_ids = _spec_to_voice_ids(voice_spec)
+    if voice_ids:
+        try:
+            ensure_voice_assets(voice_ids)
+        except Exception:
+            # Network / optional dependency variance; debug runner can still proceed.
+            pass
+
+    pipeline = _load_pipeline(language, use_gpu)
+    voice_choice = _resolve_voice(pipeline, voice_spec, use_gpu)
+
+    apostrophe_config = build_apostrophe_config(settings=settings)
+    normalization_settings = dict(settings)
+
+    artifacts: List[DebugWavArtifact] = []
+
+    overall_path = run_dir / "overall.wav"
+    overall_audio: List[np.ndarray] = []
+
+    def synth(text: str, *, apply_normalization: bool = True) -> np.ndarray:
+        normalized = (
+            normalize_for_pipeline(
+                text,
+                config=apostrophe_config,
+                settings=normalization_settings,
+            )
+            if apply_normalization
+            else str(text or "")
+        )
+        parts: List[np.ndarray] = []
+        for segment in pipeline(
+            normalized,
+            voice=voice_choice,
+            speed=speed,
+            split_pattern=SPLIT_PATTERN,
+        ):
+            audio = _to_float32(getattr(segment, "audio", None))
+            if audio.size:
+                parts.append(audio)
+        if not parts:
+            return np.zeros(0, dtype="float32")
+        return np.concatenate(parts).astype("float32", copy=False)
+
+    pause_1s = np.zeros(int(1.0 * SAMPLE_RATE), dtype="float32")
+    between_cases = np.zeros(int(0.35 * SAMPLE_RATE), dtype="float32")
+
+    # Per sample
+    for code, snippet in cases:
+        snippet = sample_text_by_code.get(code, snippet)
+        if not snippet:
+            continue
+        id_audio = synth(_spoken_id(code), apply_normalization=False)
+        text_audio = synth(snippet, apply_normalization=True)
+        audio = np.concatenate([id_audio, pause_1s, text_audio]).astype("float32", copy=False)
+        filename = f"case_{code}.wav"
+        path = run_dir / filename
+        # Write float32 PCM WAV.
+        import soundfile as sf
+
+        sf.write(path, audio, SAMPLE_RATE, subtype="FLOAT")
+        artifacts.append(DebugWavArtifact(label=f"{code}", filename=filename, code=code, text=snippet))
+        overall_audio.append(audio)
+        overall_audio.append(between_cases)
+
+    # Overall
+    if overall_audio:
+        combined = np.concatenate(overall_audio).astype("float32", copy=False)
+    else:
+        combined = np.zeros(0, dtype="float32")
+    import soundfile as sf
+
+    sf.write(overall_path, combined, SAMPLE_RATE, subtype="FLOAT")
+    artifacts.insert(0, DebugWavArtifact(label="Overall", filename="overall.wav", code=None, text=None))
+
+    manifest = {
+        "run_id": run_id,
+        "epub": str(epub_path),
+        "artifacts": [artifact.__dict__ for artifact in artifacts],
+        "sample_rate": SAMPLE_RATE,
+    }
+    (run_dir / "manifest.json").write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    return manifest

abogen/webui/entrypoint.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Entrypoint script for abogen container
+# Performs CUDA diagnostics and starts the web server
+
+set -e
+
+echo "=== Abogen Container Starting ==="
+
+# Check CUDA availability
+if command -v nvidia-smi &> /dev/null; then
+    echo "NVIDIA Driver detected:"
+    nvidia-smi --query-gpu=name,driver_version,memory.total,memory.free --format=csv,noheader 2>/dev/null || echo "  (nvidia-smi query failed)"
+    
+    # Check PyTorch CUDA support
+    python3 -c "
+import torch
+print(f'PyTorch version: {torch.__version__}')
+print(f'CUDA available: {torch.cuda.is_available()}')
+if torch.cuda.is_available():
+    print(f'CUDA version (PyTorch): {torch.version.cuda}')
+    print(f'GPU count: {torch.cuda.device_count()}')
+    for i in range(torch.cuda.device_count()):
+        props = torch.cuda.get_device_properties(i)
+        print(f'  GPU {i}: {props.name} ({props.total_memory // 1024**2} MB)')
+else:
+    print('WARNING: PyTorch cannot access CUDA. Running on CPU.')
+" 2>&1 || echo "PyTorch CUDA check failed"
+else
+    echo "No NVIDIA driver detected. Running on CPU."
+fi
+
+echo "================================="
+echo ""
+
+# Start the application
+exec "$@"

abogen/webui/routes/__init__.py

@@ -0,0 +1,18 @@
+from abogen.webui.routes.main import main_bp
+from abogen.webui.routes.jobs import jobs_bp
+from abogen.webui.routes.settings import settings_bp
+from abogen.webui.routes.voices import voices_bp
+from abogen.webui.routes.entities import entities_bp
+from abogen.webui.routes.books import books_bp
+from abogen.webui.routes.api import api_bp
+
+__all__ = [
+    "main_bp",
+    "jobs_bp",
+    "settings_bp",
+    "voices_bp",
+    "entities_bp",
+    "books_bp",
+    "api_bp",
+]
+

abogen/webui/routes/api.py

@@ -0,0 +1,680 @@
+from typing import Any, Dict, Mapping, List, Optional
+import base64
+import uuid
+from pathlib import Path
+
+from flask import Blueprint, request, jsonify, send_file, url_for, current_app
+from flask.typing import ResponseReturnValue
+
+from abogen.webui.routes.utils.settings import (
+    load_settings,
+    load_integration_settings,
+    coerce_float,
+    coerce_bool,
+    audiobookshelf_settings_from_payload,
+    calibre_settings_from_payload,
+)
+from abogen.voice_profiles import (
+    load_profiles,
+    save_profiles,
+    delete_profile,
+    duplicate_profile,
+    serialize_profiles,
+    import_profiles_data,
+    export_profiles_payload,
+    normalize_profile_entry,
+)
+from abogen.webui.routes.utils.common import split_profile_spec
+from abogen.webui.routes.utils.preview import synthesize_preview, generate_preview_audio
+from abogen.webui.routes.utils.voice import formula_from_profile
+from abogen.normalization_settings import (
+    build_llm_configuration,
+    build_apostrophe_config,
+    apply_overrides,
+)
+from abogen.llm_client import list_models, LLMClientError
+from abogen.kokoro_text_normalization import normalize_for_pipeline
+from abogen.integrations.audiobookshelf import AudiobookshelfClient, AudiobookshelfConfig
+from abogen.integrations.calibre_opds import (
+    CalibreOPDSClient,
+    CalibreOPDSError,
+)
+from abogen.webui.routes.utils.service import get_service
+from abogen.webui.routes.utils.form import build_pending_job_from_extraction
+from abogen.text_extractor import extract_from_path
+from werkzeug.utils import secure_filename
+
+api_bp = Blueprint("api", __name__)
+
+# --- Voice Profile Routes ---
+
+@api_bp.get("/voice-profiles")
+def api_get_voice_profiles() -> ResponseReturnValue:
+    profiles = load_profiles()
+    return jsonify(profiles)
+
+@api_bp.post("/voice-profiles")
+def api_save_voice_profile() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=True) or {}
+    name = str(payload.get("name") or "").strip()
+    original_name = str(payload.get("originalName") or "").strip() or None
+
+    profile = payload.get("profile")
+    if profile is None:
+        # Speaker Studio payload format
+        provider = str(payload.get("provider") or "kokoro").strip().lower()
+        if provider not in {"kokoro", "supertonic"}:
+            provider = "kokoro"
+        if provider == "supertonic":
+            profile = {
+                "provider": "supertonic",
+                "language": str(payload.get("language") or "a").strip().lower() or "a",
+                "voice": payload.get("voice"),
+                "total_steps": payload.get("total_steps") or payload.get("supertonic_total_steps"),
+                "speed": payload.get("speed") or payload.get("supertonic_speed"),
+            }
+        else:
+            profile = {
+                "provider": "kokoro",
+                "language": str(payload.get("language") or "a").strip().lower() or "a",
+                "voices": payload.get("voices") or [],
+            }
+    
+    if not name or not profile:
+        return jsonify({"error": "Name and profile are required"}), 400
+        
+    profiles = load_profiles()
+
+    normalized = normalize_profile_entry(profile)
+    if not normalized:
+        return jsonify({"error": "Invalid profile payload"}), 400
+
+    if original_name and original_name in profiles and original_name != name:
+        del profiles[original_name]
+
+    profiles[name] = normalized
+    save_profiles(profiles)
+
+    return jsonify({"success": True, "profile": name, "profiles": serialize_profiles()})
+
+@api_bp.delete("/voice-profiles/<path:name>")
+def api_delete_voice_profile(name: str) -> ResponseReturnValue:
+    delete_profile(name)
+    return jsonify({"success": True, "profiles": serialize_profiles()})
+
+
+@api_bp.post("/voice-profiles/<path:name>/duplicate")
+def api_duplicate_voice_profile(name: str) -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=True) or {}
+    new_name = str(payload.get("name") or "").strip()
+    if not new_name:
+        return jsonify({"error": "Name is required"}), 400
+    duplicate_profile(name, new_name)
+    return jsonify({"success": True, "profile": new_name, "profiles": serialize_profiles()})
+
+
+@api_bp.post("/voice-profiles/import")
+def api_import_voice_profiles() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=True) or {}
+    data = payload.get("data")
+    replace_existing = bool(payload.get("replace_existing"))
+    if not isinstance(data, dict):
+        return jsonify({"error": "Invalid profile payload"}), 400
+    try:
+        imported = import_profiles_data(data, replace_existing=replace_existing)
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 400
+    return jsonify({"success": True, "imported": imported, "profiles": serialize_profiles()})
+
+
+@api_bp.get("/voice-profiles/export")
+def api_export_voice_profiles() -> ResponseReturnValue:
+    names_param = request.args.get("names")
+    names = None
+    if names_param:
+        names = [item.strip() for item in names_param.split(",") if item.strip()]
+    payload = export_profiles_payload(names)
+    import io
+    import json
+
+    data = json.dumps(payload, indent=2).encode("utf-8")
+    filename = "voice_profiles.json" if not names else "voice_profiles_export.json"
+    return send_file(
+        io.BytesIO(data),
+        mimetype="application/json",
+        as_attachment=True,
+        download_name=filename,
+    )
+
+
+@api_bp.post("/voice-profiles/preview")
+def api_voice_profiles_preview() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=True) or {}
+    text = str(payload.get("text") or "").strip() or "Hello world"
+    language = str(payload.get("language") or "a").strip().lower() or "a"
+    speed = coerce_float(payload.get("speed"), 1.0)
+    max_seconds = coerce_float(payload.get("max_seconds"), 8.0)
+
+    settings = load_settings()
+    use_gpu = settings.get("use_gpu", False)
+
+    # Accept a direct formula string or a full profile entry.
+    formula = str(payload.get("formula") or "").strip()
+    profile_name = str(payload.get("profile") or "").strip()
+    provider = str(payload.get("tts_provider") or payload.get("provider") or "").strip().lower() or None
+    supertonic_total_steps = int(payload.get("supertonic_total_steps") or payload.get("total_steps") or settings.get("supertonic_total_steps") or 5)
+
+    voice_spec = ""
+    resolved_provider = provider or "kokoro"
+
+    profiles = load_profiles()
+    if resolved_provider == "supertonic" and not profile_name:
+        voice_spec = str(payload.get("voice") or payload.get("supertonic_voice") or "M1").strip() or "M1"
+        # Allow per-speaker overrides via payload.
+        supertonic_total_steps = int(payload.get("supertonic_total_steps") or payload.get("total_steps") or supertonic_total_steps)
+        speed = coerce_float(payload.get("supertonic_speed") or payload.get("speed"), speed)
+    elif profile_name:
+        entry = profiles.get(profile_name)
+        normalized_entry = normalize_profile_entry(entry)
+        if not normalized_entry:
+            return jsonify({"error": "Unknown profile"}), 404
+        resolved_provider = str(normalized_entry.get("provider") or "kokoro")
+        if resolved_provider == "supertonic":
+            voice_spec = str(normalized_entry.get("voice") or "M1")
+            supertonic_total_steps = int(normalized_entry.get("total_steps") or supertonic_total_steps)
+            speed = float(normalized_entry.get("speed") or speed)
+        else:
+            voice_spec = formula_from_profile(normalized_entry) or ""
+            language = str(normalized_entry.get("language") or language)
+    elif formula:
+        voice_spec = formula
+        resolved_provider = "kokoro"
+    else:
+        # Raw voices payload -> Kokoro mix.
+        voices = payload.get("voices") or []
+        pseudo = {"provider": "kokoro", "language": language, "voices": voices}
+        normalized_entry = normalize_profile_entry(pseudo)
+        voice_spec = formula_from_profile(normalized_entry) or ""
+        resolved_provider = "kokoro"
+
+    if not voice_spec:
+        return jsonify({"error": "Unable to resolve preview voice"}), 400
+
+    try:
+        return synthesize_preview(
+            text=text,
+            voice_spec=voice_spec,
+            language=language,
+            speed=speed,
+            use_gpu=use_gpu,
+            tts_provider=resolved_provider,
+            supertonic_total_steps=supertonic_total_steps,
+            max_seconds=max_seconds,
+        )
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 500
+
+@api_bp.post("/speaker-preview")
+def api_speaker_preview() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=True) or {}
+    pending_id = str(payload.get("pending_id") or "").strip()
+    text = payload.get("text", "Hello world")
+    voice = payload.get("voice", "af_heart")
+    language = payload.get("language", "a")
+    speed_value = payload.get("speed")
+    speed = coerce_float(speed_value, 1.0)
+    tts_provider = str(payload.get("tts_provider") or "").strip().lower()
+    supertonic_total_steps = int(payload.get("supertonic_total_steps") or 5)
+    
+    settings = load_settings()
+    use_gpu = settings.get("use_gpu", False)
+
+    base_spec, speaker_name = split_profile_spec(voice)
+    resolved_provider = tts_provider if tts_provider in {"kokoro", "supertonic"} else ""
+
+    if speaker_name:
+        entry = normalize_profile_entry(load_profiles().get(speaker_name))
+        if entry:
+            resolved_provider = str(entry.get("provider") or resolved_provider or "")
+            if resolved_provider == "supertonic":
+                voice = str(entry.get("voice") or "M1")
+                supertonic_total_steps = int(entry.get("total_steps") or supertonic_total_steps)
+                if speed_value is None:
+                    speed = coerce_float(entry.get("speed"), speed)
+            elif resolved_provider == "kokoro":
+                voice = formula_from_profile(entry) or (base_spec or voice)
+
+    if not resolved_provider:
+        resolved_provider = "supertonic" if str(base_spec or "").strip() in {"M1","M2","M3","M4","M5","F1","F2","F3","F4","F5"} else "kokoro"
+
+    pronunciation_overrides = None
+    manual_overrides = None
+    speakers = None
+    if pending_id:
+        try:
+            pending = get_service().get_pending_job(pending_id)
+        except Exception:
+            pending = None
+        if pending is not None:
+            manual_overrides = getattr(pending, "manual_overrides", None)
+            pronunciation_overrides = getattr(pending, "pronunciation_overrides", None)
+            speakers = getattr(pending, "speakers", None)
+    
+    try:
+        return synthesize_preview(
+            text=text,
+            voice_spec=voice,
+            language=language,
+            speed=speed,
+            use_gpu=use_gpu
+            ,
+            tts_provider=resolved_provider,
+            supertonic_total_steps=supertonic_total_steps or int(settings.get("supertonic_total_steps") or 5),
+            pronunciation_overrides=pronunciation_overrides,
+            manual_overrides=manual_overrides,
+            speakers=speakers,
+        )
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+# --- Integration Routes ---
+
+
+def _opds_metadata_overrides(metadata_payload: Mapping[str, Any]) -> Dict[str, Any]:
+    metadata_overrides: Dict[str, Any] = {}
+
+    def _stringify_metadata_value(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]
+            parts = [part for part in parts if part]
+            return ", ".join(parts)
+        return str(value).strip()
+
+    raw_series = metadata_payload.get("series") or metadata_payload.get("series_name")
+    series_name = str(raw_series or "").strip()
+    if series_name:
+        metadata_overrides["series"] = series_name
+        metadata_overrides.setdefault("series_name", series_name)
+
+    series_index_value = (
+        metadata_payload.get("series_index")
+        or metadata_payload.get("series_position")
+        or metadata_payload.get("series_sequence")
+        or metadata_payload.get("book_number")
+    )
+    if series_index_value is not None:
+        series_index_text = str(series_index_value).strip()
+        if series_index_text:
+            metadata_overrides.setdefault("series_index", series_index_text)
+            metadata_overrides.setdefault("series_position", series_index_text)
+            metadata_overrides.setdefault("series_sequence", series_index_text)
+            metadata_overrides.setdefault("book_number", series_index_text)
+
+    tags_value = metadata_payload.get("tags") or metadata_payload.get("keywords")
+    if tags_value:
+        tags_text = _stringify_metadata_value(tags_value)
+        if tags_text:
+            metadata_overrides.setdefault("tags", tags_text)
+            metadata_overrides.setdefault("keywords", tags_text)
+            metadata_overrides.setdefault("genre", tags_text)
+
+    description_value = metadata_payload.get("description") or metadata_payload.get("summary")
+    if description_value:
+        description_text = _stringify_metadata_value(description_value)
+        if description_text:
+            metadata_overrides.setdefault("description", description_text)
+            metadata_overrides.setdefault("summary", description_text)
+
+    subtitle_value = (
+        metadata_payload.get("subtitle")
+        or metadata_payload.get("sub_title")
+        or metadata_payload.get("calibre_subtitle")
+    )
+    if subtitle_value:
+        subtitle_text = _stringify_metadata_value(subtitle_value)
+        if subtitle_text:
+            metadata_overrides.setdefault("subtitle", subtitle_text)
+
+    publisher_value = metadata_payload.get("publisher")
+    if publisher_value:
+        publisher_text = _stringify_metadata_value(publisher_value)
+        if publisher_text:
+            metadata_overrides.setdefault("publisher", publisher_text)
+
+    # Author mapping: Abogen templates look for either 'authors' or 'author'.
+    authors_value = (
+        metadata_payload.get("authors")
+        or metadata_payload.get("author")
+        or metadata_payload.get("creator")
+        or metadata_payload.get("dc_creator")
+    )
+    if authors_value:
+        authors_text = _stringify_metadata_value(authors_value)
+        if authors_text:
+            metadata_overrides.setdefault("authors", authors_text)
+            metadata_overrides.setdefault("author", authors_text)
+
+    return metadata_overrides
+
+@api_bp.get("/integrations/calibre-opds/feed")
+def api_calibre_opds_feed() -> ResponseReturnValue:
+    integrations = load_integration_settings()
+    calibre_settings = integrations.get("calibre_opds", {})
+    
+    payload = {
+        "base_url": calibre_settings.get("base_url"),
+        "username": calibre_settings.get("username"),
+        "password": calibre_settings.get("password"),
+        "verify_ssl": calibre_settings.get("verify_ssl", True),
+    }
+    
+    if not payload.get("base_url"):
+        return jsonify({"error": "Calibre OPDS base URL is not configured."}), 400
+        
+    try:
+        client = CalibreOPDSClient(
+            base_url=payload.get("base_url") or "",
+            username=payload.get("username"),
+            password=payload.get("password"),
+            verify=bool(payload.get("verify_ssl", True)),
+        )
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    href = request.args.get("href", type=str)
+    query = request.args.get("q", type=str)
+    letter = request.args.get("letter", type=str)
+    
+    try:
+        if letter:
+            feed = client.browse_letter(letter, start_href=href)
+        elif query:
+            feed = client.search(query, start_href=href)
+        else:
+            feed = client.fetch_feed(href)
+    except CalibreOPDSError as exc:
+        return jsonify({"error": str(exc)}), 502
+    except Exception as exc:
+        return jsonify({"error": f"Unexpected error: {str(exc)}"}), 500
+
+    return jsonify({
+        "feed": feed.to_dict(),
+        "href": href or "",
+        "query": query or "",
+    })
+
+@api_bp.post("/integrations/audiobookshelf/folders")
+def api_abs_folders() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=True) or {}
+    # Use the helper to resolve saved tokens when use_saved_token is set
+    settings = audiobookshelf_settings_from_payload(payload)
+    host = settings.get("base_url")
+    token = settings.get("api_token")
+    library_id = settings.get("library_id")
+    
+    if not host or not token:
+        return jsonify({"error": "Base URL and API token are required"}), 400
+    
+    if not library_id:
+        return jsonify({"error": "Library ID is required to list folders"}), 400
+        
+    try:
+        config = AudiobookshelfConfig(base_url=host, api_token=token, library_id=library_id)
+        client = AudiobookshelfClient(config)
+        folders = client.list_folders()
+        return jsonify({"folders": folders})
+    except Exception as e:
+        return jsonify({"error": str(e)}), 400
+
+@api_bp.post("/integrations/audiobookshelf/test")
+def api_abs_test() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=True) or {}
+    # Use the helper to resolve saved tokens when use_saved_token is set
+    settings = audiobookshelf_settings_from_payload(payload)
+    host = settings.get("base_url")
+    token = settings.get("api_token")
+    
+    if not host or not token:
+        return jsonify({"error": "Base URL and API token are required"}), 400
+        
+    try:
+        config = AudiobookshelfConfig(base_url=host, api_token=token)
+        client = AudiobookshelfClient(config)
+        # Just getting libraries is a good enough test
+        client.get_libraries()
+        return jsonify({"success": True, "message": "Connection successful."})
+    except Exception as e:
+        return jsonify({"error": str(e)}), 400
+
+@api_bp.post("/integrations/calibre-opds/test")
+def api_calibre_opds_test() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=True) or {}
+    # Use the helper to resolve saved passwords when use_saved_password is set
+    settings = calibre_settings_from_payload(payload)
+    base_url = settings.get("base_url")
+    username = settings.get("username")
+    password = settings.get("password")
+    verify_ssl = settings.get("verify_ssl", False)
+    
+    if not base_url:
+        return jsonify({"error": "Base URL is required"}), 400
+        
+    try:
+        client = CalibreOPDSClient(
+            base_url=base_url,
+            username=username,
+            password=password,
+            verify=verify_ssl,
+            timeout=10.0
+        )
+        client.fetch_feed()
+        return jsonify({"success": True, "message": "Connection successful."})
+    except Exception as e:
+        return jsonify({"error": str(e)}), 400
+
+@api_bp.post("/integrations/calibre-opds/import")
+def api_calibre_opds_import() -> ResponseReturnValue:
+    if not request.is_json:
+        return jsonify({"error": "Expected JSON payload."}), 400
+    
+    data = request.get_json(force=True, silent=True) or {}
+    href = str(data.get("href") or "").strip()
+    
+    if not href:
+        return jsonify({"error": "Download URL (href) is required."}), 400
+        
+    metadata_payload = data.get("metadata") if isinstance(data, Mapping) else None
+    metadata_overrides: Dict[str, Any] = {}
+    if isinstance(metadata_payload, Mapping):
+        metadata_overrides = _opds_metadata_overrides(metadata_payload)
+
+    settings = load_settings()
+    integrations = load_integration_settings()
+    calibre_settings = integrations.get("calibre_opds", {})
+    
+    try:
+        client = CalibreOPDSClient(
+            base_url=calibre_settings.get("base_url") or "",
+            username=calibre_settings.get("username"),
+            password=calibre_settings.get("password"),
+            verify=bool(calibre_settings.get("verify_ssl", True)),
+        )
+        
+        temp_dir = Path(current_app.config.get("UPLOAD_FOLDER", "uploads"))
+        temp_dir.mkdir(exist_ok=True)
+        
+        resource = client.download(href)
+        filename = resource.filename
+        content = resource.content
+        
+        if not filename:
+            filename = f"{uuid.uuid4().hex}.epub"
+            
+        file_path = temp_dir / f"{uuid.uuid4().hex}_{filename}"
+        file_path.write_bytes(content)
+        
+        extraction = extract_from_path(file_path)
+        
+        if metadata_overrides:
+            extraction.metadata.update(metadata_overrides)
+            
+        result = build_pending_job_from_extraction(
+            stored_path=file_path,
+            original_name=filename,
+            extraction=extraction,
+            form={},
+            settings=settings,
+            profiles=serialize_profiles(),
+            metadata_overrides=metadata_overrides,
+        )
+        
+        get_service().store_pending_job(result.pending)
+        
+        return jsonify({
+            "success": True,
+            "status": "imported",
+            "pending_id": result.pending.id,
+            "redirect_url": url_for("main.wizard_step", step="book", pending_id=result.pending.id)
+        })
+
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+# --- LLM Routes ---
+
+@api_bp.post("/llm/models")
+def api_llm_models() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=False) or {}
+    current_settings = load_settings()
+
+    base_url = str(payload.get("base_url") or payload.get("llm_base_url") or current_settings.get("llm_base_url") or "").strip()
+    if not base_url:
+        return jsonify({"error": "LLM base URL is required."}), 400
+
+    api_key = str(payload.get("api_key") or payload.get("llm_api_key") or current_settings.get("llm_api_key") or "")
+    timeout = coerce_float(payload.get("timeout"), current_settings.get("llm_timeout", 30.0))
+
+    overrides = {
+        "llm_base_url": base_url,
+        "llm_api_key": api_key,
+        "llm_timeout": timeout,
+    }
+
+    merged = apply_overrides(current_settings, overrides)
+    configuration = build_llm_configuration(merged)
+    try:
+        models = list_models(configuration)
+    except LLMClientError as exc:
+        return jsonify({"error": str(exc)}), 400
+    return jsonify({"models": models})
+
+@api_bp.post("/llm/preview")
+def api_llm_preview() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=False) or {}
+    sample_text = str(payload.get("text") or "").strip()
+    if not sample_text:
+        return jsonify({"error": "Text is required."}), 400
+
+    base_settings = load_settings()
+    overrides: Dict[str, Any] = {
+        "llm_base_url": str(
+            payload.get("base_url")
+            or payload.get("llm_base_url")
+            or base_settings.get("llm_base_url")
+            or ""
+        ).strip(),
+        "llm_api_key": str(
+            payload.get("api_key")
+            or payload.get("llm_api_key")
+            or base_settings.get("llm_api_key")
+            or ""
+        ),
+        "llm_model": str(
+            payload.get("model")
+            or payload.get("llm_model")
+            or base_settings.get("llm_model")
+            or ""
+        ),
+        "llm_prompt": payload.get("prompt") or payload.get("llm_prompt") or base_settings.get("llm_prompt"),
+        "llm_context_mode": payload.get("context_mode") or base_settings.get("llm_context_mode"),
+        "llm_timeout": coerce_float(payload.get("timeout"), base_settings.get("llm_timeout", 30.0)),
+        "normalization_apostrophe_mode": "llm",
+    }
+
+    merged = apply_overrides(base_settings, overrides)
+    if not merged.get("llm_base_url"):
+        return jsonify({"error": "LLM base URL is required."}), 400
+    if not merged.get("llm_model"):
+        return jsonify({"error": "Select an LLM model before previewing."}), 400
+
+    apostrophe_config = build_apostrophe_config(settings=merged)
+    try:
+        normalized_text = normalize_for_pipeline(sample_text, config=apostrophe_config, settings=merged)
+    except LLMClientError as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    context = {
+        "text": sample_text,
+        "normalized_text": normalized_text,
+    }
+    return jsonify(context)
+
+# --- Normalization Routes ---
+
+@api_bp.post("/normalization/preview")
+def api_normalization_preview() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=False) or {}
+    sample_text = str(payload.get("text") or "").strip()
+    if not sample_text:
+        return jsonify({"error": "Sample text is required."}), 400
+
+    base_settings = load_settings()
+    # We might want to apply overrides from payload if any normalization settings are passed
+    # For now, just use base settings as in original code (presumably)
+    
+    apostrophe_config = build_apostrophe_config(settings=base_settings)
+    try:
+        normalized_text = normalize_for_pipeline(sample_text, config=apostrophe_config, settings=base_settings)
+    except Exception as exc:
+        return jsonify({"error": str(exc)}), 400
+
+    return jsonify({
+        "text": sample_text,
+        "normalized_text": normalized_text,
+    })
+
+@api_bp.post("/entity-pronunciation/preview")
+def api_entity_pronunciation_preview() -> ResponseReturnValue:
+    payload = request.get_json(force=True, silent=True) or {}
+    token = payload.get("token", "").strip()
+    pronunciation = payload.get("pronunciation", "").strip()
+    voice = payload.get("voice", "").strip()
+    language = payload.get("language", "a").strip()
+    
+    if not token and not pronunciation:
+        return jsonify({"error": "Token or pronunciation required"}), 400
+        
+    text_to_speak = pronunciation if pronunciation else token
+    
+    if not voice:
+        settings = load_settings()
+        voice = settings.get("default_voice", "af_heart")
+        
+    try:
+        # Check GPU setting
+        settings = load_settings()
+        use_gpu = coerce_bool(settings.get("use_gpu"), False)
+        
+        audio_bytes = generate_preview_audio(
+            text=text_to_speak,
+            voice_spec=voice,
+            language=language,
+            speed=1.0,
+            use_gpu=use_gpu,
+        )
+        audio_base64 = base64.b64encode(audio_bytes).decode("utf-8")
+        return jsonify({"audio_base64": audio_base64})
+    except Exception as e:
+        return jsonify({"error": str(e)}), 400

abogen/webui/routes/books.py

@@ -0,0 +1,34 @@
+from typing import Any, Dict
+
+from flask import Blueprint, render_template
+from flask.typing import ResponseReturnValue
+
+from abogen.webui.routes.utils.settings import (
+    load_settings,
+    load_integration_settings,
+)
+from abogen.webui.routes.utils.voice import template_options
+
+books_bp = Blueprint("books", __name__)
+
+def _calibre_integration_enabled(integrations: Dict[str, Any]) -> bool:
+    calibre = integrations.get("calibre_opds", {})
+    return bool(calibre.get("enabled") and calibre.get("base_url"))
+
+@books_bp.get("/")
+def find_books_page() -> ResponseReturnValue:
+    settings = load_settings()
+    integrations = load_integration_settings()
+    return render_template(
+        "find_books.html",
+        integrations=integrations,
+        opds_available=_calibre_integration_enabled(integrations),
+        options=template_options(),
+        settings=settings,
+    )
+
+@books_bp.get("/search")
+def search_books() -> ResponseReturnValue:
+    return find_books_page()
+
+

abogen/webui/routes/entities.py

@@ -0,0 +1,175 @@
+from typing import Mapping
+from flask import Blueprint, request, jsonify, abort, render_template, redirect, url_for
+from flask.typing import ResponseReturnValue
+
+from abogen.webui.routes.utils.service import require_pending_job, get_service
+from abogen.webui.routes.utils.entity import (
+    refresh_entity_summary,
+    pending_entities_payload,
+    upsert_manual_override,
+    delete_manual_override,
+    search_manual_override_candidates,
+)
+from abogen.webui.routes.utils.settings import coerce_int, load_settings
+from abogen.webui.routes.utils.voice import template_options
+from abogen.pronunciation_store import (
+    delete_override as delete_pronunciation_override,
+    save_override as save_pronunciation_override,
+    get_override_stats,
+    all_overrides,
+)
+
+entities_bp = Blueprint("entities", __name__)
+
+@entities_bp.post("/analyze")
+def analyze_entities() -> ResponseReturnValue:
+    # This might be triggered via wizard update, but if there's a specific route:
+    # In original routes.py, it was likely part of wizard logic or API.
+    # I'll assume this is for the API endpoint /api/pending/<id>/entities/refresh
+    pending_id = request.form.get("pending_id") or request.args.get("pending_id")
+    if not pending_id:
+        abort(400, "Pending ID required")
+        
+    pending = require_pending_job(pending_id)
+    refresh_entity_summary(pending, pending.chapters)
+    get_service().store_pending_job(pending)
+    return jsonify(pending_entities_payload(pending))
+
+@entities_bp.get("/pending/<pending_id>")
+def get_entities(pending_id: str) -> ResponseReturnValue:
+    pending = require_pending_job(pending_id)
+    refresh_flag = (request.args.get("refresh") or "").strip().lower()
+    expected_cache = (request.args.get("cache_key") or "").strip()
+    refresh_requested = refresh_flag in {"1", "true", "yes", "force"}
+    
+    if expected_cache and expected_cache != (pending.entity_cache_key or ""):
+        refresh_requested = True
+        
+    if refresh_requested or not pending.entity_summary:
+        refresh_entity_summary(pending, pending.chapters)
+        get_service().store_pending_job(pending)
+        
+    return jsonify(pending_entities_payload(pending))
+
+@entities_bp.post("/pending/<pending_id>/refresh")
+def refresh_entities(pending_id: str) -> ResponseReturnValue:
+    pending = require_pending_job(pending_id)
+    refresh_entity_summary(pending, pending.chapters)
+    get_service().store_pending_job(pending)
+    return jsonify(pending_entities_payload(pending))
+
+@entities_bp.get("/pending/<pending_id>/overrides")
+def list_manual_overrides(pending_id: str) -> ResponseReturnValue:
+    pending = require_pending_job(pending_id)
+    return jsonify({
+        "overrides": pending.manual_overrides or [],
+        "pronunciation_overrides": pending.pronunciation_overrides or [],
+        "heteronym_overrides": getattr(pending, "heteronym_overrides", None) or [],
+        "language": pending.language or "en",
+    })
+
+@entities_bp.post("/pending/<pending_id>/overrides")
+def upsert_override(pending_id: str) -> ResponseReturnValue:
+    pending = require_pending_job(pending_id)
+    payload = request.get_json(silent=True) or {}
+    if not isinstance(payload, Mapping):
+        abort(400, "Invalid override payload")
+        
+    try:
+        override = upsert_manual_override(pending, payload)
+    except ValueError as exc:
+        abort(400, str(exc))
+        
+    get_service().store_pending_job(pending)
+    return jsonify({"override": override, **pending_entities_payload(pending)})
+
+@entities_bp.delete("/pending/<pending_id>/overrides/<override_id>")
+def delete_override(pending_id: str, override_id: str) -> ResponseReturnValue:
+    pending = require_pending_job(pending_id)
+    deleted = delete_manual_override(pending, override_id)
+    if not deleted:
+        abort(404)
+        
+    get_service().store_pending_job(pending)
+    return jsonify({"deleted": True, **pending_entities_payload(pending)})
+
+@entities_bp.get("/pending/<pending_id>/overrides/search")
+def search_candidates(pending_id: str) -> ResponseReturnValue:
+    pending = require_pending_job(pending_id)
+    query = (request.args.get("q") or request.args.get("query") or "").strip()
+    limit_param = request.args.get("limit")
+    limit_value = coerce_int(limit_param, 15, minimum=1, maximum=50) if limit_param is not None else 15
+    
+    results = search_manual_override_candidates(pending, query, limit=limit_value)
+    return jsonify({"query": query, "limit": limit_value, "results": results})
+
+@entities_bp.post("/overrides")
+def upsert_global_override() -> ResponseReturnValue:
+    payload = request.form
+    action = payload.get("action", "save")
+    lang = payload.get("lang", "en")
+    token = payload.get("token", "").strip()
+    
+    if action == "delete":
+        if token:
+            delete_pronunciation_override(token=token, language=lang)
+    else:
+        pronunciation = payload.get("pronunciation", "").strip()
+        voice = payload.get("voice", "").strip()
+        if token:
+            save_pronunciation_override(
+                token=token,
+                pronunciation=pronunciation,
+                voice=voice or None,
+                language=lang
+            )
+        
+    return redirect(url_for("entities.entities_page", lang=lang))
+
+@entities_bp.get("/")
+def entities_page() -> str:
+    settings = load_settings()
+    lang = request.args.get("lang") or settings.get("language", "en")
+    voice_filter = request.args.get("voice", "")
+    pronunciation_filter = request.args.get("pronunciation", "")
+
+    options = template_options()
+    stats = get_override_stats(lang)
+    
+    overrides = all_overrides(lang)
+    
+    if voice_filter == "assigned":
+        overrides = [o for o in overrides if o.get("voice")]
+    elif voice_filter == "unassigned":
+        overrides = [o for o in overrides if not o.get("voice")]
+        
+    if pronunciation_filter == "defined":
+        overrides = [o for o in overrides if o.get("pronunciation")]
+    elif pronunciation_filter == "undefined":
+        overrides = [o for o in overrides if not o.get("pronunciation")]
+
+    voice_filter_options = [
+        {"value": "", "label": "All voices"},
+        {"value": "assigned", "label": "Assigned"},
+        {"value": "unassigned", "label": "Unassigned"},
+    ]
+    pronunciation_filter_options = [
+        {"value": "", "label": "All pronunciations"},
+        {"value": "defined", "label": "Defined"},
+        {"value": "undefined", "label": "Undefined"},
+    ]
+
+    language_label = options["languages"].get(lang, lang)
+    return render_template(
+        "entities.html",
+        language=lang,
+        language_label=language_label,
+        options=options,
+        languages=options["languages"].items(),
+        stats=stats,
+        overrides=overrides,
+        voice_filter=voice_filter,
+        pronunciation_filter=pronunciation_filter,
+        voice_filter_options=voice_filter_options,
+        pronunciation_filter_options=pronunciation_filter_options,
+    )

abogen/webui/routes/jobs.py

@@ -0,0 +1,305 @@
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from flask import Blueprint, Response, abort, redirect, render_template, request, url_for, send_file
+from flask.typing import ResponseReturnValue
+
+from abogen.webui.service import (
+    JobStatus,
+    load_audiobookshelf_chapters,
+    build_audiobookshelf_metadata,
+)
+from abogen.webui.routes.utils.service import get_service
+from abogen.webui.routes.utils.form import render_jobs_panel
+from abogen.webui.routes.utils.voice import template_options
+from abogen.webui.routes.utils.epub import (
+    job_download_flags,
+    locate_job_epub,
+    locate_job_audio,
+)
+from abogen.webui.routes.utils.settings import (
+    stored_integration_config,
+    build_audiobookshelf_config,
+    coerce_bool,
+)
+from abogen.webui.routes.utils.common import existing_paths
+from abogen.integrations.audiobookshelf import AudiobookshelfClient, AudiobookshelfUploadError
+
+logger = logging.getLogger(__name__)
+
+jobs_bp = Blueprint("jobs", __name__)
+
+@jobs_bp.get("/<job_id>")
+def job_detail(job_id: str) -> ResponseReturnValue:
+    job = get_service().get_job(job_id)
+    if not job:
+        # Return a friendly page instead of 404 to avoid confusion from stale browser tabs
+        return render_template("job_not_found.html"), 200
+    return render_template(
+        "job_detail.html",
+        job=job,
+        options=template_options(),
+        JobStatus=JobStatus,
+        downloads=job_download_flags(job),
+    )
+
+@jobs_bp.post("/<job_id>/pause")
+def pause_job(job_id: str) -> ResponseReturnValue:
+    get_service().pause(job_id)
+    if request.headers.get("HX-Request"):
+        return render_jobs_panel()
+    return redirect(url_for("jobs.job_detail", job_id=job_id))
+
+@jobs_bp.post("/<job_id>/resume")
+def resume_job(job_id: str) -> ResponseReturnValue:
+    get_service().resume(job_id)
+    if request.headers.get("HX-Request"):
+        return render_jobs_panel()
+    return redirect(url_for("jobs.job_detail", job_id=job_id))
+
+@jobs_bp.post("/<job_id>/cancel")
+def cancel_job(job_id: str) -> ResponseReturnValue:
+    get_service().cancel(job_id)
+    if request.headers.get("HX-Request"):
+        return render_jobs_panel()
+    return redirect(url_for("jobs.job_detail", job_id=job_id))
+
+@jobs_bp.post("/<job_id>/delete")
+def delete_job(job_id: str) -> ResponseReturnValue:
+    get_service().delete(job_id)
+    if request.headers.get("HX-Request"):
+        return render_jobs_panel()
+    return redirect(url_for("main.index"))
+
+@jobs_bp.post("/<job_id>/retry")
+def retry_job(job_id: str) -> ResponseReturnValue:
+    new_job = get_service().retry(job_id)
+    if request.headers.get("HX-Request"):
+        return render_jobs_panel()
+    if new_job:
+        return redirect(url_for("jobs.job_detail", job_id=new_job.id))
+    return redirect(url_for("jobs.job_detail", job_id=job_id))
+
+@jobs_bp.post("/<job_id>/audiobookshelf")
+def send_job_to_audiobookshelf(job_id: str) -> ResponseReturnValue:
+    service = get_service()
+    job = service.get_job(job_id)
+    if job is None:
+        abort(404)
+
+    def _panel_response() -> ResponseReturnValue:
+        if request.headers.get("HX-Request"):
+            return render_jobs_panel()
+        return redirect(url_for("jobs.job_detail", job_id=job.id))
+
+    if job.status != JobStatus.COMPLETED:
+        return _panel_response()
+
+    settings = stored_integration_config("audiobookshelf")
+    if not settings or not coerce_bool(settings.get("enabled"), False):
+        job.add_log("Audiobookshelf upload skipped: integration is disabled.", level="warning")
+        service._persist_state()
+        return _panel_response()
+
+    config = build_audiobookshelf_config(settings)
+    if config is None:
+        job.add_log(
+            "Audiobookshelf upload skipped: configure base URL, API token, and library ID first.",
+            level="warning",
+        )
+        service._persist_state()
+        return _panel_response()
+    if not config.folder_id:
+        job.add_log(
+            "Audiobookshelf upload skipped: enter the folder name or ID in the Audiobookshelf settings.",
+            level="warning",
+        )
+        service._persist_state()
+        return _panel_response()
+
+    audio_path = locate_job_audio(job)
+    if not audio_path or not audio_path.exists():
+        job.add_log("Audiobookshelf upload skipped: audio output not found.", level="warning")
+        service._persist_state()
+        return _panel_response()
+
+    cover_path = None
+    if config.send_cover and job.cover_image_path:
+        cover_candidate = job.cover_image_path
+        if not isinstance(cover_candidate, Path):
+            cover_candidate = Path(str(cover_candidate))
+        if cover_candidate.exists():
+            cover_path = cover_candidate
+
+    subtitles = existing_paths(job.result.subtitle_paths) if config.send_subtitles else None
+    chapters = load_audiobookshelf_chapters(job) if config.send_chapters else None
+    metadata = build_audiobookshelf_metadata(job)
+    display_title = metadata.get("title") or audio_path.stem
+    overwrite_requested = request.form.get("overwrite") == "true" or request.args.get("overwrite") == "true"
+
+    try:
+        client = AudiobookshelfClient(config)
+    except ValueError as exc:
+        job.add_log(f"Audiobookshelf configuration error: {exc}", level="error")
+        service._persist_state()
+        return _panel_response()
+
+    try:
+        existing_items = client.find_existing_items(display_title, folder_id=config.folder_id)
+    except AudiobookshelfUploadError as exc:
+        job.add_log(f"Audiobookshelf lookup failed: {exc}", level="error")
+        service._persist_state()
+        return _panel_response()
+
+    if existing_items and not overwrite_requested:
+        job.add_log(
+            f"Audiobookshelf already contains '{display_title}'. Awaiting overwrite confirmation.",
+            level="warning",
+        )
+        service._persist_state()
+        if request.headers.get("HX-Request"):
+            detail = {
+                "jobId": job.id,
+                "title": display_title,
+                "url": url_for("jobs.send_job_to_audiobookshelf", job_id=job.id),
+                "target": request.headers.get("HX-Target") or "#jobs-panel",
+                "message": f'Audiobookshelf already contains "{display_title}". Overwrite?',
+            }
+            headers = {"HX-Trigger": json.dumps({"audiobookshelf-overwrite-prompt": detail})}
+            return Response("", status=204, headers=headers)
+        return _panel_response()
+
+    if existing_items and overwrite_requested:
+        try:
+            client.delete_items(existing_items)
+        except AudiobookshelfUploadError as exc:
+            job.add_log(f"Audiobookshelf overwrite aborted: {exc}", level="error")
+            service._persist_state()
+            return _panel_response()
+        else:
+            job.add_log(
+                f"Removed {len(existing_items)} existing Audiobookshelf item(s) prior to overwrite.",
+                level="info",
+            )
+
+    job.add_log("Audiobookshelf upload triggered manually.", level="info")
+    try:
+        client.upload_audiobook(
+            audio_path,
+            metadata=metadata,
+            cover_path=cover_path,
+            chapters=chapters,
+            subtitles=subtitles,
+        )
+    except AudiobookshelfUploadError as exc:
+        job.add_log(f"Audiobookshelf upload failed: {exc}", level="error")
+    except Exception as exc:
+        job.add_log(f"Audiobookshelf integration error: {exc}", level="error")
+    else:
+        job.add_log("Audiobookshelf upload queued.", level="success")
+    finally:
+        service._persist_state()
+
+    return _panel_response()
+
+@jobs_bp.post("/clear-finished")
+def clear_finished_jobs() -> ResponseReturnValue:
+    get_service().clear_finished()
+    if request.headers.get("HX-Request"):
+        return render_jobs_panel()
+    return redirect(url_for("main.index", _anchor="queue"))
+
+@jobs_bp.get("/<job_id>/epub")
+def job_epub(job_id: str) -> ResponseReturnValue:
+    job = get_service().get_job(job_id)
+    if job is None or job.status != JobStatus.COMPLETED:
+        abort(404)
+    epub_path = locate_job_epub(job)
+    if not epub_path:
+        abort(404)
+    return send_file(
+        epub_path,
+        as_attachment=True,
+        download_name=epub_path.name,
+        mimetype="application/epub+zip",
+    )
+
+@jobs_bp.get("/<job_id>/download/<file_type>")
+def download_file(job_id: str, file_type: str) -> ResponseReturnValue:
+    job = get_service().get_job(job_id)
+    if not job or job.status != JobStatus.COMPLETED:
+        abort(404)
+
+    if file_type == "audio":
+        path = locate_job_audio(job)
+        if not path or not path.exists():
+            abort(404)
+        return send_file(
+            path,
+            as_attachment=True,
+            download_name=path.name,
+        )
+    
+    # Handle other file types if needed (subtitles, etc.)
+    # For now, just audio and epub are explicitly handled
+    abort(404)
+
+@jobs_bp.get("/<job_id>/logs")
+def job_logs(job_id: str) -> ResponseReturnValue:
+    job = get_service().get_job(job_id)
+    if not job:
+        # Return a simple page instead of 404 to avoid log spam from stale browser tabs
+        return render_template("job_logs_missing.html"), 200
+    return render_template("job_logs_static.html", job=job)
+
+
+@jobs_bp.get("/<job_id>/logs/partial")
+def job_logs_partial(job_id: str) -> ResponseReturnValue:
+    job = get_service().get_job(job_id)
+    if not job:
+        # Return a non-polling section so HTMX stops retrying.
+        return render_template("partials/logs_section_missing.html"), 200
+    return render_template("partials/logs_section.html", job=job)
+
+@jobs_bp.get("/<job_id>/logs/stream")
+def stream_logs(job_id: str) -> ResponseReturnValue:
+    job = get_service().get_job(job_id)
+    if not job:
+        abort(404)
+        
+    def generate():
+        last_index = 0
+        while True:
+            current_logs = job.logs
+            if len(current_logs) > last_index:
+                for log in current_logs[last_index:]:
+                    yield f"data: {json.dumps({'timestamp': log.timestamp, 'level': log.level, 'message': log.message})}\n\n"
+                last_index = len(current_logs)
+            
+            if job.status in {JobStatus.COMPLETED, JobStatus.FAILED, JobStatus.CANCELLED}:
+                break
+            
+            import time
+            time.sleep(0.5)
+            
+    return Response(generate(), mimetype="text/event-stream")
+
+@jobs_bp.get("/<job_id>/reader")
+def job_reader(job_id: str) -> ResponseReturnValue:
+    job = get_service().get_job(job_id)
+    if not job:
+        abort(404)
+    return render_template("reader_embed.html", job=job)
+
+@jobs_bp.get("/queue")
+def queue_page() -> str:
+    return render_template(
+        "queue.html",
+        jobs_panel=render_jobs_panel(),
+    )
+
+@jobs_bp.get("/partial")
+def jobs_partial() -> str:
+    return render_jobs_panel()

abogen/webui/routes/main.py

@@ -0,0 +1,388 @@
+import logging
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, Optional, cast
+
+from flask import Blueprint, redirect, render_template, request, url_for, jsonify, current_app
+from werkzeug.utils import secure_filename
+
+from abogen.webui.service import PendingJob, JobStatus
+from abogen.webui.routes.utils.service import get_service, remove_pending_job, submit_job
+from abogen.webui.routes.utils.settings import load_settings
+from abogen.webui.routes.utils.voice import template_options
+from abogen.webui.routes.utils.form import (
+    normalize_wizard_step,
+    wants_wizard_json,
+    render_wizard_partial,
+    wizard_json_response,
+    build_pending_job_from_extraction,
+    apply_book_step_form,
+    apply_prepare_form,
+    render_jobs_panel,
+)
+from abogen.text_extractor import extract_from_path
+from abogen.voice_profiles import serialize_profiles
+
+logger = logging.getLogger(__name__)
+
+main_bp = Blueprint("main", __name__)
+
+@main_bp.app_template_filter("datetimeformat")
+def datetimeformat(value: float, fmt: str = "%Y-%m-%d %H:%M:%S") -> str:
+    if not value:
+        return "—"
+    from datetime import datetime
+    return datetime.fromtimestamp(value).strftime(fmt)
+
+@main_bp.app_template_filter("durationformat")
+def durationformat(value: Optional[float]) -> str:
+    if value is None:
+        return ""
+    seconds = int(value)
+    if seconds < 60:
+        return f"{seconds}s"
+    minutes = seconds // 60
+    seconds = seconds % 60
+    if minutes < 60:
+        return f"{minutes}m {seconds}s"
+    hours = minutes // 60
+    minutes = minutes % 60
+    return f"{hours}h {minutes}m"
+
+@main_bp.route("/")
+def index():
+    pending_id = request.args.get("pending_id")
+    pending = get_service().get_pending_job(pending_id) if pending_id else None
+    
+    # If we have a pending job, redirect to the wizard
+    if pending:
+        step_index = getattr(pending, "wizard_max_step_index", 0)
+        # Map index to step name roughly
+        steps = ["book", "chapters", "entities"]
+        step_name = steps[min(step_index, len(steps)-1)]
+        return redirect(url_for("main.wizard_step", step=step_name, pending_id=pending.id))
+
+    jobs = get_service().list_jobs()
+    stats = {
+        "total": len(jobs),
+        "completed": sum(1 for j in jobs if j.status == JobStatus.COMPLETED),
+        "running": sum(1 for j in jobs if j.status == JobStatus.RUNNING),
+        "pending": sum(1 for j in jobs if j.status == JobStatus.PENDING),
+        "failed": sum(1 for j in jobs if j.status == JobStatus.FAILED),
+    }
+
+    return render_template(
+        "index.html",
+        options=template_options(),
+        settings=load_settings(),
+        jobs_panel=render_jobs_panel(),
+        stats=stats,
+    )
+
+@main_bp.route("/wizard")
+def wizard_start():
+    pending_id = request.args.get("pending_id")
+    step = request.args.get("step", "book")
+    if pending_id:
+        return redirect(url_for("main.wizard_step", step=step, pending_id=pending_id))
+    return redirect(url_for("main.wizard_step", step=step))
+
+@main_bp.route("/wizard/<step>")
+def wizard_step(step: str):
+    pending_id = request.args.get("pending_id")
+    pending = get_service().get_pending_job(pending_id) if pending_id else None
+    
+    normalized_step = normalize_wizard_step(step, pending)
+    if normalized_step != step:
+        return redirect(url_for("main.wizard_step", step=normalized_step, pending_id=pending_id))
+
+    if wants_wizard_json():
+        return wizard_json_response(pending, normalized_step)
+
+    return render_template(
+        "index.html",
+        options=template_options(),
+        settings=load_settings(),
+        jobs_panel=render_jobs_panel(),
+        wizard_mode=True,
+        wizard_step=normalized_step,
+        wizard_partial=render_wizard_partial(pending, normalized_step),
+    )
+
+@main_bp.route("/wizard/upload", methods=["POST"])
+def wizard_upload():
+    pending_id = request.form.get("pending_id")
+    pending = get_service().get_pending_job(pending_id) if pending_id else None
+    
+    file = request.files.get("file") or request.files.get("source_file")
+    
+    settings = load_settings()
+    profiles = serialize_profiles()
+
+    # Case 1: Updating existing job without new file
+    if pending and (not file or not file.filename):
+        try:
+            apply_book_step_form(pending, request.form, settings=settings, profiles=profiles)
+            get_service().store_pending_job(pending)
+            
+            if wants_wizard_json():
+                return wizard_json_response(pending, "chapters")
+            return redirect(url_for("main.wizard_step", step="chapters", pending_id=pending.id))
+        except Exception as e:
+            logger.exception("Error updating job settings")
+            error_msg = f"Failed to update settings: {str(e)}"
+            if wants_wizard_json():
+                return wizard_json_response(pending, "book", error=error_msg, status=500)
+            return render_template(
+                "index.html",
+                options=template_options(),
+                settings=settings,
+                jobs_panel=render_jobs_panel(),
+                wizard_mode=True,
+                wizard_step="book",
+                wizard_partial=render_wizard_partial(pending, "book", error=error_msg),
+            )
+
+    # Case 2: New file upload (or replacing file on existing job)
+    if not file or not file.filename:
+        if wants_wizard_json():
+            return wizard_json_response(None, "book", error="No file selected", status=400)
+        return redirect(url_for("main.wizard_step", step="book"))
+
+    filename = secure_filename(file.filename)
+    temp_dir = Path(current_app.config.get("UPLOAD_FOLDER", "uploads"))
+    temp_dir.mkdir(exist_ok=True)
+    file_path = temp_dir / f"{uuid.uuid4().hex}_{filename}"
+    file.save(file_path)
+
+    try:
+        extraction = extract_from_path(file_path)
+            
+        result = build_pending_job_from_extraction(
+            stored_path=file_path,
+            original_name=filename,
+            extraction=extraction,
+            form=request.form,
+            settings=settings,
+            profiles=profiles,
+        )
+        
+        # If we had a pending job, we might want to preserve its ID or other properties,
+        # but for a new file it's safer to start fresh with the new extraction.
+        # The frontend will handle the ID change via the redirect.
+        
+        get_service().store_pending_job(result.pending)
+        
+        if wants_wizard_json():
+            return wizard_json_response(result.pending, "chapters")
+            
+        return redirect(url_for("main.wizard_step", step="chapters", pending_id=result.pending.id))
+        
+    except Exception as e:
+        logger.exception("Error processing upload")
+        if file_path.exists():
+            try:
+                file_path.unlink()
+            except OSError:
+                pass
+                
+        error_msg = f"Failed to process file: {str(e)}"
+        if wants_wizard_json():
+            return wizard_json_response(None, "book", error=error_msg, status=500)
+            
+        return render_template(
+            "index.html",
+            options=template_options(),
+            settings=settings,
+            jobs_panel=render_jobs_panel(),
+            wizard_mode=True,
+            wizard_step="book",
+            wizard_partial=render_wizard_partial(None, "book", error=error_msg),
+        )
+
+@main_bp.route("/wizard/text", methods=["POST"])
+def wizard_text():
+    text = request.form.get("text", "").strip()
+    title = request.form.get("title", "").strip() or "Pasted Text"
+    
+    if not text:
+        if wants_wizard_json():
+            return wizard_json_response(None, "book", error="No text provided", status=400)
+        return redirect(url_for("main.wizard_step", step="book"))
+
+    temp_dir = Path(current_app.config.get("UPLOAD_FOLDER", "uploads"))
+    temp_dir.mkdir(exist_ok=True)
+    file_path = temp_dir / f"{uuid.uuid4().hex}.txt"
+    file_path.write_text(text, encoding="utf-8")
+
+    settings = load_settings()
+    profiles = serialize_profiles()
+
+    try:
+        extraction = extract_from_path(file_path)
+        # Override title since text extraction might not find one
+        extraction.metadata["title"] = title
+        
+        result = build_pending_job_from_extraction(
+            stored_path=file_path,
+            original_name=f"{title}.txt",
+            extraction=extraction,
+            form=request.form,
+            settings=settings,
+            profiles=profiles,
+        )
+        
+        get_service().store_pending_job(result.pending)
+        
+        if wants_wizard_json():
+            return wizard_json_response(result.pending, "chapters")
+            
+        return redirect(url_for("main.wizard_step", step="chapters", pending_id=result.pending.id))
+        
+    except Exception as e:
+        logger.exception("Error processing text")
+        if file_path.exists():
+            try:
+                file_path.unlink()
+            except OSError:
+                pass
+                
+        error_msg = f"Failed to process text: {str(e)}"
+        if wants_wizard_json():
+            return wizard_json_response(None, "book", error=error_msg, status=500)
+            
+        return render_template(
+            "index.html",
+            options=template_options(),
+            settings=settings,
+            jobs_panel=render_jobs_panel(),
+            wizard_mode=True,
+            wizard_step="book",
+            wizard_partial=render_wizard_partial(None, "book", error=error_msg),
+        )
+
+@main_bp.route("/wizard/update", methods=["POST"])
+def wizard_update():
+    pending_id = request.values.get("pending_id")
+    if not pending_id:
+        if wants_wizard_json():
+            return wizard_json_response(None, "book", error="Missing job ID", status=400)
+        return redirect(url_for("main.wizard_step", step="book"))
+
+    pending = get_service().get_pending_job(pending_id)
+    if not pending:
+        if wants_wizard_json():
+            return wizard_json_response(None, "book", error="Job expired or not found", status=404)
+        return redirect(url_for("main.wizard_step", step="book"))
+
+    current_step = request.form.get("step", "book")
+    next_step = request.form.get("next_step")
+    
+    settings = load_settings()
+    profiles = serialize_profiles()
+
+    try:
+        if current_step == "book":
+            apply_book_step_form(pending, request.form, settings=settings, profiles=profiles)
+            target_step = next_step or "chapters"
+            
+        elif current_step == "chapters":
+            # This step involves re-analyzing chunks if needed
+            (
+                chunk_level,
+                overrides,
+                enabled_overrides,
+                errors,
+                selected_total,
+                selected_config,
+                apply_config_requested,
+                persist_config_requested,
+            ) = apply_prepare_form(pending, request.form)
+            
+            if errors:
+                if wants_wizard_json():
+                    return wizard_json_response(pending, current_step, error="\n".join(errors), status=400)
+                return render_template(
+                    "index.html",
+                    options=template_options(),
+                    settings=settings,
+                    jobs_panel=render_jobs_panel(),
+                    wizard_mode=True,
+                    wizard_step=current_step,
+                    wizard_partial=render_wizard_partial(pending, current_step, error="\n".join(errors)),
+                )
+            
+            target_step = next_step or "entities"
+            
+        elif current_step == "entities":
+            # Just saving entity overrides
+            apply_prepare_form(pending, request.form)
+            target_step = next_step or "entities" # Stay or finish
+            
+        else:
+            target_step = "book"
+
+        get_service().store_pending_job(pending)
+        
+        if wants_wizard_json():
+            return wizard_json_response(pending, target_step)
+            
+        return redirect(url_for("main.wizard_step", step=target_step, pending_id=pending.id))
+
+    except Exception as e:
+        logger.exception(f"Error updating wizard step {current_step}")
+        error_msg = f"Update failed: {str(e)}"
+        if wants_wizard_json():
+            return wizard_json_response(pending, current_step, error=error_msg, status=500)
+            
+        return render_template(
+            "index.html",
+            options=template_options(),
+            settings=settings,
+            jobs_panel=render_jobs_panel(),
+            wizard_mode=True,
+            wizard_step=current_step,
+            wizard_partial=render_wizard_partial(pending, current_step, error=error_msg),
+        )
+
+@main_bp.route("/wizard/cancel", methods=["POST"])
+def wizard_cancel():
+    pending_id = request.values.get("pending_id")
+    if pending_id:
+        remove_pending_job(pending_id)
+    
+    if wants_wizard_json():
+        return jsonify({"status": "cancelled", "redirect_url": url_for("main.index")})
+        
+    return redirect(url_for("main.index"))
+
+@main_bp.route("/wizard/finish", methods=["POST"])
+def wizard_finish():
+    pending_id = request.values.get("pending_id")
+    if not pending_id:
+        if wants_wizard_json():
+            return jsonify({"error": "Missing job ID"}), 400
+        return redirect(url_for("main.index"))
+
+    pending = get_service().get_pending_job(pending_id)
+    if not pending:
+        if wants_wizard_json():
+            return jsonify({"error": "Job not found"}), 404
+        return redirect(url_for("main.index"))
+
+    # Final update from form
+    apply_prepare_form(pending, request.form)
+    
+    # Submit job
+    job_id = submit_job(pending)
+    
+    if wants_wizard_json():
+        return jsonify({
+            "status": "submitted",
+            "job_id": job_id,
+            "redirect_url": url_for("main.index"),
+            "jobs_panel": render_jobs_panel()
+        })
+        
+    return redirect(url_for("main.index"))