cartesia 1.0.3__tar.gz → 1.0.5__tar.gz

cartesia-1.0.5/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 → cartesia-1.0.5}/PKG-INFO

@@ -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.
@@ -12,6 +12,7 @@ Requires-Python: >=3.8.0
 Description-Content-Type: text/markdown
 Provides-Extra: dev
 Provides-Extra: all
+License-File: LICENSE.md
 
 
 # Cartesia Python API Library
@@ -80,10 +81,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",
@@ -131,10 +132,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",
@@ -186,10 +187,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",
@@ -227,6 +228,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).
@@ -244,10 +418,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.3 → cartesia-1.0.5}/README.md

@@ -64,10 +64,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",
@@ -115,10 +115,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",
@@ -170,10 +170,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",
@@ -211,6 +211,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).
@@ -228,10 +401,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.3 → cartesia-1.0.5}/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}")