Metadata-Version: 2.4
Name: elvenreader
Version: 0.1.0
Summary: CLI and library for the ElevenReader TTS API
Project-URL: Homepage, https://github.com/bmf/elvenreader
Project-URL: Repository, https://github.com/bmf/elvenreader
Author: Brandon Fryslie
License-Expression: MIT
License-File: LICENSE
Keywords: audiobook,elevenlabs,elvenreader,text-to-speech,tts
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.12
Requires-Dist: click>=8
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25
Requires-Dist: truststore>=0.10
Requires-Dist: websockets>=13
Description-Content-Type: text/markdown

# elvenreader

CLI and library for the ElevenReader TTS API. Read text aloud or save it as MP3 using your ElevenReader subscription.

## Install

```bash
pip install elvenreader
```

Or for development:

```bash
uv sync
uv pip install -e .
```

Requires macOS (uses `afplay` for audio playback, including AirPlay) and a [Tampermonkey](https://www.tampermonkey.net/) browser extension for App Check token capture.

## Library Usage

```python
import asyncio
from elvenreader import ElvenReader

async def main():
    reader = ElvenReader.from_keychain()  # uses stored credentials
    mp3 = await reader.read("Hello world", voice="george")

    # Or save directly to file
    await reader.read_to_file("Hello world", "output.mp3", voice="brian")

asyncio.run(main())
```

## Setup

### 1. Login

```bash
elvenreader login
```

Prompts for your ElevenLabs email and password. Stores a refresh token in the macOS Keychain.

### 2. App Check Token

The streaming API requires a Firebase App Check token (~7 day lifetime). A Tampermonkey userscript captures it automatically from elevenreader.io.

**Install the script (one-time):**

```bash
elvenreader app-check --show-script
```

Copy the output into a new Tampermonkey script.

**Capture the token:**

```bash
elvenreader app-check
```

Then open [elevenreader.io](https://elevenreader.io) and play any read. The script intercepts the token from the WebSocket handshake and sends it to the CLI. Re-run this when the token expires.

## Commands

### `elvenreader read` — Read text aloud

```bash
# Stream playback (plays through system audio output, including AirPlay)
elvenreader read "Hello world, this is a test." --play

# Save to MP3
elvenreader read "Hello world" --output hello.mp3

# Both at once
elvenreader read "Hello world" --play --output hello.mp3

# Read from a file
elvenreader read --file chapter1.txt --play

# Use a specific voice
elvenreader read "Hello world" --play --voice george
```

**Options:**
- `-p, --play` — Stream audio playback via afplay
- `-o, --output PATH` — Save MP3 to file
- `-f, --file PATH` — Read text from a file instead of an argument
- `-v, --voice NAME` — Voice name or ID (default: `brian`)

### `elvenreader voices` — List available voices

```bash
elvenreader voices
```

Shows all voices with name, gender, and description.

### `elvenreader create-voice` — Design a new voice

```bash
elvenreader create-voice "warm British male, slightly raspy, authoritative storyteller" --name "My Narrator"
```

Generates preview voices from your description, plays each one, then prompts you to pick which to save. The saved voice is immediately available for use with `--voice`.

**Options:**
- `-n, --name TEXT` — Name for the new voice (required)

### `elvenreader login` — Authenticate

```bash
elvenreader login
```

### `elvenreader app-check` — Capture App Check token

```bash
elvenreader app-check              # Wait for token from Tampermonkey script
elvenreader app-check --show-script # Print the Tampermonkey script
```
