cartesia 1.0.4__tar.gz → 1.0.5__tar.gz

cartesia-1.0.5/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 → cartesia-1.0.5}/PKG-INFO

@@ -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.
@@ -12,6 +12,7 @@ Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
 Provides-Extra: dev
 Provides-Extra: all
+License-File: LICENSE.md
 
 
 # Cartesia Python API Library
@@ -80,10 +81,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",
@@ -131,10 +132,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",
@@ -186,10 +187,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",
@@ -233,7 +234,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
 
@@ -244,13 +245,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",
@@ -322,6 +323,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).
@@ -339,10 +418,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.4 → cartesia-1.0.5}/README.md

@@ -64,10 +64,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",
@@ -115,10 +115,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",
@@ -170,10 +170,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",
@@ -217,7 +217,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
 
@@ -228,13 +228,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",
@@ -306,6 +306,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).
@@ -323,10 +401,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.4 → cartesia-1.0.5}/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-1.0.5/cartesia/version.py

@@ -0,0 +1 @@
+__version__ = "1.0.5"

{cartesia-1.0.4 → cartesia-1.0.5}/cartesia.egg-info/PKG-INFO

@@ -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.
@@ -12,6 +12,7 @@ Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
 Provides-Extra: dev
 Provides-Extra: all
+License-File: LICENSE.md
 
 
 # Cartesia Python API Library
@@ -80,10 +81,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",
@@ -131,10 +132,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",
@@ -186,10 +187,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",
@@ -233,7 +234,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
 
@@ -244,13 +245,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",
@@ -322,6 +323,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).
@@ -339,10 +418,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.4 → cartesia-1.0.5}/cartesia.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+LICENSE.md
 README.md
 pyproject.toml
 setup.py

{cartesia-1.0.4 → cartesia-1.0.5}/cartesia.egg-info/requires.txt

@@ -3,6 +3,7 @@ httpx
 pytest-asyncio
 requests
 websockets
+iterators
 
 [all]
 pytest>=8.0.2

{cartesia-1.0.4 → cartesia-1.0.5}/tests/test_tts.py

@@ -354,9 +354,41 @@ def test_websocket_send_multilingual(resources: _Resources, stream: bool, langua
     
     ws.close()
     
+    
+def chunk_generator(transcripts):
+    for transcript in transcripts:
+        if transcript.endswith(" "):
+            yield transcript
+        else:
+            yield transcript + " "
+            
+def test_sync_continuation_websocket_context_send():
+    logger.info("Testing sync continuation WebSocket context send")
+    client = create_client()
+    ws = client.tts.websocket()
+    context_id = str(uuid.uuid4())
+    try:
+        ctx = ws.context(context_id)
+        transcripts = ["Hello, world!", "I'\''m generating audio on Cartesia."]
+        output_generate = ctx.send(
+            model_id=DEFAULT_MODEL_ID,
+            transcript=chunk_generator(transcripts),
+            voice_id=SAMPLE_VOICE_ID,
+            output_format={
+                "container": "raw",
+                "encoding": "pcm_f32le",
+                "sample_rate": 44100
+            },
+        )
+        for out in output_generate:
+            assert out.keys() == {"audio", "context_id"}
+            assert isinstance(out["audio"], bytes)
+    finally:
+        ws.close()
+    
 @pytest.mark.asyncio
 async def test_continuation_websocket_context_send():
-    logger.info("Testing continuation WebSocket context send")
+    logger.info("Testing async continuation WebSocket context send")
     async_client = create_async_client()
     ws = await async_client.tts.websocket()
     context_id = str(uuid.uuid4())
@@ -387,7 +419,7 @@ async def test_continuation_websocket_context_send():
         
 @pytest.mark.asyncio
 async def test_continuation_websocket_context_send_incorrect_transcript():
-    logger.info("Testing continuation WebSocket context send with incorrect transcript")
+    logger.info("Testing async continuation WebSocket context send with incorrect transcript")
     transcript = "Hello, world! I'\''m generating audio on Cartesia."
     async_client = create_async_client()
     ws = await async_client.tts.websocket()
@@ -421,7 +453,7 @@ async def test_continuation_websocket_context_send_incorrect_transcript():
         
 @pytest.mark.asyncio
 async def test_continuation_websocket_context_send_incorrect_voice_id():
-    logger.info("Testing continuation WebSocket context send with incorrect voice_id")
+    logger.info("Testing async continuation WebSocket context send with incorrect voice_id")
     async_client = create_async_client()
     ws = await async_client.tts.websocket()
     context_id = str(uuid.uuid4())
@@ -454,7 +486,7 @@ async def test_continuation_websocket_context_send_incorrect_voice_id():
         
 @pytest.mark.asyncio
 async def test_continuation_websocket_context_send_incorrect_output_format():
-    logger.info("Testing continuation WebSocket context send with incorrect output_format")
+    logger.info("Testing async continuation WebSocket context send with incorrect output_format")
     async_client = create_async_client()
     ws = await async_client.tts.websocket()
     context_id = str(uuid.uuid4())
@@ -487,7 +519,7 @@ async def test_continuation_websocket_context_send_incorrect_output_format():
         
 @pytest.mark.asyncio
 async def test_continuation_websocket_context_send_incorrect_model_id():
-    logger.info("Testing continuation WebSocket context send with incorrect model_id")
+    logger.info("Testing async continuation WebSocket context send with incorrect model_id")
     async_client = create_async_client()
     ws = await async_client.tts.websocket()
     try:
@@ -516,7 +548,7 @@ async def test_continuation_websocket_context_send_incorrect_model_id():
     
 @pytest.mark.asyncio
 async def test_continuation_websocket_context_send_incorrect_context_id():
-    logger.info("Testing continuation WebSocket context send with incorrect context_id")
+    logger.info("Testing async continuation WebSocket context send with incorrect context_id")
     async_client = create_async_client()
     ws = await async_client.tts.websocket()
     try:
@@ -549,7 +581,7 @@ async def test_continuation_websocket_context_send_incorrect_context_id():
         
 @pytest.mark.asyncio
 async def test_continuation_websocket_context_twice_on_same_context():
-    logger.info("Testing continuation WebSocket context twice on same context")
+    logger.info("Testing async continuation WebSocket context twice on same context")
     async_client = create_async_client()
     ws = await async_client.tts.websocket()
     context_id = str(uuid.uuid4())
@@ -622,7 +654,7 @@ async def context_runner(ws, transcripts):
         
 @pytest.mark.asyncio
 async def test_continuation_websocket_context_three_contexts_parallel():
-    logger.info("Testing continuation WebSocket context three contexts parallel")
+    logger.info("Testing async continuation WebSocket context three contexts parallel")
     async_client = create_async_client()
     ws = await async_client.tts.websocket()
     try:

cartesia-1.0.4/cartesia/version.py

@@ -1 +0,0 @@
-__version__ = "1.0.4"