Optional Voice Tools

English · 简体中文 · 日本語

Optional Voice Tools

You do not need native Voice Tools to make a basic audiobook. Start with First Audiobook and Voices. Install the add-on when you need the native Preparer/Voice Lab stages or Pinokio's bundled local LLM launchers.

Return to Home · Prerequisites: Installation · Related: LLM Setup

What belongs to the normal install?

The core install supplies the audiobook app, Qwen3-TTS, Designer, Dataset Builder, and the Training tab's application dependencies. The presence of these tabs does not mean every advanced native tool or model is installed.

• Designer: create a voice from a description and save a reference.
• Dataset: build a dataset from generated samples, with preview and editing.
• Training: train a LoRA from a prepared dataset using the app's interpreter.
• Preparer: turn existing audio and optional source text into dataset ZIPs; it needs its own prepared native environment.
• Voice Lab: run a multi-stage dataset-to-adapter workflow using the configured interpreter and any required profiler model.

Training and local voice design still need suitable hardware, disk space, model weights, and compatible dependencies. They are optional workflows, not prerequisites for Custom or Clone voices.

Install the native tools in Pinokio

1. Save active work and stop the app. Finish or cancel running generation/training jobs first.
2. In Pinokio choose Install Voice Tools (Optional).
3. Let all native builds and downloads finish. Inspect the installer terminal if a step fails.
4. Start the app again and configure the paths required by the tool you plan to use.

The installer:

• Builds llama-cpp-python[server] for the detected CUDA, HIP, Metal, or CPU path in app/env.
• Creates an isolated CPython 3.10 preparer_env when it is missing, installs platform-specific PyTorch, and constrains subsequent dependency installation to that stack.
• Installs the Preparer requirements and its own llama-cpp-python build.
• Fetches pinned whisper.cpp source and a pinned model, checks the assets, then builds the selected backend.
• Installs optional pyannote diarization dependencies only on Linux AMD, whose current PyTorch pin meets pyannote 4's requirement.

Native builds require CMake and a working C/C++ toolchain, plus the matching CUDA/ROCm SDK for GPU builds. This is additional download, build time, and disk usage. The base Docker image does not run this installer or contain a prepared preparer_env; do not assume its advanced native stages are ready because the web page loads.

Check the environments

From the checkout root, using an available Python interpreter:

python env_doctor.py
python env_doctor.py --voice-tools

The first checks app/env; the second also checks the configured Voice Lab interpreter and Preparer environment. Add --json for a machine-readable report. A dependency check is not a full audio-generation, training, or GPU compatibility test.

The three environments have different roles:

Environment	Used for
app/env	Web app, ordinary local TTS/Training, bundled llama_cpp.server launcher
preparer_env	Native audio preparation; diarization dependencies belong here when supported
Voice Lab's ROCm Python	Voice Lab stages; defaults can use the app interpreter, or you can configure a separate prepared interpreter

The ROCm Python field is the UI's current label; it is an interpreter path, not proof that ROCm is installed or required for every possible stage. Choose an interpreter with that stage's dependencies. Do not point it at an empty environment or assume preparer_env contains the whole TTS training stack.

Prepare an audio dataset

Use your own recordings or audio with permission covering the intended processing and voice use. A dataset derived from someone else's voice is not automatically yours to redistribute or impersonate with.

1. Open Preparer and select a WAV/MP3 audio file.
2. Open Advanced (source alignment & LLM enrichment). Supply a real local GGUF path in Primary GGUF Model (optional, default from Setup).
   • Despite that field's current label, the normal preparation command requires a primary model path. Do not rely on an API model name or the Setup URL to supply a local GGUF.
   • Fallback GGUF Model (optional) is another local file path.
3. Optionally attach matching Source Text (EPUB/TXT, optional). Source-guided alignment can correct transcript spelling from the book. Make sure the text corresponds to the recorded edition.
4. Choose Output Filename, Language, and quality thresholds. For source alignment, Source Threshold controls the required match. Raising confidence/SNR/match thresholds rejects more material; relaxing them is not a quality repair.
5. Keep Speaker Diarization: Off unless you have the additional prerequisites below. Leave enrichment off until the baseline preparation succeeds.
6. Click Start Preparation and watch Execution Logs. When complete, use Completed Datasets to download the produced ZIPs. Inspect sample audio and transcripts before training.

Batch Mode accepts multiple audio files and makes separate dataset ZIPs. It is not the same as the command-line workflow for explicitly paired audio and source books.

Diarization and enrichment

Diarization separates speakers in existing audio. It is not the speaker annotation used by the core book-to-script workflow.

