smallestai 2.1.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

smallestai/waves/stream_tts.py

@@ -0,0 +1,272 @@
+import asyncio
+import time
+from threading import Thread
+from queue import Queue, Empty
+from typing import AsyncGenerator, Optional, Union, List, Dict, Any
+
+from smallestai.waves.waves_client import WavesClient
+from smallestai.waves.exceptions import APIError
+from smallestai.waves.async_waves_client import AsyncWavesClient
+from smallestai.waves.utils import SENTENCE_END_REGEX
+
+class TextToAudioStream:
+    def __init__(
+        self,
+        tts_instance: Union[WavesClient, AsyncWavesClient],
+        queue_timeout: Optional[float] = 5.0,
+        max_retries: Optional[int] = 3,
+        verbose: bool = False
+    ):
+        """
+        A real-time text-to-speech processor that converts streaming text into audio output.
+        Useful for applications requiring immediate audio feedback from text generation,
+        such as voice assistants, live captioning, or interactive chatbots.  
+
+        ⚠️ `add_wav_header` is disabled by default for streaming efficiency. Refer to the README for more information.  
+
+        Features:  
+        - Streams audio chunks as soon as text is available.
+        - Handles both sync and async text-to-speech engines.
+        - Automatically retries failed synthesis attempts.
+        - Low latency between text generation and speech output.
+
+        Args:
+            tts_instance: The text-to-speech engine to use (Smallest or AsyncSmallest)
+            queue_timeout: How long to wait for new text (seconds, default: 1.0)
+            max_retries: Number of retry attempts for failed synthesis (default: 3)
+            verbose: Whether to log detailed metrics about TTS requests (default: False)
+        """
+        self.tts_instance = tts_instance
+        self.tts_instance.opts.add_wav_header = False
+        self.sentence_end_regex = SENTENCE_END_REGEX
+        self.queue_timeout = queue_timeout
+        self.max_retries = max_retries
+        self.queue = Queue()
+        self.buffer_size = 250
+        self.stop_flag = False
+        self.verbose = verbose
+        
+        # Metrics tracking
+        self.request_count = 0
+        self.request_logs: List[Dict[str, Any]] = []
+        self.start_time = 0
+        self.first_api_response_time = None
+        self.end_time = 0
+
+        if self.tts_instance.opts.model == 'lightning-large':
+            self.buffer_size = 140
+
+
+    async def _stream_llm_output(self, llm_output: AsyncGenerator[str, None]) -> None:
+        """
+        Streams the LLM output, splitting it into chunks based on sentence boundaries
+        or space characters if no sentence boundary is found before reaching buffer_size.
+
+        Parameters:
+        - llm_output (AsyncGenerator[str, None]): An async generator yielding LLM output.
+        """
+        buffer = ""
+
+        async for chunk in llm_output:
+            buffer += chunk
+
+            while len(buffer) > self.buffer_size:
+                chunk_text = buffer[:self.buffer_size]
+                last_break_index = -1
+
+                # Find last sentence boundary using regex
+                for i in range(len(chunk_text) - 1, -1, -1):
+                    if self.sentence_end_regex.match(chunk_text[:i + 1]):
+                        last_break_index = i
+                        break
+
+                if last_break_index == -1:
+                    # Fallback to space if no sentence boundary found
+                    last_space = chunk_text.rfind(' ')
+                    if last_space != -1:
+                        last_break_index = last_space
+                    else:
+                        last_break_index = self.buffer_size - 1
+
+                # Add chunk to queue and update buffer
+                self.queue.put(f'{buffer[:last_break_index + 1].replace("—", " ").strip()} ')
+                buffer = buffer[last_break_index + 1:].strip()
+
+        # Don't forget the remaining text
+        if buffer:
+            self.queue.put(f'{buffer.replace("—", " ").strip()} ')
+
+        self.stop_flag = True
+
+
+    def _synthesize_sync(self, sentence: str, retries: int = 0) -> Optional[bytes]:
+        """Synchronously synthesizes a given sentence."""
+        request_start_time = time.time()
+        request_id = self.request_count + 1
+        
+        try:
+            audio_content = self.tts_instance.synthesize(sentence)
+            self.request_count += 1
+            request_end_time = time.time()
+            
+            if self.verbose:
+                request_duration = request_end_time - request_start_time
+                if self.first_api_response_time is None:
+                    self.first_api_response_time = time.time() - self.start_time
+                
+                self.request_logs.append({
+                    "id": request_id,
+                    "text": sentence,
+                    "start_time": request_start_time - self.start_time,
+                    "end_time": request_end_time - self.start_time,
+                    "duration": request_duration,
+                    "char_count": len(sentence),
+                    "retries": retries
+                })
+                
+            return audio_content
+        except APIError as e:
+            if retries < self.max_retries:
+                if self.verbose:
+                    print(f"Retry {retries + 1}/{self.max_retries} for request: '{sentence[:30]}...'")
+                return self._synthesize_sync(sentence, retries + 1)
+            else:
+                if self.verbose:
+                    print(f"Synthesis failed for sentence: {sentence} - Error: {e}. Retries Exhausted, for more information, visit https://waves.smallest.ai/")
+                return None
+            
+
+    async def _synthesize_async(self, sentence: str, retries: int = 0) -> Optional[bytes]:
+        """Asynchronously synthesizes a given sentence."""
+        request_start_time = time.time()
+        request_id = self.request_count + 1
+        
+        try:
+            audio_content = await self.tts_instance.synthesize(sentence)
+            self.request_count += 1
+            request_end_time = time.time()
+            
+            if self.verbose:
+                request_duration = request_end_time - request_start_time
+                if self.first_api_response_time is None:
+                    self.first_api_response_time = time.time() - self.start_time
+                
+                self.request_logs.append({
+                    "id": request_id,
+                    "text": sentence,
+                    "start_time": request_start_time - self.start_time,
+                    "end_time": request_end_time - self.start_time,
+                    "duration": request_duration,
+                    "char_count": len(sentence),
+                    "retries": retries
+                })
+                
+            return audio_content
+        except APIError as e:
+            if retries < self.max_retries:
+                if self.verbose:
+                    print(f"Retry {retries + 1}/{self.max_retries} for request: '{sentence[:30]}...'")
+                return await self._synthesize_async(sentence, retries + 1)
+            else:
+                if self.verbose:
+                    print(f"Synthesis failed for sentence: {sentence} - Error: {e}. Retries Exhausted, for more information, visit https://waves.smallest.ai/")
+                return None
+
+
+    async def _run_synthesis(self) -> AsyncGenerator[bytes, None]:
+        """
+        Continuously synthesizes sentences from the queue, yielding audio content.
+        If no sentences are in the queue, it waits until new data is available or streaming is complete.
+        """
+        while not self.stop_flag or not self.queue.empty():
+            try:
+                sentence = self.queue.get_nowait()
+                
+                if isinstance(self.tts_instance, AsyncWavesClient):
+                    audio_content = await self._synthesize_async(sentence)
+                else:
+                    loop = asyncio.get_running_loop()
+                    audio_content = await loop.run_in_executor(None, self._synthesize_sync, sentence)
+                
+                if audio_content:
+                    yield audio_content
+                    
+            except Empty:
+                # Quick check if we should exit
+                if self.stop_flag and self.queue.empty():
+                    break
+                    
+                # Short sleep to avoid busy-waiting
+                await asyncio.sleep(0.01)  # Much shorter sleep time (10ms)
+
+
+    def _print_verbose_summary(self) -> None:
+        """Print a summary of all metrics if verbose mode is enabled."""
+        if not self.verbose:
+            return
+            
+        total_duration = self.end_time - self.start_time
+        
+        print("\n" + "="*100)
+        print(f"TEXT-TO-AUDIO STREAM METRICS")
+        print("="*100)
+        
+        print(f"\nOVERALL STATISTICS:")
+        print(f"  Total requests made: {self.request_count}")
+        print(f"  Time to first API response: {self.first_api_response_time:.3f}s")
+        print(f"  Total processing time: {total_duration:.3f}s")
+        
+        # Print table header
+        print("\nREQUEST DETAILS:")
+        header = f"{'#':4} {'Start (s)':10} {'End (s)':10} {'Duration (s)':12} {'Characters':15} {'Text'}"
+        print("\n" + header)
+        print("-" * 100)
+        
+        # Print table rows
+        for log in self.request_logs:
+            row = (
+                f"{log['id']:4} "
+                f"{log['start_time']:10.3f} "
+                f"{log['end_time']:10.3f} "
+                f"{log['duration']:12.3f} "
+                f"{log['char_count']:15} "
+                f"{log['text'][:50]}{'...' if len(log['text']) > 50 else ''}"
+            )
+            print(row)
+            
+            # Print retry information if any
+            if log['retries'] > 0:
+                print(f"{'':4} {'':10} {'':10} {'':12} {'':15} Retries: {log['retries']}")
+                
+        print("\n" + "="*100)
+
+
+    async def process(self, llm_output: AsyncGenerator[str, None]) -> AsyncGenerator[bytes, None]:
+        """
+        Convert streaming text into audio in real-time.
+
+        Handles the entire pipeline from receiving text to producing audio,
+        yielding audio chunks as soon as they're ready.
+
+        Args:
+            llm_output: An async generator that yields text chunks.
+
+        Yields:
+            Raw audio data chunks (without WAV headers) that can be:
+            - Played directly through an audio device
+            - Saved to a file
+            - Streamed over a network
+            - Further processed as needed
+        """
+        self.start_time = time.time()
+        
+        llm_thread = Thread(target=asyncio.run, args=(self._stream_llm_output(llm_output),))
+        llm_thread.start()
+
+        async for audio_content in self._run_synthesis():
+            yield audio_content
+
+        llm_thread.join()
+        
+        self.end_time = time.time()
+        self._print_verbose_summary()

