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

cartesia/stt/types/done_message.py

@@ -0,0 +1,26 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from ...core.pydantic_utilities import UniversalBaseModel
+import pydantic
+from ...core.pydantic_utilities import IS_PYDANTIC_V2
+import typing
+
+
+class DoneMessage(UniversalBaseModel):
+    """
+    Acknowledgment message sent in response to a `done` command, indicating that the session is complete and the WebSocket will close.
+    """
+
+    request_id: str = pydantic.Field()
+    """
+    Unique identifier for this transcription session.
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

cartesia/stt/types/error_message.py

@@ -0,0 +1,27 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from ...core.pydantic_utilities import UniversalBaseModel
+import typing
+import pydantic
+from ...core.pydantic_utilities import IS_PYDANTIC_V2
+
+
+class ErrorMessage(UniversalBaseModel):
+    request_id: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    The request ID associated with the error, if applicable.
+    """
+
+    message: str = pydantic.Field()
+    """
+    Human-readable error message describing what went wrong.
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

cartesia/stt/types/flush_done_message.py

@@ -0,0 +1,26 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from ...core.pydantic_utilities import UniversalBaseModel
+import pydantic
+from ...core.pydantic_utilities import IS_PYDANTIC_V2
+import typing
+
+
+class FlushDoneMessage(UniversalBaseModel):
+    """
+    Acknowledgment message sent in response to a `finalize` command, indicating that all buffered audio has been flushed and processed.
+    """
+
+    request_id: str = pydantic.Field()
+    """
+    Unique identifier for this transcription session.
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

cartesia/stt/types/streaming_transcription_response.py

@@ -0,0 +1,92 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from __future__ import annotations
+from ...core.pydantic_utilities import UniversalBaseModel
+import typing
+from ...core.pydantic_utilities import IS_PYDANTIC_V2
+import pydantic
+
+
+class StreamingTranscriptionResponse_Transcript(UniversalBaseModel):
+    """
+    The server sends transcription results, control messages, or error messages. Each message has a `type` field to distinguish between different message types.
+    """
+
+    type: typing.Literal["transcript"] = "transcript"
+    request_id: str
+    text: str
+    is_final: bool
+    duration: typing.Optional[float] = None
+    language: typing.Optional[str] = None
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow
+
+
+class StreamingTranscriptionResponse_FlushDone(UniversalBaseModel):
+    """
+    The server sends transcription results, control messages, or error messages. Each message has a `type` field to distinguish between different message types.
+    """
+
+    type: typing.Literal["flush_done"] = "flush_done"
+    request_id: str
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow
+
+
+class StreamingTranscriptionResponse_Done(UniversalBaseModel):
+    """
+    The server sends transcription results, control messages, or error messages. Each message has a `type` field to distinguish between different message types.
+    """
+
+    type: typing.Literal["done"] = "done"
+    request_id: str
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow
+
+
+class StreamingTranscriptionResponse_Error(UniversalBaseModel):
+    """
+    The server sends transcription results, control messages, or error messages. Each message has a `type` field to distinguish between different message types.
+    """
+
+    type: typing.Literal["error"] = "error"
+    request_id: typing.Optional[str] = None
+    message: str
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow
+
+
+StreamingTranscriptionResponse = typing.Union[
+    StreamingTranscriptionResponse_Transcript,
+    StreamingTranscriptionResponse_FlushDone,
+    StreamingTranscriptionResponse_Done,
+    StreamingTranscriptionResponse_Error,
+]

cartesia/stt/types/stt_encoding.py

@@ -0,0 +1,5 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+SttEncoding = typing.Union[typing.Literal["pcm_s16le"], typing.Any]

cartesia/stt/types/transcript_message.py

