### Install VoiceLLM with Pip

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

Provides commands for installing the VoiceLLM Python package using pip. Includes basic installation, installation with development dependencies, and installation from a local source.

```bash
# Basic installation (works everywhere)
pip install voicellm

# With development dependencies
pip install "voicellm[dev]"

# From source
git clone https://github.com/lpalbou/voicellm.git
cd voicellm
pip install -e .
```

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

### VoiceLLM Basic Integration: TTS and STT

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

A quick start guide for integrating VoiceLLM, showing how to initialize the VoiceManager, perform text-to-speech, and listen for speech input with a callback function.

```python
from voicellm import VoiceManager

# 1. Initialize (automatic best-quality model selection)
vm = VoiceManager()

# 2. Text-to-Speech
vm.speak("Hello from my app!")

# 3. Speech-to-Text with callback
def handle_speech(text):
    print(f"User said: {text}")
    # Process text in your app...

vm.listen(on_transcription=handle_speech)
```

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

### VoiceLLM Installation from Requirements File

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Installs VoiceLLM and all its required dependencies by referencing a requirements.txt file. This ensures all necessary packages are installed for the project to function correctly.

```bash
pip install -r requirements.txt
```

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

### Robust VoiceManager Initialization in Python

Source: https://github.com/lpalbou/voicellm/blob/main/llms.txt

Provides an example of robust VoiceManager initialization using a try-except block to handle potential errors and fall back to a default or more compatible TTS model. This ensures the application can start even if preferred models are unavailable.

```python
# Robust initialization with fallback
def create_voice_manager():
    try:
        return VoiceManager(tts_model="tts_models/en/ljspeech/vits")
    except:
        return VoiceManager(tts_model="tts_models/en/ljspeech/fast_pitch")
```

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

### Complete AI Voice Chat Example in Python

Source: https://github.com/lpalbou/voicellm/blob/main/llms.txt

Presents a fully functional AI voice chat application class. It integrates VoiceManager for speech synthesis and recognition, handles user input, processes AI responses, and includes methods for starting, stopping, and cleaning up the application.

```python
from voicellm import VoiceManager
import time

class AIVoiceChat:
    def __init__(self):
        self.vm = VoiceManager()
        self.active = False
    
    def start(self):
        self.active = True
        self.vm.speak("Hello! How can I help you?")
        self.vm.listen(
            on_transcription=self.handle_input,
            on_stop=self.stop
        )
    
    def handle_input(self, user_text):
        if not self.active: return
        
        self.vm.stop_speaking()  # Stop any current speech
        
        # Your AI processing here
        response = f"I heard: {user_text}"
        
        if self.active:
            self.vm.speak(response)
    
    def stop(self):
        self.active = False
        self.vm.speak("Goodbye!")
        self.vm.cleanup()

# Usage
chat = AIVoiceChat()
chat.start()
```

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

### Bash: Install VoiceLLM and Optional Dependencies

Source: https://github.com/lpalbou/voicellm/blob/main/llms.txt

This Bash script provides the commands to install the VoiceLLM package using pip. It also includes optional commands for installing espeak-ng on macOS, Linux, and Windows, which is recommended for achieving the best TTS quality.

```bash
pip install voicellm

# Optional for best quality (auto-detected)
# macOS: brew install espeak-ng
# Linux: sudo apt-get install espeak-ng  
# Windows: choco install espeak-ng
```

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

### VoiceManager Full Configuration Example

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Provides a comprehensive example of VoiceManager initialization with various parameters. It demonstrates setting TTS and STT models, enabling debug mode, and configuring voice mode, speed, and VAD aggressiveness.

```python
# Full configuration example
voice_manager = VoiceManager(
    tts_model="tts_models/en/ljspeech/fast_pitch",  # Default (no external deps)
    whisper_model="base",  # Whisper STT model (tiny, base, small, medium, large)
    debug_mode=True  # Enable debug logging
)

# Alternative TTS models (all pure Python, cross-platform):
# - "tts_models/en/ljspeech/fast_pitch" - Default (fast, good quality)
# - "tts_models/en/ljspeech/glow-tts" - Alternative (similar quality)
# - "tts_models/en/ljspeech/tacotron2-DDC" - Legacy (older, slower)

# Set voice mode (full, wait, off)
voice_manager.set_voice_mode("wait")  # Recommended to avoid self-interruption

# Adjust settings (speed now preserves pitch!)
voice_manager.set_speed(1.2)  # TTS speed (default is 1.0, range 0.5-2.0)
voice_manager.change_vad_aggressiveness(2)  # VAD sensitivity (0-3)
```

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

### Initialize and Use Voice Manager for AI Assistant (Python)

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

This Python code initializes the VoiceManager, which handles Text-to-Speech (TTS) and speech recognition. It includes automatic fallback to a different TTS model if the primary one fails. The class `AIVoiceAssistant` demonstrates starting a conversation, listening to user input, generating AI responses, and speaking them.

