cartesia 2.0.3__py3-none-any.whl → 2.0.5__py3-none-any.whl

cartesia/stt/_websocket.py

@@ -0,0 +1,272 @@
+import json
+import typing
+import uuid
+from typing import Any, Dict, Generator, Optional, Union
+
+try:
+    from websockets.sync.client import connect
+    IS_WEBSOCKET_SYNC_AVAILABLE = True
+except ImportError:
+    IS_WEBSOCKET_SYNC_AVAILABLE = False
+
+from cartesia.stt.types import (
+    StreamingTranscriptionResponse,
+    StreamingTranscriptionResponse_Error,
+    StreamingTranscriptionResponse_Transcript,
+)
+
+from ..core.pydantic_utilities import parse_obj_as
+
+
+class SttWebsocket:
+    """This class contains methods to transcribe audio using WebSocket. Ideal for real-time speech transcription.
+
+    Usage:
+        >>> ws = client.stt.websocket()
+        >>> for audio_chunk in audio_chunks:
+        ...     ws.send(audio_chunk)
+        >>> ws.send("finalize")  # Flush remaining audio
+        >>> ws.send("done")      # Close session
+        >>> for transcription in ws.receive():
+        ...     print(transcription["text"])
+    """
+
+    def __init__(
+        self,
+        ws_url: str,
+        api_key: str,
+        cartesia_version: str,
+    ):
+        self.ws_url = ws_url
+        self.api_key = api_key
+        self.cartesia_version = cartesia_version
+        self.websocket: Optional[Any] = None
+        self._is_listening = False
+        # Store default connection parameters for auto-connect with proper typing
+        self._default_model: str = "ink-whisper"
+        self._default_language: Optional[str] = "en"
+        self._default_encoding: Optional[str] = "pcm_s16le"
+        self._default_sample_rate: int = 16000
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception as e:
+            raise RuntimeError("Failed to close WebSocket: ", e)
+
+    def connect(
+        self,
+        *,
+        model: str = "ink-whisper",
+        language: Optional[str] = "en",
+        encoding: Optional[str] = "pcm_s16le",
+        sample_rate: int = 16000,
+    ):
+        """Connect to the STT WebSocket with the specified parameters.
+
+        Args:
+            model: ID of the model to use for transcription
+            language: The language of the input audio in ISO-639-1 format
+            encoding: The encoding format of the audio data
+            sample_rate: The sample rate of the audio in Hz
+
+        Raises:
+            RuntimeError: If the connection to the WebSocket fails.
+        """
+        # Store parameters for future auto-connects
+        self._default_model = model
+        self._default_language = language
+        self._default_encoding = encoding
+        self._default_sample_rate = sample_rate
+        
+        if not IS_WEBSOCKET_SYNC_AVAILABLE:
+            raise ImportError(
+                "The synchronous WebSocket client is not available. Please ensure that you have 'websockets>=12.0' or compatible version installed."
+            )
+        if self.websocket is None or self._is_websocket_closed():
+            route = "stt/websocket"
+            params = {
+                "model": model,
+                "api_key": self.api_key,
+                "cartesia_version": self.cartesia_version,
+            }
+            if language is not None:
+                params["language"] = language
+            if encoding is not None:
+                params["encoding"] = encoding
+            if sample_rate is not None:
+                params["sample_rate"] = str(sample_rate)
+
+            query_string = "&".join([f"{k}={v}" for k, v in params.items()])
+            url = f"{self.ws_url}/{route}?{query_string}"
+
+            try:
+                self.websocket = connect(url)
+            except Exception as e:
+                status_code = None
+                error_message = str(e)
+                
+                if hasattr(e, 'status') and e.status is not None:
+                    status_code = e.status
+                
+                    if status_code == 402:
+                        error_message = "Payment required. Your API key may have insufficient credits or permissions."
+                    elif status_code == 401:
+                        error_message = "Unauthorized. Please check your API key."
+                    elif status_code == 403:
+                        error_message = "Forbidden. You don't have permission to access this resource."
+                    elif status_code == 404:
+                        error_message = "Not found. The requested resource doesn't exist."
+                    
+                    raise RuntimeError(f"Failed to connect to WebSocket.\nStatus: {status_code}. Error message: {error_message}")
+                else:
+                    raise RuntimeError(f"Failed to connect to WebSocket. {e}")
+
+    def _is_websocket_closed(self):
+        return self.websocket is None or (hasattr(self.websocket, 'socket') and self.websocket.socket.fileno() == -1)
+
+    def close(self):
+        """This method closes the WebSocket connection. Highly recommended to call this method when done using the WebSocket."""
+        if self.websocket and not self._is_websocket_closed():
+            self.websocket.close()
+
+    def send(self, data: Union[bytes, str]):
+        """Send audio data or control commands to the WebSocket.
+
+        Args:
+            data: Binary audio data or text command ("finalize" or "done")
+        """
+        # Auto-connect if not connected, like TTS does
+        if self.websocket is None or self._is_websocket_closed():
+            self.connect(
+                model=self._default_model,
+                language=self._default_language,
+                encoding=self._default_encoding,
+                sample_rate=self._default_sample_rate,
+            )
+        
+        assert self.websocket is not None, "WebSocket should be connected after connect() call"
+        
+        if isinstance(data, bytes):
+            self.websocket.send(data)
+        elif isinstance(data, str):
+            self.websocket.send(data)
+        else:
+            raise TypeError("Data must be bytes (audio) or str (command)")
+
+    def receive(self) -> Generator[Dict[str, Any], None, None]:
+        """Receive transcription results from the WebSocket.
+
+        Yields:
+            Dictionary containing transcription results, flush_done, done, or error messages
+        """
+        # Auto-connect if not connected, like TTS does
+        if self.websocket is None or self._is_websocket_closed():
+            self.connect(
+                model=self._default_model,
+                language=self._default_language,
+                encoding=self._default_encoding,
+                sample_rate=self._default_sample_rate,
+            )
+
+        assert self.websocket is not None, "WebSocket should be connected after connect() call"
+
+        try:
+            while True:
+                try:
+                    message = self.websocket.recv()
+                    if isinstance(message, str):
+                        raw_data = json.loads(message)
+                        
+                        # Handle error responses
+                        if raw_data.get("type") == "error":
+                            raise RuntimeError(f"Error transcribing audio: {raw_data.get('message', 'Unknown error')}")
+                        
+                        # Handle transcript responses with flexible parsing
+                        if raw_data.get("type") == "transcript":
+                            # Provide defaults for missing required fields
+                            result = {
+                                "type": raw_data["type"],
+                                "request_id": raw_data.get("request_id", ""),
+                                "text": raw_data.get("text", ""),  # Default to empty string if missing
+                                "is_final": raw_data.get("is_final", False),  # Default to False if missing
+                            }
+                            
+                            # Add optional fields if present
+                            if "duration" in raw_data:
+                                result["duration"] = raw_data["duration"]
+                            if "language" in raw_data:
+                                result["language"] = raw_data["language"]
+                            
+                            yield result
+                        
+                        # Handle flush_done acknowledgment
+                        elif raw_data.get("type") == "flush_done":
+                            result = {
+                                "type": raw_data["type"],
+                                "request_id": raw_data.get("request_id", ""),
+                            }
+                            yield result
+                        
+                        # Handle done acknowledgment - session complete
+                        elif raw_data.get("type") == "done":
+                            result = {
+                                "type": raw_data["type"],
+                                "request_id": raw_data.get("request_id", ""),
+                            }
+                            yield result
+                            # Session is complete, break out of loop
+                            break
+                
+                except Exception as inner_e:
+                    self.close()
+                    raise RuntimeError(f"Error receiving transcription: {inner_e}")
+                        
+        except Exception as e:
+            self.close()
+            raise RuntimeError(f"Failed to receive transcription. {e}")
+
+    def transcribe(
+        self,
+        audio_chunks: typing.Iterator[bytes],
+        *,
+        model: str = "ink-whisper",
+        language: Optional[str] = "en",
+        encoding: Optional[str] = "pcm_s16le",
+        sample_rate: int = 16000,
+    ) -> Generator[Dict[str, Any], None, None]:
+        """Transcribe audio chunks using the WebSocket.
+
+        Args:
+            audio_chunks: Iterator of audio chunks as bytes
+            model: ID of the model to use for transcription
+            language: The language of the input audio in ISO-639-1 format
+            encoding: The encoding format of the audio data
+            sample_rate: The sample rate of the audio in Hz
+
+        Yields:
+            Dictionary containing transcription results, flush_done, done, or error messages
+        """
+        self.connect(
+            model=model,
+            language=language,
+            encoding=encoding,
+            sample_rate=sample_rate,
+        )
+
+        try:
+            # Send all audio chunks
+            for chunk in audio_chunks:
+                self.send(chunk)
+            
+            # Send finalize command to flush remaining audio
+            self.send("finalize")
+            
+            # Send done command to close session cleanly
+            self.send("done")
+            
+            # Receive all responses until done
+            yield from self.receive()
+            
+        finally:
+            self.close() 

