### Run AbstractVoice Local Web Example

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/README

Start the local web example for AbstractVoice, which includes a browser UI for various audio processing tasks. Requires the 'web' extra.

```bash
pip install "abstractvoice[web]"
abstractvoice web --port 5000
```

--------------------------------

### Start AbstractCore Server

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/api

Run the AbstractCore server to enable OpenAI-compatible audio endpoints. Ensure abstractcore[server] and abstractvoice are installed.

```bash
python -m abstractcore.server.app
```

--------------------------------

### Setup Development Environment

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/getting-started

Set up a Python virtual environment, activate it, install the project in editable mode with development dependencies, and run tests.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest -q
```

--------------------------------

### Start AbstractVoice Web Server

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/getting-started

Launch the local web UI example using FastAPI, which includes various voice functionalities.

```bash
abstractvoice web --port 5000
```

--------------------------------

### Start AbstractVoice REPL from Source

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/getting-started

Run the AbstractVoice REPL directly from a source checkout without installing the console script.

```bash
python -m abstractvoice cli --verbose
```

--------------------------------

### Install and Test AbstractVoice CLI

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/faq

Install the AbstractVoice package into your current Python environment and test the CLI. This is the most reliable way to start without depending on console-script path setup.

```bash
python -m pip install abstractvoice
python -m abstractvoice cli --verbose
```

--------------------------------

### Install AbstractCore Server and AbstractVoice

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/getting-started

Install AbstractCore with server capabilities and AbstractVoice for integration testing.

```bash
pip install "abstractcore[server]" abstractvoice
python -m abstractcore.server.app
```

--------------------------------

### AbstractVoice CLI REPL Commands

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/examples/cli_repl.py

These are example commands for the AbstractVoice CLI REPL. Commands start with '/', and other lines are treated as messages to the LLM. Ensure necessary models are downloaded for offline use.

```text
print("Examples")
print(" OmniVoice TTS (French):")
print(" /tts engine omnivoice")
print(" /voices profile female_01 # optional (demo preset; use /voices profiles)")
print(" # Or manual voice design:")
print(" # /omnivoice instruct \"female, young adult, moderate pitch\"")
print(" /language fr")
print(" /speak Bonjour. Ceci est un test.")
print()
print(" OmniVoice cloning (create + use):")
print(" /cloning_download omnivoice")
print(" /clone /path/to/ref.wav my_voice --engine omnivoice --text \"Bonjour, je m'appelle ...\"")
print(" /voices clone my_voice")
print(" /speak Ceci est un test avec ma voix clonée.")
print()
print("Notes")
print(" - Commands start with '/'. Any other line is sent to the LLM as a message.")
print(" - Offline-first: the REPL will not download large weights implicitly; use /cloning_download or `python -m abstractvoice download ...`.")
print(" - Voice-mode STOP: when using /voice stop, you can say \"stop\" to interrupt TTS without exiting voice mode.")
```

--------------------------------

### Install AbstractVoice (Editable)

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/CONTRIBUTING

Clone the repository, set up a virtual environment, and install the project in editable mode with development dependencies. Ensure Python 3.10+ is installed.

```bash
git clone https://github.com/lpalbou/abstractvoice.git
cd abstractvoice

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

python -m pip install -U pip
python -m pip install -e ".[dev]"
```

--------------------------------

### Install AbstractVoice with Web Extras

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/getting-started

Install AbstractVoice with the necessary extras for the web UI and optional engines.

```bash
pip install "abstractvoice[web]"
```

--------------------------------

### Minimal Python TTS Example

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/README

Use this snippet to quickly start speaking text using AbstractVoice. Ensure the library is installed.

```python
from abstractvoice import VoiceManager

vm = VoiceManager()
vm.speak("Hello! This is AbstractVoice.")
```

--------------------------------

### Print Available Examples (Python)

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/__main__.py

This function lists the available examples and provides usage instructions for running them via the command line.

```python
#!/usr/bin/env python3
"""
AbstractVoice - A modular Python library for voice interactions with AI systems.
This module allows running the examples directly.
"""
import sys
import argparse