```python
#!/usr/bin/env python3
"""Complete VoiceLLM integration example for AI systems"""

from voicellm import VoiceManager
import time
import threading

class AIVoiceAssistant:
    def __init__(self):
        # Initialize with automatic fallback
        try:
            self.vm = VoiceManager(
                tts_model="tts_models/en/ljspeech/vits",
                whisper_model="tiny"
            )
            print("✅ Voice system ready (VITS model)")
        except:
            self.vm = VoiceManager(
                tts_model="tts_models/en/ljspeech/fast_pitch",
                whisper_model="tiny"
            )
            print("✅ Voice system ready (fallback model)")
        
        self.conversation_active = False
    
    def start_conversation(self):
        """Start voice conversation"""
        self.conversation_active = True
        
        # Welcome message
        self.vm.speak("Hello! I'm your AI assistant. How can I help you today?")
        
        # Start listening
        self.vm.listen(
            on_transcription=self.handle_user_input,
            on_stop=self.handle_stop
        )
        
        print("🎤 Listening... (say 'stop' to exit)")
    
    def handle_user_input(self, user_text):
        """Process user speech input"""
        if not self.conversation_active:
            return
        
        print(f"👤 User: {user_text}")
        
        # Stop any current speech
        self.vm.stop_speaking()
        
        # Process with AI (placeholder)
        ai_response = self.generate_ai_response(user_text)
        
        # Speak response
        if self.conversation_active:
            print(f"🤖 AI: {ai_response}")
            self.vm.speak(ai_response)
    
    def generate_ai_response(self, user_text):
        """Generate AI response (replace with your AI system)"""
        # Placeholder - integrate with your AI system here
        responses = [
            f"I understand you said: {user_text}",
            "That's interesting! Tell me more.",
            "I'm processing that information.",
            "How can I help you further?"
        ]
        import random
        return random.choice(responses)
    
    def handle_stop(self):
        """Handle stop command"""
        self.conversation_active = False
        self.vm.speak("Goodbye! Have a great day!")
        time.sleep(2)  # Let goodbye message finish
    
    def pause_resume_demo(self):
        """Demonstrate pause/resume functionality"""
        print("🎵 Pause/Resume Demo")
        
        # Start long speech
        long_text = """
        This is a demonstration of VoiceLLM's immediate pause and resume functionality. 
        The system can pause speech within 20 milliseconds and resume from the exact position. 
        This creates a professional user experience with no repetition or gaps in audio playback.
        """
        
        self.vm.speak(long_text)
        
        # Pause after 3 seconds
        time.sleep(3)
        print("⏸️ Pausing...")
        self.vm.pause_speaking()
        
        # Resume after 2 seconds
        time.sleep(2)
        print("▶️ Resuming...")
        self.vm.resume_speaking()
    
    def cleanup(self):
        """Clean up resources"""
        self.conversation_active = False
        self.vm.cleanup()

# Example usage
if __name__ == "__main__":
    assistant = AIVoiceAssistant()
    
    try:
        # Demo pause/resume
        assistant.pause_resume_demo()
        time.sleep(10)  # Let demo finish
        
        # Start conversation
        assistant.start_conversation()
        
        # Keep running until interrupted
        while assistant.conversation_active:
            time.sleep(0.1)
    
    except KeyboardInterrupt:
        print("\n🛑 Interrupted by user")
    
    finally:
        assistant.cleanup()
        print("✅ Cleanup complete")

```

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

### VoiceLLM Command-Line Interface Usage

Source: https://context7.com/lpalbou/voicellm/llms.txt

Provides examples of using the VoiceLLM command-line interface to launch the application in voice mode, with custom configurations, text-only mode, custom API endpoints, and specifying different Whisper models. Includes examples for enabling debug mode.

```bash
# Start in voice mode (TTS + STT enabled)
voicellm

# Start with custom configuration
voicellm --model gemma3:latest --whisper base --debug

# Start in text-only mode (TTS enabled, STT disabled)
voicellm --no-listening

# Custom API endpoint and system prompt
voicellm --api http://localhost:11434/api/chat \
         --model phi4-mini:latest \
         --system "You are a helpful coding assistant" \
         --temperature 0.7 \
         --max-tokens 2048

# Available Whisper models
voicellm --whisper tiny    # Fastest, lowest accuracy
voicellm --whisper base    # Balanced (recommended)
voicellm --whisper small   # Better accuracy
voicellm --whisper medium  # High accuracy, slower
voicellm --whisper large   # Best accuracy, slowest

# Debug mode for troubleshooting
voicellm --debug
```

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

### Basic VoiceLLM Installation via PyPI

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Installs the VoiceLLM package from the Python Package Index (PyPI) using pip. This is the standard method for adding VoiceLLM to your Python environment.

```bash
pip install voicellm
```

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

### Initialize VoiceManager in Python

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

Demonstrates initializing the VoiceManager class in Python for AI voice interactions. Shows different initialization methods, including specifying TTS and Whisper models for quality and performance trade-offs.

```python
from voicellm import VoiceManager

# Initialize with best quality (requires espeak-ng, auto-fallback to fast_pitch)
vm = VoiceManager(
    tts_model="tts_models/en/ljspeech/vits",  # Best quality
    whisper_model="tiny",  # Fast, good for most use cases
    debug_mode=False
)

# Default: Works everywhere (recommended for production)
vm = VoiceManager(
    tts_model="tts_models/en/ljspeech/fast_pitch",  # Default
    whisper_model="tiny"
)

# Simple initialization (uses fast_pitch by default)
vm = VoiceManager()
```

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

### VoiceLLM Development Installation from Repository

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Installs VoiceLLM in editable mode from a cloned repository, including development dependencies. This is useful for contributing to the VoiceLLM project or testing local changes.

