mia-narrative 1.0.5 → 1.0.7

package/README.md

@@ -1,112 +1,123 @@
 # 🎙️ mia-narrative CLI
 
-A powerful, multi-engine text-to-speech command-line tool for narrative audio generation.
+**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.
 
-## Features
+## What You Can Do
 
-- **Multiple TTS Engines**:
-  - `system`: Uses the operating system's built-in TTS. No setup required.
-  - `elevenlabs`: High-quality, low-latency speech from ElevenLabs. Requires an API key.
-  - `piper`: High-quality, local, and private TTS via Piper. Requires Piper to be installed.
-- **Audio Effects**: Customize your audio with effects like speed, pitch, volume, and more.
-- **Simple Interface**: Easy-to-use commands for generating audio and listing voices.
+🎭 **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)
 
-1.  **Node.js**: v18 or higher.
-2.  **FFmpeg**: For audio processing.
-3.  **(Optional) Piper TTS**: If you plan to use the `piper` engine. Install from [https://github.com/rhasspy/piper](https://github.com/rhasspy/piper).
-
-### Setup
+### Get Started
 
 ```bash
-cd /workspace/MiaNar/cli
+git clone <repo>
+cd cli
 npm install
 npm run build
-npm link  # Makes 'mia-narrative' globally available
+npm link  # Makes 'mia-narrative' available globally
 ```
 
-## Configuration
-
-### System Engine
-
-No configuration is required. This is the default engine.
-
-### ElevenLabs Engine
-
-Set your ElevenLabs API key as an environment variable:
+### Optional: Setup Professional Voices
 
 ```bash
-export ELEVENLABS_API_KEY="your_api_key_here"
+npm run setup
+# Automatically downloads Piper models (one-time, ~380MB)
 ```
 
-### Piper Engine
+### Optional: ElevenLabs (Cloud Voices)
 
-Set the path to your Piper model(s) directory:
+Get an API key from [elevenlabs.io](https://elevenlabs.io):
 
 ```bash
-export MIA_NARRATIVE_PIPER_MODEL_PATH="/path/to/your/piper/models"
+export ELEVENLABS_API_KEY="your_key_here"
+mia-narrative g -E elevenlabs -T "Hello" -O output.mp3
 ```
-You also need to specify the piper executable path if it's not in your PATH:
-```bash
-export MIA_NARRATIVE_PIPER_PATH="/path/to/your/piper/executable"
-```
-
-## Usage
-
-### Generate Audio
 
-**Using the default `system` engine:**
+## Quick Start
 
+**Simplest command** (uses system voice):
 ```bash
-mia-narrative generate --text "Hello from my computer" --output hello.mp3
+mia-narrative g -T "Hello, world!"
 ```
 
-**Using the `elevenlabs` engine:**
-
+**With a specific voice** (Miette with British accent):
 ```bash
-mia-narrative generate --engine elevenlabs --text "Hello from the cloud" --voiceId "Rachel" --output cloud.mp3
+mia-narrative g -E piper -v miette -T "What a lovely day!" -O story.mp3
 ```
 
-**Using the `piper` engine with a file:**
-
+**From a text file** with effects:
 ```bash
-mia-narrative generate --engine piper --file story.txt --voiceId "en_US-lessac-medium" --output story.mp3
+mia-narrative g -E piper -v mia -F chapter.txt --pitch 1.1 --speed 0.95 -O chapter.mp3
 ```
 
-**With audio parameters:**
-
+**Professional narrator** with full effects:
 ```bash
-mia-narrative generate \
-  --file chapter.txt \
-  --engine piper \
-  --voiceId "en_US-lessac-medium" \
+mia-narrative g \
+  -E piper \
+  -v mia \
+  -F narrative.txt \
+  --pitch 1.0 \
   --speed 0.9 \
-  --pitch 1.1 \
-  --output chapter.mp3
+  --reverb 0.3 \
+  --compression 0.4 \
+  -O final.mp3
 ```
 
-### List Voices
+### Command & Option Reference
 
-List voices for a specific engine.
+- `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)
 
-**List system voices:**
+### Explore Voices
+
+See which narrators are available:
 
 ```bash
+# See system voices (quick, no setup)
 mia-narrative voices --engine system
-```
 
-**List ElevenLabs voices (in JSON format):**
+# See Piper personalities (download models first)
+mia-narrative voices --engine piper
 
-```bash
-mia-narrative voices --engine elevenlabs --format json
+# See ElevenLabs options (requires API key)
+mia-narrative voices --engine elevenlabs
 ```
 
-**List Piper voices:**
+Output shows voice ID, personality, and which model it uses.
+
+### Setup Piper (Optional)
+
+Get access to professional voices with full control:
+
 ```bash
-mia-narrative voices --engine piper
+npm run setup
+# Downloads Mia, Miette, Seraphine, Jeremy, ResoNova, Zephyr, Echo, Atlas
 ```
 
 ## Audio Parameters
@@ -125,25 +136,25 @@ mia-narrative voices --engine piper
 
 ## Environment Variables
 
--   `ELEVENLABS_API_KEY`: Your API key for the ElevenLabs engine.
--   `MIA_NARRATIVE_PIPER_PATH`: Custom path to the Piper binary (e.g., `/usr/local/bin/piper`).
--   `MIA_NARRATIVE_PIPER_MODEL_PATH`: Path to the directory containing Piper voice models.
--   `DEBUG`: Set to `1` for verbose debug output.
+| 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
 
-### FFmpeg not found
-
-Install FFmpeg using your system's package manager (e.g., `brew install ffmpeg`, `sudo apt-get install ffmpeg`).
-
-## Development
+| Issue | Fix |
+|-------|-----|
+| FFmpeg not found | `brew install ffmpeg` (Mac) or `apt-get install ffmpeg` (Linux) |
+| Piper not found | Install from [github.com/rhasspy/piper](https://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 |
 
-Build the project:
-```bash
-npm run build
-```
+## Contributing & Development
 
-Run in development mode:
 ```bash
-npm run dev -- voices --engine system
+npm run build    # Compile TypeScript
+npm run dev -- g -T "test"  # Run in dev mode
+npm test         # Run tests
 ```

package/bin/mia-narrative.ts

@@ -13,17 +13,18 @@ program
 
 program
   .command('generate')
+  .alias('g')
   .description('Generate audio from text')
-  .option('--text <text>', 'Text to convert to speech')
-  .option('--file <path>', 'Read text from file')
+  .option('-T, --text <text>', 'Text to convert to speech')
+  .option('-F, --file <path>', 'Read text from file')
   .option(
-    '--engine <name>',
+    '-E, --engine <name>',
     'TTS engine to use (system, elevenlabs, piper)',
     'system'
   )
-  .option('--voiceId <id>', 'Voice ID to use')
+  .option('-v, --voiceId <id>', 'Voice ID to use')
   .option(
-    '--output <path>',
+    '-O, --output <path>',
     'Output MP3 file path (default: output.mp3)'
   )
   .option(

package/dist/bin/mia-narrative.js

@@ -9,12 +9,13 @@ program
     .version('1.0.0');
 program
     .command('generate')
+    .alias('g')
     .description('Generate audio from text')
-    .option('--text <text>', 'Text to convert to speech')
-    .option('--file <path>', 'Read text from file')
-    .option('--engine <name>', 'TTS engine to use (system, elevenlabs, piper)', 'system')
-    .option('--voiceId <id>', 'Voice ID to use')
-    .option('--output <path>', 'Output MP3 file path (default: output.mp3)')
+    .option('-T, --text <text>', 'Text to convert to speech')
+    .option('-F, --file <path>', 'Read text from file')
+    .option('-E, --engine <name>', 'TTS engine to use (system, elevenlabs, piper)', 'system')
+    .option('-v, --voiceId <id>', 'Voice ID to use')
+    .option('-O, --output <path>', 'Output MP3 file path (default: output.mp3)')
     .option('--speed <number>', 'Speech rate (default: 1.0)', parseFloat)
     .option('--pitch <number>', 'Pitch (default: 1.0)', parseFloat)
     .option('--volume <number>', 'Volume (default: 0.8)', parseFloat)

package/dist/bin/mia-narrative.js.map

@@ -1 +1 @@
-{"version":3,"file":"mia-narrative.js","sourceRoot":"","sources":["../../bin/mia-narrative.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,eAAe,CAAC;KACrB,WAAW,CAAC,mDAAmD,CAAC;KAChE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,UAAU,CAAC;KACnB,WAAW,CAAC,0BAA0B,CAAC;KACvC,MAAM,CAAC,eAAe,EAAE,2BAA2B,CAAC;KACpD,MAAM,CAAC,eAAe,EAAE,qBAAqB,CAAC;KAC9C,MAAM,CACL,iBAAiB,EACjB,+CAA+C,EAC/C,QAAQ,CACT;KACA,MAAM,CAAC,gBAAgB,EAAE,iBAAiB,CAAC;KAC3C,MAAM,CACL,iBAAiB,EACjB,4CAA4C,CAC7C;KACA,MAAM,CACL,kBAAkB,EAClB,4BAA4B,EAC5B,UAAU,CACX;KACA,MAAM,CACL,kBAAkB,EAClB,sBAAsB,EACtB,UAAU,CACX;KACA,MAAM,CACL,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,CACX;KACA,MAAM,CACL,qBAAqB,EACrB,yBAAyB,EACzB,UAAU,CACX;KACA,MAAM,CACL,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,CACX;KACA,MAAM,CACL,iBAAiB,EACjB,qBAAqB,EACrB,UAAU,CACX;KACA,MAAM,CACL,wBAAwB,EACxB,4BAA4B,EAC5B,UAAU,CACX;KACA,MAAM,CACL,kBAAkB,EAClB,6BAA6B,EAC7B,UAAU,CACX;KACA,MAAM,CAAC,eAAe,CAAC,CAAC;AAE3B,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,6CAA6C,CAAC;KAC1D,MAAM,CACL,iBAAiB,EACjB,2DAA2D,EAC3D,QAAQ,CACT;KACA,MAAM,CACL,mBAAmB,EACnB,mCAAmC,EACnC,OAAO,CACR;KACA,MAAM,CAAC,aAAa,CAAC,CAAC;AAEzB,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"mia-narrative.js","sourceRoot":"","sources":["../../bin/mia-narrative.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,eAAe,CAAC;KACrB,WAAW,CAAC,mDAAmD,CAAC;KAChE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,UAAU,CAAC;KACnB,KAAK,CAAC,GAAG,CAAC;KACV,WAAW,CAAC,0BAA0B,CAAC;KACvC,MAAM,CAAC,mBAAmB,EAAE,2BAA2B,CAAC;KACxD,MAAM,CAAC,mBAAmB,EAAE,qBAAqB,CAAC;KAClD,MAAM,CACL,qBAAqB,EACrB,+CAA+C,EAC/C,QAAQ,CACT;KACA,MAAM,CAAC,oBAAoB,EAAE,iBAAiB,CAAC;KAC/C,MAAM,CACL,qBAAqB,EACrB,4CAA4C,CAC7C;KACA,MAAM,CACL,kBAAkB,EAClB,4BAA4B,EAC5B,UAAU,CACX;KACA,MAAM,CACL,kBAAkB,EAClB,sBAAsB,EACtB,UAAU,CACX;KACA,MAAM,CACL,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,CACX;KACA,MAAM,CACL,qBAAqB,EACrB,yBAAyB,EACzB,UAAU,CACX;KACA,MAAM,CACL,mBAAmB,EACnB,uBAAuB,EACvB,UAAU,CACX;KACA,MAAM,CACL,iBAAiB,EACjB,qBAAqB,EACrB,UAAU,CACX;KACA,MAAM,CACL,wBAAwB,EACxB,4BAA4B,EAC5B,UAAU,CACX;KACA,MAAM,CACL,kBAAkB,EAClB,6BAA6B,EAC7B,UAAU,CACX;KACA,MAAM,CAAC,eAAe,CAAC,CAAC;AAE3B,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,6CAA6C,CAAC;KAC1D,MAAM,CACL,iBAAiB,EACjB,2DAA2D,EAC3D,QAAQ,CACT;KACA,MAAM,CACL,mBAAmB,EACnB,mCAAmC,EACnC,OAAO,CACR;KACA,MAAM,CAAC,aAAa,CAAC,CAAC;AAEzB,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mia-narrative",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Text-to-speech CLI for narrative audio generation",
   "type": "module",
   "bin": {