llms.txt

# AbstractVoice
> Modular Python voice I/O for AI apps. The base install is remote-first (OpenAI/OpenAI-compatible TTS/STT by default); `abstractvoice[apple]` and `[gpu]` install the local Piper/Supertonic/faster-whisper/audio/cloning stack.

Start with `README.md` for the primary entry flow and treat `docs/api.md` as the supported integrator contract. Requires Python `>=3.9` (see `pyproject.toml`).

Positioning:
- AbstractVoice is a **voice I/O library** (TTS/STT + optional cloning). It does not run an agent loop or an LLM server.
- In the AbstractFramework ecosystem, AbstractVoice is meant to be used with **AbstractCore** (via the capability plugin entry point, including TTS/STT and voice catalog discovery).
- The REPL and local FastAPI web UI are **examples/smoke-test harnesses**. They share a minimal OpenAI-compatible LLM HTTP client (`abstractvoice/examples/llm_provider.py`) for local providers such as Ollama/LM Studio.
- REPL voice selection is centered on `/voices`; `/profile`, `/tts_voice`, and `/setvoice` remain compatibility/direct commands.
- REPL/web base TTS switching uses `VoiceManager.set_tts_engine(...)` and resets the base profile to the provider/language default.
- Plain `abstractvoice` is remote/OpenAI by default; `abstractvoice[all-apple]` and `abstractvoice[all-gpu]` include Supertonic and the REPL/web examples default to Supertonic via their install-aware `auto` resolver.
- One-shot TTS is available without entering the REPL: `abstractvoice --provider openai --model tts-1 --voice alloy --prompt "Hello" --output hello.wav`.
- Library `VoiceManager()` remains remote-first unless a provider is selected explicitly: `tts_engine="openai"` and `stt_engine="openai"` by default. OpenAI uses `https://api.openai.com/v1` and reads `OPENAI_API_KEY` or `remote_api_key=...`; compatible endpoints use `OPENAI_BASE_URL` or `remote_base_url=...`.
- Local inference/listening is explicit: install `abstractvoice[apple]` / `abstractvoice[gpu]`, or granular extras such as `abstractvoice[supertonic,stt,audio-io]`, and select `tts_engine="supertonic"` / `stt_engine="faster_whisper"` (providers). Supertonic is the recommended local base TTS path; OmniVoice is the recommended/default local cloning backend.
- The AbstractCore plugin exposes clean provider/model/voice discovery for TTS, STT, and cloning. Use `available_providers()` for provider lists, `list_models(...)` / `list_tts_models(...)` / `list_stt_models(...)` / `list_cloning_models(...)` for model lists, `list_tts_voices(...)` / `list_cloned_voices(...)` for voices, `get_capability_support(...)` / `find_compatible_models(...)` for feature filtering, `clone(...)` / `clone_voice(...)` for clone creation, and `voice_catalog()` for the richer nested discovery payload.
- Local engine preload/unload is explicit:
  - library: `VoiceManager.preload_tts_engine(...)` / `preload_stt_engine(...)` and `unload_tts_engine()` / `unload_stt_engine()`
  - AbstractCore plugin: `load_resident_model(...)` / `list_resident_models(...)` / `unload_resident_model(...)` (local engines only; remote providers remain configured)
- The STT-only plugin backend (`abstractvoice:stt`) also implements AbstractCore's generic capability discovery contract (`available_providers(task=None)`, `list_models(task=None, provider=...|provider_id=...)`) so `llm.capabilities.*` can query audio discovery without special-casing.
- The plugin accepts both split and combined selectors: `tts(..., provider=\"openai\", model=\"tts-1\", voice=\"alloy\")`, `tts(..., provider=\"openai:tts-1\", voice=\"voice_...\")`, `stt(..., provider=\"faster-whisper\", model=\"large\")`, or `stt(..., provider=\"transformers-asr:Qwen/Qwen3-ASR-1.7B\")`.
- `voice_catalog()` includes `tts_model_variants` and `stt_engine_variants` so AbstractCore can expose clean OpenAI-compatible `/v1/audio/voices`, `/v1/audio/speech/models`, and `/v1/audio/transcriptions/models` discovery endpoints.
- The local web UI has assistant/user voice selectors, browser voice cloning from uploaded or recorded reference audio, message/conversation playback, an example-only `/api/chat` bridge, local `/api/*` routes, and compatible extension routes `/v1/audio/voices` + `/v1/voice/clone`; production `/v1/audio/*` endpoints remain owned by AbstractCore Server.
- Web extras compose directly: `abstractvoice[web]` is lightweight; use `abstractvoice[all-apple]` / `abstractvoice[all-gpu]` for the full platform local lab or `abstractvoice[web,supertonic]` / `abstractvoice[web,omnivoice]` for narrower engine installs.

