mia-narrative 1.0.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "mia-narrative",
+  "version": "1.0.0",
+  "description": "Text-to-speech CLI for narrative audio generation",
+  "type": "module",
+  "bin": {
+    "mia-narrative": "./dist/bin/mia-narrative.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node bin/mia-narrative.ts",
+    "test": "node --test dist/**/*.test.js"
+  },
+  "keywords": [
+    "tts",
+    "text-to-speech",
+    "piper",
+    "audio",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@elevenlabs/elevenlabs-js": "^2.27.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "ora": "^9.0.0",
+    "say": "^0.16.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/audio/processor.ts

@@ -0,0 +1,94 @@
+import { spawn } from 'child_process';
+import { AudioParameters } from '../config/defaults.js';
+import { Logger } from '../utils/logger.js';
+
+export class AudioProcessor {
+  static buildFFmpegFilter(params: AudioParameters): string {
+    const filters: string[] = [];
+
+    if (params.speed !== 1.0) {
+      filters.push(`atempo=${Math.max(0.5, Math.min(2.0, params.speed))}`);
+    }
+
+    if (params.volume !== 0.8) {
+      filters.push(`volume=${Math.max(0.0, Math.min(1.0, params.volume))}`);
+    }
+
+    if (params.pitch !== 1.0) {
+      const sampleRateMultiplier = Math.max(0.5, Math.min(2.0, params.pitch));
+      filters.push(`asetrate=44100*${sampleRateMultiplier}`);
+    }
+
+    if (params.reverb > 0.0) {
+      const reverb = Math.min(1.0, params.reverb);
+      filters.push(
+        `aecho=0.8:${0.88 * reverb}:${6 + reverb * 100}:${0.3 + reverb * 0.4}`
+      );
+    }
+
+    if (params.echo !== 0.1) {
+      const echoDelay = Math.max(0.1, Math.min(2.0, params.echo)) * 100;
+      filters.push(`aecho=0.8:0.88:${echoDelay}:0.4`);
+    }
+
+    if (params.compression > 0.0) {
+      const ratio = 2 + params.compression * 8; // 2:1 to 10:1
+      const threshold = Math.max(0.001, Math.min(1, 0.3 + params.compression * 0.5));
+      filters.push(
+        `acompressor=ratio=${ratio}:threshold=${threshold}:makeup=${params.compression * 5}`
+      );
+    }
+
+    return filters.length > 0 ? filters.join(',') : '';
+  }
+
+  static async processAudio(
+    inputPath: string,
+    outputPath: string,
+    params: AudioParameters
+  ): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const filterComplex = this.buildFFmpegFilter(params);
+      const args: string[] = [
+        '-i',
+        inputPath,
+        '-codec:a',
+        'libmp3lame',
+        '-b:a',
+        '192k',
+        '-ar',
+        '44100',
+        '-ac',
+        '2',
+      ];
+
+      if (filterComplex) {
+        Logger.debug(`Applying FFMpeg filters: ${filterComplex}`);
+        args.push('-af', filterComplex);
+      }
+
+      args.push(outputPath);
+
+      const ffmpeg = spawn('ffmpeg', args);
+
+      ffmpeg.on('close', (code) => {
+        if (code === 0) {
+          Logger.debug('FFmpeg processing completed');
+          resolve();
+        } else {
+          Logger.error(`FFmpeg exited with code ${code}`);
+          reject(new Error(`FFmpeg failed with exit code ${code}`));
+        }
+      });
+
+      ffmpeg.stderr.on('data', (data) => {
+        Logger.debug(`ffmpeg: ${data}`);
+      });
+
+      ffmpeg.on('error', (err) => {
+        Logger.error(`Failed to start FFmpeg: ${err.message}`);
+        reject(err);
+      });
+    });
+  }
+}

package/src/commands/generate.ts

