cartesia 0.0.3__tar.gz → 0.0.5rc1__tar.gz

{cartesia-0.0.3 → cartesia-0.0.5rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 0.0.3
+Version: 0.0.5rc1
 Summary: The official Python library for the Cartesia API.
 Home-page: 
 Author: Cartesia, Inc.
@@ -10,8 +10,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
-Requires-Dist: websockets
+Requires-Dist: aiohttp
+Requires-Dist: httpx
+Requires-Dist: pytest-asyncio
 Requires-Dist: requests
+Requires-Dist: websockets
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: docformatter; extra == "dev"
@@ -21,6 +24,7 @@ Requires-Dist: flake8==7.0.0; extra == "dev"
 Requires-Dist: flake8-bugbear==24.2.6; extra == "dev"
 Requires-Dist: pytest>=8.0.2; extra == "dev"
 Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: twine; extra == "dev"
 Provides-Extra: all
 Requires-Dist: pre-commit; extra == "all"
 Requires-Dist: docformatter; extra == "all"
@@ -30,6 +34,7 @@ Requires-Dist: flake8==7.0.0; extra == "all"
 Requires-Dist: flake8-bugbear==24.2.6; extra == "all"
 Requires-Dist: pytest>=8.0.2; extra == "all"
 Requires-Dist: pytest-cov>=4.1.0; extra == "all"
+Requires-Dist: twine; extra == "all"
 
 
 # Cartesia Python API Library
@@ -104,10 +109,42 @@ for output in client.generate(transcript=transcript, voice=voice, stream=True):
 audio_data.seek(0)
 
 # Create an Audio object from the BytesIO data
-audio = Audio(audio_data, rate=output["sampling_rate"])
+audio = Audio(np.frombuffer(audio_data.read(), dtype=np.float32), rate=output["sampling_rate"])
+
+# Display the Audio object
+display(audio)
+```
+
+You can also use the async client if you want to make asynchronous API calls. The usage is very similar:
+```python
+from cartesia.tts import AsyncCartesiaTTS
+from IPython.display import Audio
+import io
+import os
+
+client = AsyncCartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
+voices = client.get_voices()
+voice = client.get_voice_embedding(voice_id=voices["Graham"]["id"])
+transcript = "Hello! Welcome to Cartesia"
+
+# Create a BytesIO object to store the audio data
+audio_data = io.BytesIO()
+
+# Generate and stream audio
+async for output in client.generate(transcript=transcript, voice=voice, stream=True):
+    buffer = output["audio"]
+    audio_data.write(buffer)
+
+# Set the cursor position to the beginning of the BytesIO object
+audio_data.seek(0)
+
+# Create an Audio object from the BytesIO data
+audio = Audio(np.frombuffer(audio_data.read(), dtype=np.float32), rate=output["sampling_rate"])
 
 # Display the Audio object
 display(audio)
 ```
 
-We recommend using [`python-dotenv`](https://pypi.org/project/python-dotenv/) to add `CARTESIA_API_KEY="my-api-key"` to your .env file so that your API Key is not stored in the source code.
+To avoid storing your API key in the source code, we recommend doing one of the following:
+1. Use [`python-dotenv`](https://pypi.org/project/python-dotenv/) to add `CARTESIA_API_KEY="my-api-key"` to your .env file. 
+1. Set the `CARTESIA_API_KEY` environment variable, preferably to a secure shell init file (e.g. `~/.zshrc`, `~/.bashrc`)

{cartesia-0.0.3 → cartesia-0.0.5rc1}/README.md

@@ -70,10 +70,42 @@ for output in client.generate(transcript=transcript, voice=voice, stream=True):
 audio_data.seek(0)
 
 # Create an Audio object from the BytesIO data
-audio = Audio(audio_data, rate=output["sampling_rate"])
+audio = Audio(np.frombuffer(audio_data.read(), dtype=np.float32), rate=output["sampling_rate"])
 
 # Display the Audio object
 display(audio)
 ```
 
-We recommend using [`python-dotenv`](https://pypi.org/project/python-dotenv/) to add `CARTESIA_API_KEY="my-api-key"` to your .env file so that your API Key is not stored in the source code.
+You can also use the async client if you want to make asynchronous API calls. The usage is very similar:
+```python
+from cartesia.tts import AsyncCartesiaTTS
+from IPython.display import Audio
+import io
+import os
+
+client = AsyncCartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
+voices = client.get_voices()
+voice = client.get_voice_embedding(voice_id=voices["Graham"]["id"])
+transcript = "Hello! Welcome to Cartesia"
+
+# Create a BytesIO object to store the audio data
+audio_data = io.BytesIO()
+
+# Generate and stream audio
+async for output in client.generate(transcript=transcript, voice=voice, stream=True):
+    buffer = output["audio"]
+    audio_data.write(buffer)
+
+# Set the cursor position to the beginning of the BytesIO object
+audio_data.seek(0)
+
+# Create an Audio object from the BytesIO data
+audio = Audio(np.frombuffer(audio_data.read(), dtype=np.float32), rate=output["sampling_rate"])
+
+# Display the Audio object
+display(audio)
+```
+
+To avoid storing your API key in the source code, we recommend doing one of the following:
+1. Use [`python-dotenv`](https://pypi.org/project/python-dotenv/) to add `CARTESIA_API_KEY="my-api-key"` to your .env file. 
+1. Set the `CARTESIA_API_KEY` environment variable, preferably to a secure shell init file (e.g. `~/.zshrc`, `~/.bashrc`)

{cartesia-0.0.3 → cartesia-0.0.5rc1}/cartesia/tts.py

@@ -1,15 +1,20 @@
+import asyncio
 import base64
 import json
 import os
 import uuid
-from typing import Any, Dict, Generator, List, Optional, TypedDict, Union
+from typing import Any, AsyncGenerator, Dict, Generator, List, Optional, Tuple, TypedDict, Union
 
+import aiohttp
+import httpx
 import requests
 from websockets.sync.client import connect
 
 DEFAULT_MODEL_ID = "genial-planet-1346"
 DEFAULT_BASE_URL = "api.cartesia.ai"
 DEFAULT_API_VERSION = "v0"
+DEFAULT_TIMEOUT = 60  # seconds
+DEFAULT_NUM_CONNECTIONS = 10  # connections per client
 
 
 class AudioOutput(TypedDict):
@@ -27,11 +32,46 @@ class VoiceMetadata(TypedDict):
     embedding: Optional[Embedding]
 
 
+def update_buffer(buffer: str, chunk_bytes: bytes) -> Tuple[str, List[Dict[str, Any]]]:
+    buffer += chunk_bytes.decode("utf-8")
+    outputs = []
+    while "{" in buffer and "}" in buffer:
+        start_index = buffer.find("{")
+        end_index = buffer.find("}", start_index)
+        if start_index != -1 and end_index != -1:
+            try:
+                chunk_json = json.loads(buffer[start_index : end_index + 1])
+                audio = base64.b64decode(chunk_json["data"])
+                outputs.append({"audio": audio, "sampling_rate": chunk_json["sampling_rate"]})
+                buffer = buffer[end_index + 1 :]
+            except json.JSONDecodeError:
+                break
+    return buffer, outputs
+
+
+def convert_response(response: Dict[str, any], include_context_id: bool) -> Dict[str, Any]:
+    audio = base64.b64decode(response["data"])
+
+    optional_kwargs = {}
+    if include_context_id:
+        optional_kwargs["context_id"] = response["context_id"]
+
+    return {
+        "audio": audio,
+        "sampling_rate": response["sampling_rate"],
+        **optional_kwargs,
+    }
+
+
 class CartesiaTTS:
     """The client for Cartesia's text-to-speech library.
 
     This client contains methods to interact with the Cartesia text-to-speech API.
-    The API offers
+    The client can be used to retrieve available voices, compute new voice embeddings,
+    and generate speech from text.
+
+    The client also supports generating audio using a websocket for lower latency.
+    To enable interrupt handling along the websocket, set `experimental_ws_handle_interrupts=True`.
 
     Examples:
 
@@ -55,18 +95,22 @@ class CartesiaTTS:
         ...     audio, sr = audio_chunk["audio"], audio_chunk["sampling_rate"]
     """
 
-    def __init__(self, *, api_key: str = None):
+    def __init__(self, *, api_key: str = None, experimental_ws_handle_interrupts: bool = False):
         """
         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`.
+            experimental_ws_handle_interrupts: Whether to handle interrupts when generating
+                audio using the websocket. This is an experimental feature and may have bugs
+                or be deprecated in the future.
         """
         self.base_url = os.environ.get("CARTESIA_BASE_URL", DEFAULT_BASE_URL)
         self.api_key = api_key or os.environ.get("CARTESIA_API_KEY")
         self.api_version = os.environ.get("CARTESIA_API_VERSION", DEFAULT_API_VERSION)
         self.headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}
         self.websocket = None
+        self.experimental_ws_handle_interrupts = experimental_ws_handle_interrupts
         self.refresh_websocket()
 
     def get_voices(self, skip_embeddings: bool = True) -> Dict[str, VoiceMetadata]:
@@ -100,9 +144,9 @@ class CartesiaTTS:
             >>> audio = client.generate(transcript="Hello world!", voice=embedding)
         """
         params = {"select": "id, name, description"} if skip_embeddings else None
-        response = requests.get(f"{self._http_url()}/voices", headers=self.headers, params=params)
+        response = httpx.get(f"{self._http_url()}/voices", headers=self.headers, params=params)
 
-        if response.status_code != 200:
+        if not response.is_success:
             raise ValueError(f"Failed to get voices. Error: {response.text}")
 
         voices = response.json()
@@ -134,20 +178,20 @@ class CartesiaTTS:
 
         if voice_id:
             url = f"{self._http_url()}/voices/embedding/{voice_id}"
-            response = requests.get(url, headers=self.headers)
+            response = httpx.get(url, headers=self.headers)
         elif filepath:
             url = f"{self._http_url()}/voices/clone/clip"
             files = {"clip": open(filepath, "rb")}
             headers = self.headers.copy()
             # The default content type of JSON is incorrect for file uploads
             headers.pop("Content-Type")
-            response = requests.post(url, headers=headers, files=files)
+            response = httpx.post(url, headers=headers, files=files)
         elif link:
             url = f"{self._http_url()}/voices/clone/url"
             params = {"link": link}
-            response = requests.post(url, headers=self.headers, params=params)
+            response = httpx.post(url, headers=self.headers, params=params)
 
-        if response.status_code != 200:
+        if not response.is_success:
             raise ValueError(
                 f"Failed to clone voice. Status Code: {response.status_code}\n"
                 f"Error: {response.text}"
@@ -167,8 +211,11 @@ class CartesiaTTS:
         """
         if self.websocket and not self._is_websocket_closed():
             self.websocket.close()
+        route = "audio/websocket"
+        if self.experimental_ws_handle_interrupts:
+            route = f"experimental/{route}"
         self.websocket = connect(
-            f"{self._ws_url()}/audio/websocket?api_key={self.api_key}",
+            f"{self._ws_url()}/{route}?api_key={self.api_key}",
             close_timeout=None,
         )
 
@@ -189,6 +236,29 @@ class CartesiaTTS:
         if transcript.strip() == "":
             raise ValueError("`transcript` must be non empty")
 
+    def _generate_request_body(
+        self,
+        *,
+        transcript: str,
+        duration: int = None,
+        chunk_time: float = None,
+        voice: Embedding = None,
+    ) -> Dict[str, Any]:
+        """
+        Create the request body for a stream request.
+        Note that anything that's not provided will use a default if available or be filtered out otherwise.
+        """
+        body = dict(transcript=transcript, model_id=DEFAULT_MODEL_ID, voice=voice)
+
+        optional_body = dict(
+            duration=duration,
+            chunk_time=chunk_time,
+            voice=voice,
+        )
+        body.update({k: v for k, v in optional_body.items() if v is not None})
+
+        return body
+
     def generate(
         self,
         *,
@@ -221,14 +291,9 @@ class CartesiaTTS:
         """
         self._check_inputs(transcript, duration, chunk_time)
 
-        body = dict(transcript=transcript, model_id=DEFAULT_MODEL_ID)
-
-        optional_body = dict(
-            duration=duration,
-            chunk_time=chunk_time,
-            voice=voice,
+        body = self._generate_request_body(
+            transcript=transcript, duration=duration, chunk_time=chunk_time, voice=voice
         )
-        body.update({k: v for k, v in optional_body.items() if v is not None})
 
         if websocket:
             generator = self._generate_ws(body)
@@ -254,23 +319,14 @@ class CartesiaTTS:
             data=json.dumps(body),
             headers=self.headers,
         )
-        if response.status_code != 200:
+        if not response.ok:
             raise ValueError(f"Failed to generate audio. {response.text}")
 
         buffer = ""
         for chunk_bytes in response.iter_content(chunk_size=None):
-            buffer += chunk_bytes.decode("utf-8")
-            while "{" in buffer and "}" in buffer:
-                start_index = buffer.find("{")
-                end_index = buffer.find("}", start_index)
-                if start_index != -1 and end_index != -1:
-                    try:
-                        chunk_json = json.loads(buffer[start_index : end_index + 1])
-                        audio = base64.b64decode(chunk_json["data"])
-                        yield {"audio": audio, "sampling_rate": chunk_json["sampling_rate"]}
-                        buffer = buffer[end_index + 1 :]
-                    except json.JSONDecodeError:
-                        break
+            buffer, outputs = update_buffer(buffer, chunk_bytes)
+            for output in outputs:
+                yield output
 
         if buffer:
             try:
@@ -280,21 +336,41 @@ class CartesiaTTS:
             except json.JSONDecodeError:
                 pass
 
-    def _generate_ws(self, body: Dict[str, Any]):
+    def _generate_ws(self, body: Dict[str, Any], *, context_id: str = None):
+        """Generate audio using the websocket connection.
+
+        Args:
+            body: The request body.
+            context_id: The context id for the request.
+                The context id must be globally unique for the duration this client exists.
+                If this is provided, the context id that is in the response will
+                also be returned as part of the dict. This is helpful for testing.
+        """
         if not self.websocket or self._is_websocket_closed():
             self.refresh_websocket()
 
-        self.websocket.send(json.dumps({"data": body, "context_id": uuid.uuid4().hex}))
+        include_context_id = bool(context_id)
+        if context_id is None:
+            context_id = uuid.uuid4().hex
+        self.websocket.send(json.dumps({"data": body, "context_id": context_id}))
         try:
-            response = json.loads(self.websocket.recv())
-            while not response["done"]:
-                audio = base64.b64decode(response["data"])
-                # print("timing", time.perf_counter() - start)
-                yield {"audio": audio, "sampling_rate": response["sampling_rate"]}
-
+            while True:
                 response = json.loads(self.websocket.recv())
-        except Exception:
-            raise RuntimeError(f"Failed to generate audio. {response}")
+                if response["done"]:
+                    break
+
+                yield convert_response(response, include_context_id)
+
+                if self.experimental_ws_handle_interrupts:
+                    self.websocket.send(json.dumps({"context_id": context_id}))
+        except GeneratorExit:
+            # The exit is only called when the generator is garbage collected.
+            # It may not be called directly after a break statement.
+            # However, the generator will be automatically cancelled on the next request.
+            if self.experimental_ws_handle_interrupts:
+                self.websocket.send(json.dumps({"context_id": context_id, "action": "cancel"}))
+        except Exception as e:
+            raise RuntimeError(f"Failed to generate audio. {response}") from e
 
     def _http_url(self):
         prefix = "http" if "localhost" in self.base_url else "https"
@@ -307,3 +383,143 @@ class CartesiaTTS:
     def __del__(self):
         if self.websocket.socket.fileno() > -1:
             self.websocket.close()
+
+
+class AsyncCartesiaTTS(CartesiaTTS):
+    def __init__(self, *, api_key: str = None, experimental_ws_handle_interrupts: bool = False):
+        self.timeout = aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT)
+        self.connector = aiohttp.TCPConnector(limit=DEFAULT_NUM_CONNECTIONS)
+        self._session = aiohttp.ClientSession(timeout=self.timeout, connector=self.connector)
+        super().__init__(
+            api_key=api_key, experimental_ws_handle_interrupts=experimental_ws_handle_interrupts
+        )
+
+    def refresh_websocket(self):
+        pass  # do not load the websocket for the client until asynchronously when it is needed
+
+    async def _async_refresh_websocket(self):
+        """Refresh the websocket connection."""
+        if self.websocket and not self._is_websocket_closed():
+            self.websocket.close()
+        route = "audio/websocket"
+        if self.experimental_ws_handle_interrupts:
+            route = f"experimental/{route}"
+        self.websocket = await self._session.ws_connect(
+            f"{self._ws_url()}/{route}?api_key={self.api_key}"
+        )
+
+    async def generate(
+        self,
+        *,
+        transcript: str,
+        duration: int = None,
+        chunk_time: float = None,
+        voice: Embedding = None,
+        stream: bool = False,
+        websocket: bool = True,
+    ) -> Union[AudioOutput, AsyncGenerator[AudioOutput, None]]:
+        """Asynchronously generate audio from a transcript.
+        NOTE: This overrides the non-asynchronous generate method from the base class.
+        Args:
+            transcript: The text to generate audio for.
+            voice: The embedding to use for generating audio.
+            options: The options to use for generating audio. See :class:`GenerateOptions`.
+        Returns:
+            A dictionary containing the following:
+                * "audio": The audio as a 1D numpy array.
+                * "sampling_rate": The sampling rate of the audio.
+        """
+        body = self._generate_request_body(
+            transcript=transcript, duration=duration, chunk_time=chunk_time, voice=voice
+        )
+
+        if websocket:
+            generator = self._generate_ws(body)
+        else:
+            generator = self._generate_http(body)
+
+        if stream:
+            return generator
+
+        chunks = []
+        sampling_rate = None
+        async for chunk in generator:
+            if sampling_rate is None:
+                sampling_rate = chunk["sampling_rate"]
+            chunks.append(chunk["audio"])
+
+        return {"audio": b"".join(chunks), "sampling_rate": sampling_rate}
+
+    async def _generate_http(self, body: Dict[str, Any]):
+        async with self._session.post(
+            f"{self._http_url()}/audio/stream", data=json.dumps(body), headers=self.headers
+        ) as response:
+            if response.status < 200 or response.status >= 300:
+                raise ValueError(f"Failed to generate audio. {response.text}")
+
+            buffer = ""
+            async for chunk_bytes in response.content.iter_any():
+                buffer, outputs = update_buffer(buffer, chunk_bytes)
+                for output in outputs:
+                    yield output
+
+            if buffer:
+                try:
+                    chunk_json = json.loads(buffer)
+                    audio = base64.b64decode(chunk_json["data"])
+                    yield {"audio": audio, "sampling_rate": chunk_json["sampling_rate"]}
+                except json.JSONDecodeError:
+                    pass
+
+    async def _generate_ws(self, body: Dict[str, Any], *, context_id: str = None):
+        include_context_id = bool(context_id)
+        route = "audio/websocket"
+        if self.experimental_ws_handle_interrupts:
+            route = f"experimental/{route}"
+
+        if not self.websocket or self._is_websocket_closed():
+            await self._async_refresh_websocket()
+
+        ws = self.websocket
+        if context_id is None:
+            context_id = uuid.uuid4().hex
+        await ws.send_json({"data": body, "context_id": context_id})
+        try:
+            response = None
+            while True:
+                response = await ws.receive_json()
+                if response["done"]:
+                    break
+
+                yield convert_response(response, include_context_id)
+
+                if self.experimental_ws_handle_interrupts:
+                    await ws.send_json({"context_id": context_id})
+        except GeneratorExit:
+            # The exit is only called when the generator is garbage collected.
+            # It may not be called directly after a break statement.
+            # However, the generator will be automatically cancelled on the next request.
+            if self.experimental_ws_handle_interrupts:
+                await ws.send_json({"context_id": context_id, "action": "cancel"})
+        except Exception as e:
+            raise RuntimeError(f"Failed to generate audio. {response}") from e
+
+    def _is_websocket_closed(self):
+        return self.websocket.closed
+
+    async def cleanup(self):
+        if self.websocket is not None and not self._is_websocket_closed():
+            await self.websocket.close()
+        if not self._session.closed:
+            await self._session.close()
+
+    def __del__(self):
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop is None:
+            asyncio.run(self.cleanup())
+        else:
+            loop.create_task(self.cleanup())

cartesia-0.0.5rc1/cartesia/version.py

@@ -0,0 +1 @@
+__version__ = "0.0.5rc1"

{cartesia-0.0.3 → cartesia-0.0.5rc1}/cartesia.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 0.0.3
+Version: 0.0.5rc1
 Summary: The official Python library for the Cartesia API.
 Home-page: 
 Author: Cartesia, Inc.
@@ -10,8 +10,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
-Requires-Dist: websockets
+Requires-Dist: aiohttp
+Requires-Dist: httpx
+Requires-Dist: pytest-asyncio
 Requires-Dist: requests
+Requires-Dist: websockets
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: docformatter; extra == "dev"
@@ -21,6 +24,7 @@ Requires-Dist: flake8==7.0.0; extra == "dev"
 Requires-Dist: flake8-bugbear==24.2.6; extra == "dev"
 Requires-Dist: pytest>=8.0.2; extra == "dev"
 Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: twine; extra == "dev"
 Provides-Extra: all
 Requires-Dist: pre-commit; extra == "all"
 Requires-Dist: docformatter; extra == "all"
@@ -30,6 +34,7 @@ Requires-Dist: flake8==7.0.0; extra == "all"
 Requires-Dist: flake8-bugbear==24.2.6; extra == "all"
 Requires-Dist: pytest>=8.0.2; extra == "all"
 Requires-Dist: pytest-cov>=4.1.0; extra == "all"
+Requires-Dist: twine; extra == "all"
 
 
 # Cartesia Python API Library
@@ -104,10 +109,42 @@ for output in client.generate(transcript=transcript, voice=voice, stream=True):
 audio_data.seek(0)
 
 # Create an Audio object from the BytesIO data
-audio = Audio(audio_data, rate=output["sampling_rate"])
+audio = Audio(np.frombuffer(audio_data.read(), dtype=np.float32), rate=output["sampling_rate"])
+
+# Display the Audio object
+display(audio)
+```
+
+You can also use the async client if you want to make asynchronous API calls. The usage is very similar:
+```python
+from cartesia.tts import AsyncCartesiaTTS
+from IPython.display import Audio
+import io
+import os
+
+client = AsyncCartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
+voices = client.get_voices()
+voice = client.get_voice_embedding(voice_id=voices["Graham"]["id"])
+transcript = "Hello! Welcome to Cartesia"
+
+# Create a BytesIO object to store the audio data
+audio_data = io.BytesIO()
+
+# Generate and stream audio
+async for output in client.generate(transcript=transcript, voice=voice, stream=True):
+    buffer = output["audio"]
+    audio_data.write(buffer)
+
+# Set the cursor position to the beginning of the BytesIO object
+audio_data.seek(0)
+
+# Create an Audio object from the BytesIO data
+audio = Audio(np.frombuffer(audio_data.read(), dtype=np.float32), rate=output["sampling_rate"])
 
 # Display the Audio object
 display(audio)
 ```
 
-We recommend using [`python-dotenv`](https://pypi.org/project/python-dotenv/) to add `CARTESIA_API_KEY="my-api-key"` to your .env file so that your API Key is not stored in the source code.
+To avoid storing your API key in the source code, we recommend doing one of the following:
+1. Use [`python-dotenv`](https://pypi.org/project/python-dotenv/) to add `CARTESIA_API_KEY="my-api-key"` to your .env file. 
+1. Set the `CARTESIA_API_KEY` environment variable, preferably to a secure shell init file (e.g. `~/.zshrc`, `~/.bashrc`)

{cartesia-0.0.3 → cartesia-0.0.5rc1}/cartesia.egg-info/requires.txt

@@ -1,5 +1,8 @@
-websockets
+aiohttp
+httpx
+pytest-asyncio
 requests
+websockets
 
 [all]
 pre-commit
@@ -10,6 +13,7 @@ flake8==7.0.0
 flake8-bugbear==24.2.6
 pytest>=8.0.2
 pytest-cov>=4.1.0
+twine
 
 [dev]
 pre-commit
@@ -20,3 +24,4 @@ flake8==7.0.0
 flake8-bugbear==24.2.6
 pytest>=8.0.2
 pytest-cov>=4.1.0
+twine

{cartesia-0.0.3 → cartesia-0.0.5rc1}/setup.py

@@ -78,7 +78,8 @@ class UploadCommand(Command):
     """Support setup.py upload."""
 
     description = "Build and publish the package."
-    user_options = []
+    user_options = [("skip-upload", "u", "skip git tagging and pypi upload")]
+    boolean_options = ["skip-upload"]
 
     @staticmethod
     def status(s):
@@ -86,21 +87,26 @@ class UploadCommand(Command):
         print("\033[1m{0}\033[0m".format(s))
 
     def initialize_options(self):
-        pass
+        self.skip_upload = False
 
     def finalize_options(self):
-        pass
+        self.skip_upload = bool(self.skip_upload)
 
     def run(self):
         try:
             self.status("Removing previous builds…")
             rmtree(os.path.join(here, "dist"))
+            rmtree(os.path.join(here, "build"))
         except OSError:
             pass
 
         self.status("Building Source and Wheel (universal) distribution…")
         os.system("{0} setup.py sdist bdist_wheel --universal".format(sys.executable))
 
+        if self.skip_upload:
+            self.status("Skipping git tagging and pypi upload")
+            sys.exit()
+
         self.status("Uploading the package to PyPI via Twine…")
         os.system("twine upload dist/*")
 
@@ -116,6 +122,9 @@ class BumpVersionCommand(Command):
     To use: python setup.py bumpversion -v <version>
 
     This command will push the new version directly and tag it.
+
+    Usage:
+        python setup.py bumpversion --version=1.0.1
     """
 
     description = "Installs the foo."
@@ -130,6 +139,11 @@ class BumpVersionCommand(Command):
 
     def initialize_options(self):
         self.version = None
+        self.base_branch = None
+        self.version_branch = None
+        self.updated_files = [
+            "cartesia/version.py",
+        ]
 
     def finalize_options(self):
         # This package cannot be imported at top level because it
@@ -147,14 +161,18 @@ class BumpVersionCommand(Command):
             )
 
     def _undo(self):
-        os.system(f"git restore --staged {PACKAGE_DIR}/__init__.py")
-        os.system(f"git checkout -- {PACKAGE_DIR}/__init__.py")
+        os.system(f"git restore --staged {' '.join(self.updated_files)}")
+        os.system(f"git checkout -- {' '.join(self.updated_files)}")
+
+        # Return to the original branch
+        os.system(f"git checkout {self.base_branch}")
+        os.system(f"git branch -D {self.version_branch}")
 
     def run(self):
         current_version = about["__version__"]
 
         self.status("Checking current branch is 'main'")
-        current_branch = get_git_branch()
+        self.base_branch = current_branch = get_git_branch()
         if current_branch != "main":
             raise RuntimeError(
                 "You can only bump the version from the 'main' branch. "
@@ -174,33 +192,43 @@ class BumpVersionCommand(Command):
 
         # TODO: Add check to see if all tests are passing on main.
 
+        # Checkout new branch
+        self.version_branch = f"bumpversion/v{self.version}"
+        self.status(f"Create branch '{self.version_branch}'")
+        err_code = os.system(f"git checkout -b {self.version_branch}")
+        if err_code != 0:
+            raise RuntimeError("Failed to create branch.")
+
         # Change the version in __init__.py
         self.status(f"Updating version {current_version} -> {self.version}")
         update_version(self.version)
-        if current_version != self.version:
-            self._undo()
-            raise RuntimeError("Failed to update version.")
+        # if current_version != self.version:
+        #     self._undo()
+        #     raise RuntimeError("Failed to update version.")
 
-        self.status(f"Adding {PACKAGE_DIR}/__init__.py to git")
-        err_code = os.system(f"git add {PACKAGE_DIR}/__init__.py")
+        self.status(f"Adding {', '.join(self.updated_files)} to git")
+        err_code = os.system(f"git add {' '.join(self.updated_files)}")
         if err_code != 0:
             self._undo()
-            raise RuntimeError("Failed to add file to git.")
+            raise RuntimeError("Failed to add files to git.")
 
         # Commit the file with a message '[bumpversion] v<version>'.
         self.status(f"Commit with message '[bumpversion] v{self.version}'")
-        err_code = os.system("git commit -m '[bumpversion] v{}'".format(current_version))
+        err_code = os.system("git commit -m '[bumpversion] v{}'".format(self.version))
         if err_code != 0:
             self._undo()
             raise RuntimeError("Failed to commit file to git.")
 
         # Push the commit to origin.
-        # self.status("Pushing commit to origin")
-        # err_code = os.system("git push")
-        # if err_code != 0:
-        #     # TODO: undo the commit automatically.
-        #     raise RuntimeError("Failed to push commit to origin.")
+        self.status(f"Pushing commit to origin/{self.version_branch}")
+        err_code = os.system(f"git push --force --set-upstream origin {self.version_branch}")
+        if err_code != 0:
+            # TODO: undo the commit automatically.
+            self._undo()
+            raise RuntimeError("Failed to push commit to origin.")
 
+        os.system(f"git checkout {self.base_branch}")
+        os.system(f"git branch -D {self.version_branch}")
         sys.exit()
 
 

{cartesia-0.0.3 → cartesia-0.0.5rc1}/tests/test_tts.py

@@ -6,11 +6,14 @@ but rather for general correctness.
 """
 
 import os
-from typing import Dict, Generator
+import sys
+import uuid
+from typing import AsyncGenerator, Dict, Generator, List
 
 import pytest
 
-from cartesia.tts import CartesiaTTS, VoiceMetadata
+sys.path.append(os.path.dirname(os.path.dirname(__file__)))
+from cartesia.tts import DEFAULT_MODEL_ID, AsyncCartesiaTTS, CartesiaTTS, VoiceMetadata
 
 SAMPLE_VOICE = "Milo"
 
@@ -21,9 +24,24 @@ class _Resources:
         self.voices = voices
 
 
+def create_client():
+    return CartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
+
+
+def create_async_client():
+    return AsyncCartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
+
+
 @pytest.fixture(scope="session")
 def client():
-    return CartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
+    return create_client()
+
+
+@pytest.fixture(scope="session")
+def client_with_ws_interrupt():
+    return CartesiaTTS(
+        api_key=os.environ.get("CARTESIA_API_KEY"), experimental_ws_handle_interrupts=True
+    )
 
 
 @pytest.fixture(scope="session")
@@ -93,6 +111,80 @@ def test_generate_stream(resources: _Resources, websocket: bool):
         assert isinstance(output["sampling_rate"], int)
 
 
+@pytest.mark.parametrize("websocket", [True, False])
+@pytest.mark.asyncio
+async def test_async_generate(resources: _Resources, websocket: bool):
+    voices = resources.voices
+    embedding = voices[SAMPLE_VOICE]["embedding"]
+    transcript = "Hello, world!"
+
+    async_client = create_async_client()
+    output = await async_client.generate(
+        transcript=transcript, voice=embedding, websocket=websocket
+    )
+
+    assert output.keys() == {"audio", "sampling_rate"}
+    assert isinstance(output["audio"], bytes)
+    assert isinstance(output["sampling_rate"], int)
+
+
+@pytest.mark.parametrize("websocket", [True, False])
+@pytest.mark.asyncio
+async def test_async_generate_stream(resources: _Resources, websocket: bool):
+    voices = resources.voices
+    embedding = voices[SAMPLE_VOICE]["embedding"]
+    transcript = "Hello, world!"
+
+    async_client = create_async_client()
+
+    generator = await async_client.generate(transcript=transcript, voice=embedding, stream=True)
+    assert isinstance(generator, AsyncGenerator)
+
+    async for output in generator:
+        assert output.keys() == {"audio", "sampling_rate"}
+        assert isinstance(output["audio"], bytes)
+        assert isinstance(output["sampling_rate"], int)
+
+
+@pytest.mark.parametrize(
+    "actions",
+    [
+        ["cancel-5", None],
+        ["cancel-5", "cancel-1", None],
+        [None, "cancel-3", None],
+        [None, "cancel-1", "cancel-2"],
+    ],
+)
+def test_generate_stream_interrupt(
+    client_with_ws_interrupt: CartesiaTTS, resources: _Resources, actions: List[str]
+):
+    client = client_with_ws_interrupt
+    voices = resources.voices
+    embedding = voices[SAMPLE_VOICE]["embedding"]
+    transcript = "Hello, world!"
+
+    context_ids = [f"test-{uuid.uuid4().hex[:6]}" for _ in range(len(actions))]
+
+    for context_id, action in zip(context_ids, actions):
+        body = dict(transcript=transcript, model_id=DEFAULT_MODEL_ID, voice=embedding)
+
+        # Parse actions to see what we should expect.
+        if action is None:
+            num_turns = None
+        elif "cancel" in action:
+            num_turns = int(action.split("-")[1])
+
+        generator = client._generate_ws(body, context_id=context_id)
+        for idx, response in enumerate(generator):
+            assert response.keys() == {"audio", "sampling_rate", "context_id"}
+            assert response["context_id"] == context_id, (
+                f"Context ID from response ({response['context_id']}) does not match "
+                f"the expected context ID ({context_id})"
+            )
+            if idx + 1 == num_turns:
+                break
+
+
 @pytest.mark.parametrize("chunk_time", [0.05, 0.6])
 def test_check_inputs_invalid_chunk_time(client: CartesiaTTS, chunk_time):
     with pytest.raises(ValueError, match="`chunk_time` must be between 0.1 and 0.5"):

cartesia-0.0.3/cartesia/version.py

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