openvoiceui 1.0.0

package/tts_providers/__init__.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""
+TTS Providers Package.
+
+This package provides a unified interface for multiple Text-to-Speech backends.
+All providers inherit from TTSProvider base class and implement the same API.
+
+Available Providers:
+    - HumeProvider: Hume EVI WebSocket TTS (INACTIVE - placeholder only)
+    - SupertonicProvider: Local ONNX-based TTS (active, recommended)
+
+Usage:
+    >>> from tts_providers import get_provider, list_providers
+    >>> # Get default provider (Supertonic)
+    >>> provider = get_provider()
+    >>> audio = provider.generate_speech("Hello world", voice='M1')
+    >>>
+    >>> # List all providers
+    >>> providers = list_providers()
+
+Author: OpenVoiceUI
+Date: 2026-02-11
+"""
+
+import json
+import os
+from typing import Optional, Dict, Any, List
+
+from .base_provider import TTSProvider
+from .hume_provider import HumeProvider
+from .supertonic_provider import SupertonicProvider
+from .groq_provider import GroqProvider
+from .qwen3_provider import Qwen3Provider
+from .resemble_provider import ResembleProvider
+
+# Provider registry
+_PROVIDERS = {
+    'hume': HumeProvider,
+    'supertonic': SupertonicProvider,
+    'groq': GroqProvider,
+    'qwen3': Qwen3Provider,
+    'resemble': ResembleProvider,
+}
+
+def _load_config() -> Dict[str, Any]:
+    """Load providers configuration from JSON file."""
+    config_path = os.path.join(os.path.dirname(__file__), 'providers_config.json')
+    try:
+        with open(config_path, 'r') as f:
+            return json.load(f)
+    except FileNotFoundError:
+        return {'providers': {}, 'default_provider': 'supertonic'}
+
+def get_provider(provider_id: Optional[str] = None) -> TTSProvider:
+    """
+    Get a TTS provider instance.
+
+    Args:
+        provider_id: Provider identifier ('hume', 'supertonic'). If None, uses default.
+
+    Returns:
+        TTSProvider instance
+
+    Raises:
+        ValueError: If provider_id is unknown
+
+    Example:
+        >>> provider = get_provider('supertonic')
+        >>> audio = provider.generate_speech("Hello", voice='M1')
+    """
+    config = _load_config()
+    if provider_id is None:
+        provider_id = config.get('default_provider', 'supertonic')
+
+    if provider_id not in _PROVIDERS:
+        available = ', '.join(_PROVIDERS.keys())
+        raise ValueError(f"Unknown provider '{provider_id}'. Available: {available}")
+
+    return _PROVIDERS[provider_id]()
+
+def list_providers(include_inactive: bool = True) -> List[Dict[str, Any]]:
+    """
+    List all TTS providers with metadata.
+
+    Args:
+        include_inactive: If True, include inactive providers. Default True.
+
+    Returns:
+        List of provider metadata dictionaries
+
+    Example:
+        >>> for p in list_providers():
+        ...     print(f"{p['name']}: ${p['cost_per_minute']}/min")
+    """
+    config = _load_config()
+    providers = []
+
+    for provider_id, provider_class in _PROVIDERS.items():
+        try:
+            instance = provider_class()
+            info = instance.get_info()
+
+            # Merge with config metadata
+            if provider_id in config.get('providers', {}):
+                config_data = config['providers'][provider_id]
+                info.update({
+                    'provider_id': provider_id,
+                    'cost_per_minute': config_data.get('cost_per_minute', 0.0),
+                    'quality': config_data.get('quality', 'unknown'),
+                    'latency': config_data.get('latency', 'unknown'),
+                    'features': config_data.get('features', []),
+                    'requires_api_key': config_data.get('requires_api_key', False),
+                    'languages': config_data.get('languages', []),
+                    'notes': config_data.get('notes', ''),
+                })
+
+            # Filter inactive if requested
+            if not include_inactive and info.get('status') != 'active':
+                continue
+
+            providers.append(info)
+        except Exception as e:
+            print(f"Warning: Failed to load provider {provider_id}: {e}")
+
+    return providers
+
+__all__ = [
+    'TTSProvider',
+    'HumeProvider',
+    'SupertonicProvider',
+    'GroqProvider',
+    'Qwen3Provider',
+    'ResembleProvider',
+    'get_provider',
+    'list_providers',
+]

package/tts_providers/base_provider.py

@@ -0,0 +1,319 @@
+#!/usr/bin/env python3
+"""
+Base TTS Provider Abstract Class for OpenVoiceUI.
+
+This module defines the abstract interface that all TTS providers must implement.
+It provides a consistent API for generating speech, listing available voices,
+and retrieving provider information.
+
+Author: OpenVoiceUI
+Date: 2026-02-11
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class TTSVoice:
+    """
+    Represents a single voice available from a TTS provider.
+
+    Attributes:
+        id: Unique identifier for the voice (e.g., 'M1', 'your-hume-voice-id')
+        name: Human-readable name (e.g., 'Male Voice 1', 'Custom Voice')
+        language: Language code (e.g., 'en-US', 'en', 'es')
+        gender: Gender of the voice ('male', 'female', 'neutral', or None)
+        description: Optional description of the voice characteristics
+    """
+    id: str
+    name: str
+    language: str = 'en'
+    gender: Optional[str] = None
+    description: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert the voice to a dictionary representation."""
+        return {
+            'id': self.id,
+            'name': self.name,
+            'language': self.language,
+            'gender': self.gender,
+            'description': self.description
+        }
+
+
+@dataclass
+class TTSProviderInfo:
+    """
+    Metadata about a TTS provider.
+
+    Attributes:
+        name: Provider name (e.g., 'supertonic', 'hume')
+        display_name: Human-readable name (e.g., 'Supertonic TTS', 'Hume EVI')
+        version: Provider version string
+        cost_per_minute: Cost in USD per minute of generated audio
+        quality: Quality rating ('low', 'medium', 'high', 'premium')
+        latency: Expected latency ('instant', 'fast', 'medium', 'slow')
+        features: List of feature strings (e.g., ['emotion-aware', 'multi-language'])
+        requires_api_key: Whether the provider requires an API key
+        is_online: Whether the provider requires internet connectivity
+        status: Current status ('active', 'inactive', 'error')
+    """
+    name: str
+    display_name: str
+    version: str
+    cost_per_minute: float
+    quality: str
+    latency: str
+    features: List[str]
+    requires_api_key: bool
+    is_online: bool
+    status: str = 'active'
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert the provider info to a dictionary representation."""
+        return {
+            'name': self.name,
+            'display_name': self.display_name,
+            'version': self.version,
+            'cost_per_minute': self.cost_per_minute,
+            'quality': self.quality,
+            'latency': self.latency,
+            'features': self.features,
+            'requires_api_key': self.requires_api_key,
+            'is_online': self.is_online,
+            'status': self.status
+        }
+
+
+class TTSProvider(ABC):
+    """
+    Abstract base class for Text-to-Speech providers.
+
+    All TTS providers must inherit from this class and implement the required methods.
+    This ensures a consistent interface across different TTS backends.
+
+    Required Methods:
+        - generate_speech(text, **kwargs): Convert text to audio bytes
+        - list_voices(): Return list of available voice names
+        - get_info(): Return provider metadata (name, status, capabilities)
+
+    Example:
+        >>> class MyTTS(TTSProvider):
+        ...     def generate_speech(self, text, **kwargs):
+        ...         # Implementation here
+        ...         return audio_bytes
+        ...     def list_voices(self):
+        ...         return ['voice1', 'voice2']
+        ...     def get_info(self):
+        ...         return {'name': 'MyTTS', 'status': 'active'}
+    """
+
+    @abstractmethod
+    def generate_speech(self, text: str, **kwargs) -> bytes:
+        """
+        Generate speech audio from the given text.
+
+        Args:
+            text: The text to synthesize into speech.
+            **kwargs: Provider-specific parameters (voice, speed, lang, etc.)
+
+        Returns:
+            bytes: Raw audio data (usually WAV format) that can be written
+                   to a file or sent via HTTP with Content-Type: audio/wav.
+
+        Raises:
+            ValueError: If text is empty or parameters are invalid.
+            RuntimeError: If speech generation fails.
+
+        Example:
+            >>> audio = provider.generate_speech("Hello world", voice='M1')
+            >>> with open('output.wav', 'wb') as f:
+            ...     f.write(audio)
+        """
+        pass
+
+    @abstractmethod
+    def list_voices(self) -> List[str]:
+        """
+        Return a list of available voice names for this provider.
+
+        Returns:
+            List[str]: List of voice identifiers (e.g., ['M1', 'M2', 'F1']).
+                       These IDs should be valid values for a 'voice' parameter
+                       in generate_speech().
+
+        Example:
+            >>> provider.list_voices()
+            ['M1', 'M2', 'F1', 'F2']
+        """
+        pass
+
+    @abstractmethod
+    def get_info(self) -> Dict[str, Any]:
+        """
+        Return metadata about this TTS provider.
+
+        Returns:
+            Dict with at minimum:
+                - 'name': str - Provider display name
+                - 'status': str - 'active', 'inactive', or 'error'
+                - 'description': str - Brief description of the provider
+                - 'capabilities': dict - Optional feature flags
+                    - 'streaming': bool - Supports streaming audio
+                    - 'ssml': bool - Supports SSML markup
+                    - 'custom_voices': bool - Supports custom voice cloning
+                    - 'languages': List[str] - Supported language codes
+
+        Example:
+            >>> provider.get_info()
+            {
+                'name': 'Supertonic',
+                'status': 'active',
+                'description': 'Local ONNX-based TTS engine',
+                'capabilities': {
+                    'streaming': False,
+                    'ssml': False,
+                    'custom_voices': True,
+                    'languages': ['en', 'ko', 'es', 'pt', 'fr']
+                }
+            }
+        """
+        pass
+
+    def is_available(self) -> bool:
+        """
+        Check if this provider is currently available for use.
+
+        Returns:
+            bool: True if the provider is active and ready, False otherwise.
+
+        Default implementation checks if get_info()['status'] == 'active'.
+        Subclasses can override for more complex availability checks.
+
+        Example:
+            >>> if provider.is_available():
+            ...     audio = provider.generate_speech("Hello")
+        """
+        return self.get_info().get('status', 'inactive') == 'active'
+
+    def validate_text(self, text: str) -> None:
+        """
+        Validate that text is suitable for speech generation.
+
+        Args:
+            text: Text to validate.
+
+        Raises:
+            ValueError: If text is None, empty, or only whitespace.
+
+        Example:
+            >>> provider.validate_text("Hello world")  # OK
+            >>> provider.validate_text("")  # Raises ValueError
+        """
+        if text is None:
+            raise ValueError("Text cannot be None")
+        if not isinstance(text, str):
+            raise ValueError(f"Text must be a string, got {type(text).__name__}")
+        if not text.strip():
+            raise ValueError("Text cannot be empty or contain only whitespace")
+
+    def validate_voice(self, voice: str) -> bool:
+        """
+        Check if a given voice name is valid for this provider.
+
+        Args:
+            voice: Voice identifier to validate.
+
+        Returns:
+            bool: True if the voice is available, False otherwise.
+
+        Example:
+            >>> provider.validate_voice('M1')
+            True
+            >>> provider.validate_voice('invalid')
+            False
+        """
+        return voice in self.list_voices()
+
+    def get_default_voice(self) -> Optional[str]:
+        """
+        Return the default voice for this provider.
+
+        Returns:
+            The first voice in list_voices(), or None if no voices available.
+
+        Example:
+            >>> provider.get_default_voice()
+            'M1'
+        """
+        voices = self.list_voices()
+        return voices[0] if voices else None
+
+    def __repr__(self) -> str:
+        """String representation of the provider."""
+        info = self.get_info()
+        return f"{self.__class__.__name__}(name='{info.get('name', 'Unknown')}', status='{info.get('status', 'unknown')}')"
+
+
+class TTSProviderError(Exception):
+    """
+    Base exception class for TTS provider errors.
+
+    This exception is raised when a TTS provider encounters an error
+    that is specific to the provider implementation.
+    """
+
+    def __init__(self, provider_name: str, message: str):
+        """
+        Initialize the exception.
+
+        Args:
+            provider_name: Name of the provider that raised the error.
+            message: Error message describing what went wrong.
+        """
+        self.provider_name = provider_name
+        super().__init__(f"[{provider_name}] {message}")
+
+
+class TTSGenerationError(TTSProviderError):
+    """
+    Raised when speech generation fails.
+
+    This can occur due to invalid input, network issues, or
+    problems with the TTS service.
+    """
+    pass
+
+
+class TTSConfigurationError(TTSProviderError):
+    """
+    Raised when the provider is misconfigured.
+
+    This can occur due to missing API keys, invalid paths,
+    or other configuration issues.
+    """
+    pass
+
+
+class TTSVoiceNotFoundError(TTSProviderError):
+    """
+    Raised when a requested voice is not available.
+
+    This occurs when a voice ID is specified that doesn't
+    exist in the provider's voice catalog.
+    """
+    pass
+
+
+__all__ = [
+    'TTSProvider',
+    'TTSVoice',
+    'TTSProviderInfo',
+    'TTSProviderError',
+    'TTSGenerationError',
+    'TTSConfigurationError',
+    'TTSVoiceNotFoundError',
+]

