CLI reference

Invocation: python main.py [options]

General

Flag	Value	Default	Description
`--cli`	—	not set	Run in CLI mode instead of GUI
`--version`	—	not set	Show program's version number and exit

CLI Options

Flag	Value	Default	Description
`--text, -t`	`str`	not set	Text to synthesize
`--file, -f`	`Path`	not set	Text file to synthesize
`--voice, -v`	`str`	not set	Voice profile to use (name or path to reference audio)
`--output, -o`	`Path`	output.wav	Output audio file path (default: output.wav)
`--backend, -b`	`{f5-tts,gpt-sovits,fish-speech}`	f5-tts	TTS backend to use (default: f5-tts)

Performance Options

Flag	Value	Default	Description
`--quantization, -q`	`{fp16,int8,int4,gguf-q4,gguf-q8}`	int8	Quantization level (default: int8)
`--device`	`{cuda,cpu,auto}`	auto	Device to use (default: auto)

Backend choices are model backends, not runtime targets. --backend accepts f5-tts, gpt-sovits and fish-speech. The ONNX / OpenVINO / TensorRT / DirectML / llama.cpp / vLLM classes live in the registry used by the GUI and auto-selector; their synthesis methods are not implemented.

Examples

synthesize

# Short text
python main.py --cli --text "Hello from the studio." --output hello.wav

# From a UTF-8 text file
python main.py --cli --file input.txt --output output.wav

# Reference audio for zero-shot cloning
python main.py --cli --text "Hello" \
  --voice reference.wav --backend f5-tts --output cloned.wav

# Force CPU and FP16
python main.py --cli --text "Hello" --device cpu --quantization fp16

--voice accepts a path to a reference audio file (WAV/MP3/FLAC/OGG/M4A) or the name/ID of a saved speaker profile. Profiles are stored in ~/.config/voicesynth/profiles.db.

CLI behaviour worth knowing

Output sample rate follows the backend. The CLI now saves the sample rate returned by synthesis instead of assuming 24 kHz, so GPT-SoVITS (32 kHz) is written correctly.
No input is an error. Pass --text or --file; the process exits non-zero otherwise.
Model loading is lazy. The manager loads the backend on the first synthesize() call.
Quantization is accepted, not guaranteed. The CLI exposes five levels, but the F5-TTS backend effectively implements FP16 and INT8. On CUDA, INT8 falls back to FP16 with a log line; CPU can apply dynamic INT8. INT4/GGUF flags do not magically quantize an F5 checkpoint.
Language is a hint. auto uses a character heuristic: Romanian diacritics → ro, CJK → zh, otherwise en.

Studio guide

Launch with python main.py. The main window is a tabbed workspace with a GPU monitor on the right.

01

Text-to-Speech

Write or paste text. Choose voice, language (EN/RO/ZH/auto), backend, adapter, NFE steps (4–64), sampler (Euler/Midpoint/RK4), speed (0.5–2.0×), seed and chunking mode. Generate, inspect the waveform, play the result and export WAV.

02

Voice Cloning

Drop a reference clip, transcribe it with faster-whisper if installed, review/edit the transcript, then save a profile. The profile can be selected anywhere a voice is requested.

03

Backends

Shows the registry entries and install hints. The panel exposes options for ONNX providers, llama.cpp context/GPU layers, OpenVINO devices and DirectML device IDs; these configure loaders, not missing synthesis code.

04

Quantization

Lists supported methods and memory estimates. The bitsandbytes path is implemented; GGUF/GPTQ/AWQ conversion controls are placeholders and the UI warns about that.

05

Presets

Four built-in VRAM presets (Ultra Low, Low, Balanced, Quality) plus custom presets persisted as JSON. Presets are configuration templates; they do not benchmark your machine.

06

Batch

Paste one job per line, choose priority, voice and adapter. The queue runs jobs through the same inference manager with pause, resume, cancel and per-job status.

07

Monitor

VRAM, utilization, temperature and memory-manager statistics. Without NVML the widget degrades to a “not available” state instead of crashing.

Profiles & cloning

A SpeakerProfile stores a name, tags, description, reference samples (path, transcript, duration), a quality score and optional embedding data. Profiles can be exported/imported as human-readable .vsp JSON files.

Sample quality is scored locally from duration, RMS energy, clipping and silence ratio. The voice-fusion module can blend multiple spectral embeddings (average, quality-weighted, duration-weighted), but the GPT-SoVITS and Fish branches currently reuse a generic mel-statistics embedding rather than their native encoders.

Batch queue

The queue is a priority worker thread. Jobs carry text, voice, adapter, optional reference audio and output path. Callbacks fire on start, progress, completion and error.

python

from core.batch_queue import BatchQueue, JobPriority

queue = BatchQueue(inference_manager=manager)
queue.add_batch(
    texts=["First line.", "Second line."],
    voice="reference.wav",
    output_dir="out",
    priority=JobPriority.NORMAL,
)
queue.start()

Python API

The orchestrator is small enough to embed directly.