smallestai 1.3.3__tar.gz → 2.0.0__tar.gz

{smallestai-1.3.3 → smallestai-2.0.0}/PKG-INFO

@@ -1,8 +1,8 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: smallestai
-Version: 1.3.3
+Version: 2.0.0
 Summary: Official Python client for the Smallest AI API
-Author-email: Smallest <info@smallest.ai>
+Author-email: Smallest <support@smallest.ai>
 License: MIT
 Project-URL: Homepage, https://github.com/smallest-inc/smallest-python-sdk
 Keywords: smallest,smallest.ai,tts,text-to-speech
@@ -53,10 +53,14 @@ Currently, the library supports direct synthesis and the ability to synthesize s
 
 - [Installation](#installation)
 - [Get the API Key](#get-the-api-key)
+- [Best Practices for Input Text](#best-practices-for-input-text)
 - [Examples](#examples)
-  - [Sync](#sync)
-  - [Async](#async)
+  - [Synchronous](#Synchronous)
+  - [Aynchronous](#Synchronous)
   - [LLM to Speech](#llm-to-speech)
+  - [Add your Voice](#add-your-voice)
+    - [Synchronously](#synchronously)
+    - [Asynchronously](#asynchronously)
 - [Available Methods](#available-methods)
 - [Technical Note: WAV Headers in Streaming Audio](#technical-note-wav-headers-in-streaming-audio)
 
@@ -76,19 +80,30 @@ When using an SDK in your application, make sure to pin to at least the major ve
 3. Create a new API Key and copy it.
 4. Export the API Key in your environment with the name `SMALLEST_API_KEY`, ensuring that your application can access it securely for authentication.
 
+## Best Practices for Input Text
+While the `transliterate` parameter is provided, please note that it is not fully supported and may not perform consistently across all cases. It is recommended to use the model without relying on this parameter.
+
+For optimal voice generation results:
+
+1. For English, provide the input in Latin script (e.g., "Hello, how are you?").
+2. For Hindi, provide the input in Devanagari script (e.g., "नमस्ते, आप कैसे हैं?").
+3. For code-mixed input, use Latin script for English and Devanagari script for Hindi (e.g., "Hello, आप कैसे हैं?").
+
 ## Examples
 
-### Sync  
+### Synchronous  
 A synchronous text-to-speech synthesis client. 
 
 **Basic Usage:**   
 ```python
-import os
 from smallest import Smallest
 
 def main():
-    client = Smallest(api_key=os.environ.get("SMALLEST_API_KEY"))
-    client.synthesize("Hello, this is a test for sync synthesis function.", save_as="sync_synthesize.wav")
+    client = Smallest(api_key="SMALLEST_API_KEY")
+    client.synthesize(
+        text="Hello, this is a test for sync synthesis function.",
+        save_as="sync_synthesize.wav"
+    )
 
 if __name__ == "__main__":
     main()
@@ -98,7 +113,7 @@ if __name__ == "__main__":
 - `api_key`: Your API key (can be set via SMALLEST_API_KEY environment variable)
 - `model`: TTS model to use (default: "lightning")
 - `sample_rate`: Audio sample rate (default: 24000)
-- `voice`: Voice ID (default: "emily")
+- `voice_id`: Voice ID (default: "emily")
 - `speed`: Speech speed multiplier (default: 1.0)
 - `add_wav_header`: Include WAV header in output (default: True)
 - `transliterate`: Enable text transliteration (default: False)
@@ -117,17 +132,16 @@ client.synthesize(
 ```
 
 
-### Async   
+### Asynchronous   
 Asynchronous text-to-speech synthesis client.    
 
 **Basic Usage:**   
 ```python
-import os
 import asyncio
 import aiofiles
 from smallest import AsyncSmallest
 
-client = AsyncSmallest(api_key=os.environ.get("SMALLEST_API_KEY"))
+client = AsyncSmallest(api_key="SMALLEST_API_KEY")
 
 async def main():
     async with client as tts:
@@ -143,7 +157,7 @@ if __name__ == "__main__":
 - `api_key`: Your API key (can be set via SMALLEST_API_KEY environment variable)
 - `model`: TTS model to use (default: "lightning")
 - `sample_rate`: Audio sample rate (default: 24000)
-- `voice`: Voice ID (default: "emily")
+- `voice_id`: Voice ID (default: "emily")
 - `speed`: Speech speed multiplier (default: 1.0)
 - `add_wav_header`: Include WAV header in output (default: True)
 - `transliterate`: Enable text transliteration (default: False)
@@ -162,18 +176,16 @@ audio_bytes = await tts.synthesize(
 
 ### LLM to Speech    
 
-The `TextToAudioStream` class provides real-time text-to-speech processing, converting streaming text into audio output with minimal latency. It's particularly useful for applications like voice assistants, live captioning, or interactive chatbots that require immediate audio feedback from text generation. Supports both synchronous and asynchronous TTS instance.
+The `TextToAudioStream` class provides real-time text-to-speech processing, converting streaming text into audio output. It's particularly useful for applications like voice assistants, live captioning, or interactive chatbots that require immediate audio feedback from text generation. Supports both synchronous and asynchronous TTS instance.
 
 ```python
-import os
 import wave
 import asyncio
 from groq import Groq
-from smallest import Smallest
-from smallest import TextToAudioStream
+from smallest import Smallest, TextToAudioStream
 
-llm = Groq(api_key=os.environ.get("GROQ_API_KEY"))
-tts = Smallest(api_key=os.environ.get("SMALLEST_API_KEY"))
+llm = Groq(api_key="GROQ_API_KEY")
+tts = Smallest(api_key="SMALLEST_API_KEY")
 
 async def generate_text(prompt):
     """Async generator for streaming text from Groq. You can use any LLM"""
@@ -230,16 +242,46 @@ The processor yields raw audio data chunks without WAV headers for streaming eff
 - Streamed over a network
 - Further processed as needed
 
+## Add your Voice   
+The Smallest AI SDK allows you to clone your voice by uploading an audio file. This feature is available both synchronously and asynchronously, making it flexible for different use cases. Below are examples of how to use this functionality.  
+
+### Synchronously
+```python
+from smallest import Smallest
+
+def main():
+    client = Smallest(api_key="YOUR_API_KEY")
+    res = client.add_voice(display_name="My Voice", file_path="my_voice.wav")
+    print(res)
+
+if __name__ == "__main__":
+    main()
+```  
+
+### Asynchronously
+```python
+import asyncio
+from smallest import AsyncSmallest
+
+async def main():
+    client = AsyncSmallest(api_key="YOUR_API_KEY")
+    res = await client.add_voice(display_name="My Voice", file_path="my_voice.wav")
+    print(res)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
 
 ## Available Methods
 
 ```python
-from smallest.tts import Smallest
+from smallest import Smallest
 
-client = Smallest()
+client = Smallest(api_key="SMALLEST_API_KEY")
 
-print(f"Avalaible Languages: {client.get_languages()}")
-print(f"Available Voices: {client.get_voices()}")
+print(f"Available Languages: {client.get_languages()}")
+print(f"Available Voices: {client.get_voices(model='lightning')}")
+print(f"Available Voices: {client.get_cloned_voices()}")
 print(f"Available Models: {client.get_models()}")
 ```
 
@@ -254,7 +296,7 @@ When implementing audio streaming with chunks of synthesized speech, WAV headers
 - Sequential playback of chunks with headers causes audio artifacts (pop sounds) when concatenating or playing audio sequentially.
 - Audio players would try to reinitialize audio settings for each chunk.
 
-### Best Practices
+### Best Practices for Audio Streaming
 1. Stream raw PCM audio data without headers
 2. Add a single WAV header only when:
    - Saving the complete stream to a file

{smallestai-1.3.3 → smallestai-2.0.0}/README.md

@@ -26,10 +26,14 @@ Currently, the library supports direct synthesis and the ability to synthesize s
 
 - [Installation](#installation)
 - [Get the API Key](#get-the-api-key)
+- [Best Practices for Input Text](#best-practices-for-input-text)
 - [Examples](#examples)
-  - [Sync](#sync)
-  - [Async](#async)
+  - [Synchronous](#Synchronous)
+  - [Aynchronous](#Synchronous)
   - [LLM to Speech](#llm-to-speech)
+  - [Add your Voice](#add-your-voice)
+    - [Synchronously](#synchronously)
+    - [Asynchronously](#asynchronously)
 - [Available Methods](#available-methods)
 - [Technical Note: WAV Headers in Streaming Audio](#technical-note-wav-headers-in-streaming-audio)
 
@@ -49,19 +53,30 @@ When using an SDK in your application, make sure to pin to at least the major ve
 3. Create a new API Key and copy it.
 4. Export the API Key in your environment with the name `SMALLEST_API_KEY`, ensuring that your application can access it securely for authentication.
 
+## Best Practices for Input Text
+While the `transliterate` parameter is provided, please note that it is not fully supported and may not perform consistently across all cases. It is recommended to use the model without relying on this parameter.
+
+For optimal voice generation results:
+
+1. For English, provide the input in Latin script (e.g., "Hello, how are you?").
+2. For Hindi, provide the input in Devanagari script (e.g., "नमस्ते, आप कैसे हैं?").
+3. For code-mixed input, use Latin script for English and Devanagari script for Hindi (e.g., "Hello, आप कैसे हैं?").
+
 ## Examples
 
-### Sync  
+### Synchronous  
 A synchronous text-to-speech synthesis client. 
 
 **Basic Usage:**   
 ```python
-import os
 from smallest import Smallest
 
 def main():
-    client = Smallest(api_key=os.environ.get("SMALLEST_API_KEY"))
-    client.synthesize("Hello, this is a test for sync synthesis function.", save_as="sync_synthesize.wav")
+    client = Smallest(api_key="SMALLEST_API_KEY")
+    client.synthesize(
+        text="Hello, this is a test for sync synthesis function.",
+        save_as="sync_synthesize.wav"
+    )
 
 if __name__ == "__main__":
     main()
@@ -71,7 +86,7 @@ if __name__ == "__main__":
 - `api_key`: Your API key (can be set via SMALLEST_API_KEY environment variable)
 - `model`: TTS model to use (default: "lightning")
 - `sample_rate`: Audio sample rate (default: 24000)
-- `voice`: Voice ID (default: "emily")
+- `voice_id`: Voice ID (default: "emily")
 - `speed`: Speech speed multiplier (default: 1.0)
 - `add_wav_header`: Include WAV header in output (default: True)
 - `transliterate`: Enable text transliteration (default: False)
@@ -90,17 +105,16 @@ client.synthesize(
 ```
 
 
-### Async   
+### Asynchronous   
 Asynchronous text-to-speech synthesis client.    
 
 **Basic Usage:**   
 ```python
-import os
 import asyncio
 import aiofiles
 from smallest import AsyncSmallest
 
-client = AsyncSmallest(api_key=os.environ.get("SMALLEST_API_KEY"))
+client = AsyncSmallest(api_key="SMALLEST_API_KEY")
 
 async def main():
     async with client as tts:
@@ -116,7 +130,7 @@ if __name__ == "__main__":
 - `api_key`: Your API key (can be set via SMALLEST_API_KEY environment variable)
 - `model`: TTS model to use (default: "lightning")
 - `sample_rate`: Audio sample rate (default: 24000)
-- `voice`: Voice ID (default: "emily")
+- `voice_id`: Voice ID (default: "emily")
 - `speed`: Speech speed multiplier (default: 1.0)
 - `add_wav_header`: Include WAV header in output (default: True)
 - `transliterate`: Enable text transliteration (default: False)
@@ -135,18 +149,16 @@ audio_bytes = await tts.synthesize(
 
 ### LLM to Speech    
 
-The `TextToAudioStream` class provides real-time text-to-speech processing, converting streaming text into audio output with minimal latency. It's particularly useful for applications like voice assistants, live captioning, or interactive chatbots that require immediate audio feedback from text generation. Supports both synchronous and asynchronous TTS instance.
+The `TextToAudioStream` class provides real-time text-to-speech processing, converting streaming text into audio output. It's particularly useful for applications like voice assistants, live captioning, or interactive chatbots that require immediate audio feedback from text generation. Supports both synchronous and asynchronous TTS instance.
 
 ```python
-import os
 import wave
 import asyncio
 from groq import Groq
-from smallest import Smallest
-from smallest import TextToAudioStream
+from smallest import Smallest, TextToAudioStream
 
-llm = Groq(api_key=os.environ.get("GROQ_API_KEY"))
-tts = Smallest(api_key=os.environ.get("SMALLEST_API_KEY"))
+llm = Groq(api_key="GROQ_API_KEY")
+tts = Smallest(api_key="SMALLEST_API_KEY")
 
 async def generate_text(prompt):
     """Async generator for streaming text from Groq. You can use any LLM"""
@@ -203,16 +215,46 @@ The processor yields raw audio data chunks without WAV headers for streaming eff
 - Streamed over a network
 - Further processed as needed
 
+## Add your Voice   
+The Smallest AI SDK allows you to clone your voice by uploading an audio file. This feature is available both synchronously and asynchronously, making it flexible for different use cases. Below are examples of how to use this functionality.  
+
+### Synchronously
+```python
+from smallest import Smallest
+
+def main():
+    client = Smallest(api_key="YOUR_API_KEY")
+    res = client.add_voice(display_name="My Voice", file_path="my_voice.wav")
+    print(res)
+
+if __name__ == "__main__":
+    main()
+```  
+
+### Asynchronously
+```python
+import asyncio
+from smallest import AsyncSmallest
+
+async def main():
+    client = AsyncSmallest(api_key="YOUR_API_KEY")
+    res = await client.add_voice(display_name="My Voice", file_path="my_voice.wav")
+    print(res)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
 
 ## Available Methods
 
 ```python
-from smallest.tts import Smallest
+from smallest import Smallest
 
-client = Smallest()
+client = Smallest(api_key="SMALLEST_API_KEY")
 
-print(f"Avalaible Languages: {client.get_languages()}")
-print(f"Available Voices: {client.get_voices()}")
+print(f"Available Languages: {client.get_languages()}")
+print(f"Available Voices: {client.get_voices(model='lightning')}")
+print(f"Available Voices: {client.get_cloned_voices()}")
 print(f"Available Models: {client.get_models()}")
 ```
 
@@ -227,7 +269,7 @@ When implementing audio streaming with chunks of synthesized speech, WAV headers
 - Sequential playback of chunks with headers causes audio artifacts (pop sounds) when concatenating or playing audio sequentially.
 - Audio players would try to reinitialize audio settings for each chunk.
 
-### Best Practices
+### Best Practices for Audio Streaming
 1. Stream raw PCM audio data without headers
 2. Add a single WAV header only when:
    - Saving the complete stream to a file

{smallestai-1.3.3 → smallestai-2.0.0}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "smallestai"
-version = "1.3.3"
+version = "2.0.0"
 description = "Official Python client for the Smallest AI API"
 authors = [
-    {name = "Smallest", email = "info@smallest.ai"},
+    {name = "Smallest", email = "support@smallest.ai"},
 ]
 readme = "README.md"
 license = {text = "MIT"}

smallestai-2.0.0/smallest/async_tts.py

@@ -0,0 +1,260 @@
+import os
+import copy
+import json
+import aiohttp
+import aiofiles
+import requests
+from typing import Optional, Union, List
+
+from smallest.exceptions import TTSError, APIError
+from smallest.utils import (TTSOptions, validate_input, preprocess_text, add_wav_header, chunk_text,
+                     get_smallest_languages, get_smallest_models, API_BASE_URL)
+
+
+class AsyncSmallest:
+    def __init__(
+        self,
+        api_key: str = None,
+        model: Optional[str] = "lightning",
+        sample_rate: Optional[int] = 24000,
+        voice_id: Optional[str] = "emily",
+        speed: Optional[float] = 1.0,
+        add_wav_header: Optional[bool] = True,
+        transliterate: Optional[bool] = False,
+        remove_extra_silence: Optional[bool] = False
+    ) -> None:
+        """
+        AsyncSmallest Instance for asynchronous text-to-speech synthesis.
+
+        This class provides an asynchronous implementation of the text-to-speech functionality.
+        It allows for non-blocking synthesis of speech from text, making it suitable for applications
+        that require async processing.
+
+        Args:
+        - api_key (str): The API key for authentication, export it as 'SMALLEST_API_KEY' in your environment variables.
+        - model (TTSModels): The model to be used for synthesis.
+        - 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.
+        - add_wav_header (bool): Whether to add a WAV header to the output audio.
+        - transliterate (bool): Whether to transliterate the text.
+        - remove_extra_silence (bool): Whether to remove extra silence from the synthesized audio.
+
+        Methods:
+        - get_languages: Returns a list of available languages for synthesis.
+        - get_voices: Returns a list of available voices for synthesis.
+        - get_models: Returns a list of available models for synthesis.
+        - synthesize: Asynchronously converts the provided text into speech and returns the audio content.
+        """
+        self.api_key = api_key or os.environ.get("SMALLEST_API_KEY")
+        if not self.api_key:
+            raise TTSError()
+        self.chunk_size = 250
+
+        self.opts = TTSOptions(
+            model=model,
+            sample_rate=sample_rate,
+            voice_id=voice_id,
+            api_key=self.api_key,
+            add_wav_header=add_wav_header,
+            speed=speed,
+            transliterate=transliterate,
+            remove_extra_silence=remove_extra_silence,
+        )
+        self.session = None
+
+
+    async def __aenter__(self):
+        if self.session is None:
+            self.session = aiohttp.ClientSession()
+        return self
+
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self.session:
+            await self.session.close()
+
+
+    async def _ensure_session(self):
+        """Ensure session exists for direct calls"""
+        if not self.session:
+            self.session = aiohttp.ClientSession()
+            return True
+        return False
+    
+
+    def get_languages(self) -> List[str]:
+        """Returns a list of available languages."""
+        return get_smallest_languages()
+
+    def get_cloned_voices(self) -> str:
+        """Returns a list of your cloned voices."""
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+        }
+
+        res = requests.request("GET", f"{API_BASE_URL}/lightning-large/get_cloned_voices", headers=headers)
+        if res.status_code != 200:
+            raise APIError(f"Failed to get cloned voices: {res.text}. For more information, visit https://waves.smallest.ai/")
+        
+        return json.dumps(res.json(), indent=4, ensure_ascii=False)
+    
+
+    def get_voices(
+            self,
+            model: Optional[str] = "lightning"
+        ) -> str:
+        """Returns a list of available voices."""
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+        }
+
+        res = requests.request("GET", f"{API_BASE_URL}/{model}/get_voices", headers=headers)
+        if res.status_code != 200:
+            raise APIError(f"Failed to get voices: {res.text}. For more information, visit https://waves.smallest.ai/")
+        
+        return json.dumps(res.json(), indent=4, ensure_ascii=False)
+
+
+    def get_models(self) -> List[str]:
+        """Returns a list of available models."""
+        return get_smallest_models()
+
+
+    async def synthesize(
+            self,
+            text: str,
+            save_as: Optional[str] = None,
+            **kwargs
+        ) -> Union[bytes, None]:
+        """
+        Asynchronously 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.
+                                   The file must have a .wav extension.
+        - 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.
+
+        Raises:
+        - TTSError: If the provided file name does not have a .wav extension when `save_as` is specified.
+        - APIError: If the API request fails or returns an error.
+        """
+        should_cleanup = await self._ensure_session()
+
+        try:
+            opts = copy.deepcopy(self.opts)
+            for key, value in kwargs.items():
+                setattr(opts, key, value)
+
+            validate_input(preprocess_text(text), opts.model, opts.sample_rate, opts.speed)
+
+            self.chunk_size = 250
+            if opts.model == 'ligtning-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,
+                    "model": opts.model,
+                    "transliterate": opts.transliterate,
+                    "remove_extra_silence": opts.remove_extra_silence
+                }
+
+                headers = {
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                }
+
+                if not self.session:
+                    self.session = aiohttp.ClientSession()
+
+                async with self.session.post(f"{API_BASE_URL}/{opts.model}/get_speech", json=payload, headers=headers) as res:
+                    if res.status != 200:
+                        raise APIError(f"Failed to synthesize speech: {await res.text()}. For more information, visit https://waves.smallest.ai/")
+
+                    audio_content += await res.read()
+
+            if save_as:
+                if not save_as.endswith(".wav"):
+                    raise TTSError("Invalid file name. Extension must be .wav")
+
+                async with aiofiles.open(save_as, mode='wb') as f:
+                    await f.write(add_wav_header(audio_content, opts.sample_rate))
+
+                return None
+
+            if opts.add_wav_header:
+                return add_wav_header(audio_content, opts.sample_rate)
+
+            return audio_content
+        
+        finally:
+            if should_cleanup and self.session:
+                await self.session.close()
+                self.session = None
+
+
+    async def add_voice(self, display_name: str, file_path: str) -> str:
+        """
+        Instantly clone your voice asynchronously.
+
+        Args:
+        - display_name (str): The display name for the new voice.
+        - file_path (str): The path to the reference audio file to be cloned.
+
+        Returns:
+        - str: The response from the API as a formatted JSON string.
+
+        Raises:
+        - TTSError: If the file does not exist or is not a valid audio file.
+        - APIError: If the API request fails or returns an error.
+        """
+        url = f"{API_BASE_URL}/lightning-large/add_voice"
+
+        if not os.path.exists(file_path):
+            raise TTSError("Invalid file path. File does not exist.")
+
+        ALLOWED_AUDIO_EXTENSIONS = ['.mp3', '.wav']
+        file_extension = os.path.splitext(file_path)[1].lower()
+        if file_extension not in ALLOWED_AUDIO_EXTENSIONS:
+            raise TTSError(f"Invalid file type. Supported formats are: {ALLOWED_AUDIO_EXTENSIONS}")
+
+        headers = {
+            'Authorization': f"Bearer {self.api_key}",
+        }
+
+        should_cleanup = await self._ensure_session()
+
+        try:
+            async with aiofiles.open(file_path, 'rb') as f:
+                file_data = await f.read()
+
+            data = aiohttp.FormData()
+            content_type = file_extension[1:]
+            
+            data.add_field('displayName', display_name)
+            data.add_field('file', file_data, filename=file_path, content_type=f"audio/{content_type}")
+
+            async with self.session.post(url, headers=headers, data=data) as res:
+                if res.status != 200:
+                    raise APIError(f"Failed to add voice: {await res.text()}. For more information, visit https://waves.smallest.ai/")
+
+                return json.dumps(await res.json(), indent=4, ensure_ascii=False)
+        
+        finally:
+            if should_cleanup and self.session:
+                await self.session.close()
+                self.session = None
+

smallestai-2.0.0/smallest/models.py

@@ -0,0 +1,5 @@
+TTSLanguages = ["en", "hi"]
+TTSModels = [
+    "lightning", 
+    "lightning-large"
+]