```bash
git clone https://github.com/lpalbou/voicellm.git
cd voicellm
pip install -e .
```

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

### Clone and Install Development Dependencies - Bash

Source: https://github.com/lpalbou/voicellm/blob/main/CONTRIBUTING.md

This snippet shows how to clone the VoiceLLM repository, set up a Python virtual environment, and install development dependencies using pip. It assumes the user has Git and Python 3.11.7+ installed.

```bash
git clone https://github.com/lpalbou/voicellm.git
cd voicellm
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

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

### Install VoiceLLM Web API Dependencies

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Installs the necessary Python packages for the VoiceLLM web API, including Flask, soundfile, numpy, and requests.

```bash
pip install flask soundfile numpy requests
```

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

### VoiceLLM Installation with Development Dependencies

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Installs VoiceLLM along with its development dependencies using pip. This command is typically used by developers working on the VoiceLLM library.

```bash
pip install "voicellm[dev]"
```

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

### Python Method with Google-Style Docstring - Python

Source: https://github.com/lpalbou/voicellm/blob/main/CONTRIBUTING.md

An example of a Python method demonstrating Google-style docstrings, including type hints, argument descriptions, return value explanation, and a usage example. This adheres to the project's documentation standards.

```python
from typing import Optional, Callable

# Assuming VoiceManager is defined elsewhere
# class VoiceManager:
#     def speak(self, text: str, speed: float = 1.0, callback: Optional[Callable] = None) -> bool:
#         pass # Implementation details

def speak(self, text: str, speed: float = 1.0, callback: Optional[Callable] = None) -> bool:
    """Convert text to speech and play audio.
    
    Args:
        text: Text to convert to speech
        speed: Speech speed multiplier (0.5-2.0, default 1.0)
        callback: Optional callback function called when speech completes
        
    Returns:
        True if speech started, False if text was empty
        
    Example:
        >>> vm = VoiceManager()
        >>> vm.speak("Hello world", speed=1.2)
        True
    """
    # Actual implementation would go here
```

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

### Speech-to-Text Only Example

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Shows the standalone speech-to-text (STT) functionality of VoiceLLM. It initializes the VoiceManager and starts listening for audio input. A callback function `on_transcription` is provided to process the transcribed text, which in this example, simply prints it to the console. The loop maintains the listening state.

```python
from voicellm import VoiceManager
import time

voice_manager = VoiceManager()

def on_transcription(text):
    print(f"Transcribed: {text}")
    # Do something with the transcribed text
    # e.g., save to file, send to API, etc.

# Start listening
voice_manager.listen(on_transcription)

# Keep running
try:
    while voice_manager.is_listening():
        time.sleep(0.1)
except KeyboardInterrupt:
    voice_manager.cleanup()
```

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

### Control Speech Playback (Python - Basic)

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Provides a basic example of controlling speech playback, including starting a long speech, pausing it, checking its paused state, resuming it, and waiting for completion.

```python
# Start long speech
vm.speak("This is a very long text that will be used to demonstrate the advanced pause and resume control features.")

# Wait and pause
time.sleep(1.5)
if vm.is_speaking():
    vm.pause_speaking()
    print("Speech paused")

# Check pause status
if vm.is_paused():
    print("Confirmed: TTS is paused")
    time.sleep(2)
    
    # Resume from exact position
    vm.resume_speaking()
    print("Speech resumed from exact position")

# Wait for completion
while vm.is_speaking():
    time.sleep(0.1)
print("Speech completed")
```

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

### Install espeak-ng on Windows

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Provides multiple methods for installing espeak-ng on Windows, including using Conda, Chocolatey, or downloading an installer. espeak-ng is recommended for superior TTS quality with VoiceLLM.

```bash
# Option 1: Using Conda
conda install -c conda-forge espeak-ng

# Option 2: Using Chocolatey
choco install espeak-ng

# Option 3: Download installer from https://github.com/espeak-ng/espeak-ng/releases
```

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

### Voice Mode TTS Start Logic

Source: https://github.com/lpalbou/voicellm/blob/main/docs/development.md

Handles actions when Text-to-Speech (TTS) starts playing, based on the current voice mode. Depending on the mode ('wait' or 'full'), it either pauses the voice recognizer or signals that TTS can be interrupted.

```python
def _on_tts_start(self):
    """Called when TTS starts playing"""
    if self._voice_mode == "wait":
        self.voice_recognizer.pause_listening()
    elif self._voice_mode == "full":
        self.voice_recognizer.pause_tts_interrupt()
```

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

### Non-Blocking Audio Stream Setup

Source: https://github.com/lpalbou/voicellm/blob/main/docs/development.md

Configures a non-blocking audio output stream using the sounddevice library. It sets parameters for sample rate, channels, buffer size, data type, and specifies a callback function for audio processing, enabling low-latency audio playback.

```python
self.stream = sd.OutputStream(
    samplerate=22050,
    channels=1,
    callback=self._audio_callback,  # Called ~50x per second
    blocksize=1024,  # Small buffer for low latency
    dtype=np.float32
)
```

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

### Install espeak-ng on macOS

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Installs the espeak-ng package on macOS using the Homebrew package manager, which is recommended for achieving the best voice quality with VoiceLLM.

```bash
brew install espeak-ng
```

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

### Run VoiceLLM CLI REPL

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Starts the VoiceLLM command-line REPL (Read-Eval-Print Loop) for interactive use. The `--debug` flag enables verbose logging for troubleshooting.

```bash
voicellm-cli cli
voicellm-cli cli --debug
```

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

### Install espeak-ng - macOS and Linux

Source: https://github.com/lpalbou/voicellm/blob/main/CONTRIBUTING.md

Instructions for installing the espeak-ng Text-to-Speech synthesizer on macOS and Linux systems using package managers. espeak-ng is recommended for optimal TTS quality in VoiceLLM.

```bash
# macOS:
brew install espeak-ng