{smallest → smallestai/waves}/utils.py

@@ -4,15 +4,13 @@ from typing import List
 from typing import Optional
 from pydub import AudioSegment
 from dataclasses import dataclass
-from sacremoses import MosesPunctNormalizer
 
-from smallest.exceptions import ValidationError
-from smallest.models import TTSModels, TTSLanguages
+from smallestai.waves.exceptions import ValidationError
+from smallestai.waves.models import TTSModels, TTSLanguages
 
 
 API_BASE_URL = "https://waves-api.smallest.ai/api/v1"
 SENTENCE_END_REGEX = re.compile(r'.*[-.—!?,;:…।|]$')
-mpn = MosesPunctNormalizer()
 SAMPLE_WIDTH = 2
 CHANNELS = 1
 ALLOWED_AUDIO_EXTENSIONS = ['.mp3', '.wav']
@@ -26,9 +24,12 @@ class TTSOptions:
     api_key: str
     add_wav_header: bool
     speed: float
+    consistency: float
+    similarity: float
+    enhancement: int
 
 
-def validate_input(text: str, model: str, sample_rate: int, speed: float, consistency: Optional[float] = None, similarity: Optional[float] = None, enhancement: Optional[bool] = None):
+def validate_input(text: str, model: str, sample_rate: int, speed: float, consistency: Optional[float] = None, similarity: Optional[float] = None, enhancement: Optional[int] = None):
     if not text:
         raise ValidationError("Text cannot be empty.")
     if model not in TTSModels:
