cartesia 1.0.12__py2.py3-none-any.whl → 1.0.14__py2.py3-none-any.whl

cartesia/resource.py

@@ -0,0 +1,44 @@
+from cartesia._constants import DEFAULT_CARTESIA_VERSION
+
+
+class Resource:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+    ):
+        """Constructor for the Resource class. Used by the Voices and TTS classes."""
+        self.api_key = api_key
+        self.timeout = timeout
+        self._base_url = base_url
+        self.cartesia_version = DEFAULT_CARTESIA_VERSION
+        self.headers = {
+            "X-API-Key": self.api_key,
+            "Cartesia-Version": self.cartesia_version,
+            "Content-Type": "application/json",
+        }
+
+    @property
+    def base_url(self):
+        return self._base_url
+
+    def _http_url(self):
+        """Returns the HTTP URL for the Cartesia API.
+        If the base URL is localhost, the URL will start with 'http'. Otherwise, it will start with 'https'.
+        """
+        if self._base_url.startswith("http://") or self._base_url.startswith("https://"):
+            return self._base_url
+        else:
+            prefix = "http" if "localhost" in self._base_url else "https"
+            return f"{prefix}://{self._base_url}"
+
+    def _ws_url(self):
+        """Returns the WebSocket URL for the Cartesia API.
+        If the base URL is localhost, the URL will start with 'ws'. Otherwise, it will start with 'wss'.
+        """
+        if self._base_url.startswith("ws://") or self._base_url.startswith("wss://"):
+            return self._base_url
+        else:
+            prefix = "ws" if "localhost" in self._base_url else "wss"
+            return f"{prefix}://{self._base_url}"

cartesia/tts.py

