cartesia 1.0.0__py2.py3-none-any.whl → 1.0.2__py2.py3-none-any.whl

cartesia/_types.py

@@ -1,26 +1,63 @@
 from typing import List, TypedDict
+from cartesia.utils.deprecated import deprecated
+
 
 class OutputFormatMapping:
+    _format_mapping = {
+        "raw_pcm_f32le_44100": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 44100},
+        "raw_pcm_s16le_44100": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 44100},
+        "raw_pcm_f32le_24000": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 24000},
+        "raw_pcm_s16le_24000": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 24000},
+        "raw_pcm_f32le_22050": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 22050},
+        "raw_pcm_s16le_22050": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 22050},
+        "raw_pcm_f32le_16000": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 16000},
+        "raw_pcm_s16le_16000": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 16000},
+        "raw_pcm_f32le_8000": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 8000},
+        "raw_pcm_s16le_8000": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 8000},
+        "raw_pcm_mulaw_8000": {"container": "raw", "encoding": "pcm_mulaw", "sample_rate": 8000},
+        "raw_pcm_alaw_8000": {"container": "raw", "encoding": "pcm_alaw", "sample_rate": 8000},
+    }
+
+    @classmethod
+    def get_format(cls, format_name):
+        if format_name in cls._format_mapping:
+            return cls._format_mapping[format_name]
+        else:
+            raise ValueError(f"Unsupported format: {format_name}")
+
+
+class DeprecatedOutputFormatMapping:
+    """Deprecated formats as of v1.0.1. These will be removed in v1.2.0. Use :class:`OutputFormatMapping` instead."""
+
     _format_mapping = {
         "fp32": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 44100},
         "pcm": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 44100},
+        "fp32_8000": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 8000},
         "fp32_16000": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 16000},
         "fp32_22050": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 22050},
+        "fp32_24000": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 24000},
         "fp32_44100": {"container": "raw", "encoding": "pcm_f32le", "sample_rate": 44100},
+        "pcm_8000": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 8000},
         "pcm_16000": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 16000},
         "pcm_22050": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 22050},
+        "pcm_24000": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 24000},
         "pcm_44100": {"container": "raw", "encoding": "pcm_s16le", "sample_rate": 44100},
         "mulaw_8000": {"container": "raw", "encoding": "pcm_mulaw", "sample_rate": 8000},
         "alaw_8000": {"container": "raw", "encoding": "pcm_alaw", "sample_rate": 8000},
     }
 
-    @classmethod
-    def get_format(cls, format_name):
-        if format_name in cls._format_mapping:
-            return cls._format_mapping[format_name]
+    @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]
         else:
             raise ValueError(f"Unsupported format: {format_name}")
-        
+
+
 class VoiceMetadata(TypedDict):
     id: str
     name: str
@@ -30,7 +67,8 @@ class VoiceMetadata(TypedDict):
     user_id: str
     created_at: str
     language: str
-    
+
+
 class OutputFormat(TypedDict):
     container: str
     encoding: str

cartesia/client.py

@@ -12,10 +12,12 @@ import logging
 import requests
 from websockets.sync.client import connect
 
-from cartesia.utils import retry_on_connection_error, retry_on_connection_error_async
+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,
+    DeprecatedOutputFormatMapping,
     VoiceMetadata,
 )
 
