Text-to-speech CLI for narrative audio generation
npm install mia-narrativeTransform your text into expressive audio narratives. Choose between professional narrators, adjust their tone and pace, add ambient effects—all from your command line. No recording equipment needed.
🎭 Meet the Voices
- Mia: Professional, technical content expert
- Miette: Conversational, warm British charm
- Seraphine & Echo: Expressive storytellers
- Jeremy & Atlas: Confident male narrators
- ResoNova & Zephyr: Unique, experimental voices
💨 Shape Your Audio
- Adjust speech speed (0.5x - 2.0x)
- Change pitch and tone
- Add reverb, echo, or compression effects
- Insert natural pauses at sentence boundaries
🔌 Multiple Engines
- System: Your OS's built-in voice (quick, no setup)
- Piper: Private, local, open-source (best control)
- ElevenLabs: Cloud-based, premium quality (requires API key)
\\\bash\
git clone
cd cli
npm install
npm run build
npm link # Makes 'mia-narrative' available globally
\\
\\\bash\
npm run setupAutomatically downloads Piper models (one-time, ~380MB)
\\
Get an API key from elevenlabs.io:
\\\bash\
export ELEVENLABS_API_KEY="your_key_here"
mia-narrative g -E elevenlabs -T "Hello" -O output.mp3
\\
Simplest command (uses system voice):
\\\bash\
mia-narrative g -T "Hello, world!"
\\
With a specific voice (Miette with British accent):
\\\bash\
mia-narrative g -E piper -v miette -T "What a lovely day!" -O story.mp3
\\
From a text file with effects:
\\\bash\
mia-narrative g -E piper -v mia -F chapter.txt --pitch 1.1 --speed 0.95 -O chapter.mp3
\\
Professional narrator with full effects:
\\\bash\
mia-narrative g \
-E piper \
-v mia \
-F narrative.txt \
--pitch 1.0 \
--speed 0.9 \
--reverb 0.3 \
--compression 0.4 \
-O final.mp3
\\
- g = short for generate command
- -E, --engine = which TTS engine (piper, elevenlabs, system)
- -v, --voiceId = which narrator (mia, miette, seraphine, jeremy, etc.)
- -T, --text = text to speak
- -F, --file = read from file instead
- -O, --output = where to save (default: output.mp3)
See which narrators are available:
\\\bashSee system voices (quick, no setup)
mia-narrative voices --engine system
\Output shows voice ID, personality, and which model it uses.
Get access to professional voices with full control:
\\\bash\
npm run setupDownloads Mia, Miette, Seraphine, Jeremy, ResoNova, Zephyr, Echo, Atlas
\\
| Parameter | Range | Default | Effect |
|---------------|-----------|---------|------------------|
| speed | 0.5-2.0 | 1.0 | Speech rate |
| pitch | 0.5-2.0 | 1.0 | Tonal height |
| volume | 0.0-1.0 | 0.8 | Loudness |
| emphasis | 0.0-1.0 | 0.5 | Dramatic intensity |
| reverb | 0.0-1.0 | 0.2 | Spatial acoustics|
| echo | 0.1-2.0 | 0.1 | Delay effect |
| compression | 0.0-1.0 | 0.3 | Dynamic range |
| pause | 0.1-2.0s | 0.5 | Break timing |
| Variable | What it does |
|----------|-------------|
| ELEVENLABS_API_KEY | Your API key for cloud voices |
| MIA_NARRATIVE_PIPER_PATH | Custom path to Piper binary (if not in PATH) |
| DEBUG | Set to 1 for verbose output |
| Issue | Fix |
|-------|-----|
| FFmpeg not found | brew install ffmpeg (Mac) or apt-get install ffmpeg (Linux) |
| Piper not found | Install from github.com/rhasspy/piper |
| Voices not available | Run npm run setup to download Piper models |
| API errors with ElevenLabs | Check your ELEVENLABS_API_KEY is set correctly |
\\\bash\
npm run build # Compile TypeScript
npm run dev -- g -T "test" # Run in dev mode
npm test # Run tests
\\