@@ -0,0 +1,109 @@
+from typing import List, Optional
+
+from cartesia._sse import _SSE
+from cartesia._types import (
+    DeprecatedOutputFormatMapping,
+    OutputFormat,
+    OutputFormatMapping,
+    VoiceControls,
+)
+from cartesia._websocket import _WebSocket
+from cartesia.resource import Resource
+from cartesia.utils.tts import _validate_and_construct_voice
+
+
+class TTS(Resource):
+    """This resource contains methods to generate audio using Cartesia's text-to-speech API."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: float):
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+        self._sse_class = _SSE(self._http_url(), self.headers, self.timeout)
+        self.sse = self._sse_class.send
+
+    def websocket(self) -> _WebSocket:
+        """This method returns a WebSocket object that can be used to generate audio using WebSocket.
+
+        Returns:
+            _WebSocket: A WebSocket object that can be used to generate audio using WebSocket.
+        """
+        ws = _WebSocket(self._ws_url(), self.api_key, self.cartesia_version)
+        ws.connect()
+        return ws
+
+    @staticmethod
+    def get_output_format(output_format_name: str) -> OutputFormat:
+        """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
+        """
+        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"],
+            sample_rate=output_format_obj["sample_rate"],
+        )
+
+    @staticmethod
+    def get_sample_rate(output_format_name: str) -> int:
+        """Convenience method to get the sample rate for a given output format.
+
+        Args:
+            output_format_name (str): The name of the output format.
+
+        Returns:
+            int: The sample rate for the output format.
+
+        Raises:
+            ValueError: If the output_format name is not supported
+        """
+        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"]
+
+    @staticmethod
+    def _validate_and_construct_voice(
+        voice_id: Optional[str] = None,
+        voice_embedding: Optional[List[float]] = None,
+        experimental_voice_controls: Optional[VoiceControls] = None,
+    ) -> dict:
+        """Validate and construct the voice dictionary for the request.
+
+        Args:
+            voice_id: The ID of the voice to use for generating audio.
+            voice_embedding: The embedding of the voice to use for generating audio.
+            experimental_voice_controls: Voice controls for emotion and speed.
+                Note: This is an experimental feature and may rapidly change in the future.
+
+        Returns:
+            A dictionary representing the voice configuration.
+
+        Raises:
+            ValueError: If neither or both voice_id and voice_embedding are specified.
+        """
+        return _validate_and_construct_voice(voice_id, voice_embedding, experimental_voice_controls)

cartesia/utils/tts.py

@@ -0,0 +1,25 @@
+from typing import List, Optional
+
+from cartesia._types import VoiceControls
+
+
+def _validate_and_construct_voice(
+    voice_id: Optional[str] = None,
+    voice_embedding: Optional[List[float]] = None,
+    experimental_voice_controls: Optional[VoiceControls] = None,
+) -> dict:
+    if voice_id is None and voice_embedding is None:
+        raise ValueError("Either voice_id or voice_embedding must be specified.")
+
+    voice = {}
+
+    if voice_id is not None:
+        voice["id"] = voice_id
+
+    if voice_embedding is not None:
+        voice["embedding"] = voice_embedding
+
+    if experimental_voice_controls is not None:
+        voice["__experimental_controls"] = experimental_voice_controls
+
+    return voice

cartesia/version.py

@@ -1 +1 @@
-__version__ = "1.0.12"
+__version__ = "1.0.14"

cartesia/voices.py

@@ -0,0 +1,170 @@
+from typing import Dict, List, Optional, Union
+
+import httpx
+
+from cartesia._types import VoiceMetadata
+from cartesia.resource import Resource
+
+
+class Voices(Resource):
+    """This resource contains methods to list, get, clone, and create voices in your Cartesia voice library.
+
+    Usage:
+        >>> client = Cartesia(api_key="your_api_key")
+        >>> voices = client.voices.list()
+        >>> voice = client.voices.get(id="a0e99841-438c-4a64-b679-ae501e7d6091")
+        >>> print("Voice Name:", voice["name"], "Voice Description:", voice["description"])
+        >>> embedding = client.voices.clone(filepath="path/to/clip.wav")
+        >>> new_voice = client.voices.create(
+        ...     name="My Voice", description="A new voice", embedding=embedding
+        ... )
+    """
+
+    def list(self) -> List[VoiceMetadata]:
+        """List all voices in your voice library.
+
+        Returns:
+        This method returns a list of VoiceMetadata objects.
+        """
+        response = httpx.get(
+            f"{self._http_url()}/voices",
+            headers=self.headers,
+            timeout=self.timeout,
+        )
+
+        if not response.is_success:
+            raise ValueError(f"Failed to get voices. Error: {response.text}")
+
+        voices = response.json()
+        return voices
+
+    def get(self, id: str) -> VoiceMetadata:
+        """Get a voice by its ID.
+
+        Args:
+            id: The ID of the voice.
+
+        Returns:
+            A VoiceMetadata object containing the voice metadata.
+        """
+        url = f"{self._http_url()}/voices/{id}"
+        response = httpx.get(url, headers=self.headers, timeout=self.timeout)
+
+        if not response.is_success:
+            raise ValueError(
+                f"Failed to get voice. Status Code: {response.status_code}\n"
+                f"Error: {response.text}"
+            )
+
+        return response.json()
+
+    def clone(self, filepath: Optional[str] = None, enhance: str = True) -> List[float]:
+        """Clone a voice from a clip.
+
+        Args:
+            filepath: The path to the clip file.
+            enhance: Whether to enhance the clip before cloning the voice (highly recommended). Defaults to True.
+
+        Returns:
+            The embedding of the cloned voice as a list of floats.
+        """
+        if not filepath:
+            raise ValueError("Filepath must be specified.")
+        url = f"{self._http_url()}/voices/clone/clip"
+        with open(filepath, "rb") as file:
+            files = {"clip": file}
+            files["enhance"] = str(enhance).lower()
+            headers = self.headers.copy()
+            headers.pop("Content-Type", None)
+            response = httpx.post(url, headers=headers, files=files, timeout=self.timeout)
+            if not response.is_success:
+                raise ValueError(f"Failed to clone voice from clip. Error: {response.text}")
+
+        return response.json()["embedding"]
+
+    def create(
+        self,
+        name: str,
+        description: str,
+        embedding: List[float],
+        base_voice_id: Optional[str] = None,
+    ) -> VoiceMetadata:
+        """Create a new voice.
+
+        Args:
+            name: The name of the voice.
+            description: The description of the voice.
+            embedding: The embedding of the voice. This should be generated with :meth:`clone`.
+            base_voice_id: The ID of the base voice. This should be a valid voice ID if specified.
+
+        Returns:
+            A dictionary containing the voice metadata.
+        """
+        response = httpx.post(
+            f"{self._http_url()}/voices",
+            headers=self.headers,
+            json={
+                "name": name,
+                "description": description,
+                "embedding": embedding,
+                "base_voice_id": base_voice_id,
+            },
+            timeout=self.timeout,
+        )
+
+        if not response.is_success:
+            raise ValueError(f"Failed to create voice. Error: {response.text}")
+
+        return response.json()
+
+    def delete(self, id: str) -> bool:
+        """Delete a voice by its ID.
+
+        Args:
+            id: The ID of the voice.
+
+        Raises:
+            ValueError: If the request fails.
+        """
+        response = httpx.delete(
+            f"{self._http_url()}/voices/{id}",
+            headers=self.headers,
+            timeout=self.timeout,
+        )
+
+        if not response.is_success:
+            raise ValueError(f"Failed to delete voice. Error: {response.text}")
+
+    def mix(self, voices: List[Dict[str, Union[str, float]]]) -> List[float]:
+        """Mix multiple voices together.
+
+        Args:
+            voices: A list of dictionaries, each containing either:
+                        - 'id': The ID of an existing voice
+                        - 'embedding': A voice embedding
+                    AND
+                        - 'weight': The weight of the voice in the mix (0.0 to 1.0)
+
+        Returns:
+            The embedding of the mixed voice as a list of floats.
+
+        Raises:
+            ValueError: If the request fails or if the input is invalid.
+        """
+        url = f"{self._http_url()}/voices/mix"
+
+        if not voices or not isinstance(voices, list):
+            raise ValueError("voices must be a non-empty list")
+
+        response = httpx.post(
+            url,
+            headers=self.headers,
+            json={"voices": voices},
+            timeout=self.timeout,
+        )
+
+        if not response.is_success:
+            raise ValueError(f"Failed to mix voices. Error: {response.text}")
+
+        result = response.json()
+        return result["embedding"]

{cartesia-1.0.12.dist-info → cartesia-1.0.14.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 1.0.12
+Version: 1.0.14
 Summary: The official Python library for the Cartesia API.
 Home-page: 
 Author: Cartesia, Inc.
@@ -24,6 +24,8 @@ Requires-Dist: twine; extra == "all"
 Requires-Dist: setuptools; extra == "all"
 Requires-Dist: wheel; extra == "all"
 Requires-Dist: numpy; extra == "all"
+Requires-Dist: isort; extra == "all"
+Requires-Dist: ruff; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.2; extra == "dev"
 Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
@@ -31,17 +33,19 @@ Requires-Dist: twine; extra == "dev"
 Requires-Dist: setuptools; extra == "dev"
 Requires-Dist: wheel; extra == "dev"
 Requires-Dist: numpy; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
 
 
 # Cartesia Python API Library
 
 ![PyPI - Version](https://img.shields.io/pypi/v/cartesia)
-[![Discord](https://badgen.net/badge/black/Cartesia/icon?icon=discord&label)](https://discord.gg/ZVxavqHB9X)
+[![Discord](https://badgen.net/badge/black/Cartesia/icon?icon=discord&label)](https://discord.gg/cartesia)
 
 The official Cartesia Python library which provides convenient access to the Cartesia REST and Websocket API from any Python 3.8+ application.
 
 > [!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/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!
+> 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/cartesia) for any support requests!
 
 - [Cartesia Python API Library](#cartesia-python-api-library)
   - [Documentation](#documentation)
@@ -123,7 +127,7 @@ transcript = "Hello! Welcome to Cartesia"
 # 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
+# You can find the supported `output_format`s at https://docs.cartesia.ai/reference/api-reference/rest/stream-speech-server-sent-events
 output_format = {
     "container": "raw",
     "encoding": "pcm_f32le",
@@ -174,7 +178,7 @@ async def write_stream():
     # 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
+    # You can find the supported `output_format`s at https://docs.cartesia.ai/reference/api-reference/rest/stream-speech-server-sent-events
     output_format = {
         "container": "raw",
         "encoding": "pcm_f32le",
@@ -229,7 +233,7 @@ transcript = "Hello! Welcome to Cartesia"
 # 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
+# You can find the supported `output_format`s at https://docs.cartesia.ai/reference/api-reference/rest/stream-speech-server-sent-events
 output_format = {
     "container": "raw",
     "encoding": "pcm_f32le",
@@ -290,7 +294,7 @@ async def send_transcripts(ctx):
     # 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
+    # You can find the supported `output_format`s at https://docs.cartesia.ai/reference/api-reference/rest/stream-speech-server-sent-events
     output_format = {
         "container": "raw",
         "encoding": "pcm_f32le",
@@ -398,7 +402,7 @@ 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
+# You can find the supported `output_format`s at https://docs.cartesia.ai/reference/api-reference/rest/stream-speech-server-sent-events
 output_format = {
     "container": "raw",
     "encoding": "pcm_f32le",
@@ -488,7 +492,7 @@ 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 https://docs.cartesia.ai/getting-started/available-models
 model_id = "sonic-multilingual"
 
-# You can find the supported `output_format`s at 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/reference/api-reference/rest/stream-speech-server-sent-events
 output_format = {
     "container": "raw",
     "encoding": "pcm_f32le",
@@ -641,7 +645,7 @@ display(audio)
 
 #### 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).
+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/reference/api-reference/rest/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`.
 

cartesia-1.0.14.dist-info/RECORD

@@ -0,0 +1,24 @@
+cartesia/__init__.py,sha256=rS7jIg4iqT0VgnwjzYK25JXxnF5hjZGE_-PGynAqHFo,126
+cartesia/_async_sse.py,sha256=syfGJvQD6JEzqA2thuk9CY91gzWz1FJwJdwaE1dhffQ,3598
+cartesia/_async_websocket.py,sha256=8ZfSLHbaMQS25AEHOboqiAd9ttNN0zxyZ74PiMCR9B0,12756
+cartesia/_constants.py,sha256=lquaYIg7IThdmC1fCklnWC8EM7stbSeVCDwRqCzPq-U,389
+cartesia/_logger.py,sha256=vU7QiGSy_AJuJFmClUocqIJ-Ltku_8C24ZU8L6fLJR0,53
+cartesia/_sse.py,sha256=C4oG17t1G_sI1oTyESPxhlvPA99gCra1C-TyhvS3BZ0,5934
+cartesia/_types.py,sha256=2fTSCwjL9lJ3jsdbs0P9fHsjkhejyrrYt6oqIXGk1y4,4488
+cartesia/_websocket.py,sha256=moHoX4WDslXBwbdi8dJcS2RjGkemH73EjMNO42uYGdg,15300
+cartesia/async_client.py,sha256=y_K_Yuv0weA4k9ZYD0M9bNM3x3frsq07tqkg7R9h0-o,2714
+cartesia/async_tts.py,sha256=OhADdUngrB3XhOirOwX3SmLBFGZakicOUGD61FqGXRo,723
+cartesia/client.py,sha256=OS1ORUSlR8Jg-em1imeTAFfwkC85AQFnw8PYtTdUuC8,2364
+cartesia/resource.py,sha256=wpnB3IPcTdxYSp0vxSkpntp4NSvqvnwUWF-0ZpgWV9o,1585
+cartesia/tts.py,sha256=P-lFTgyNtU4VRdpxAdGfPjIlL4hWp6w3Pc-qf61dzoA,4199
+cartesia/version.py,sha256=tmJFcbWnlgNwXFCrgJHkNSJZmxR67rAjso_lz91m_vc,23
+cartesia/voices.py,sha256=DB4tEiSJp7jfnQM0HoiSFS09ZY2oAFbOwMlKe6pofTs,5606
+cartesia/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cartesia/utils/deprecated.py,sha256=2cXvGtrxhPeUZA5LWy2n_U5OFLDv7SHeFtzqhjSJGyk,1674
+cartesia/utils/retry.py,sha256=O6fyVWpH9Su8c0Fwupl57xMt6JrwJ52txBwP3faUL7k,3339
+cartesia/utils/tts.py,sha256=d32Yqye-dyP1Bgt6djVOkKeb6aETDZ3VqTNMvfIMolU,709
+cartesia-1.0.14.dist-info/LICENSE.md,sha256=PT2YG5wEtEX1TNDn5sXkUXqbn-neyr7cZenTxd40ql4,1074
+cartesia-1.0.14.dist-info/METADATA,sha256=nb0aVbVjwWDefgmQAXUeEX6dFmXfa71ZvBeWwih6MBQ,21590
+cartesia-1.0.14.dist-info/WHEEL,sha256=fS9sRbCBHs7VFcwJLnLXN1MZRR0_TVTxvXKzOnaSFs8,110
+cartesia-1.0.14.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
+cartesia-1.0.14.dist-info/RECORD,,

cartesia-1.0.12.dist-info/RECORD

@@ -1,12 +0,0 @@
-cartesia/__init__.py,sha256=E4w7psbAwx8X6Iri3W8jGeo11gIlhr3mSU33zChipmI,93
-cartesia/_types.py,sha256=pkFJmsO-OWAJNtqxV80-YcR8KWWLhIwLFejzDjBewbw,4428
-cartesia/client.py,sha256=bYUk-P7QlPNNDhQaI5fldkDZAC8vVVUuHrgRHOq_V78,52818
-cartesia/version.py,sha256=bQ8TKIXU3qSGr-K-gVtWDgjDfBlCgBju76OGKtY9tS8,23
-cartesia/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cartesia/utils/deprecated.py,sha256=2cXvGtrxhPeUZA5LWy2n_U5OFLDv7SHeFtzqhjSJGyk,1674
-cartesia/utils/retry.py,sha256=O6fyVWpH9Su8c0Fwupl57xMt6JrwJ52txBwP3faUL7k,3339
-cartesia-1.0.12.dist-info/LICENSE.md,sha256=PT2YG5wEtEX1TNDn5sXkUXqbn-neyr7cZenTxd40ql4,1074
-cartesia-1.0.12.dist-info/METADATA,sha256=3jeDZosoKAHVx9hcLjE9iZsggAvpR_L2iX3hnP_UFd4,21413
-cartesia-1.0.12.dist-info/WHEEL,sha256=fS9sRbCBHs7VFcwJLnLXN1MZRR0_TVTxvXKzOnaSFs8,110
-cartesia-1.0.12.dist-info/top_level.txt,sha256=rTX4HnnCegMxl1FK9czpVC7GAvf3SwDzPG65qP-BS4w,9
-cartesia-1.0.12.dist-info/RECORD,,