elvenreader 0.2.0

CLI and library for the ElevenReader TTS API

elvenreader

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

Install

pip install elvenreader

Or for development:

uv sync
uv pip install -e .

Requires macOS (uses afplay for audio playback, including AirPlay) and a Tampermonkey browser extension for App Check token capture.

Library Usage

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

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):

elvenreader app-check --show-script

Copy the output into a new Tampermonkey script.

Capture the token:

elvenreader app-check

Then open 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

# 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

elvenreader voices

Shows all voices with name, gender, and description.

elvenreader create-voice — Design a new voice

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

elvenreader login

elvenreader app-check — Capture App Check token

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