cartesia 0.0.3__py2.py3-none-any.whl → 0.0.4__py2.py3-none-any.whl

cartesia/tts.py

@@ -31,7 +31,11 @@ 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 +59,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]:
@@ -167,8 +175,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,
         )
 
@@ -280,21 +291,50 @@ 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"]:
+            while True:
+                response = json.loads(self.websocket.recv())
+                if response["done"]:
+                    break
                 audio = base64.b64decode(response["data"])
-                # print("timing", time.perf_counter() - start)
-                yield {"audio": audio, "sampling_rate": response["sampling_rate"]}
 
-                response = json.loads(self.websocket.recv())
-        except Exception:
-            raise RuntimeError(f"Failed to generate audio. {response}")
+                optional_kwargs = {}
+                if include_context_id:
+                    optional_kwargs["context_id"] = response["context_id"]
+
+                yield {
+                    "audio": audio,
+                    "sampling_rate": response["sampling_rate"],
+                    **optional_kwargs,
+                }
+
+                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"

cartesia/version.py

@@ -1 +1 @@
-__version__ = "0.0.3"
+__version__ = "0.0.4"

{cartesia-0.0.3.dist-info → cartesia-0.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 0.0.3
+Version: 0.0.4
 Summary: The official Python library for the Cartesia API.
 Home-page: 
 Author: Cartesia, Inc.
@@ -110,4 +110,6 @@ audio = Audio(audio_data, rate=output["sampling_rate"])
 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.4.dist-info/RECORD

@@ -0,0 +1,7 @@
+cartesia/__init__.py,sha256=m8BX-qLjsMoI_JZtgf3jNi8R3cBZqYy-z4oEhYeJLdI,64
+cartesia/tts.py,sha256=9m9_kqscMY0yzUU0Ty5k2HoeMqfrIbHouaS-ymcr64s,14127
+cartesia/version.py,sha256=1mptEzQihbdyqqzMgdns_j5ZGK9gz7hR2bsgA_TnjO4,22
+cartesia-0.0.4.dist-info/METADATA,sha256=tLUrKLREJiXrW-pfd3k61i9CnElKHk5RAyidCMxpR-s,3752
+cartesia-0.0.4.dist-info/WHEEL,sha256=iYlv5fX357PQyRT2o6tw1bN-YcKFFHKqB_LwHO5wP-g,110
+cartesia-0.0.4.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
+cartesia-0.0.4.dist-info/RECORD,,

cartesia-0.0.3.dist-info/RECORD

@@ -1,7 +0,0 @@
-cartesia/__init__.py,sha256=m8BX-qLjsMoI_JZtgf3jNi8R3cBZqYy-z4oEhYeJLdI,64
-cartesia/tts.py,sha256=ABXW9rc8Pn0GTRvb_7DHZKMtbvhGUiqOgHmvztwlOnI,12033
-cartesia/version.py,sha256=4GZKi13lDTD25YBkGakhZyEQZWTER_OWQMNPoH_UM2c,22
-cartesia-0.0.3.dist-info/METADATA,sha256=VsCGL1sITbKqERihK2rzVm9WIY5EJ5nCS_CXQ0s14ns,3604
-cartesia-0.0.3.dist-info/WHEEL,sha256=iYlv5fX357PQyRT2o6tw1bN-YcKFFHKqB_LwHO5wP-g,110
-cartesia-0.0.3.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
-cartesia-0.0.3.dist-info/RECORD,,