Policy: the REPL runs offline‑first (`allow_downloads=False`), so model downloads should be explicit (see `docs/installation.md` and `docs/model-management.md`).
CI/release tests use `python -m pytest -q` (defaults to skipping `integration`, `model_download`, and `slow` marked tests) to avoid optional integration and artifact-download paths.

Format: follows the [llms.txt spec](https://llmstxt.org/) (`## Optional` is skippable when context is tight).

## Start here
- [README](README.md): install + smoke tests + ecosystem diagram
- [Docs index](docs/README.md): map of user-facing vs internal docs
- [Getting started](docs/getting-started.md): recommended setup + first smoke tests
- [API (integrator contract)](docs/api.md): supported surface (incl. AbstractFramework integrations)
- [FAQ](docs/faq.md): cache/history reset + common install/runtime issues
- [Known issues](docs/known-issues.md): active release caveats and workarounds
- [Installation](docs/installation.md): platform notes + optional extras
- [REPL guide](docs/repl_guide.md): end-to-end validation + commands

## Ecosystem
- [AbstractFramework](https://github.com/lpalbou/AbstractFramework): umbrella ecosystem
- [AbstractCore](https://github.com/lpalbou/abstractcore): capabilities/plugins
- [AbstractRuntime](https://github.com/lpalbou/abstractruntime): runtime + ArtifactStore

## Architecture & decisions
- [Architecture](docs/architecture.md): implementation map + diagrams
- [Development](docs/development.md): local tests, CI, release checklist
- [Known issues](docs/known-issues.md): current bug tracker mirror for release-facing caveats
- [CI workflow](.github/workflows/ci.yml): Python 3.9-3.12 tests + build check
- [Release workflow](.github/workflows/release.yml): tag/manual release to PyPI + GitHub Release
- [Acronyms](docs/acronyms.md)
- [ADR 0001](docs/adr/0001-local_assistant_out_of_box.md): out-of-box local assistant
- [ADR 0002](docs/adr/0002_barge_in_interruption.md): barge-in modes + stop phrase + optional AEC
- [ADR 0003](docs/adr/0003_cloning_reference_text_fallback.md): cloning `reference_text` auto-fallback
- [ADR 0004](docs/adr/0004_streaming_and_cancellation_for_cloned_tts.md): streaming + cancellation for cloned TTS
- [ADR 0005](docs/adr/0005_torch_device_and_dtype_policy.md): torch device + dtype selection policy

## Core code map
- [VoiceManager façade](abstractvoice/voice_manager.py): public import target
- [Version source](abstractvoice/_version.py): single release version source
- [VoiceManager wiring](abstractvoice/vm/manager.py): constructor + engine selection
- [Voice-mode behavior](abstractvoice/vm/core.py): listening behavior during TTS playback
- [TTS orchestration](abstractvoice/vm/tts_mixin.py): `speak*()` + cloning orchestration
- [TTS delivery mode](abstractvoice/tts/delivery_mode.py): normalize `"buffered"` vs `"streamed"`
- [Text chunking](abstractvoice/tts/text_chunking.py): `split_text_batches(...)` + `TextStreamChunker`
- [Text→audio streaming bridge](abstractvoice/tts/text_to_speech_stream.py): `TextToSpeechStream` (LLM streaming → TTS)
- [Voice profiles abstraction](abstractvoice/voice_profiles.py): cross-engine `VoiceProfile` ids + metadata, including remote provider voices
- [Remote audio HTTP helpers](abstractvoice/adapters/openai_compatible_http.py): lightweight requests-based OpenAI-compatible audio client
- [Remote TTS adapter](abstractvoice/adapters/tts_openai_compatible.py): `/audio/speech` + remote profile discovery
- [Remote STT adapter](abstractvoice/adapters/stt_openai_compatible.py): `/audio/transcriptions`
- [Remote cloning bridge](abstractvoice/cloning/engine_remote.py): compatible `/voice/clone` + stored remote voice ids
- [Audio chunk smoothing](abstractvoice/audio/fade.py): edge fades + headroom scaling
- [STT/listening orchestration](abstractvoice/vm/stt_mixin.py): `listen()` + `transcribe_*()`
- [Piper TTS adapter](abstractvoice/adapters/tts_piper.py): model caching + synthesis
- [Supertonic TTS adapter](abstractvoice/adapters/tts_supertonic.py): fixed-profile ONNX TTS (`M1`-`M5`, `F1`-`F5`)
- [Supertonic runtime](abstractvoice/supertonic/runtime.py): internal ONNX loader + explicit `--supertonic` prefetch; no external Supertonic SDK dependency
- [AudioDiT TTS adapter (optional)](abstractvoice/adapters/tts_audiodit.py): LongCat-AudioDiT engine (extra)
- [OmniVoice runtime (optional)](abstractvoice/omnivoice/runtime.py): offline-first load + device/dtype policy glue
- [OmniVoice TTS adapter (optional)](abstractvoice/adapters/tts_omnivoice.py): omnilingual TTS engine (extra)
- [OmniVoice cloning engine (optional)](abstractvoice/cloning/engine_omnivoice.py): reference-audio cloning (extra)
- [faster-whisper STT adapter](abstractvoice/adapters/stt_faster_whisper.py): STT backend
- [Mic/VAD/STT loop](abstractvoice/recognition.py): listening thread + stop phrase handling
- [Stop phrase matching](abstractvoice/stop_phrase.py): normalization/matching (dependency-light)
- [Explicit prefetch CLI](abstractvoice/prefetch.py): `abstractvoice-prefetch ...`
- [Local web example](abstractvoice/examples/web_ui.py): browser TTS/STT smoke test

## Integrations (AbstractFramework ecosystem)
- [AbstractCore capability plugin](abstractvoice/integrations/abstractcore_plugin.py): registers voice/audio backends and exposes provider/model/voice discovery, clone creation, plus TTS/STT execution with split or combined `provider:model` selectors
- [AbstractCore tool helpers](abstractvoice/integrations/abstractcore.py): `make_voice_tools(...)`
- [Artifact store adapter](abstractvoice/artifacts.py): AbstractRuntime-like ArtifactStore adapter (duck-typed)

## Project + safety
- [Contributing](CONTRIBUTING.md)
- [Bug report template](.github/ISSUE_TEMPLATE/bug_report.yml)
- [Security policy](SECURITY.md)
- [Acknowledgments](ACKNOWLEDGMENTS.md)
- [Changelog](CHANGELOG.md)
- [License](LICENSE)
- [LongCat AudioDiT license](third_party_licenses/longcat_audiodit_license.txt)
- [Supertonic model notice](third_party_licenses/supertone_supertonic_notice.txt)
- [OmniVoice notice](third_party_licenses/omnivoice_notice.txt)

## Optional
- [Full index](llms-full.txt): expanded repo map + workflows
- [Tests](tests/): CI-safe run is `python -m pytest -q` (defaults to skipping `integration`, `model_download`, and `slow` marked tests)
- [Preload benchmark](examples/bench_preload_local_models.py): compare cold start vs preloaded local TTS/STT latency
- [Backlog](docs/backlog/): internal planning (not an API contract)
- [Reports](docs/reports/): historical snapshots
- [Voice cloning research notes](docs/voice_cloning_2026.md): non-contract research notes