@@ -0,0 +1,144 @@
+import { writeFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import ora from 'ora';
+import {
+  DEFAULT_AUDIO_PARAMS,
+  AUDIO_PARAM_RANGES,
+  AudioParameters,
+  ExitCode,
+} from '../config/defaults.js';
+import { FileReader } from '../utils/file-reader.js';
+import { Logger } from '../utils/logger.js';
+import { EngineFactory, EngineType } from '../engines/factory.js';
+import { AudioProcessor } from '../audio/processor.js';
+
+interface GenerateOptions {
+  text?: string;
+  file?: string;
+  engine?: EngineType;
+  voiceId?: string;
+  output?: string;
+  speed?: number;
+  pitch?: number;
+  volume?: number;
+  emphasis?: number;
+  reverb?: number;
+  echo?: number;
+  compression?: number;
+  pause?: number;
+}
+
+function validateParams(params: Partial<AudioParameters>): AudioParameters {
+  // Filter out undefined values to preserve defaults
+  const definedParams = Object.fromEntries(
+    Object.entries(params).filter(([, v]) => v !== undefined)
+  );
+
+  const validated = { ...DEFAULT_AUDIO_PARAMS, ...definedParams };
+
+  Object.entries(AUDIO_PARAM_RANGES).forEach(([key, range]) => {
+    const param = key as keyof AudioParameters;
+    const value = validated[param];
+    if (typeof value === 'number') {
+      validated[param] = Math.max(range.min, Math.min(range.max, value));
+    }
+  });
+
+  return validated;
+}
+
+export async function generateCommand(options: GenerateOptions): Promise<void> {
+  const spinner = ora();
+
+  try {
+    if (!options.text && !options.file) {
+      Logger.error('Please provide either --text or --file');
+      process.exit(ExitCode.INVALID_PARAMS);
+    }
+
+    if (options.text && options.file) {
+      Logger.error('Please provide either --text or --file, not both');
+      process.exit(ExitCode.INVALID_PARAMS);
+    }
+
+    let text: string;
+    if (options.file) {
+      spinner.start('Reading file...');
+      text = FileReader.readTextFile(options.file);
+      spinner.succeed('File read successfully');
+    } else {
+      text = options.text!;
+    }
+
+    const engineType = options.engine || 'system';
+    spinner.start(`Initializing ${engineType} TTS engine...`);
+    const engine = await EngineFactory.create(engineType, {
+      piperPath: process.env.MIA_NARRATIVE_PIPER_PATH,
+      modelPath: process.env.MIA_NARRATIVE_PIPER_MODEL,
+    });
+    spinner.succeed('TTS engine ready');
+
+    if (!(await engine.isAvailable())) {
+      Logger.error(
+        `${engine.getName()} engine not available. Please check your configuration.`
+      );
+      process.exit(ExitCode.TTS_ENGINE_ERROR);
+    }
+
+    const voices = await engine.getVoices();
+    const voiceId = options.voiceId || voices[0]?.id;
+
+    if (!voiceId) {
+        Logger.error(`No voices available for the ${engineType} engine.`);
+        process.exit(ExitCode.INVALID_PARAMS);
+    }
+
+    Logger.info(`Using voice: ${voiceId}`);
+
+    const audioParams = validateParams({
+      speed: options.speed,
+      pitch: options.pitch,
+      volume: options.volume,
+      emphasis: options.emphasis,
+      reverb: options.reverb,
+      echo: options.echo,
+      compression: options.compression,
+      pauseLength: options.pause,
+    });
+
+    spinner.start('Generating audio...');
+    const rawAudioBuffer = await engine.generateAudio({
+      text,
+      voiceId,
+      parameters: audioParams,
+    });
+    spinner.succeed('Audio generated');
+
+    spinner.start('Applying audio effects...');
+    const tempAudioPath = join(tmpdir(), `temp-audio-${Date.now()}.wav`);
+    writeFileSync(tempAudioPath, rawAudioBuffer);
+
+    const outputPath = options.output || 'output.mp3';
+
+    await AudioProcessor.processAudio(tempAudioPath, outputPath, audioParams);
+    spinner.succeed('Audio effects applied');
+
+    try {
+      unlinkSync(tempAudioPath);
+      Logger.debug(`Cleaned up temporary file: ${tempAudioPath}`);
+    } catch (err) {
+      // ignore
+    }
+
+    Logger.success(`Audio generated: ${outputPath}`);
+  } catch (error) {
+    spinner.fail();
+    if (error instanceof Error) {
+      Logger.error(error.message);
+    } else {
+      Logger.error('Unknown error occurred');
+    }
+    process.exit(ExitCode.GENERAL_ERROR);
+  }
+}

package/src/commands/voices.ts

@@ -0,0 +1,68 @@
+import { Logger } from '../utils/logger.js';
+import { EngineFactory, EngineType } from '../engines/factory.js';
+import ora from 'ora';
+import { ExitCode } from '../config/defaults.js';
+
+interface VoicesListOptions {
+  engine?: EngineType;
+  format?: 'json' | 'table' | 'list';
+}
+
+export async function voicesCommand(options: VoicesListOptions): Promise<void> {
+  const spinner = ora();
+  try {
+    const engineType = options.engine || 'system';
+    spinner.start(`Initializing ${engineType} TTS engine...`);
+    const engine = await EngineFactory.create(engineType, {
+      piperPath: process.env.MIA_NARRATIVE_PIPER_PATH,
+      modelPath: process.env.MIA_NARRATIVE_PIPER_MODEL,
+    });
+    spinner.succeed('TTS engine ready');
+
+    spinner.start('Fetching voices...');
+    const voices = await engine.getVoices();
+    spinner.succeed('Voices fetched');
+
+    if (voices.length === 0) {
+      Logger.warn(`No voices found for the ${engineType} engine.`);
+      return;
+    }
+
+    const format = options.format || 'table';
+
+    if (format === 'json') {
+      Logger.log(JSON.stringify(voices, null, 2));
+    } else if (format === 'list') {
+      voices.forEach((voice) => {
+        Logger.log(voice.id);
+      });
+    } else {
+      // Table format
+      Logger.log('');
+      Logger.log(`Available Voices for ${engineType}:`);
+      Logger.log('─'.repeat(80));
+
+      const idHeader = 'ID'.padEnd(30);
+      const nameHeader = 'Name';
+      Logger.log(`  ${idHeader}${nameHeader}`);
+      Logger.log('─'.repeat(80));
+
+      voices.forEach((voice) => {
+        const idStr = (voice.id || 'unknown').padEnd(30);
+        const nameStr = voice.name || 'Unknown';
+        Logger.log(`  ${idStr}${nameStr}`);
+      });
+
+      Logger.log('─'.repeat(80));
+      Logger.log('');
+    }
+  } catch (error) {
+    spinner.fail();
+    if (error instanceof Error) {
+      Logger.error(error.message);
+    } else {
+      Logger.error('Unknown error occurred');
+    }
+    process.exit(ExitCode.GENERAL_ERROR);
+  }
+}

package/src/config/defaults.ts

@@ -0,0 +1,41 @@
+export interface AudioParameters {
+  speed: number;
+  pitch: number;
+  volume: number;
+  emphasis: number;
+  reverb: number;
+  echo: number;
+  compression: number;
+  pauseLength: number;
+}
+
+export const DEFAULT_AUDIO_PARAMS: AudioParameters = {
+  speed: 1.0,
+  pitch: 1.0,
+  volume: 0.8,
+  emphasis: 0.5,
+  reverb: 0.2,
+  echo: 0.1,
+  compression: 0.3,
+  pauseLength: 0.5,
+};
+
+export const AUDIO_PARAM_RANGES = {
+  speed: { min: 0.5, max: 2.0 },
+  pitch: { min: 0.5, max: 2.0 },
+  volume: { min: 0.0, max: 1.0 },
+  emphasis: { min: 0.0, max: 1.0 },
+  reverb: { min: 0.0, max: 1.0 },
+  echo: { min: 0.1, max: 2.0 },
+  compression: { min: 0.0, max: 1.0 },
+  pauseLength: { min: 0.1, max: 2.0 },
+};
+
+export enum ExitCode {
+  SUCCESS = 0,
+  GENERAL_ERROR = 1,
+  INVALID_PARAMS = 2,
+  CONFIG_ERROR = 3,
+  TTS_ENGINE_ERROR = 4,
+  OUTPUT_ERROR = 5,
+}

package/src/config/voices.ts

@@ -0,0 +1,89 @@
+export interface VoiceProfile {
+  id: string;
+  name: string;
+  gender: "male" | "female" | "neutral";
+  style: string;
+  description: string;
+  piperModel: string;
+}
+
+export const VOICE_PROFILES: Record<string, VoiceProfile> = {
+  "mia-default": {
+    id: "mia-default",
+    name: "Mia",
+    gender: "female",
+    style: "professional",
+    description: "Professional narrator for expert technical content",
+    piperModel: `${process.env.HOME}/.local/share/piper-tts/en_US-lessac-medium.onnx`,
+  },
+  "miette-default": {
+    id: "miette-default",
+    name: "Miette",
+    gender: "female",
+    style: "conversational",
+    description: "Friendly conversational narrator",
+    piperModel: "en_US-amy-medium",
+  },
+  "seraphine-default": {
+    id: "seraphine-default",
+    name: "Seraphine",
+    gender: "female",
+    style: "narrative",
+    description: "Expressive narrative and storytelling",
+    piperModel: "en_US-libritts-high",
+  },
+  "jeremy-default": {
+    id: "jeremy-default",
+    name: "Jeremy",
+    gender: "male",
+    style: "professional",
+    description: "Professional male narrator",
+    piperModel: "en_US-ryan-medium",
+  },
+  "resonova-default": {
+    id: "resonova-default",
+    name: "ResoNova",
+    gender: "neutral",
+    style: "expressive",
+    description: "Varied and experimental voice",
+    piperModel: "en_US-hfc-female",
+  },
+  "zephyr-default": {
+    id: "zephyr-default",
+    name: "Zephyr",
+    gender: "neutral",
+    style: "narrative",
+    description: "Contemplative nature and narrative voice",
+    piperModel: "en_US-kusal-medium",
+  },
+  "echo-default": {
+    id: "echo-default",
+    name: "Echo",
+    gender: "female",
+    style: "expressive",
+    description: "Expressive character and dialogue voice",
+    piperModel: "en_US-libritts-high",
+  },
+  "atlas-default": {
+    id: "atlas-default",
+    name: "Atlas",
+    gender: "male",
+    style: "conversational",
+    description: "Casual and approachable male voice",
+    piperModel: "en_US-ryan-medium",
+  },
+};
+
+export function getVoiceProfile(id: string): VoiceProfile | undefined {
+  return VOICE_PROFILES[id];
+}
+
+export function listVoices(
+  filter?: { gender?: string; style?: string }
+): VoiceProfile[] {
+  return Object.values(VOICE_PROFILES).filter((voice) => {
+    if (filter?.gender && voice.gender !== filter.gender) return false;
+    if (filter?.style && voice.style !== filter.style) return false;
+    return true;
+  });
+}

package/src/engines/ElevenLabsEngine.ts

@@ -0,0 +1,81 @@
+import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
+import { TTSEngine, GenerateAudioOptions, Voice, TTSEngineConfig } from './base.js';
+import { Logger } from '../utils/logger.js';
+import { Readable } from 'stream';
+
+export class ElevenLabsEngine extends TTSEngine {
+  private client: ElevenLabsClient | undefined;
+
+  async initialize(config: TTSEngineConfig): Promise<void> {
+    const apiKey = config.apiKey || process.env.ELEVENLABS_API_KEY;
+    if (!apiKey) {
+      throw new Error('ElevenLabs API key not provided. Please set the ELEVENLABS_API_KEY environment variable or provide it in the config.');
+    }
+    this.client = new ElevenLabsClient({ apiKey });
+  }
+
+  async generateAudio(options: GenerateAudioOptions): Promise<Buffer> {
+    if (!this.client) {
+      throw new Error('ElevenLabs engine not initialized.');
+    }
+
+    const { text, voiceId } = options;
+    const audioStream = await this.client.textToSpeech.convert(voiceId, {
+      text,
+      modelId: 'eleven_multilingual_v2',
+    });
+
+    // Handle multiple response types from ElevenLabs API
+    try {
+      if (audioStream instanceof Readable) {
+        const chunks: Buffer[] = [];
+        for await (const chunk of audioStream) {
+          chunks.push(Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+      } else if (Buffer.isBuffer(audioStream)) {
+        return audioStream;
+      } else if (audioStream && typeof audioStream === 'object' && Symbol.asyncIterator in audioStream) {
+        // Handle async iterable streams
+        const chunks: Buffer[] = [];
+        for await (const chunk of audioStream as any) {
+          if (Buffer.isBuffer(chunk)) {
+            chunks.push(chunk);
+          } else if (chunk instanceof Uint8Array) {
+            chunks.push(Buffer.from(chunk));
+          } else {
+            chunks.push(Buffer.from(chunk));
+          }
+        }
+        return Buffer.concat(chunks);
+      } else {
+        // Fallback: try to convert to Buffer
+        return Buffer.from(audioStream as any);
+      }
+    } catch (error) {
+      throw new Error(`Failed to process ElevenLabs audio response: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  async getVoices(): Promise<Voice[]> {
+    if (!this.client) {
+      throw new Error('ElevenLabs engine not initialized.');
+    }
+    const availableVoices = await this.client.voices.getAll();
+    return availableVoices.voices.map((v: any) => {
+      const voiceId = v.voice_id || (v as any).voiceId || v.id;
+      return {
+        id: voiceId,
+        name: `${v.name}`,
+      };
+    });
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return !!(process.env.ELEVENLABS_API_KEY);
+  }
+
+  getName(): string {
+    return 'elevenlabs';
+  }
+}

package/src/engines/SystemTtsEngine.ts

@@ -0,0 +1,61 @@
+import { TTSEngine, GenerateAudioOptions, Voice, TTSEngineConfig } from './base.js';
+import { AudioParameters } from '../config/defaults.js';
+import say from 'say';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { unlinkSync, readFileSync } from 'fs';
+import { Logger } from '../utils/logger.js';
+
+export class SystemTtsEngine extends TTSEngine {
+  async initialize(config: TTSEngineConfig): Promise<void> {
+    // No initialization needed for system TTS
+  }
+
+  async generateAudio(options: GenerateAudioOptions): Promise<Buffer> {
+    const { text, voiceId, parameters } = options;
+    const tempDir = tmpdir();
+    const uid = randomUUID();
+    const audioFile = join(tempDir, `mia-narrative-output-${uid}.wav`);
+
+    return new Promise((resolve, reject) => {
+      say.export(text, voiceId, parameters.speed, audioFile, (err) => {
+        if (err) {
+          Logger.error(`System TTS error: ${err}`);
+          return reject(new Error(err));
+        }
+        try {
+          const audioBuffer = readFileSync(audioFile);
+          unlinkSync(audioFile); // Clean up the temp file
+          resolve(audioBuffer);
+        } catch (readErr: unknown) {
+          if (readErr instanceof Error) {
+            Logger.error(`Error processing system TTS audio file: ${readErr.message}`);
+          }
+          reject(readErr);
+        }
+      });
+    });
+  }
+
+  async getVoices(): Promise<Voice[]> {
+    return new Promise((resolve, reject) => {
+      say.getInstalledVoices(((err: string | null, voices: string[]) => {
+        if (err) {
+          return reject(new Error(err || 'Failed to get voices'));
+        }
+        resolve((voices || []).map((v: string) => ({ id: v, name: v })));
+      }) as any);
+    });
+  }
+
+  async isAvailable(): Promise<boolean> {
+    // The 'say' package should work on most systems with built-in TTS.
+    // A more robust check could be added here if needed.
+    return true;
+  }
+
+  getName(): string {
+    return 'system';
+  }
+}

package/src/engines/base.ts

@@ -0,0 +1,26 @@
+import { AudioParameters } from '../config/defaults.js';
+
+export interface TTSEngineConfig {
+  apiKey?: string;
+  piperPath?: string;
+  modelPath?: string;
+}
+
+export interface Voice {
+  id: string;
+  name: string;
+}
+
+export interface GenerateAudioOptions {
+  text: string;
+  voiceId: string;
+  parameters: AudioParameters;
+}
+
+export abstract class TTSEngine {
+  abstract initialize(config: TTSEngineConfig): Promise<void>;
+  abstract generateAudio(options: GenerateAudioOptions): Promise<Buffer>;
+  abstract getVoices(): Promise<Voice[]>;
+  abstract isAvailable(): Promise<boolean>;
+  abstract getName(): string;
+}

package/src/engines/factory.ts

@@ -0,0 +1,28 @@
+import { TTSEngine, TTSEngineConfig } from './base.js';
+import { PiperEngine } from './piper.js';
+import { SystemTtsEngine } from './SystemTtsEngine.js';
+import { ElevenLabsEngine } from './ElevenLabsEngine.js';
+
+export type EngineType = 'piper' | 'system' | 'elevenlabs';
+
+const engineMap: Record<EngineType, new () => TTSEngine> = {
+  piper: PiperEngine,
+  system: SystemTtsEngine,
+  elevenlabs: ElevenLabsEngine,
+};
+
+export class EngineFactory {
+  static async create(
+    engineType: EngineType,
+    config: TTSEngineConfig = {}
+  ): Promise<TTSEngine> {
+    const EngineClass = engineMap[engineType];
+    if (!EngineClass) {
+      throw new Error(`Unknown engine type: ${engineType}`);
+    }
+
+    const engine = new EngineClass();
+    await engine.initialize(config);
+    return engine;
+  }
+}