lollms-client 0.15.1__py3-none-any.whl → 0.16.0__py3-none-any.whl

lollms_client/tts_bindings/piper_tts/__init__.py

@@ -0,0 +1,343 @@
+# lollms_client/tts_bindings/piper/__init__.py
+import io
+import os
+import wave # Standard Python library for WAV files
+import json
+from pathlib import Path
+from typing import Optional, List, Union, Dict, Any
+
+from ascii_colors import trace_exception, ASCIIColors
+
+# --- Package Management and Conditional Imports ---
+_piper_tts_installed = False
+_piper_tts_installation_error = ""
+try:
+    import pipmaster as pm
+    # piper-tts should handle onnxruntime, but ensure it's there if needed
+    # We might need specific onnxruntime for CUDA/DirectML later if we extend device support
+    pm.ensure_packages(["piper-tts", "onnxruntime"])
+
+    from piper import PiperVoice
+    import numpy as np # For converting audio samples if needed
+
+    _piper_tts_installed = True
+except Exception as e:
+    _piper_tts_installation_error = str(e)
+    PiperVoice = None
+    np = None # Piper often returns bytes, but numpy can be handy for sample rate conversion if needed
+# --- End Package Management ---
+
+from lollms_client.lollms_tts_binding import LollmsTTSBinding
+
+BindingName = "PiperTTSBinding"
+
+# Example of a known good voice URL prefix from rhasspy.github.io/piper-voices/
+PIPER_VOICES_BASE_URL = "https://huggingface.co/rhasspy/piper-voices/resolve/main/"
+
+
+class PiperTTSBinding(LollmsTTSBinding):
+    def __init__(self,
+                 default_voice_model_path: Optional[Union[str, Path]] = None, # Path to .onnx file
+                 piper_voices_dir: Optional[Union[str, Path]] = None, # Directory to scan for voices
+                 # Standard LollmsTTSBinding args (host, service_key, verify_ssl are not used for local Piper)
+                 host_address: Optional[str] = None,
+                 service_key: Optional[str] = None,
+                 verify_ssl_certificate: bool = True,
+                 **kwargs): # Catch-all for future params or Piper-specific init options
+
+        super().__init__(binding_name="piper")
+
+        if not _piper_tts_installed:
+            raise ImportError(f"Piper TTS binding dependencies not met. Error: {_piper_tts_installation_error}")
+
+        self.piper_voices_dir = Path(piper_voices_dir).resolve() if piper_voices_dir else None
+        if self.piper_voices_dir and not self.piper_voices_dir.is_dir():
+            ASCIIColors.warning(f"Piper voices directory does not exist: {self.piper_voices_dir}. Voice listing will be limited.")
+            self.piper_voices_dir = None
+
+        self.current_voice_model_path: Optional[Path] = None
+        self.piper_voice: Optional[PiperVoice] = None
+        self.voice_config: Optional[Dict] = None # To store sample rate, channels etc.
+
+        if default_voice_model_path:
+            self._load_piper_voice(default_voice_model_path)
+        else:
+            ASCIIColors.info("No default_voice_model_path provided for Piper. Load a voice via generate_audio or ensure piper_voices_dir is set.")
+
+
+    def _load_piper_voice(self, voice_model_identifier: Union[str, Path]):
+        """
+        Loads a Piper voice model.
+        identifier can be a full path to .onnx or a filename to be found in piper_voices_dir.
+        """
+        voice_model_path_onnx: Optional[Path] = None
+        voice_model_path_json: Optional[Path] = None
+
+        potential_path = Path(voice_model_identifier)
+
+        if potential_path.is_absolute() and potential_path.suffix == ".onnx" and potential_path.exists():
+            voice_model_path_onnx = potential_path
+            voice_model_path_json = potential_path.with_suffix(".onnx.json")
+        elif self.piper_voices_dir and (self.piper_voices_dir / voice_model_identifier).exists():
+            # Assume voice_model_identifier is a filename like "en_US-ryan-medium.onnx"
+            p = self.piper_voices_dir / voice_model_identifier
+            if p.suffix == ".onnx":
+                voice_model_path_onnx = p
+                voice_model_path_json = p.with_suffix(".onnx.json")
+        elif potential_path.suffix == ".onnx" and potential_path.exists(): # Relative path
+             voice_model_path_onnx = potential_path.resolve()
+             voice_model_path_json = voice_model_path_onnx.with_suffix(".onnx.json")
+
+
+        if not voice_model_path_onnx or not voice_model_path_onnx.exists():
+            raise FileNotFoundError(f"Piper ONNX voice model not found: {voice_model_identifier}")
+        if not voice_model_path_json or not voice_model_path_json.exists():
+            raise FileNotFoundError(f"Piper voice JSON config not found for {voice_model_path_onnx} (expected: {voice_model_path_json})")
+
+        if self.piper_voice and self.current_voice_model_path == voice_model_path_onnx:
+            ASCIIColors.info(f"Piper voice '{voice_model_path_onnx.name}' already loaded.")
+            return
+
+        ASCIIColors.info(f"Loading Piper voice: {voice_model_path_onnx.name}...")
+        try:
+            # Piper documentation often shows use_cuda=True for GPU with onnxruntime-gpu.
+            # For simplicity and Piper's primary CPU strength, we'll omit it for now.
+            # onnxruntime will use CPU by default.
+            # To enable GPU: user needs onnxruntime-gpu and then `PiperVoice.from_files(..., use_cuda=True)`
+            self.piper_voice = PiperVoice.from_files(
+                onnx_path=str(voice_model_path_onnx),
+                config_path=str(voice_model_path_json)
+                # use_cuda=True # if onnxruntime-gpu is installed and desired
+            )
+            with open(voice_model_path_json, 'r', encoding='utf-8') as f:
+                self.voice_config = json.load(f)
+
+            self.current_voice_model_path = voice_model_path_onnx
+            ASCIIColors.green(f"Piper voice '{voice_model_path_onnx.name}' loaded successfully.")
+        except Exception as e:
+            self.piper_voice = None
+            self.current_voice_model_path = None
+            self.voice_config = None
+            ASCIIColors.error(f"Failed to load Piper voice '{voice_model_path_onnx.name}': {e}"); trace_exception(e)
+            raise RuntimeError(f"Failed to load Piper voice '{voice_model_path_onnx.name}'") from e
+
+    def generate_audio(self,
+                       text: str,
+                       voice: Optional[Union[str, Path]] = None, # Filename or path to .onnx
+                       **kwargs) -> bytes: # kwargs can include Piper synthesis options
+        if voice:
+            try:
+                self._load_piper_voice(voice) # Attempt to switch voice
+            except Exception as e_load:
+                ASCIIColors.error(f"Failed to switch to Piper voice '{voice}': {e_load}. Using previously loaded voice if available.")
+                if not self.piper_voice: # If no voice was previously loaded either
+                    raise RuntimeError("No Piper voice loaded and failed to switch.") from e_load
+
+        if not self.piper_voice or not self.voice_config:
+            raise RuntimeError("Piper voice model not loaded. Cannot generate audio.")
+
+        ASCIIColors.info(f"Generating speech with Piper voice '{self.current_voice_model_path.name}': '{text[:60]}...'")
+        
+        try:
+            # Piper's synthesize returns raw audio bytes (PCM s16le)
+            # Piper can also stream with synthesize_stream_raw if needed for very long texts
+            # For simplicity, using synthesize which returns all bytes at once.
+            
+            # synthesis_kwargs: length_scale, noise_scale, noise_w
+            piper_synthesis_kwargs = {}
+            if 'length_scale' in kwargs: piper_synthesis_kwargs['length_scale'] = float(kwargs['length_scale'])
+            if 'noise_scale' in kwargs: piper_synthesis_kwargs['noise_scale'] = float(kwargs['noise_scale'])
+            if 'noise_w' in kwargs: piper_synthesis_kwargs['noise_w'] = float(kwargs['noise_w'])
+
+
+            audio_bytes_iterable = self.piper_voice.synthesize_stream_raw(text, **piper_synthesis_kwargs)
+            
+            # Accumulate bytes from the stream
+            pcm_s16le_data = b"".join(audio_bytes_iterable)
+
+            if not pcm_s16le_data:
+                raise RuntimeError("Piper synthesize_stream_raw returned empty audio data.")
+
+            # Now package these raw PCM bytes into a WAV container
+            buffer = io.BytesIO()
+            sample_rate = self.voice_config.get("audio", {}).get("sample_rate", 22050) # Default if not in config
+            num_channels = 1 # Piper voices are typically mono
+            sample_width = 2 # 16-bit audio means 2 bytes per sample
+
+            with wave.open(buffer, 'wb') as wf:
+                wf.setnchannels(num_channels)
+                wf.setsampwidth(sample_width)
+                wf.setframerate(sample_rate)
+                wf.writeframes(pcm_s16le_data)
+            
+            wav_bytes = buffer.getvalue()
+            buffer.close()
+
+            ASCIIColors.green("Piper TTS audio generation successful.")
+            return wav_bytes
+        except Exception as e:
+            ASCIIColors.error(f"Piper TTS audio generation failed: {e}"); trace_exception(e)
+            raise RuntimeError(f"Piper TTS audio generation error: {e}") from e
+
+    def list_voices(self, **kwargs) -> List[str]:
+        """
+        Lists available Piper voice models found in the piper_voices_dir.
+        Returns a list of .onnx filenames.
+        """
+        voices = []
+        if self.piper_voices_dir and self.piper_voices_dir.is_dir():
+            for item in self.piper_voices_dir.iterdir():
+                if item.is_file() and item.suffix == ".onnx":
+                    json_config_path = item.with_suffix(".onnx.json")
+                    if json_config_path.exists():
+                        voices.append(item.name) # Return just the filename
+        
+        if not voices and not self.current_voice_model_path:
+             ASCIIColors.warning("No voices found in piper_voices_dir and no default voice loaded.")
+             ASCIIColors.info(f"Download Piper voices (e.g., from {PIPER_VOICES_BASE_URL} or https://rhasspy.github.io/piper-voices/) "
+                              "and place the .onnx and .onnx.json files into your voices directory.")
+        elif not voices and self.current_voice_model_path:
+            voices.append(self.current_voice_model_path.name) # Add the default loaded one if dir is empty
+
+        return sorted(list(set(voices))) # Ensure unique and sorted
+
+    def __del__(self):
+        # PiperVoice objects don't have an explicit close/del, Python's GC should handle C extensions
+        if hasattr(self, 'piper_voice') and self.piper_voice is not None:
+            del self.piper_voice
+            self.piper_voice = None
+            ASCIIColors.info(f"PiperTTSBinding voice '{getattr(self, 'current_voice_model_path', 'N/A')}' resources released.")
+
+# --- Main Test Block ---
+if __name__ == '__main__':
+    if not _piper_tts_installed:
+        print(f"{ASCIIColors.RED}Piper TTS binding dependencies not met. Skipping tests. Error: {_piper_tts_installation_error}{ASCIIColors.RESET}")
+        exit()
+
+    ASCIIColors.yellow("--- PiperTTSBinding Test ---")
+
+    # --- USER CONFIGURATION FOR TEST ---
+    # 1. Create a directory to store Piper voices, e.g., "./test_piper_voices"
+    TEST_PIPER_VOICES_DIR = Path("./test_piper_voices")
+    TEST_PIPER_VOICES_DIR.mkdir(exist_ok=True)
+
+    # 2. Download at least one voice model (ONNX + JSON files) into that directory.
+    #    From: https://rhasspy.github.io/piper-voices/
+    #    Example: Download en_US-lessac-medium.onnx and en_US-lessac-medium.onnx.json
+    #             and place them in TEST_PIPER_VOICES_DIR
+    #    Or find direct links on Hugging Face: e.g., from https://huggingface.co/rhasspy/piper-voices/tree/main/en/en_US/lessac/medium
+    #    Let's pick a common English voice for testing.
+    DEFAULT_TEST_VOICE_FILENAME = "en_US-lessac-medium.onnx" # Ensure this (and .json) is in TEST_PIPER_VOICES_DIR
+    DEFAULT_TEST_VOICE_ONNX_URL = f"{PIPER_VOICES_BASE_URL}en/en_US/lessac/medium/en_US-lessac-medium.onnx"
+    DEFAULT_TEST_VOICE_JSON_URL = f"{PIPER_VOICES_BASE_URL}en/en_US/lessac/medium/en_US-lessac-medium.onnx.json"
+
+    # Function to download test voice if missing
+    def ensure_test_voice(voices_dir: Path, voice_filename: str, onnx_url: str, json_url: str):
+        onnx_path = voices_dir / voice_filename
+        json_path = voices_dir / f"{voice_filename}.json"
+        if not onnx_path.exists() or not json_path.exists():
+            ASCIIColors.info(f"Test voice '{voice_filename}' not found. Attempting to download...")
+            try:
+                import requests
+                # Download ONNX
+                if not onnx_path.exists():
+                    ASCIIColors.info(f"Downloading {onnx_url} to {onnx_path}")
+                    r_onnx = requests.get(onnx_url, stream=True)
+                    r_onnx.raise_for_status()
+                    with open(onnx_path, 'wb') as f:
+                        for chunk in r_onnx.iter_content(chunk_size=8192): f.write(chunk)
+                # Download JSON
+                if not json_path.exists():
+                    ASCIIColors.info(f"Downloading {json_url} to {json_path}")
+                    r_json = requests.get(json_url)
+                    r_json.raise_for_status()
+                    with open(json_path, 'w', encoding='utf-8') as f: f.write(r_json.text)
+                ASCIIColors.green(f"Test voice '{voice_filename}' downloaded successfully.")
+            except Exception as e_download:
+                ASCIIColors.error(f"Failed to download test voice '{voice_filename}': {e_download}")
+                ASCIIColors.warning(f"Please manually download '{voice_filename}' and '{voice_filename}.json' "
+                                    f"from {PIPER_VOICES_BASE_URL} (or rhasspy.github.io/piper-voices/) "
+                                    f"and place them in {voices_dir.resolve()}")
+                return False
+        return True
+
+    if not ensure_test_voice(TEST_PIPER_VOICES_DIR, DEFAULT_TEST_VOICE_FILENAME, DEFAULT_TEST_VOICE_ONNX_URL, DEFAULT_TEST_VOICE_JSON_URL):
+        ASCIIColors.error("Cannot proceed with test without a default voice model.")
+        exit(1)
+
+    # Optional: Download a second voice for testing voice switching
+    SECOND_TEST_VOICE_FILENAME = "de_DE-thorsten-medium.onnx" # Example German voice
+    SECOND_TEST_VOICE_ONNX_URL = f"{PIPER_VOICES_BASE_URL}de/de_DE/thorsten/medium/de_DE-thorsten-medium.onnx"
+    SECOND_TEST_VOICE_JSON_URL = f"{PIPER_VOICES_BASE_URL}de/de_DE/thorsten/medium/de_DE-thorsten-medium.onnx.json"
+    ensure_test_voice(TEST_PIPER_VOICES_DIR, SECOND_TEST_VOICE_FILENAME, SECOND_TEST_VOICE_ONNX_URL, SECOND_TEST_VOICE_JSON_URL)
+
+
+    test_output_dir = Path("./test_piper_tts_output")
+    test_output_dir.mkdir(exist_ok=True)
+    tts_binding = None
+    # --- END USER CONFIGURATION FOR TEST ---
+
+    try:
+        ASCIIColors.cyan(f"\n--- Initializing PiperTTSBinding ---")
+        # Initialize with the path to the ONNX file for the default voice
+        tts_binding = PiperTTSBinding(
+            default_voice_model_path = TEST_PIPER_VOICES_DIR / DEFAULT_TEST_VOICE_FILENAME,
+            piper_voices_dir = TEST_PIPER_VOICES_DIR
+        )
+
+        ASCIIColors.cyan("\n--- Listing available Piper voices ---")
+        voices = tts_binding.list_voices();
+        if voices: print(f"Available voices in '{TEST_PIPER_VOICES_DIR}': {voices}")
+        else: ASCIIColors.warning(f"No voices found in {TEST_PIPER_VOICES_DIR}. Check paths and ensure .onnx/.json pairs exist.")
+
+
+        texts_to_synthesize = [
+            ("english_hello", "Hello world, this is a test of the Piper text to speech binding."),
+            ("english_question", "Can you generate speech quickly and efficiently? Let's find out!"),
+        ]
+        if (TEST_PIPER_VOICES_DIR / SECOND_TEST_VOICE_FILENAME).exists():
+             texts_to_synthesize.append(
+                 ("german_greeting", "Hallo Welt, wie geht es Ihnen heute?", SECOND_TEST_VOICE_FILENAME)
+             )
+
+
+        for name, text, *voice_file_arg in texts_to_synthesize:
+            voice_to_use_filename = voice_file_arg[0] if voice_file_arg else None # Filename like "en_US-lessac-medium.onnx"
+            
+            ASCIIColors.cyan(f"\n--- Synthesizing TTS for: '{name}' (Voice file: {voice_to_use_filename or DEFAULT_TEST_VOICE_FILENAME}) ---")
+            print(f"Text: {text}")
+            try:
+                # Example of passing Piper-specific synthesis parameters
+                synthesis_kwargs = {"length_scale": 1.0} # Default is 1.0. Smaller is faster, larger is slower.
+                if "question" in name:
+                    synthesis_kwargs["length_scale"] = 0.9 # Slightly faster for questions
+
+                audio_bytes = tts_binding.generate_audio(text, voice=voice_to_use_filename, **synthesis_kwargs)
+                if audio_bytes:
+                    output_filename = f"tts_piper_{name}.wav"
+                    output_path = test_output_dir / output_filename
+                    with open(output_path, "wb") as f: f.write(audio_bytes)
+                    ASCIIColors.green(f"TTS for '{name}' saved to: {output_path} ({len(audio_bytes) / 1024:.2f} KB)")
+                else: ASCIIColors.error(f"TTS generation for '{name}' returned empty bytes.")
+            except Exception as e_gen: ASCIIColors.error(f"Failed to generate TTS for '{name}': {e_gen}")
+
+    except ImportError as e_imp: ASCIIColors.error(f"Import error: {e_imp}")
+    except FileNotFoundError as e_fnf: ASCIIColors.error(f"File not found error during init/load: {e_fnf}")
+    except RuntimeError as e_rt: ASCIIColors.error(f"Runtime error: {e_rt}")
+    except Exception as e: ASCIIColors.error(f"Unexpected error: {e}"); trace_exception(e)
+    finally:
+        if tts_binding: del tts_binding
+        ASCIIColors.info(f"Test TTS audio (if any) are in: {test_output_dir.resolve()}")
+        print(f"{ASCIIColors.YELLOW}Check the audio files in '{test_output_dir.resolve()}'!{ASCIIColors.RESET}")
+        # Optional: Clean up downloaded test voices
+        # if input("Clean up downloaded test voices? (y/N): ").lower() == 'y':
+        #     for f_name in [DEFAULT_TEST_VOICE_FILENAME, SECOND_TEST_VOICE_FILENAME]:
+        #         onnx_p = TEST_PIPER_VOICES_DIR / f_name
+        #         json_p = TEST_PIPER_VOICES_DIR / f"{f_name}.json"
+        #         if onnx_p.exists(): onnx_p.unlink()
+        #         if json_p.exists(): json_p.unlink()
+        #     if not any(TEST_PIPER_VOICES_DIR.iterdir()): TEST_PIPER_VOICES_DIR.rmdir()
+        #     ASCIIColors.info("Cleaned up test voices.")
+
+
+    ASCIIColors.yellow("\n--- PiperTTSBinding Test Finished ---")