# Linux:
sudo apt-get install espeak-ng
```

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

### Integrate Speech-to-Text (STT) in Python

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

Demonstrates integrating Speech-to-Text functionality using VoiceManager. Includes setting up callbacks for transcription and stop commands, checking listening state, and stopping listening.

```python
def handle_user_speech(transcribed_text):
    """Process user's spoken input"""
    print(f"User said: {transcribed_text}")
    # Replace with your AI system processing
    response = f"I understand you said: {transcribed_text}"
    vm.speak(response)

def handle_stop_command():
    """Handle when user says 'stop'"""
    print("User requested stop")
    vm.stop_speaking()

# Start listening
vm.listen(
    on_transcription=handle_user_speech,
    on_stop=handle_stop_command
)

# Check listening state
if vm.is_listening():
    print("Actively listening")

# Stop listening
vm.stop_listening()
```

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

### Initialize and Control VoiceRecognizer in Python

Source: https://context7.com/lpalbou/voicellm/llms.txt

Demonstrates initializing the VoiceRecognizer with various parameters for speech recognition, including callbacks, VAD settings, and Whisper model. It also shows how to start, pause, resume, and stop recognition, as well as control TTS interruption and dynamically change models or VAD aggressiveness.

```python
from voicellm.recognizer import VoiceRecognizer
import time

def on_transcription(text):
    print(f"Transcribed: {text}")

def on_stop(text):
    print(f"Stopped: {text}")

def tts_interrupt():
    print("TTS interrupt callback")

# Initialize recognizer
recognizer = VoiceRecognizer(
    transcription_callback=on_transcription,
    stop_callback=on_stop,
    vad_aggressiveness=1,  # 0-3, higher = more strict
    min_speech_duration=600,  # ms
    silence_timeout=1500,  # ms
    sample_rate=16000,
    chunk_duration=30,  # ms
    whisper_model="tiny",
    min_transcription_length=5,
    debug_mode=True
)

# Start recognition with TTS interrupt capability
recognizer.start(tts_interrupt_callback=tts_interrupt)

# Check if running
if recognizer.is_running:
    print("Recognition active")

# Control TTS interrupt behavior
recognizer.pause_tts_interrupt()   # Disable TTS interruption
recognizer.resume_tts_interrupt()  # Re-enable TTS interruption

# Pause/resume listening entirely
recognizer.pause_listening()   # Stop processing audio
time.sleep(2)
recognizer.resume_listening()  # Resume processing audio

# Change Whisper model dynamically
recognizer.change_whisper_model("base")

# Adjust VAD sensitivity
recognizer.change_vad_aggressiveness(2)

# Stop recognition
recognizer.stop()
```

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

### TTSEngine for Streaming Speech Synthesis

Source: https://context7.com/lpalbou/voicellm/llms.txt

Shows how to use the TTSEngine for text-to-speech synthesis with streaming capabilities. It covers initialization with specific models, controlling speech speed while preserving pitch, and implementing immediate pause/resume functionality. Includes setup for playback event callbacks.

```python
from voicellm.tts import TTSEngine
import time

# Initialize with specific model
tts = TTSEngine(
    model_name="tts_models/en/ljspeech/fast_pitch",
    debug_mode=False,
    streaming=True  # Enable progressive playback for long text
)

# Basic speech synthesis with speed control (pitch preserved)
tts.speak("Hello world", speed=1.0)

# Wait for completion
while tts.is_active():
    time.sleep(0.1)

# Faster speech (pitch preserved via librosa time-stretching)
tts.speak("This is 30% faster while maintaining natural pitch", speed=1.3)

# Immediate pause and resume (takes effect within ~20ms)
tts.speak("This is a long sentence that can be paused and resumed immediately")
time.sleep(1)

success = tts.pause()  # Pause immediately
if success:
    print("Paused immediately")

time.sleep(2)

success = tts.resume()  # Resume from exact position
if success:
    print("Resumed from exact position")

# Check pause status
if tts.is_paused():
    print("Currently paused")

# Stop playback completely
tts.stop()

# Callbacks for playback events
def on_complete():
    print("Speech completed")

tts.speak("Text with completion callback", callback=on_complete)

# Register callbacks for start/end events
def on_start():
    print("TTS started")

def on_end():
    print("TTS ended")

tts.on_playback_start = on_start
tts.on_playback_end = on_end
tts.speak("Text with event callbacks")
```

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

### Initialize and Use VoiceRecognizer for Speech Recognition

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Demonstrates the initialization of VoiceRecognizer for speech recognition, setting up callbacks for transcription and stop commands. It shows how to start the recognizer, stop it, change the Whisper model used for recognition, and adjust the Voice Activity Detection (VAD) aggressiveness.

```python
from voicellm.recognition import VoiceRecognizer