cartesia/stt/requests/__init__.py

@@ -0,0 +1,27 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from .done_message import DoneMessageParams
+from .error_message import ErrorMessageParams
+from .flush_done_message import FlushDoneMessageParams
+from .streaming_transcription_response import (
+    StreamingTranscriptionResponseParams,
+    StreamingTranscriptionResponse_DoneParams,
+    StreamingTranscriptionResponse_ErrorParams,
+    StreamingTranscriptionResponse_FlushDoneParams,
+    StreamingTranscriptionResponse_TranscriptParams,
+)
+from .transcript_message import TranscriptMessageParams
+from .transcription_response import TranscriptionResponseParams
+
+__all__ = [
+    "DoneMessageParams",
+    "ErrorMessageParams",
+    "FlushDoneMessageParams",
+    "StreamingTranscriptionResponseParams",
+    "StreamingTranscriptionResponse_DoneParams",
+    "StreamingTranscriptionResponse_ErrorParams",
+    "StreamingTranscriptionResponse_FlushDoneParams",
+    "StreamingTranscriptionResponse_TranscriptParams",
+    "TranscriptMessageParams",
+    "TranscriptionResponseParams",
+]

cartesia/stt/requests/done_message.py

@@ -0,0 +1,14 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+
+
+class DoneMessageParams(typing_extensions.TypedDict):
+    """
+    Acknowledgment message sent in response to a `done` command, indicating that the session is complete and the WebSocket will close.
+    """
+
+    request_id: str
+    """
+    Unique identifier for this transcription session.
+    """