• Auto-detect multiple speakers and Always diarize require pyannote dependencies in the interpreter running Preparer, plus access to the Community-1 model.
• Accept that model's terms on Hugging Face and provide a token with the necessary access. The Preparer UI's Hugging Face Token is used for that run and is not saved by the UI. HF_TOKEN in the launch environment is also supported.
• The shipped optional installer only provisions this on Linux AMD. Do not install pyannote into app/env to work around a missing module: its PyTorch requirements can conflict with other platform pins.
• LLM enrichment requires Enrichment LLM Model Path and at least one selected enrichment task, such as Speaker attribution, Narration style, or Emotional tone. This is a separate local GGUF path, not your OpenAI-compatible server address.

For advanced installations, ALEXANDRIA_PREPARER_PYTHON selects the Preparer interpreter. ALEXANDRIA_WHISPER_CPP_BIN and ALEXANDRIA_WHISPER_CPP_MODEL override the whisper.cpp binary and model paths. Use these only after preparing and verifying those files.

Use Voice Lab deliberately

Voice Lab can run Quality → Dedup → Train → Evaluate → Profile → Name. Open Pipeline settings & environment, set the actual paths, and click Save settings:

• ROCm Python: the interpreter with the required stage dependencies
• Profiler model (GGUF, optional): your local profiler model, when using Profile; the default expects a specific GGUF in the checkout root, not an automatically downloaded model
• Default input folder: your narrator-dataset folder
• EPUB search folders (optional): one folder per line for book context in voice descriptions

Then choose an Input folder (narrator subfolders) and click Inspect. Select only the Stages to run you intend, check the displayed preflight, and use Run Pipeline. Changed inputs require a fresh preflight.

Read the stage descriptions carefully:

• Quality is a warning-only health/duplicate audit.
• Dedup can merge confirmed matches and remove exact duplicate clips in its processing workflow. Keep originals backed up.
• Train consumes substantial resources and creates adapters; passing a preflight is not a guarantee that the run will fit all later workloads.
• Evaluate reports probe-based similarity, silence, and clipping evidence. Listen as well.
• Profile needs the native LLM dependency and model.
• Name stage: actually rename is checked by default. Uncheck it for a dry-run naming preview. Renaming is a real change to adapter artifacts.

Use Copy diagnostics or Download diagnostics for support, and review even sanitized output before sharing it.

Dataset and Training basics

For a manually prepared training dataset, use a ZIP with WAV clips and metadata.jsonl records containing audio_filepath and text. The documented target audio format is 24 kHz mono. References must point to files inside the dataset, and transcripts should accurately match the recorded words. Use Build New Dataset if you want to create samples in the app instead.

In Training:

1. Upload the ZIP or choose an existing Dataset.
2. Enter an Adapter Name.
3. Review Epochs, Learning Rate, Batch Size, LoRA Rank, LoRA Alpha, Grad Accum Steps, and Language.
4. Use Start Training and watch its progress and logs.
5. Test the resulting adapter on held-out lines before assigning it throughout a book. Compare it with a Clone voice made from a clean reference.

Use the current UI defaults as a starting point, not a quality guarantee. More clips, higher rank, more epochs, or a lower training loss do not by themselves establish a better voice. Recording consistency, transcript accuracy, language, expressiveness, and evaluation all matter. Train in small, inspectable experiments before a large library job.

Do not generalize Voice Lab's resource preflight floors into recommended system specifications. A check that permits a run does not measure end-to-end memory use or performance for your dataset.

Command-line entry points

After installing the native tools, run these from the checkout root. On Windows replace preparer_env/bin/python with preparer_env\Scripts\python.exe.

preparer_env/bin/python alexandria_batch_processor.py --help
preparer_env/bin/python alexandria_compare.py --help

The batch processor supports audiobook folders and matching source folders with an explicit GGUF model. The comparison tool supports reviewing extracted datasets against their source. Read their help before a production run and keep source audio/datasets backed up.

download_model.py downloads a standalone legacy Whisper-base Transformers bundle. It does not fetch a GGUF LLM or replace the current whisper.cpp setup. The Linux start_llama_server.sh / ensure_llama_server.sh helpers likewise expect a separately installed native llama-server and explicitly configured model paths; they do not install either one.

Continue to Voices to use an adapter, Rendering and Export to render, or Troubleshooting if a dependency/path check fails.

Sources

Verified against shipped main at 8c7a33cb310ab9264594a09ca27e48271585094f: optional installer, advanced UI, Preparer routing, Preparer CLI, Voice Lab routing, Training routing, environment doctor.