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

Prerequisites

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

Get Started

git clone <repo>
cd cli
npm install
npm run build
npm link  # Makes 'mia-narrative' available globally

Optional: Setup Professional Voices

npm run setup
# Automatically downloads Piper models (one-time, ~380MB)

Optional: ElevenLabs (Cloud Voices)

Get an API key from elevenlabs.io:

export ELEVENLABS_API_KEY="your_key_here"
mia-narrative g -E elevenlabs -T "Hello" -O output.mp3

Quick Start

Simplest command (uses system voice):

mia-narrative g -T "Hello, world!"

With a specific voice (Miette with British accent):

mia-narrative g -E piper -v miette -T "What a lovely day!" -O story.mp3

From a text file with effects:

mia-narrative g -E piper -v mia -F chapter.txt --pitch 1.1 --speed 0.95 -O chapter.mp3

Professional narrator with full effects:

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

Command & Option Reference

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

Explore Voices

See which narrators are available:

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

Setup Piper (Optional)

Get access to professional voices with full control:

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

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