openvoiceui 1.0.0

package/tts_providers/hume_provider.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""
+Hume EVI TTS Provider (Placeholder/Stub).
+
+This module is a STUB/PLACEHOLDER for future Hume EVI Text-to-Speech integration.
+It is currently INACTIVE due to API costs - use Supertonic instead.
+
+When implemented, this provider would use Hume's EVI WebSocket API to generate
+speech using a custom cloned voice (bdcf156c-6678-4720-9f91-46bf8063bd7f).
+
+IMPORTANT: This is NOT IMPLEMENTED. All methods will raise NotImplementedError
+or return placeholder data. Use SupertonicTTS for actual TTS functionality.
+
+Author: OpenVoiceUI
+Date: 2026-02-11
+
+Status: INACTIVE - No API funds available
+
+Future Implementation Reference:
+    https://dev.hume.ai/docs/speech-to-speech-evi/overview
+    https://dev.hume.ai/docs/speech-to-speech-evi/streaming-with-websockets
+"""
+
+import logging
+import os
+from typing import List, Dict, Any, Optional
+
+from .base_provider import TTSProvider
+
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+class HumeProvider(TTSProvider):
+    """
+    Hume EVI TTS Provider - PLACEHOLDER (INACTIVE).
+
+    This is a stub class for future Hume EVI TTS integration.
+    Currently inactive due to API cost constraints.
+
+    When implemented, this would:
+        1. Connect to Hume EVI WebSocket API
+        2. Use a custom voice (ID: bdcf156c-6678-4720-9f91-46bf8063bd7f)
+        3. Stream text to the WebSocket
+        4. Receive audio chunks in real-time
+        5. Return concatenated audio bytes
+
+    Example (future implementation):
+        >>> provider = HumeProvider(api_key="xxx", voice_id="bdcf156c-...")
+        >>> audio = provider.generate_speech("Hello, how can I help you today?")
+        >>> # Returns WAV audio bytes using the custom cloned voice
+
+    Current behavior:
+        >>> provider = HumeProvider()
+        >>> provider.generate_speech("test")
+        NotImplementedError: Hume TTS is currently inactive (no funds). Use Supertonic instead.
+    """
+
+    # Hume API configuration
+    HUME_API_BASE = "https://api.hume.ai"
+    HUME_WS_PATH = "/v0/evi/chat"
+
+    # Default custom voice ID (cloned voice)
+    DEFAULT_VOICE_ID = "bdcf156c-6678-4720-9f91-46bf8063bd7f"
+
+    # Config ID (optional, for preset configurations)
+    DEFAULT_CONFIG_ID = "3c824978-efa3-40df-bac2-023127b30e31"
+
+    def __init__(self, api_key: Optional[str] = None, voice_id: Optional[str] = None):
+        """
+        Initialize the Hume TTS provider.
+
+        Args:
+            api_key: Hume API key (from .env or parameter). Currently unused
+                    as this provider is inactive.
+            voice_id: Custom voice ID. Defaults to the default custom voice.
+
+        Note:
+            This is a placeholder. Parameters are accepted for API compatibility
+            but are not used in the current stub implementation.
+        """
+        self.api_key = api_key
+        self.voice_id = voice_id or self.DEFAULT_VOICE_ID
+        logger.debug(
+            "HumeProvider initialized (inactive stub). "
+            "Use SupertonicTTS for actual TTS functionality."
+        )
+
+    def generate_speech(self, text: str, **kwargs) -> bytes:
+        """
+        Generate speech using Hume EVI WebSocket API.
+
+        **STUB METHOD - NOT IMPLEMENTED**
+
+        When implemented, this would:
+            1. Establish WebSocket connection to Hume EVI
+            2. Send text input via chat messages
+            3. Receive audio_output chunks
+            4. Concatenate and return as WAV bytes
+
+        Args:
+            text: Text to synthesize (currently ignored)
+            **kwargs: Additional parameters (currently ignored):
+                - speed: Speech speed multiplier
+                - temperature: Generation randomness
+                - language: Language code
+
+        Returns:
+            bytes: WAV audio data (when implemented)
+
+        Raises:
+            NotImplementedError: Always raised - this is a stub
+
+        Future Implementation Flow:
+            ```python
+            async with websockets.connect(
+                f"{self.HUME_API_BASE.replace('https', 'wss')}{self.HUME_WS_PATH}"
+                f"?access_token={self.api_key}"
+            ) as ws:
+                # Send text input
+                await ws.send(json.dumps({
+                    "text": text,
+                    "voice": {"voice_id": self.voice_id}
+                }))
+
+                # Collect audio chunks
+                audio_chunks = []
+                async for msg in ws:
+                    data = json.loads(msg)
+                    if 'audio_output' in data:
+                        audio_chunks.append(base64.b64decode(data['audio_output']))
+                    if data.get('message_end'):
+                        break
+
+                return b''.join(audio_chunks)
+            ```
+        """
+        error_msg = (
+            "Hume TTS is currently inactive (no funds). Use Supertonic instead.\n\n"
+            "When funded, this will use Hume EVI WebSocket API with custom voice: "
+            f"{self.voice_id}\n"
+            f"See: https://dev.hume.ai/docs/speech-to-speech-evi/streaming-with-websockets"
+        )
+        logger.error(f"HumeProvider.generate_speech() called but not implemented: {text[:50]}")
+        raise NotImplementedError(error_msg)
+
+    def list_voices(self) -> List[str]:
+        """
+        Return available Hume voices.
+
+        **STUB METHOD** - Returns placeholder data.
+
+        When implemented, this would query Hume's API to list:
+            - Custom cloned voices
+            - Built-in Hume voices
+            - Voice preview IDs
+
+        Returns:
+            List[str]: List of configured Hume voice IDs.
+        """
+        return ['your-hume-voice-id']
+
+    def get_info(self) -> Dict[str, Any]:
+        """
+        Return provider metadata.
+
+        Returns:
+            Dict with provider information including:
+                - name: Provider display name
+                - status: 'inactive' (no API funds)
+                - cost_per_minute: Cost in USD
+                - quality: Audio quality rating
+                - latency: Expected latency
+                - description: Brief provider description
+                - capabilities: Feature flags
+                - emotion_aware: Supports emotional expression
+                - real_time: Supports real-time streaming
+        """
+        _api_key = os.environ.get('HUME_API_KEY', '').strip()
+        _secret = os.environ.get('HUME_SECRET_KEY', '').strip()
+        _status = 'active' if (_api_key and _secret) else 'inactive'
+        return {
+            'name': 'Hume EVI (subscription)',
+            'status': _status,
+            'cost_per_minute': 0.06,
+            'quality': 'high',
+            'latency': 'medium',
+            'description': 'Hume Expressive Voice Interface — full real-time voice agent (STT + TTS + emotion)',
+            'capabilities': {
+                'emotion_aware': True,
+                'real_time': True
+            },
+            'voice_id': self.DEFAULT_VOICE_ID,
+            'config_id': self.DEFAULT_CONFIG_ID,
+            'notes': [
+                'Subscription required. Plans: Starter $3/mo (40 min), Creator $14/mo (200 min), Pro $70/mo (1,200 min).',
+                'Overage: $0.06/min (~$3.60/hr). Effective cost on lower plans can be $5-10+/hr.',
+                'Set HUME_API_KEY and HUME_SECRET_KEY in .env to activate.',
+                'Docs: https://platform.hume.ai/pricing'
+            ],
+            'api_endpoints': {
+                'websocket': f"{self.HUME_API_BASE.replace('https', 'wss')}{self.HUME_WS_PATH}",
+                'config': f"{self.HUME_API_BASE}/v0/evi/configs",
+                'voices': f"{self.HUME_API_BASE}/v0/evi/voices"
+            },
+            'requires_microphone': True,
+            'requires_websocket': True,
+            'mode': 'full-voice',
+        }
+
+    def is_available(self) -> bool:
+        """
+        Check if Hume provider is available.
+
+        Returns:
+            bool: Always False - this provider is inactive.
+        """
+        return False
+
+    def __repr__(self) -> str:
+        """String representation showing inactive status."""
+        return f"HumeProvider(voice_id='{self.voice_id}', status='INACTIVE - Use Supertonic instead')"
+
+
+__all__ = ['HumeProvider']

package/tts_providers/providers_config.json

@@ -0,0 +1,119 @@
+{
+  "providers": {
+    "hume": {
+      "name": "Hume EVI (subscription)",
+      "provider_id": "hume",
+      "cost_per_minute": 0.06,
+      "quality": "high",
+      "latency": "medium",
+      "voices": ["your-hume-voice-id"],
+      "features": [
+        "emotion-aware",
+        "real-time",
+        "websocket-streaming",
+        "voice-cloning"
+      ],
+      "requires_api_key": true,
+      "status": "active",
+      "description": "Hume Expressive Voice Interface — full real-time voice agent (STT + TTS + emotion)",
+      "documentation_url": "https://platform.hume.ai/pricing",
+      "languages": ["en"],
+      "max_characters": 5000,
+      "notes": "Subscription required. Plans: Starter $3/mo (40 min), Creator $14/mo (200 min), Pro $70/mo (1,200 min). Overage: $0.06/min (~$3.60/hr). Effective cost on lower plans can be $5-10+/hr depending on usage. Includes STT+TTS+emotion — not just TTS.",
+      "requires_microphone": true,
+      "requires_websocket": true,
+      "mode": "full-voice"
+    },
+    "supertonic": {
+      "name": "Supertonic TTS",
+      "provider_id": "supertonic",
+      "cost_per_minute": 0.0,
+      "quality": "high",
+      "latency": "very-fast",
+      "voices": ["M1", "M2", "M3", "M4", "M5", "F1", "F2", "F3", "F4", "F5"],
+      "features": [
+        "multi-language",
+        "local-processing",
+        "open-source",
+        "no-api-key-required",
+        "onnx-based"
+      ],
+      "requires_api_key": false,
+      "status": "active",
+      "description": "Local ONNX-based TTS engine with multiple voice styles",
+      "documentation_url": "https://github.com/playht/supertonic",
+      "languages": ["en", "ko", "es", "pt", "fr"],
+      "max_characters": 10000,
+      "notes": "Free, fast, local inference. Default provider.",
+      "requires_microphone": false,
+      "requires_websocket": false,
+      "mode": "tts-only"
+    },
+    "qwen3": {
+      "name": "Qwen3-TTS (fal.ai)",
+      "provider_id": "qwen3",
+      "cost_per_minute": 0.003,
+      "quality": "very-high",
+      "latency": "fast",
+      "voices": ["Vivian", "Serena", "Dylan", "Eric", "Ryan", "Aiden", "Uncle_Fu", "Ono_Anna", "Sohee"],
+      "features": ["multilingual", "expressive", "voice-cloning", "emotion-control", "cloud", "mp3-output"],
+      "requires_api_key": true,
+      "status": "active",
+      "description": "Qwen3-TTS via fal.ai — voice cloning, emotion control, multilingual, 10 languages",
+      "languages": ["en", "zh", "es", "fr", "de", "it", "ja", "ko", "pt", "ru"],
+      "max_characters": 5000,
+      "notes": "Voice cloning: POST /api/tts/clone with audio sample. Use cloned voice_id in /api/tts/generate. FAL_KEY required.",
+      "clone_endpoint": "/api/tts/clone",
+      "clone_cost_per_minute": 0.0008,
+      "requires_microphone": false,
+      "requires_websocket": false,
+      "mode": "tts-only",
+      "audio_format": "mp3",
+      "sample_rate": 24000
+    },
+    "resemble": {
+      "name": "Resemble AI (Chatterbox)",
+      "provider_id": "resemble",
+      "cost_per_minute": 0.10,
+      "quality": "very-high",
+      "latency": "very-fast",
+      "voices": [],
+      "features": ["streaming", "voice-cloning", "emotion-control", "ssml", "multilingual", "cloud", "wav-output", "paralinguistic-tags"],
+      "requires_api_key": true,
+      "status": "active",
+      "description": "Resemble AI Chatterbox — streaming TTS, voice cloning, emotion/exaggeration control, SSML, 90+ languages",
+      "documentation_url": "https://docs.resemble.ai",
+      "languages": ["en", "es", "fr", "de", "it", "pt", "ja", "ko", "zh", "ar", "ru", "hi", "nl", "pl", "sv", "da", "fi", "el", "cs", "hu", "ro", "tr", "uk", "vi", "th", "id"],
+      "max_characters": 2000,
+      "notes": "Models: chatterbox-turbo (fastest, paralinguistic tags), chatterbox (emotion/exaggeration), chatterbox-multilingual (23 langs). Voice cloning via Resemble dashboard. RESEMBLE_API_KEY + RESEMBLE_VOICE_UUID required.",
+      "requires_microphone": false,
+      "requires_websocket": false,
+      "mode": "tts-only",
+      "audio_format": "wav",
+      "sample_rate": 24000
+    },
+    "groq": {
+      "name": "Groq Orpheus",
+      "provider_id": "groq",
+      "cost_per_minute": 0.05,
+      "quality": "high",
+      "latency": "very-fast",
+      "voices": ["autumn", "diana", "hannah", "austin", "daniel", "troy"],
+      "features": ["streaming", "natural", "empathetic", "cloud", "mp3-output"],
+      "requires_api_key": true,
+      "status": "active",
+      "description": "Orpheus TTS (canopylabs/orpheus-v1-english) via Groq LPU — ~130-200ms, very natural",
+      "languages": ["en"],
+      "max_characters": 5000,
+      "notes": "~130-200ms latency on Groq LPU. Natural human-like prosody. GROQ_API_KEY required.",
+      "requires_microphone": false,
+      "requires_websocket": false,
+      "mode": "tts-only",
+      "audio_format": "mp3",
+      "sample_rate": 24000
+    }
+  },
+  "default_provider": "supertonic",
+  "version": "1.2.0",
+  "last_updated": "2026-02-21"
+}