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

cartesia/_types.py

@@ -45,15 +45,16 @@ class DeprecatedOutputFormatMapping:
         "mulaw_8000": {"container": "raw", "encoding": "pcm_mulaw", "sample_rate": 8000},
         "alaw_8000": {"container": "raw", "encoding": "pcm_alaw", "sample_rate": 8000},
     }
-
+    
+    @classmethod
     @deprecated(
         vdeprecated="1.0.1",
         vremove="1.2.0",
         reason="Old output format names are being deprecated in favor of names aligned with the Cartesia API. Use names from `OutputFormatMapping` instead.",
     )
-    def get_format_deprecated(self, format_name):
-        if format_name in self._format_mapping:
-            return self._format_mapping[format_name]
+    def get_format_deprecated(cls, format_name):
+        if format_name in cls._format_mapping:
+            return cls._format_mapping[format_name]
         else:
             raise ValueError(f"Unsupported format: {format_name}")
 

cartesia/client.py

@@ -4,7 +4,17 @@ import json
 import os
 import uuid
 from types import TracebackType
-from typing import Any, AsyncGenerator, Dict, Generator, List, Optional, Tuple, Union, Callable
+from typing import (
+    Any,
+    AsyncGenerator,
+    Dict,
+    Generator,
+    List,
+    Optional,
+    Tuple,
+    Union,
+    Callable,
+)
 
 import aiohttp
 import httpx
@@ -13,7 +23,6 @@ import requests
 from websockets.sync.client import connect
 
 from cartesia.utils.retry import retry_on_connection_error, retry_on_connection_error_async
