🎙️ mia-narrative CLI

Transform 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.

What You Can Do

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

Installation

$3

- Node.js v18+
- FFmpeg (for audio processing)
- Piper (optional, for better voices)

$3

\\\bash
git clone
cd cli
npm install
npm run build
npm link # Makes 'mia-narrative' available globally
\\\

$3

\\\bash
npm run setup


Automatically downloads Piper models (one-time, ~380MB)


\\\

$3

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
\\\

Quick Start

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
\\\

$3

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

$3

See which narrators are available:

\\\bash


See system voices (quick, no setup)

mia-narrative voices --engine system

See Piper personalities (download models first)

mia-narrative voices --engine piper

See ElevenLabs options (requires API key)

mia-narrative voices --engine elevenlabs
\\\

Output shows voice ID, personality, and which model it uses.

$3

Get access to professional voices with full control:

\\\bash
npm run setup


Downloads Mia, Miette, Seraphine, Jeremy, ResoNova, Zephyr, Echo, Atlas


\\\

Audio Parameters

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

Environment Variables

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

Troubleshooting

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

Contributing & Development

\\\bash
npm run build # Compile TypeScript
npm run dev -- g -T "test" # Run in dev mode
npm test # Run tests
\\\