Quickstart¶

VoiceHub keeps configuration, processing, pretrained loading, inference, and training behind a small public surface shared by text-to-speech (TTS), automatic speech recognition (ASR), and voice activity detection (VAD).

This quickstart shows you how to:

load a pretrained speech model;
run inference with pipeline(); and
inspect training support before constructing a Trainer.

Set up¶

Choose your platform. Each option creates an isolated environment and installs VoiceHub from source.

LinuxmacOSWindows

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "voicehub @ git+https://github.com/kadirnar/voicehub.git@main"

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "voicehub @ git+https://github.com/kadirnar/voicehub.git@main"

py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install "voicehub @ git+https://github.com/kadirnar/voicehub.git@main"

Install the correct PyTorch build before VoiceHub when a checkpoint requires an accelerator. The Installation guide covers editable, cache, and offline workflows.

Pretrained models¶

Three shared contracts keep pretrained integrations predictable.

Contract	Purpose
`VoiceHubConfig`	Stores serializable model attributes and the immutable checkpoint identity
`PreTrainedSpeechModel`	Defines the common loading, saving, device, and task-model lifecycle
Processor	Converts text or audio into the model-specific inputs declared by `AutoProcessor`

Prefer the Auto classes because they resolve the configuration, processor, and task wrapper from registry metadata. Pass model_type when the checkpoint does not contain a VoiceHub config.json.

from voicehub import AutoConfig, AutoModelForTextToSpeech, AutoProcessor

checkpoint = "parler-tts/parler-tts-mini-v1"
config = AutoConfig.from_pretrained(checkpoint, model_type="parlertts")
processor = AutoProcessor.from_pretrained(checkpoint, config=config)
model = AutoModelForTextToSpeech.from_pretrained(
    checkpoint,
    config=config,
    device="cuda",
    lazy_load=True,
)
print(config.model_type, type(processor).__name__, model.is_loaded)

lazy_load=True resolves the public contract without allocating the checkpoint. Call model.load() when a service should fail during startup rather than on its first inference request.

Tip

Skip to Trainer when you already have a model, dataset, processor, and collator for a supported differentiable training path.

Inference¶

pipeline() is the shortest task-aware inference API. It selects the correct Auto model, preserves the model's normalized output type, and accepts either a checkpoint source or an already constructed model.

Text to speechAutomatic speech recognitionVoice activity detection

Create a TTS pipeline with an explicit checkpoint and registry key.

from voicehub import pipeline

synthesizer = pipeline(
    task="text-to-speech",
    model="parler-tts/parler-tts-mini-v1",
    model_type="parlertts",
    device="cuda",
)

Generate speech and inspect the normalized TTSOutput.

speech = synthesizer(
    "VoiceHub uses one predictable speech-model lifecycle.",
    description="A clear speaker talks at a steady pace.",
)
print(speech.sample_rate, speech.file_path)

Create an ASR pipeline. The selected checkpoint determines its language and hardware boundaries.

from voicehub import pipeline

transcriber = pipeline(
    task="automatic-speech-recognition",
    model="Qwen/Qwen3-ASR-0.6B",
    model_type="asr_qwen3",
    device="cuda",
)

Pass a local audio path and read the normalized ASROutput.

transcript = transcriber("speech.wav", language="English")
print(transcript.text)

Create a VAD pipeline. Omitting model uses the registry's declared task default when one exists.

from voicehub import pipeline

detector = pipeline(
    task="voice-activity-detection",
    model_type="vad_silero",
)

Detect speech regions and inspect the normalized VADOutput.

detection = detector("speech.wav", threshold=0.55)
for segment in detection.segments:
    print(segment.start, segment.end, segment.score)

Tip

The Inference guide covers batching boundaries, task parameters, chunking, streaming, large inputs, save/reload, and failure behavior.

Trainer¶

Trainer provides shared evaluation, checkpoint, resume, and reporting orchestration only when an integration declares a real differentiable objective. Inspect that contract before allocating a training runtime.

from voicehub import Trainer, TrainingArguments, get_training_spec

training_spec = get_training_spec("parlertts")
if not training_spec.supports_training:
    raise RuntimeError(f"Training is not supported: {training_spec.support.value}")

arguments = TrainingArguments(
    output_dir="runs/parlertts-smoke",
    max_steps=1,
    per_device_train_batch_size=1,
    report_to="none",
)
print(Trainer.__name__, training_spec.support.value, arguments.max_steps)

The training guide adds the checkpoint-specific model, dataset, processor, collator, one-step validation, save, and exact-resume boundaries required before calling Trainer.train().

Next steps¶

Model list: choose a TTS, ASR, or VAD model.
Train: check training support and orchestration.
Optimize: apply supported optimization passes.