cartesia/stt/requests/error_message.py

@@ -0,0 +1,16 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+import typing_extensions
+
+
+class ErrorMessageParams(typing_extensions.TypedDict):
+    request_id: typing_extensions.NotRequired[str]
+    """
+    The request ID associated with the error, if applicable.
+    """
+
+    message: str
+    """
+    Human-readable error message describing what went wrong.
+    """

cartesia/stt/requests/flush_done_message.py

@@ -0,0 +1,14 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+
+
+class FlushDoneMessageParams(typing_extensions.TypedDict):
+    """
+    Acknowledgment message sent in response to a `finalize` command, indicating that all buffered audio has been flushed and processed.
+    """
+
+    request_id: str
+    """
+    Unique identifier for this transcription session.
+    """

cartesia/stt/requests/streaming_transcription_response.py

@@ -0,0 +1,39 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from __future__ import annotations
+import typing_extensions
+import typing
+import typing_extensions
+
+
+class StreamingTranscriptionResponse_TranscriptParams(typing_extensions.TypedDict):
+    type: typing.Literal["transcript"]
+    request_id: str
+    text: str
+    is_final: bool
+    duration: typing_extensions.NotRequired[float]
+    language: typing_extensions.NotRequired[str]
+
+
+class StreamingTranscriptionResponse_FlushDoneParams(typing_extensions.TypedDict):
+    type: typing.Literal["flush_done"]
+    request_id: str
+
+
+class StreamingTranscriptionResponse_DoneParams(typing_extensions.TypedDict):
+    type: typing.Literal["done"]
+    request_id: str
+
+
+class StreamingTranscriptionResponse_ErrorParams(typing_extensions.TypedDict):
+    type: typing.Literal["error"]
+    request_id: typing_extensions.NotRequired[str]
+    message: str
+
+
+StreamingTranscriptionResponseParams = typing.Union[
+    StreamingTranscriptionResponse_TranscriptParams,
+    StreamingTranscriptionResponse_FlushDoneParams,
+    StreamingTranscriptionResponse_DoneParams,
+    StreamingTranscriptionResponse_ErrorParams,
+]

cartesia/stt/requests/transcript_message.py

