---
slug: "pi-elevenlabs-tts"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ajsharp/pi-elevenlabs-tts@main/README.md"
repo: "https://github.com/ajsharp/pi-elevenlabs-tts"
source_file: "README.md"
branch: "main"
---
# pi-elevenlabs-tts

Pi extension that reads assistant text responses aloud with ElevenLabs text-to-speech. Tool calls and tool results are ignored. Bare `http://` and `https://` URL schemes are removed before speech. Current playback is stopped when the user submits a new message. On macOS, TTS skips playback by default when `pmset` reports active system audio or WebRTC audio activity, and the Pi status line shows when audio is blocking speech.

## Requirements

- Pi (`@mariozechner/pi-coding-agent`)
- ElevenLabs API key
- An audio player:
  - macOS: built-in `afplay`
  - Linux/other: `mpv` or `ffplay`, or set `ELEVENLABS_PLAYER`

## Setup

Install and authenticate the ElevenLabs CLI. The CLI is useful for login/account setup; TTS behavior is configured in the Pi extension via environment variables and `/speak` commands.

```bash
npm install -g @elevenlabs/cli
elevenlabs auth login
```

The extension reads the API key from either:

1. `ELEVENLABS_API_KEY`, or
2. `~/.elevenlabs/api_key` created by `elevenlabs auth login`

## Try locally

From this package directory:

```bash
pi -e ./extensions/elevenlabs-tts/index.ts
```

Or install as a local Pi package:

```bash
pi install /Users/ajsharp/code/pi-elevenlabs-tts
```

Then restart Pi or run `/reload`.

## Commands

Inside Pi:

```text
/speak status                  # show current config
/speak on                      # enable auto-read
/speak off                     # disable auto-read
/speak stop                    # stop playback
/speak last                    # replay last spoken assistant text
/speak voices [search]         # list available ElevenLabs voices
/speak voice <voice-id>        # set voice
/speak model <model-id>        # set TTS model
/speak skip-when-audio on|off  # skip TTS when macOS reports active audio
/speak stability <0-1>         # set voice stability
/speak similarity <0-1>        # set similarity boost
/speak style <0-1>             # set style exaggeration
/speak speed <0.7-1.2>         # set speaking speed
/speak boost on|off            # speaker boost
/speak reset                   # reset to environment/default config
```

Command changes are persisted into the current Pi session and restored after `/reload`.

## Configuration

Environment variables:

| Variable | Default | Description |
| --- | --- | --- |
| `ELEVENLABS_API_KEY` | read from `~/.elevenlabs/api_key` | ElevenLabs API key |
| `ELEVENLABS_TTS_ENABLED` | `true` | Auto-read responses aloud |
| `ELEVENLABS_VOICE_ID` | `JBFqnCBsd6RMkjVDRZzb` | Voice ID |
| `ELEVENLABS_MODEL_ID` | `eleven_turbo_v2_5` | TTS model |
| `ELEVENLABS_OUTPUT_FORMAT` | `mp3_44100_128` | ElevenLabs output format |
| `ELEVENLABS_API_BASE` | `https://api.elevenlabs.io` | API base URL |
| `ELEVENLABS_MAX_CHARS` | `4000` | Max characters spoken per response |
| `ELEVENLABS_STRIP_CODE_BLOCKS` | `true` | Remove fenced code blocks from spoken text |
| `ELEVENLABS_SKIP_WHEN_AUDIO_ACTIVE` | `true` | On macOS, skip TTS when `pmset` reports active output audio or WebRTC audio activity |
| `ELEVENLABS_AUDIO_ACTIVE_STATUS_INTERVAL_MS` | `30000` | Status-line polling interval for macOS audio activity |
| `ELEVENLABS_STABILITY` | ElevenLabs default | Voice stability, `0`-`1` |
| `ELEVENLABS_SIMILARITY_BOOST` | ElevenLabs default | Similarity boost, `0`-`1` |
| `ELEVENLABS_STYLE` | ElevenLabs default | Style exaggeration, `0`-`1` |
| `ELEVENLABS_SPEED` | ElevenLabs default | Speaking speed, usually `0.7`-`1.2` |
| `ELEVENLABS_USE_SPEAKER_BOOST` | ElevenLabs default | `true`/`false` speaker boost |
| `ELEVENLABS_PLAYER` | `afplay` on macOS, `mpv --really-quiet` elsewhere | Audio player command |

Example:

```bash
export ELEVENLABS_VOICE_ID="JBFqnCBsd6RMkjVDRZzb"
export ELEVENLABS_MODEL_ID="eleven_turbo_v2_5"
pi -e ./extensions/elevenlabs-tts/index.ts
```