cartesia 1.0.3__py2.py3-none-any.whl → 1.0.5__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,16 +4,28 @@ 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,
+    Iterator,
+    Dict,
+    Generator,
+    List,
+    Optional,
+    Tuple,
+    Union,
+    Callable,
+    Set,
+)
 
 import aiohttp
 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.utils.deprecated import deprecated
 from cartesia._types import (
     OutputFormat,
     OutputFormatMapping,
@@ -36,22 +48,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 +83,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 +118,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 +225,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}")
@@ -227,14 +263,174 @@ 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.
 
     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"]
     """
@@ -249,23 +445,40 @@ 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."""
+        """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
 
     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]:
@@ -329,7 +542,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 +554,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)
 
@@ -385,17 +598,29 @@ 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.
 
     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 +748,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 +779,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 +798,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 +857,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 +908,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 +984,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 +1009,145 @@ class _AsyncSSE(_SSE):
                     pass
 
 
+class _AsyncTTSContext:
+    """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.
+    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)
+
+    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
+
+    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 +1156,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 +1203,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 +1233,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 +1263,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

@@ -17,6 +17,8 @@ def deprecated(
     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

cartesia/version.py

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

cartesia-1.0.5.dist-info/LICENSE.md

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 1.0.3
+Version: 1.0.5
 Summary: The official Python library for the Cartesia API.
 Home-page: 
 Author: Cartesia, Inc.
@@ -10,11 +10,13 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
+License-File: LICENSE.md
 Requires-Dist: aiohttp
 Requires-Dist: httpx
 Requires-Dist: pytest-asyncio
 Requires-Dist: requests
 Requires-Dist: websockets
+Requires-Dist: iterators
 Provides-Extra: all
 Requires-Dist: pytest >=8.0.2 ; extra == 'all'
 Requires-Dist: pytest-cov >=4.1.0 ; extra == 'all'
@@ -97,10 +99,10 @@ voice = client.voices.get(id=voice_id)
 
 transcript = "Hello! Welcome to Cartesia"
 
-# You can check out our models at [docs.cartesia.ai](https://docs.cartesia.ai/getting-started/available-models).
+# You can check out our models at https://docs.cartesia.ai/getting-started/available-models
 model_id = "sonic-english"
 
-# You can find the supported `output_format`s in our [API Reference](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events).
+# You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events
 output_format = {
     "container": "raw",
     "encoding": "pcm_f32le",
@@ -148,10 +150,10 @@ async def write_stream():
     voice_id = "a0e99841-438c-4a64-b679-ae501e7d6091"
     voice = client.voices.get(id=voice_id)
     transcript = "Hello! Welcome to Cartesia"
-    # You can check out our models at [docs.cartesia.ai](https://docs.cartesia.ai/getting-started/available-models).
+    # You can check out our models at https://docs.cartesia.ai/getting-started/available-models
     model_id = "sonic-english"
 
-    # You can find the supported `output_format`s in our [API Reference](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events).
+    # You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events
     output_format = {
         "container": "raw",
         "encoding": "pcm_f32le",
@@ -203,10 +205,10 @@ voice_id = "a0e99841-438c-4a64-b679-ae501e7d6091"
 voice = client.voices.get(id=voice_id)
 transcript = "Hello! Welcome to Cartesia"
 
-# You can check out our models at [docs.cartesia.ai](https://docs.cartesia.ai/getting-started/available-models).
+# You can check out our models at https://docs.cartesia.ai/getting-started/available-models
 model_id = "sonic-english"
 
-# You can find the supported `output_format`s in our [API Reference](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events).
+# You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events
 output_format = {
     "container": "raw",
     "encoding": "pcm_f32le",
@@ -244,6 +246,179 @@ 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 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
+
+```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 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,
+    }
+
+    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())
+```
+
+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).
@@ -261,10 +436,10 @@ voice = client.voices.get(id=voice_id)
 transcript = "Hola! Bienvenido a Cartesia"
 language = "es"  # Language code corresponding to the language of the transcript
 
-# Make sure you use the multilingual model! You can check out all models at [docs.cartesia.ai](https://docs.cartesia.ai/getting-started/available-models).
+# Make sure you use the multilingual model! You can check out all models at https://docs.cartesia.ai/getting-started/available-models
 model_id = "sonic-multilingual"
 
-# You can find the supported `output_format`s in our [API Reference](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events).
+# You can find the supported `output_format`s at https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events
 output_format = {
     "container": "raw",
     "encoding": "pcm_f32le",

cartesia-1.0.5.dist-info/RECORD

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

cartesia-1.0.3.dist-info/RECORD

@@ -1,11 +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=2plzdEEb24FLjE2I2XyBBcJEPYWHccNL4SgtLC_6erg,22
-cartesia/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cartesia/utils/deprecated.py,sha256=QSM-ld_g1r-JlT571SSt6-w650jVm9mJmmI2MSScLPw,1599
-cartesia/utils/retry.py,sha256=nuwWRfu3MOVTxIQMLjYf6WLaxSlnu_GdE3QjTV0zisQ,3339
-cartesia-1.0.3.dist-info/METADATA,sha256=y5_HREGB417qL69qMFYtKrIRQAQJ1WDxqObaAg6-V6U,12394
-cartesia-1.0.3.dist-info/WHEEL,sha256=DZajD4pwLWue70CAfc7YaxT1wLUciNBvN_TTcvXpltE,110
-cartesia-1.0.3.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
-cartesia-1.0.3.dist-info/RECORD,,