Quickstart

From clone to first WAV.

VoiceSynth Studio runs the model locally, but the models are not vendored in this repository. Plan for a Python environment, network access for the first weight download, and a few gigabytes of disk.

Requirements

Python	3.10–3.12. The pinned torch/torchaudio wheels in `requirements_ultimate.txt` do not cover 3.13.
OS	Windows is the primary tested path. Linux works for the Python core; the `.bat` helpers are Windows-only.
GPU	Optional. CUDA is used when `torch.cuda.is_available()`; otherwise the manager resolves to CPU. The declared F5-TTS VRAM floor is 1.5 GB.
Disk	Room for a Python environment plus model weight caches. The F5-TTS checkpoint alone is a multi-gigabyte download.
Network	Required once to download weights. Inference itself does not call a cloud TTS service.

About the lockfile. requirements_ultimate.txt pins a Windows/CUDA 12.1 stack, including a Windows-only bitsandbytes wheel and torch==2.5.1+cu121. On Linux, install the matching torch/torchaudio build from pytorch.org first, then install the remaining packages. It is a full research environment, not a minimal runtime.

1 · Install

Clone the repository and create an isolated environment.

terminal

git clone https://github.com/FiredMosquito831/LOCAL-Text-to-Speech-Synthesis.git
cd LOCAL-Text-to-Speech-Synthesis

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

python -m pip install --upgrade pip
pip install -r requirements_ultimate.txt

The requirements file installs F5-TTS from its upstream Git revision and includes PyQt6, faster-whisper, ONNX Runtime, OpenVINO and the other optional libraries used by the studio panels.

Verify the Python core without loading a model. python test_all.py imports every module and exercises the model-free services. It does not download weights.

2 · Model weights

F5-TTS is the default backend. Its load() path downloads the F5TTS_v1_Base checkpoint with huggingface_hub and then loads the vocoder. The first synthesis will therefore be slower and requires network access.

optional · prefetch

# Downloads GPT-SoVITS v2 weights and attempts the Romanian F5 adapter.
# F5-TTS weights are fetched automatically by the F5 backend on first use.
python scripts/setup_weights.py

scripts/setup_weights.py expects a GPT-SoVITS checkout at ./GPT-SoVITS. The Fish Speech branch only prints download instructions; it does not fetch weights.

3 · First synthesis

Use the CLI with the default backend and an explicit output path.

terminal

python main.py --cli --text "The tape is rolling." --output hello.wav

Or synthesize a whole text file:

terminal

python main.py --cli --file script.txt --output script.wav
python main.py --version

The CLI prints the resolved backend, quantization and text length, then writes WAV audio at the backend's own sample rate (24 kHz for F5-TTS).

4 · Open the studio

terminal

python main.py

PyQt6 opens the studio with TTS, voice cloning, backend configuration, quantization, presets, batch processing and a GPU monitor. If PyQt6 is not installed, the entry point exits with the install hint rather than silently falling back.

Optional backends

The model integrations import third-party repositories that are gitignored in this project. Clone them next to main.py if you need them:

GPT-SoVITS

git clone https://github.com/RVC-Boss/GPT-SoVITS.git --depth 1
python scripts/setup_weights.py
python main.py --cli --backend gpt-sovits --text "Test" --output gpt.wav

Fish Speech is a scaffold. The backend's inference engine is not wired up in this revision. It falls back to a 330 Hz placeholder tone. Do not evaluate the project on Fish Speech output yet.

Troubleshooting

“F5-TTS not properly installed”: The f5_tts package is missing. Install it from the pinned Git URL in the requirements file, or clone F5-TTS and run pip install -e ./F5-TTS.
PyQt6 import error: Install PyQt6 in the active environment: pip install PyQt6==6.10.2 (the pinned version).
The first run hangs while “Downloading model weights…”: That is the Hugging Face download. Check the connection and the cache at ~/.cache/huggingface/hub.
GPU out of memory: Choose a lower NFE count, select a 24 kHz model that fits, or run on CPU. The repo does not ship a magic 6 GB guarantee; the memory manager and presets are targets, not measured envelopes.
No audio in hello.wav / a beep instead of speech: You are probably on GPT-SoVITS without the package or Fish Speech (scaffold). The code returns placeholder tones in those cases; check the log warning.

NEXT CLI reference & studio guide → REFERENCE Backend capability matrix →