A system-level Select-to-Speak desktop reader that brings your favorite characters to life with their own voices while you read.
Important
MaidWhisper is preparing for its first Public Beta. Features, installation workflows, and GPT-SoVITS integration may still be adjusted during the beta period. We recommend reading the System Requirements, GPT-SoVITS Guide, and Disclaimer before testing.
Caution
An NVIDIA GPU is strongly recommended. GPT-SoVITS can run on some CPU-only systems, but voice synthesis is usually extremely slow, making daily reading almost unusable. If you want to use MaidWhisper as a real-time, system-level Select-to-Speak tool, please prepare an NVIDIA GPU capable of running GPT-SoVITS, adequate VRAM, and a compatible CUDA / PyTorch environment.
- What Is MaidWhisper?
- Why MaidWhisper?
- Preview
- Main Features
- System Requirements
- Project Status
- Quick Start
- AI Persona & Translation
- Data & Privacy
- GPT-SoVITS Resources
- FAQ
- Developer Documentation
- Disclaimer
- Support Development
- License
MaidWhisper is a Windows Select-to-Speak desktop tool with real-time voice synthesis powered by a GPT-SoVITS backend.
Instead of building another complex WebUI, its goal is to transform GPT-SoVITS into a seamless, system-level reading companion for daily use: select text in any window, press a global hotkey, and a floating control panel immediately handles reading, character switching, language selection, and lyrics synchronization.
MaidWhisper is ideal for reading light novels, web pages, documents, chat logs, and long-form text. It is designed for users who want to enjoy reading with familiar character voices without having to manually copy text, launch a WebUI, switch models, and send synthesis requests every single time.
Select Text → Global Hotkey → Language Detection → (Optional LLM Preprocessing) → Segmentation → GPT-SoVITS Synthesis → Playback + Lyrics Sync
| Key Highlight | Description |
|---|---|
| System-Level Global Trigger | Trigger directly via hotkey from browsers, e-readers, documents, chat apps, or any window with selectable text. |
| Floating Control Panel | No need to switch back to the main window; character, language, tone, speed, volume, and playback state are centralized in a lightweight panel. |
| Effortless Character Switching | Centralized management of multi-character, multi-language, and multi-tone configurations for quick voice switching during reading. |
| Designed for Daily Use | Supports instant reading upon text capture, as well as text staging and previewing before playback—ideal for long reading sessions. |
| No Tedious WebUI Operations | GPT-SoVITS handles synthesis while MaidWhisper automates text capture, model selection, segmentation, playback, and lyrics sync. |
| Real-Time Playback Experience | Segmented synthesis and pre-buffered playback reduce waiting times, integrating voice generation smoothly into your reading workflow. |
| User-Friendly for Everyone | Installer with optional GPT-SoVITS backend setup, settings persistence, tray controls, status alerts, and FAQ guide non-developers through configuration step by step. |
Select text, press hotkey, and read aloud with character voice |
AI translates text into character language before reading |
Floating Playback Control Panel |
Lyrics Sync and Click-to-Jump |
General Settings |
Playback & GPT-SoVITS Backend |
Character, Language & Tone Models |
AI Persona & Translation |
System Integration, Hotkeys & UI Language |
|
| Demo | Audio File |
|---|---|
| Character Voice Demo 1 | DemoVoice_1.wav |
| Character Voice Demo 2 | DemoVoice_2.wav |
| Character Voice Demo 3 | DemoVoice_3.wav |
| Character Voice Demo 4 | DemoVoice_4.wav |
| Character Voice Demo 5 | DemoVoice_5.wav |
Demo audio files are provided solely to demonstrate MaidWhisper's reading workflow and audio quality. Actual output will vary depending on your GPT-SoVITS models, reference audio, synthesis speed, and playback settings.
- System-Level Global Hotkeys: Trigger after selecting text in any desktop application without switching windows or launching a WebUI.
- Floating Control Panel: Compact floating panel for quick control over character, language, tone, speed, volume, and playback state.
- Clickable Lyrics Sync: Segmented text display supporting click-to-jump navigation, manual scrolling, and auto-centering on active segments.
- Reading Staging & Preview: Option to disable "Auto-read on Capture", allowing text staging and previewing before generating audio.
- Daily Reading Workflow: Panel position memory, tray operations, and hotkey design make it feel like an OS system utility rather than a one-time generator.
- Multi-language GPT-SoVITS models, reference audio, and reference text per character profile.
- Independent speed and temperature controls per language profile.
- Automatic input language detection and profile auto-switching (optional).
- Floating panel filters to display only fully configured character / language / tone models.
- AI Character Persona: Rewrites text to match character speaking styles (Conservative / Natural / Expressive / Free).
- AI Translation: Translates text into the target character language (supports Traditional or Simplified Chinese preferences).
- Smart Skip: Automatically skips LLM calls when the input language matches target language and no style adjustment is required.
- Automatic GPT-SoVITS idle release and auto-wake before reading starts.
- System Tray integration, startup options, Always-on-Top, and decoupled main window / floating panel.
- Multi-language UI support (i18n).
- Panel geometry and playback preference persistence.
- Secure API key storage using Windows Credential Manager (never stored in config JSON files).
| Item | Requirement |
|---|---|
| Operating System | Windows 10 or later |
| GPU / VRAM | NVIDIA GPU Recommended; CPU-only synthesis is theoretically supported but usually very slow. |
| GPT-SoVITS Model | SoVITS .pth · GPT .ckpt · Reference Audio · Matching Reference Text |
| LLM (Optional) | AI Persona / AI Translation require an API key from a compatible LLM provider. |
MaidWhisper is currently preparing for its first Public Beta. Core reading pipelines, floating panels, character model management, LLM preprocessing, GPT-SoVITS runtime integration, and the Windows installer have entered integration testing.
Key Beta Goals:
- Validate that end users can complete installation, configure character models, and begin reading.
- Continuously refine GPT-SoVITS startup, release, model switching, and error handling.
- Finalize READMEs, FAQ, Release Checklist, and Known Issues documentation.
- Collect compatibility feedback across diverse GPU hardware, model versions, and GPT-SoVITS environments.
We prioritize local workflow stability, maintainability, and clarity over bundling built-in models or cloud service dependencies.
MaidWhisper handles "text capture, floating panel control, character switching, playback, and lyrics sync." Voice generation itself is powered by GPT-SoVITS, so before starting for the first time, prepare:
- MaidWhisper Installer.
- Executable GPT-SoVITS API environment.
- At least one set of character model files: SoVITS
.pth, GPT.ckpt, reference audio, and reference text.
Once the Public Beta is released, download the latest MaidWhisper-*-Setup.exe from GitHub Releases and launch the setup program.
You may select the optional Install GPT-SoVITS checkbox during setup. If selected, the installer will download and configure a MaidWhisper-managed GPT-SoVITS backend environment (download and extraction typically takes 5 to 10 minutes depending on network and disk speed).
If your system lacks an NVIDIA GPU, you can still test setup and execution, but expect CPU synthesis to be significantly slower. We recommend testing with short sentences first.
| Your Situation | Recommended Action |
|---|---|
| First time using GPT-SoVITS | Run the Release Setup executable and check Install GPT-SoVITS. |
| Already have a working GPT-SoVITS | No need to reinstall; specify your existing launch script and API URL in Settings. |
| Only want to read original text | Skip LLM settings; add a character model and start reading immediately. |
| Want translation or AI character voice styling | Complete basic setup first, then go to Settings → LLM to enable AI Translation or Persona. |
- Install and launch MaidWhisper.
- If you do not have GPT-SoVITS, check Install GPT-SoVITS during setup and wait for installation to finish.
- If you already have GPT-SoVITS, refer to Using Existing / Self-Provided GPT-SoVITS to configure your launch script and API URL.
- Go to Settings → Characters and click Add Character.
- Under the character profile, add a language and tone, select
.pth,.ckpt, reference audio files, and enter the reference text. - Save settings and return to normal usage.
If you did not check Install GPT-SoVITS during MaidWhisper setup and plan to use an existing standalone GPT-SoVITS installation, pay close attention to these configuration steps:
Important
1. Launch api_v2.py, NOT webui.py!
MaidWhisper communicates with GPT-SoVITS via HTTP API endpoints. Launching webui.py only starts the browser GUI interface and does not expose TTS API services, causing MaidWhisper connection failures.
2. Port Alignment
api_v2.py defaults to port 9880 (http://127.0.0.1:9880). If your launch script uses a custom port (e.g. -p 9872), update MaidWhisper Settings → General → GPT-SoVITS API URL accordingly.
Inside your GPT-SoVITS folder, create a .bat file (e.g., start_api_v2.bat):
Option A: Official Standalone Windows Package (with bundled Python runtime)
@echo off
:: Change to GPT-SoVITS root directory
cd /d "%~dp0"
:: Start api_v2.py using the bundled python executable (Default Host: 127.0.0.1, Port: 9880)
runtime\python.exe api_v2.py -a 127.0.0.1 -p 9880
pauseOption B: Conda or Independent Python Environment
@echo off
:: Change to your GPT-SoVITS project directory
cd /d "C:\YourPath\GPT-SoVITS"
:: Activate virtual environment and launch api_v2.py
call conda activate gpt-sovits
python api_v2.py -a 127.0.0.1 -p 9880
pauseTip
Double-click the .bat file to test. If the terminal shows INFO: Uvicorn running on http://127.0.0.1:9880 or a success startup message, your GPT-SoVITS API is operating properly.
- Open MaidWhisper ⚙️ Settings → General.
- GPT-SoVITS API URL: Set to
http://127.0.0.1:9880(matching your script port). - GPT-SoVITS Launch Script Path: Click Browse and select
start_api_v2.bat. - Auto-start GPT-SoVITS: (Optional) Enable this option so MaidWhisper can launch the script automatically when reading is requested and the API is offline.
- Select text in a browser, eBook reader, PDF viewer, chat app, or other software.
- Press the global hotkey (default:
Alt+Shift+M). - MaidWhisper opens the floating control panel.
- Select your desired character, language, and tone.
- Click Play (or start playback automatically if "Auto-read on Capture" is enabled).
- Click lyrics lines to jump between segments, or switch character voices directly on the floating panel.
Daily usage does not require manually opening the GPT-SoVITS WebUI or pasting text into web forms. MaidWhisper invokes the GPT-SoVITS API on demand and manages text segmentation, voice generation, audio playback, and status feedback seamlessly.
AI Character Persona and AI Translation are completely optional. When needed, configure Provider, Model, and API Key under Settings → LLM.
- Read original text as-is: No LLM configuration required.
- Translate text into character language: Enable AI Translation.
- Rewrite text in character tone: Enable AI Persona and enter tone descriptions in character settings.
The installer's GPT-SoVITS option sets up a local API environment managed by MaidWhisper:
- Downloads the official Windows integrated package.
- Extracts files to your chosen path.
- Locates bundled Python and
api_v2.py. - Generates
MaidWhisper-GPT-SoVITS.cmd. - Automatically imports launcher paths and API URLs into MaidWhisper.
MaidWhisper only executes the GPT-SoVITS API service—it does not launch training tools or full web interfaces. Model training, audio slicing, labeling, and fine-tuning should still be performed using standard GPT-SoVITS toolchains.
# Build Qt Client following doc/MaidWhisper-System-Design.md
# Launch local Python Server
python server/run_server.pySee Developer Documentation for details.
LLM preprocessing is an optional feature that does not affect basic GPT-SoVITS voice synthesis pipelines.
| Feature | Description |
|---|---|
| AI Character Persona | Adjusts text style based on tone descriptions in character settings. |
| AI Translation | Translates input text into the active character language (supports Traditional/Simplified Chinese preferences). |
| Smart Skip | Automatically skips LLM calls if detected text language matches target language and no style rewriting is requested. |
API keys are securely stored in Windows Credential Manager and are never written to standard settings JSON files.
MaidWhisper operates primarily offline on your local machine. Character profiles, model paths, playback preferences, and audio caches are stored in your local user data directory. GPT-SoVITS voice synthesis is processed by your specified local API.
Text is sent to your configured LLM Provider only when AI Character Persona or AI Translation is enabled. Without LLM features enabled, MaidWhisper requires zero external service calls for reading.
Data Security Standards:
- LLM API keys are stored in Windows Credential Manager.
- Configuration JSON files never store API keys.
- Users maintain full local control over GPT-SoVITS models, reference audio, and synthesized outputs.
- When using external LLM providers, please consult your provider's privacy and data retention policies.
| Resource | Purpose | Notes |
|---|---|---|
| Official GPT-SoVITS Project | Installation, versioning, and model specifications | Recommended reading for official documentation |
| Official Windows Package | Quick Windows environment setup | Source utilized by the installer's GPT-SoVITS setup option |
| Hugging Face Model Search | Search community-contributed models | Verify licenses and sources before downloading |
| ModelScope Model Search | Chinese community models | Verify licenses and sources before downloading |
| GPT-SoVITS Model Collection | Curated community model repository | Verify model versions, sources, and permissions |
Warning
Community models may contain unverified files or unclear license permissions. Only download assets from trusted sources, and verify usage rights for models, audio files, character names, and generated content.
No. MaidWhisper is a local reading workflow tool. It does not provide, host, or distribute third-party character models or voice assets. You must supply your own compatible .pth, .ckpt, reference audio, and reference text files.
Yes. MaidWhisper synthesizes audio via the GPT-SoVITS API. You can either check Install GPT-SoVITS during setup or point MaidWhisper to your existing GPT-SoVITS launcher and API URL.
No. MaidWhisper focuses on daily reading, global hotkeys, floating control panels, and playback workflows. Model training, slicing, labeling, and fine-tuning should still be conducted in standard GPT-SoVITS tools.
Yes. Specify your .bat / .cmd launch script and GPT-SoVITS API URL in Settings. Make sure to launch api_v2.py instead of webui.py and align port numbers. See Using Existing / Self-Provided GPT-SoVITS Guide.
CPU execution is theoretically possible, but GPT-SoVITS voice synthesis is usually very slow on CPU. For comfortable daily reading, an NVIDIA GPU with proper CUDA / PyTorch environments is strongly recommended.
No. Both are optional LLM preprocessing features. When disabled, MaidWhisper passes selected text directly to segmentation and voice synthesis. External LLM providers are called only when these features are enabled.
LLM API keys are stored in Windows Credential Manager and are never saved to standard settings JSON files. Only provider names, model names, and non-sensitive settings are stored in configuration files.
The floating panel only displays fully configured character and language profiles. A complete profile requires model files, reference audio, and reference text to prevent synthesis failures.
Any switch that alters text content, model parameters, voice settings, or segmentation requires reprocessing from the corresponding pipeline stage. If the new selection shares existing cached audio content, MaidWhisper preserves current playback position whenever possible.
The uninstaller removes application binaries. User data, settings, models, and audio caches are preserved in your local user data folder to allow seamless reinstallation. To completely remove all data, manually backup and delete the MaidWhisper user data directory.
MaidWhisper provides no licensing for third-party models, character IP, audio files, or generated content. Whether generated audio can be published, monetized, or redistributed depends on your model licenses, asset rights, character copyright, platform terms, and local legal jurisdiction.
| Document | Description |
|---|---|
| Project Guide | Architecture overview, runtime flows, and entry points |
| System Design | Design targets, pipeline contracts, text state, and restart strategies |
| Development Plan | Milestones and TODO items |
| Runtime Layout | Directory structure and path resolution after installation |
| Release Checklist | Pre-release checklist |
| Release Acceptance Matrix | Manual acceptance test matrix |
| CI/CD & Windows Installer | Automated build and release workflows |
| 2026-06-05 Architecture Analysis | Pipelines, coupling, data separation, and pre-beta risk assessment |
| Server API & GPT-SoVITS Bridge | Python Server endpoints and bridge documentation |
| Packaging Guide | Installer setup and packaging workflow |
MaidWhisper is a local voice generation workflow tool. It does not provide, host, or license third-party character models, voice assets, text content, or LLM services. Users must independently ensure that:
- You hold or have obtained necessary rights for models, reference audio, text, and character assets.
- You comply with applicable local laws, model licenses, platform terms, and third-party intellectual property rights.
- Generated audio is never used for impersonation, fraud, harassment, deception, or unlawful infringement.
- You accept full responsibility for all audio generated, published, or distributed.
The authors and contributors of this project provide no guarantees and assume no liability for user inputs, third-party models, third-party services, generated outputs, or subsequent downstream usage.
| Method | Address |
|---|---|
| USDT TRC-20 | TXmghw1R9QaQSKGWEWP9ydr1xj8G1MqHrL |
| ETH ERC-20 | 0xe7b06b924cbca4b922585a4ccd665cd2c3d0e02c |
MaidWhisper is released under the GNU General Public License v3.0.
Made with ♥ · Powered by GPT-SoVITS