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

cartesia/_types.py

@@ -70,7 +70,31 @@ class VoiceMetadata(TypedDict):
     language: str
 
 
+class VoiceControls(TypedDict):
+    """Defines different voice control parameters for voice synthesis.
+
+    For a complete list of supported parameters, refer to the Cartesia API documentation.
+    https://docs.cartesia.ai/getting-started/welcome
+
+    Examples:
+        >>> {"speed": "fastest"}
+        >>> {"speed": "slow", "emotion": "anger:high, positivity:low"}
+        >>> {"emotion": "surprise:high, positivity:high"}
+
+    Note:
+        This is an experimental class and is subject to rapid change in future versions.
+    """
+    speed: str = ""
+    emotion: str = ""
+
+
 class OutputFormat(TypedDict):
     container: str
     encoding: str
     sample_rate: int
+
+
+class EventType:
+    NULL = ""
+    AUDIO = "chunk"
+    TIMESTAMPS = "timestamps"

cartesia/client.py

@@ -1,5 +1,6 @@
 import asyncio
 import base64
+from collections import defaultdict
 import json
 import os
 import uuid
@@ -7,6 +8,7 @@ from types import TracebackType
 from typing import (
     Any,
     AsyncGenerator,
+    Iterator,
     Dict,
     Generator,
     List,
@@ -14,6 +16,7 @@ from typing import (
     Tuple,
     Union,
     Callable,
+    Set,
 )
 
 import aiohttp
@@ -21,12 +24,15 @@ 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 (
+    EventType,
     OutputFormat,
     OutputFormatMapping,
     DeprecatedOutputFormatMapping,
+    VoiceControls,
     VoiceMetadata,
 )
 
@@ -260,6 +266,168 @@ 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,
+        _experimental_voice_controls: Optional[VoiceControls] = 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`
+            _experimental_voice_controls: Experimental voice controls for controlling speed and emotion.
+                Note: This is an experimental feature and may change rapidly in future releases.
+
+        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 = _validate_and_construct_voice(voice_id, voice_embedding=voice_embedding, experimental_voice_controls = _experimental_voice_controls)
+
+        # 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 +451,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,48 +479,25 @@ 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]:
-        audio = base64.b64decode(response["data"])
-
-        optional_kwargs = {}
+        out = {}
+        if response["type"] == EventType.AUDIO:
+            out["audio"] = base64.b64decode(response["data"])
+        elif response["type"] == EventType.TIMESTAMPS:
+            out["word_timestamps"] = response["word_timestamps"]
+        
         if include_context_id:
-            optional_kwargs["context_id"] = response["context_id"]
-
-        return {
-            "audio": audio,
-            **optional_kwargs,
-        }
-
-    def _validate_and_construct_voice(
-        self, voice_id: Optional[str] = None, voice_embedding: Optional[List[float]] = None
-    ) -> dict:
-        """Validate and construct the voice dictionary for the request.
-
-        Args:
-            voice_id: The ID of the voice to use for generating audio.
-            voice_embedding: The embedding of the voice to use for generating audio.
-
-        Returns:
-            A dictionary representing the voice configuration.
-
-        Raises:
-            ValueError: If neither or both voice_id and voice_embedding are specified.
-        """
-        if voice_id is None and voice_embedding is None:
-            raise ValueError("Either voice_id or voice_embedding must be specified.")
+            out["context_id"] = response["context_id"]
 
-        if voice_id is not None and voice_embedding is not None:
-            raise ValueError("Only one of voice_id or voice_embedding should be specified.")
-
-        if voice_id:
-            return {"mode": "id", "id": voice_id}
-
-        return {"mode": "embedding", "embedding": voice_embedding}
+        return out
 
     def send(
         self,
@@ -358,6 +510,8 @@ class _WebSocket:
         duration: Optional[int] = None,
         language: Optional[str] = None,
         stream: bool = True,
+        add_timestamps: bool = False,
+        _experimental_voice_controls: Optional[VoiceControls] = None,
     ) -> Union[bytes, Generator[bytes, None, None]]:
         """Send a request to the WebSocket to generate audio.
 
@@ -371,6 +525,9 @@ class _WebSocket:
             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`
             stream: Whether to stream the audio or not.
+            add_timestamps: Whether to return word-level timestamps.
+            _experimental_voice_controls: Experimental voice controls for controlling speed and emotion.
+                Note: This is an experimental feature and may change rapidly in future releases.
 
         Returns:
             If `stream` is True, the method returns a generator that yields chunks. Each chunk is a dictionary.
@@ -384,7 +541,7 @@ class _WebSocket:
         if context_id is None:
             context_id = str(uuid.uuid4())
 
-        voice = self._validate_and_construct_voice(voice_id, voice_embedding)
+        voice = _validate_and_construct_voice(voice_id, voice_embedding=voice_embedding, experimental_voice_controls = _experimental_voice_controls)
 
         request_body = {
             "model_id": model_id,
@@ -397,6 +554,7 @@ class _WebSocket:
             },
             "context_id": context_id,
             "language": language,
+            "add_timestamps": add_timestamps,
         }
 
         if duration is not None:
