claude-phone-local 2.0.0

package/voice-app/lib/sip-handler.js

@@ -0,0 +1,490 @@
+/**
+ * SIP Call Handler with Conversation Loop
+ * v12: Device registry integration with proper method names
+ */
+
+const { setTimeout: sleep } = require('node:timers/promises');
+
+// FreeSWITCH (a separate container) fetches/connects to these - must be the
+// voice-app container's address, not FreeSWITCH's own loopback.
+const AUDIO_BASE_URL = process.env.AUDIO_BASE_URL || 'http://voice-app:3000';
+const AUDIO_WS_HOST = new URL(AUDIO_BASE_URL).hostname;
+
+// Audio cue URLs
+const READY_BEEP_URL = `${AUDIO_BASE_URL}/static/ready-beep.wav`;
+const GOTIT_BEEP_URL = `${AUDIO_BASE_URL}/static/gotit-beep.wav`;
+const HOLD_MUSIC_URL = `${AUDIO_BASE_URL}/static/hold-music.wav`;
+
+// Default voice ID (Morpheus)
+const DEFAULT_VOICE_ID = 'JAgnJveGGUh4qy4kh6dF';
+
+// Whisper language code -> Piper voice installed in tts-local/voices/.
+// Whisper detects the caller's language per utterance and we answer in the
+// same one. Override/extend with LANG_VOICE_MAP in .env as JSON.
+const DEFAULT_LANG_VOICES = {
+  en: 'en_US-lessac-medium',
+  hi: 'hi_IN-priyamvada-medium',
+  mr: 'mr_IN-google-medium'
+};
+
+let LANG_VOICES = DEFAULT_LANG_VOICES;
+if (process.env.LANG_VOICE_MAP) {
+  try {
+    LANG_VOICES = Object.assign({}, DEFAULT_LANG_VOICES, JSON.parse(process.env.LANG_VOICE_MAP));
+  } catch (e) {
+    console.log('[' + new Date().toISOString() + '] LANG: bad LANG_VOICE_MAP JSON, using defaults');
+  }
+}
+
+// Languages we will actually answer in. Anything Whisper detects outside this
+// set falls back to the device's own voice, so a misdetection can't leave us
+// with no installed model.
+const SUPPORTED_LANGS = (process.env.SUPPORTED_LANGS || 'en,hi,mr')
+  .split(',').map(function (x) { return x.trim(); }).filter(Boolean);
+
+function voiceForLanguage(lang, fallbackVoice) {
+  if (!lang) return fallbackVoice;
+  if (SUPPORTED_LANGS.indexOf(lang) === -1) return fallbackVoice;
+  return LANG_VOICES[lang] || fallbackVoice;
+}
+
+// Claude Code-style thinking phrases
+const THINKING_PHRASES = [
+  "Let me check that for you.",
+  "One moment.",
+  "Just a second.",
+  "Looking into it now.",
+  "Give me a moment.",
+  "Checking on that.",
+  "Hang on, almost there.",
+  "Still working on it.",
+  "Nearly done.",
+  "Bear with me a moment.",
+];
+
+// Said only while the caller is already waiting, so they never hear the same
+// line twice in a row within one wait.
+const WAITING_PHRASES = [
+  "Still working on this.",
+  "Almost there.",
+  "Just a little longer.",
+  "Nearly finished.",
+  "Hang in there, still going.",
+  "Won't be much longer.",
+];
+
+function getRandomThinkingPhrase() {
+  return THINKING_PHRASES[Math.floor(Math.random() * THINKING_PHRASES.length)];
+}
+
+function extractCallerId(req) {
+  var from = req.get("From") || "";
+  var match = from.match(/sip:([+\d]+)@/);
+  if (match) return match[1];
+  var numMatch = from.match(/<sip:(\d+)@/);
+  if (numMatch) return numMatch[1];
+  return "unknown";
+}
+
+/**
+ * Extract dialed extension from SIP To header
+ */
+function extractDialedExtension(req) {
+  var to = req.get("To") || "";
+  var match = to.match(/sip:(\d+)@/);
+  if (match) {
+    return match[1];
+  }
+  return null;
+}
+
+function isGoodbye(transcript) {
+  const lower = transcript.toLowerCase().trim();
+  const goodbyePhrases = [
+    // English
+    'goodbye', 'good bye', 'bye', 'bye bye', 'hang up', 'end call', 'end the call',
+    'close the call', 'cut the call', 'disconnect', "that's all", 'thats all',
+    'thank you bye', 'talk later',
+    // Hindi / Marathi (Devanagari + common romanisations)
+    'अलविदा', 'नमस्ते', 'बाय', 'फोन बंद करो', 'कॉल बंद करो', 'बंद करो',
+    'ठेवतो', 'ठेवते', 'फोन ठेव', 'बंद कर',
+    'alvida', 'phone band karo', 'call band karo', 'band karo', 'thevto'
+  ];
+  return goodbyePhrases.some(function(phrase) {
+    return lower === phrase || lower.includes(' ' + phrase) ||
+           lower.startsWith(phrase + ' ') || lower.endsWith(' ' + phrase);
+  });
+}
+
+/**
+ * Extract voice-friendly line from Claude's response
+ * Priority: VOICE_RESPONSE > CUSTOM COMPLETED > COMPLETED > first sentence
+ */
+function extractVoiceLine(response) {
+  // Priority 1: VOICE_RESPONSE (new format)
+  var voiceMatch = response.match(/🗣️\s*VOICE_RESPONSE:\s*([^\n]+)/im);
+  if (voiceMatch) {
+    var text = voiceMatch[1].trim().replace(/\*+/g, '').replace(/\[.*?\]/g, '').trim();
+    if (text && text.split(/\s+/).length <= 60) {
+      return text;
+    }
+  }
+
+  // Priority 2: CUSTOM COMPLETED
+  var customMatch = response.match(/🗣️\s*CUSTOM\s+COMPLETED:\s*(.+?)(?:\n|$)/im);
+  if (customMatch) {
+    text = customMatch[1].trim().replace(/\*+/g, '').replace(/\[.*?\]/g, '').trim();
+    if (text && text.split(/\s+/).length <= 50) {
+      return text;
+    }
+  }
+
+  // Priority 3: COMPLETED
+  var completedMatch = response.match(/🎯\s*COMPLETED:\s*(.+?)(?:\n|$)/im);
+  if (completedMatch) {
+    return completedMatch[1].trim().replace(/\*+/g, '').replace(/\[.*?\]/g, '').trim();
+  }
+
+  // Priority 4: First sentence
+  var firstSentence = response.split(/[.!?]/)[0];
+  if (firstSentence && firstSentence.length < 500) {
+    return firstSentence.trim();
+  }
+
+  return response.substring(0, 500).trim();
+}
+
+/**
+ * Play a clip the caller is allowed to interrupt.
+ *
+ * FreeSWITCH plays to completion unless told otherwise, so to support barge-in
+ * we arm the detector, then issue uuid_break the moment the caller starts
+ * talking. Returns true if the caller cut in, so the loop can skip straight to
+ * listening instead of finishing what it was saying.
+ */
+async function playInterruptible(endpoint, session, url) {
+  if (!session) {
+    await endpoint.play(url);
+    return false;
+  }
+
+  let barged = false;
+  const onBarge = function () {
+    barged = true;
+    // uuid_break stops the current playback on this leg immediately.
+    endpoint.api('uuid_break', endpoint.uuid).catch(function () {});
+  };
+
+  session.once('barge-in', onBarge);
+  session.setBargeInEnabled(true);
+  try {
+    await endpoint.play(url);
+  } finally {
+    session.setBargeInEnabled(false);
+    session.removeListener('barge-in', onBarge);
+  }
+  if (barged) {
+    console.log('[' + new Date().toISOString() + '] BARGE-IN: caller interrupted, listening now');
+  }
+  return barged;
+}
+
+/**
+ * Main conversation loop
+ * @param {Object} deviceConfig - Device configuration (name, prompt, voiceId, etc.) or null for default
+ */
+async function conversationLoop(endpoint, dialog, callUuid, options, deviceConfig) {
+  const { ttsService, whisperClient, claudeBridge, wsPort, audioForkServer } = options;
+
+  let session = null;
+  let forkRunning = false;
+
+  // Get device-specific settings
+  const deviceName = deviceConfig ? deviceConfig.name : 'Morpheus';
+  const devicePrompt = deviceConfig ? deviceConfig.prompt : null;
+  // Local mode: device.voice is a Piper voice name (null falls back to PIPER_VOICE env).
+  // Cloud mode: device.voiceId is an ElevenLabs voice ID (falls back to DEFAULT_VOICE_ID).
+  const voiceId = ttsService.mode === 'cloud'
+    ? ((deviceConfig && deviceConfig.voiceId) ? deviceConfig.voiceId : DEFAULT_VOICE_ID)
+    : ((deviceConfig && deviceConfig.voice) ? deviceConfig.voice : null);
+  // Voice used for the current turn - starts as the device voice and follows
+  // the caller's detected language from the first utterance onward.
+  let turnVoice = ttsService.mode === 'cloud'
+    ? (deviceConfig && deviceConfig.voiceId ? deviceConfig.voiceId : DEFAULT_VOICE_ID)
+    : (deviceConfig && deviceConfig.voice ? deviceConfig.voice : null);
+
+  const greeting = deviceConfig && deviceConfig.name !== 'Morpheus'
+    ? "Hello! I'm " + deviceConfig.name + ". How can I help you today?"
+    : "Hello! I'm your server. How can I help you today?";
+
+  try {
+    console.log('[' + new Date().toISOString() + '] CONVERSATION Starting (session: ' + callUuid + ', device: ' + deviceName + ', voice: ' + voiceId + ')...');
+
+    // Play device-specific greeting with device voice BEFORE starting audio fork
+    console.log('[' + new Date().toISOString() + '] Generating greeting...');
+    const greetingUrl = await ttsService.generateSpeech(greeting, voiceId);
+    console.log('[' + new Date().toISOString() + '] Playing greeting: ' + greetingUrl);
+    await endpoint.play(greetingUrl);
+    console.log('[' + new Date().toISOString() + '] Greeting played successfully');
+
+    // Start fork for entire call AFTER greeting
+    const wsUrl = 'ws://' + AUDIO_WS_HOST + ':' + wsPort + '/' + encodeURIComponent(callUuid);
+    const sessionPromise = audioForkServer.expectSession(callUuid, { timeoutMs: 10000 });
+
+    await endpoint.forkAudioStart({
+      wsUrl: wsUrl,
+      mixType: 'mono',
+      sampling: '16k'
+    });
+    forkRunning = true;
+
+    session = await sessionPromise;
+    console.log('[' + new Date().toISOString() + '] AUDIO Fork connected');
+
+    // Main conversation loop
+    let turnCount = 0;
+    const MAX_TURNS = 20;
+
+    while (turnCount < MAX_TURNS) {
+      turnCount++;
+      console.log('[' + new Date().toISOString() + '] CONVERSATION Turn ' + turnCount + '/' + MAX_TURNS);
+
+      // READY BEEP
+      try {
+        await endpoint.play(READY_BEEP_URL);
+      } catch (e) {
+        console.log('[' + new Date().toISOString() + '] BEEP: Ready beep failed, continuing');
+      }
+
+      session.setCaptureEnabled(true);
+      console.log('[' + new Date().toISOString() + '] LISTEN Waiting for speech...');
+
+      let utterance = null;
+      try {
+        utterance = await session.waitForUtterance({ timeoutMs: 30000 });
+        console.log('[' + new Date().toISOString() + '] LISTEN Got: ' + utterance.audio.length + ' bytes');
+      } catch (err) {
+        console.log('[' + new Date().toISOString() + '] LISTEN Timeout: ' + err.message);
+      }
+
+      session.setCaptureEnabled(false);
+
+      if (!utterance) {
+        const promptUrl = await ttsService.generateSpeech("I didn't hear anything. Are you still there?", turnVoice);
+        await endpoint.play(promptUrl);
+        continue;
+      }
+
+      // GOT-IT BEEP
+      try {
+        await endpoint.play(GOTIT_BEEP_URL);
+      } catch (e) {
+        console.log('[' + new Date().toISOString() + '] BEEP: Got-it beep failed, continuing');
+      }
+
+      // Transcribe (language auto-detected unless STT_LANGUAGE pins one)
+      const sttResult = await whisperClient.transcribeDetailed(utterance.audio, {
+        format: 'pcm',
+        sampleRate: 16000,
+        language: (deviceConfig && deviceConfig.language) || process.env.STT_LANGUAGE || 'auto'
+      });
+      const transcript = sttResult.text;
+      const detectedLang = sttResult.language;
+
+      // Answer in whatever language the caller just used.
+      turnVoice = voiceForLanguage(detectedLang, voiceId);
+      console.log('[' + new Date().toISOString() + '] WHISPER [' + (detectedLang || '?') +
+        ' -> voice ' + turnVoice + ']: "' + transcript + '"');
+
+      if (!transcript || transcript.trim().length < 2) {
+        const clarifyUrl = await ttsService.generateSpeech("Sorry, I didn't catch that. Could you repeat?", turnVoice);
+        await endpoint.play(clarifyUrl);
+        continue;
+      }
+
+      if (isGoodbye(transcript)) {
+        const byeUrl = await ttsService.generateSpeech("Goodbye! Call again anytime.", turnVoice);
+        await endpoint.play(byeUrl);
+        break;
+      }
+
+      // THINKING FEEDBACK
+      const thinkingPhrase = getRandomThinkingPhrase();
+      console.log('[' + new Date().toISOString() + '] THINKING: "' + thinkingPhrase + '"');
+      const thinkingUrl = await ttsService.generateSpeech(thinkingPhrase, turnVoice);
+      await endpoint.play(thinkingUrl);
+
+      // hears nothing for the whole query and hangs up.
+      // Fill the whole wait, not just parts of it. The gap alternates between a
+      // soft music bed and a spoken line, so the line never goes dead. Clips play
+      // to completion - one endpoint cannot layer two streams - and every Nth
+      // round is speech instead of music.
+      let waiting = true;
+      const SPEAK_EVERY = parseInt(process.env.KEEPALIVE_SPEAK_EVERY || '3', 10);
+      const keepAlive = (async function () {
+        let round = 0;
+        while (waiting) {
+          round++;
+          try {
+            const clipUrl = (round % SPEAK_EVERY === 0)
+              ? await ttsService.generateSpeech(getRandomWaitingPhrase(), turnVoice)
+              : HOLD_MUSIC_URL;
+            if (!waiting) break;
+            // Caller can cut through the hold music / filler to add something.
+            if (await playInterruptible(endpoint, session, clipUrl)) {
+              waiting = false;
+              break;
+            }
+          } catch (e) {
+            console.log('[' + new Date().toISOString() + '] KEEPALIVE: stopped (' + e.message + ')');
+            return;
+          }
+        }
+      })();
+
+      // Query Claude with device-specific prompt
+      console.log('[' + new Date().toISOString() + '] CLAUDE Querying (device: ' + deviceName + ')...');
+      let claudeResponse;
+      try {
+        claudeResponse = await claudeBridge.query(
+          transcript,
+          { callId: callUuid, devicePrompt: devicePrompt }
+        );
+      } finally {
+        waiting = false;
+        try { await keepAlive; } catch (e) {}
+      }
+
+      console.log('[' + new Date().toISOString() + '] CLAUDE Response received');
+
+      // Extract and play voice line with device voice
+      const voiceLine = extractVoiceLine(claudeResponse);
+      console.log('[' + new Date().toISOString() + '] VOICE: "' + voiceLine + '"');
+
+      const responseUrl = await ttsService.generateSpeech(voiceLine, turnVoice);
+      // Long answers are the usual thing people want to interrupt.
+      await playInterruptible(endpoint, session, responseUrl);
+
+      console.log('[' + new Date().toISOString() + '] CONVERSATION Turn ' + turnCount + ' complete');
+    }
+
+    if (turnCount >= MAX_TURNS) {
+      const maxUrl = await ttsService.generateSpeech("We've been talking for a while. Goodbye!", turnVoice);
+      await endpoint.play(maxUrl);
+    }
+
+  } catch (error) {
+    console.error('[' + new Date().toISOString() + '] CONVERSATION Error:', error.message);
+    try {
+      if (session) session.setCaptureEnabled(false);
+      const errUrl = await ttsService.generateSpeech("Sorry, something went wrong.", voiceId);
+      await endpoint.play(errUrl);
+    } catch (e) {}
+  } finally {
+    console.log('[' + new Date().toISOString() + '] CONVERSATION Cleanup...');
+
+    try {
+      await claudeBridge.endSession(callUuid);
+    } catch (e) {}
+
+    if (forkRunning) {
+      try {
+        await endpoint.forkAudioStop();
+      } catch (e) {}
+    }
+
+    try { dialog.destroy(); } catch (e) {}
+  }
+}
+
+/**
+ * Strip video tracks from SDP (FreeSWITCH doesn't support H.261 and rejects with 488)
+ * Keeps only audio tracks to ensure codec negotiation succeeds
+ */
+function stripVideoFromSdp(sdp) {
+  if (!sdp) return sdp;
+
+  const lines = sdp.split('\r\n');
+  const result = [];
+  let inVideoSection = false;
+
+  for (const line of lines) {
+    // Check if we're entering a video media section
+    if (line.startsWith('m=video')) {
+      inVideoSection = true;
+      continue; // Skip the m=video line
+    }
+
+    // Check if we're entering a new media section (audio, etc.)
+    if (line.startsWith('m=') && !line.startsWith('m=video')) {
+      inVideoSection = false;
+    }
+
+    // Skip all lines in the video section
+    if (inVideoSection) {
+      continue;
+    }
+
+    result.push(line);
+  }
+
+  return result.join('\r\n');
+}
+
+/**
+ * Handle incoming SIP INVITE
+ */
+async function handleInvite(req, res, options) {
+  const { mediaServer, deviceRegistry } = options;
+
+  const callerId = extractCallerId(req);
+  const dialedExt = extractDialedExtension(req);
+
+  // Look up device config using deviceRegistry.get() (works with name OR extension)
+  let deviceConfig = null;
+  if (deviceRegistry && dialedExt) {
+    deviceConfig = deviceRegistry.get(dialedExt);
+    if (deviceConfig) {
+      console.log('[' + new Date().toISOString() + '] CALL Device matched: ' + deviceConfig.name + ' (ext ' + dialedExt + ')');
+    } else {
+      console.log('[' + new Date().toISOString() + '] CALL Unknown extension ' + dialedExt + ', using default');
+      deviceConfig = deviceRegistry.getDefault();
+    }
+  }
+
+  console.log('[' + new Date().toISOString() + '] CALL Incoming from: ' + callerId + ' to ext: ' + (dialedExt || 'unknown'));
+
+  try {
+    // Strip video from SDP to avoid FreeSWITCH 488 error with unsupported video codecs
+    const originalSdp = req.body;
+    const audioOnlySdp = stripVideoFromSdp(originalSdp);
+    if (originalSdp !== audioOnlySdp) {
+      console.log('[' + new Date().toISOString() + '] CALL Stripped video track from SDP');
+    }
+
+    const result = await mediaServer.connectCaller(req, res, { remoteSdp: audioOnlySdp });
+    const { endpoint, dialog } = result;
+    const callUuid = endpoint.uuid;
+
+    console.log('[' + new Date().toISOString() + '] CALL Connected: ' + callUuid);
+
+    dialog.on('destroy', function() {
+      console.log('[' + new Date().toISOString() + '] CALL Ended');
+      if (endpoint) endpoint.destroy().catch(function() {});
+    });
+
+    await conversationLoop(endpoint, dialog, callUuid, options, deviceConfig);
+    return { endpoint: endpoint, dialog: dialog, callerId: callerId, callUuid: callUuid };
+
+  } catch (error) {
+    console.error('[' + new Date().toISOString() + '] CALL Error:', error.message);
+    try { res.send(500); } catch (e) {}
+    throw error;
+  }
+}
+
+module.exports = {
+  handleInvite: handleInvite,
+  extractCallerId: extractCallerId,
+  extractDialedExtension: extractDialedExtension
+};