lollms_client/tts_bindings/xtts/__init__.py

@@ -0,0 +1,317 @@
+# lollms_client/tts_bindings/xtts/__init__.py
+import io
+import os
+from pathlib import Path
+from typing import Optional, List, Union, Dict, Any
+
+from ascii_colors import trace_exception, ASCIIColors
+
+# --- Package Management and Conditional Imports ---
+_xtts_deps_installed_with_correct_torch = False
+_xtts_installation_error = ""
+try:
+    import pipmaster as pm
+    import platform
+
+    preferred_torch_device_for_install = "cpu"
+    if platform.system() == "Linux" or platform.system() == "Windows":
+        preferred_torch_device_for_install = "cuda"
+    elif platform.system() == "Darwin":
+        preferred_torch_device_for_install = "mps"
+
+    torch_pkgs = ["torch", "torchaudio"] # TTS often needs torchaudio
+    # Coqui-TTS has specific version requirements sometimes, ensure_packages handles this
+    xtts_core_pkgs = ["TTS"]
+    other_deps = ["scipy", "numpy", "soundfile"] # soundfile is often a TTS dependency
+
+    torch_index_url = None
+    if preferred_torch_device_for_install == "cuda":
+        torch_index_url = "https://download.pytorch.org/whl/cu126"
+        ASCIIColors.info(f"Attempting to ensure PyTorch with CUDA support (target index: {torch_index_url}) for XTTS binding.")
+        pm.ensure_packages(torch_pkgs, index_url=torch_index_url)
+        pm.ensure_packages(xtts_core_pkgs + other_deps)
+    else:
+        ASCIIColors.info("Ensuring PyTorch, Coqui-TTS, and dependencies using default PyPI index for XTTS binding.")
+        pm.ensure_packages(torch_pkgs + xtts_core_pkgs + other_deps)
+
+    import torch
+    from TTS.api import TTS # Main Coqui TTS class
+    import scipy.io.wavfile
+    import numpy as np
+    import soundfile as sf # For reading speaker_wav if not in standard wav
+
+    _xtts_deps_installed_with_correct_torch = True
+except ImportError as e_imp: # Catch ImportError specifically if TTS itself fails
+    _xtts_installation_error = f"ImportError: {e_imp}. Coqui TTS (TTS lib) might not be installed correctly or has missing dependencies."
+    TTS, torch, scipy, np, sf = None, None, None, None, None
+except Exception as e:
+    _xtts_installation_error = str(e)
+    TTS, torch, scipy, np, sf = None, None, None, None, None
+# --- End Package Management ---
+
+from lollms_client.lollms_tts_binding import LollmsTTSBinding
+
+BindingName = "XTTSBinding"
+
+# Common XTTS model IDs from Coqui on Hugging Face
+# The primary one is usually "coqui/XTTS-v2" or similar official releases.
+# Users might also point to fine-tuned versions or local paths.
+XTTS_MODELS = [
+    "tts_models/multilingual/multi-dataset/xtts_v2", # Standard XTTS v2 model string for Coqui TTS lib
+    # "coqui/XTTS-v2" # This is the HF repo ID, TTS lib might map it or expect the above format
+]
+
+# Supported languages by XTTS v2 (example, check latest Coqui docs)
+XTTS_SUPPORTED_LANGUAGES = [
+    "en", "es", "fr", "de", "it", "pt", "pl", "tr", "ru", "nl", "cs", "ar", "zh-cn", "ja", "hu", "ko", "hi"
+]
+
+class XTTSBinding(LollmsTTSBinding):
+    def __init__(self,
+                 model_name: str = "tts_models/multilingual/multi-dataset/xtts_v2", # Coqui TTS model identifier
+                 default_speaker_wav: Optional[Union[str, Path]] = None, # Path to a reference WAV for default voice
+                 default_language: str = "en",
+                 device: Optional[str] = None,
+                 # Standard LollmsTTSBinding args
+                 host_address: Optional[str] = None,
+                 service_key: Optional[str] = None,
+                 verify_ssl_certificate: bool = True,
+                 **kwargs): # Catch-all for future TTS API changes or specific params
+
+        super().__init__(binding_name="xtts")
+
+        if not _xtts_deps_installed_with_correct_torch:
+            raise ImportError(f"XTTS binding dependencies not met. Error: {_xtts_installation_error}")
+
+        self.device = device
+        if self.device is None:
+            if torch.cuda.is_available(): self.device = "cuda"; ASCIIColors.info("CUDA device detected by PyTorch for XTTS.")
+            elif hasattr(torch.backends, 'mps') and torch.backends.mps.is_available(): self.device = "mps"; ASCIIColors.info("MPS device detected for XTTS.")
+            else: self.device = "cpu"; ASCIIColors.info("No GPU (CUDA/MPS) by PyTorch, using CPU for XTTS.")
+        elif self.device == "cuda" and not torch.cuda.is_available(): self.device = "cpu"; ASCIIColors.warning("CUDA req, not avail. CPU for XTTS.")
+        elif self.device == "mps" and not (hasattr(torch.backends, 'mps') and torch.backends.mps.is_available()): self.device = "cpu"; ASCIIColors.warning("MPS req, not avail. CPU for XTTS.")
+
+        ASCIIColors.info(f"XTTSBinding: Using device '{self.device}'.")
+
+        self.xtts_model_id_or_path = model_name # Store the model identifier passed by user
+        self.loaded_xtts_model_id = None
+        self.tts_model: Optional[TTS] = None
+        self.default_speaker_wav = str(default_speaker_wav) if default_speaker_wav else None
+        self.default_language = default_language
+        
+        if self.default_speaker_wav and not Path(self.default_speaker_wav).exists():
+            ASCIIColors.warning(f"Default speaker WAV not found: {self.default_speaker_wav}. Voice cloning will require a speaker_wav per call.")
+            self.default_speaker_wav = None # Invalidate if not found
+
+        self._load_xtts_model(self.xtts_model_id_or_path)
+
+    def _load_xtts_model(self, model_id_to_load: str):
+        if self.tts_model is not None and self.loaded_xtts_model_id == model_id_to_load:
+            ASCIIColors.info(f"XTTS model '{model_id_to_load}' already loaded.")
+            return
+
+        ASCIIColors.info(f"Loading XTTS model: '{model_id_to_load}' on device '{self.device}'...")
+        try:
+            # TTS class handles model downloading from Hugging Face or loading from local path.
+            # It also manages moving to the specified device.
+            self.tts_model = TTS(model_name=model_id_to_load, progress_bar=True).to(self.device)
+            self.loaded_xtts_model_id = model_id_to_load
+            ASCIIColors.green(f"XTTS model '{model_id_to_load}' loaded successfully.")
+        except Exception as e:
+            self.tts_model = None; self.loaded_xtts_model_id = None
+            ASCIIColors.error(f"Failed to load XTTS model '{model_id_to_load}': {e}"); trace_exception(e)
+            raise RuntimeError(f"Failed to load XTTS model '{model_id_to_load}'") from e
+
+    def generate_audio(self,
+                       text: str,
+                       voice: Optional[Union[str, Path]] = None, # Path to speaker WAV for XTTS
+                       language: Optional[str] = None,
+                       # XTTS specific parameters (can be passed via kwargs)
+                       # speed: float = 1.0, # Not directly in XTTS v2 tts() method's main signature
+                       **kwargs) -> bytes:
+        if self.tts_model is None:
+            raise RuntimeError("XTTS model not loaded.")
+
+        speaker_wav_path = voice if voice is not None else self.default_speaker_wav
+        effective_language = language if language is not None else self.default_language
+
+        if not speaker_wav_path:
+            raise ValueError("XTTS requires a 'speaker_wav' path for voice cloning. Provide it in the 'voice' argument or set 'default_speaker_wav' during initialization.")
+        
+        speaker_wav_p = Path(speaker_wav_path)
+        if not speaker_wav_p.exists():
+            raise FileNotFoundError(f"Speaker WAV file not found: {speaker_wav_path}")
+        
+        if effective_language not in XTTS_SUPPORTED_LANGUAGES:
+            ASCIIColors.warning(f"Language '{effective_language}' might not be officially supported by XTTS v2. "
+                                f"Known supported: {XTTS_SUPPORTED_LANGUAGES}. Attempting anyway.")
+
+        ASCIIColors.info(f"Generating speech with XTTS: '{text[:60]}...' (Speaker: {speaker_wav_p.name}, Lang: {effective_language})")
+        
+        try:
+            # The tts() method returns a NumPy array (waveform)
+            # It expects speaker_wav and language as direct arguments.
+            # Other TTS generation parameters might be available via model's config or specific methods.
+            # For XTTS, common ones like speed are handled internally or via config.
+            # We can pass other kwargs if the TTS library might pick them up for specific models.
+            
+            # XTTS's tts() returns list of ints (scaled PCM), not float numpy array directly
+            wav_array_int_list = self.tts_model.tts(
+                text=text,
+                speaker_wav=str(speaker_wav_path), # Must be a string path
+                language=effective_language,
+                # split_sentences=True, # Default True, good for longer texts
+                **kwargs # Pass other potential TTS lib args
+            )
+
+            if not wav_array_int_list: # Check if list is empty
+                raise RuntimeError("XTTS model returned empty audio data (list of ints was empty).")
+
+            # Convert list of ints to a NumPy array of int16
+            # The TTS library usually returns samples scaled appropriately for int16.
+            audio_array_np = np.array(wav_array_int_list, dtype=np.int16)
+
+
+            if audio_array_np.ndim == 0 or audio_array_np.size == 0: # Double check after conversion
+                raise RuntimeError("XTTS model resulted in empty NumPy audio array.")
+
+
+            buffer = io.BytesIO()
+            # Get sample rate from the loaded TTS model's config
+            sample_rate = self.tts_model.synthesizer.output_sample_rate if hasattr(self.tts_model, 'synthesizer') and hasattr(self.tts_model.synthesizer, 'output_sample_rate') else 24000 # XTTS v2 default is 24kHz
+            
+            scipy.io.wavfile.write(buffer, rate=sample_rate, data=audio_array_np)
+            audio_bytes = buffer.getvalue()
+            buffer.close()
+
+            ASCIIColors.green("XTTS audio generation successful.")
+            return audio_bytes
+        except Exception as e:
+            ASCIIColors.error(f"XTTS audio generation failed: {e}"); trace_exception(e)
+            if "out of memory" in str(e).lower() and self.device == "cuda":
+                 ASCIIColors.yellow("CUDA out of memory. Ensure GPU has sufficient VRAM for XTTS (can be several GB).")
+            raise RuntimeError(f"XTTS audio generation error: {e}") from e
+
+    def list_voices(self, **kwargs) -> List[str]:
+        """
+        For XTTS, voices are determined by the `speaker_wav` file.
+        This method returns a message or an empty list, as there are no predefined voices.
+        Optionally, one could implement scanning a user-defined directory of speaker WAVs.
+        """
+        # return ["Dynamic (provide 'speaker_wav' path to generate_audio)"]
+        ASCIIColors.info("XTTS voices are dynamic and determined by the 'speaker_wav' file provided during generation.")
+        ASCIIColors.info("You can provide a path to any reference WAV file for voice cloning.")
+        return [] # Or provide a helper message as above in a different way
+
+    def get_xtts_model_ids(self) -> List[str]:
+        """Helper to list known XTTS model identifiers for Coqui TTS library."""
+        return XTTS_MODELS.copy()
+    
+    def get_supported_languages(self) -> List[str]:
+        """Helper to list known supported languages for XTTS v2."""
+        return XTTS_SUPPORTED_LANGUAGES.copy()
+
+
+    def __del__(self):
+        if hasattr(self, 'tts_model') and self.tts_model is not None:
+            del self.tts_model; self.tts_model = None
+            if torch and hasattr(torch, 'cuda') and torch.cuda.is_available():
+                torch.cuda.empty_cache()
+            loaded_name = getattr(self, 'loaded_xtts_model_id', None)
+            msg = f"XTTSBinding for model '{loaded_name}' destroyed." if loaded_name else "XTTSBinding destroyed."
+            ASCIIColors.info(msg)
+
+# --- Main Test Block ---
+if __name__ == '__main__':
+    if not _xtts_deps_installed_with_correct_torch:
+        print(f"{ASCIIColors.RED}XTTS binding dependencies not met. Skipping tests. Error: {_xtts_installation_error}{ASCIIColors.RESET}")
+        exit()
+
+    ASCIIColors.yellow("--- XTTSBinding Test ---")
+    # For XTTS, model_name is the Coqui TTS model string or HF repo ID if supported by TTS lib directly
+    test_xtts_model_id = "tts_models/multilingual/multi-dataset/xtts_v2"
+    test_output_dir = Path("./test_xtts_output")
+    test_output_dir.mkdir(exist_ok=True)
+    
+    # --- IMPORTANT: Create or provide a speaker reference WAV file ---
+    # For this test to work, you need a short (~5-15 seconds) clean audio file of a voice.
+    # Name it 'speaker_ref.wav' and place it in the same directory as this script,
+    # or update the path below.
+    default_speaker_wav_path = Path(__file__).parent / "speaker_ref.wav" # Assumes it's next to this __init__.py
+
+    if not default_speaker_wav_path.exists():
+        ASCIIColors.warning(f"Reference speaker WAV file not found: {default_speaker_wav_path}")
+        ASCIIColors.warning("Please create/place a 'speaker_ref.wav' (clean, ~5-15s audio) in the "
+                            f"'{default_speaker_wav_path.parent}' directory for the test to run properly.")
+        # Attempt to create a very basic dummy if scipy available, NOT suitable for good cloning
+        try:
+            import numpy as np; import scipy.io.wavfile
+            samplerate = 22050; duration = 2; frequency = 440
+            t = np.linspace(0., duration, int(samplerate * duration), endpoint=False)
+            data = (np.iinfo(np.int16).max * 0.1 * np.sin(2. * np.pi * frequency * t)).astype(np.int16)
+            scipy.io.wavfile.write(default_speaker_wav_path, samplerate, data)
+            ASCIIColors.info(f"Created a VERY BASIC dummy 'speaker_ref.wav'. Replace with a real voice sample for good results.")
+        except Exception as e_dummy_spk:
+            ASCIIColors.error(f"Could not create dummy speaker_ref.wav: {e_dummy_spk}. Test will likely fail or use no speaker.")
+            default_speaker_wav_path = None # Ensure it's None if creation failed
+
+    tts_binding = None
+    try:
+        ASCIIColors.cyan(f"\n--- Initializing XTTSBinding (XTTS Model: '{test_xtts_model_id}') ---")
+        tts_binding = XTTSBinding(
+            model_name=test_xtts_model_id,
+            default_speaker_wav=str(default_speaker_wav_path) if default_speaker_wav_path else None,
+            default_language="en"
+        )
+
+        ASCIIColors.cyan("\n--- Listing XTTS 'voices' (dynamic, requires speaker_wav) ---")
+        voices = tts_binding.list_voices(); # This will print an informational message
+        
+        ASCIIColors.cyan("\n--- Listing known XTTS model IDs for Coqui TTS library ---")
+        xtts_models = tts_binding.get_xtts_model_ids(); print(f"Known XTTS model IDs: {xtts_models}")
+        ASCIIColors.cyan("\n--- Listing known XTTS supported languages ---")
+        langs = tts_binding.get_supported_languages(); print(f"Supported languages (example): {langs[:5]}...")
+
+
+        texts_to_synthesize = [
+            ("english_greeting", "Hello, this is a test of the XTTS voice synthesis system. I hope you like my voice!", "en"),
+            ("spanish_question", "¿Cómo estás hoy? Espero que tengas un día maravilloso.", "es"),
+            # ("short_custom_voice", "This voice should sound like your reference audio.", "en", "path/to/your/custom_speaker.wav"), # Example for custom
+        ]
+        if not default_speaker_wav_path: # If no default speaker, we can't run text loop as is
+            ASCIIColors.error("No default_speaker_wav available. Skipping synthesis loop.")
+            texts_to_synthesize = []
+
+
+        for name, text, lang, *speaker_override_list in texts_to_synthesize:
+            speaker_to_use = speaker_override_list[0] if speaker_override_list else None # Uses binding default if None
+            
+            ASCIIColors.cyan(f"\n--- Synthesizing TTS for: '{name}' (Lang: {lang}, Speaker: {speaker_to_use or tts_binding.default_speaker_wav}) ---")
+            print(f"Text: {text}")
+            try:
+                # XTTS tts() doesn't have as many direct generation params as Bark's generate()
+                # Control is more via the model config or specific methods if available.
+                audio_bytes = tts_binding.generate_audio(text, voice=speaker_to_use, language=lang)
+                if audio_bytes:
+                    output_filename = f"tts_{name}_{tts_binding.loaded_xtts_model_id.replace('/','_')}.wav"
+                    output_path = test_output_dir / output_filename
+                    with open(output_path, "wb") as f: f.write(audio_bytes)
+                    ASCIIColors.green(f"TTS for '{name}' saved to: {output_path} ({len(audio_bytes) / 1024:.2f} KB)")
+                else: ASCIIColors.error(f"TTS generation for '{name}' returned empty bytes.")
+            except Exception as e_gen: ASCIIColors.error(f"Failed to generate TTS for '{name}': {e_gen}")
+
+    except ImportError as e_imp: ASCIIColors.error(f"Import error: {e_imp}")
+    except RuntimeError as e_rt: ASCIIColors.error(f"Runtime error: {e_rt}")
+    except Exception as e: ASCIIColors.error(f"Unexpected error: {e}"); trace_exception(e)
+    finally:
+        if tts_binding: del tts_binding
+        ASCIIColors.info(f"Test TTS audio (if any) are in: {test_output_dir.resolve()}")
+        print(f"{ASCIIColors.YELLOW}Check the audio files in '{test_output_dir.resolve()}'!{ASCIIColors.RESET}")
+        # Clean up dummy speaker_ref.wav if we created it
+        if "samplerate" in locals() and default_speaker_wav_path and default_speaker_wav_path.name == "speaker_ref.wav" and "dummy" in str(default_speaker_wav_path).lower():
+            if default_speaker_wav_path.exists():
+                try: default_speaker_wav_path.unlink(); ASCIIColors.info("Removed dummy speaker_ref.wav")
+                except: pass
+
+
+    ASCIIColors.yellow("\n--- XTTSBinding Test Finished ---")