@@ -408,10 +566,17 @@ class _WebSocket:
             return generator
 
         chunks = []
+        word_timestamps = defaultdict(list)
         for chunk in generator:
-            chunks.append(chunk["audio"])
-
-        return {"audio": b"".join(chunks), "context_id": context_id}
+            if "audio" in chunk:
+                chunks.append(chunk["audio"])
+            if add_timestamps and "word_timestamps" in chunk:
+                for k, v in chunk["word_timestamps"].items():
+                    word_timestamps[k].extend(v)
+        out = {"audio": b"".join(chunks), "context_id": context_id}
+        if add_timestamps:
+            out["word_timestamps"] = word_timestamps
+        return out
 
     def _websocket_generator(self, request_body: Dict[str, Any]):
         self.websocket.send(json.dumps(request_body))
@@ -426,10 +591,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.
@@ -472,32 +649,6 @@ class _SSE:
                     break
         return buffer, outputs
 
-    def _validate_and_construct_voice(
-        self, voice_id: Optional[str] = None, voice_embedding: Optional[List[float]] = None
-    ) -> dict:
-        """Validate and construct the voice dictionary for the request.
-
-        Args:
-            voice_id: The ID of the voice to use for generating audio.
-            voice_embedding: The embedding of the voice to use for generating audio.
-
-        Returns:
-            A dictionary representing the voice configuration.
-
-        Raises:
-            ValueError: If neither or both voice_id and voice_embedding are specified.
-        """
-        if voice_id is None and voice_embedding is None:
-            raise ValueError("Either voice_id or voice_embedding must be specified.")
-
-        if voice_id is not None and voice_embedding is not None:
-            raise ValueError("Only one of voice_id or voice_embedding should be specified.")
-
-        if voice_id:
-            return {"mode": "id", "id": voice_id}
-
-        return {"mode": "embedding", "embedding": voice_embedding}
-
     def send(
         self,
         model_id: str,
@@ -508,6 +659,7 @@ class _SSE:
         duration: Optional[int] = None,
         language: Optional[str] = None,
         stream: bool = True,
+        _experimental_voice_controls: Optional[VoiceControls] = None,
     ) -> Union[bytes, Generator[bytes, None, None]]:
         """Send a request to the server to generate audio using Server-Sent Events.
 
@@ -520,6 +672,8 @@ class _SSE:
             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`
             stream: Whether to stream the audio or not.
+            _experimental_voice_controls: Experimental voice controls for controlling speed and emotion.
+                Note: This is an experimental feature and may change rapidly in future releases.
 
         Returns:
             If `stream` is True, the method returns a generator that yields chunks. Each chunk is a dictionary.
@@ -527,8 +681,7 @@ class _SSE:
             Both the generator and the dictionary contain the following key(s):
             - audio: The audio as bytes.
         """
-        voice = self._validate_and_construct_voice(voice_id, voice_embedding)
-
+        voice = _validate_and_construct_voice(voice_id, voice_embedding=voice_embedding, experimental_voice_controls=_experimental_voice_controls)
         request_body = {
             "model_id": model_id,
             "transcript": transcript,
@@ -762,8 +915,9 @@ class _AsyncSSE(_SSE):
         duration: Optional[int] = None,
         language: Optional[str] = None,
         stream: bool = True,
+        _experimental_voice_controls: Optional[VoiceControls] = None,
     ) -> Union[bytes, AsyncGenerator[bytes, None]]:
-        voice = self._validate_and_construct_voice(voice_id, voice_embedding)
+        voice = _validate_and_construct_voice(voice_id, voice_embedding=voice_embedding,experimental_voice_controls=_experimental_voice_controls)
 
         request_body = {
             "model_id": model_id,
@@ -826,7 +980,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.
@@ -859,6 +1013,8 @@ class _AsyncTTSContext:
         continue_: bool = False,
         duration: Optional[int] = None,
         language: Optional[str] = None,
+        add_timestamps: bool = False,
+        _experimental_voice_controls: Optional[VoiceControls] = None,
     ) -> None:
         """Send audio generation requests to the WebSocket. The response can be received using the `receive` method.
 
@@ -871,7 +1027,10 @@ class _AsyncTTSContext:
             context_id: The context ID to use for the request. If not specified, a random context ID will be generated.
             continue_: Whether to continue the audio generation from the previous transcript or not.
             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`
+            language: The language code for the audio request. This can only be used with `model_id = sonic-multilingual`.
+            add_timestamps: Whether to return word-level timestamps.
+            _experimental_voice_controls: Experimental voice controls for controlling speed and emotion.
+                Note: This is an experimental feature and may change rapidly in future releases.
 
         Returns:
             None.
@@ -883,7 +1042,7 @@ class _AsyncTTSContext:
 
         await self._websocket.connect()
 
-        voice = self._websocket._validate_and_construct_voice(voice_id, voice_embedding)
+        voice = _validate_and_construct_voice(voice_id, voice_embedding, experimental_voice_controls=_experimental_voice_controls)
 
         request_body = {
             "model_id": model_id,
@@ -897,6 +1056,7 @@ class _AsyncTTSContext:
             "context_id": self._context_id,
             "continue": continue_,
             "language": language,
+            "add_timestamps": add_timestamps,
         }
 
         if duration is not None:
@@ -945,6 +1105,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
 
@@ -1046,7 +1210,10 @@ class _AsyncWebSocket(_WebSocket):
         duration: Optional[int] = None,
         language: Optional[str] = None,
         stream: bool = True,
+        add_timestamps: bool = False,
+        _experimental_voice_controls: Optional[VoiceControls] = None,
     ) -> Union[bytes, AsyncGenerator[bytes, None]]:
+        """See :meth:`_WebSocket.send` for details."""
         if context_id is None:
             context_id = str(uuid.uuid4())
 
@@ -1062,6 +1229,8 @@ class _AsyncWebSocket(_WebSocket):
             duration=duration,
             language=language,
             continue_=False,
+            add_timestamps = add_timestamps,
+            _experimental_voice_controls=_experimental_voice_controls,
         )
 
         generator = ctx.receive()
@@ -1070,10 +1239,17 @@ class _AsyncWebSocket(_WebSocket):
             return generator
 
         chunks = []
+        word_timestamps = defaultdict(list)
         async for chunk in generator:
-            chunks.append(chunk["audio"])
-
-        return {"audio": b"".join(chunks), "context_id": context_id}
+            if "audio" in chunk:
+                chunks.append(chunk["audio"])
+            if add_timestamps and "word_timestamps" in chunk:
+                for k, v in chunk["word_timestamps"].items():
+                    word_timestamps[k].extend(v)
+        out = {"audio": b"".join(chunks), "context_id": context_id}
+        if add_timestamps:
+            out["word_timestamps"] = word_timestamps
+        return out
 
     async def _process_responses(self):
         try:
@@ -1123,3 +1299,35 @@ class AsyncTTS(TTS):
         )
         await ws.connect()
         return ws
+
+
+def _validate_and_construct_voice(
+    voice_id: Optional[str] = None, voice_embedding: Optional[List[float]] = None, experimental_voice_controls: Optional[VoiceControls] = None
+) -> dict:
+    """Validate and construct the voice dictionary for the request.
+
+    Args:
+        voice_id: The ID of the voice to use for generating audio.
+        voice_embedding: The embedding of the voice to use for generating audio.
+        experimental_voice_controls: Voice controls for emotion and speed.
+            Note: This is an experimental feature and may rapidly change in the future.
+
+    Returns:
+        A dictionary representing the voice configuration.
+
+    Raises:
+        ValueError: If neither or both voice_id and voice_embedding are specified.
+    """
+    if voice_id is None and voice_embedding is None:
+        raise ValueError("Either voice_id or voice_embedding must be specified.")
+
+    if voice_id is not None and voice_embedding is not None:
+        raise ValueError("Only one of voice_id or voice_embedding should be specified.")
+
+    if voice_id:
+        voice = {"mode": "id", "id": voice_id}
+    else:
+        voice = {"mode": "embedding", "embedding": voice_embedding}
+    if experimental_voice_controls is not None:
+        voice["__experimental_controls"] = experimental_voice_controls
+    return voice

cartesia/version.py

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

cartesia-1.0.6.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.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 1.0.4
+Version: 1.0.6
 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.6.dist-info/RECORD

@@ -0,0 +1,12 @@
+cartesia/__init__.py,sha256=jMIf2O7dTGxvTA5AfXtmh1H_EGfMtQseR5wXrjNRbLs,93
+cartesia/_types.py,sha256=l3tKFnyUInn5_OJOSB63Mp1g16p9R23VNAuJ5qykOzY,4424
+cartesia/client.py,sha256=zLyxaDkX0et6lY_hthSgDA-eoP6NXEN5ysDsxxseyZQ,51502
+cartesia/version.py,sha256=mqMuQB3aqJVPrHHqJMLjqiMKUiJjozc7EPLcX5DpKHg,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.6.dist-info/LICENSE.md,sha256=PT2YG5wEtEX1TNDn5sXkUXqbn-neyr7cZenTxd40ql4,1074
+cartesia-1.0.6.dist-info/METADATA,sha256=JcNWr0UHSp_GK3X05YD92zbLZonV0BkeyuzT90HuGSs,18368
+cartesia-1.0.6.dist-info/WHEEL,sha256=DZajD4pwLWue70CAfc7YaxT1wLUciNBvN_TTcvXpltE,110
+cartesia-1.0.6.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
+cartesia-1.0.6.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,,