-from cartesia.utils.deprecated import deprecated
 from cartesia._types import (
     OutputFormat,
     OutputFormatMapping,
@@ -36,22 +45,34 @@ logger = logging.getLogger(__name__)
 
 
 class BaseClient:
-    def __init__(self, *, api_key: Optional[str] = None, timeout: float = DEFAULT_TIMEOUT):
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
         """Constructor for the BaseClient. Used by the Cartesia and AsyncCartesia clients."""
         self.api_key = api_key or os.environ.get("CARTESIA_API_KEY")
+        self._base_url = base_url or os.environ.get("CARTESIA_BASE_URL", DEFAULT_BASE_URL)
         self.timeout = timeout
 
+    @property
+    def base_url(self):
+        return self._base_url
+
 
 class Resource:
     def __init__(
         self,
         api_key: str,
+        base_url: str,
         timeout: float,
     ):
         """Constructor for the Resource class. Used by the Voices and TTS classes."""
         self.api_key = api_key
         self.timeout = timeout
-        self.base_url = os.environ.get("CARTESIA_BASE_URL", DEFAULT_BASE_URL)
+        self._base_url = base_url
         self.cartesia_version = DEFAULT_CARTESIA_VERSION
         self.headers = {
             "X-API-Key": self.api_key,
@@ -59,25 +80,29 @@ class Resource:
             "Content-Type": "application/json",
         }
 
+    @property
+    def base_url(self):
+        return self._base_url
+
     def _http_url(self):
         """Returns the HTTP URL for the Cartesia API.
         If the base URL is localhost, the URL will start with 'http'. Otherwise, it will start with 'https'.
         """
-        if self.base_url.startswith("http://") or self.base_url.startswith("https://"):
-            return self.base_url
+        if self._base_url.startswith("http://") or self._base_url.startswith("https://"):
+            return self._base_url
         else:
-            prefix = "http" if "localhost" in self.base_url else "https"
-            return f"{prefix}://{self.base_url}"
+            prefix = "http" if "localhost" in self._base_url else "https"
+            return f"{prefix}://{self._base_url}"
 
     def _ws_url(self):
         """Returns the WebSocket URL for the Cartesia API.
         If the base URL is localhost, the URL will start with 'ws'. Otherwise, it will start with 'wss'.
         """
-        if self.base_url.startswith("ws://") or self.base_url.startswith("wss://"):
-            return self.base_url
+        if self._base_url.startswith("ws://") or self._base_url.startswith("wss://"):
+            return self._base_url
         else:
-            prefix = "ws" if "localhost" in self.base_url else "wss"
-            return f"{prefix}://{self.base_url}"
+            prefix = "ws" if "localhost" in self._base_url else "wss"
+            return f"{prefix}://{self._base_url}"
 
 
 class Cartesia(BaseClient):
@@ -90,18 +115,27 @@ class Cartesia(BaseClient):
     The client supports generating audio using both Server-Sent Events and WebSocket for lower latency.
     """
 
-    def __init__(self, *, api_key: Optional[str] = None, timeout: float = DEFAULT_TIMEOUT):
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
         """Constructor for the Cartesia client.
 
         Args:
             api_key: The API key to use for authorization.
                 If not specified, the API key will be read from the environment variable
                 `CARTESIA_API_KEY`.
-            timeout: The timeout for the HTTP requests in seconds. Defaults to 30 seconds.
+            base_url: The base URL for the Cartesia API.
+                If not specified, the base URL will be read from the enviroment variable
+                `CARTESIA_BASE_URL`. Defaults to `api.cartesia.ai`.
+            timeout: The timeout for HTTP and WebSocket requests in seconds. Defaults to 30 seconds.
         """
-        super().__init__(api_key=api_key, timeout=timeout)
-        self.voices = Voices(api_key=self.api_key, timeout=self.timeout)
-        self.tts = TTS(api_key=self.api_key, timeout=self.timeout)
+        super().__init__(api_key=api_key, base_url=base_url, timeout=timeout)
+        self.voices = Voices(api_key=self.api_key, base_url=self._base_url, timeout=self.timeout)
+        self.tts = TTS(api_key=self.api_key, base_url=self._base_url, timeout=self.timeout)
 
     def __enter__(self):
         return self
@@ -188,7 +222,6 @@ class Voices(Resource):
                 files = {"clip": file}
                 headers = self.headers.copy()
                 headers.pop("Content-Type", None)
-                headers["Content-Type"] = "multipart/form-data"
                 response = httpx.post(url, headers=headers, files=files, timeout=self.timeout)
                 if not response.is_success:
                     raise ValueError(f"Failed to clone voice from clip. Error: {response.text}")
@@ -233,8 +266,9 @@ class _WebSocket:
     Usage:
         >>> ws = client.tts.websocket()
         >>> for audio_chunk in ws.send(
-        ...     model_id="upbeat-moon", transcript="Hello world!", voice_embedding=embedding,
-        ...     output_format={"container": "raw", "encoding": "pcm_f32le", "sample_rate": 44100}, stream=True
+        ...     model_id="sonic-english", transcript="Hello world!", voice_embedding=embedding,
+        ...     output_format={"container": "raw", "encoding": "pcm_f32le", "sample_rate": 44100},
+        ...     context_id=context_id, stream=True
         ... ):
         ...     audio = audio_chunk["audio"]
     """
@@ -251,12 +285,19 @@ class _WebSocket:
         self.websocket = None
 
     def connect(self):
-        """This method connects to the WebSocket if it is not already connected."""
+        """This method connects to the WebSocket if it is not already connected.
+
+        Raises:
+            RuntimeError: If the connection to the WebSocket fails.
+        """
         if self.websocket is None or self._is_websocket_closed():
             route = "tts/websocket"
-            self.websocket = connect(
-                f"{self.ws_url}/{route}?api_key={self.api_key}&cartesia_version={self.cartesia_version}"
-            )
+            try:
+                self.websocket = connect(
+                    f"{self.ws_url}/{route}?api_key={self.api_key}&cartesia_version={self.cartesia_version}"
+                )
+            except Exception as e:
+                raise RuntimeError(f"Failed to connect to WebSocket. {e}")
 
     def _is_websocket_closed(self):
         return self.websocket.socket.fileno() == -1
@@ -329,7 +370,7 @@ class _WebSocket:
             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`
-            stream: Whether to stream the audio or not. (Default is True)
+            stream: Whether to stream the audio or not.
 
         Returns:
             If `stream` is True, the method returns a generator that yields chunks. Each chunk is a dictionary.
@@ -341,7 +382,7 @@ class _WebSocket:
         self.connect()
 
         if context_id is None:
-            context_id = uuid.uuid4().hex
+            context_id = str(uuid.uuid4())
 
         voice = self._validate_and_construct_voice(voice_id, voice_embedding)
 
@@ -395,7 +436,7 @@ class _SSE:
 
     Usage:
         >>> for audio_chunk in client.tts.sse(
-        ...     model_id="upbeat-moon", transcript="Hello world!", voice_embedding=embedding,
+        ...     model_id="sonic-english", transcript="Hello world!", voice_embedding=embedding,
         ...     output_format={"container": "raw", "encoding": "pcm_f32le", "sample_rate": 44100}, stream=True
         ... ):
         ...     audio = audio_chunk["audio"]
@@ -523,8 +564,7 @@ class _SSE:
             for chunk in self._sse_generator(request_body):
                 yield chunk
         except Exception as e:
-            logger.error(f"Failed to generate audio. {e}")
-            raise e
+            raise RuntimeError(f"Error generating audio. {e}")
 
     def _sse_generator(self, request_body: Dict[str, Any]):
         response = requests.post(
@@ -555,9 +595,10 @@ class _SSE:
 class TTS(Resource):
     """This resource contains methods to generate audio using Cartesia's text-to-speech API."""
 
-    def __init__(self, api_key, timeout):
+    def __init__(self, api_key: str, base_url: str, timeout: float):
         super().__init__(
             api_key=api_key,
+            base_url=base_url,
             timeout=timeout,
         )
         self._sse_class = _SSE(self._http_url(), self.headers, self.timeout)
@@ -573,7 +614,8 @@ class TTS(Resource):
         ws.connect()
         return ws
 
-    def get_output_format(self, output_format_name: str) -> OutputFormat:
+    @staticmethod
+    def get_output_format(output_format_name: str) -> OutputFormat:
         """Convenience method to get the output_format dictionary from a given output format name.
 
         Args:
@@ -631,22 +673,27 @@ class AsyncCartesia(Cartesia):
         self,
         *,
         api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
         timeout: float = DEFAULT_TIMEOUT,
         max_num_connections: int = DEFAULT_NUM_CONNECTIONS,
     ):
         """
         Args:
             api_key: See :class:`Cartesia`.
+            base_url: See :class:`Cartesia`.
             timeout: See :class:`Cartesia`.
             max_num_connections: The maximum number of concurrent connections to use for the client.
                 This is used to limit the number of connections that can be made to the server.
         """
         self._session = None
         self._loop = None
-        super().__init__(api_key=api_key, timeout=timeout)
+        super().__init__(api_key=api_key, base_url=base_url, timeout=timeout)
         self.max_num_connections = max_num_connections
         self.tts = AsyncTTS(
-            api_key=self.api_key, timeout=self.timeout, get_session=self._get_session
+            api_key=self.api_key,
+            base_url=self._base_url,
+            timeout=self.timeout,
+            get_session=self._get_session,
         )
 
     async def _get_session(self):
@@ -677,7 +724,7 @@ class AsyncCartesia(Cartesia):
 
         if loop is None:
             asyncio.run(self.close())
-        else:
+        elif loop.is_running():
             loop.create_task(self.close())
 
     async def __aenter__(self):
@@ -753,8 +800,7 @@ class _AsyncSSE(_SSE):
             async for chunk in self._sse_generator(request_body):
                 yield chunk
         except Exception as e:
-            logger.error(f"Failed to generate audio. {e}")
-            raise e
+            raise RuntimeError(f"Error generating audio. {e}")
 
     async def _sse_generator(self, request_body: Dict[str, Any]):
         session = await self._get_session()
@@ -779,6 +825,141 @@ class _AsyncSSE(_SSE):
                     pass
 
 
+class _AsyncTTSContext:
+    """Manage a single context over a WebSocket.
+
+    This class separates sending requests and receiving responses into two separate methods.
+    This can be used for sending multiple requests without awaiting the response.
+    Then you can listen to the responses in the order they were sent. See README for usage.
+
+    Each AsyncTTSContext will close automatically when a done message is received for that context.
+    This happens when the no_more_inputs method is called (equivalent to sending a request with `continue_ = False`),
+    or if no requests have been sent for 5 seconds on the same context. It also closes if there is an error.
+
+    """
+
+    def __init__(self, context_id: str, websocket: "_AsyncWebSocket", timeout: float):
+        self._context_id = context_id
+        self._websocket = websocket
+        self.timeout = timeout
+        self._error = None
+
+    @property
+    def context_id(self) -> str:
+        return self._context_id
+
+    async def send(
+        self,
+        model_id: str,
+        transcript: str,
+        output_format: OutputFormat,
+        voice_id: Optional[str] = None,
+        voice_embedding: Optional[List[float]] = None,
+        context_id: Optional[str] = None,
+        continue_: bool = False,
+        duration: Optional[int] = None,
+        language: Optional[str] = None,
+    ) -> None:
+        """Send audio generation requests to the WebSocket. The response can be received using the `receive` method.
+
+        Args:
+            model_id: The ID of the model to use for generating audio.
+            transcript: The text to convert to speech.
+            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.
+            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`
+
+        Returns:
+            None.
+        """
+        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.")
+        if continue_ and transcript == "":
+            raise ValueError("Transcript cannot be empty when continue_ is True.")
+
+        await self._websocket.connect()
+
+        voice = self._websocket._validate_and_construct_voice(voice_id, voice_embedding)
+
+        request_body = {
+            "model_id": model_id,
+            "transcript": transcript,
+            "voice": voice,
+            "output_format": {
+                "container": output_format["container"],
+                "encoding": output_format["encoding"],
+                "sample_rate": output_format["sample_rate"],
+            },
+            "context_id": self._context_id,
+            "continue": continue_,
+            "language": language,
+        }
+
+        if duration is not None:
+            request_body["duration"] = duration
+
+        await self._websocket.websocket.send_json(request_body)
+
+        # Start listening for responses on the WebSocket
+        self._websocket._dispatch_listener()
+
+    async def no_more_inputs(self) -> None:
+        """Send a request to the WebSocket to indicate that no more requests will be sent."""
+        await self.send(
+            model_id=DEFAULT_MODEL_ID,
+            transcript="",
+            output_format=TTS.get_output_format("raw_pcm_f32le_44100"),
+            voice_id="a0e99841-438c-4a64-b679-ae501e7d6091",  # Default voice ID since it's a required input for now
+            context_id=self._context_id,
+            continue_=False,
+        )
+
+    async def receive(self) -> AsyncGenerator[Dict[str, Any], None]:
+        """Receive the audio chunks from the WebSocket. This method is a generator that yields audio chunks.
+
+        Returns:
+            An async generator that yields audio chunks. Each chunk is a dictionary containing the audio as bytes.
+        """
+        try:
+            while True:
+                response = await self._websocket._get_message(
+                    self._context_id, timeout=self.timeout
+                )
+                if "error" in response:
+                    raise RuntimeError(f"Error generating audio:\n{response['error']}")
+                if response["done"]:
+                    break
+                yield self._websocket._convert_response(response, include_context_id=True)
+        except Exception as e:
+            if isinstance(e, asyncio.TimeoutError):
+                raise RuntimeError("Timeout while waiting for audio chunk")
+            raise RuntimeError(f"Failed to generate audio:\n{e}")
+        finally:
+            self._close()
+
+    def _close(self) -> None:
+        """Closes the context. Automatically called when a done message is received for this context."""
+        self._websocket._remove_context(self._context_id)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Union[type, None],
+        exc: Union[BaseException, None],
+        exc_tb: Union[TracebackType, None],
+    ):
+        self._close()
+
+    def __del__(self):
+        self._close()
+
+
 class _AsyncWebSocket(_WebSocket):
     """This class contains methods to generate audio using WebSocket asynchronously."""
 
@@ -787,19 +968,45 @@ class _AsyncWebSocket(_WebSocket):
         ws_url: str,
         api_key: str,
         cartesia_version: str,
+        timeout: float,
         get_session: Callable[[], Optional[aiohttp.ClientSession]],
     ):
+        """
+        Args:
+            ws_url: The WebSocket URL for the Cartesia API.
+            api_key: The API key to use for authorization.
+            cartesia_version: The version of the Cartesia API to use.
+            timeout: The timeout for responses on the WebSocket in seconds.
+            get_session: A function that returns an aiohttp.ClientSession object.
+        """
         super().__init__(ws_url, api_key, cartesia_version)
+        self.timeout = timeout
         self._get_session = get_session
         self.websocket = None
+        self._context_queues: Dict[str, asyncio.Queue] = {}
+        self._processing_task: asyncio.Task = None
+
+    def __del__(self):
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop is None:
+            asyncio.run(self.close())
+        elif loop.is_running():
+            loop.create_task(self.close())
 
     async def connect(self):
         if self.websocket is None or self._is_websocket_closed():
             route = "tts/websocket"
             session = await self._get_session()
-            self.websocket = await session.ws_connect(
-                f"{self.ws_url}/{route}?api_key={self.api_key}&cartesia_version={self.cartesia_version}"
-            )
+            try:
+                self.websocket = await session.ws_connect(
+                    f"{self.ws_url}/{route}?api_key={self.api_key}&cartesia_version={self.cartesia_version}"
+                )
+            except Exception as e:
+                raise RuntimeError(f"Failed to connect to WebSocket. {e}")
 
     def _is_websocket_closed(self):
         return self.websocket.closed
@@ -808,6 +1015,25 @@ class _AsyncWebSocket(_WebSocket):
         """This method closes the websocket connection. *Highly* recommended to call this method when done."""
         if self.websocket is not None and not self._is_websocket_closed():
             await self.websocket.close()
+        if self._processing_task:
+            self._processing_task.cancel()
+            try:
+                self._processing_task = None
+            except asyncio.CancelledError:
+                pass
+            except TypeError as e:
+                # Ignore the error if the task is already cancelled
+                # For some reason we are getting None responses
+                # TODO: This needs to be fixed - we need to think about why we are getting None responses.
+                if "Received message 256:None" not in str(e):
+                    raise e
+
+        for context_id in list(self._context_queues.keys()):
+            self._remove_context(context_id)
+
+        self._context_queues.clear()
+        self._processing_task = None
+        self.websocket = None
 
     async def send(
         self,
@@ -819,32 +1045,26 @@ class _AsyncWebSocket(_WebSocket):
         context_id: Optional[str] = None,
         duration: Optional[int] = None,
         language: Optional[str] = None,
-        stream: Optional[bool] = True,
+        stream: bool = True,
     ) -> Union[bytes, AsyncGenerator[bytes, None]]:
-        await self.connect()
-
         if context_id is None:
-            context_id = uuid.uuid4().hex
-
-        voice = self._validate_and_construct_voice(voice_id, voice_embedding)
-
-        request_body = {
-            "model_id": model_id,
-            "transcript": transcript,
-            "voice": voice,
-            "output_format": {
-                "container": output_format["container"],
-                "encoding": output_format["encoding"],
-                "sample_rate": output_format["sample_rate"],
-            },
-            "context_id": context_id,
-            "language": language,
-        }
-
-        if duration is not None:
-            request_body["duration"] = duration
+            context_id = str(uuid.uuid4())
+
+        ctx = self.context(context_id)
+
+        await ctx.send(
+            model_id=model_id,
+            transcript=transcript,
+            output_format=output_format,
+            voice_id=voice_id,
+            voice_embedding=voice_embedding,
+            context_id=context_id,
+            duration=duration,
+            language=language,
+            continue_=False,
+        )
 
-        generator = self._websocket_generator(request_body)
+        generator = ctx.receive()
 
         if stream:
             return generator
@@ -855,35 +1075,51 @@ class _AsyncWebSocket(_WebSocket):
 
         return {"audio": b"".join(chunks), "context_id": context_id}
 
-    async def _websocket_generator(self, request_body: Dict[str, Any]):
-        await self.websocket.send_json(request_body)
-
+    async def _process_responses(self):
         try:
-            response = None
             while True:
                 response = await self.websocket.receive_json()
-                if "error" in response:
-                    raise RuntimeError(f"Error generating audio:\n{response['error']}")
-                if response["done"]:
-                    break
-
-                yield self._convert_response(response=response, include_context_id=True)
+                if response["context_id"]:
+                    context_id = response["context_id"]
+                if context_id in self._context_queues:
+                    await self._context_queues[context_id].put(response)
         except Exception as e:
-            # Close the websocket connection if an error occurs.
-            if self.websocket and not self._is_websocket_closed():
-                await self.websocket.close()
-            error_msg_end = "" if response is None else f": {await response.text()}"
-            raise RuntimeError(f"Failed to generate audio. {error_msg_end}") from e
+            self._error = e
+            raise e
+
+    async def _get_message(self, context_id: str, timeout: float) -> Dict[str, Any]:
+        if context_id not in self._context_queues:
+            raise ValueError(f"Context ID {context_id} not found.")
+        return await asyncio.wait_for(self._context_queues[context_id].get(), timeout=timeout)
+
+    def _remove_context(self, context_id: str):
+        if context_id in self._context_queues:
+            del self._context_queues[context_id]
+
+    def _dispatch_listener(self):
+        if self._processing_task is None or self._processing_task.done():
+            self._processing_task = asyncio.create_task(self._process_responses())
+
+    def context(self, context_id: Optional[str] = None) -> _AsyncTTSContext:
+        if context_id in self._context_queues:
+            raise ValueError(f"AsyncContext for context ID {context_id} already exists.")
+        if context_id is None:
+            context_id = str(uuid.uuid4())
+        if context_id not in self._context_queues:
+            self._context_queues[context_id] = asyncio.Queue()
+        return _AsyncTTSContext(context_id, self, self.timeout)
 
 
 class AsyncTTS(TTS):
-    def __init__(self, api_key, timeout, get_session):
-        super().__init__(api_key, timeout)
+    def __init__(self, api_key, base_url, timeout, get_session):
+        super().__init__(api_key, base_url, timeout)
         self._get_session = get_session
         self._sse_class = _AsyncSSE(self._http_url(), self.headers, self.timeout, get_session)
         self.sse = self._sse_class.send
 
     async def websocket(self) -> _AsyncWebSocket:
-        ws = _AsyncWebSocket(self._ws_url(), self.api_key, self.cartesia_version, self._get_session)
+        ws = _AsyncWebSocket(
+            self._ws_url(), self.api_key, self.cartesia_version, self.timeout, self._get_session
+        )
         await ws.connect()
         return ws

cartesia/utils/deprecated.py

@@ -0,0 +1,55 @@
+import os
+import warnings
+from typing import Any, Callable, TypeVar
+
+TCallable = TypeVar("TCallable", bound=Callable[..., Any])
+
+# List of statistics of deprecated functions.
+# This should only be used by the test suite to find any deprecated functions
+# that should be removed for this version.
+_TRACK_DEPRECATED_FUNCTION_STATS = os.environ.get("CARTESIA_TEST_DEPRECATED", "").lower() == "true"
+_DEPRECATED_FUNCTION_STATS = []
+
+
+def deprecated(
+    reason=None, vdeprecated=None, vremove=None, replacement=None
+) -> Callable[[TCallable], TCallable]:
+    local_vars = locals()
+
+    def fn(func: TCallable) -> TCallable:
+        if isinstance(func, classmethod):
+            func = func.__func__
+        msg = _get_deprecated_msg(func, reason, vdeprecated, vremove, replacement)
+        warnings.warn(msg, DeprecationWarning)
+        return func
+
+    if _TRACK_DEPRECATED_FUNCTION_STATS:  # pragma: no cover
+        _DEPRECATED_FUNCTION_STATS.append(local_vars)
+
+    return fn
+
+
+def _get_deprecated_msg(wrapped, reason, vdeprecated, vremoved, replacement=None):
+    fmt = "{name} is deprecated"
+    if vdeprecated:
+        fmt += " since v{vdeprecated}"
+    if vremoved:
+        fmt += " and will be removed in v{vremoved}"
+    fmt += "."
+
+    if reason:
+        fmt += " ({reason})"
+    if replacement:
+        fmt += " -- Use {replacement} instead."
+
+    return fmt.format(
+        name=wrapped.__name__,
+        reason=reason or "",
+        vdeprecated=vdeprecated or "",
+        vremoved=vremoved or "",
+        replacement=replacement or "",
+    )
+
+
+# This method is taken from the following source:
+# https://github.com/ad12/meddlr/blob/main/meddlr/utils/deprecated.py

cartesia/utils/retry.py

@@ -0,0 +1,87 @@
+import time
+
+from aiohttp.client_exceptions import ServerDisconnectedError
+import asyncio
+from functools import wraps
+from http.client import RemoteDisconnected
+from httpx import TimeoutException
+from requests.exceptions import ConnectionError
+
+
+def retry_on_connection_error(max_retries=3, backoff_factor=1, logger=None):
+    """Retry a function if a ConnectionError, RemoteDisconnected, ServerDisconnectedError, or TimeoutException occurs.
+
+    Args:
+        max_retries (int): The maximum number of retries.
+        backoff_factor (int): The factor to increase the delay between retries.
+        logger (logging.Logger): The logger to use for logging.
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            retry_count = 0
+            while retry_count < max_retries:
+                try:
+                    return func(*args, **kwargs)
+                except (
+                    ConnectionError,
+                    RemoteDisconnected,
+                    ServerDisconnectedError,
+                    TimeoutException,
+                ) as e:
+                    logger.info(f"Retrying after exception: {e}")
+                    retry_count += 1
+                    if retry_count < max_retries:
+                        delay = backoff_factor * (2 ** (retry_count - 1))
+                        logger.warn(
+                            f"Attempt {retry_count + 1}/{max_retries} in {delay} seconds..."
+                        )
+                        time.sleep(delay)
+                    else:
+                        raise Exception(f"Exception occurred after {max_retries} tries.") from e
+
+        return wrapper
+
+    return decorator
+
+
+def retry_on_connection_error_async(max_retries=3, backoff_factor=1, logger=None):
+    """Retry an asynchronous function if a ConnectionError, RemoteDisconnected, ServerDisconnectedError, or TimeoutException occurs.
+
+    Args:
+        max_retries (int): The maximum number of retries.
+        backoff_factor (int): The factor to increase the delay between retries.
+        logger (logging.Logger): The logger to use for logging.
+    """
+
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            retry_count = 0
+            while retry_count < max_retries:
+                try:
+                    async for chunk in func(*args, **kwargs):
+                        yield chunk
+                    # If the function completes without raising an exception return
+                    return
+                except (
+                    ConnectionError,
+                    RemoteDisconnected,
+                    ServerDisconnectedError,
+                    TimeoutException,
+                ) as e:
+                    logger.info(f"Retrying after exception: {e}")
+                    retry_count += 1
+                    if retry_count < max_retries:
+                        delay = backoff_factor * (2 ** (retry_count - 1))
+                        logger.warn(
+                            f"Attempt {retry_count + 1}/{max_retries} in {delay} seconds..."
+                        )
+                        await asyncio.sleep(delay)
+                    else:
+                        raise Exception(f"Exception occurred after {max_retries} tries.") from e
+
+        return wrapper
+
+    return decorator

cartesia/version.py

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 1.0.2
+Version: 1.0.4
 Summary: The official Python library for the Cartesia API.
 Home-page: 
 Author: Cartesia, Inc.
@@ -244,6 +244,101 @@ p.terminate()
 ws.close()  # Close the websocket connection
 ```
 
+#### Conditioning speech on previous generations using WebSocket
+
+In some cases, input text may need to be streamed in. In these cases, it would be slow to wait for all the text to buffer before sending it to Cartesia's TTS service.
+
+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.
+
+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
+
+```python
+import asyncio
+import os
+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/)
+    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).
+    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).
+    output_format = {
+        "container": "raw",
+        "encoding": "pcm_f32le",
+        "sample_rate": 44100,
+    }
+
+    transcripts = [
+        "Sonic and Yoshi team up in a dimension-hopping adventure! ",
+        "Racing through twisting zones, they dodge Eggman's badniks and solve ancient puzzles. ",
+        "In the Echoing Caverns, they find the Harmonic Crystal, unlocking new powers. ",
+        "Sonic's speed creates sound waves, while Yoshi's eggs become sonic bolts. ",
+        "As they near Eggman's lair, our heroes charge their abilities for an epic boss battle. ",
+        "Get ready to spin, jump, and sound-blast your way to victory in this high-octane crossover!"
+    ]
+    
+    for transcript in transcripts:
+        # Send text inputs as they become available
+        await ctx.send(
+            model_id=model_id,
+            transcript=transcript,
+            voice_id=voice_id,
+            continue_=True,
+            output_format=output_format,
+        )
+
+    # Indicate that no more inputs will be sent. Otherwise, the context will close after 5 seconds of inactivity.
+    await ctx.no_more_inputs() 
+
+async def receive_and_play_audio(ctx):
+    p = pyaudio.PyAudio()
+    stream = None
+    rate = 44100
+
+    async for output in ctx.receive():
+        buffer = output["audio"]
+
+        if not stream:
+            stream = p.open(
+                format=pyaudio.paFloat32,
+                channels=1,
+                rate=rate,
+                output=True
+            )
+
+        stream.write(buffer)
+
+    stream.stop_stream()
+    stream.close()
+    p.terminate()
+
+async def stream_and_listen():
+    client = AsyncCartesia(api_key=os.environ.get("CARTESIA_API_KEY"))
+
+    # Set up the websocket connection
+    ws = await client.tts.websocket()
+
+    # Create a context to send and receive audio
+    ctx = ws.context() # Generates a random context ID if not provided
+
+    send_task = asyncio.create_task(send_transcripts(ctx))
+    listen_task = asyncio.create_task(receive_and_play_audio(ctx))
+
+    # Call the two coroutine tasks concurrently
+    await asyncio.gather(send_task, listen_task)
+
+    await ws.close()
+    await client.close()
+
+asyncio.run(stream_and_listen())
+```
+
 ### 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).

cartesia-1.0.4.dist-info/RECORD

@@ -0,0 +1,11 @@
+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,,

cartesia-1.0.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-cartesia/__init__.py,sha256=jMIf2O7dTGxvTA5AfXtmh1H_EGfMtQseR5wXrjNRbLs,93
-cartesia/_types.py,sha256=msXRqNwVx_mbcLIQgRJYEl8U-hO9LRPWmscnX89cBCY,3747
-cartesia/client.py,sha256=jMlFDPRtKVDelqevHlv7YZJgOES3ws9BFN_6uUyN0W8,32720
-cartesia/version.py,sha256=Y3LSfRioSl2xch70pq_ULlvyECXyEtN3krVaWeGyaxk,22
-cartesia-1.0.2.dist-info/METADATA,sha256=LPW7f4297S2DQ_uRtc3A-7-5WUCXsIgGcr1M3XelXys,12394
-cartesia-1.0.2.dist-info/WHEEL,sha256=DZajD4pwLWue70CAfc7YaxT1wLUciNBvN_TTcvXpltE,110
-cartesia-1.0.2.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
-cartesia-1.0.2.dist-info/RECORD,,