package/tts_providers/groq_provider.py

@@ -0,0 +1,155 @@
+"""
+Groq Orpheus TTS Provider — canopylabs/orpheus-v1-english via Groq LPU.
+
+~130-200ms TTFB, natural human-like prosody, MP3 output.
+API key: GROQ_API_KEY env var
+"""
+
+import os
+import time
+import logging
+
+from .base_provider import TTSProvider
+
+logger = logging.getLogger(__name__)
+
+MODEL = "canopylabs/orpheus-v1-english"
+# If a single TTS call exceeds this, abort and let fallback handle it.
+# Normal Groq latency is 130-700ms. Rate-limited calls take 12-27s.
+GROQ_TTS_TIMEOUT_SECONDS = 5.0
+
+AVAILABLE_VOICES = [
+    "autumn",  # Female (default)
+    "diana",   # Female
+    "hannah",  # Female
+    "austin",  # Male
+    "daniel",  # Male
+    "troy",    # Male
+]
+
+
+class GroqProvider(TTSProvider):
+    """
+    TTS Provider using Groq Orpheus (canopylabs/orpheus-v1-english).
+
+    Voices: autumn, diana, hannah, austin, daniel, troy
+    Output: WAV audio bytes
+    Latency: ~130-200ms (Groq LPU)
+    Cost: ~$0.05/1K chars
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.api_key = os.getenv('GROQ_API_KEY', '')
+        self._status = 'active' if self.api_key else 'error'
+        self._init_error = None if self.api_key else 'GROQ_API_KEY not set'
+        self._client = None
+
+    def _get_client(self):
+        if self._client is None:
+            try:
+                from groq import Groq
+                self._client = Groq(
+                    api_key=self.api_key,
+                    timeout=GROQ_TTS_TIMEOUT_SECONDS,
+                )
+            except ImportError:
+                raise RuntimeError("groq package not installed — run: pip install groq")
+        return self._client
+
+    def generate_speech(self, text: str, voice: str = 'autumn', **kwargs) -> bytes:
+        """
+        Generate speech via Groq Orpheus.
+
+        Args:
+            text: Text to synthesize.
+            voice: One of AVAILABLE_VOICES. Default: 'autumn'.
+
+        Returns:
+            MP3 audio bytes.
+        """
+        if not self.api_key:
+            raise RuntimeError("GROQ_API_KEY not set")
+
+        self.validate_text(text)
+
+        if voice not in AVAILABLE_VOICES:
+            logger.warning(f"[Groq] Unknown voice '{voice}', using autumn")
+            voice = 'autumn'
+
+        t = time.time()
+        logger.info(f"[Groq] Requesting TTS: '{text[:60]}' voice={voice}")
+
+        try:
+            client = self._get_client()
+            resp = client.audio.speech.create(
+                model=MODEL,
+                voice=voice,
+                input=text,
+                response_format="wav",
+            )
+            audio_bytes = resp.content if hasattr(resp, 'content') else resp.read()
+        except Exception as e:
+            # Parse structured Groq API errors to extract error code
+            import re
+            err_str = str(e)
+            err_code = 'unknown'
+            err_msg = err_str
+            try:
+                code_match = re.search(r"'code':\s*'([^']+)'", err_str)
+                msg_match = re.search(r"'message':\s*'([^']+)'", err_str)
+                if code_match:
+                    err_code = code_match.group(1)
+                if msg_match:
+                    err_msg = msg_match.group(1)
+            except Exception:
+                pass
+            raise RuntimeError(f"[groq:{err_code}] {err_msg}")
+
+        elapsed = int((time.time() - t) * 1000)
+        logger.info(f"[Groq] Generated {len(audio_bytes)} bytes in {elapsed}ms")
+        return audio_bytes
+
+    def health_check(self) -> dict:
+        if not self.api_key:
+            return {"ok": False, "latency_ms": 0, "detail": "GROQ_API_KEY not set"}
+        t = time.time()
+        try:
+            from groq import Groq
+            client = Groq(api_key=self.api_key)
+            client.models.list()
+            latency_ms = int((time.time() - t) * 1000)
+            return {"ok": True, "latency_ms": latency_ms, "detail": "Groq reachable — Orpheus ready"}
+        except Exception as e:
+            latency_ms = int((time.time() - t) * 1000)
+            return {"ok": False, "latency_ms": latency_ms, "detail": str(e)}
+
+    def list_voices(self) -> list:
+        return AVAILABLE_VOICES.copy()
+
+    def get_default_voice(self) -> str:
+        return 'autumn'
+
+    def is_available(self) -> bool:
+        return bool(self.api_key)
+
+    def get_info(self) -> dict:
+        return {
+            'name': 'Groq Orpheus',
+            'provider_id': 'groq',
+            'status': self._status,
+            'description': 'Orpheus TTS via Groq LPU — fast, natural, human-like prosody',
+            'quality': 'high',
+            'latency': 'very-fast',
+            'cost_per_minute': 0.05,
+            'voices': AVAILABLE_VOICES.copy(),
+            'features': ['fast', 'natural', 'empathetic', 'mp3-output', 'cloud'],
+            'requires_api_key': True,
+            'languages': ['en'],
+            'max_characters': 5000,
+            'notes': 'Orpheus v1 English on Groq LPU. ~130-200ms latency. GROQ_API_KEY required.',
+            'default_voice': 'autumn',
+            'audio_format': 'wav',
+            'sample_rate': 24000,
+            'error': self._init_error,
+        }