def print_examples():
    """Print available examples."""
    print("Available examples:")
    print(" cli - Command-line REPL example")
    print(" web - Local FastAPI web example")
    print(" simple - Simple usage example")
    print(" check-deps - Check dependency compatibility")
    print(" download - Explicitly prefetch model artifacts")
    print("\nUsage: python -m abstractvoice [--language ] [args...]")
    print("\nSupported languages: en, fr, de, es, ru, zh")
    print("\nExamples:")
    print(" python -m abstractvoice cli --language fr # French CLI")
    print(" python -m abstractvoice web --port 5000 # Local web example")
    print(" python -m abstractvoice simple --language ru # Russian simple example")
    print(" python -m abstractvoice check-deps # Check dependencies")
```

--------------------------------

### Install AbstractVoice with Optional Extras

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/README

Install AbstractVoice with optional feature flags like 'all' or 'web' for extended functionality.

```bash
pip install "abstractvoice[all]"
```

```bash
pip install "abstractvoice[web]"   # local FastAPI web example
```

--------------------------------

### Execute Web UI Example

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/__main__.py

Launches the web-based user interface (UI) example for AbstractVoice. This provides a graphical interface for interacting with the library.

```python
from abstractvoice.examples.web_ui import main
main()
```

--------------------------------

### Install AbstractVoice with AbstractCore

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/README

Install AbstractVoice and AbstractCore together to enable TTS and STT capabilities through AbstractCore's API.

```bash
pip install "abstractcore[server]" abstractvoice
```

--------------------------------

### Install AudioDiT TTS Adapter

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/adapters/tts_audiodit.py

Install the AudioDiT adapter and its dependencies using pip.

```bash
pip install "abstractvoice[audiodit]"
```

--------------------------------

### start

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/recognition.py

Starts voice recognition in a separate thread.

```APIDOC
## start

### Description
Start voice recognition in a separate thread. This method initiates the recognition process and allows for asynchronous operation.

### Method
`start(tts_interrupt_callback=None) -> bool`

### Parameters
#### Arguments
- **tts_interrupt_callback** - Optional - A function to be called when speech is detected during listening. This can be used to interrupt Text-to-Speech (TTS) playback.

### Returns
- **bool** - True if the recognition process was successfully started, False if it was already running.
```

--------------------------------

### Install AbstractVoice

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/getting-started

Install the AbstractVoice package using pip. Optional extras are available and documented separately.

```bash
pip install abstractvoice
```

--------------------------------

### Execute Simple Example

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/__main__.py

Runs a simple, self-contained example of AbstractVoice functionality. This is useful for quick testing or basic demonstrations.

```python
simple_example()
```

--------------------------------

### Execute CLI Example

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/__main__.py

Runs the command-line interface (CLI) example for AbstractVoice. This is typically used for interactive command-line operations.

```python
from abstractvoice.examples.cli_repl import main
main()
```

--------------------------------

### Install AbstractVoice with Voice Cloning Support

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/faq

Install optional packages for voice cloning capabilities. Choose the specific backend (OpenF5, Chroma, AudioDiT, OmniVoice) based on your requirements.

```bash
pip install "abstractvoice[cloning]"   # OpenF5
pip install "abstractvoice[chroma]"    # Chroma, GPU-heavy
pip install "abstractvoice[audiodit]"  # AudioDiT
pip install "abstractvoice[omnivoice]" # OmniVoice
```

--------------------------------

### Local Web Example: List LLM Models

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/api

An example endpoint to list available models for a local OpenAI-compatible provider, such as Ollama.

```APIDOC
## GET /api/llm/models

### Description
Lists available models for a local OpenAI-compatible provider.

### Method
GET

### Endpoint
/api/llm/models