def on_transcription(text):
    print(f"Transcribed: {text}")

def on_stop():
    print("Stop command detected")

recognizer = VoiceRecognizer(transcription_callback=on_transcription,
                           stop_callback=on_stop, 
                           whisper_model="tiny",
                           debug_mode=False)
# recognizer.start(tts_interrupt_callback=None)
# recognizer.stop()
# recognizer.change_whisper_model("base")
# recognizer.change_vad_aggressiveness(2)
```

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

### Run VoiceLLM CLI with Custom Model and Whisper

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Starts the VoiceLLM command-line interface with specific configurations, setting the language model to 'gemma3:latest' and the Whisper model to 'base'. This allows for tailored AI interaction.

```bash
voicellm --model gemma3:latest --whisper base
```

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

### VoiceLLM Integration Pattern: Full Voice Interaction

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Provides an example of a full voice interaction loop, where user speech is transcribed, processed by an LLM, and the response is spoken back. Includes handling of stop commands and cleanup.

```python
vm = VoiceManager()

def on_speech(text):
    response = your_llm.generate(text)
    vm.speak(response)

def on_stop():
    print("User said stop")
    vm.cleanup()

vm.listen(
    on_transcription=on_speech,
    on_stop=on_stop
)
```

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

### Install espeak-ng on Linux (Ubuntu/Debian)

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Installs the espeak-ng package on Ubuntu or Debian-based Linux distributions using the apt-get package manager. This is recommended for optimal TTS quality in VoiceLLM.

```bash
sudo apt-get install espeak-ng
```

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

### Install espeak-ng on Linux (Fedora/RHEL)

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Installs the espeak-ng package on Fedora or RHEL-based Linux distributions using the yum package manager. This ensures high-quality TTS output when using VoiceLLM.

```bash
sudo yum install espeak-ng
```

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

### Dynamically Switch Models and Settings in Python

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

Shows how to dynamically change TTS and Whisper models at runtime using the VoiceManager. Also covers adjusting Voice Activity Detection (VAD) sensitivity and global speech speed.

```python
# Change TTS model at runtime
vm.set_tts_model("tts_models/en/ljspeech/vits")  # Best quality (needs espeak-ng)
vm.set_tts_model("tts_models/en/ljspeech/fast_pitch")  # Default (works everywhere)
vm.set_tts_model("tts_models/en/ljspeech/glow-tts")  # Alternative

# Change Whisper model
vm.set_whisper("base")  # Better accuracy
vm.set_whisper("tiny")  # Faster processing
current_model = vm.get_whisper()  # Get current model name

# VAD (Voice Activity Detection) sensitivity
vm.change_vad_aggressiveness(2)  # 0-3, higher = more sensitive

# Adjust global speed
vm.set_speed(1.2)  # 20% faster
current_speed = vm.get_speed()
```

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

### Robust Voice Manager Initialization (Python)

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

This function, `create_robust_voice_manager`, initializes a `VoiceManager` with fallback options. It first attempts to use a high-quality VITS model, falling back to a default `fast_pitch` model if the first fails. This ensures voice functionality is available even if specific TTS engines are missing. It prints status messages and returns `None` if all attempts fail.

```python
def create_robust_voice_manager():
    """Create VoiceManager with automatic fallbacks"""
    
    # Try best quality first (requires espeak-ng)
    try:
        vm = VoiceManager(tts_model="tts_models/en/ljspeech/vits")
        print("✅ Using VITS model (best quality)")
        return vm
    except Exception as e:
        print(f"⚠️ VITS failed (espeak-ng missing?): {e}")
    
    # Fallback to default model (works everywhere)
    try:
        vm = VoiceManager(tts_model="tts_models/en/ljspeech/fast_pitch")
        print("✅ Using fast_pitch model (default quality)")
        return vm
    except Exception as e:
        print(f"❌ All TTS models failed: {e}")
        return None

# Usage
vm = create_robust_voice_manager()
if vm is None:
    print("Voice functionality unavailable")
```

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

### Robust Exception Handling Example - Python

Source: https://github.com/lpalbou/voicellm/blob/main/CONTRIBUTING.md

A Python method demonstrating robust error handling with a `try-except` block. It includes validation, handling specific exceptions, and a general exception catch-all for unexpected issues, with optional debug output.

```python
import traceback

# Assuming SpecificException is defined elsewhere
# class SpecificException(Exception):
#     pass

def robust_method(self, input_data):
    """Example of robust error handling."""
    try:
        # Validate input
        if not input_data:
            return False
            
        # Main logic
        result = self._process_data(input_data) # Assuming _process_data exists
        return result
        
    except SpecificException as e:
        # Handle specific known issues
        if self.debug_mode: # Assuming debug_mode is an instance attribute
            print(f"Known issue: {e}")
        return self._fallback_method(input_data) # Assuming _fallback_method exists
        
    except Exception as e:
        # Handle unexpected issues
        if self.debug_mode:
            print(f"Unexpected error: {e}")
            traceback.print_exc()
        return False
```

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

### Production-Ready Voice Manager Initialization (Python)

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

Initializes a VoiceManager for production environments with optimized settings for reliability and resource usage. It configures logging to a warning level, selects a reliable TTS model ('tts_models/en/ljspeech/fast_pitch'), a fast Whisper model ('tiny'), and disables debug mode.

```python
# Production-ready initialization
import logging

