webscout 8.2.2__py3-none-any.whl → 2026.1.19__py3-none-any.whl

webscout/Provider/TTS/openai_fm.py

@@ -0,0 +1,364 @@
+##################################################################################
+##  OpenAI.fm TTS Provider                                                     ##
+##################################################################################
+import pathlib
+import tempfile
+from typing import Any, Generator, List, Optional, Union, cast
+
+import requests
+from litprinter import ic
+
+from webscout import exceptions
+from webscout.litagent import LitAgent
+from webscout.Provider.TTS.base import BaseTTSProvider
+
+
+class OpenAIFMTTS(BaseTTSProvider):
+    """
+    Text-to-speech provider using the OpenAI.fm API with OpenAI-compatible interface.
+
+    This provider follows the OpenAI TTS API structure with support for:
+    - Multiple TTS models (gpt-4o-mini-tts, tts-1, tts-1-hd)
+    - 11 built-in voices optimized for English
+    - Voice instructions for controlling speech aspects
+    - Multiple output formats
+    - Streaming support
+    """
+    required_auth = False
+
+    # Request headers
+    headers = {
+        "accept": "*/*",
+        "accept-language": "en-US,en;q=0.9",
+        "cache-control": "no-cache",
+        "pragma": "no-cache",
+        "sec-fetch-dest": "audio",
+        "sec-fetch-mode": "no-cors",
+        "sec-fetch-site": "same-origin",
+        "user-agent": LitAgent().random(),
+        "referer": "https://www.openai.fm"
+    }
+
+    # Override supported models for OpenAI.fm
+    SUPPORTED_MODELS = [
+        "gpt-4o-mini-tts",  # Latest intelligent realtime model
+        "tts-1",            # Lower latency model
+        "tts-1-hd"          # Higher quality model
+    ]
+
+    # OpenAI.fm supported voices (11 built-in voices)
+    SUPPORTED_VOICES = [
+        "alloy",    # Neutral voice with balanced tone
+        "ash",      # Calm and thoughtful male voice
+        "ballad",   # Soft and melodic voice
+        "coral",    # Warm and inviting female voice
+        "echo",     # Clear and precise voice
+        "fable",    # Authoritative and narrative voice
+        "nova",     # Energetic and bright female voice
+        "onyx",     # Deep and resonant male voice
+        "sage",     # Measured and contemplative voice
+        "shimmer"   # Bright and optimistic voice
+    ]
+
+    # Voice mapping for API compatibility
+    voice_mapping = {
+        "alloy": "alloy",
+        "ash": "ash",
+        "ballad": "ballad",
+        "coral": "coral",
+        "echo": "echo",
+        "fable": "fable",
+        "nova": "nova",
+        "onyx": "onyx",
+        "sage": "sage",
+        "shimmer": "shimmer"
+    }
+
+    def __init__(self, timeout: int = 20, proxies: Optional[dict] = None):
+        """
+        Initialize the OpenAI.fm TTS client.
+
+        Args:
+            timeout (int): Request timeout in seconds
+            proxies (dict): Proxy configuration
+        """
+        super().__init__()
+        self.api_url = "https://www.openai.fm/api/generate"
+        self.session = requests.Session()
+        self.session.headers.update(self.headers)
+        if proxies:
+            self.session.proxies.update(proxies)
+        self.timeout = timeout
+
+    def tts(
+        self,
+        text: str,
+        voice: Optional[str] = None,
+        verbose: bool = False,
+        **kwargs
+    ) -> str:
+        """
+        Convert text to speech using OpenAI.fm API with OpenAI-compatible parameters.
+
+        Args:
+            text (str): The text to convert to speech (max 10,000 characters)
+            model (str): The TTS model to use (gpt-4o-mini-tts, tts-1, tts-1-hd)
+            voice (str): The voice to use for TTS (alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer)
+            response_format (str): Audio format (mp3, opus, aac, flac, wav, pcm)
+            instructions (str): Voice instructions for controlling speech aspects like accent, tone, speed
+            verbose (bool): Whether to print debug information
+
+        Returns:
+            str: Path to the generated audio file
+
+        Raises:
+            ValueError: If input parameters are invalid
+            exceptions.FailedToGenerateResponseError: If there is an error generating or saving the audio
+        """
+        # Extract optional parameters from kwargs
+        model = kwargs.get("model", "gpt-4o-mini-tts")
+        response_format = kwargs.get("response_format", "mp3")
+        instructions = kwargs.get("instructions", None)
+
+        # Validate input parameters
+        if not text or not isinstance(text, str):
+            raise ValueError("Input text must be a non-empty string")
+        if len(text) > 10000:
+            raise ValueError("Input text exceeds maximum allowed length of 10,000 characters")
+
+        # Validate model, voice, and format using base class methods
+        model = self.validate_model(model)
+        voice = self.validate_voice(voice or "coral")
+        response_format = self.validate_format(response_format)
+
+        # Map voice to API format
+        voice_id = self.voice_mapping.get(voice, voice)
+
+        # Set default instructions if not provided
+        if instructions is None:
+            instructions = "Speak in a cheerful and positive tone."
+
+        # Create temporary file with appropriate extension
+        file_extension = f".{response_format}" if response_format != "pcm" else ".wav"
+        with tempfile.NamedTemporaryFile(suffix=file_extension, dir=self.temp_dir, delete=False) as temp_file:
+            filename = pathlib.Path(temp_file.name)
+
+        # Prepare parameters for the API request
+        params = {
+            "input": text,
+            "prompt": instructions,
+            "voice": voice_id,
+            "model": model,
+            "response_format": response_format
+        }
+
+        try:
+            # Make the API request
+            response = self.session.get(
+                self.api_url,
+                params=params,
+                timeout=self.timeout
+            )
+            response.raise_for_status()
+
+            # Validate response content
+            if not response.content:
+                raise exceptions.FailedToGenerateResponseError("Empty response from API")
+
+            # Save the audio file
+            with open(filename, "wb") as f:
+                f.write(response.content)
+
+            if verbose:
+                ic.configureOutput(prefix='DEBUG| ')
+                ic("Speech generated successfully")
+                ic.configureOutput(prefix='DEBUG| ')
+                ic(f"Model: {model}")
+                ic.configureOutput(prefix='DEBUG| ')
+                ic(f"Voice: {voice}")
+                ic.configureOutput(prefix='DEBUG| ')
+                ic(f"Format: {response_format}")
+                ic.configureOutput(prefix='DEBUG| ')
+                ic(f"Audio saved to {filename}")
+
+            return filename.as_posix()
+
+        except requests.exceptions.RequestException as e:
+            if verbose:
+                ic.configureOutput(prefix='DEBUG| ')
+                ic(f"Failed to generate speech: {e}")
+            raise exceptions.FailedToGenerateResponseError(
+                f"Failed to generate speech: {e}"
+            )
+        except Exception as e:
+            if verbose:
+                ic.configureOutput(prefix='DEBUG| ')
+                ic(f"Unexpected error: {e}")
+            raise exceptions.FailedToGenerateResponseError(
+                f"Unexpected error during speech generation: {e}"
+            )
+
+    def create_speech(
+        self,
+        input_text: str,
+        model: Optional[str] = "gpt-4o-mini-tts",
+        voice: Optional[str] = "alloy",
+        response_format: Optional[str] = "mp3",
+        instructions: Optional[str] = None,
+        verbose: bool = False,
+        **kwargs: Any
+    ) -> str:
+        """
+        OpenAI-compatible speech creation interface.
+
+        Args:
+            input_text (str): The text to convert to speech
+            model (str): The TTS model to use
+            voice (str): The voice to use
+            response_format (str): Audio format
+            instructions (str): Voice instructions
+            verbose (bool): Whether to print debug information
+
+        Returns:
+            str: Path to the generated audio file
+        """
+        return self.tts(
+            text=input_text,
+            voice=voice or "alloy",
+            model=model or "gpt-4o-mini-tts",
+            response_format=response_format or "mp3",
+            verbose=verbose
+        )
+
+    def with_streaming_response(self):
+        """
+        Return a streaming response context manager (OpenAI-compatible).
+
+        Returns:
+            StreamingResponseContextManager: Context manager for streaming responses
+        """
+        return StreamingResponseContextManager(self)
+
+
+class StreamingResponseContextManager:
+    """
+    Context manager for streaming TTS responses (OpenAI-compatible).
+    """
+
+    def __init__(self, tts_provider: OpenAIFMTTS):
+        self.tts_provider = tts_provider
+        self.audio_file = None
+
+    def create(
+        self,
+        input_text: str,
+        model: Optional[str] = "gpt-4o-mini-tts",
+        voice: Optional[str] = "coral",
+        response_format: Optional[str] = "mp3",
+        instructions: Optional[str] = None
+    ):
+        """
+        Create speech with streaming capability.
+
+        Args:
+            input_text (str): The text to convert to speech
+            model (str): The TTS model to use
+            voice (str): The voice to use
+            response_format (str): Audio format
+            instructions (str): Voice instructions
+
+        Returns:
+            StreamingResponse: Streaming response object
+        """
+        self.audio_file = self.tts_provider.create_speech(
+            input_text=input_text,
+            model=model,
+            voice=voice,
+            response_format=response_format,
+            instructions=instructions
+        )
+        return StreamingResponse(self.audio_file)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass
+
+
+class StreamingResponse:
+    """
+    Streaming response object for TTS audio (OpenAI-compatible).
+    """
+
+    def __init__(self, audio_file: str):
+        self.audio_file = audio_file
+
+    def __enter__(self):
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit the context manager."""
+        pass
+
+    def stream_to_file(self, file_path: str, chunk_size: int = 1024):
+        """
+        Stream audio content to a file.
+
+        Args:
+            file_path (str): Destination file path
+            chunk_size (int): Size of chunks to read/write
+        """
+        import shutil
+        shutil.copy2(self.audio_file, file_path)
+
+    def iter_bytes(self, chunk_size: int = 1024):
+        """
+        Iterate over audio bytes in chunks.
+
+        Args:
+            chunk_size (int): Size of chunks to yield
+
+        Yields:
+            bytes: Audio data chunks
+        """
+        with open(self.audio_file, 'rb') as f:
+            while chunk := f.read(chunk_size):
+                yield chunk
+
+
+if __name__ == "__main__":
+    # Example usage demonstrating OpenAI-compatible interface
+    tts_provider = OpenAIFMTTS()
+
+    try:
+        # Basic usage
+        ic.configureOutput(prefix='DEBUG| ')
+        ic("Testing basic speech generation...")
+        audio_file = tts_provider.create_speech(
+            input_text="Today is a wonderful day to build something people love!",
+            model="gpt-4o-mini-tts",
+            voice="coral",
+            instructions="Speak in a cheerful and positive tone."
+        )
+        print(f"Audio file generated: {audio_file}")
+
+        # Streaming usage
+        ic.configureOutput(prefix='DEBUG| ')
+        ic("Testing streaming response...")
+        with tts_provider.with_streaming_response().create(
+            input_text="This is a streaming test.",
+            voice="alloy",
+            response_format="wav"
+        ) as response:
+            response.stream_to_file("streaming_test.wav")
+            ic.configureOutput(prefix='INFO| ')
+            ic("Streaming audio saved to streaming_test.wav")
+
+    except exceptions.FailedToGenerateResponseError as e:
+        ic.configureOutput(prefix='ERROR| ')
+        ic(f"Error: {e}")
+    except Exception as e:
+        ic.configureOutput(prefix='ERROR| ')
+        ic(f"Unexpected error: {e}")

webscout/Provider/TTS/parler.py

@@ -1,111 +1,203 @@
-import time
-import tempfile
-from pathlib import Path
-from webscout import exceptions
-from webscout.AIbase import TTSProvider
-from gradio_client import Client
-import os
-
-
-class ParlerTTS(TTSProvider):
-    """
-    A class to interact with the Parler TTS API through Gradio Client.
-    """
-
-    def __init__(self, timeout: int = 20, proxies: dict = None):
-        """Initializes the Parler TTS client."""
-        self.api_endpoint = "/gen_tts"
-        self.client = Client("parler-tts/parler_tts")  # Initialize the Gradio client
-        self.timeout = timeout
-        self.temp_dir = tempfile.mkdtemp(prefix="webscout_tts_")
-
-    def tts(self, text: str, description: str = "", use_large: bool = False, verbose: bool = True) -> str:
-        """
-        Converts text to speech using the Parler TTS API.
-
-        Args:
-            text (str): The text to be converted to speech.
-            description (str, optional): Description of the desired voice characteristics. Defaults to "".
-            use_large (bool, optional): Whether to use the large model variant. Defaults to False.
-            verbose (bool, optional): Whether to log detailed information. Defaults to True.
-
-        Returns:
-            str: The filename of the saved audio file.
-
-        Raises:
-            exceptions.FailedToGenerateResponseError: If there is an error generating or saving the audio.
-        """
-        filename = Path(tempfile.mktemp(suffix=".wav", dir=self.temp_dir))
-
-        try:
-            if verbose:
-                print(f"[debug] Generating TTS with description: {description}")
-            
-            result = self.client.predict(
-                text=text,
-                description=description,
-                use_large=use_large,
-                api_name=self.api_endpoint,
-            )
-
-            if isinstance(result, bytes):
-                audio_bytes = result
-            elif isinstance(result, str) and os.path.isfile(result):
-                with open(result, "rb") as f:
-                    audio_bytes = f.read()
-            else:
-                raise ValueError(f"Unexpected response from API: {result}")
-
-            self._save_audio(audio_bytes, filename, verbose)
-            
-            if verbose:
-                print(f"[debug] Audio generated successfully: {filename}")
-            
-            return filename.as_posix()
-
-        except Exception as e:
-            if verbose:
-                print(f"[debug] Error generating audio: {e}")
-            raise exceptions.FailedToGenerateResponseError(
-                f"Error generating audio after multiple retries: {e}"
-            ) from e
-
-    def _save_audio(self, audio_data: bytes, filename: Path, verbose: bool = True):
-        """
-        Saves the audio data to a WAV file.
-
-        Args:
-            audio_data (bytes): Audio data to save
-            filename (Path): Path to save the audio file
-            verbose (bool): Whether to print debug information
-
-        Raises:
-            exceptions.FailedToGenerateResponseError: If there is an error saving the audio.
-        """
-        try:
-            with open(filename, "wb") as f:
-                f.write(audio_data)
-            if verbose:
-                print(f"[debug] Audio saved to {filename}")
-
-        except Exception as e:
-            if verbose:
-                print(f"[debug] Error saving audio: {e}")
-            raise exceptions.FailedToGenerateResponseError(f"Error saving audio: {e}")
-
-# Example usage
-if __name__ == "__main__":
-    parlertts = ParlerTTS()
-    text = (
-        "All of the data, pre-processing, training code, and weights are released "
-        "publicly under a permissive license, enabling the community to build on our work "
-        "and develop their own powerful models."
-    )
-    voice_description = (
-        "Laura's voice is monotone yet slightly fast in delivery, with a very close "
-        "recording that almost has no background noise."
-    )
-
-    print("[debug] Generating audio...")
-    audio_file = parlertts.tts(text, description=voice_description, use_large=False)
-    print(f"Audio saved to: {audio_file}")
+##################################################################################
+##  ParlerTTS Provider                                                         ##
+##################################################################################
+import json
+import pathlib
+import random
+import string
+import tempfile
+from typing import Any, Optional, Union, cast
+
+import httpx
+from litprinter import ic
+
+from webscout import exceptions
+from webscout.litagent import LitAgent
+
+try:
+    from . import utils
+    from .base import BaseTTSProvider
+except ImportError:
+    # Handle direct execution
+    import os
+    import sys
+    sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', '..'))
+    from webscout.Provider.TTS.base import BaseTTSProvider
+
+class ParlerTTS(BaseTTSProvider):
+    """
+    Text-to-speech provider using the Parler-TTS API (Hugging Face Spaces).
+
+    Features:
+    - High-fidelity speech generation
+    - Controllable via simple text prompts (description)
+    - Manual polling logic for robustness
+    """
+    required_auth = False
+
+    BASE_URL = "https://parler-tts-parler-tts.hf.space"
+
+    # Request headers
+    headers: dict[str, str] = {
+        "User-Agent": LitAgent().random(),
+        "origin": BASE_URL,
+        "referer": f"{BASE_URL}/",
+    }
+
+    SUPPORTED_MODELS = ["parler-mini-v1", "parler-large-v1"]
+
+    def __init__(self, timeout: int = 120, proxy: Optional[str] = None):
+        """
+        Initialize the ParlerTTS client.
+        """
+        super().__init__()
+        self.timeout = timeout
+        self.proxy = proxy
+        self.default_model = "parler-mini-v1"
+
+    def _generate_session_hash(self) -> str:
+        return "".join(random.choices(string.ascii_lowercase + string.digits, k=10))
+
+    def tts(self, text: str, voice: Optional[str] = None, verbose: bool = False, **kwargs) -> str:
+        """
+        Convert text to speech using Parler-TTS API.
+
+        Args:
+            text (str): The text to convert to speech
+            voice (str): The voice to use
+            verbose (bool): Whether to print debug information
+            **kwargs: Additional parameters
+        """
+        # Extract parameters from kwargs with defaults
+        description = kwargs.get('description', "A female speaker delivers a slightly expressive and animated speech with a moderate speed. The recording features a low-pitch voice and very clear audio.")
+        use_large = kwargs.get('use_large', False)
+        response_format = kwargs.get('response_format', "wav")
+        verbose = verbose if verbose is not None else kwargs.get('verbose', True)
+
+        if not text:
+            raise ValueError("Input text must be a non-empty string")
+
+        session_hash = self._generate_session_hash()
+        filename = pathlib.Path(tempfile.NamedTemporaryFile(suffix=f".{response_format}", dir=self.temp_dir, delete=False).name)
+
+        if verbose:
+            ic.configureOutput(prefix='DEBUG| ')
+            ic(f"ParlerTTS: Generating speech for '{text[:20]}...'")
+
+        client_kwargs: dict[str, Any] = {"headers": self.headers, "timeout": self.timeout}
+        if self.proxy:
+            client_kwargs["proxy"] = self.proxy
+
+        try:
+            with httpx.Client(**client_kwargs) as client:
+                # Step 1: Join the queue
+                join_url = f"{self.BASE_URL}/queue/join?__theme=system"
+                # fn_index 0 is for the main generation task
+                payload = {
+                    "data": [text, description, use_large],
+                    "event_data": None,
+                    "fn_index": 0,
+                    "trigger_id": 8,
+                    "session_hash": session_hash
+                }
+
+                response = client.post(join_url, json=payload)
+                response.raise_for_status()
+
+                # Step 2: Poll for data
+                data_url = f"{self.BASE_URL}/queue/data?session_hash={session_hash}"
+                audio_url = None
+
+                # Gradio Spaces can take time to wake up or process
+                with client.stream("GET", data_url) as stream:
+                    for line in stream.iter_lines():
+                        if not line:
+                            continue
+                        if line.startswith("data: "):
+                            try:
+                                data = json.loads(line[6:])
+                            except json.JSONDecodeError:
+                                continue
+
+                            msg = data.get("msg")
+                            if msg == "process_completed":
+                                if data.get("success"):
+                                    output_data = data.get("output", {}).get("data", [])
+                                    if output_data:
+                                        audio_info = output_data[0]
+                                        path = audio_info["path"] if isinstance(audio_info, dict) else audio_info
+                                        audio_url = f"{self.BASE_URL}/file={path}"
+                                    break
+                                else:
+                                    raise exceptions.FailedToGenerateResponseError(f"Generation failed: {data}")
+                            elif msg == "queue_full":
+                                raise exceptions.FailedToGenerateResponseError("Queue is full")
+                            elif msg == "send_hash":
+                                # Normal handshake
+                                pass
+
+                if not audio_url:
+                    raise exceptions.FailedToGenerateResponseError("Failed to get audio URL from stream")
+
+                # Step 3: Download the audio file
+                audio_response = client.get(audio_url)
+                audio_response.raise_for_status()
+
+                with open(filename, "wb") as f:
+                    f.write(audio_response.content)
+
+                if verbose:
+                    ic.configureOutput(prefix='DEBUG| ')
+                    ic(f"Speech generated successfully: {filename}")
+
+                return filename.as_posix()
+
+        except Exception as e:
+            if verbose:
+                ic.configureOutput(prefix='DEBUG| ')
+                ic(f"Error in ParlerTTS: {e}")
+            raise exceptions.FailedToGenerateResponseError(f"Failed to generate audio: {e}")
+
+    def create_speech(
+        self,
+        input_text: str,
+        model: Optional[str] = "parler-mini-v1",
+        voice: Optional[str] = None,
+        response_format: Optional[str] = "mp3",
+        instructions: Optional[str] = None,
+        verbose: bool = False
+    ) -> str:
+        """
+        OpenAI-compatible speech creation interface.
+
+        Args:
+            input_text (str): The text to convert to speech
+            model (str): The TTS model to use
+            voice (str): The voice to use (not used by ParlerAI directly)
+            response_format (str): Audio format
+            instructions (str): Voice instructions (used as description)
+            verbose (bool): Whether to print debug information
+
+        Returns:
+            str: Path to the generated audio file
+        """
+        description = instructions or "A female speaker delivers a slightly expressive and animated speech with a moderate speed. The recording features a low-pitch voice and very clear audio."
+        use_large = (model == "parler-large-v1")
+
+        return self.tts(
+            text=input_text,
+            description=description,
+            use_large=use_large,
+            response_format=response_format or "mp3",
+            verbose=verbose
+        )
+
+if __name__ == "__main__":
+    tts = ParlerTTS()
+    try:
+        path = tts.tts("Testing Parler-TTS with manual polling.", verbose=True)
+        ic.configureOutput(prefix='INFO| ')
+        ic(f"Saved to {path}")
+    except Exception as e:
+        ic.configureOutput(prefix='ERROR| ')
+        ic(f"Error: {e}")