Text-to-Speech

Listen to assistant messages with natural-sounding audio using ElevenLabs. Click the play button on any assistant message to hear it read aloud.

Features

• One-Click Playback: Play button appears on every assistant message
• Natural Voices: High-quality audio from ElevenLabs
• Stop Anytime: Click again to stop playback mid-sentence
• Rate Limited: 10 requests per minute to manage API costs

Setup

Text-to-speech requires an ElevenLabs API key. Add these to your .env:

IRIS_TTS_ENABLED=true
ELEVENLABS_API_KEY=your-elevenlabs-key

That's it - the play button will appear on assistant messages automatically.

Getting an ElevenLabs API Key

1. Create an account at elevenlabs.io
2. Navigate to your profile settings
3. Copy your API key from the API section

ElevenLabs offers a free tier with limited characters per month, which is enough for casual use.

Usage

After enabling TTS, you'll see a speaker icon next to the copy button on assistant messages:

1. Click the speaker icon to generate and play audio
2. The icon shows a loading spinner while generating
3. The icon changes to a stop button during playback
4. Click stop to end playback early

What Gets Converted

The text content of the assistant's message is sent to ElevenLabs. Code blocks, tool calls, and other non-text elements are excluded from the audio.

TIP

For long messages, audio generation may take a few seconds. The loading spinner indicates the API is processing your request.

Configuration

TTS settings are defined in config/iris.php:

Setting	Value	Description
tts.enabled	env-controlled	Set via IRIS_TTS_ENABLED
tts.model	eleven_multilingual_v2	Supports multiple languages
tts.voice	(configured)	Voice ID for speech generation

Changing the Voice

To use a different ElevenLabs voice, override the voice ID in config/iris-custom.php:

// config/iris-custom.php
return [
    'tts' => [
        'voice' => 'your-preferred-voice-id',
    ],
];

Find voice IDs in your ElevenLabs Voice Library.

TIP

See Customization for details on how iris-custom.php merges with core config.

Rate Limiting

TTS requests are rate limited to 10 per minute per user. This prevents accidental cost overruns and API abuse. If you hit the limit, wait a moment before trying again.

How It Works

1. Request: You click the play button on an assistant message
2. Generate: The backend sends the message text to ElevenLabs
3. Stream: ElevenLabs returns audio data
4. Play: The browser plays the audio using the Web Audio API

Audio is generated on-demand - there's no caching, so each click makes an API call.

Costs

ElevenLabs pricing is based on characters generated:

Plan	Characters/month	Notes
Free	10,000	Good for testing
Starter	30,000	~$5/month
Creator	100,000	~$22/month

A typical assistant message is 200-500 characters. The free tier supports roughly 20-50 message playbacks per month.

WARNING

Long conversations with frequent TTS use can consume characters quickly. Monitor your ElevenLabs dashboard for usage.

Troubleshooting

Play button doesn't appear: Verify IRIS_TTS_ENABLED=true in your .env and rebuild the frontend with npm run build.

"Text-to-speech is not enabled" error: The backend config isn't detecting the environment variable. Check your .env and clear the config cache: php artisan config:clear.

Audio doesn't play: Check your browser's console for errors. Some browsers block autoplay - try clicking the play button again.

"Too many requests" error: You've hit the rate limit. Wait a minute before trying again.

ElevenLabs API errors: Verify your API key is correct and your account has available characters.

Disabling Text-to-Speech

To disable TTS entirely, set the environment variable:

IRIS_TTS_ENABLED=false

The play button will no longer appear on assistant messages.