def create_production_voice_manager():
    """Production-ready VoiceManager setup"""
    
    logging.basicConfig(level=logging.WARNING)  # Reduce noise
    
    # Use reliable model for production
    vm = VoiceManager(
        tts_model="tts_models/en/ljspeech/fast_pitch",  # Reliable
        whisper_model="tiny",  # Fast, low resource usage
        debug_mode=False  # Disable debug output
    )
    
    return vm
```

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

### Perform Text-to-Speech (TTS) in Python

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

Illustrates basic Text-to-Speech operations using the VoiceManager in Python. Includes speaking text, controlling speech speed while preserving pitch, and using a callback function upon speech completion.

```python
# Basic speech synthesis
success = vm.speak("Hello, I am your AI assistant!")

# Speed control (preserves pitch)
vm.speak("This is faster speech", speed=1.5)
vm.speak("This is slower speech", speed=0.7)

# With completion callback
def on_speech_done():
    print("Speech completed")

vm.speak("Text with callback", callback=on_speech_done)

# Check if currently speaking
if vm.is_speaking():
    print("TTS is active")
```

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

### Perform Voice Activity Detection with VoiceDetector in Python

Source: https://context7.com/lpalbou/voicellm/llms.txt

Illustrates initializing the VoiceDetector for WebRTC VAD, checking audio frames for speech, and dynamically adjusting aggressiveness. It also provides an example of using the detector in a streaming context with PyAudio.

```python
from voicellm.vad import VoiceDetector
import pyaudio

# Initialize detector
detector = VoiceDetector(
    aggressiveness=1,  # 0-3, higher = more strict
    sample_rate=16000,  # Must be 8000, 16000, 32000, or 48000
    debug_mode=True
)

# Check if audio frame contains speech
# Frame must be 10, 20, or 30ms at the specified sample_rate
audio_frame = b'...'  # Raw audio bytes (16-bit PCM)
is_speech = detector.is_speech(audio_frame)
if is_speech:
    print("Speech detected")
else:
    print("No speech")

# Adjust sensitivity dynamically
detector.set_aggressiveness(2)  # More aggressive filtering
is_speech = detector.is_speech(audio_frame)

# Test different aggressiveness levels
for level in range(4):  # 0, 1, 2, 3
    detector.set_aggressiveness(level)
    if detector.is_speech(audio_frame):
        print(f"Level {level}: Speech detected")
    else:
        print(f"Level {level}: No speech")

# Use in streaming context
pa = pyaudio.PyAudio()
stream = pa.open(
    format=pyaudio.paInt16,
    channels=1,
    rate=16000,
    input=True,
    frames_per_buffer=480  # 30ms at 16000 Hz
)

try:
    while True:
        frame = stream.read(480)
        if detector.is_speech(frame):
            print("Voice activity detected")
            # Start recording or trigger action...
except KeyboardInterrupt:
    stream.stop_stream()
    stream.close()
    pa.terminate()
```

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

### VoiceManager Callback Functions Setup

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Illustrates how to set up callback functions for VoiceManager's listening functionality. It defines `on_transcription` to handle transcribed speech and `on_stop` for when a stop command is detected. These callbacks are then passed to the `listen` method.

```python
def on_transcription(text):
    """Called when speech is transcribed"""
    print(f"User said: {text}")
    # Your custom logic here

def on_stop():
    """Called when user says 'stop'"""
    print("Stopping voice mode")
    # Your cleanup logic here

voice_manager.listen(
    on_transcription=on_transcription,
    on_stop=on_stop
)
```

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

### Control Audio Playback with Pause/Resume in Python

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

Demonstrates professional audio control for TTS, including immediate pausing and resuming speech from the exact point of interruption. It also shows how to check the pause state and stop speech entirely.

```python
# Immediate pause (takes effect in ~20ms)
if vm.pause_speaking():
    print("Successfully paused")
else:
    print("Nothing to pause")

# Resume from exact position
if vm.resume_speaking():
    print("Successfully resumed")
else:
    print("Nothing to resume")

# Check pause state
if vm.is_paused():
    print("Currently paused")

# Stop completely
vm.stop_speaking()
```

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

### Text-to-Speech Only Example

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Demonstrates the standalone text-to-speech (TTS) functionality of VoiceLLM. It initializes the VoiceManager, speaks a predefined message, waits for speech completion, adjusts the speaking speed, speaks another message at the new speed, and finally cleans up resources.

```python
from voicellm import VoiceManager
import time

# Initialize voice manager
voice_manager = VoiceManager()

# Simple text-to-speech
voice_manager.speak("Hello! This is a test of the text to speech system.")

# Wait for speech to finish
while voice_manager.is_speaking():
    time.sleep(0.1)

# Adjust speed
voice_manager.set_speed(1.5)
voice_manager.speak("This speech is 50% faster.")

while voice_manager.is_speaking():
    time.sleep(0.1)

# Cleanup
voice_manager.cleanup()
```

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

### Control Speech Playback with Pause and Resume (Python)

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Demonstrates starting a long speech, pausing it, and resuming from the exact position using the VoiceManager. Includes interactive control via a separate thread and error handling for playback operations.

```python
from voicellm import VoiceManager
import threading
import time

vm = VoiceManager()