@@ -41,8 +42,8 @@ def validate_input(text: str, model: str, sample_rate: int, speed: float, consis
         raise ValidationError(f"Invalid consistency: {consistency}. Must be between 0.0 and 1.0")
     if similarity is not None and not 0.0 <= similarity <= 1.0:
         raise ValidationError(f"Invalid similarity: {similarity}. Must be between 0.0 and 1.0")
-    if enhancement is not None and not isinstance(enhancement, bool):
-        raise ValidationError(f"Invalid enhancement: {enhancement}. Must be a boolean value.")
+    if enhancement is not None and not 0 <= enhancement <= 2:
+        raise ValidationError(f"Invalid enhancement: {enhancement}. Must be between 0 and 2.")
 
 
 def add_wav_header(frame_input: bytes, sample_rate: int = 24000, sample_width: int = 2, channels: int = 1) -> bytes:
@@ -56,7 +57,6 @@ def add_wav_header(frame_input: bytes, sample_rate: int = 24000, sample_width: i
 def preprocess_text(text: str) -> str:
     text = text.replace("\n", " ").replace("\t", " ").replace("—", " ").replace("-", " ").replace("–", " ")
     text = re.sub(r'\s+', ' ', text)
-    text = mpn.normalize(text)
     return text.strip()
 
 

smallest/tts.py → smallestai/waves/waves_client.py

@@ -3,13 +3,13 @@ import json
 import wave
 import copy
 import requests
-from typing import Optional, Union, List
+from typing import Optional, Union, List, Iterator
 
-from smallest.exceptions import TTSError, APIError
-from smallest.utils import (TTSOptions, validate_input, preprocess_text, add_wav_header, chunk_text,
+from smallestai.waves.exceptions import TTSError, APIError
+from smallestai.waves.utils import (TTSOptions, validate_input, preprocess_text, add_wav_header, chunk_text,
 get_smallest_languages, get_smallest_models, ALLOWED_AUDIO_EXTENSIONS, API_BASE_URL)
 
-class Smallest:
+class WavesClient:
     def __init__(
         self,
         api_key: str = None,
@@ -17,6 +17,9 @@ class Smallest:
         sample_rate: Optional[int] = 24000,
         voice_id: Optional[str] = "emily",
         speed: Optional[float] = 1.0,
+        consistency: Optional[float] = 0.5,
+        similarity: Optional[float] = 0.0,
+        enhancement: Optional[int] = 1,
         add_wav_header: Optional[bool] = True
     ) -> None:
         """
@@ -31,6 +34,9 @@ class Smallest:
         - sample_rate (int): The sample rate for the audio output.
         - voice_id (TTSVoices): The voice to be used for synthesis.
         - speed (float): The speed of the speech synthesis.
+        - consistency (float): This parameter controls word repetition and skipping. Decrease it to prevent skipped words, and increase it to prevent repetition. Only supported in `lightning-large` model. Range - [0, 1]
+        - similarity (float): This parameter controls the similarity between the synthesized audio and the reference audio. Increase it to make the speech more similar to the reference audio. Only supported in `lightning-large` model. Range - [0, 1]
+        - enhancement (int): Enhances speech quality at the cost of increased latency. Only supported in `lightning-large` model. Range - [0, 2].
         - add_wav_header (bool): Whether to add a WAV header to the output audio.
 
         Methods:
@@ -42,7 +48,7 @@ class Smallest:
         self.api_key = api_key or os.environ.get("SMALLEST_API_KEY")
         if not self.api_key:
             raise TTSError()
-        if model == "lightning-large":
+        if model == "lightning-large" and voice_id is None:
             voice_id = "lakshya"
 
         self.chunk_size = 250
@@ -53,7 +59,10 @@ class Smallest:
             voice_id=voice_id,
             api_key=self.api_key,
             add_wav_header=add_wav_header,
-            speed=speed
+            speed=speed,
+            consistency=consistency,
+            similarity=similarity,
+            enhancement=enhancement
         )
     
         
@@ -98,27 +107,24 @@ class Smallest:
     def synthesize(
             self,
             text: str,
-            consistency: Optional[float] = 0.5,
-            similarity: Optional[float] = 0,
-            enhancement: Optional[bool] = False,
+            stream: Optional[bool] = False,
             save_as: Optional[str] = None,
             **kwargs
-        ) -> Union[bytes, None]:
+        ) -> Union[bytes, None, Iterator[bytes]]:
         """
         Synthesize speech from the provided text.
 
-        Args:
         - text (str): The text to be converted to speech.
-        - save_as (Optional[str]): If provided, the synthesized audio will be saved to this file path. 
+        - stream (Optional[bool]): If True, returns an iterator yielding audio chunks instead of a full byte array.
+        - save_as (Optional[str]): If provided, the synthesized audio will be saved to this file path.
                                    The file must have a .wav extension.
-        - consistency (Optional[float]): This parameter controls word repetition and skipping. Decrease it to prevent skipped words, and increase it to prevent repetition. Only supported in `lightning-large` model.
-        - similarity (Optional[float]): This parameter controls the similarity between the synthesized audio and the reference audio. Increase it to make the speech more similar to the reference audio. Only supported in `lightning-large` model.
-        - enhancement (Optional[bool]): Enhances speech quality at the cost of increased latency. Only supported in `lightning-large` model.
         - kwargs: Additional optional parameters to override `__init__` options for this call.
 
         Returns:
-        - Union[bytes, None]: The synthesized audio content in bytes if `save_as` is not specified; 
-                              otherwise, returns None after saving the audio to the specified file.
+        - Union[bytes, None, Iterator[bytes]]: 
+            - If `stream=True`, returns an iterator yielding audio chunks.
+            - If `save_as` is provided, saves the file and returns None.
+            - Otherwise, returns the synthesized audio content as bytes.
 
         Raises:
         - TTSError: If the provided file name does not have a .wav extension when `save_as` is specified.
@@ -134,42 +140,48 @@ class Smallest:
         for key, value in kwargs.items():
             setattr(opts, key, value)
 
-        validate_input(preprocess_text(text), opts.model, opts.sample_rate, opts.speed, consistency, similarity, enhancement)
+        text = preprocess_text(text)
+        validate_input(text, opts.model, opts.sample_rate, opts.speed, opts.consistency, opts.similarity, opts.enhancement)
 
         self.chunk_size = 250
         if opts.model == "lightning-large":
             self.chunk_size = 140
 
         chunks = chunk_text(text, self.chunk_size)
-        audio_content = b""
-
-        for chunk in chunks:
-            payload = {
-                "text": preprocess_text(chunk),
-                "sample_rate": opts.sample_rate,
-                "voice_id": opts.voice_id,
-                "add_wav_header": False,
-                "speed": opts.speed,
-            }
-
-            if opts.model == "lightning-large":
-                if consistency:
-                    payload["consistency"] = consistency
-                if similarity:
-                    payload["similarity"] = similarity
-                if enhancement:
-                    payload["enhancement"] = enhancement
-
-            headers = {
-                "Authorization": f"Bearer {self.api_key}",
-                "Content-Type": "application/json",
-            }
-
-            res = requests.post(f"{API_BASE_URL}/{opts.model}/get_speech", json=payload, headers=headers)
-            if res.status_code != 200:
-                raise APIError(f"Failed to synthesize speech: {res.text}. For more information, visit https://waves.smallest.ai/")
+
+        def audio_stream():
+            for chunk in chunks:
+                payload = {
+                    "text": chunk,
+                    "sample_rate": opts.sample_rate,
+                    "voice_id": opts.voice_id,
+                    "add_wav_header": False,
+                    "speed": opts.speed,
+                }
+
+                if opts.model == "lightning-large":
+                    if opts.consistency is not None:
+                        payload["consistency"] = opts.consistency
+                    if opts.similarity is not None:
+                        payload["similarity"] = opts.similarity
+                    if opts.enhancement is not None:
+                        payload["enhancement"] = opts.enhancement
+
+                headers = {
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                }
+
+                res = requests.post(f"{API_BASE_URL}/{opts.model}/get_speech", json=payload, headers=headers)
+                if res.status_code != 200:
+                    raise APIError(f"Failed to synthesize speech: {res.text}. Please check if you have set the correct API key. For more information, visit https://waves.smallest.ai/")
+
+                yield res.content
             
-            audio_content += res.content
+        if stream:
+            return audio_stream()
+        
+        audio_content = b"".join(audio_stream())
 
         if save_as:
             if not save_as.endswith(".wav"):