### Response
#### Success Response (200)
- A list of available LLM models.
```

--------------------------------

### Install Cloning Extras and Prefetch Artifacts

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/repl_guide

Install the necessary extras and prefetch artifacts for specific TTS engines to enable voice cloning capabilities. Run these commands in your terminal.

```bash
pip install "abstractvoice[cloning]"
python -m abstractvoice download --openf5
```

```bash
pip install "abstractvoice[audiodit]"
python -m abstractvoice download --audiodit
```

```bash
pip install "abstractvoice[omnivoice]"
python -m abstractvoice download --omnivoice
```

```bash
pip install "abstractvoice[chroma]"
python -m abstractvoice download --chroma
```

--------------------------------

### Start TextToSpeechStream

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/vm/tts_mixin.py

Initializes and starts a TextToSpeechStream with provided chunk iteration, audio chunk handling, cancellation event, pause check, and metrics callbacks.

```python
stream = TextToSpeechStream(
    iter_audio_chunks_for_segment=_iter_chunks,
    on_audio_chunk=_on_audio_chunk,
    cancel_event=cancel,
    is_paused=_is_paused,
    on_metrics=_on_metrics,
).start()
return stream
```

--------------------------------

### Install PortAudio Development Files on Linux

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/installation

On Debian/Ubuntu systems, install the PortAudio development files using apt-get. This is required for `sounddevice` to function correctly with audio devices.

```bash
sudo apt-get update
```

```bash
sudo apt-get install -y portaudio19-dev
```

--------------------------------

### Download Core and Optional Engines

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/faq

Download core engines like Piper and speech-to-text, as well as optional heavy engines such as OpenF5, Chroma, AudioDit, and OmniVoice. Ensure matching extras are installed (e.g., 'pip install "abstractvoice[omnivoice]"') before prefetching.

```bash
python -m abstractvoice download --piper en
python -m abstractvoice download --stt small
python -m abstractvoice download --openf5
python -m abstractvoice download --chroma
python -m abstractvoice download --audiodit
python -m abstractvoice download --omnivoice
```

--------------------------------

### Local Web Example: Chat Completion

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/api

Use curl to send a POST request to the local web example's /api/chat endpoint for chat completions via a local OpenAI-compatible provider like Ollama.

```bash
# Example dialogue call via a local OpenAI-compatible provider.
curl -X POST http://127.0.0.1:5000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"provider":"ollama","model":"gemma3:1b","messages":[{"role":"user","content":"Say hi in one sentence."}]}'
```

--------------------------------

### Get OmniVoice Runtime Instance

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/cloning/engine_omnivoice.py

Lazily initializes and returns the OmniVoiceRuntime instance. It raises a RuntimeError if the optional dependencies for OmniVoice are not installed, providing installation instructions.

```python
def _get_runtime(self):
    if self._runtime is not None:
        return self._runtime
    try:
        from ..omnivoice.runtime import OmniVoiceRuntime
    except Exception as e:
        raise RuntimeError(
            "OmniVoice cloning requires optional dependencies.\n"
            "Install with:\n"
            " pip install \"abstractvoice[omnivoice]\""
        ) from e
    model_id = self._model_id or OmniVoiceRuntime.DEFAULT_MODEL_ID
    self._runtime = OmniVoiceRuntime(
        model_id=model_id,
        revision=self._revision,
        device=self._device_pref,
        allow_downloads=bool(self._allow_downloads),
        debug=bool(self.debug),
    )
    return self._runtime
```

--------------------------------

### AudioDiT Runtime Initialization

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/cloning/engine_audiodit.py

Internal method to get or initialize the AudioDiTRuntime. Raises a RuntimeError if optional dependencies are not installed.

```python
runtime = self._get_runtime()
```

--------------------------------

### Start AbstractVoice REPL

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/getting-started

Launch the AbstractVoice REPL for interactive use. Use --verbose for more detailed output.

```bash
abstractvoice --verbose
```

--------------------------------

### Initialize VoiceManager

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/api

Instantiate the VoiceManager with language and download permissions. Ensure necessary setup from README.md and docs/getting-started.md.

```python
from abstractvoice import VoiceManager

vm = VoiceManager(language="en", allow_downloads=True)
```

--------------------------------

### Initialize AdapterTTSEngine

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/tts/adapter_tts_engine.py

Initializes the facade with a TTSAdapter and an optional debug mode. It sets up the NonBlockingAudioPlayer and prepares callbacks.

```python
def __init__(self, adapter: TTSAdapter, debug_mode: bool = False):
    self.adapter = adapter
    self.debug_mode = debug_mode
    self.on_playback_start: Optional[Callable[[], None]] = None
    self.on_playback_end: Optional[Callable[[], None]] = None
    self._user_callback: Optional[Callable[[], None]] = None
    sample_rate = self._safe_sample_rate()
    self.audio_player = NonBlockingAudioPlayer(sample_rate=sample_rate, debug_mode=debug_mode)
    self.audio_player.playback_complete_callback = self._on_playback_complete
    # Best-effort last TTS metrics (used by verbose REPL output).
    self.last_tts_metrics: dict | None = None