def control_speech():
    """Interactive control in separate thread"""
    time.sleep(2)
    print("Pausing speech...")
    vm.pause_speaking()
    
    time.sleep(3)
    print("Resuming speech...")
    vm.resume_speaking()

# Start long speech
long_text = """
This is a comprehensive demonstration of VoiceLLM's immediate pause and resume functionality.
The system uses non-blocking audio streaming with callback-based control.
You can pause and resume at any time with immediate response.
The audio continues from the exact position where it was paused.
"""

# Start control thread
control_thread = threading.Thread(target=control_speech, daemon=True)
control_thread.start()

# Start speech (non-blocking)
vm.speak(long_text)

# Wait for completion
while vm.is_speaking() or vm.is_paused():
    time.sleep(0.1)

vm.cleanup()
```

```python
from voicellm import VoiceManager

vm = VoiceManager()

# Start speech
vm.speak("Testing pause/resume with error handling")

# Safe pause with error handling
try:
    if vm.is_speaking():
        success = vm.pause_speaking()
        if success:
            print("Successfully paused")
        else:
            print("No active speech to pause")
    
    # Safe resume with error handling
    if vm.is_paused():
        success = vm.resume_speaking()
        if success:
            print("Successfully resumed")
        else:
            print("Was not paused or playback completed")
            
except Exception as e:
    print(f"Error controlling TTS: {e}")
```

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

### Run VoiceLLM CLI in Voice Mode

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Launches the VoiceLLM command-line interface in its default voice mode, enabling both Text-to-Speech (TTS) and Speech-to-Text (STT). It automatically selects the best TTS model available, prioritizing VITS if espeak-ng is installed.

```bash
voicellm
```

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

### Resource Cleanup for Voice Systems (Python)

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

Provides a function to properly clean up VoiceLLM resources in production environments. It stops any ongoing speech or listening activities and calls a general cleanup method. Includes error handling to report any issues during the cleanup process, ensuring a clean shutdown.

```python
def cleanup_voice_resources(vm):
    """Proper cleanup for production environments"""
    try:
        vm.stop_speaking()
        vm.stop_listening()
        vm.cleanup()
        print("✅ Voice resources cleaned up")
    except Exception as e:
        print(f"⚠️ Cleanup warning: {e}")
```

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

### Initialize VoiceManager in Python

Source: https://github.com/lpalbou/voicellm/blob/main/llms.txt

Demonstrates different ways to initialize the VoiceManager, including options for quality and fallback mechanisms. It highlights the dependency on external speech synthesis engines like espeak-ng for the best quality.

```python
from voicellm import VoiceManager

# Best quality (requires espeak-ng, auto-fallback to fast_pitch)
vm = VoiceManager(tts_model="tts_models/en/ljspeech/vits")

# Guaranteed to work everywhere (default)
vm = VoiceManager(tts_model="tts_models/en/ljspeech/fast_pitch")

# Simple initialization (uses default fast_pitch)
vm = VoiceManager()
```

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

### Stream AI Responses with Voice (Python)

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

This function streams AI responses and provides immediate Text-to-Speech (TTS) feedback as sentences are generated. It utilizes a mock AI generator and requires a VoiceManager instance (`vm`) for speech output. The function processes chunks of text, speaks complete sentences immediately, and handles any remaining text at the end.

```python
def stream_ai_response_with_voice(user_input):
    """Stream AI response with immediate TTS feedback"""
    
    # Replace with your AI streaming generator
    def mock_ai_generator(text):
        sentences = [
            f"Processing your input: {text}.",
            "This is the first part of my response.",
            "Here's additional information.",
            "Thank you for your question!"
        ]
        for sentence in sentences:
            yield sentence
    
    # Start generating response
    response_chunks = mock_ai_generator(user_input)
    
    full_response = ""
    current_sentence = ""
    
    for chunk in response_chunks:
        full_response += chunk
        current_sentence += chunk
        
        # Speak complete sentences immediately
        if chunk.endswith(('.', '!', '?')):
            vm.speak(current_sentence.strip())
            current_sentence = ""
    
    # Speak any remaining text
    if current_sentence.strip():
        vm.speak(current_sentence.strip())
    
    return full_response
```

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

### Run VoiceLLM Simple Demo

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Executes a simplified demo version of VoiceLLM, providing a basic interactive experience without loading all complex models.

```bash
voicellm-cli simple
```

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

### Interrupt-Safe AI Conversations (Python)

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

This class, `VoiceAIConversation`, manages voice-based conversations with interrupt handling. It uses a `VoiceManager` for listening and speaking. The `start_conversation` method sets up callbacks for user input and stopping the conversation. User input is processed by AI, and responses are spoken only if the conversation is still active. Includes a placeholder `process_with_ai` method.

```python
class VoiceAIConversation:
    def __init__(self):
        self.vm = VoiceManager()
        self.conversation_active = False
    
    def start_conversation(self):
        """Start voice conversation with interrupt handling"""
        self.conversation_active = True
        
        def on_user_input(text):
            if not self.conversation_active:
                return
            
            # Stop any current AI speech
            self.vm.stop_speaking()
            
            # Process user input
            ai_response = self.process_with_ai(text)
            
            # Speak response if conversation still active
            if self.conversation_active:
                self.vm.speak(ai_response)
        
        def on_stop():
            self.conversation_active = False
            self.vm.speak("Goodbye!")
        
        self.vm.listen(
            on_transcription=on_user_input,
            on_stop=on_stop
        )
    
    def process_with_ai(self, user_text):
        """Replace with your AI processing logic"""
        # Example responses - replace with your AI system
        responses = [
            f"I understand you said: {user_text}",
            "That's interesting! Tell me more.",
            "I'm processing that information.",
            "How can I help you further?"
        ]
        import random
        return random.choice(responses)