@@ -131,14 +133,7 @@ class Voices(Resource):
         """List all voices in your voice library.
 
         Returns:
-        This method returns a list of VoiceMetadata objects with the following keys:
-        - id: The ID of the voice.
-        - name: The name of the voice.
-        - description: The description of the voice.
-        - embedding: The embedding of the voice.
-        - is_public: Whether the voice is public.
-        - user_id: The ID of the user who created the voice.
-        - created_at: The timestamp (str) when the voice was created.
+        This method returns a list of VoiceMetadata objects.
         """
         response = httpx.get(
             f"{self._http_url()}/voices",
@@ -159,14 +154,7 @@ class Voices(Resource):
             id: The ID of the voice.
 
         Returns:
-            A dictionary containing the voice metadata with the following keys:
-            - id: The ID of the voice.
-            - name: The name of the voice.
-            - description: The description of the voice.
-            - embedding: The embedding of the voice as a list of floats.
-            - is_public: Whether the voice is public.
-            - user_id: The ID of the user who created the voice.
-            - created_at: The timestamp when the voice was created.
+            A VoiceMetadata object containing the voice metadata.
         """
         url = f"{self._http_url()}/voices/{id}"
         response = httpx.get(url, headers=self.headers, timeout=self.timeout)
@@ -344,8 +332,11 @@ class _WebSocket:
             stream: Whether to stream the audio or not. (Default is True)
 
         Returns:
-            If `stream` is True, the method returns a generator that yields chunks of audio as bytes.
-            If `stream` is False, the method returns a dictionary containing the concatenated audio as bytes and the context ID.
+            If `stream` is True, the method returns a generator that yields chunks. Each chunk is a dictionary.
+            If `stream` is False, the method returns a dictionary.
+            Both the generator and the dictionary contain the following key(s):
+            - audio: The audio as bytes.
+            - context_id: The context ID for the request.
         """
         self.connect()
 
@@ -490,8 +481,10 @@ class _SSE:
             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 containing the audio as bytes.
-            If `stream` is False, the method returns a dictionary containing the audio as bytes.
+            If `stream` is True, the method returns a generator that yields chunks. Each chunk is a dictionary.
+            If `stream` is False, the method returns a dictionary.
+            Both the generator and the dictionary contain the following key(s):
+            - audio: The audio as bytes.
         """
         voice = self._validate_and_construct_voice(voice_id, voice_embedding)
 
@@ -581,15 +574,26 @@ class TTS(Resource):
         return ws
 
     def get_output_format(self, output_format_name: str) -> OutputFormat:
-        """Convenience method to get the output_format object from a given output format name.
+        """Convenience method to get the output_format dictionary from a given output format name.
 
         Args:
             output_format_name (str): The name of the output format.
 
         Returns:
             OutputFormat: A dictionary containing the details of the output format to be passed into tts.sse() or tts.websocket().send()
+
+        Raises:
+            ValueError: If the output_format name is not supported
         """
-        output_format_obj = OutputFormatMapping.get_format(output_format_name)
+        if output_format_name in OutputFormatMapping._format_mapping:
+            output_format_obj = OutputFormatMapping.get_format(output_format_name)
+        elif output_format_name in DeprecatedOutputFormatMapping._format_mapping:
+            output_format_obj = DeprecatedOutputFormatMapping.get_format_deprecated(
+                output_format_name
+            )
+        else:
+            raise ValueError(f"Unsupported format: {output_format_name}")
+
         return OutputFormat(
             container=output_format_obj["container"],
             encoding=output_format_obj["encoding"],
@@ -604,8 +608,19 @@ class TTS(Resource):
 
         Returns:
             int: The sample rate for the output format.
+
+        Raises:
+            ValueError: If the output_format name is not supported
         """
-        output_format_obj = OutputFormatMapping.get_format(output_format_name)
+        if output_format_name in OutputFormatMapping._format_mapping:
+            output_format_obj = OutputFormatMapping.get_format(output_format_name)
+        elif output_format_name in DeprecatedOutputFormatMapping._format_mapping:
+            output_format_obj = DeprecatedOutputFormatMapping.get_format_deprecated(
+                output_format_name
+            )
+        else:
+            raise ValueError(f"Unsupported format: {output_format_name}")
+
         return output_format_obj["sample_rate"]
 
 

cartesia/version.py

@@ -1 +1 @@
-__version__ = "1.0.0"
+__version__ = "1.0.2"

{cartesia-1.0.0.dist-info → cartesia-1.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 1.0.0
+Version: 1.0.2
 Summary: The official Python library for the Cartesia API.
 Home-page: 
 Author: Cartesia, Inc.
@@ -38,10 +38,8 @@ Requires-Dist: numpy ; extra == 'dev'
 
 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.
-
 > [!IMPORTANT]
-> The client library introduces breaking changes in v1.0.0, which was released on June 24th 2024. See the [release notes](https://github.com/cartesia-ai/cartesia-python/discussions/44) here and reach out to us on [Discord](https://discord.gg/ZVxavqHB9X) if you have any questions!
+> The client library introduces breaking changes in v1.0.0, which was released on June 24th 2024. See the [release notes](https://github.com/cartesia-ai/cartesia-python/releases/tag/v1.0.0) and [migration guide](https://github.com/cartesia-ai/cartesia-python/discussions/44). Reach out to us on [Discord](https://discord.gg/ZVxavqHB9X) for any support requests!
 
 ## Documentation
 
@@ -76,7 +74,11 @@ print("The embedding for", voice["name"], "is", voice["embedding"])
 cloned_voice_embedding = client.voices.clone(filepath="path/to/voice")
 
 # Create a new voice
-new_voice = client.voices.create(name="New Voice", description="A clone of my own voice", embedding=cloned_voice_embedding)
+new_voice = client.voices.create(
+    name="New Voice",
+    description="A clone of my own voice",
+    embedding=cloned_voice_embedding,
+)
 ```
 
 ## Text-to-Speech
@@ -111,14 +113,17 @@ rate = 44100
 stream = None
 
 # Generate and stream audio
-for output in client.tts.sse(model_id=model_id, transcript=transcript, voice_embedding=voice["embedding"], stream=True, output_format=output_format):
+for output in client.tts.sse(
+    model_id=model_id,
+    transcript=transcript,
+    voice_embedding=voice["embedding"],
+    stream=True,
+    output_format=output_format,
+):
     buffer = output["audio"]
 
     if not stream:
-        stream = p.open(format=pyaudio.paFloat32,
-                        channels=1,
-                        rate=rate,
-                        output=True)
+        stream = p.open(format=pyaudio.paFloat32, channels=1, rate=rate, output=True)
 
     # Write the audio data to the stream
     stream.write(buffer)
@@ -136,6 +141,7 @@ import asyncio
 import pyaudio
 import os
 
+
 async def write_stream():
     client = AsyncCartesia(api_key=os.environ.get("CARTESIA_API_KEY"))
     voice_name = "Barbershop Man"
@@ -158,15 +164,19 @@ async def write_stream():
     stream = None
 
     # Generate and stream audio
-    async for output in await client.tts.sse(model_id=model_id, transcript=transcript, voice_embedding=voice["embedding"], stream=True, output_format=output_format
+    async for output in await client.tts.sse(
+        model_id=model_id,
+        transcript=transcript,
+        voice_embedding=voice["embedding"],
+        stream=True,
+        output_format=output_format,
     ):
         buffer = output["audio"]
 
         if not stream:
-            stream = p.open(format=pyaudio.paFloat32,
-                            channels=1,
-                            rate=rate,
-                            output=True)
+            stream = p.open(
+                format=pyaudio.paFloat32, channels=1, rate=rate, output=True
+            )
 
         # Write the audio data to the stream
         stream.write(buffer)
@@ -174,6 +184,8 @@ async def write_stream():
     stream.stop_stream()
     stream.close()
     p.terminate()
+    await client.close()
+
 
 asyncio.run(write_stream())
 ```
@@ -210,14 +222,17 @@ stream = None
 ws = client.tts.websocket()
 
 # Generate and stream audio using the websocket
-for output in ws.send(model_id=model_id, transcript=transcript, voice_embedding=voice["embedding"], stream=True, output_format=output_format):
+for output in ws.send(
+    model_id=model_id,
+    transcript=transcript,
+    voice_embedding=voice["embedding"],
+    stream=True,
+    output_format=output_format,
+):
     buffer = output["audio"]
 
     if not stream:
-        stream = p.open(format=pyaudio.paFloat32,
-                        channels=1,
-                        rate=rate,
-                        output=True)
+        stream = p.open(format=pyaudio.paFloat32, channels=1, rate=rate, output=True)
 
     # Write the audio data to the stream
     stream.write(buffer)
@@ -226,7 +241,7 @@ stream.stop_stream()
 stream.close()
 p.terminate()
 
-ws.close() # Close the websocket connection
+ws.close()  # Close the websocket connection
 ```
 
 ### Multilingual Text-to-Speech [Alpha]
@@ -262,14 +277,18 @@ rate = 44100
 stream = None
 
 # Pass in the corresponding language code to the `language` parameter to generate and stream audio.
-for output in client.tts.sse(model_id=model_id, transcript=transcript, voice_embedding=voice["embedding"], stream=True, output_format=output_format, language=language):
+for output in client.tts.sse(
+    model_id=model_id,
+    transcript=transcript,
+    voice_embedding=voice["embedding"],
+    stream=True,
+    output_format=output_format,
+    language=language,
+):
     buffer = output["audio"]
 
     if not stream:
-        stream = p.open(format=pyaudio.paFloat32,
-                        channels=1,
-                        rate=rate,
-                        output=True)
+        stream = p.open(format=pyaudio.paFloat32, channels=1, rate=rate, output=True)
 
     stream.write(buffer)
 
@@ -304,7 +323,12 @@ with Cartesia(api_key=os.environ.get("CARTESIA_API_KEY")) as client:
     audio_data = io.BytesIO()
 
     # Generate and stream audio
-    for output in client.tts.sse(model_id="sonic-english", transcript=transcript, voice_embedding=voice["embedding"], stream=True, output_format=output_format
+    for output in client.tts.sse(
+        model_id="sonic-english",
+        transcript=transcript,
+        voice_embedding=voice["embedding"],
+        stream=True,
+        output_format=output_format,
     ):
         buffer = output["audio"]
         audio_data.write(buffer)
@@ -343,7 +367,12 @@ async with AsyncCartesia(api_key=os.environ.get("CARTESIA_API_KEY")) as client:
     audio_data = io.BytesIO()
 
     # Generate and stream audio
-    async for output in client.tts.sse(model_id="sonic-english", transcript=transcript, voice_id=voice_id, stream=True, output_format=output_format
+    async for output in client.tts.sse(
+        model_id="sonic-english",
+        transcript=transcript,
+        voice_id=voice_id,
+        stream=True,
+        output_format=output_format,
     ):
         buffer = output["audio"]
         audio_data.write(buffer)
@@ -358,6 +387,28 @@ audio = Audio(np.frombuffer(audio_data.read(), dtype=np.float32), rate=rate)
 display(audio)
 ```
 
+### Utility methods
+
+#### Output Formats
+
+You can use the `client.tts.get_output_format` method to convert string-based output format names into the `output_format` dictionary which is expected by the `output_format` parameter. You can see the `OutputFormatMapping` class in `cartesia._types` for the currently supported output format names. You can also view the currently supported `output_format`s in our [API Reference](https://docs.cartesia.ai/api-reference/endpoints/stream-speech-server-sent-events).
+
+The previously used `output_format` strings are now deprecated and will be removed in v1.2.0. These are listed in the `DeprecatedOutputFormatMapping` class in `cartesia._types`.
+
+```python
+# Get the output format dictionary from string name
+output_format = client.tts.get_output_format("raw_pcm_f32le_44100")
+
+# Pass in the output format dictionary to generate and stream audio
+generator = client.tts.sse(
+    model_id=model,
+    transcript=transcript,
+    voice_id=SAMPLE_VOICE_ID,
+    stream=True,
+    output_format=output_format,
+)
+```
+
 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.

cartesia-1.0.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+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=Y3LSfRioSl2xch70pq_ULlvyECXyEtN3krVaWeGyaxk,22
+cartesia-1.0.2.dist-info/METADATA,sha256=LPW7f4297S2DQ_uRtc3A-7-5WUCXsIgGcr1M3XelXys,12394
+cartesia-1.0.2.dist-info/WHEEL,sha256=DZajD4pwLWue70CAfc7YaxT1wLUciNBvN_TTcvXpltE,110
+cartesia-1.0.2.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
+cartesia-1.0.2.dist-info/RECORD,,

cartesia/utils.py

@@ -1,87 +0,0 @@
-import time
-
-from aiohttp.client_exceptions import ServerDisconnectedError
-import asyncio
-from functools import wraps
-from http.client import RemoteDisconnected
-from httpx import TimeoutException
-from requests.exceptions import ConnectionError
-
-
-def retry_on_connection_error(max_retries=3, backoff_factor=1, logger=None):
-    """Retry a function if a ConnectionError, RemoteDisconnected, ServerDisconnectedError, or TimeoutException occurs.
-
-    Args:
-        max_retries (int): The maximum number of retries.
-        backoff_factor (int): The factor to increase the delay between retries.
-        logger (logging.Logger): The logger to use for logging.
-    """
-
-    def decorator(func):
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            retry_count = 0
-            while retry_count < max_retries:
-                try:
-                    return func(*args, **kwargs)
-                except (
-                    ConnectionError,
-                    RemoteDisconnected,
-                    ServerDisconnectedError,
-                    TimeoutException,
-                ) as e:
-                    logger.info(f"Retrying after exception: {e}")
-                    retry_count += 1
-                    if retry_count < max_retries:
-                        delay = backoff_factor * (2 ** (retry_count - 1))
-                        logger.warn(
-                            f"Attempt {retry_count + 1}/{max_retries} in {delay} seconds..."
-                        )
-                        time.sleep(delay)
-                    else:
-                        raise Exception(f"Exception occurred after {max_retries} tries.") from e
-
-        return wrapper
-
-    return decorator
-
-
-def retry_on_connection_error_async(max_retries=3, backoff_factor=1, logger=None):
-    """Retry an asynchronous function if a ConnectionError, RemoteDisconnected, ServerDisconnectedError, or TimeoutException occurs.
-
-    Args:
-        max_retries (int): The maximum number of retries.
-        backoff_factor (int): The factor to increase the delay between retries.
-        logger (logging.Logger): The logger to use for logging.
-    """
-
-    def decorator(func):
-        @wraps(func)
-        async def wrapper(*args, **kwargs):
-            retry_count = 0
-            while retry_count < max_retries:
-                try:
-                    async for chunk in func(*args, **kwargs):
-                        yield chunk
-                    # If the function completes without raising an exception return
-                    return
-                except (
-                    ConnectionError,
-                    RemoteDisconnected,
-                    ServerDisconnectedError,
-                    TimeoutException,
-                ) as e:
-                    logger.info(f"Retrying after exception: {e}")
-                    retry_count += 1
-                    if retry_count < max_retries:
-                        delay = backoff_factor * (2 ** (retry_count - 1))
-                        logger.warn(
-                            f"Attempt {retry_count + 1}/{max_retries} in {delay} seconds..."
-                        )
-                        await asyncio.sleep(delay)
-                    else:
-                        raise Exception(f"Exception occurred after {max_retries} tries.") from e
-
-        return wrapper
-
-    return decorator

cartesia-1.0.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-cartesia/__init__.py,sha256=jMIf2O7dTGxvTA5AfXtmh1H_EGfMtQseR5wXrjNRbLs,93
-cartesia/_types.py,sha256=M-gtOFGBRWYAHUpJZNEl2jodqmNm_ZIPQUHkXLyP_-s,1503
-cartesia/client.py,sha256=9uSIYzGGE-Bgcsq5qJ1ApVesAGz_l5Olg07ZUvw268Q,32306
-cartesia/utils.py,sha256=nuwWRfu3MOVTxIQMLjYf6WLaxSlnu_GdE3QjTV0zisQ,3339
-cartesia/version.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
-cartesia-1.0.0.dist-info/METADATA,sha256=PAsYxXc-s1TO_2ROmlLUH4w4CXI7zRMOjmSo0cHg_Os,11399
-cartesia-1.0.0.dist-info/WHEEL,sha256=DZajD4pwLWue70CAfc7YaxT1wLUciNBvN_TTcvXpltE,110
-cartesia-1.0.0.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
-cartesia-1.0.0.dist-info/RECORD,,