cartesia 1.0.4__py2.py3-none-any.whl → 1.0.5__py2.py3-none-any.whl

cartesia/client.py

@@ -7,6 +7,7 @@ from types import TracebackType
 from typing import (
     Any,
     AsyncGenerator,
+    Iterator,
     Dict,
     Generator,
     List,
@@ -14,6 +15,7 @@ from typing import (
     Tuple,
     Union,
     Callable,
+    Set,
 )
 
 import aiohttp
@@ -21,6 +23,7 @@ import httpx
 import logging
 import requests
 from websockets.sync.client import connect
+from iterators import TimeoutIterator
 
 from cartesia.utils.retry import retry_on_connection_error, retry_on_connection_error_async
 from cartesia._types import (
@@ -260,6 +263,165 @@ class Voices(Resource):
         return response.json()
 
 
+class _TTSContext:
+    """Manage a single context over a WebSocket.
+
+    This class can be used to stream inputs, as they become available, to a specific `context_id`. See README for usage.
+
+    See :class:`_AsyncTTSContext` for asynchronous use cases.
+
+    Each TTSContext will close automatically when a done message is received for that context. It also closes if there is an error.
+    """
+
+    def __init__(self, context_id: str, websocket: "_WebSocket"):
+        self._context_id = context_id
+        self._websocket = websocket
+        self._error = None
+
+    def __del__(self):
+        self._close()
+
+    @property
+    def context_id(self) -> str:
+        return self._context_id
+
+    def send(
+        self,
+        model_id: str,
+        transcript: Iterator[str],
+        output_format: OutputFormat,
+        voice_id: Optional[str] = None,
+        voice_embedding: Optional[List[float]] = None,
+        context_id: Optional[str] = None,
+        duration: Optional[int] = None,
+        language: Optional[str] = None,
+    ) -> Generator[bytes, None, None]:
+        """Send audio generation requests to the WebSocket and yield responses.
+
+        Args:
+            model_id: The ID of the model to use for generating audio.
+            transcript: Iterator over text chunks with <1s latency.
+            output_format: A dictionary containing the details of the output format.
+            voice_id: The ID of the voice to use for generating audio.
+            voice_embedding: The embedding of the voice to use for generating audio.
+            context_id: The context ID to use for the request. If not specified, a random context ID will be generated.
+            duration: The duration of the audio in seconds.
+            language: The language code for the audio request. This can only be used with `model_id = sonic-multilingual`
+
+        Yields:
+            Dictionary containing the following key(s):
+            - audio: The audio as bytes.
+            - context_id: The context ID for the request.
+
+        Raises:
+            ValueError: If provided context_id doesn't match the current context.
+            RuntimeError: If there's an error generating audio.
+        """
+        if context_id is not None and context_id != self._context_id:
+            raise ValueError("Context ID does not match the context ID of the current context.")
+
+        self._websocket.connect()
+
+        voice = self._websocket._validate_and_construct_voice(voice_id, voice_embedding)
+
+        # Create the initial request body
+        request_body = {
+            "model_id": model_id,
+            "voice": voice,
+            "output_format": {
+                "container": output_format["container"],
+                "encoding": output_format["encoding"],
+                "sample_rate": output_format["sample_rate"],
+            },
+            "context_id": self._context_id,
+            "language": language,
+        }
+
+        if duration is not None:
+            request_body["duration"] = duration
+
+        try:
+            # Create an iterator with a timeout to get text chunks
+            text_iterator = TimeoutIterator(
+                transcript, timeout=0.001
+            )  # 1ms timeout for nearly non-blocking receive
+            next_chunk = next(text_iterator, None)
+
+            while True:
+                # Send the next text chunk to the WebSocket if available
+                if next_chunk is not None and next_chunk != text_iterator.get_sentinel():
+                    request_body["transcript"] = next_chunk
+                    request_body["continue"] = True
+                    self._websocket.websocket.send(json.dumps(request_body))
+                    next_chunk = next(text_iterator, None)
+
+                try:
+                    # Receive responses from the WebSocket with a small timeout
+                    response = json.loads(
+                        self._websocket.websocket.recv(timeout=0.001)
+                    )  # 1ms timeout for nearly non-blocking receive
+                    if response["context_id"] != self._context_id:
+                        pass
+                    if "error" in response:
+                        raise RuntimeError(f"Error generating audio:\n{response['error']}")
+                    if response["done"]:
+                        break
+                    if response["data"]:
+                        yield self._websocket._convert_response(
+                            response=response, include_context_id=True
+                        )
+                except TimeoutError:
+                    pass
+
+                # Continuously receive from WebSocket until the next text chunk is available
+                while next_chunk == text_iterator.get_sentinel():
+                    try:
+                        response = json.loads(self._websocket.websocket.recv(timeout=0.001))
+                        if response["context_id"] != self._context_id:
+                            continue
+                        if "error" in response:
+                            raise RuntimeError(f"Error generating audio:\n{response['error']}")
+                        if response["done"]:
+                            break
+                        if response["data"]:
+                            yield self._websocket._convert_response(
+                                response=response, include_context_id=True
+                            )
+                    except TimeoutError:
+                        pass
+                    next_chunk = next(text_iterator, None)
+
+                # Send final message if all input text chunks are exhausted
+                if next_chunk is None:
+                    request_body["transcript"] = ""
+                    request_body["continue"] = False
+                    self._websocket.websocket.send(json.dumps(request_body))
+                    break
+
+            # Receive remaining messages from the WebSocket until "done" is received
+            while True:
+                response = json.loads(self._websocket.websocket.recv())
+                if response["context_id"] != self._context_id:
+                    continue
+                if "error" in response:
+                    raise RuntimeError(f"Error generating audio:\n{response['error']}")
+                if response["done"]:
+                    break
+                yield self._websocket._convert_response(response=response, include_context_id=True)
+
+        except Exception as e:
+            self._websocket.close()
+            raise RuntimeError(f"Failed to generate audio. {e}")
+
+    def _close(self):
+        """Closes the context. Automatically called when a done message is received for this context."""
+        self._websocket._remove_context(self._context_id)
+
+    def is_closed(self):
+        """Check if the context is closed or not. Returns True if closed."""
+        return self._context_id not in self._websocket._contexts
+
+
 class _WebSocket:
     """This class contains methods to generate audio using WebSocket. Ideal for low-latency audio generation.
 
@@ -283,6 +445,13 @@ class _WebSocket:
         self.api_key = api_key
         self.cartesia_version = cartesia_version
         self.websocket = None
+        self._contexts: Set[str] = set()
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception as e:
+            raise RuntimeError("Failed to close WebSocket: ", e)
 
     def connect(self):
         """This method connects to the WebSocket if it is not already connected.
@@ -304,9 +473,12 @@ class _WebSocket:
 
     def close(self):
         """This method closes the WebSocket connection. *Highly* recommended to call this method when done using the WebSocket."""
-        if self.websocket is not None and not self._is_websocket_closed():
+        if self.websocket and not self._is_websocket_closed():
             self.websocket.close()
 
+        if self._contexts:
+            self._contexts.clear()
+
     def _convert_response(
         self, response: Dict[str, any], include_context_id: bool
     ) -> Dict[str, Any]:
@@ -426,10 +598,22 @@ class _WebSocket:
                 yield self._convert_response(response=response, include_context_id=True)
         except Exception as e:
             # Close the websocket connection if an error occurs.
-            if self.websocket and not self._is_websocket_closed():
-                self.websocket.close()
+            self.close()
             raise RuntimeError(f"Failed to generate audio. {response}") from e
 
+    def _remove_context(self, context_id: str):
+        if context_id in self._contexts:
+            self._contexts.remove(context_id)
+
+    def context(self, context_id: Optional[str] = None) -> _TTSContext:
+        if context_id in self._contexts:
+            raise ValueError(f"Context for context ID {context_id} already exists.")
+        if context_id is None:
+            context_id = str(uuid.uuid4())
+        if context_id not in self._contexts:
+            self._contexts.add(context_id)
+        return _TTSContext(context_id, self)
+
 
 class _SSE:
     """This class contains methods to generate audio using Server-Sent Events.
@@ -826,7 +1010,7 @@ class _AsyncSSE(_SSE):
 
 
 class _AsyncTTSContext:
-    """Manage a single context over a WebSocket.
+    """Manage a single context over an AsyncWebSocket.
 
     This class separates sending requests and receiving responses into two separate methods.
     This can be used for sending multiple requests without awaiting the response.
@@ -945,6 +1129,10 @@ class _AsyncTTSContext:
         """Closes the context. Automatically called when a done message is received for this context."""
         self._websocket._remove_context(self._context_id)
 
+    def is_closed(self):
+        """Check if the context is closed or not. Returns True if closed."""
+        return self._context_id not in self._websocket._context_queues
+
     async def __aenter__(self):
         return self
 

cartesia/version.py

@@ -1 +1 @@
-__version__ = "1.0.4"
+__version__ = "1.0.5"

cartesia-1.0.5.dist-info/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cartesia AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{cartesia-1.0.4.dist-info → cartesia-1.0.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 1.0.4
+Version: 1.0.5
 Summary: The official Python library for the Cartesia API.
 Home-page: 
 Author: Cartesia, Inc.
@@ -10,11 +10,13 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
+License-File: LICENSE.md
 Requires-Dist: aiohttp
 Requires-Dist: httpx
 Requires-Dist: pytest-asyncio
 Requires-Dist: requests
 Requires-Dist: websockets
+Requires-Dist: iterators
 Provides-Extra: all
 Requires-Dist: pytest >=8.0.2 ; extra == 'all'
 Requires-Dist: pytest-cov >=4.1.0 ; extra == 'all'
@@ -97,10 +99,10 @@ voice = client.voices.get(id=voice_id)
 
 transcript = "Hello! Welcome to Cartesia"
 
-# You can check out our models at [docs.cartesia.ai](https://docs.cartesia.ai/getting-started/available-models).
+# You can check out our models at https://docs.cartesia.ai/getting-started/available-models
 model_id = "sonic-english"
 
-# You can find the supported `output_format`s in our [API Reference](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events).
+# You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events
 output_format = {
     "container": "raw",
     "encoding": "pcm_f32le",
@@ -148,10 +150,10 @@ async def write_stream():
     voice_id = "a0e99841-438c-4a64-b679-ae501e7d6091"
     voice = client.voices.get(id=voice_id)
     transcript = "Hello! Welcome to Cartesia"
-    # You can check out our models at [docs.cartesia.ai](https://docs.cartesia.ai/getting-started/available-models).
+    # You can check out our models at https://docs.cartesia.ai/getting-started/available-models
     model_id = "sonic-english"
 
-    # You can find the supported `output_format`s in our [API Reference](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events).
+    # You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events
     output_format = {
         "container": "raw",
         "encoding": "pcm_f32le",
@@ -203,10 +205,10 @@ voice_id = "a0e99841-438c-4a64-b679-ae501e7d6091"
 voice = client.voices.get(id=voice_id)
 transcript = "Hello! Welcome to Cartesia"
 
-# You can check out our models at [docs.cartesia.ai](https://docs.cartesia.ai/getting-started/available-models).
+# You can check out our models at https://docs.cartesia.ai/getting-started/available-models
 model_id = "sonic-english"
 
-# You can find the supported `output_format`s in our [API Reference](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events).
+# You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events
 output_format = {
     "container": "raw",
     "encoding": "pcm_f32le",
@@ -250,7 +252,7 @@ In some cases, input text may need to be streamed in. In these cases, it would b
 
 To mitigate this, Cartesia offers audio continuations. In this setting, users can send input text, as it becomes available, over a websocket connection.
 
-To do this, we will create a `context` and sending multiple requests without awaiting the response. Then you can listen to the responses in the order they were sent.
+To do this, we will create a `context` and send multiple requests without awaiting the response. Then you can listen to the responses in the order they were sent.
 
 Each `context` will be closed automatically after 5 seconds of inactivity or when the `no_more_inputs` method is called. `no_more_inputs` sends a request with the `continue_=False`, which indicates no more inputs will be sent over this context
 
@@ -261,13 +263,13 @@ import pyaudio
 from cartesia import AsyncCartesia
 
 async def send_transcripts(ctx):
-    # Check out voice IDs by calling `client.voices.list()` or on [play.cartesia.ai](https://play.cartesia.ai/)
+    # Check out voice IDs by calling `client.voices.list()` or on https://play.cartesia.ai/
     voice_id = "87748186-23bb-4158-a1eb-332911b0b708"
 
-    # You can check out our models at [docs.cartesia.ai](https://docs.cartesia.ai/getting-started/available-models).
+    # You can check out our models at https://docs.cartesia.ai/getting-started/available-models
     model_id = "sonic-english"
     
-    # You can find the supported `output_format`s in our [API Reference](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events).
+    # You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events
     output_format = {
         "container": "raw",
         "encoding": "pcm_f32le",
@@ -339,6 +341,84 @@ async def stream_and_listen():
 asyncio.run(stream_and_listen())
 ```
 
+You can also use continuations on the synchronous Cartesia client to stream in text as it becomes available. To do this, pass in a text generator that produces text chunks at intervals of less than 1 second, as shown below. This ensures smooth audio playback.
+
+Note: the sync client has a different API for continuations compared to the async client.
+
+```python
+from cartesia import Cartesia
+import pyaudio
+import os
+
+client = Cartesia(api_key=os.environ.get("CARTESIA_API_KEY"))
+
+transcripts = [
+    "The crew engaged in a range of activities designed to mirror those "
+    "they might perform on a real Mars mission. ",
+    "Aside from growing vegetables and maintaining their habitat, they faced "
+    "additional stressors like communication delays with Earth, ",
+    "up to twenty-two minutes each way, to simulate the distance from Mars to our planet. ",
+    "These exercises were critical for understanding how astronauts can "
+    "maintain not just physical health but also mental well-being under such challenging conditions. ",
+]
+
+# Ending each transcript with a space makes the audio smoother
+def chunk_generator(transcripts):
+    for transcript in transcripts:
+        if transcript.endswith(" "):
+            yield transcript
+        else:
+            yield transcript + " "
+
+
+# You can check out voice IDs by calling `client.voices.list()` or on https://play.cartesia.ai/
+voice_id = "87748186-23bb-4158-a1eb-332911b0b708"
+
+# You can check out our models at https://docs.cartesia.ai/getting-started/available-models
+model_id = "sonic-english"
+
+# You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events
+output_format = {
+    "container": "raw",
+    "encoding": "pcm_f32le",
+    "sample_rate": 44100,
+}
+
+p = pyaudio.PyAudio()
+rate = 44100
+
+stream = None
+
+# Set up the websocket connection
+ws = client.tts.websocket()
+
+# Create a context to send and receive audio
+ctx = ws.context()  # Generates a random context ID if not provided
+
+# Pass in a text generator to generate & stream the audio
+output_stream = ctx.send(
+    model_id=model_id,
+    transcript=chunk_generator(transcripts),
+    voice_id=voice_id,
+    output_format=output_format,
+)
+    
+for output in output_stream:
+    buffer = output["audio"]
+
+    if not stream:
+        stream = p.open(format=pyaudio.paFloat32, channels=1, rate=rate, output=True)
+
+    # Write the audio data to the stream
+    stream.write(buffer)
+
+stream.stop_stream()
+stream.close()
+p.terminate()
+
+ws.close()  # Close the websocket connection
+```
+
 ### Multilingual Text-to-Speech [Alpha]
 
 You can use our `sonic-multilingual` model to generate audio in multiple languages. The languages supported are available at [docs.cartesia.ai](https://docs.cartesia.ai/getting-started/available-models).
@@ -356,10 +436,10 @@ voice = client.voices.get(id=voice_id)
 transcript = "Hola! Bienvenido a Cartesia"
 language = "es"  # Language code corresponding to the language of the transcript
 
-# Make sure you use the multilingual model! You can check out all models at [docs.cartesia.ai](https://docs.cartesia.ai/getting-started/available-models).
+# Make sure you use the multilingual model! You can check out all models at https://docs.cartesia.ai/getting-started/available-models
 model_id = "sonic-multilingual"
 
-# You can find the supported `output_format`s in our [API Reference](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events).
+# You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events
 output_format = {
     "container": "raw",
     "encoding": "pcm_f32le",

cartesia-1.0.5.dist-info/RECORD

@@ -0,0 +1,12 @@
+cartesia/__init__.py,sha256=jMIf2O7dTGxvTA5AfXtmh1H_EGfMtQseR5wXrjNRbLs,93
+cartesia/_types.py,sha256=tO3Nef_V78TDMKDuIv_wsQLkxoSvYG4bdzFkMGXUFho,3765
+cartesia/client.py,sha256=46XiKTXa0gBXJ_GftMtLHAzBoX0GmWz_aWYuG68jaNQ,49316
+cartesia/version.py,sha256=B9kKWJLln1i8LjtkcYecvNWGLTrez4gCUOHtnPlInFo,22
+cartesia/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cartesia/utils/deprecated.py,sha256=2cXvGtrxhPeUZA5LWy2n_U5OFLDv7SHeFtzqhjSJGyk,1674
+cartesia/utils/retry.py,sha256=nuwWRfu3MOVTxIQMLjYf6WLaxSlnu_GdE3QjTV0zisQ,3339
+cartesia-1.0.5.dist-info/LICENSE.md,sha256=PT2YG5wEtEX1TNDn5sXkUXqbn-neyr7cZenTxd40ql4,1074
+cartesia-1.0.5.dist-info/METADATA,sha256=PImHYCNoo7iSnm3Br6PuRdqvli92c7AyXR4iagdv-d8,18368
+cartesia-1.0.5.dist-info/WHEEL,sha256=DZajD4pwLWue70CAfc7YaxT1wLUciNBvN_TTcvXpltE,110
+cartesia-1.0.5.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
+cartesia-1.0.5.dist-info/RECORD,,

cartesia-1.0.4.dist-info/RECORD

@@ -1,11 +0,0 @@
-cartesia/__init__.py,sha256=jMIf2O7dTGxvTA5AfXtmh1H_EGfMtQseR5wXrjNRbLs,93
-cartesia/_types.py,sha256=tO3Nef_V78TDMKDuIv_wsQLkxoSvYG4bdzFkMGXUFho,3765
-cartesia/client.py,sha256=UCNTAU8eVzb-o-bygxfQQXWTDov_FX8dbAQdn7a8Hr0,41458
-cartesia/version.py,sha256=acuR_XSJzp4OrQ5T8-Ac5gYe48mUwObuwjRmisFmZ7k,22
-cartesia/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cartesia/utils/deprecated.py,sha256=2cXvGtrxhPeUZA5LWy2n_U5OFLDv7SHeFtzqhjSJGyk,1674
-cartesia/utils/retry.py,sha256=nuwWRfu3MOVTxIQMLjYf6WLaxSlnu_GdE3QjTV0zisQ,3339
-cartesia-1.0.4.dist-info/METADATA,sha256=N7NoGr6XBtmLI6EHsG3efw0QNJ7uhV_E9HV8uqTYfQM,15991
-cartesia-1.0.4.dist-info/WHEEL,sha256=DZajD4pwLWue70CAfc7YaxT1wLUciNBvN_TTcvXpltE,110
-cartesia-1.0.4.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
-cartesia-1.0.4.dist-info/RECORD,,