voxavatar is a small, dependency-free toolkit for building voice-driven digital humans in Python: the glue between speech recognition, an LLM, speech synthesis, and the lip-sync that makes an avatar's mouth move.
It does not ship its own ASR/LLM/TTS models. Instead it gives you:
- clean provider protocols (
ASRProvider,LLMProvider,TTSProvider) and a registry, so real backends drop in behind a stable interface; - a streaming pipeline that turns one user utterance into a stream of transcript → response → audio → viseme events, emitting the first audio as soon as the first sentence is ready;
- a real grapheme→phoneme→viseme timeline generator (Oculus OVR15 visemes, with an ARKit 52-blendshape exporter for Unity/Unreal);
- an energy-based VAD and a conversation session with barge-in;
- deterministic reference backends so the whole thing runs and tests offline, with no API keys and nothing to download.
| area | what you get |
|---|---|
| Providers | typed protocols + a case-insensitive registry |
| Pipeline | streaming events, sentence segmentation, per-stage error isolation, metrics |
| Visemes | OVR15 mapping, attack/release envelope, co-articulation, ARKit CSV export |
| Audio | PCM16 WAV I/O, framing, RMS, energy VAD + endpointing, linear resample |
| Phonemes | rule-based G2P with digraphs, silent-e, and contraction handling |
| CLI | voxavatar say / voxavatar providers |
pip install voxavatarThe core has zero runtime dependencies — just the Python standard library.
from voxavatar import text_to_visemes
timeline = text_to_visemes("hello world")
print(timeline.to_json())Or run the whole pipeline with the bundled reference providers:
from voxavatar import Pipeline
from voxavatar.types import AudioBuffer
pipe = Pipeline() # mock_asr + echo_llm + sine_tts
mic = AudioBuffer(samples=(0,) * 16000, sample_rate=16000)
for event in pipe.run(mic):
print(event)voxavatar say "hello there" -o hello.wav --visemes hello.json
voxavatar say "open wide" --arkit frames.csv # ARKit blendshape CSV
voxavatar providers # list registered backendsRunnable, dependency-free walkthroughs live in examples/:
01_hello_session— a minimal conversationSession02_streaming_pipeline— the full pipeline, event by event03_text_to_visemes— text → OVR15 viseme piano-roll04_arkit_export— ARKit blendshape CSV for Unity/Unreal05_custom_provider— register your own backend
- Architecture — how the pieces fit together
- Usage — recipes for the common tasks
- API reference — the public surface
- Design notes — why it's built this way
MIT — see LICENSE.