Metadata-Version: 2.1
Name: cartesia
Version: 0.0.3
Summary: The official Python library for the Cartesia API.
Home-page: 
Author: Cartesia, Inc.
Author-email: support@cartesia.ai
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8.0
Description-Content-Type: text/markdown
Requires-Dist: websockets
Requires-Dist: requests
Provides-Extra: all
Requires-Dist: pre-commit ; extra == 'all'
Requires-Dist: docformatter ; extra == 'all'
Requires-Dist: black ==24.1.1 ; extra == 'all'
Requires-Dist: isort ==5.13.2 ; extra == 'all'
Requires-Dist: flake8 ==7.0.0 ; extra == 'all'
Requires-Dist: flake8-bugbear ==24.2.6 ; extra == 'all'
Requires-Dist: pytest >=8.0.2 ; extra == 'all'
Requires-Dist: pytest-cov >=4.1.0 ; extra == 'all'
Provides-Extra: dev
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: docformatter ; extra == 'dev'
Requires-Dist: black ==24.1.1 ; extra == 'dev'
Requires-Dist: isort ==5.13.2 ; extra == 'dev'
Requires-Dist: flake8 ==7.0.0 ; extra == 'dev'
Requires-Dist: flake8-bugbear ==24.2.6 ; extra == 'dev'
Requires-Dist: pytest >=8.0.2 ; extra == 'dev'
Requires-Dist: pytest-cov >=4.1.0 ; extra == 'dev'


# Cartesia Python API Library
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.

## Installation
```bash
pip install cartesia

# pip install in editable mode w/ dev dependencies
pip install -e '.[dev]'
```

## Usage
```python
from cartesia.tts import CartesiaTTS
import pyaudio
import os

client = CartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
voices = client.get_voices()
voice = client.get_voice_embedding(voice_id=voices["Graham"]["id"])
transcript = "Hello! Welcome to Cartesia"

p = pyaudio.PyAudio()

stream = None

# Generate and stream audio
for output in client.generate(transcript=transcript, voice=voice, stream=True):
    buffer = output["audio"]
    rate = output["sampling_rate"]

    if not stream:
        stream = p.open(format=pyaudio.paFloat32,
                        channels=1,
                        rate=rate,
                        output=True)

    # Write the audio data to the stream
    stream.write(buffer)

stream.stop_stream()
stream.close()
p.terminate()
```

If you are using Jupyter Notebook or JupyterLab, you can use IPython.display.Audio to play the generated audio directly in the notebook. Here's an example:

```python
from cartesia.tts import CartesiaTTS
from IPython.display import Audio
import io
import os

client = CartesiaTTS(api_key=os.environ.get("CARTESIA_API_KEY"))
voices = client.get_voices()
voice = client.get_voice_embedding(voice_id=voices["Graham"]["id"])
transcript = "Hello! Welcome to Cartesia"

# Create a BytesIO object to store the audio data
audio_data = io.BytesIO()

# Generate and stream audio
for output in client.generate(transcript=transcript, voice=voice, stream=True):
    buffer = output["audio"]
    audio_data.write(buffer)

# Set the cursor position to the beginning of the BytesIO object
audio_data.seek(0)

# Create an Audio object from the BytesIO data
audio = Audio(audio_data, rate=output["sampling_rate"])

# Display the Audio object
display(audio)
```

We recommend using [`python-dotenv`](https://pypi.org/project/python-dotenv/) to add `CARTESIA_API_KEY="my-api-key"` to your .env file so that your API Key is not stored in the source code.