@@ -0,0 +1,44 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from ...core.pydantic_utilities import UniversalBaseModel
+import pydantic
+import typing
+from ...core.pydantic_utilities import IS_PYDANTIC_V2
+
+
+class TranscriptMessage(UniversalBaseModel):
+    request_id: str = pydantic.Field()
+    """
+    Unique identifier for this transcription session.
+    """
+
+    text: str = pydantic.Field()
+    """
+    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 = pydantic.Field()
+    """
+    Whether this is a final transcription result or an interim result.
+    """
+
+    duration: typing.Optional[float] = pydantic.Field(default=None)
+    """
+    The duration of the audio transcribed so far, in seconds.
+    """
+
+    language: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    The detected or specified language of the input audio.
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

cartesia/stt/types/transcription_response.py

@@ -0,0 +1,32 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from ...core.pydantic_utilities import UniversalBaseModel
+import pydantic
+import typing
+from ...core.pydantic_utilities import IS_PYDANTIC_V2
+
+
+class TranscriptionResponse(UniversalBaseModel):
+    text: str = pydantic.Field()
+    """
+    The transcribed text.
+    """
+
+    language: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    The detected or specified language of the input audio.
+    """
+
+    duration: typing.Optional[float] = pydantic.Field(default=None)
+    """
+    The duration of the input audio in seconds.
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

{cartesia-2.0.4.dist-info → cartesia-2.0.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cartesia
-Version: 2.0.4
+Version: 2.0.5
 Summary: 
 Requires-Python: >=3.8,<4.0
 Classifier: Intended Audience :: Developers
@@ -213,6 +213,161 @@ p.terminate()
 ws.close()  # Close the websocket connection
 ```
 
+## Speech-to-Text (STT) with Websockets
+
+```python
+from cartesia import Cartesia
+import os
+
+client = Cartesia(api_key=os.getenv("CARTESIA_API_KEY"))
+
+# Load your audio file as bytes
+with open("path/to/audio.wav", "rb") as f:
+    audio_data = f.read()
+
+# Convert to audio chunks (20ms chunks used here for a streaming example)
+# This chunk size is calculated for 16kHz, 16-bit audio: 16000 * 0.02 * 2 = 640 bytes
+chunk_size = 640
+audio_chunks = [audio_data[i:i+chunk_size] for i in range(0, len(audio_data), chunk_size)]
+
+# Create websocket connection
+ws = client.stt.websocket(
+    model="ink-whisper",
+    language="en",           # Must match the language of your audio
+    encoding="pcm_s16le",    # Must match your audio's encoding format
+    sample_rate=16000,       # Must match your audio's sample rate
+)
+
+# Send audio chunks (streaming approach)
+for chunk in audio_chunks:
+    ws.send(chunk)
+
+# Finalize and close
+ws.send("finalize")
+ws.send("done")
+
+# Receive transcription results
+for result in ws.receive():
+    if result['type'] == 'transcript':
+        print(f"Transcription: {result['text']}")
+        if result['is_final']:
+            print("Final result received")
+    elif result['type'] == 'done':
+        break
+
+ws.close()
+```
+
+### Async Streaming Speech-to-Text (STT) with Websockets
+
+For real-time streaming applications, here's a more practical async example that demonstrates concurrent audio processing and result handling:
+
+```python
+import asyncio
+import os
+from cartesia import AsyncCartesia
+
+async def streaming_stt_example():
+    """
+    Advanced async STT example for real-time streaming applications.
+    This example simulates streaming audio processing with proper error handling.
+    """
+    client = AsyncCartesia(api_key=os.getenv("CARTESIA_API_KEY"))
+    
+    try:
+        # Create websocket connection
+        ws = await client.stt.websocket(
+            model="ink-whisper",
+            language="en",           # Must match the language of your audio
+            encoding="pcm_s16le",    # Must match your audio's encoding format
+            sample_rate=16000,       # Must match your audio's sample rate
+        )
+        
+        # Simulate streaming audio data (replace with your audio source)
+        async def audio_stream():
+            """Simulate real-time audio streaming - replace with actual audio capture"""
+            # Load audio file for simulation
+            with open("path/to/audio.wav", "rb") as f:
+                audio_data = f.read()
+            
+            # Stream in 100ms chunks (realistic for real-time processing)
+            chunk_size = int(16000 * 0.1 * 2)  # 100ms at 16kHz, 16-bit
+            
+            for i in range(0, len(audio_data), chunk_size):
+                chunk = audio_data[i:i + chunk_size]
+                if chunk:
+                    yield chunk
+                    # Simulate real-time streaming delay
+                    await asyncio.sleep(0.1)
+        
+        # Send audio and receive results concurrently
+        async def send_audio():
+            """Send audio chunks to the STT websocket"""
+            try:
+                async for chunk in audio_stream():
+                    await ws.send(chunk)
+                    print(f"Sent audio chunk of {len(chunk)} bytes")
+                    # Small delay to simulate realtime applications
+                    await asyncio.sleep(0.02)
+                
+                # Signal end of audio stream
+                await ws.send("finalize")
+                await ws.send("done")
+                print("Audio streaming completed")
+                
+            except Exception as e:
+                print(f"Error sending audio: {e}")
+        
+        async def receive_transcripts():
+            """Receive and process transcription results"""
+            full_transcript = ""
+            
+            try:
+                async for result in ws.receive():
+                    if result['type'] == 'transcript':
+                        text = result['text']
+                        is_final = result['is_final']
+                        
+                        if is_final:
+                            # Final result - this text won't change
+                            full_transcript += text + " "
+                            print(f"FINAL: {text}")
+                        else:
+                            # Partial result - may change as more audio is processed
+                            print(f"PARTIAL: {text}")
+                            
+                    elif result['type'] == 'done':
+                        print("Transcription completed")
+                        break
+                        
+            except Exception as e:
+                print(f"Error receiving transcripts: {e}")
+            
+            return full_transcript.strip()
+        
+        print("Starting streaming STT...")
+        
+        # Use asyncio.gather to run audio sending and transcript receiving concurrently
+        _, final_transcript = await asyncio.gather(
+            send_audio(),
+            receive_transcripts()
+        )
+        
+        print(f"\nComplete transcript: {final_transcript}")
+        
+        # Clean up
+        await ws.close()
+        
+    except Exception as e:
+        print(f"STT streaming error: {e}")
+    finally:
+        await client.close()
+
+# Run the example
+if __name__ == "__main__":
+    asyncio.run(streaming_stt_example())
+```
+
 ## Voices
 
 List all available Voices with `client.voices.list`, which returns an iterable that automatically handles pagination:
@@ -358,7 +513,6 @@ new_voice = client.voices.create(
     language="en"
 )
 ```
-
 ### Custom Client
 
 You can override the `httpx` client to customize it for your use-case. Some common use-cases include support for proxies
@@ -412,3 +566,6 @@ $ git commit --amend -m "manually regenerate from docs" # optional
 
 From https://github.com/cartesia-ai/docs click `Actions` then `Release Python SDK`. (Requires permissions.)
 
+
+
+

{cartesia-2.0.4.dist-info → cartesia-2.0.5.dist-info}/RECORD

@@ -1,4 +1,4 @@
-cartesia/__init__.py,sha256=p9ilqR-oE6N6pPQbiKUbnfEdDy00ihjNTtg7ES7EHg0,8448
+cartesia/__init__.py,sha256=aJVi_CoPyZ9i3PV0X8znskO0Jir6bfIAPVjKGvQHQmY,9957
 cartesia/api_status/__init__.py,sha256=_dHNLdknrBjxHtU2PvLumttJM-JTQhJQqhhAQkLqt_U,168
 cartesia/api_status/client.py,sha256=GJ9Dq8iCn3hn8vCIqc6k1fCGEhSz0T0kaPGcdFnbMDY,3146
 cartesia/api_status/requests/__init__.py,sha256=ilEMzEy1JEw484CuL92bX5lHGOznc62pjiDMgiZ0tKM,130
@@ -15,11 +15,11 @@ cartesia/auth/types/__init__.py,sha256=iZrkHrlWs8e9KkR27f2IG-B72HC_N05A7Lcyt_EU9
 cartesia/auth/types/token_grant.py,sha256=sdEqlqS95XSy_Xdp4TEeRSC1hQp4nbPv1HHZFxbU0So,666
 cartesia/auth/types/token_request.py,sha256=2cx2OBXTEjrbuVMOpBzkIm9-DZD2mGiWE6Ui3kumxGI,893
 cartesia/auth/types/token_response.py,sha256=_GcvfQdjwgNu1ODj8EuTkaMsez508a6xuOo8HOVNOJQ,626
-cartesia/base_client.py,sha256=YH0l0UUzanAa9mDdJU6BFQ9XKELiaPTm9NsJpVQ4evA,6539
-cartesia/client.py,sha256=sPAYQLt9W2E_2F17ooocvvJImuNyLrL8xUypgf6dZeI,6238
+cartesia/base_client.py,sha256=igAZOMDXz2Nv58oXHa7I9UfgxVN48drqhEmfsCCQlg8,6701
+cartesia/client.py,sha256=LoJjlJW2kJA-hyDt-Wu7QuKQsiTiLQfLYZjsjtewPJM,6537
 cartesia/core/__init__.py,sha256=-t9txgeQZL_1FDw_08GEoj4ft1Cn9Dti6X0Drsadlr0,1519
 cartesia/core/api_error.py,sha256=RE8LELok2QCjABadECTvtDp7qejA1VmINCh6TbqPwSE,426
-cartesia/core/client_wrapper.py,sha256=gIGKiDzwmBL6e1kFzl8OT46mrZICICC7g76ietRUp54,1854
+cartesia/core/client_wrapper.py,sha256=hvkz6qsmuAuZEKl86cWmFoKGN9WEIGEitiTe0ge6ODQ,1854
 cartesia/core/datetime_utils.py,sha256=nBys2IsYrhPdszxGKCNRPSOCwa-5DWOHG95FB8G9PKo,1047
 cartesia/core/file.py,sha256=d4NNbX8XvXP32z8KpK2Xovv33nFfruIrpz0QWxlgpZk,2663
 cartesia/core/http_client.py,sha256=KL5RGa0y4n8nX0-07WRg4ZQUTq30sc-XJbWcP5vjBDg,19552
@@ -51,6 +51,25 @@ cartesia/environment.py,sha256=Qnp91BGLic7hXmKsiYub2m3nPfvDWm59aB1wWta1J6A,160
 cartesia/infill/__init__.py,sha256=FTtvy8EDg9nNNg9WCatVgKTRYV8-_v1roeGPAKoa_pw,65
 cartesia/infill/client.py,sha256=PWE5Ak-wsaBM_8g52oDl9PYx76PkW6f900mnxvZf4Bk,12571
 cartesia/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cartesia/stt/__init__.py,sha256=tfwo6MBzRGeKhhXKfSKQPhHjSeTr0jTib9hv7a9OJyg,1601
+cartesia/stt/_async_websocket.py,sha256=YMOHdRmGLD2jsQzqK8UlcVkS-hG0PsXhBi17t6tccLo,11673
+cartesia/stt/_websocket.py,sha256=d0Nmsu_VgVyR6OBgrx5KcvyjNXycDB7rruDRF2WbNc8,10864
+cartesia/stt/requests/__init__.py,sha256=xufSQ2wiPAPP6J45-niiaRKGHkdMAZcUCApVcu8CAkQ,1036
+cartesia/stt/requests/done_message.py,sha256=7kCw8FrTZ6C5MS1xTkCOonYPcaqttbzG6TRvMj_-Z8I,388
+cartesia/stt/requests/error_message.py,sha256=AbVs03q-Rdp2AFmaJqj-b3RshYqhIQeSiQO3zOkFdiA,395
+cartesia/stt/requests/flush_done_message.py,sha256=zCMsHdoXXsBS8jz-ZAIRkEyAsbgqYCI5jPdBHEBFHLY,394
+cartesia/stt/requests/streaming_transcription_response.py,sha256=torouKJLwjB6SJNGYQwMsZG9q1nQEoRInTicpNFzzRM,1159
+cartesia/stt/requests/transcript_message.py,sha256=H7vx-c2BmdiekPtiPXX3mvhgzxj0EeGEC6oeAQZ_YQU,964
+cartesia/stt/requests/transcription_response.py,sha256=jV-FMzKp_cfvhQq3VmBvxY3-mi8zsWkdH6RwbBvPIUM,478
+cartesia/stt/socket_client.py,sha256=Ly5lBPUbnYsiOjiidzSVFGEIu_ojuw9gqITIrP9qGdQ,7006
+cartesia/stt/types/__init__.py,sha256=yVtbBSSFiTIBc0bEEffZef-oZsYPGJ3VCZd5m_N_uFI,973
+cartesia/stt/types/done_message.py,sha256=F3Upci6Lm3Wcd_Ga4Uxxw9WO7XB3y54hrvR1cFqPxlo,803
+cartesia/stt/types/error_message.py,sha256=7HmoN7pBymPvJSB9JHwvMp3iXP-4xxd-ATpr-U68ocA,802
+cartesia/stt/types/flush_done_message.py,sha256=uaDC6IBtZQ9ahPS575ezZiH6neR5JDnaI9KOemCeIwI,809
+cartesia/stt/types/streaming_transcription_response.py,sha256=ZrOvlwRF068NQ5xm09WU0Nb8HH9yhDoubESMJvYKjPE,3063
+cartesia/stt/types/stt_encoding.py,sha256=OLxgmaNExZVFD1LXsEXcblALyylKIDePapAjDAI0r7w,148
+cartesia/stt/types/transcript_message.py,sha256=U7g0wAhA1T21Ls1KP4chuigwgGe15Ea-vsDWBSpm5e8,1426
+cartesia/stt/types/transcription_response.py,sha256=IJO6rDyO_5YmjlBUJX-3CdguZwB9ezQ4d9U4cG1V8Uw,902
 cartesia/tts/__init__.py,sha256=YrVxJT7i-0wygFgN2hOVftYLEM7JoFgCo3SvLoN7pkA,4735
 cartesia/tts/_async_websocket.py,sha256=tJ-6rdJrviKvGhSW8J8t-rCinXM5gXXQJgDO8OgW3EE,18805
 cartesia/tts/_websocket.py,sha256=bYaJ5vmCAl8AYrIJsqP3aA_nkFTeN3ey-Zc1nql_I3g,19274
@@ -171,6 +190,6 @@ cartesia/voices/types/voice_expand_options.py,sha256=e4FroWdlxEE-LXQfT1RWlGHtswl
 cartesia/voices/types/voice_id.py,sha256=GDoXcRVeIm-V21R4suxG2zqLD3DLYkXE9kgizadzFKo,79
 cartesia/voices/types/voice_metadata.py,sha256=4KNGjXMUKm3niv-NvKIFVGtiilpH13heuzKcZYNQxk4,1181
 cartesia/voices/types/weight.py,sha256=XqDU7_JItNUb5QykIDqTbELlRYQdbt2SviRgW0w2LKo,80
-cartesia-2.0.4.dist-info/METADATA,sha256=qzkBl1eSiyXX38UH3EiqhbFpFwoVZagLzaI233HYscE,11206
-cartesia-2.0.4.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
-cartesia-2.0.4.dist-info/RECORD,,
+cartesia-2.0.5.dist-info/METADATA,sha256=07frH81jDGiPEaVtyn2_sKwXyFWw81XkWWqsEWWV1Zw,16627
+cartesia-2.0.5.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
+cartesia-2.0.5.dist-info/RECORD,,