@@ -0,0 +1,33 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+import typing_extensions
+
+
+class TranscriptMessageParams(typing_extensions.TypedDict):
+    request_id: str
+    """
+    Unique identifier for this transcription session.
+    """
+
+    text: str
+    """
+    The transcribed text. May be partial or final depending on is_final.
+    
+    **Note**: Text may be empty in initial responses while the system accumulates sufficient audio for transcription. This is normal behavior - wait for responses with non-empty text or monitor is_final for completion status.
+    """
+
+    is_final: bool
+    """
+    Whether this is a final transcription result or an interim result.
+    """
+
+    duration: typing_extensions.NotRequired[float]
+    """
+    The duration of the audio transcribed so far, in seconds.
+    """
+
+    language: typing_extensions.NotRequired[str]
+    """
+    The detected or specified language of the input audio.
+    """

cartesia/stt/requests/transcription_response.py

@@ -0,0 +1,21 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+import typing_extensions
+
+
+class TranscriptionResponseParams(typing_extensions.TypedDict):
+    text: str
+    """
+    The transcribed text.
+    """
+
+    language: typing_extensions.NotRequired[str]
+    """
+    The detected or specified language of the input audio.
+    """
+
+    duration: typing_extensions.NotRequired[float]
+    """
+    The duration of the input audio in seconds.
+    """

cartesia/stt/socket_client.py