```

--------------------------------

### Check AbstractVoice Dependencies

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/installation

Run this command to check your environment and get a report on AbstractVoice's dependencies. This is useful for troubleshooting installation or runtime issues.

```bash
python -m abstractvoice check-deps
```

```bash
abstractvoice check-deps
```

--------------------------------

### Get Voice Cloner Instance

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/vm/tts_mixin.py

Initializes and returns a VoiceCloner instance if one doesn't exist. It handles optional installation of cloning dependencies and configures the cloner with debug mode, whisper model, and default engine settings from the VoiceManager instance.

```python
def _get_voice_cloner(self):
    if getattr(self, "_voice_cloner", None) is None:
        try:
            from ..cloning import VoiceCloner
        except Exception as e:
            raise RuntimeError(
                "Voice cloning is an optional feature.\n"
                "Install with: pip install \"abstractvoice[cloning]\"\n"
                f"Original error: {e}"
            )
        # Use a slightly larger STT model for one-time reference-text auto-fallback.
        self._voice_cloner = VoiceCloner(
            debug=bool(getattr(self, "debug_mode", False)),
            whisper_model=getattr(self, "whisper_model", "tiny"),
            reference_text_whisper_model="small",
            allow_downloads=bool(getattr(self, "allow_downloads", True)),
            default_engine=str(getattr(self, "cloning_engine", "f5_tts") or "f5_tts"),
        )
    return self._voice_cloner
```

--------------------------------

### Optional Engine Installation Check

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/examples/web_ui.py

Checks if an optional engine is installed or available. Updates the UI to reflect the installation status of optional engines.

```javascript
function optionEngineInstalled(engine) { const key = String(engine || "").trim().toLowerCase(); if (!key || !optionalDependencies[key]) return true; return optionalDependencies[key].installed !== false; }
function updateOptionalEngineUi() { for (const opt of cloneEngineInput.options) { const installed = optionEngineInstalled(opt.value); opt.disabled = !installed; const base = opt.dataset.baseLabel || opt.textContent.replace(" (not installed)", ""); opt.dataset.baseLabel = base; opt.textContent = installed ? base : base + " (not installed)"; } if (cloneEngineInput.selectedOptions[0] && cloneEngineInput.selectedOptions[0].disabled) { const firstReady = Array.from(cloneEngineInput.options).find((opt) => !opt.disabled); if (firstReady) cloneEngineInput.value = firstReady.value; } }
function updateProfileEngineUi() { for (const opt of profileChoice.options) { const engine = opt.dataset.engine || ""; if (!engine) continue; const installed = optionEngineInstalled(engine); opt.disabled = !installed; const base = opt.dataset.baseLabel || opt.textContent.replace(" (not installed)", ""); opt.dataset.baseLabel = base; opt.textContent = installed ? base : base + " (not installed)"; } if (profileChoice.selectedOptions[0] && profileChoice.selectedOptions[0].disabled) profileChoice.value = ""; }
```

--------------------------------

### Check and Install Chroma Dependency

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/examples/cli_repl.py

Checks if Chroma artifacts are cached and provides installation instructions if not. Requires pip install "abstractvoice[chroma]".

```python
if self._is_chroma_cached():
print("✅ Chroma artifacts: present (cached)")
else:
print("ℹ️ Chroma artifacts: not present (will require a large download + HF access)")
print(" Run: /cloning_download chroma")
```

--------------------------------

### Enable Microphone Input from Source

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/getting-started

Run the AbstractVoice CLI from a source checkout with microphone capture enabled.

```bash
python -m abstractvoice cli --voice-mode stop
```

--------------------------------

### Check and Install OmniVoice Dependency

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/examples/cli_repl.py

Checks if OmniVoice runtime and weights are cached and provides installation instructions if not. Requires pip install "abstractvoice[omnivoice]".

```python
if ( importlib.util.find_spec("omnivoice") is None or importlib.util.find_spec("torch") is None or importlib.util.find_spec("torchaudio") is None or importlib.util.find_spec("transformers") is None ):
print("ℹ️ OmniVoice runtime: not installed (missing: omnivoice/torch/torchaudio/transformers)")
print(" Install: pip install \"abstractvoice[omnivoice]\"")
else:
if self._is_omnivoice_cached():
print("✅ OmniVoice weights: present (cached)")
else:
print("ℹ️ OmniVoice weights: not present (will require a large download + HF access)")
print(" Run: /cloning_download omnivoice")
```

--------------------------------

### Initialize and Run AbstractVoice REPL

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/examples/cli_repl.py

Initializes the VoiceREPL with parsed arguments and starts the command loop. Handles KeyboardInterrupt for graceful exit and general exceptions for application errors.

```python
from abstractvoice.voice_repl import VoiceREPL