```

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

### LangChain Integration for Voice Chat (Python)

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

Enables voice chat functionality using LangChain, connecting it with an OpenAI LLM. It maintains conversation memory and uses LangChain's ConversationChain to predict responses to user input, which are then vocalized by VoiceLLM. Requires LangChain and OpenAI libraries, along with an API key.

```python
from langchain.llms import OpenAI
from langchain.chains import ConversationChain
from langchain.memory import ConversationBufferMemory

def voice_langchain_chat(vm, openai_api_key):
    """Voice chat using LangChain"""
    
    llm = OpenAI(openai_api_key=openai_api_key)
    memory = ConversationBufferMemory()
    conversation = ConversationChain(llm=llm, memory=memory)
    
    def handle_voice_input(user_text):
        # Process with LangChain
        ai_response = conversation.predict(input=user_text)
        
        # Speak response
        vm.speak(ai_response)
    
    vm.listen(on_transcription=handle_voice_input)
```

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

### Multi-Threaded Voice Control (Python)

Source: https://github.com/lpalbou/voicellm/blob/main/llms-full.txt

The `ThreadSafeVoiceController` class enables multi-threaded voice operations using a queue. It manages a `speech_queue` and a worker thread (`_speech_worker`) to handle `VoiceManager.speak` calls in a thread-safe manner. This prevents race conditions when multiple threads attempt to speak simultaneously. Includes methods for starting the worker, queuing speech, and emergency stopping.

```python
import threading
import time

class ThreadSafeVoiceController:
    def __init__(self):
        self.vm = VoiceManager()
        self.speech_queue = []
        self.queue_lock = threading.Lock()
        self.worker_thread = None
        self.running = False
    
    def start_worker(self):
        """Start background speech worker"""
        self.running = True
        self.worker_thread = threading.Thread(target=self._speech_worker)
        self.worker_thread.start()
    
    def _speech_worker(self):
        """Background worker for queued speech"""
        while self.running:
            with self.queue_lock:
                if self.speech_queue and not self.vm.is_speaking():
                    text, speed = self.speech_queue.pop(0)
                    self.vm.speak(text, speed=speed)
            time.sleep(0.1)
    
    def queue_speech(self, text, speed=1.0):
        """Thread-safe speech queueing"""
        with self.queue_lock:
            self.speech_queue.append((text, speed))
    
    def emergency_stop(self):
        """Immediate stop from any thread"""
        with self.queue_lock:
            self.speech_queue.clear()
        self.vm.stop_speaking()
```

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

### Programmatic CLI Access in Python

Source: https://context7.com/lpalbou/voicellm/llms.txt

Demonstrates how to programmatically launch the VoiceLLM CLI application using its main function and passing arguments via `sys.argv`.

```python
from voicellm.examples.voice_cli import main
import sys

# Set arguments
sys.argv = [
    'voicellm',
    '--model', 'granite3.3:2b',
    '--whisper', 'base',
    '--temperature', '0.4',
    '--no-listening'
]

# Launch
main()
```

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

### Run VoiceLLM Web API

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Launches the VoiceLLM web API server. This allows integration with other applications. Options to specify host, port, or run in simulation mode are available.

```bash
voicellm-cli web
voicellm-cli web --host 0.0.0.0 --port 8000
voicellm-cli web --simulate
```

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

### VoiceLLM Cleanup and Resource Management

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Demonstrates proper resource management in VoiceLLM by showing how to explicitly call the `cleanup()` method and how to use a context manager for automatic cleanup.

```python
# Always cleanup when done
vm.cleanup()
```

```python
# Or use context manager pattern
from contextlib import contextmanager

@contextmanager
def voice_manager():
    vm = VoiceManager()
    try:
        yield vm
    finally:
        vm.cleanup()

# Usage
with voice_manager() as vm:
    vm.speak("Hello")
```

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

### Initialize and Use TTSEngine for Text-to-Speech

Source: https://github.com/lpalbou/voicellm/blob/main/README.md

Shows how to initialize the TTSEngine for text-to-speech synthesis, enabling progressive playback with the `streaming` option. It covers speaking with speed control while preserving pitch, immediate pause and resume functionality, stopping playback, and checking the active or paused status of the engine.

```python
from voicellm.tts import TTSEngine

# Initialize with fast_pitch model (default, no external dependencies)
tts = TTSEngine(
    model_name="tts_models/en/ljspeech/fast_pitch",
    debug_mode=False,
    streaming=True  # Enable progressive playback for long text
)

# Speak with speed control (pitch preserved via time-stretching)
# tts.speak(text, speed=1.2, callback=None)  # 20% faster, same pitch

# Immediate pause and resume control
# success = tts.pause()      # Pause IMMEDIATELY (~20ms response)
# success = tts.resume()     # Resume IMMEDIATELY from exact position
# is_paused = tts.is_paused()  # Check if currently paused

# tts.stop()       # Stop completely (cannot resume)
# tts.is_active()  # Check if active
```