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

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

Optional: Setup Professional Voices

```bash npm run setup

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

```

Optional: ElevenLabs (Cloud Voices)

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

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:

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

Setup Piper (Optional)

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