@@ -0,0 +1,195 @@
+import typing
+from typing import Any, Dict, Generator, Optional, Union
+
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ._async_websocket import AsyncSttWebsocket
+from ._websocket import SttWebsocket
+
+
+class SttClientWithWebsocket:
+    """
+    Extension of STT functionality that supports a synchronous WebSocket STT connection.
+    """
+
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    def _ws_url(self):
+        base_url = self._client_wrapper.get_base_url()
+        if base_url.startswith("ws://") or base_url.startswith("wss://"):
+            return base_url
+        else:
+            prefix = "ws" if "localhost" in base_url else "wss"
+            base_url_without_protocol = base_url.split("://")[-1]
+            return f"{prefix}://{base_url_without_protocol}"
+
+    def websocket(self, *, 
+                  model: str = "ink-whisper",
+                  language: Optional[str] = "en", 
+                  encoding: Optional[str] = "pcm_s16le",
+                  sample_rate: int = 16000):
+        """Create a WebSocket connection for real-time speech transcription.
+
+        Args:
+            model: ID of the model to use for transcription
+            language: The language of the input audio in ISO-639-1 format
+            encoding: The encoding format of the audio data
+            sample_rate: The sample rate of the audio in Hz
+
+        Returns:
+            SttWebsocket: A connected WebSocket client for STT operations.
+        """
+        client_headers = self._client_wrapper.get_headers()
+        ws = SttWebsocket(
+            ws_url=self._ws_url(),
+            cartesia_version=client_headers["Cartesia-Version"],
+            api_key=client_headers["X-API-Key"],
+        )
+        # Auto-connect like TTS does for consistency
+        ws.connect(
+            model=model,
+            language=language,
+            encoding=encoding,
+            sample_rate=sample_rate,
+        )
+        return ws
+
+    def transcribe(
+        self,
+        audio_chunks: typing.Iterator[bytes],
+        *,
+        model: str = "ink-whisper",
+        language: Optional[str] = "en",
+        encoding: Optional[str] = "pcm_s16le",
+        sample_rate: int = 16000,
+    ) -> Generator[Dict[str, Any], None, None]:
+        """Transcribe audio chunks using WebSocket.
+
+        Args:
+            audio_chunks: Iterator of audio chunks as bytes
+            model: ID of the model to use for transcription
+            language: The language of the input audio in ISO-639-1 format
+            encoding: The encoding format of the audio data
+            sample_rate: The sample rate of the audio in Hz
+
+        Yields:
+            Dictionary containing transcription results, flush_done, done, or error messages
+
+        Example:
+            >>> client = Cartesia(api_key="your-api-key")
+            >>> ws_client = client.stt.websocket()
+            >>> for result in ws_client.transcribe(audio_chunks):
+            ...     print(result["text"])
+        """
+        ws = self.websocket(
+            model=model,
+            language=language,
+            encoding=encoding,
+            sample_rate=sample_rate,
+        )
+        try:
+            yield from ws.transcribe(
+                audio_chunks,
+                model=model,
+                language=language,
+                encoding=encoding,
+                sample_rate=sample_rate,
+            )
+        finally:
+            ws.close()
+
+
+class AsyncSttClientWithWebsocket:
+    """
+    Extension of STT functionality that supports an asynchronous WebSocket STT connection.
+    """
+
+    def __init__(self, *, client_wrapper: AsyncClientWrapper, get_session):
+        self._client_wrapper = client_wrapper
+        self._get_session = get_session
+
+    def _ws_url(self) -> str:
+        base_url = self._client_wrapper.get_base_url()
+        if base_url.startswith("ws://") or base_url.startswith("wss://"):
+            return base_url
+        else:
+            prefix = "ws" if "localhost" in base_url else "wss"
+            base_url_without_protocol = base_url.split("://")[-1]
+            return f"{prefix}://{base_url_without_protocol}"
+
+    async def websocket(self, *,
+                        model: str = "ink-whisper",
+                        language: Optional[str] = "en",
+                        encoding: Optional[str] = "pcm_s16le", 
+                        sample_rate: int = 16000):
+        """Create an async WebSocket connection for real-time speech transcription.
+
+        Args:
+            model: ID of the model to use for transcription
+            language: The language of the input audio in ISO-639-1 format
+            encoding: The encoding format of the audio data
+            sample_rate: The sample rate of the audio in Hz
+
+        Returns:
+            AsyncSttWebsocket: A connected async WebSocket client for STT operations.
+        """
+        client_headers = self._client_wrapper.get_headers()
+        ws = AsyncSttWebsocket(
+            ws_url=self._ws_url(),
+            cartesia_version=client_headers["Cartesia-Version"],
+            api_key=client_headers["X-API-Key"],
+            get_session=self._get_session,
+        )
+        # Auto-connect like TTS does for consistency
+        await ws.connect(
+            model=model,
+            language=language,
+            encoding=encoding,
+            sample_rate=sample_rate,
+        )
+        return ws
+
+    async def transcribe(
+        self,
+        audio_chunks: typing.AsyncIterator[bytes],
+        *,
+        model: str = "ink-whisper",
+        language: Optional[str] = "en",
+        encoding: Optional[str] = "pcm_s16le",
+        sample_rate: int = 16000,
+    ) -> typing.AsyncGenerator[Dict[str, Any], None]:
+        """Transcribe audio chunks using async WebSocket.
+
+        Args:
+            audio_chunks: Async iterator of audio chunks as bytes
+            model: ID of the model to use for transcription
+            language: The language of the input audio in ISO-639-1 format
+            encoding: The encoding format of the audio data
+            sample_rate: The sample rate of the audio in Hz
+
+        Yields:
+            Dictionary containing transcription results, flush_done, done, or error messages
+
+        Example:
+            >>> client = AsyncCartesia(api_key="your-api-key")
+            >>> ws_client = await client.stt.websocket()
+            >>> async for result in ws_client.transcribe(audio_chunks):
+            ...     print(result["text"])
+        """
+        ws = await self.websocket(
+            model=model,
+            language=language,
+            encoding=encoding,
+            sample_rate=sample_rate,
+        )
+        try:
+            async for result in ws.transcribe(
+                audio_chunks,
+                model=model,
+                language=language,
+                encoding=encoding,
+                sample_rate=sample_rate,
+            ):
+                yield result
+        finally:
+            await ws.close() 

cartesia/stt/types/__init__.py

@@ -0,0 +1,29 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from .done_message import DoneMessage
+from .error_message import ErrorMessage
+from .flush_done_message import FlushDoneMessage
+from .streaming_transcription_response import (
+    StreamingTranscriptionResponse,
+    StreamingTranscriptionResponse_Done,
+    StreamingTranscriptionResponse_Error,
+    StreamingTranscriptionResponse_FlushDone,
+    StreamingTranscriptionResponse_Transcript,
+)
+from .stt_encoding import SttEncoding
+from .transcript_message import TranscriptMessage
+from .transcription_response import TranscriptionResponse
+
+__all__ = [
+    "DoneMessage",
+    "ErrorMessage",
+    "FlushDoneMessage",
+    "StreamingTranscriptionResponse",
+    "StreamingTranscriptionResponse_Done",
+    "StreamingTranscriptionResponse_Error",
+    "StreamingTranscriptionResponse_FlushDone",
+    "StreamingTranscriptionResponse_Transcript",
+    "SttEncoding",
+    "TranscriptMessage",
+    "TranscriptionResponse",
+]