cartesia 1.1.0.dev0__py3-none-any.whl

cartesia/tts.py

@@ -0,0 +1,146 @@
+from typing import Iterator, List, Optional
+
+import httpx
+
+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 _construct_tts_request, _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
+
+    def bytes(
+        self,
+        *,
+        model_id: str,
+        transcript: str,
+        output_format: OutputFormat,
+        voice_id: Optional[str] = None,
+        voice_embedding: Optional[List[float]] = None,
+        duration: Optional[int] = None,
+        language: Optional[str] = None,
+        _experimental_voice_controls: Optional[VoiceControls] = None,
+    ) -> bytes:
+        request_body = _construct_tts_request(
+            model_id=model_id,
+            transcript=transcript,
+            output_format=output_format,
+            voice_id=voice_id,
+            voice_embedding=voice_embedding,
+            duration=duration,
+            language=language,
+            _experimental_voice_controls=_experimental_voice_controls,
+        )
+
+        response = httpx.post(
+            f"{self._http_url()}/tts/bytes",
+            headers=self.headers,
+            timeout=self.timeout,
+            json=request_body,
+        )
+
+        if not response.is_success:
+            raise ValueError(f"Failed to generate audio. Error: {response.text}")
+
+        return response.content
+
+    @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/deprecated.py

@@ -0,0 +1,55 @@
+import os
+import warnings
+from typing import Any, Callable, TypeVar
+
+TCallable = TypeVar("TCallable", bound=Callable[..., Any])
+
+# List of statistics of deprecated functions.
+# This should only be used by the test suite to find any deprecated functions
+# that should be removed for this version.
+_TRACK_DEPRECATED_FUNCTION_STATS = os.environ.get("CARTESIA_TEST_DEPRECATED", "").lower() == "true"
+_DEPRECATED_FUNCTION_STATS = []
+
+
+def deprecated(
+    reason=None, vdeprecated=None, vremove=None, replacement=None
+) -> Callable[[TCallable], TCallable]:
+    local_vars = locals()
+
+    def fn(func: TCallable) -> TCallable:
+        if isinstance(func, classmethod):
+            func = func.__func__
+        msg = _get_deprecated_msg(func, reason, vdeprecated, vremove, replacement)
+        warnings.warn(msg, DeprecationWarning)
+        return func
+
+    if _TRACK_DEPRECATED_FUNCTION_STATS:  # pragma: no cover
+        _DEPRECATED_FUNCTION_STATS.append(local_vars)
+
+    return fn
+
+
+def _get_deprecated_msg(wrapped, reason, vdeprecated, vremoved, replacement=None):
+    fmt = "{name} is deprecated"
+    if vdeprecated:
+        fmt += " since v{vdeprecated}"
+    if vremoved:
+        fmt += " and will be removed in v{vremoved}"
+    fmt += "."
+
+    if reason:
+        fmt += " ({reason})"
+    if replacement:
+        fmt += " -- Use {replacement} instead."
+
+    return fmt.format(
+        name=wrapped.__name__,
+        reason=reason or "",
+        vdeprecated=vdeprecated or "",
+        vremoved=vremoved or "",
+        replacement=replacement or "",
+    )
+
+
+# This method is taken from the following source:
+# https://github.com/ad12/meddlr/blob/main/meddlr/utils/deprecated.py

cartesia/utils/retry.py

@@ -0,0 +1,87 @@
+import asyncio
+import time
+from functools import wraps
+from http.client import RemoteDisconnected
+
+from aiohttp.client_exceptions import ServerDisconnectedError
+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/utils/tts.py

@@ -0,0 +1,74 @@
+from typing import List, Optional
+
+from cartesia._types import OutputFormat, 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
+
+
+def _construct_tts_request(
+    *,
+    model_id: str,
+    output_format: OutputFormat,
+    transcript: Optional[str] = None,
+    voice_id: Optional[str] = None,
+    voice_embedding: Optional[List[float]] = None,
+    duration: Optional[int] = None,
+    language: Optional[str] = None,
+    add_timestamps: bool = False,
+    context_id: Optional[str] = None,
+    continue_: bool = False,
+    _experimental_voice_controls: Optional[VoiceControls] = None,
+):
+    tts_request = {
+        "model_id": model_id,
+        "voice": _validate_and_construct_voice(
+            voice_id,
+            voice_embedding=voice_embedding,
+            experimental_voice_controls=_experimental_voice_controls,
+        ),
+        "output_format": {
+            "container": output_format["container"],
+            "encoding": output_format["encoding"],
+            "sample_rate": output_format["sample_rate"],
+        },
+    }
+
+    if language is not None:
+        tts_request["language"] = language
+
+    if transcript is not None:
+        tts_request["transcript"] = transcript
+
+    if duration is not None:
+        tts_request["duration"] = duration
+
+    if add_timestamps:
+        tts_request["add_timestamps"] = add_timestamps
+
+    if context_id is not None:
+        tts_request["context_id"] = context_id
+
+    if continue_:
+        tts_request["continue"] = continue_
+
+    return tts_request

cartesia/version.py

@@ -0,0 +1 @@
+__version__ = "1.1.0-dev0"

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.1.0.dev0.dist-info/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.