cartesia 0.0.2__tar.gz → 0.0.3__tar.gz

{cartesia-0.0.2 → cartesia-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 0.0.2
+Version: 0.0.3
 Summary: The official Python library for the Cartesia API.
 Home-page: 
 Author: Cartesia, Inc.
@@ -12,7 +12,6 @@ Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
 Requires-Dist: websockets
 Requires-Dist: requests
-Requires-Dist: numpy
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: docformatter; extra == "dev"
@@ -49,22 +48,66 @@ pip install -e '.[dev]'
 ## Usage
 ```python
 from cartesia.tts import CartesiaTTS
-from IPython.display import Audio
+import pyaudio
+import os
 
 client = CartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
-
 voices = client.get_voices()
-embedding = voices["Milo"]["embedding"]
+voice = client.get_voice_embedding(voice_id=voices["Graham"]["id"])
 transcript = "Hello! Welcome to Cartesia"
 
-# No streaming
-output = client.generate(transcript=transcript, voice=embedding)
-Audio(output["audio"], rate=output["sampling_rate"])
+p = pyaudio.PyAudio()
+
+stream = None
 
-# Streaming
-for output in client.generate(transcript=transcript, voice=embedding, stream=True):
-    arr = output["audio"]  # a numpy array
+# Generate and stream audio
+for output in client.generate(transcript=transcript, voice=voice, stream=True):
+    buffer = output["audio"]
     rate = output["sampling_rate"]
+
+    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()
+```
+
+If you are using Jupyter Notebook or JupyterLab, you can use IPython.display.Audio to play the generated audio directly in the notebook. Here's an example:
+
+```python
+from cartesia.tts import CartesiaTTS
+from IPython.display import Audio
+import io
+import os
+
+client = CartesiaTTS(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
+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(audio_data, 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.

cartesia-0.0.3/README.md

@@ -0,0 +1,79 @@
+# Cartesia Python API Library
+The official Cartesia Python library which provides convenient access to the Cartesia REST and Websocket API from any Python 3.8+ application.
+
+**Note:** This API is still in alpha. Please expect breaking changes and report any issues you encounter.
+
+## Installation
+```bash
+pip install cartesia
+
+# pip install in editable mode w/ dev dependencies
+pip install -e '.[dev]'
+```
+
+## Usage
+```python
+from cartesia.tts import CartesiaTTS
+import pyaudio
+import os
+
+client = CartesiaTTS(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"
+
+p = pyaudio.PyAudio()
+
+stream = None
+
+# Generate and stream audio
+for output in client.generate(transcript=transcript, voice=voice, stream=True):
+    buffer = output["audio"]
+    rate = output["sampling_rate"]
+
+    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()
+```
+
+If you are using Jupyter Notebook or JupyterLab, you can use IPython.display.Audio to play the generated audio directly in the notebook. Here's an example:
+
+```python
+from cartesia.tts import CartesiaTTS
+from IPython.display import Audio
+import io
+import os
+
+client = CartesiaTTS(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
+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(audio_data, 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.

{cartesia-0.0.2 → cartesia-0.0.3}/cartesia/tts.py

@@ -4,7 +4,6 @@ import os
 import uuid
 from typing import Any, Dict, Generator, List, Optional, TypedDict, Union
 
-import numpy as np
 import requests
 from websockets.sync.client import connect
 
@@ -14,7 +13,7 @@ DEFAULT_API_VERSION = "v0"
 
 
 class AudioOutput(TypedDict):
-    audio: np.ndarray
+    audio: bytes
     sampling_rate: int
 
 
@@ -176,13 +175,26 @@ class CartesiaTTS:
     def _is_websocket_closed(self):
         return self.websocket.socket.fileno() == -1
 
+    def _check_inputs(
+        self, transcript: str, duration: Optional[float], chunk_time: Optional[float]
+    ):
+        if chunk_time is not None:
+            if chunk_time < 0.1 or chunk_time > 0.5:
+                raise ValueError("`chunk_time` must be between 0.1 and 0.5")
+
+        if chunk_time is not None and duration is not None:
+            if duration < chunk_time:
+                raise ValueError("`duration` must be greater than chunk_time")
+
+        if transcript.strip() == "":
+            raise ValueError("`transcript` must be non empty")
+
     def generate(
         self,
         *,
         transcript: str,
         duration: int = None,
         chunk_time: float = None,
-        lookahead: int = None,
         voice: Embedding = None,
         stream: bool = False,
         websocket: bool = True,
@@ -194,8 +206,6 @@ class CartesiaTTS:
             duration: The maximum duration of the audio in seconds.
             chunk_time: How long each audio segment should be in seconds.
                 This should not need to be adjusted.
-            lookahead: The number of seconds to look ahead for each chunk.
-                This should not need to be adjusted.
             voice: The voice to use for generating audio.
                 This can either be a voice id (string) or an embedding vector (List[float]).
             stream: Whether to stream the audio or not.
@@ -206,18 +216,16 @@ class CartesiaTTS:
         Returns:
             A generator if `stream` is True, otherwise a dictionary.
             Dictionary from both generator and non-generator return types have the following keys:
-                * "audio": The audio as a 1D numpy array.
+                * "audio": The audio as a bytes buffer.
                 * "sampling_rate": The sampling rate of the audio.
         """
-        body = dict(transcript=transcript, model_id=DEFAULT_MODEL_ID)
+        self._check_inputs(transcript, duration, chunk_time)
 
-        if isinstance(voice, str):
-            voice = self._voices[voice]
+        body = dict(transcript=transcript, model_id=DEFAULT_MODEL_ID)
 
         optional_body = dict(
             duration=duration,
             chunk_time=chunk_time,
-            lookahead=lookahead,
             voice=voice,
         )
         body.update({k: v for k, v in optional_body.items() if v is not None})
@@ -237,7 +245,7 @@ class CartesiaTTS:
                 sampling_rate = chunk["sampling_rate"]
             chunks.append(chunk["audio"])
 
-        return {"audio": np.concatenate(chunks), "sampling_rate": sampling_rate}
+        return {"audio": b"".join(chunks), "sampling_rate": sampling_rate}
 
     def _generate_http(self, body: Dict[str, Any]):
         response = requests.post(
@@ -258,8 +266,7 @@ class CartesiaTTS:
                 if start_index != -1 and end_index != -1:
                     try:
                         chunk_json = json.loads(buffer[start_index : end_index + 1])
-                        data = base64.b64decode(chunk_json["data"])
-                        audio = np.frombuffer(data, dtype=np.float32)
+                        audio = base64.b64decode(chunk_json["data"])
                         yield {"audio": audio, "sampling_rate": chunk_json["sampling_rate"]}
                         buffer = buffer[end_index + 1 :]
                     except json.JSONDecodeError:
@@ -268,8 +275,7 @@ class CartesiaTTS:
         if buffer:
             try:
                 chunk_json = json.loads(buffer)
-                data = base64.b64decode(chunk_json["data"])
-                audio = np.frombuffer(data, dtype=np.float32)
+                audio = base64.b64decode(chunk_json["data"])
                 yield {"audio": audio, "sampling_rate": chunk_json["sampling_rate"]}
             except json.JSONDecodeError:
                 pass
@@ -282,8 +288,7 @@ class CartesiaTTS:
         try:
             response = json.loads(self.websocket.recv())
             while not response["done"]:
-                data = base64.b64decode(response["data"])
-                audio = np.frombuffer(data, dtype=np.float32)
+                audio = base64.b64decode(response["data"])
                 # print("timing", time.perf_counter() - start)
                 yield {"audio": audio, "sampling_rate": response["sampling_rate"]}
 

cartesia-0.0.3/cartesia/version.py

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 0.0.2
+Version: 0.0.3
 Summary: The official Python library for the Cartesia API.
 Home-page: 
 Author: Cartesia, Inc.
@@ -12,7 +12,6 @@ Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
 Requires-Dist: websockets
 Requires-Dist: requests
-Requires-Dist: numpy
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: docformatter; extra == "dev"
@@ -49,22 +48,66 @@ pip install -e '.[dev]'
 ## Usage
 ```python
 from cartesia.tts import CartesiaTTS
-from IPython.display import Audio
+import pyaudio
+import os
 
 client = CartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
-
 voices = client.get_voices()
-embedding = voices["Milo"]["embedding"]
+voice = client.get_voice_embedding(voice_id=voices["Graham"]["id"])
 transcript = "Hello! Welcome to Cartesia"
 
-# No streaming
-output = client.generate(transcript=transcript, voice=embedding)
-Audio(output["audio"], rate=output["sampling_rate"])
+p = pyaudio.PyAudio()
+
+stream = None
 
-# Streaming
-for output in client.generate(transcript=transcript, voice=embedding, stream=True):
-    arr = output["audio"]  # a numpy array
+# Generate and stream audio
+for output in client.generate(transcript=transcript, voice=voice, stream=True):
+    buffer = output["audio"]
     rate = output["sampling_rate"]
+
+    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()
+```
+
+If you are using Jupyter Notebook or JupyterLab, you can use IPython.display.Audio to play the generated audio directly in the notebook. Here's an example:
+
+```python
+from cartesia.tts import CartesiaTTS
+from IPython.display import Audio
+import io
+import os
+
+client = CartesiaTTS(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
+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(audio_data, 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.

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

@@ -1,6 +1,5 @@
 websockets
 requests
-numpy
 
 [all]
 pre-commit

{cartesia-0.0.2 → cartesia-0.0.3}/tests/test_tts.py

@@ -8,7 +8,6 @@ but rather for general correctness.
 import os
 from typing import Dict, Generator
 
-import numpy as np
 import pytest
 
 from cartesia.tts import CartesiaTTS, VoiceMetadata
@@ -72,8 +71,7 @@ def test_generate(resources: _Resources, websocket: bool):
 
     output = client.generate(transcript=transcript, voice=embedding, websocket=websocket)
     assert output.keys() == {"audio", "sampling_rate"}
-    assert isinstance(output["audio"], np.ndarray)
-    assert output["audio"].dtype == np.float32
+    assert isinstance(output["audio"], bytes)
     assert isinstance(output["sampling_rate"], int)
 
 
@@ -91,6 +89,45 @@ def test_generate_stream(resources: _Resources, websocket: bool):
 
     for output in generator:
         assert output.keys() == {"audio", "sampling_rate"}
-        assert isinstance(output["audio"], np.ndarray)
-        assert output["audio"].dtype == np.float32
+        assert isinstance(output["audio"], bytes)
         assert isinstance(output["sampling_rate"], int)
+
+
+@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"):
+        client._check_inputs("Test", None, chunk_time)
+
+
+@pytest.mark.parametrize("chunk_time", [0.1, 0.3, 0.5])
+def test_check_inputs_valid_chunk_time(client, chunk_time):
+    try:
+        client._check_inputs("Test", None, chunk_time)
+    except ValueError:
+        pytest.fail("Unexpected ValueError raised")
+
+
+def test_check_inputs_duration_less_than_chunk_time(client: CartesiaTTS):
+    with pytest.raises(ValueError, match="`duration` must be greater than chunk_time"):
+        client._check_inputs("Test", 0.2, 0.3)
+
+
+@pytest.mark.parametrize("duration,chunk_time", [(0.5, 0.2), (1.0, 0.5), (2.0, 0.1)])
+def test_check_inputs_valid_duration_and_chunk_time(client: CartesiaTTS, duration, chunk_time):
+    try:
+        client._check_inputs("Test", duration, chunk_time)
+    except ValueError:
+        pytest.fail("Unexpected ValueError raised")
+
+
+def test_check_inputs_empty_transcript(client: CartesiaTTS):
+    with pytest.raises(ValueError, match="`transcript` must be non empty"):
+        client._check_inputs("", None, None)
+
+
+@pytest.mark.parametrize("transcript", ["Hello", "Test transcript", "Lorem ipsum dolor sit amet"])
+def test_check_inputs_valid_transcript(client: CartesiaTTS, transcript):
+    try:
+        client._check_inputs(transcript, None, None)
+    except ValueError:
+        pytest.fail("Unexpected ValueError raised")

cartesia-0.0.2/README.md

@@ -1,35 +0,0 @@
-# Cartesia Python API Library
-The official Cartesia Python library which provides convenient access to the Cartesia REST and Websocket API from any Python 3.8+ application.
-
-**Note:** This API is still in alpha. Please expect breaking changes and report any issues you encounter.
-
-## Installation
-```bash
-pip install cartesia
-
-# pip install in editable mode w/ dev dependencies
-pip install -e '.[dev]'
-```
-
-## Usage
-```python
-from cartesia.tts import CartesiaTTS
-from IPython.display import Audio
-
-client = CartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
-
-voices = client.get_voices()
-embedding = voices["Milo"]["embedding"]
-transcript = "Hello! Welcome to Cartesia"
-
-# No streaming
-output = client.generate(transcript=transcript, voice=embedding)
-Audio(output["audio"], rate=output["sampling_rate"])
-
-# Streaming
-for output in client.generate(transcript=transcript, voice=embedding, stream=True):
-    arr = output["audio"]  # a numpy array
-    rate = output["sampling_rate"]
-```
-
-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.

cartesia-0.0.2/cartesia/version.py

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