def main():
    """Entry point for the application."""
    try:
        # Parse command line arguments
        args = parse_args()
        # Initialize and run REPL with language support
        repl = VoiceREPL(
            provider=args.provider,
            api_url=args.api,
            model=args.model,
            debug_mode=args.debug,
            verbose_mode=args.verbose,
            language=args.language,
            tts_model=args.tts_model,
            voice_mode=args.voice_mode,
            cloning_engine=args.cloning_engine,
        )
        repl.cmdloop()
    except KeyboardInterrupt:
        print("\nExiting...")
    except Exception as e:
        print(f"Application error: {e}")

if __name__ == "__main__":
    main()
```

--------------------------------

### Check and Install AudioDiT Dependency

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/examples/cli_repl.py

Checks if AudioDiT runtime and weights are cached and provides installation instructions if not. Requires pip install "abstractvoice[audiodit]".

```python
if importlib.util.find_spec("torch") is None or importlib.util.find_spec("transformers") is None:
print("ℹ️ AudioDiT runtime: not installed (missing: torch/transformers)")
print(" Install: pip install \"abstractvoice[audiodit]\"")
else:
if self._is_audiodit_cached():
print("✅ AudioDiT weights: present (cached)")
else:
print("ℹ️ AudioDiT weights: not present (will require a large download + HF access)")
print(" Run: /cloning_download audiodit")
```

--------------------------------

### Initialize VoiceCloneStore

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/cloning/store.py

Initializes the local storage directory and index file for managing voice clones.

```python
class VoiceCloneStore:
    """Stores cloned-voice metadata + reference audio bundles locally.
    Design principles:
    - Keep the storage format portable and engine-agnostic.
    - Avoid embedding binary blobs in JSON; store files on disk.
    """
    def __init__(self, base_dir: Optional[str | Path] = None):
        if base_dir is None:
            root = Path(appdirs.user_data_dir("abstractvoice"))
            self._base_dir = root / "cloned_voices"
        else:
            self._base_dir = Path(base_dir)
        self._base_dir.mkdir(parents=True, exist_ok=True)
        self._index_path = self._base_dir / "index.json"
        if not self._index_path.exists():
            self._write_index({})
```

--------------------------------

### Local Web Example: Select Voice

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/api

Use curl to interact with the local web example's /api/voices/select endpoint. This example sets a browser-default role and preloads a cloned voice.

```bash
# Browser-example role default; still resolves to a cloned voice_id.
curl -X POST http://127.0.0.1:5000/api/voices/select \
  -H "Content-Type: application/json" \
  -d '{"role":"assistant","kind":"clone","voice":"my_voice","preload":true}'
```

--------------------------------

### Initialize AudioDiTVoiceCloningEngine

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/cloning/engine_audiodit.py

Initializes the AudioDiTVoiceCloningEngine with various configuration options. Requires optional dependencies to be installed.

```python
from abstractvoice.engine.audiodit import AudioDiTVoiceCloningEngine

