mia-narrative 1.0.10 → 1.1.0

package/README.md

@@ -31,49 +31,49 @@
 
 ### Get Started
 
-```bash
+\`\`\`bash
 git clone <repo>
 cd cli
 npm install
 npm run build
 npm link  # Makes 'mia-narrative' available globally
-```
+\`\`\`
 
 ### Optional: Setup Professional Voices
 
-```bash
+\`\`\`bash
 npm run setup
 # Automatically downloads Piper models (one-time, ~380MB)
-```
+\`\`\`
 
 ### Optional: ElevenLabs (Cloud Voices)
 
 Get an API key from [elevenlabs.io](https://elevenlabs.io):
 
-```bash
+\`\`\`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
+\`\`\`bash
 mia-narrative g -T "Hello, world!"
-```
+\`\`\`
 
 **With a specific voice** (Miette with British accent):
-```bash
+\`\`\`bash
 mia-narrative g -E piper -v miette -T "What a lovely day!" -O story.mp3
-```
+\`\`\`
 
 **From a text file** with effects:
-```bash
+\`\`\`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
+\`\`\`bash
 mia-narrative g \
   -E piper \
   -v mia \
@@ -83,7 +83,7 @@ mia-narrative g \
   --reverb 0.3 \
   --compression 0.4 \
   -O final.mp3
-```
+\`\`\`
 
 ### Command & Option Reference
 
@@ -98,7 +98,7 @@ mia-narrative g \
 
 See which narrators are available:
 
-```bash
+\`\`\`bash
 # See system voices (quick, no setup)
 mia-narrative voices --engine system
 
@@ -107,7 +107,7 @@ 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.
 
@@ -115,10 +115,10 @@ Output shows voice ID, personality, and which model it uses.
 
 Get access to professional voices with full control:
 
-```bash
+\`\`\`bash
 npm run setup
 # Downloads Mia, Miette, Seraphine, Jeremy, ResoNova, Zephyr, Echo, Atlas
-```
+\`\`\`
 
 ## Audio Parameters
 
@@ -153,8 +153,8 @@ npm run setup
 
 ## Contributing & Development
 
-```bash
+\`\`\`bash
 npm run build    # Compile TypeScript
 npm run dev -- g -T "test"  # Run in dev mode
 npm test         # Run tests
-```
+\`\`\`

package/bin/mia-narrative.ts

@@ -6,6 +6,7 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { generateCommand } from '../src/commands/generate.js';
 import { voicesCommand } from '../src/commands/voices.js';
+import { ensureMpg123 } from '../src/utils/prerequisites.js';
 
 // Get version from package.json
 let version = '1.0.0'; // fallback
@@ -20,6 +21,9 @@ try {
   // If we can't read package.json, use fallback version
 }
 
+// Check for mpg123 on startup (try to install if missing)
+ensureMpg123();
+
 const program = new Command();
 
 program

package/dist/bin/mia-narrative.js

@@ -5,6 +5,7 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { generateCommand } from '../src/commands/generate.js';
 import { voicesCommand } from '../src/commands/voices.js';
+import { ensureMpg123 } from '../src/utils/prerequisites.js';
 // Get version from package.json
 let version = '1.0.0'; // fallback
 try {
@@ -18,6 +19,8 @@ try {
 catch {
     // If we can't read package.json, use fallback version
 }
+// Check for mpg123 on startup (try to install if missing)
+ensureMpg123();
 const program = new Command();
 program
     .name('mia-narrative')

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,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D,gCAAgC;AAChC,IAAI,OAAO,GAAG,OAAO,CAAC,CAAC,WAAW;AAClC,IAAI,CAAC;IACH,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,oDAAoD;IACpD,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;IACpE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;IACvE,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC;AAChC,CAAC;AAAC,MAAM,CAAC;IACP,sDAAsD;AACxD,CAAC;AAED,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"}
+{"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,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,gCAAgC;AAChC,IAAI,OAAO,GAAG,OAAO,CAAC,CAAC,WAAW;AAClC,IAAI,CAAC;IACH,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,oDAAoD;IACpD,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;IACpE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;IACvE,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC;AAChC,CAAC;AAAC,MAAM,CAAC;IACP,sDAAsD;AACxD,CAAC;AAED,0DAA0D;AAC1D,YAAY,EAAE,CAAC;AAEf,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/dist/src/engines/piper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"piper.d.ts","sourceRoot":"","sources":["../../../src/engines/piper.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAGpF,qBAAa,WAAY,SAAQ,SAAS;IACxC,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,SAAS,CAAc;IAEzB,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxD,OAAO,CAAC,cAAc;IAMhB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC;IAmD7D,SAAS,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IAe7B,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAgBrC,OAAO,IAAI,MAAM;IAIjB,OAAO,CAAC,QAAQ;CA4CjB"}
+{"version":3,"file":"piper.d.ts","sourceRoot":"","sources":["../../../src/engines/piper.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAIpF,qBAAa,WAAY,SAAQ,SAAS;IACxC,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,SAAS,CAAc;IAEzB,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxD,OAAO,CAAC,cAAc;IAMhB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC;IAyD7D,SAAS,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IAiB7B,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAerC,OAAO,IAAI,MAAM;IAIjB,OAAO,CAAC,QAAQ;CA4CjB"}

package/dist/src/engines/piper.js

@@ -1,11 +1,12 @@
 import { spawn, execSync } from 'child_process';
 import { writeFileSync, unlinkSync, readFileSync, existsSync } from 'fs';
-import { tmpdir, homedir } from 'os';
+import { tmpdir } from 'os';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
 import { Logger } from '../utils/logger.js';
 import { TTSEngine } from './base.js';
 import { getVoiceProfile, VOICE_PROFILES } from '../config/voices.js';
+import { getPiperPath, getModelPath, getPiperMissingMessage } from '../utils/prerequisites.js';
 export class PiperEngine extends TTSEngine {
     constructor() {
         super(...arguments);
@@ -13,16 +14,15 @@ export class PiperEngine extends TTSEngine {
         this.modelPath = '';
     }
     async initialize(config) {
-        if (config.piperPath) {
-            this.piperPath = config.piperPath;
-        }
+        // Use provided config or fall back to environment/auto-detection
+        this.piperPath = config.piperPath || getPiperPath();
         if (config.modelPath) {
             this.modelPath = config.modelPath;
         }
         else {
-            this.modelPath = process.env.MIA_NARRATIVE_PIPER_MODEL || '';
+            this.modelPath = getModelPath();
         }
-        Logger.debug(`Piper engine initialized with model path: ${this.modelPath}`);
+        Logger.debug(`Piper engine initialized with piper path: ${this.piperPath}, model path: ${this.modelPath}`);
     }
     preprocessText(text) {
         // Add line breaks after periods to create longer pauses
@@ -38,13 +38,20 @@ export class PiperEngine extends TTSEngine {
         if (!text || text.trim().length === 0) {
             throw new Error('Text cannot be empty');
         }
-        // Build path to model file
-        const modelDir = join(homedir(), '.local/share/piper-tts');
-        const modelFile = join(modelDir, `${voiceProfile.piperModel}.onnx`);
+        // Build path to model file using configured model path
+        let modelFile;
+        if (this.modelPath.endsWith('.onnx')) {
+            // If modelPath is already a full model path, use it directly
+            modelFile = this.modelPath;
+        }
+        else {
+            // Otherwise, treat it as a directory and append model filename
+            modelFile = join(this.modelPath, `${voiceProfile.piperModel}.onnx`);
+        }
         if (!existsSync(modelFile)) {
             throw new Error(`Piper model not found: ${voiceProfile.piperModel}\n` +
                 `Expected location: ${modelFile}\n` +
-                `Run 'npm run setup' to download models.`);
+                `Run 'npm run setup' to download models or set MIA_NARRATIVE_PIPER_MODEL environment variable.`);
         }
         const tempDir = tmpdir();
         const uid = randomUUID();
@@ -75,7 +82,9 @@ export class PiperEngine extends TTSEngine {
         }
     }
     async getVoices() {
-        const modelDir = join(homedir(), '.local/share/piper-tts');
+        const modelDir = this.modelPath.endsWith('.onnx')
+            ? this.modelPath.substring(0, this.modelPath.lastIndexOf('/'))
+            : this.modelPath;
         return Object.values(VOICE_PROFILES)
             .filter(v => {
             const modelFile = join(modelDir, `${v.piperModel}.onnx`);
@@ -93,7 +102,6 @@ export class PiperEngine extends TTSEngine {
                 execSync('which piper', { stdio: 'pipe' });
             }
             else {
-                const { existsSync } = await import('fs');
                 if (!existsSync(this.piperPath)) {
                     return false;
                 }
@@ -134,7 +142,7 @@ export class PiperEngine extends TTSEngine {
                 }
             });
             piper.on('error', (error) => {
-                reject(new Error(`Failed to start Piper: ${error.message}. Ensure Piper is installed and in your PATH.`));
+                reject(new Error(`Failed to start Piper: ${error.message}\n\n${getPiperMissingMessage()}`));
             });
         });
     }

package/dist/src/engines/piper.js.map

@@ -1 +1 @@
-{"version":3,"file":"piper.js","sourceRoot":"","sources":["../../../src/engines/piper.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"piper.js","sourceRoot":"","sources":["../../../src/engines/piper.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/file-reader.d.ts

@@ -3,6 +3,7 @@ export declare class FileReader {
     static fileExists(filePath: string): boolean;
     /**
      * Strip Markdown syntax from text, leaving only readable content
+     * Also adds strategic pauses for better TTS pacing
      */
     static stripMarkdown(text: string): string;
 }

package/dist/src/utils/file-reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-reader.d.ts","sourceRoot":"","sources":["../../../src/utils/file-reader.ts"],"names":[],"mappings":"AAIA,qBAAa,UAAU;IACrB,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAY7C,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAQ5C;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAkD3C"}
+{"version":3,"file":"file-reader.d.ts","sourceRoot":"","sources":["../../../src/utils/file-reader.ts"],"names":[],"mappings":"AAIA,qBAAa,UAAU;IACrB,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAY7C,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAQ5C;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CA6D3C"}

package/dist/src/utils/file-reader.js

@@ -24,9 +24,18 @@ export class FileReader {
     }
     /**
      * Strip Markdown syntax from text, leaving only readable content
+     * Also adds strategic pauses for better TTS pacing
      */
     static stripMarkdown(text) {
         let result = text;
+        // Add pauses before headers (before stripping syntax)
+        // Insert period+newline twice before headers for longer pause
+        result = result.replace(/^(#{1,6})\s+/gm, '\n\n. \n. \n$1 ');
+        // Add pause after list items (before stripping list markers)
+        result = result.replace(/^([\s]*[-*+]\s+.+)$/gm, '$1. ');
+        result = result.replace(/^([\s]*\d+\.\s+.+)$/gm, '$1. ');
+        // Add pause after colons (in regular text)
+        result = result.replace(/:\s+([^\n])/g, ': . $1');
         // Remove code blocks (``` ... ```)
         result = result.replace(/```[\s\S]*?```/g, '');
         // Remove indented code blocks (4 spaces or tab at start of line)

package/dist/src/utils/file-reader.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-reader.js","sourceRoot":"","sources":["../../../src/utils/file-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,OAAO,UAAU;IACrB,MAAM,CAAC,YAAY,CAAC,QAAgB;QAClC,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YACvC,OAAO,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,MAAM,CAAC,KAAK,CAAC,wBAAwB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACxD,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,QAAgB;QAChC,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,IAAY;QAC/B,IAAI,MAAM,GAAG,IAAI,CAAC;QAElB,mCAAmC;QACnC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QAE/C,iEAAiE;QACjE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QAE/C,8BAA8B;QAC9B,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAE5C,qCAAqC;QACrC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;QACnD,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;QAE9C,mCAAmC;QACnC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;QAC/C,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAE5C,2BAA2B;QAC3B,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,yBAAyB,EAAE,IAAI,CAAC,CAAC;QAEzD,4BAA4B;QAC5B,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC;QAExD,+BAA+B;QAC/B,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAExC,yBAAyB;QACzB,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAEvC,6CAA6C;QAC7C,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;QAChD,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;QAEhD,0CAA0C;QAC1C,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,4BAA4B,EAAE,EAAE,CAAC,CAAC;QAE1D,mBAAmB;QACnB,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAExC,wDAAwD;QACxD,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;QAEjD,kBAAkB;QAClB,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAEvB,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}
+{"version":3,"file":"file-reader.js","sourceRoot":"","sources":["../../../src/utils/file-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,OAAO,UAAU;IACrB,MAAM,CAAC,YAAY,CAAC,QAAgB;QAClC,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YACvC,OAAO,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,MAAM,CAAC,KAAK,CAAC,wBAAwB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACxD,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,CAAC,UAAU,CAAC,QAAgB;QAChC,IAAI,CAAC;YACH,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,IAAY;QAC/B,IAAI,MAAM,GAAG,IAAI,CAAC;QAElB,sDAAsD;QACtD,8DAA8D;QAC9D,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,CAAC;QAE7D,6DAA6D;QAC7D,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC;QACzD,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC;QAEzD,2CAA2C;QAC3C,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;QAElD,mCAAmC;QACnC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QAE/C,iEAAiE;QACjE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QAE/C,8BAA8B;QAC9B,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAE5C,qCAAqC;QACrC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;QACnD,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;QAE9C,mCAAmC;QACnC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;QAC/C,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAE5C,2BAA2B;QAC3B,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,yBAAyB,EAAE,IAAI,CAAC,CAAC;QAEzD,4BAA4B;QAC5B,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC;QAExD,+BAA+B;QAC/B,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAExC,yBAAyB;QACzB,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAEvC,6CAA6C;QAC7C,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;QAChD,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;QAEhD,0CAA0C;QAC1C,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,4BAA4B,EAAE,EAAE,CAAC,CAAC;QAE1D,mBAAmB;QACnB,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAExC,wDAAwD;QACxD,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;QAEjD,kBAAkB;QAClB,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAEvB,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/src/utils/prerequisites.d.ts

@@ -0,0 +1,59 @@
+export interface PrerequisiteStatus {
+    piperPath: string;
+    piperAvailable: boolean;
+    modelPath: string;
+    modelAvailable: boolean;
+    configPath: string;
+    configAvailable: boolean;
+}
+/**
+ * Get the path to the piper binary
+ * Priority: MIA_NARRATIVE_PIPER_PATH env var → which piper → /opt/mianar/bin/piper
+ */
+export declare function getPiperPath(): string;
+/**
+ * Get the path to piper model file
+ * Priority: MIA_NARRATIVE_PIPER_MODEL env var → /opt/mianar/piper-tts/... → ~/.local/share/piper-tts/...
+ */
+export declare function getModelPath(): string;
+/**
+ * Check piper binary availability
+ */
+export declare function isPiperAvailable(): boolean;
+/**
+ * Check if model is available
+ */
+export declare function isModelAvailable(modelName?: string): boolean;
+/**
+ * Get comprehensive prerequisite status
+ */
+export declare function getPrerequisiteStatus(): PrerequisiteStatus;
+/**
+ * Generate helpful error message when piper is not available
+ */
+export declare function getPiperMissingMessage(): string;
+/**
+ * Generate helpful error message when models are not available
+ */
+export declare function getModelsMissingMessage(): string;
+/**
+ * Ensure directory exists for models
+ */
+export declare function ensureModelDirectory(): void;
+/**
+ * Check if mpg123 (MP3 audio player) is installed
+ */
+export declare function isMpg123Available(): boolean;
+/**
+ * Generate helpful message about mpg123 installation
+ */
+export declare function getMpg123MissingMessage(): string;
+/**
+ * Attempt to install mpg123 automatically (Linux only)
+ */
+export declare function tryInstallMpg123(): boolean;
+/**
+ * Ensure mpg123 is available, try to install if missing
+ */
+export declare function ensureMpg123(): boolean;
+//# sourceMappingURL=prerequisites.d.ts.map

package/dist/src/utils/prerequisites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prerequisites.d.ts","sourceRoot":"","sources":["../../../src/utils/prerequisites.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAqBrC;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAiBrC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAe1C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,GAAE,MAA8B,GAAG,OAAO,CAMnF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,CAY1D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAoB/C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAoBhD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAM3C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAO3C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAYhD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAkB1C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAYtC"}

package/dist/src/utils/prerequisites.js

@@ -0,0 +1,218 @@
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { Logger } from './logger.js';
+const OPT_MIANAR_PATH = '/opt/mianar';
+const OPT_MIANAR_PIPER_MODEL = '/opt/mianar/piper-tts/en_US-lessac-medium.onnx';
+/**
+ * Get the path to the piper binary
+ * Priority: MIA_NARRATIVE_PIPER_PATH env var → which piper → /opt/mianar/bin/piper
+ */
+export function getPiperPath() {
+    // 1. Check explicit environment variable
+    if (process.env.MIA_NARRATIVE_PIPER_PATH) {
+        Logger.debug(`Using MIA_NARRATIVE_PIPER_PATH: ${process.env.MIA_NARRATIVE_PIPER_PATH}`);
+        return process.env.MIA_NARRATIVE_PIPER_PATH;
+    }
+    // 2. Try to find piper in PATH
+    try {
+        const result = execSync('which piper', { stdio: 'pipe' }).toString().trim();
+        if (result) {
+            Logger.debug(`Found piper in PATH: ${result}`);
+            return result;
+        }
+    }
+    catch {
+        // Not in PATH
+    }
+    // 3. Default fallback
+    Logger.debug('Using default piper path: piper (will try to find in PATH at runtime)');
+    return 'piper';
+}
+/**
+ * Get the path to piper model file
+ * Priority: MIA_NARRATIVE_PIPER_MODEL env var → /opt/mianar/piper-tts/... → ~/.local/share/piper-tts/...
+ */
+export function getModelPath() {
+    // 1. Check explicit environment variable
+    if (process.env.MIA_NARRATIVE_PIPER_MODEL) {
+        Logger.debug(`Using MIA_NARRATIVE_PIPER_MODEL: ${process.env.MIA_NARRATIVE_PIPER_MODEL}`);
+        return process.env.MIA_NARRATIVE_PIPER_MODEL;
+    }
+    // 2. Check /opt/mianar structure
+    if (existsSync(OPT_MIANAR_PIPER_MODEL)) {
+        Logger.debug(`Found model in /opt/mianar: ${OPT_MIANAR_PIPER_MODEL}`);
+        return OPT_MIANAR_PIPER_MODEL;
+    }
+    // 3. Default to home directory structure
+    const defaultPath = join(homedir(), '.local/share/piper-tts');
+    Logger.debug(`Using default model directory: ${defaultPath}`);
+    return defaultPath;
+}
+/**
+ * Check piper binary availability
+ */
+export function isPiperAvailable() {
+    try {
+        const piperPath = getPiperPath();
+        if (piperPath === 'piper') {
+            // Try to find piper in PATH
+            execSync('which piper > /dev/null 2>&1');
+        }
+        else if (existsSync(piperPath)) {
+            return true;
+        }
+        else {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if model is available
+ */
+export function isModelAvailable(modelName = 'en_US-lessac-medium') {
+    const modelPath = getModelPath();
+    const modelFile = join(modelPath, `${modelName}.onnx`);
+    const configFile = `${modelFile}.json`;
+    return existsSync(modelFile) && existsSync(configFile);
+}
+/**
+ * Get comprehensive prerequisite status
+ */
+export function getPrerequisiteStatus() {
+    const piperPath = getPiperPath();
+    const modelPath = getModelPath();
+    return {
+        piperPath,
+        piperAvailable: isPiperAvailable(),
+        modelPath,
+        modelAvailable: isModelAvailable(),
+        configPath: `${modelPath}/en_US-lessac-medium.onnx.json`,
+        configAvailable: existsSync(join(modelPath, 'en_US-lessac-medium.onnx.json')),
+    };
+}
+/**
+ * Generate helpful error message when piper is not available
+ */
+export function getPiperMissingMessage() {
+    const status = getPrerequisiteStatus();
+    return `
+❌ Piper TTS is not available
+
+Piper path checked: ${status.piperPath}
+Piper available: ${status.piperAvailable ? '✓' : '✗'}
+
+To install Piper:
+1. Using pip:
+   pip install -U piper-tts
+   
+2. Then ensure it's in your PATH or set MIA_NARRATIVE_PIPER_PATH
+
+3. Or use the setup script:
+   npm run setup
+
+For more info: https://github.com/rhasspy/piper
+`;
+}
+/**
+ * Generate helpful error message when models are not available
+ */
+export function getModelsMissingMessage() {
+    const status = getPrerequisiteStatus();
+    return `
+❌ Piper TTS models are not available
+
+Looking in: ${status.modelPath}
+Models available: ${status.modelAvailable ? '✓' : '✗'}
+
+To download models:
+1. Run the setup script:
+   npm run setup
+   
+2. Or manually download to:
+   ${status.modelPath}
+
+Expected file:
+   en_US-lessac-medium.onnx
+   en_US-lessac-medium.onnx.json
+`;
+}
+/**
+ * Ensure directory exists for models
+ */
+export function ensureModelDirectory() {
+    const modelPath = getModelPath();
+    if (!existsSync(modelPath)) {
+        mkdirSync(modelPath, { recursive: true });
+        Logger.debug(`Created model directory: ${modelPath}`);
+    }
+}
+/**
+ * Check if mpg123 (MP3 audio player) is installed
+ */
+export function isMpg123Available() {
+    try {
+        execSync('which mpg123 > /dev/null 2>&1');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Generate helpful message about mpg123 installation
+ */
+export function getMpg123MissingMessage() {
+    return `
+⚠️  MP3 player (mpg123) not found
+
+To play generated audio files, install mpg123:
+  sudo apt-get install mpg123 -y    (Linux)
+  brew install mpg123               (macOS)
+  
+Or manually download from: https://www.mpg123.de/
+
+After installation, audio playback will work automatically.
+`;
+}
+/**
+ * Attempt to install mpg123 automatically (Linux only)
+ */
+export function tryInstallMpg123() {
+    try {
+        const { platform } = require('os');
+        // Only try on Linux systems with apt
+        if (platform() !== 'linux') {
+            return false;
+        }
+        execSync('which apt-get > /dev/null 2>&1');
+        Logger.debug('Attempting to install mpg123...');
+        execSync('sudo apt-get install mpg123 -y', { stdio: 'pipe' });
+        Logger.debug('✓ mpg123 installed successfully');
+        return true;
+    }
+    catch (error) {
+        Logger.debug(`Failed to auto-install mpg123: ${error}`);
+        return false;
+    }
+}
+/**
+ * Ensure mpg123 is available, try to install if missing
+ */
+export function ensureMpg123() {
+    if (isMpg123Available()) {
+        return true;
+    }
+    // Try to install
+    if (tryInstallMpg123()) {
+        return true;
+    }
+    Logger.warn(getMpg123MissingMessage());
+    return false;
+}
+//# sourceMappingURL=prerequisites.js.map

package/dist/src/utils/prerequisites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prerequisites.js","sourceRoot":"","sources":["../../../src/utils/prerequisites.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/scripts/fn_tts.sh

@@ -0,0 +1,89 @@
+fread() # Read a file with --file instead of --text (default: Mia voice)
+{
+        local _file="$1"
+        if [ -z "$_file" ];then
+                echo "Usage: fread <file>"
+                return 1
+        fi
+        local _withou_extension=$(basename "$_file" | cut -f 1 -d '.')
+        #the output file is the same as the input file but .mp3 and is NOT in /tmp
+        local _output_file="$_withou_extension.mp3"
+
+        mia-narrative generate --engine piper --file "$_file" --output $_output_file || {
+                echo "Failed to generate audio with mia-narrative."
+                return 1
+        }
+
+        # Try to play audio, but don't fail if unavailable (e.g., headless/SSH without forwarding)
+        if mpg123 $_output_file 2>/dev/null; then
+                :  # Audio played successfully
+        else
+                echo "✓ Generated: $_output_file (audio playback unavailable - use audio-gaia/audio-hu to enable)"
+        fi
+}
+
+# Persona-specific TTS functions
+fread_mia() { # Professional female narrator
+        local _file="$1"
+        [ -z "$_file" ] && echo "Usage: fread_mia <file>" && return 1
+        local _output="$(basename "$_file" .txt).mp3"
+        mia-narrative generate --engine piper --voiceId mia --file "$_file" --output "$_output" || return 1
+        mpg123 "$_output" 2>/dev/null || echo "✓ Generated: $_output (audio playback unavailable)"
+}
+
+fread_miette() { # Conversational female narrator
+        local _file="$1"
+        [ -z "$_file" ] && echo "Usage: fread_miette <file>" && return 1
+        local _output="$(basename "$_file" .txt).mp3"
+        mia-narrative generate --engine piper --voiceId miette --file "$_file" --output "$_output" || return 1
+        mpg123 "$_output" 2>/dev/null || echo "✓ Generated: $_output (audio playback unavailable)"
+}
+
+fread_seraphine() { # Expressive narrative female voice
+        local _file="$1"
+        [ -z "$_file" ] && echo "Usage: fread_seraphine <file>" && return 1
+        local _output="$(basename "$_file" .txt).mp3"
+        mia-narrative generate --engine piper --voiceId seraphine --file "$_file" --output "$_output" || return 1
+        mpg123 "$_output" 2>/dev/null || echo "✓ Generated: $_output (audio playback unavailable)"
+}
+
+fread_jeremy() { # Professional male narrator
+        local _file="$1"
+        [ -z "$_file" ] && echo "Usage: fread_jeremy <file>" && return 1
+        local _output="$(basename "$_file" .txt).mp3"
+        mia-narrative generate --engine piper --voiceId jeremy --file "$_file" --output "$_output" || return 1
+        mpg123 "$_output" 2>/dev/null || echo "✓ Generated: $_output (audio playback unavailable)"
+}
+
+fread_atlas() { # Casual male voice
+        local _file="$1"
+        [ -z "$_file" ] && echo "Usage: fread_atlas <file>" && return 1
+        local _output="$(basename "$_file" .txt).mp3"
+        mia-narrative generate --engine piper --voiceId atlas --file "$_file" --output "$_output" || return 1
+        mpg123 "$_output" 2>/dev/null || echo "✓ Generated: $_output (audio playback unavailable)"
+}
+
+fread_resonova() { # Expressive female voice
+        local _file="$1"
+        [ -z "$_file" ] && echo "Usage: fread_resonova <file>" && return 1
+        local _output="$(basename "$_file" .txt).mp3"
+        mia-narrative generate --engine piper --voiceId resonova --file "$_file" --output "$_output" || return 1
+        mpg123 "$_output" 2>/dev/null || echo "✓ Generated: $_output (audio playback unavailable)"
+}
+
+fread_zephyr() { # Neutral contemplative voice
+        local _file="$1"
+        [ -z "$_file" ] && echo "Usage: fread_zephyr <file>" && return 1
+        local _output="$(basename "$_file" .txt).mp3"
+        mia-narrative generate --engine piper --voiceId zephyr --file "$_file" --output "$_output" || return 1
+        mpg123 "$_output" 2>/dev/null || echo "✓ Generated: $_output (audio playback unavailable)"
+}
+
+fread_echo() { # Expressive character voice
+        local _file="$1"
+        [ -z "$_file" ] && echo "Usage: fread_echo <file>" && return 1
+        local _output="$(basename "$_file" .txt).mp3"
+        mia-narrative generate --engine piper --voiceId echo --file "$_file" --output "$_output" || return 1
+        mpg123 "$_output" 2>/dev/null || echo "✓ Generated: $_output (audio playback unavailable)"
+}
+

package/scripts/setup.js

@@ -7,6 +7,8 @@ import { join } from 'path';
 
 const HOME = homedir();
 const PIPER_MODEL_DIR = join(HOME, '.local/share/piper-tts');
+const OPT_MIANAR_PATH = '/opt/mianar';
+const DROPBOX_URL = 'https://www.dropbox.com/scl/fi/vl4mmi4wpz0eqtjljdh6c/opt_mianar_prerequisite_piper.tar?rlkey=paq9nfeoppfzjua1whsu7476z&dl=1';
 
 // Voice models to download (maps to voice profiles)
 const MODELS = [
@@ -20,30 +22,53 @@ const MODELS = [
 
 console.log('\n🎙️  mia-narrative Setup\n');
 
+// Check if /opt/mianar prerequisites are already downloaded
+console.log('1️⃣  Checking for /opt/mianar prerequisites...');
+if (existsSync(OPT_MIANAR_PATH)) {
+  const piperTtsPath = join(OPT_MIANAR_PATH, 'piper-tts');
+  if (existsSync(piperTtsPath)) {
+    console.log('   ✓ Found /opt/mianar/piper-tts');
+    console.log(`   → Using: ${piperTtsPath}`);
+    process.env.MIA_NARRATIVE_PIPER_MODEL = join(piperTtsPath, 'en_US-lessac-medium.onnx');
+  }
+} else {
+  console.log('   ⚠️  /opt/mianar not found, will download to home directory');
+}
+
 // Check Piper installation
-console.log('1️⃣  Checking for Piper TTS...');
+console.log('2️⃣  Checking for Piper TTS...');
 try {
   execSync('which piper > /dev/null 2>&1');
   console.log('   ✓ Piper is installed');
 } catch {
   console.log('   ⚠️  Piper not found in PATH');
-  console.log('   → Install from: https://github.com/rhasspy/piper');
-  process.exit(1);
+  console.log('   → Install from: pip install -U piper-tts');
+  console.log('   → After install, make sure "piper" is in your PATH');
 }
 
 // Check FFmpeg
-console.log('2️⃣  Checking for FFmpeg...');
+console.log('3️⃣  Checking for FFmpeg...');
 try {
   execSync('which ffmpeg > /dev/null 2>&1');
   console.log('   ✓ FFmpeg is installed');
 } catch {
   console.log('   ⚠️  FFmpeg not found');
   console.log('   → Install: brew install ffmpeg (macOS) or apt-get install ffmpeg (Linux)');
-  process.exit(1);
+}
+
+// Check mpg123
+console.log('4️⃣  Checking for MP3 player (mpg123)...');
+try {
+  execSync('which mpg123 > /dev/null 2>&1');
+  console.log('   ✓ mpg123 is installed');
+} catch {
+  console.log('   ⚠️  mpg123 not found');
+  console.log('   → For MP3 playback, install: sudo apt-get install mpg123 -y (Linux)');
+  console.log('   → Or: brew install mpg123 (macOS)');
 }
 
 // Check/Setup Piper models
-console.log(`3️⃣  Setting up Piper voice models...`);
+console.log(`5️⃣  Setting up Piper voice models...`);
 mkdirSync(PIPER_MODEL_DIR, { recursive: true });
 
 const totalSize = MODELS.reduce((sum, m) => {
@@ -97,10 +122,18 @@ for (const model of MODELS) {
 console.log('');
 if (downloadedCount === 0) {
   console.log('   ⚠️  No models downloaded. Check your internet connection.');
-  process.exit(1);
+} else {
+  console.log(`   ✓ Downloaded ${downloadedCount}/${MODELS.length} models`);
 }
 
-console.log(`   ✓ Downloaded ${downloadedCount}/${MODELS.length} models`);
+// Suggest /opt/mianar download
+console.log('\n6️⃣  Optional: Download /opt/mianar prerequisites...');
+if (!existsSync(OPT_MIANAR_PATH)) {
+  console.log('   → To use /opt/mianar structure:');
+  console.log('   → Run: mkdir -p /opt/mianar && sudo chown $USER /opt/mianar');
+  console.log('   → Then: wget -q -O - ' + DROPBOX_URL + ' | tar -xz -C /opt/mianar');
+  console.log('   → Set: export MIA_NARRATIVE_PIPER_MODEL=/opt/mianar/piper-tts/en_US-lessac-medium.onnx');
+}
 
 console.log('\n✅ Setup complete!');
 console.log('\nModels installed to:', PIPER_MODEL_DIR);
@@ -108,4 +141,7 @@ console.log('\nNext steps:');
 console.log('1. Test: mia-narrative generate --engine piper --text "hello"');
 console.log('2. List voices: mia-narrative voices --engine piper');
 console.log('3. Try a specific voice: mia-narrative generate --engine piper --voice miette-default --text "hello"');
+console.log('\nEnvironment variables you can set:');
+console.log('  MIA_NARRATIVE_PIPER_PATH=/path/to/piper');
+console.log('  MIA_NARRATIVE_PIPER_MODEL=/path/to/model.onnx or /path/to/models/directory');
 console.log('\n');

package/src/engines/piper.ts

@@ -6,23 +6,23 @@ import { randomUUID } from 'crypto';
 import { Logger } from '../utils/logger.js';
 import { TTSEngine, TTSEngineConfig, GenerateAudioOptions, Voice } from './base.js';
 import { getVoiceProfile, VOICE_PROFILES } from '../config/voices.js';
+import { getPiperPath, getModelPath, getPiperMissingMessage } from '../utils/prerequisites.js';
 
 export class PiperEngine extends TTSEngine {
   private piperPath: string = 'piper';
   private modelPath: string = '';
 
   async initialize(config: TTSEngineConfig): Promise<void> {
-    if (config.piperPath) {
-      this.piperPath = config.piperPath;
-    }
+    // Use provided config or fall back to environment/auto-detection
+    this.piperPath = config.piperPath || getPiperPath();
 
     if (config.modelPath) {
       this.modelPath = config.modelPath;
     } else {
-      this.modelPath = process.env.MIA_NARRATIVE_PIPER_MODEL || '';
+      this.modelPath = getModelPath();
     }
 
-    Logger.debug(`Piper engine initialized with model path: ${this.modelPath}`);
+    Logger.debug(`Piper engine initialized with piper path: ${this.piperPath}, model path: ${this.modelPath}`);
   }
 
   private preprocessText(text: string): string {
@@ -43,15 +43,21 @@ export class PiperEngine extends TTSEngine {
       throw new Error('Text cannot be empty');
     }
 
-    // Build path to model file
-    const modelDir = join(homedir(), '.local/share/piper-tts');
-    const modelFile = join(modelDir, `${voiceProfile.piperModel}.onnx`);
+    // Build path to model file using configured model path
+    let modelFile: string;
+    if (this.modelPath.endsWith('.onnx')) {
+      // If modelPath is already a full model path, use it directly
+      modelFile = this.modelPath;
+    } else {
+      // Otherwise, treat it as a directory and append model filename
+      modelFile = join(this.modelPath, `${voiceProfile.piperModel}.onnx`);
+    }
 
     if (!existsSync(modelFile)) {
       throw new Error(
         `Piper model not found: ${voiceProfile.piperModel}\n` +
         `Expected location: ${modelFile}\n` +
-        `Run 'npm run setup' to download models.`
+        `Run 'npm run setup' to download models or set MIA_NARRATIVE_PIPER_MODEL environment variable.`
       );
     }
 
@@ -83,7 +89,9 @@ export class PiperEngine extends TTSEngine {
   }
 
   async getVoices(): Promise<Voice[]> {
-    const modelDir = join(homedir(), '.local/share/piper-tts');
+    const modelDir = this.modelPath.endsWith('.onnx') 
+      ? this.modelPath.substring(0, this.modelPath.lastIndexOf('/'))
+      : this.modelPath;
 
     return Object.values(VOICE_PROFILES)
       .filter(v => {
@@ -102,7 +110,6 @@ export class PiperEngine extends TTSEngine {
       if (this.piperPath === 'piper') {
         execSync('which piper', { stdio: 'pipe' });
       } else {
-        const { existsSync } = await import('fs');
         if (!existsSync(this.piperPath)) {
           return false;
         }
@@ -155,7 +162,7 @@ export class PiperEngine extends TTSEngine {
       piper.on('error', (error) => {
         reject(
           new Error(
-            `Failed to start Piper: ${error.message}. Ensure Piper is installed and in your PATH.`
+            `Failed to start Piper: ${error.message}\n\n${getPiperMissingMessage()}`
           )
         );
       });

package/src/utils/file-reader.ts

@@ -25,10 +25,22 @@ export class FileReader {
 
   /**
    * Strip Markdown syntax from text, leaving only readable content
+   * Also adds strategic pauses for better TTS pacing
    */
   static stripMarkdown(text: string): string {
     let result = text;
 
+    // Add pauses before headers (before stripping syntax)
+    // Insert period+newline twice before headers for longer pause
+    result = result.replace(/^(#{1,6})\s+/gm, '\n\n. \n. \n$1 ');
+
+    // Add pause after list items (before stripping list markers)
+    result = result.replace(/^([\s]*[-*+]\s+.+)$/gm, '$1. ');
+    result = result.replace(/^([\s]*\d+\.\s+.+)$/gm, '$1. ');
+
+    // Add pause after colons (in regular text)
+    result = result.replace(/:\s+([^\n])/g, ': . $1');
+
     // Remove code blocks (``` ... ```)
     result = result.replace(/```[\s\S]*?```/g, '');
 

package/src/utils/prerequisites.ts

@@ -0,0 +1,245 @@
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { Logger } from './logger.js';
+
+const OPT_MIANAR_PATH = '/opt/mianar';
+const OPT_MIANAR_PIPER_MODEL = '/opt/mianar/piper-tts/en_US-lessac-medium.onnx';
+
+export interface PrerequisiteStatus {
+  piperPath: string;
+  piperAvailable: boolean;
+  modelPath: string;
+  modelAvailable: boolean;
+  configPath: string;
+  configAvailable: boolean;
+}
+
+/**
+ * Get the path to the piper binary
+ * Priority: MIA_NARRATIVE_PIPER_PATH env var → which piper → /opt/mianar/bin/piper
+ */
+export function getPiperPath(): string {
+  // 1. Check explicit environment variable
+  if (process.env.MIA_NARRATIVE_PIPER_PATH) {
+    Logger.debug(`Using MIA_NARRATIVE_PIPER_PATH: ${process.env.MIA_NARRATIVE_PIPER_PATH}`);
+    return process.env.MIA_NARRATIVE_PIPER_PATH;
+  }
+
+  // 2. Try to find piper in PATH
+  try {
+    const result = execSync('which piper', { stdio: 'pipe' }).toString().trim();
+    if (result) {
+      Logger.debug(`Found piper in PATH: ${result}`);
+      return result;
+    }
+  } catch {
+    // Not in PATH
+  }
+
+  // 3. Default fallback
+  Logger.debug('Using default piper path: piper (will try to find in PATH at runtime)');
+  return 'piper';
+}
+
+/**
+ * Get the path to piper model file
+ * Priority: MIA_NARRATIVE_PIPER_MODEL env var → /opt/mianar/piper-tts/... → ~/.local/share/piper-tts/...
+ */
+export function getModelPath(): string {
+  // 1. Check explicit environment variable
+  if (process.env.MIA_NARRATIVE_PIPER_MODEL) {
+    Logger.debug(`Using MIA_NARRATIVE_PIPER_MODEL: ${process.env.MIA_NARRATIVE_PIPER_MODEL}`);
+    return process.env.MIA_NARRATIVE_PIPER_MODEL;
+  }
+
+  // 2. Check /opt/mianar structure
+  if (existsSync(OPT_MIANAR_PIPER_MODEL)) {
+    Logger.debug(`Found model in /opt/mianar: ${OPT_MIANAR_PIPER_MODEL}`);
+    return OPT_MIANAR_PIPER_MODEL;
+  }
+
+  // 3. Default to home directory structure
+  const defaultPath = join(homedir(), '.local/share/piper-tts');
+  Logger.debug(`Using default model directory: ${defaultPath}`);
+  return defaultPath;
+}
+
+/**
+ * Check piper binary availability
+ */
+export function isPiperAvailable(): boolean {
+  try {
+    const piperPath = getPiperPath();
+    if (piperPath === 'piper') {
+      // Try to find piper in PATH
+      execSync('which piper > /dev/null 2>&1');
+    } else if (existsSync(piperPath)) {
+      return true;
+    } else {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if model is available
+ */
+export function isModelAvailable(modelName: string = 'en_US-lessac-medium'): boolean {
+  const modelPath = getModelPath();
+  const modelFile = join(modelPath, `${modelName}.onnx`);
+  const configFile = `${modelFile}.json`;
+  
+  return existsSync(modelFile) && existsSync(configFile);
+}
+
+/**
+ * Get comprehensive prerequisite status
+ */
+export function getPrerequisiteStatus(): PrerequisiteStatus {
+  const piperPath = getPiperPath();
+  const modelPath = getModelPath();
+  
+  return {
+    piperPath,
+    piperAvailable: isPiperAvailable(),
+    modelPath,
+    modelAvailable: isModelAvailable(),
+    configPath: `${modelPath}/en_US-lessac-medium.onnx.json`,
+    configAvailable: existsSync(join(modelPath, 'en_US-lessac-medium.onnx.json')),
+  };
+}
+
+/**
+ * Generate helpful error message when piper is not available
+ */
+export function getPiperMissingMessage(): string {
+  const status = getPrerequisiteStatus();
+  
+  return `
+❌ Piper TTS is not available
+
+Piper path checked: ${status.piperPath}
+Piper available: ${status.piperAvailable ? '✓' : '✗'}
+
+To install Piper:
+1. Using pip:
+   pip install -U piper-tts
+   
+2. Then ensure it's in your PATH or set MIA_NARRATIVE_PIPER_PATH
+
+3. Or use the setup script:
+   npm run setup
+
+For more info: https://github.com/rhasspy/piper
+`;
+}
+
+/**
+ * Generate helpful error message when models are not available
+ */
+export function getModelsMissingMessage(): string {
+  const status = getPrerequisiteStatus();
+  
+  return `
+❌ Piper TTS models are not available
+
+Looking in: ${status.modelPath}
+Models available: ${status.modelAvailable ? '✓' : '✗'}
+
+To download models:
+1. Run the setup script:
+   npm run setup
+   
+2. Or manually download to:
+   ${status.modelPath}
+
+Expected file:
+   en_US-lessac-medium.onnx
+   en_US-lessac-medium.onnx.json
+`;
+}
+
+/**
+ * Ensure directory exists for models
+ */
+export function ensureModelDirectory(): void {
+  const modelPath = getModelPath();
+  if (!existsSync(modelPath)) {
+    mkdirSync(modelPath, { recursive: true });
+    Logger.debug(`Created model directory: ${modelPath}`);
+  }
+}
+
+/**
+ * Check if mpg123 (MP3 audio player) is installed
+ */
+export function isMpg123Available(): boolean {
+  try {
+    execSync('which mpg123 > /dev/null 2>&1');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Generate helpful message about mpg123 installation
+ */
+export function getMpg123MissingMessage(): string {
+  return `
+⚠️  MP3 player (mpg123) not found
+
+To play generated audio files, install mpg123:
+  sudo apt-get install mpg123 -y    (Linux)
+  brew install mpg123               (macOS)
+  
+Or manually download from: https://www.mpg123.de/
+
+After installation, audio playback will work automatically.
+`;
+}
+
+/**
+ * Attempt to install mpg123 automatically (Linux only)
+ */
+export function tryInstallMpg123(): boolean {
+  try {
+    const { platform } = require('os');
+    // Only try on Linux systems with apt
+    if (platform() !== 'linux') {
+      return false;
+    }
+
+    execSync('which apt-get > /dev/null 2>&1');
+    
+    Logger.debug('Attempting to install mpg123...');
+    execSync('sudo apt-get install mpg123 -y', { stdio: 'pipe' });
+    Logger.debug('✓ mpg123 installed successfully');
+    return true;
+  } catch (error) {
+    Logger.debug(`Failed to auto-install mpg123: ${error}`);
+    return false;
+  }
+}
+
+/**
+ * Ensure mpg123 is available, try to install if missing
+ */
+export function ensureMpg123(): boolean {
+  if (isMpg123Available()) {
+    return true;
+  }
+
+  // Try to install
+  if (tryInstallMpg123()) {
+    return true;
+  }
+
+  Logger.warn(getMpg123MissingMessage());
+  return false;
+}