abstractvoice 0.4.6__tar.gz → 0.5.1__tar.gz

{abstractvoice-0.4.6 → abstractvoice-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractvoice
-Version: 0.4.6
+Version: 0.5.1
 Summary: A modular Python library for voice interactions with AI systems
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 License-Expression: MIT
@@ -172,38 +172,51 @@ AbstractVoice automatically detects espeak-ng and upgrades to premium quality vo
 
 ## Quick Start
 
-### ⚡ Instant TTS (v0.4.0+)
+### ⚡ Instant TTS (v0.5.0+)
 
 ```python
 from abstractvoice import VoiceManager
 
-# Initialize voice manager - automatically downloads essential model if needed
+# Initialize voice manager - works immediately with included dependencies
 vm = VoiceManager()
 
-# Text-to-speech works immediately!
+# Text-to-speech works right away!
 vm.speak("Hello! TTS works out of the box!")
+
+# Language switching with automatic model download
+vm.set_language('fr')
+vm.speak("Bonjour! Le français fonctionne aussi!")
 ```
 
-**That's it!** AbstractVoice v0.4.0+ automatically:
-- ✅ Downloads essential English model (107MB) on first use
-- ✅ Caches models permanently for offline use
-- ✅ Works immediately after first setup
+**That's it!** AbstractVoice v0.5.0+ automatically:
+- ✅ Includes essential TTS dependencies in base installation
+- ✅ Downloads models automatically when switching languages/voices
+- ✅ Works immediately after `pip install abstractvoice`
+- ✅ No silent failures - clear error messages if download fails
 - ✅ No complex configuration needed
 
-### 🌍 Multi-Language Support
+### 🌍 Multi-Language Support (Auto-Download in v0.5.0+)
 
 ```python
-# Download and use French voice
-vm.download_model('fr.css10_vits')  # Downloads automatically
+# Simply switch language - downloads model automatically if needed!
 vm.set_language('fr')
 vm.speak("Bonjour! Je parle français maintenant.")
 
-# Download and use German voice
-vm.download_model('de.thorsten_vits')
+# Switch to German - no manual download needed
 vm.set_language('de')
 vm.speak("Hallo! Ich spreche jetzt Deutsch.")
+
+# Spanish, Italian also supported
+vm.set_language('es')
+vm.speak("¡Hola! Hablo español ahora.")
+
+# If download fails, you'll get clear error messages with instructions
+# Example: "❌ Cannot switch to French: Model download failed"
+#          "   Try: abstractvoice download-models --language fr"
 ```
 
+**New in v0.5.0:** No more manual `download_model()` calls! Language switching handles downloads automatically.
+
 ### 🔧 Check System Status
 
 ```python
@@ -602,6 +615,37 @@ manager.set_tts_model("tts_models/en/ljspeech/glow-tts")
 # - "tts_models/en/ljspeech/glow-tts" (alternative fallback)
 # - "tts_models/en/ljspeech/tacotron2-DDC" (legacy)
 
+# === Audio Lifecycle Callbacks (v0.5.1+) ===
+
+# NEW: Precise audio timing callbacks for visual status indicators
+def on_synthesis_start():
+    print("🔴 Synthesis started - show thinking animation")
+
+def on_audio_start():
+    print("🔵 Audio started - show speaking animation")
+
+def on_audio_pause():
+    print("⏸️ Audio paused - show paused animation")
+
+def on_audio_resume():
+    print("▶️ Audio resumed - continue speaking animation")
+
+def on_audio_end():
+    print("🟢 Audio ended - show ready animation")
+
+def on_synthesis_end():
+    print("✅ Synthesis complete")
+
+# Wire up callbacks
+manager.tts_engine.on_playback_start = on_synthesis_start    # Existing (synthesis phase)
+manager.tts_engine.on_playback_end = on_synthesis_end        # Existing (synthesis phase)
+manager.on_audio_start = on_audio_start                      # NEW (actual audio playback)
+manager.on_audio_end = on_audio_end                          # NEW (actual audio playback)
+manager.on_audio_pause = on_audio_pause                      # NEW (pause events)
+manager.on_audio_resume = on_audio_resume                    # NEW (resume events)
+
+# Perfect for system tray icons, UI animations, or coordinating multiple audio streams
+
 # === STT (Speech-to-Text) ===
 
 def on_transcription(text):
@@ -1371,20 +1415,22 @@ abstractvoice check-deps
 
 ### CLI Voice Commands
 
-In the CLI REPL, use these commands:
+In the CLI REPL, use these commands (v0.5.0+):
 
 ```bash
 # List all available voices with download status
 /setvoice
 
-# Download and set specific voice
-/setvoice fr.css10_vits      # French CSS10 VITS
-/setvoice de.thorsten_vits   # German Thorsten
-/setvoice it.mai_male_vits   # Italian Male
+# Automatically download and set specific voice (NEW in v0.5.0!)
+/setvoice fr.css10_vits      # Downloads French CSS10 if needed
+/setvoice de.thorsten_vits   # Downloads German Thorsten if needed
+/setvoice it.mai_male_vits   # Downloads Italian Male if needed
+/setvoice en.jenny           # Downloads Jenny voice if needed
 
-# Change language
-/language fr
-/language de
+# Change language (automatically downloads models if needed - NEW!)
+/language fr                 # Switches to French, downloads if needed
+/language de                 # Switches to German, downloads if needed
+/language es                 # Switches to Spanish, downloads if needed
 
 # Voice controls
 /pause                       # Pause current speech
@@ -1395,6 +1441,8 @@ In the CLI REPL, use these commands:
 /exit
 ```
 
+**New in v0.5.0:** Language and voice commands now automatically download missing models with progress indicators. No more silent failures!
+
 ## Perspectives
 
 This is a test project that I designed with examples to work with Ollama, but I will adapt the examples and abstractvoice to work with any LLM provider (anthropic, openai, etc).

{abstractvoice-0.4.6 → abstractvoice-0.5.1}/README.md

@@ -82,38 +82,51 @@ AbstractVoice automatically detects espeak-ng and upgrades to premium quality vo
 
 ## Quick Start
 
-### ⚡ Instant TTS (v0.4.0+)
+### ⚡ Instant TTS (v0.5.0+)
 
 ```python
 from abstractvoice import VoiceManager
 
-# Initialize voice manager - automatically downloads essential model if needed
+# Initialize voice manager - works immediately with included dependencies
 vm = VoiceManager()
 
-# Text-to-speech works immediately!
+# Text-to-speech works right away!
 vm.speak("Hello! TTS works out of the box!")
+
+# Language switching with automatic model download
+vm.set_language('fr')
+vm.speak("Bonjour! Le français fonctionne aussi!")
 ```
 
-**That's it!** AbstractVoice v0.4.0+ automatically:
-- ✅ Downloads essential English model (107MB) on first use
-- ✅ Caches models permanently for offline use
-- ✅ Works immediately after first setup
+**That's it!** AbstractVoice v0.5.0+ automatically:
+- ✅ Includes essential TTS dependencies in base installation
+- ✅ Downloads models automatically when switching languages/voices
+- ✅ Works immediately after `pip install abstractvoice`
+- ✅ No silent failures - clear error messages if download fails
 - ✅ No complex configuration needed
 
-### 🌍 Multi-Language Support
+### 🌍 Multi-Language Support (Auto-Download in v0.5.0+)
 
 ```python
-# Download and use French voice
-vm.download_model('fr.css10_vits')  # Downloads automatically
+# Simply switch language - downloads model automatically if needed!
 vm.set_language('fr')
 vm.speak("Bonjour! Je parle français maintenant.")
 
-# Download and use German voice
-vm.download_model('de.thorsten_vits')
+# Switch to German - no manual download needed
 vm.set_language('de')
 vm.speak("Hallo! Ich spreche jetzt Deutsch.")
+
+# Spanish, Italian also supported
+vm.set_language('es')
+vm.speak("¡Hola! Hablo español ahora.")
+
+# If download fails, you'll get clear error messages with instructions
+# Example: "❌ Cannot switch to French: Model download failed"
+#          "   Try: abstractvoice download-models --language fr"
 ```
 
+**New in v0.5.0:** No more manual `download_model()` calls! Language switching handles downloads automatically.
+
 ### 🔧 Check System Status
 
 ```python
@@ -512,6 +525,37 @@ manager.set_tts_model("tts_models/en/ljspeech/glow-tts")
 # - "tts_models/en/ljspeech/glow-tts" (alternative fallback)
 # - "tts_models/en/ljspeech/tacotron2-DDC" (legacy)
 
+# === Audio Lifecycle Callbacks (v0.5.1+) ===
+
+# NEW: Precise audio timing callbacks for visual status indicators
+def on_synthesis_start():
+    print("🔴 Synthesis started - show thinking animation")
+
+def on_audio_start():
+    print("🔵 Audio started - show speaking animation")
+
+def on_audio_pause():
+    print("⏸️ Audio paused - show paused animation")
+
+def on_audio_resume():
+    print("▶️ Audio resumed - continue speaking animation")
+
+def on_audio_end():
+    print("🟢 Audio ended - show ready animation")
+
+def on_synthesis_end():
+    print("✅ Synthesis complete")
+
+# Wire up callbacks
+manager.tts_engine.on_playback_start = on_synthesis_start    # Existing (synthesis phase)
+manager.tts_engine.on_playback_end = on_synthesis_end        # Existing (synthesis phase)
+manager.on_audio_start = on_audio_start                      # NEW (actual audio playback)
+manager.on_audio_end = on_audio_end                          # NEW (actual audio playback)
+manager.on_audio_pause = on_audio_pause                      # NEW (pause events)
+manager.on_audio_resume = on_audio_resume                    # NEW (resume events)
+
+# Perfect for system tray icons, UI animations, or coordinating multiple audio streams
+
 # === STT (Speech-to-Text) ===
 
 def on_transcription(text):
@@ -1281,20 +1325,22 @@ abstractvoice check-deps
 
 ### CLI Voice Commands
 
-In the CLI REPL, use these commands:
+In the CLI REPL, use these commands (v0.5.0+):
 
 ```bash
 # List all available voices with download status
 /setvoice
 
-# Download and set specific voice
-/setvoice fr.css10_vits      # French CSS10 VITS
-/setvoice de.thorsten_vits   # German Thorsten
-/setvoice it.mai_male_vits   # Italian Male
+# Automatically download and set specific voice (NEW in v0.5.0!)
+/setvoice fr.css10_vits      # Downloads French CSS10 if needed
+/setvoice de.thorsten_vits   # Downloads German Thorsten if needed
+/setvoice it.mai_male_vits   # Downloads Italian Male if needed
+/setvoice en.jenny           # Downloads Jenny voice if needed
 
-# Change language
-/language fr
-/language de
+# Change language (automatically downloads models if needed - NEW!)
+/language fr                 # Switches to French, downloads if needed
+/language de                 # Switches to German, downloads if needed
+/language es                 # Switches to Spanish, downloads if needed
 
 # Voice controls
 /pause                       # Pause current speech
@@ -1305,6 +1351,8 @@ In the CLI REPL, use these commands:
 /exit
 ```
 
+**New in v0.5.0:** Language and voice commands now automatically download missing models with progress indicators. No more silent failures!
+
 ## Perspectives
 
 This is a test project that I designed with examples to work with Ollama, but I will adapt the examples and abstractvoice to work with any LLM provider (anthropic, openai, etc).

{abstractvoice-0.4.6 → abstractvoice-0.5.1}/abstractvoice/__init__.py

@@ -32,5 +32,5 @@ from .voice_manager import VoiceManager
 # Import simple APIs for third-party applications
 from .simple_model_manager import list_models, download_model, get_status, is_ready
 
-__version__ = "0.4.6"
+__version__ = "0.5.1"
 __all__ = ['VoiceManager', 'list_models', 'download_model', 'get_status', 'is_ready'] 

{abstractvoice-0.4.6 → abstractvoice-0.5.1}/abstractvoice/simple_model_manager.py

@@ -212,7 +212,7 @@ class SimpleModelManager:
             return False
 
     def download_model(self, model_name: str, progress_callback: Optional[Callable[[str, bool], None]] = None) -> bool:
-        """Download a specific model.
+        """Download a specific model with improved error handling.
 
         Args:
             model_name: TTS model name (e.g., 'tts_models/en/ljspeech/fast_pitch')
@@ -231,25 +231,56 @@ class SimpleModelManager:
         try:
             TTS, _ = _import_tts()
 
-            if self.debug_mode:
-                print(f"📥 Downloading {model_name}...")
+            print(f"📥 Downloading {model_name}...")
+            print(f"   This may take a few minutes depending on your connection...")
 
             start_time = time.time()
 
             # Initialize TTS to trigger download
-            tts = TTS(model_name=model_name, progress_bar=True)
+            # Set gpu=False to avoid CUDA errors on systems without GPU
+            try:
+                tts = TTS(model_name=model_name, progress_bar=True, gpu=False)
+
+                # Verify the model actually downloaded
+                if not self.is_model_cached(model_name):
+                    print(f"⚠️ Model download completed but not found in cache")
+                    return False
+
+            except Exception as init_error:
+                # Try alternative download method
+                error_msg = str(init_error).lower()
+                if "connection" in error_msg or "timeout" in error_msg:
+                    print(f"❌ Network error: Check your internet connection")
+                elif "not found" in error_msg:
+                    print(f"❌ Model '{model_name}' not found in registry")
+                else:
+                    print(f"❌ Download error: {init_error}")
+                raise
 
             download_time = time.time() - start_time
-            if self.debug_mode:
-                print(f"✅ Downloaded {model_name} in {download_time:.1f}s")
+            print(f"✅ Downloaded {model_name} in {download_time:.1f}s")
 
             if progress_callback:
                 progress_callback(model_name, True)
             return True
 
         except Exception as e:
-            if self.debug_mode:
-                print(f"❌ Failed to download {model_name}: {e}")
+            error_msg = str(e).lower()
+
+            # Provide helpful error messages
+            if "connection" in error_msg or "timeout" in error_msg:
+                print(f"❌ Failed to download {model_name}: Network issue")
+                print(f"   Check your internet connection and try again")
+            elif "permission" in error_msg:
+                print(f"❌ Failed to download {model_name}: Permission denied")
+                print(f"   Check write permissions for cache directory")
+            elif "space" in error_msg:
+                print(f"❌ Failed to download {model_name}: Insufficient disk space")
+            else:
+                print(f"❌ Failed to download {model_name}")
+                if self.debug_mode:
+                    print(f"   Error: {e}")
+
             if progress_callback:
                 progress_callback(model_name, False)
             return False
@@ -454,8 +485,16 @@ def download_models_cli():
         return
 
     if args.clear:
-        manager.clear_cache()
-        print("✅ Cache cleared")
+        # Ask for confirmation
+        response = input("⚠️ This will delete all downloaded TTS models. Continue? (y/N): ")
+        if response.lower() == 'y':
+            success = manager.clear_cache(confirm=True)
+            if success:
+                print("✅ Model cache cleared")
+            else:
+                print("❌ Failed to clear cache")
+        else:
+            print("Cancelled")
         return
 
     if args.model:

{abstractvoice-0.4.6 → abstractvoice-0.5.1}/abstractvoice/tts/tts_engine.py

@@ -212,6 +212,13 @@ class NonBlockingAudioPlayer:
         self.current_position = 0
         self.playback_complete_callback = None
         
+        # NEW: Enhanced audio lifecycle callbacks
+        self.on_audio_start = None      # Called when first audio sample plays
+        self.on_audio_end = None        # Called when last audio sample finishes
+        self.on_audio_pause = None      # Called when audio is paused
+        self.on_audio_resume = None     # Called when audio is resumed
+        self._audio_started = False     # Track if we've fired start callback
+        
     def _audio_callback(self, outdata, frames, time, status):
         """Callback function for OutputStream - provides immediate pause/resume."""
         if status and self.debug_mode:
@@ -237,6 +244,12 @@ class NonBlockingAudioPlayer:
                     outdata.fill(0)
                     if self.is_playing:
                         self.is_playing = False
+                        self._audio_started = False  # Reset for next playback
+                        
+                        # Fire audio end callback
+                        if self.on_audio_end:
+                            threading.Thread(target=self.on_audio_end, daemon=True).start()
+                            
                         if self.playback_complete_callback:
                             # Call completion callback in a separate thread to avoid blocking
                             threading.Thread(target=self.playback_complete_callback, daemon=True).start()
@@ -246,6 +259,12 @@ class NonBlockingAudioPlayer:
             remaining = len(self.current_audio) - self.current_position
             frames_to_output = min(frames, remaining)
             
+            # Fire audio start callback on first real audio output
+            if frames_to_output > 0 and not self._audio_started:
+                self._audio_started = True
+                if self.on_audio_start:
+                    threading.Thread(target=self.on_audio_start, daemon=True).start()
+            
             # Output the audio data
             if frames_to_output > 0:
                 # Handle both mono and stereo output
@@ -344,6 +363,11 @@ class NonBlockingAudioPlayer:
                 self.is_paused = True
                 if self.debug_mode:
                     print(" > Audio paused immediately")
+                
+                # Fire audio pause callback
+                if self.on_audio_pause:
+                    threading.Thread(target=self.on_audio_pause, daemon=True).start()
+                
                 return True
         return False
     
@@ -354,6 +378,11 @@ class NonBlockingAudioPlayer:
                 self.is_paused = False
                 if self.debug_mode:
                     print(" > Audio resumed immediately")
+                
+                # Fire audio resume callback
+                if self.on_audio_resume:
+                    threading.Thread(target=self.on_audio_resume, daemon=True).start()
+                
                 return True
         return False
     
@@ -1264,4 +1293,5 @@ class TTSEngine:
         Returns:
             True if TTS is active, False otherwise
         """
-        return self.is_playing 
+        return self.is_playing
+    

{abstractvoice-0.4.6 → abstractvoice-0.5.1}/abstractvoice/voice_manager.py

@@ -241,6 +241,18 @@ class VoiceManager:
         self.tts_engine.on_playback_start = self._on_tts_start
         self.tts_engine.on_playback_end = self._on_tts_end
         
+        # NEW: Enhanced audio lifecycle callbacks (v0.5.1)
+        self.on_audio_start = None      # Called when first audio sample plays
+        self.on_audio_end = None        # Called when last audio sample finishes
+        self.on_audio_pause = None      # Called when audio is paused
+        self.on_audio_resume = None     # Called when audio is resumed
+        
+        # Wire callbacks directly to audio player (skip TTSEngine layer)
+        self.tts_engine.audio_player.on_audio_start = self._on_audio_start
+        self.tts_engine.audio_player.on_audio_end = self._on_audio_end
+        self.tts_engine.audio_player.on_audio_pause = self._on_audio_pause
+        self.tts_engine.audio_player.on_audio_resume = self._on_audio_resume
+        
         # Voice recognizer is initialized on demand
         self.voice_recognizer = None
         self.whisper_model = whisper_model
@@ -548,13 +560,37 @@ class VoiceManager:
 
         # Select best model for this language
         selected_model = self._select_best_model(language)
-        models_to_try = [selected_model, self.SAFE_FALLBACK]
+
+        # CRITICAL FIX: Check if model is available, download if not
+        from .instant_setup import is_model_cached
+        from .simple_model_manager import download_model
+
+        if not is_model_cached(selected_model):
+            if self.debug_mode:
+                print(f"📥 Model {selected_model} not cached, downloading...")
+
+            # Try to download the model
+            success = download_model(selected_model)
+            if not success:
+                if self.debug_mode:
+                    print(f"❌ Failed to download {selected_model}")
+                # If download fails and it's not English, we have a problem
+                if language != 'en':
+                    print(f"❌ Cannot switch to {self.LANGUAGES[language]['name']}: Model download failed")
+                    print(f"   Try: abstractvoice download-models --language {language}")
+                    return False
+
+        models_to_try = [selected_model]
+
+        # Only add fallback if it's different from selected
+        if selected_model != self.SAFE_FALLBACK:
+            models_to_try.append(self.SAFE_FALLBACK)
 
         for model_name in models_to_try:
             try:
                 if self.debug_mode:
                     lang_name = self.LANGUAGES[language]['name']
-                    print(f"🌍 Switching to {lang_name} voice: {model_name}")
+                    print(f"🌍 Loading {lang_name} voice: {model_name}")
 
                 # Reinitialize TTS engine
                 TTSEngine = _import_tts_engine()
@@ -579,12 +615,16 @@ class VoiceManager:
 
             except Exception as e:
                 if self.debug_mode:
-                    print(f"⚠️ Model {model_name} failed: {e}")
+                    print(f"⚠️ Model {model_name} failed to load: {e}")
+                # Don't silently continue - report the failure
+                if model_name == selected_model and language != 'en':
+                    print(f"❌ Failed to load {lang_name} voice model")
+                    print(f"   The model might be corrupted. Try:")
+                    print(f"   abstractvoice download-models --language {language}")
                 continue
 
         # All models failed
-        if self.debug_mode:
-            print(f"❌ All models failed for language '{language}'")
+        print(f"❌ Cannot switch to {self.LANGUAGES[language]['name']}: No working models")
         return False
 
     def get_language(self):
@@ -856,15 +896,29 @@ class VoiceManager:
             return False
 
         voice_info = self.VOICE_CATALOG[language][voice_id]
+        model_name = voice_info['model']
 
-        # Check compatibility
-        if voice_info['requires'] == 'espeak-ng' and not self._test_model_compatibility(voice_info['model']):
+        # CRITICAL FIX: Download model if not cached
+        from .instant_setup import is_model_cached
+        from .simple_model_manager import download_model
+
+        if not is_model_cached(model_name):
+            print(f"📥 Voice model '{voice_id}' not cached, downloading...")
+            success = download_model(model_name)
+            if not success:
+                print(f"❌ Failed to download voice '{voice_id}'")
+                print(f"   Check your internet connection and try again")
+                return False
+            print(f"✅ Voice model '{voice_id}' downloaded successfully")
+
+        # Check compatibility after download
+        if voice_info['requires'] == 'espeak-ng' and not self._test_model_compatibility(model_name):
             if self.debug_mode:
                 print(f"⚠️ Voice '{voice_id}' requires espeak-ng. Install it for premium quality.")
-            return False
+            # Don't fail - try to load anyway
+            # return False
 
         # Set the specific voice
-        model_name = voice_info['model']
         if self.debug_mode:
             print(f"🎭 Setting {language} voice to: {voice_id}")
             print(f"   Model: {model_name}")
@@ -988,4 +1042,24 @@ class VoiceManager:
             self.voice_recognizer.stop()
 
         self.stop_speaking()
-        return True 
+        return True
+    
+    def _on_audio_start(self):
+        """Called when audio actually starts playing."""
+        if self.on_audio_start:
+            self.on_audio_start()
+    
+    def _on_audio_end(self):
+        """Called when audio actually finishes playing."""
+        if self.on_audio_end:
+            self.on_audio_end()
+    
+    def _on_audio_pause(self):
+        """Called when audio is paused."""
+        if self.on_audio_pause:
+            self.on_audio_pause()
+    
+    def _on_audio_resume(self):
+        """Called when audio is resumed."""
+        if self.on_audio_resume:
+            self.on_audio_resume() 

{abstractvoice-0.4.6 → abstractvoice-0.5.1}/abstractvoice.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractvoice
-Version: 0.4.6
+Version: 0.5.1
 Summary: A modular Python library for voice interactions with AI systems
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 License-Expression: MIT
@@ -172,38 +172,51 @@ AbstractVoice automatically detects espeak-ng and upgrades to premium quality vo
 
 ## Quick Start
 
-### ⚡ Instant TTS (v0.4.0+)
+### ⚡ Instant TTS (v0.5.0+)
 
 ```python
 from abstractvoice import VoiceManager
 
-# Initialize voice manager - automatically downloads essential model if needed
+# Initialize voice manager - works immediately with included dependencies
 vm = VoiceManager()
 
-# Text-to-speech works immediately!
+# Text-to-speech works right away!
 vm.speak("Hello! TTS works out of the box!")
+
+# Language switching with automatic model download
+vm.set_language('fr')
+vm.speak("Bonjour! Le français fonctionne aussi!")
 ```
 
-**That's it!** AbstractVoice v0.4.0+ automatically:
-- ✅ Downloads essential English model (107MB) on first use
-- ✅ Caches models permanently for offline use
-- ✅ Works immediately after first setup
+**That's it!** AbstractVoice v0.5.0+ automatically:
+- ✅ Includes essential TTS dependencies in base installation
+- ✅ Downloads models automatically when switching languages/voices
+- ✅ Works immediately after `pip install abstractvoice`
+- ✅ No silent failures - clear error messages if download fails
 - ✅ No complex configuration needed
 
-### 🌍 Multi-Language Support
+### 🌍 Multi-Language Support (Auto-Download in v0.5.0+)
 
 ```python
-# Download and use French voice
-vm.download_model('fr.css10_vits')  # Downloads automatically
+# Simply switch language - downloads model automatically if needed!
 vm.set_language('fr')
 vm.speak("Bonjour! Je parle français maintenant.")
 
-# Download and use German voice
-vm.download_model('de.thorsten_vits')
+# Switch to German - no manual download needed
 vm.set_language('de')
 vm.speak("Hallo! Ich spreche jetzt Deutsch.")
+
+# Spanish, Italian also supported
+vm.set_language('es')
+vm.speak("¡Hola! Hablo español ahora.")
+
+# If download fails, you'll get clear error messages with instructions
+# Example: "❌ Cannot switch to French: Model download failed"
+#          "   Try: abstractvoice download-models --language fr"
 ```
 
+**New in v0.5.0:** No more manual `download_model()` calls! Language switching handles downloads automatically.
+
 ### 🔧 Check System Status
 
 ```python
@@ -602,6 +615,37 @@ manager.set_tts_model("tts_models/en/ljspeech/glow-tts")
 # - "tts_models/en/ljspeech/glow-tts" (alternative fallback)
 # - "tts_models/en/ljspeech/tacotron2-DDC" (legacy)
 
+# === Audio Lifecycle Callbacks (v0.5.1+) ===
+
+# NEW: Precise audio timing callbacks for visual status indicators
+def on_synthesis_start():
+    print("🔴 Synthesis started - show thinking animation")
+
+def on_audio_start():
+    print("🔵 Audio started - show speaking animation")
+
+def on_audio_pause():
+    print("⏸️ Audio paused - show paused animation")
+
+def on_audio_resume():
+    print("▶️ Audio resumed - continue speaking animation")
+
+def on_audio_end():
+    print("🟢 Audio ended - show ready animation")
+
+def on_synthesis_end():
+    print("✅ Synthesis complete")
+
+# Wire up callbacks
+manager.tts_engine.on_playback_start = on_synthesis_start    # Existing (synthesis phase)
+manager.tts_engine.on_playback_end = on_synthesis_end        # Existing (synthesis phase)
+manager.on_audio_start = on_audio_start                      # NEW (actual audio playback)
+manager.on_audio_end = on_audio_end                          # NEW (actual audio playback)
+manager.on_audio_pause = on_audio_pause                      # NEW (pause events)
+manager.on_audio_resume = on_audio_resume                    # NEW (resume events)
+
+# Perfect for system tray icons, UI animations, or coordinating multiple audio streams
+
 # === STT (Speech-to-Text) ===
 
 def on_transcription(text):
@@ -1371,20 +1415,22 @@ abstractvoice check-deps
 
 ### CLI Voice Commands
 
-In the CLI REPL, use these commands:
+In the CLI REPL, use these commands (v0.5.0+):
 
 ```bash
 # List all available voices with download status
 /setvoice
 
-# Download and set specific voice
-/setvoice fr.css10_vits      # French CSS10 VITS
-/setvoice de.thorsten_vits   # German Thorsten
-/setvoice it.mai_male_vits   # Italian Male
+# Automatically download and set specific voice (NEW in v0.5.0!)
+/setvoice fr.css10_vits      # Downloads French CSS10 if needed
+/setvoice de.thorsten_vits   # Downloads German Thorsten if needed
+/setvoice it.mai_male_vits   # Downloads Italian Male if needed
+/setvoice en.jenny           # Downloads Jenny voice if needed
 
-# Change language
-/language fr
-/language de
+# Change language (automatically downloads models if needed - NEW!)
+/language fr                 # Switches to French, downloads if needed
+/language de                 # Switches to German, downloads if needed
+/language es                 # Switches to Spanish, downloads if needed
 
 # Voice controls
 /pause                       # Pause current speech
@@ -1395,6 +1441,8 @@ In the CLI REPL, use these commands:
 /exit
 ```
 
+**New in v0.5.0:** Language and voice commands now automatically download missing models with progress indicators. No more silent failures!
+
 ## Perspectives
 
 This is a test project that I designed with examples to work with Ollama, but I will adapt the examples and abstractvoice to work with any LLM provider (anthropic, openai, etc).