engine = AudioDiTVoiceCloningEngine(
    debug=False,
    device="auto",
    model_id=None,
    revision=None,
    allow_downloads=True,
    steps=16,
    cfg_strength=4.0,
    guidance_method="apg",
)
```

--------------------------------

### Start Audio Stream

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/tts/tts_engine.py

Initializes the audio stream using the sounddevice library.

```python
def start_stream(self): if self.stream is not None: return sd = _import_sounddevice() desired_sr = int(self.sample_rate) # Device candidates: default first, then explicit indices as fallback. device_candidates: list[int | None] = [None] try: dev = sd.query_devices(None, "output")
```

--------------------------------

### Main Entry Point and Argument Parsing (Python)

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/__main__.py

Handles the main execution flow, including parsing command-line arguments for different examples (web, simple, check-deps, download) and setting the language. It delegates to specific functions or modules based on the provided arguments.

```python
def main():
    """Main entry point."""
    if len(sys.argv) > 1 and sys.argv[1] == "web":
        from abstractvoice.examples.web_ui import main as web_main
        web_main(sys.argv[2:])
        return

    parser = argparse.ArgumentParser(description="AbstractVoice examples")
    parser.add_argument("example", nargs="?", help="Example to run (cli, web, simple, check-deps, download)")
    parser.add_argument("--language", "--lang", default="en", choices=["en", "fr", "de", "es", "ru", "zh"], help="Voice language for examples")

    # Parse just the first argument and language
    args, remaining = parser.parse_known_args()

    if not args.example:
        print_examples()
        return

    # Handle check-deps specially (doesn't need language)
    if args.example == "check-deps":
        from abstractvoice.dependency_check import check_dependencies
        try:
            check_dependencies(verbose=True)
        except Exception as e:
            print(f"❌ Error running dependency check: {e}")
            print("This might indicate a dependency issue.")
        return

    if args.example == "download":
        dl = argparse.ArgumentParser(description="AbstractVoice explicit downloads")
        dl.add_argument("--stt", dest="stt_model", default=None, help="Prefetch faster-whisper model (e.g. small)")
        dl.add_argument(
            "--openf5", action="store_true", help="Prefetch OpenF5 artifacts for cloning (~5.4GB, requires abstractvoice[cloning])",
        )
        dl.add_argument(
            "--chroma", action="store_true", help="Prefetch Chroma-4B artifacts (~14GB+, requires HF access; install abstractvoice[chroma] to run inference)",
        )
        dl.add_argument(
            "--piper", dest="piper_language", default=None, help="Prefetch Piper voice model for a language (e.g. en/fr/de).",
        )
        dl.add_argument(
            "--audiodit", action="store_true", help="Prefetch LongCat-AudioDiT-1B weights + tokenizer (requires abstractvoice[audiodit])",
        )
        dl.add_argument(
            "--omnivoice", action="store_true", help="Prefetch OmniVoice weights + tokenizer (requires abstractvoice[omnivoice])",
        )
        dl_args = dl.parse_args(remaining)

        if (
            not dl_args.stt_model
            and not dl_args.openf5
            and not dl_args.chroma
            and not dl_args.piper_language
            and not dl_args.audiodit
            and not dl_args.omnivoice
        ):
            print("Nothing to download. Examples:")
            print(" python -m abstractvoice download --stt small")
            print(" python -m abstractvoice download --openf5")
            print(" python -m abstractvoice download --chroma")
            print(" python -m a
```

--------------------------------

### Start Voice Recognition

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/recognition.py

Starts the voice recognition service in a separate thread. Includes a timeout for startup.

```python
if not self._startup_event.wait(timeout=3.0):
    self.is_running = False
    self._close_stream()
    self._thread_error = TimeoutError("Voice recognition did not start within 3 seconds")
    self.last_error = self._thread_error
    if self.debug_mode:
        print(f"Voice recognition startup error: {self._thread_error}")
    return False
if self._thread_error is not None:
    self.is_running = False
    self._close_stream()
    self.last_error = self._thread_error
    if self.thread and self.thread is not threading.current_thread():
        self.thread.join(timeout=0.2)
    if self.debug_mode:
        print(f"Voice recognition startup error: {self._thread_error}")
    return False
if self.debug_mode:
    print(" > Voice recognition started")
return True
```

--------------------------------

### Start AbstractVoice REPL

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/README

Launch the AbstractVoice Read-Eval-Print Loop (REPL) for quick end-to-end testing. Mic input is off by default.

```bash
abstractvoice --verbose
# or (from a source checkout):
python -m abstractvoice cli --verbose
```

--------------------------------

### Download Opt-in Engines via CLI

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/model-management

Commands to download weights for optional engines like Chroma, AudioDiT, or OmniVoice. Ensure the corresponding extras are installed (e.g., `abstractvoice[chroma]`).

```bash
python -m abstractvoice download --chroma
```

```bash
python -m abstractvoice download --audiodit
```

```bash
python -m abstractvoice download --omnivoice
```

--------------------------------

### Install AbstractVoice with Optional Extras

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/docs/installation

Install AbstractVoice with specific optional features by appending extra identifiers to the pip install command. Each extra enables a different set of functionalities, such as voice cloning, advanced STT models, or web interfaces.

```bash
pip install "abstractvoice[cloning]"
```

```bash
pip install "abstractvoice[chroma]"
```

```bash
pip install "abstractvoice[audiodit]"
```

```bash
pip install "abstractvoice[omnivoice]"
```

```bash
pip install "abstractvoice[aec]"
```

```bash
pip install "abstractvoice[audio-fx]"
```

```bash
pip install "abstractvoice[web]"
```

```bash
pip install "abstractvoice[web-omnivoice]"
```

```bash
pip install "abstractvoice[web-full]"
```

```bash
pip install "abstractvoice[stt]"
```

```bash
pip install "abstractvoice[legacy-stt]"
```

--------------------------------

### Ensure Chroma Runtime Dependencies

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/cloning/engine_chroma.py

Validates that 'torch' and 'transformers' are installed, raising a RuntimeError with installation instructions if missing.

```python
def _ensure_chroma_runtime(self) -> None: try: import importlib.util if importlib.util.find_spec("torch") is None: raise ImportError("torch not installed") if importlib.util.find_spec("transformers") is None: raise ImportError("transformers not installed") except Exception as e: raise RuntimeError( "Chroma requires the optional dependency group.\n" "Install with:\n" " pip install \"abstractvoice[chroma]\"\n" f"Original error: {e}" ) from e
```

--------------------------------

### Initialize and Start Audio Output Stream

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/tts/tts_engine.py

Configures and opens an audio output stream by iterating through available devices and sample rates. It attempts to match the desired sample rate and channel configuration, falling back to common defaults if necessary.

```python
output") # default output device idx = dev.get("index", None) if isinstance(idx, int) and idx not in device\_candidates: device\_candidates.append(idx) except Exception: pass try: for i, dev in enumerate(sd.query\_devices()): # all devices if int(dev.get("max\_output\_channels", 0) or 0) <= 0: continue if i not in device\_candidates: device\_candidates.append(i) except Exception: pass # Common output rates (keep short; we already prefer device default + desired). common\_rates = (48000, 44100, 24000, 22050, 16000) last\_err: Exception | None = None for device in device\_candidates: # Build per-device candidate sample rates (desired first, then device default, then common). sr\_candidates: list\[int\] = \[] try: dev = sd.query\_devices(device, "output") if device is not None else sd.query\_devices(None, "output") default\_sr = int(round(float(dev.get("default\_samplerate", 0) or 0))) max\_ch = int(dev.get("max\_output\_channels", 0) or 0) except Exception: default\_sr = 0 max\_ch = 0 # Prefer opening the stream at the audio's natural rate to avoid resampling # (e.g. 24 kHz for AudioDiT). If the device rejects it, we fall back. if desired\_sr: sr\_candidates.append(int(desired\_sr)) if default\_sr and int(default\_sr) not in sr\_candidates: sr\_candidates.append(int(default\_sr)) for sr in common\_rates: if sr not in sr\_candidates: sr\_candidates.append(sr) # Prefer stereo devices (most macOS outputs are 2ch); fall back to mono. ch\_order = (2, 1) if max\_ch >= 2 else (1,) # Prefer PortAudio-chosen blocksize first (often most compatible). block\_order = (0, 1024) for sr in sr\_candidates: for blocksize in block\_order: for channels in ch\_order: if max\_ch and channels > max\_ch: continue stream = None try: with \_SilenceStderrFD(enabled=not self.debug\_mode): stream = sd.OutputStream( samplerate=int(sr), channels=int(channels), callback=self.\_audio\_callback, blocksize=int(blocksize), dtype=np.float32, device=int(device) if device is not None else None, ) stream.start() self.stream = stream self.sample\_rate = int(sr) # Record which device we pinned to at open time. try: opened\_info = ( sd.query\_devices(int(device), "output") if device is not None else sd.query\_devices(None, "output") ) except Exception: opened\_info = None try: if isinstance(opened\_info, dict): self.\_opened\_output\_device\_index = ( int(opened\_info.get("index")) if isinstance(opened\_info.get("index"), int) else None ) self.\_opened\_output\_device\_name = str(opened\_info.get("name", "") or "").strip() or None else: self.\_opened\_output\_device\_index = int(device) if device is not None else None self.\_opened\_output\_device\_name = None except Exception: self.\_opened\_output\_device\_index = int(device) if device is not None else None self.\_opened\_output\_device\_name = None try: self.\_opened\_output\_channels = int(channels) except Exception: self.\_opened\_output\_channels = None try: # Cache the system default output at open time so we can detect changes later. cur\_default = self.\_default\_output\_device\_index() self.\_last\_seen\_default\_output\_device\_index = ( int(cur\_default) if cur\_default is not None else self.\_last\_seen\_default\_output\_device\_index ) except Exception: pass if self.debug\_mode: try: name = str(getattr(self, "\_opened\_output\_device\_name", None) or "").strip() or "(unknown)" idx\_txt = ( str(int(self.\_opened\_output\_device\_index)) if isinstance(getattr(self, "\_opened\_output\_device\_index", None), int) else "?" ) ch\_txt = ( str(int(self.\_opened\_output\_channels)) if isinstance(getattr(self, "\_opened\_output\_channels", None), int) else "?" ) print(f"Audio output device: {name} (index={idx\_txt}, channels={ch\_txt}, sr={int(sr)}Hz)") except Exception: pass if self.debug\_mode and int(sr) != desired\_sr: print(f"⚠️ Output device rejected {desired\_sr}Hz; using {sr}Hz (resampling)") return except Exception as e: last\_err = e try: if stream is not None: stream.close() except Exception: pass continue # If we couldn't start, surface the last error. if last\_err is not None: raise last\_err raise RuntimeError("Failed to start audio output stream")
```

--------------------------------

### Run Heavy/Integration Tests

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/CONTRIBUTING

To run heavy or optional integration tests, specific environment variables and additional package installations are required. For cloning tests, set ABSTRACTVOICE_RUN_CLONING_TESTS=1 and install 'abstractvoice[cloning]'. For Chroma tests, set ABSTRACTVOICE_RUN_CHROMA_TESTS=1 and install 'abstractvoice[chroma]'.

```bash
# Cloning (OpenF5):
# set ABSTRACTVOICE_RUN_CLONING_TESTS=1 (also needs pip install "abstractvoice[cloning]")
# Chroma:
# set ABSTRACTVOICE_RUN_CHROMA_TESTS=1 (also needs pip install "abstractvoice[chroma]")
```

--------------------------------

### AudioDiTTTSAdapter Initialization

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/adapters/tts_audiodit.py

Initializes the AudioDiTTTSAdapter with various configuration options including language, download permissions, model details, and session prompt settings. It handles optional dependency loading and quality preset configuration.

```python
def __init__(
        self,
        language: str = "en",
        *, 
        allow_downloads: bool = True,
        auto_load: bool = False,
        debug_mode: bool = False,
        model_id: str | None = None,
        revision: str | None = None,
        device: str = "auto",
        runtime: Any | None = None,
        settings: Any | None = None,
        max_chars: int = 800,
        use_session_prompt: bool = True,
        session_prompt_seconds: float = 4.0,
    ):
        self._language = str(language or "en").strip().lower()
        self._allow_downloads = bool(allow_downloads)
        self._debug = bool(debug_mode)
        self._sample_rate = 24000
        self._runtime = runtime
        self._settings = settings
        self._max_chars = int(max_chars) if int(max_chars) > 0 else 800
        # Session speaker consistency (upstream methodology: prompt audio + prompt text).
        self._use_session_prompt = bool(use_session_prompt)
        try:
            self._session_prompt_seconds = float(session_prompt_seconds)
        except Exception:
            self._session_prompt_seconds = 4.0
        if not (self._session_prompt_seconds > 0.0):
            self._session_prompt_seconds = 4.0
        self._session_prompt_audio: np.ndarray | None = None
        self._session_prompt_text: str | None = None
        self._session_prompt_sr: int = 24000
        # Cache an encoded prompt latent (torch.Tensor) for session consistency
        # without paying VAE prompt encoding on every turn. Best-effort only.
        self._session_prompt_latent: Any | None = None
        if self._runtime is None:
            try:
                from ..audiodit.runtime import AudioDiTRuntime, AudioDiTSettings
            except Exception as e:
                raise RuntimeError(
                    "AudioDiT requires optional dependencies.\n"
                    "Install with:\n"
                    ' pip install \
```

--------------------------------

### Ensure F5 TTS Runtime Dependency

Source: https://raw.githubusercontent.com/lpalbou/AbstractVoice/refs/heads/main/abstractvoice/cloning/engine_f5.py

Checks if the 'f5_tts' package is installed and raises a RuntimeError if it's missing, providing installation instructions.

```python
def _ensure_f5_runtime(self) -> None:
    try:
        import importlib.util
        if importlib.util.find_spec("f5_tts") is None:
            raise ImportError("f5_tts not installed")
    except Exception as e:
        raise RuntimeError(
            "Voice cloning requires the optional dependency group.\n"
            "Install with:\n"
            " pip install \"abstractvoice[cloning]\"\n"
            f"Original error: {e}"
        ) from e
```