package/voice-app/lib/tts-service.js

@@ -0,0 +1,205 @@
+/**
+ * Text-to-Speech Service
+ *
+ * Default mode ("local"): sends text to the local Piper sidecar container
+ * (tts-local) and saves the returned WAV — no API key, fully offline.
+ *
+ * Optional mode ("cloud", set TTS_MODE=cloud): original ElevenLabs API
+ * behavior, preserved for anyone who still wants it.
+ */
+
+const axios = require('axios');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const logger = require('./logger');
+
+const TTS_MODE = (process.env.TTS_MODE || 'local').toLowerCase();
+const TTS_LOCAL_URL = process.env.TTS_LOCAL_URL || 'http://tts-local:9002';
+const PIPER_VOICE = process.env.PIPER_VOICE || 'en_US-lessac-medium';
+// Base URL other containers (FreeSWITCH) use to fetch generated audio back
+// from this voice-app container. Under Docker Desktop bridge networking
+// this must be the service name, not 127.0.0.1.
+const AUDIO_BASE_URL = process.env.AUDIO_BASE_URL || 'http://voice-app:3000';
+
+const ELEVENLABS_API_KEY = process.env.ELEVENLABS_API_KEY;
+const ELEVENLABS_API_URL = 'https://api.elevenlabs.io/v1';
+const DEFAULT_VOICE_ID = 'JAgnJveGGUh4qy4kh6dF';
+const MODEL_ID = 'eleven_turbo_v2';
+
+// Audio output directory (set via setAudioDir)
+let audioDir = path.join(__dirname, '../audio-temp');
+
+/**
+ * Set the audio output directory
+ * @param {string} dir - Absolute path to audio directory
+ */
+function setAudioDir(dir) {
+  audioDir = dir;
+  if (!fs.existsSync(audioDir)) {
+    fs.mkdirSync(audioDir, { recursive: true });
+    logger.info('Created audio directory', { path: audioDir });
+  }
+}
+
+function generateFilename(text, ext) {
+  const hash = crypto.createHash('md5').update(text).digest('hex').substring(0, 8);
+  const timestamp = Date.now();
+  return `tts-${timestamp}-${hash}.${ext}`;
+}
+
+/**
+ * Generate speech using the local Piper sidecar
+ * @param {string} text
+ * @param {string} voice - Piper voice name (falls back to PIPER_VOICE env)
+ * @returns {Promise<string>} HTTP URL to the generated WAV file
+ */
+async function generateSpeechLocal(text, voice) {
+  const startTime = Date.now();
+
+  logger.info('Generating speech with local Piper', { textLength: text.length, voice });
+
+  const response = await axios({
+    method: 'POST',
+    url: `${TTS_LOCAL_URL}/speak`,
+    headers: { 'Content-Type': 'application/json' },
+    data: { text, voice: voice || PIPER_VOICE },
+    responseType: 'arraybuffer',
+    timeout: 30000
+  });
+
+  const filename = generateFilename(text, 'wav');
+  const filepath = path.join(audioDir, filename);
+  fs.writeFileSync(filepath, response.data);
+
+  const latency = Date.now() - startTime;
+  logger.info('Speech generation successful (local)', {
+    filename, fileSize: response.data.length, latency, textLength: text.length
+  });
+
+  return `${AUDIO_BASE_URL}/audio-files/${filename}`;
+}
+
+/**
+ * Generate speech using ElevenLabs (cloud mode)
+ */
+async function generateSpeechCloud(text, voiceId = DEFAULT_VOICE_ID) {
+  const startTime = Date.now();
+
+  try {
+    if (!ELEVENLABS_API_KEY) {
+      throw new Error('ELEVENLABS_API_KEY environment variable not set');
+    }
+
+    logger.info('Generating speech with ElevenLabs', { textLength: text.length, voiceId, model: MODEL_ID });
+
+    const response = await axios({
+      method: 'POST',
+      url: `${ELEVENLABS_API_URL}/text-to-speech/${voiceId}`,
+      headers: {
+        'Accept': 'audio/mpeg',
+        'Content-Type': 'application/json',
+        'xi-api-key': ELEVENLABS_API_KEY
+      },
+      data: {
+        text,
+        model_id: MODEL_ID,
+        voice_settings: { stability: 0.5, similarity_boost: 0.75, style: 0.0, use_speaker_boost: true }
+      },
+      responseType: 'arraybuffer'
+    });
+
+    const filename = generateFilename(text, 'mp3');
+    const filepath = path.join(audioDir, filename);
+    fs.writeFileSync(filepath, response.data);
+
+    const latency = Date.now() - startTime;
+    logger.info('Speech generation successful (cloud)', {
+      filename, fileSize: response.data.length, latency, textLength: text.length
+    });
+
+    return `${AUDIO_BASE_URL}/audio-files/${filename}`;
+  } catch (error) {
+    const latency = Date.now() - startTime;
+    logger.error('Speech generation failed', {
+      error: error.message, latency, textLength: text?.length,
+      responseStatus: error.response?.status, responseData: error.response?.data?.toString()
+    });
+
+    if (error.response?.status === 401) throw new Error('ElevenLabs API authentication failed - check API key');
+    if (error.response?.status === 429) throw new Error('ElevenLabs API rate limit exceeded');
+    if (error.response?.status === 400) throw new Error('Invalid request to ElevenLabs API');
+    throw new Error(`TTS generation failed: ${error.message}`);
+  }
+}
+
+/**
+ * Convert text to speech (local Piper by default, ElevenLabs if TTS_MODE=cloud)
+ * @param {string} text
+ * @param {string} voiceId - Piper voice name (local) or ElevenLabs voice ID (cloud)
+ * @returns {Promise<string>} HTTP URL to audio file
+ */
+async function generateSpeech(text, voiceId) {
+  if (TTS_MODE === 'cloud') {
+    return generateSpeechCloud(text, voiceId || DEFAULT_VOICE_ID);
+  }
+  return generateSpeechLocal(text, voiceId);
+}
+
+/**
+ * Clean up old audio files (older than specified age)
+ */
+function cleanupOldFiles(maxAgeMs = 60 * 60 * 1000) {
+  try {
+    const now = Date.now();
+    const files = fs.readdirSync(audioDir);
+    let deletedCount = 0;
+    files.forEach(file => {
+      if (!file.startsWith('tts-') || !(file.endsWith('.mp3') || file.endsWith('.wav'))) return;
+      const filepath = path.join(audioDir, file);
+      const stats = fs.statSync(filepath);
+      if (now - stats.mtimeMs > maxAgeMs) {
+        fs.unlinkSync(filepath);
+        deletedCount++;
+      }
+    });
+    if (deletedCount > 0) logger.info('Cleaned up old audio files', { deletedCount });
+  } catch (error) {
+    logger.warn('Failed to cleanup old audio files', { error: error.message });
+  }
+}
+
+/**
+ * Get list of available voices
+ * @returns {Promise<Array>} local: Piper voices installed; cloud: ElevenLabs voices
+ */
+async function getAvailableVoices() {
+  if (TTS_MODE !== 'cloud') {
+    const response = await axios.get(`${TTS_LOCAL_URL}/voices`, { timeout: 5000 });
+    return response.data.voices || [];
+  }
+
+  if (!ELEVENLABS_API_KEY) {
+    throw new Error('ELEVENLABS_API_KEY environment variable not set');
+  }
+  const response = await axios({
+    method: 'GET',
+    url: `${ELEVENLABS_API_URL}/voices`,
+    headers: { 'xi-api-key': ELEVENLABS_API_KEY }
+  });
+  return response.data.voices;
+}
+
+// Initialize audio directory
+setAudioDir(audioDir);
+
+// Periodic cleanup (every 30 minutes)
+setInterval(() => cleanupOldFiles(), 30 * 60 * 1000);
+
+module.exports = {
+  generateSpeech,
+  setAudioDir,
+  cleanupOldFiles,
+  getAvailableVoices,
+  mode: TTS_MODE
+};