opencode-smart-voice-notify 1.3.0 → 1.3.1

package/README.md

@@ -1,11 +1,15 @@
-<!-- Dynamic Header -->
-<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=0:667eea,100:764ba2&height=120&section=header"/>
-
-# OpenCode Smart Voice Notify
-
-![Coverage](https://img.shields.io/badge/coverage-86.73%25-brightgreen)
-![Version](https://img.shields.io/badge/version-1.2.5-blue)
-![License](https://img.shields.io/badge/license-MIT-green)
+<!-- Dynamic Header -->
+<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=0:667eea,100:764ba2&height=120&section=header"/>
+
+# OpenCode Smart Voice Notify
+
+[![npm version](https://img.shields.io/npm/v/opencode-smart-voice-notify?color=blue&logo=npm)](https://www.npmjs.com/package/opencode-smart-voice-notify)
+[![npm downloads](https://img.shields.io/npm/dm/opencode-smart-voice-notify?color=blue&logo=npm)](https://www.npmjs.com/package/opencode-smart-voice-notify)
+[![GitHub release](https://img.shields.io/github/v/release/MasuRii/opencode-smart-voice-notify?logo=github)](https://github.com/MasuRii/opencode-smart-voice-notify/releases)
+[![CI](https://img.shields.io/github/actions/workflow/status/MasuRii/opencode-smart-voice-notify/test.yml?branch=master&logo=github&label=tests)](https://github.com/MasuRii/opencode-smart-voice-notify/actions/workflows/test.yml)
+[![License](https://img.shields.io/github/license/MasuRii/opencode-smart-voice-notify?color=green)](https://github.com/MasuRii/opencode-smart-voice-notify/blob/master/LICENSE)
+[![Node](https://img.shields.io/node/v/opencode-smart-voice-notify?color=brightgreen&logo=node.js)](https://nodejs.org)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?logo=windows-terminal)](https://github.com/MasuRii/opencode-smart-voice-notify#platform-support-matrix)
 
 
 > **Disclaimer**: This project is not built by the OpenCode team and is not affiliated with [OpenCode](https://opencode.ai) in any way. It is an independent community plugin.
@@ -17,14 +21,15 @@ A smart voice notification plugin for [OpenCode](https://opencode.ai) with **mul
 
 ## Features
 
-### Smart TTS Engine Selection
-The plugin automatically tries multiple TTS engines in order, falling back if one fails:
-
-1. **OpenAI-Compatible** (Cloud/Self-hosted) - Any OpenAI-compatible `/v1/audio/speech` endpoint (Kokoro, LocalAI, Coqui, AllTalk, OpenAI API, etc.)
-2. **ElevenLabs** (Online) - High-quality, anime-like voices with natural expression
-3. **Edge TTS** (Free) - Microsoft's neural voices, native Node.js implementation (no Python required)
-4. **Windows SAPI** (Offline) - Built-in Windows speech synthesis
-5. **Local Sound Files** (Fallback) - Plays bundled MP3 files if all TTS fails
+### Smart TTS Engine Selection
+The plugin automatically tries multiple TTS engines in order, falling back if one fails:
+
+1. **OpenAI-Compatible** (Cloud/Self-hosted) - Any OpenAI-compatible `/v1/audio/speech` endpoint (Kokoro, LocalAI, Coqui, AllTalk, OpenAI API, etc.)
+2. **ElevenLabs** (Online) - High-quality, anime-like voices with natural expression
+3. **Edge TTS** (Free) - Microsoft's neural voices via Python CLI (recommended) or native npm fallback
+4. **Windows SAPI** (Offline) - Built-in Windows speech synthesis
+5. **macOS Say** (Offline) - Built-in macOS speech synthesis
+6. **Local Sound Files** (Fallback) - Plays bundled MP3 files if all TTS fails
 
 ### Smart Notification System
 - **Sound-first mode**: Play a sound immediately, then speak a TTS reminder if user doesn't respond
@@ -313,16 +318,17 @@ You can replace individual sound files with entire "Sound Themes" (like the clas
 
 ### Platform Support Matrix
 
-| Feature | Windows | macOS | Linux |
-|---------|:---:|:---:|:---:|
-| **Sound Playback** | ✅ | ✅ | ✅ |
-| **TTS (Cloud/Edge)** | ✅ | ✅ | ✅ |
-| **TTS (Windows SAPI)** | ✅ | ❌ | ❌ |
-| **Desktop Notifications** | ✅ | ✅ | ✅ (req libnotify) |
-| **Focus Detection** | ❌ | ✅ | ❌ |
-| **Webhook Integration** | ✅ | ✅ | ✅ |
-| **Wake Monitor** | ✅ | ✅ | ✅ (X11/Gnome) |
-| **Volume Control** | ✅ | ✅ | ✅ (Pulse/ALSA) |
+| Feature | Windows | macOS | Linux |
+|---------|:---:|:---:|:---:|
+| **Sound Playback** | ✅ | ✅ | ✅ |
+| **TTS (Cloud/Edge)** | ✅ | ✅ | ✅ |
+| **TTS (Windows SAPI)** | ✅ | ❌ | ❌ |
+| **TTS (macOS Say)** | ❌ | ✅ | ❌ |
+| **Desktop Notifications** | ✅ | ✅ | ✅ (req libnotify) |
+| **Focus Detection** | ❌ | ✅ | ❌ |
+| **Webhook Integration** | ✅ | ✅ | ✅ |
+| **Wake Monitor** | ✅ | ✅ | ✅ (X11/Gnome) |
+| **Volume Control** | ✅ | ✅ | ✅ (Pulse/ALSA) |
 
 ### For OpenAI-Compatible TTS
 - Any server implementing the `/v1/audio/speech` endpoint
@@ -333,11 +339,18 @@ You can replace individual sound files with entire "Sound Themes" (like the clas
 - ElevenLabs API key (free tier: 10,000 characters/month)
 - Internet connection
 
-### For Edge TTS
-- Internet connection (No external dependencies required)
-
-### For Windows SAPI
-- Windows OS (uses built-in System.Speech)
+### For Edge TTS
+- Internet connection required
+- **Recommended**: Install Python edge-tts for best reliability: `pip install edge-tts`
+- **Fallback**: Works without Python (uses bundled npm package), but may be less reliable
+- If Edge TTS fails, automatically falls back to SAPI (Windows) or Say (macOS)
+
+### For Windows SAPI
+- Windows OS (uses built-in System.Speech)
+
+### For macOS Say
+- macOS (uses built-in `say` command)
+- Serves as fallback when other TTS engines fail
 
 ### For Desktop Notifications
 - **Windows**: Built-in (uses Toast notifications)
@@ -442,19 +455,131 @@ OpenCode does not automatically update plugins. To update to the latest version:
 ```bash
 # Clear the cached plugin
 rm -rf ~/.cache/opencode/node_modules/opencode-smart-voice-notify
-
-# Run OpenCode to trigger a fresh install
-opencode
-```
-
-## License
-
-MIT
-
-## Support
-
-- Open an issue on [GitHub](https://github.com/MasuRii/opencode-smart-voice-notify/issues)
-- Check the [OpenCode docs](https://opencode.ai/docs/plugins)
-
-<!-- Dynamic Header -->
-<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=0:667eea,100:764ba2&height=120&section=header"/>
+
+# Run OpenCode to trigger a fresh install
+opencode
+```
+
+<!--
+LLM-AGENT-INSTRUCTIONS (Hidden from rendered markdown, visible to AI assistants scanning raw file)
+
+## LLM Instructions
+
+> This section provides structured guidance for AI assistants (Claude, GPT, Cursor, Copilot, etc.) helping users set up and configure this plugin.
+
+### Quick Setup (Execute These Steps)
+
+When a user asks you to set up this plugin, follow these steps:
+
+1. **Add plugin to OpenCode config** - Edit `~/.config/opencode/opencode.json`:
+   ```json
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugin": ["opencode-smart-voice-notify@latest"]
+   }
+   ```
+
+2. **Run OpenCode once** - This auto-generates the configuration file at `~/.config/opencode/smart-voice-notify.jsonc`
+
+3. **Configure based on user's TTS preference**:
+   - **Free/No API key**: Use Edge TTS (default, works out of box)
+   - **High quality**: Use ElevenLabs (requires API key)
+   - **Self-hosted**: Use OpenAI-compatible endpoint (Kokoro, LocalAI, etc.)
+   - **Offline Windows**: Use Windows SAPI
+   - **Offline macOS**: Use macOS Say (built-in fallback)
+
+### Configuration Tasks
+
+#### Task: Enable ElevenLabs TTS
+```jsonc
+// In ~/.config/opencode/smart-voice-notify.jsonc
+{
+  "ttsEngine": "elevenlabs",
+  "elevenLabsApiKey": "USER_API_KEY_HERE",
+  "elevenLabsVoiceId": "cgSgspJ2msm6clMCkdW9"
+}
+```
+**Note**: User must get API key from https://elevenlabs.io/app/settings/api-keys
+
+#### Task: Enable OpenAI-Compatible TTS (Kokoro, LocalAI, etc.)
+```jsonc
+{
+  "ttsEngine": "openai",
+  "openaiTtsEndpoint": "http://localhost:8880",
+  "openaiTtsVoice": "af_heart",
+  "openaiTtsModel": "kokoro"
+}
+```
+**Note**: User must have a compatible TTS server running locally or remotely.
+
+#### Task: Enable Discord Webhook Notifications
+```jsonc
+{
+  "enableWebhook": true,
+  "webhookUrl": "https://discord.com/api/webhooks/...",
+  "webhookEvents": ["idle", "permission", "error", "question"],
+  "webhookMentionOnPermission": true
+}
+```
+
+#### Task: Enable AI-Generated Messages (requires local AI server)
+```jsonc
+{
+  "enableAIMessages": true,
+  "aiEndpoint": "http://localhost:11434/v1",
+  "aiModel": "llama3"
+}
+```
+**Note**: Requires Ollama, LM Studio, or similar running locally.
+
+#### Task: Set Up Custom Sound Theme
+```jsonc
+{
+  "soundThemeDir": "themes/warcraft2",
+  "randomizeSoundFromTheme": true
+}
+```
+**Directory structure**: `~/.config/opencode/themes/warcraft2/{idle,permission,error,question}/*.mp3`
+
+### Common Issues & Fixes
+
+| Issue | Solution |
+|-------|----------|
+| No sound playing | Check `"enableSound": true` and verify audio files exist in `~/.config/opencode/assets/` |
+| TTS not working | Try fallback: change `"ttsEngine"` to `"edge"` (free, no API key) |
+| ElevenLabs quota exceeded | Plugin auto-falls back to Edge TTS; or set `"ttsEngine": "edge"` |
+| Notifications too frequent | Increase `"ttsReminderDelaySeconds"` (default: 30) |
+| Want to disable completely | Set `"enabled": false` in config |
+| Edge TTS not speaking | Install Python edge-tts: `pip install edge-tts` |
+
+### Platform-Specific Notes
+
+- **Windows**: All features supported, SAPI as offline fallback
+- **macOS**: Focus detection available, `say` command as offline fallback
+- **Linux**: Requires `libnotify-bin` for desktop notifications, no offline TTS fallback
+
+### TTS Fallback Chain
+
+Primary Engine → Edge TTS → Windows SAPI → macOS Say → Sound File
+
+### Done When
+
+The plugin is successfully configured when:
+- [ ] `~/.config/opencode/opencode.json` contains the plugin entry
+- [ ] `~/.config/opencode/smart-voice-notify.jsonc` exists with user's settings
+- [ ] Running `opencode` produces audio notification when agent finishes a task
+
+END LLM-AGENT-INSTRUCTIONS
+-->
+
+## License
+
+MIT
+
+## Support
+
+- Open an issue on [GitHub](https://github.com/MasuRii/opencode-smart-voice-notify/issues)
+- Check the [OpenCode docs](https://opencode.ai/docs/plugins)
+
+<!-- Dynamic Header -->
+<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=0:667eea,100:764ba2&height=120&section=header"/>

package/index.js

@@ -385,14 +385,14 @@ export default async function SmartVoiceNotifyPlugin({ project, client, $, direc
     pendingReminders.clear();
   };
 
-  /**
-   * Schedule a TTS reminder if user doesn't respond within configured delay.
-   * The reminder uses a personalized TTS message.
-   * @param {string} type - 'idle', 'permission', 'question', or 'error'
-   * @param {string} message - The TTS message to speak (used directly, supports count-aware messages)
-   * @param {object} options - Additional options (fallbackSound, permissionCount, questionCount, errorCount, aiContext)
-   */
-  const scheduleTTSReminder = (type, message, options = {}) => {
+  /**
+   * Schedule a TTS reminder if user doesn't respond within configured delay.
+   * The reminder generates an AI message WHEN IT FIRES (not immediately), avoiding wasteful early AI calls.
+   * @param {string} type - 'idle', 'permission', 'question', or 'error'
+   * @param {string} _message - DEPRECATED: No longer used (AI message is generated when reminder fires)
+   * @param {object} options - Additional options (fallbackSound, permissionCount, questionCount, errorCount, aiContext)
+   */
+  const scheduleTTSReminder = (type, _message, options = {}) => {
     // Check if TTS reminders are enabled
     if (!config.enableTTSReminder) {
       debugLog(`scheduleTTSReminder: TTS reminders disabled`);
@@ -825,25 +825,25 @@ export default async function SmartVoiceNotifyPlugin({ project, client, $, direc
       debugLog('processPermissionBatch: new permissions arrived during sound');
     }
     
-    // Step 3: Check race condition - did user respond during sound?
-    if (activePermissionId === null) {
-      debugLog('processPermissionBatch: user responded during sound - aborting');
-      return;
-    }
-
-    // Step 4: Generate AI message for reminder AFTER sound played (with context)
-    const reminderMessage = await getPermissionMessage(batchCount, true, aiContext);
-    
-    // Step 5: Schedule TTS reminder if enabled
-    if (config.enableTTSReminder && reminderMessage) {
-      scheduleTTSReminder('permission', reminderMessage, {
-        fallbackSound: config.permissionSound,
-        permissionCount: batchCount,
-        aiContext  // Pass context for follow-up reminders
-      });
-    }
-    
-    // Step 6: If TTS-first or both mode, generate and speak immediate message
+    // Step 3: Check race condition - did user respond during sound?
+    if (activePermissionId === null) {
+      debugLog('processPermissionBatch: user responded during sound - aborting');
+      return;
+    }
+
+    // Step 4: Schedule TTS reminder if enabled
+    // NOTE: The AI message is generated ONLY when the reminder fires (inside scheduleTTSReminder)
+    // This avoids wasteful immediate AI generation in sound-first mode - the user might respond before the reminder fires
+    // IMPORTANT: Skip TTS reminder entirely in 'sound-only' mode
+    if (config.enableTTSReminder && config.notificationMode !== 'sound-only') {
+      scheduleTTSReminder('permission', null, {
+        fallbackSound: config.permissionSound,
+        permissionCount: batchCount,
+        aiContext  // Pass context for reminder message generation
+      });
+    }
+    
+    // Step 5: If TTS-first or both mode, generate and speak immediate message
     if (config.notificationMode === 'tts-first' || config.notificationMode === 'both') {
       const ttsMessage = await getPermissionMessage(batchCount, false, aiContext);
       await tts.wakeMonitor();
@@ -931,25 +931,25 @@ export default async function SmartVoiceNotifyPlugin({ project, client, $, direc
       debugLog('processQuestionBatch: new questions arrived during sound');
     }
     
-    // Step 3: Check race condition - did user respond during sound?
-    if (activeQuestionId === null) {
-      debugLog('processQuestionBatch: user responded during sound - aborting');
-      return;
-    }
-
-    // Step 4: Generate AI message for reminder AFTER sound played (with context)
-    const reminderMessage = await getQuestionMessage(totalQuestionCount, true, aiContext);
-
-    // Step 5: Schedule TTS reminder if enabled
-    if (config.enableTTSReminder && reminderMessage) {
-      scheduleTTSReminder('question', reminderMessage, {
-        fallbackSound: config.questionSound,
-        questionCount: totalQuestionCount,
-        aiContext  // Pass context for follow-up reminders
-      });
-    }
-    
-    // Step 6: If TTS-first or both mode, generate and speak immediate message
+    // Step 3: Check race condition - did user respond during sound?
+    if (activeQuestionId === null) {
+      debugLog('processQuestionBatch: user responded during sound - aborting');
+      return;
+    }
+
+    // Step 4: Schedule TTS reminder if enabled
+    // NOTE: The AI message is generated ONLY when the reminder fires (inside scheduleTTSReminder)
+    // This avoids wasteful immediate AI generation in sound-first mode - the user might respond before the reminder fires
+    // IMPORTANT: Skip TTS reminder entirely in 'sound-only' mode
+    if (config.enableTTSReminder && config.notificationMode !== 'sound-only') {
+      scheduleTTSReminder('question', null, {
+        fallbackSound: config.questionSound,
+        questionCount: totalQuestionCount,
+        aiContext  // Pass context for reminder message generation
+      });
+    }
+    
+    // Step 5: If TTS-first or both mode, generate and speak immediate message
     if (config.notificationMode === 'tts-first' || config.notificationMode === 'both') {
       const ttsMessage = await getQuestionMessage(totalQuestionCount, false, aiContext);
       await tts.wakeMonitor();
@@ -1188,24 +1188,24 @@ export default async function SmartVoiceNotifyPlugin({ project, client, $, direc
             }
           }
           
-          // Step 3: Check race condition - did user respond during sound?
-          if (lastUserActivityTime > lastSessionIdleTime) {
-            debugLog(`session.idle: user active during sound - aborting`);
-            return;
-          }
-
-          // Step 4: Generate AI message for reminder AFTER sound played
-          const reminderMessage = await getSmartMessage('idle', true, config.idleReminderTTSMessages, aiContext);
-
-          // Step 5: Schedule TTS reminder if enabled
-          if (config.enableTTSReminder && reminderMessage) {
-            scheduleTTSReminder('idle', reminderMessage, {
-              fallbackSound: config.idleSound,
-              aiContext  // Pass context for follow-up reminders
-            });
-          }
-          
-          // Step 6: If TTS-first or both mode, generate and speak immediate message
+          // Step 3: Check race condition - did user respond during sound?
+          if (lastUserActivityTime > lastSessionIdleTime) {
+            debugLog(`session.idle: user active during sound - aborting`);
+            return;
+          }
+
+          // Step 4: Schedule TTS reminder if enabled
+          // NOTE: The AI message is generated ONLY when the reminder fires (inside scheduleTTSReminder)
+          // This avoids wasteful immediate AI generation in sound-first mode - the user might respond before the reminder fires
+          // IMPORTANT: Skip TTS reminder entirely in 'sound-only' mode
+          if (config.enableTTSReminder && config.notificationMode !== 'sound-only') {
+            scheduleTTSReminder('idle', null, {
+              fallbackSound: config.idleSound,
+              aiContext  // Pass context for reminder message generation
+            });
+          }
+          
+          // Step 5: If TTS-first or both mode, generate and speak immediate message
           if (config.notificationMode === 'tts-first' || config.notificationMode === 'both') {
             const ttsMessage = await getSmartMessage('idle', false, config.idleTTSMessages, aiContext);
             await tts.wakeMonitor();
@@ -1269,23 +1269,23 @@ export default async function SmartVoiceNotifyPlugin({ project, client, $, direc
           if (config.notificationMode !== 'tts-first') {
             if (!suppressError) {
               await playSound(config.errorSound, 2, 'error');  // Play twice for urgency
-            } else {
-              debugLog('session.error: sound suppressed (terminal focused)');
-            }
-          }
-
-          // Step 3: Generate AI message for reminder AFTER sound played
-          const reminderMessage = await getErrorMessage(1, true);
-
-          // Step 4: Schedule TTS reminder if enabled
-          if (config.enableTTSReminder && reminderMessage) {
-            scheduleTTSReminder('error', reminderMessage, {
-              fallbackSound: config.errorSound,
-              errorCount: 1
-            });
-          }
-          
-          // Step 5: If TTS-first or both mode, generate and speak immediate message
+            } else {
+              debugLog('session.error: sound suppressed (terminal focused)');
+            }
+          }
+
+          // Step 3: Schedule TTS reminder if enabled
+          // NOTE: The AI message is generated ONLY when the reminder fires (inside scheduleTTSReminder)
+          // This avoids wasteful immediate AI generation in sound-first mode - the user might respond before the reminder fires
+          // IMPORTANT: Skip TTS reminder entirely in 'sound-only' mode
+          if (config.enableTTSReminder && config.notificationMode !== 'sound-only') {
+            scheduleTTSReminder('error', null, {
+              fallbackSound: config.errorSound,
+              errorCount: 1
+            });
+          }
+          
+          // Step 4: If TTS-first or both mode, generate and speak immediate message
           if (config.notificationMode === 'tts-first' || config.notificationMode === 'both') {
             const ttsMessage = await getErrorMessage(1, false);
             await tts.wakeMonitor();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-smart-voice-notify",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Smart voice notification plugin for OpenCode with multiple TTS engines (ElevenLabs, Edge TTS, Windows SAPI), AI-generated dynamic messages, and intelligent reminder system",
   "main": "index.js",
   "type": "module",
@@ -50,7 +50,7 @@
   "dependencies": {
     "@elevenlabs/elevenlabs-js": "^2.32.0",
     "detect-terminal": "^2.0.0",
-    "msedge-tts": "^2.0.3",
+    "msedge-tts": "^2.0.4",
     "node-notifier": "^10.0.1"
   },
   "peerDependencies": {

package/util/sound-theme.js

@@ -48,15 +48,15 @@ export const listSoundsInTheme = (themeDir, eventType) => {
     return [];
   }
 
-  try {
-    return fs.readdirSync(subDir)
-      .filter(file => AUDIO_EXTENSIONS.includes(path.extname(file).toLowerCase()))
-      .sort() // Sort alphabetically for consistent cross-platform behavior
-      .map(file => path.join(subDir, file))
-      .filter(filePath => fs.statSync(filePath).isFile());
-  } catch (error) {
-    return [];
-  }
+  try {
+    return fs.readdirSync(subDir)
+      .filter(file => AUDIO_EXTENSIONS.includes(path.extname(file).toLowerCase()))
+      .sort() // Sort alphabetically for consistent cross-platform behavior
+      .map(file => path.join(subDir, file))
+      .filter(filePath => fs.statSync(filePath).isFile());
+  } catch (error) {
+    return [];
+  }
 };
 
 /**

package/util/tts.js

@@ -337,30 +337,57 @@ export const createTTS = ({ $, client }) => {
     }
   };
 
-  /**
-   * Edge TTS Engine (Free, Neural voices)
-   */
-  const speakWithEdgeTTS = async (text) => {
-    try {
-      const { MsEdgeTTS, OUTPUT_FORMAT } = await import('msedge-tts');
-      const tts = new MsEdgeTTS();
-      const voice = config.edgeVoice || 'en-US-JennyNeural';
-      const pitch = config.edgePitch || '+0Hz';
-      const rate = config.edgeRate || '+10%';
-      const volume = config.edgeVolume || '+0%';
-      
-      await tts.setMetadata(voice, OUTPUT_FORMAT.AUDIO_24KHZ_48KBITRATE_MONO_MP3);
-      
-      const { audioFilePath } = await tts.toFile(os.tmpdir(), text, { pitch, rate, volume });
-      
-      await playAudioFile(audioFilePath);
-      try { fs.unlinkSync(audioFilePath); } catch (e) {}
-      return true;
-    } catch (e) {
-      debugLog(`speakWithEdgeTTS error: ${e?.message || String(e) || 'Unknown error'}`);
-      return false;
-    }
-  };
+  /**
+   * Edge TTS Engine via Python CLI (Free, Neural voices)
+   * Uses Python edge-tts package via command line as it's more reliable than Node.js WebSocket libraries.
+   * Fallback: tries msedge-tts npm package if Python edge-tts is not available.
+   */
+  const speakWithEdgeTTS = async (text) => {
+    const voice = config.edgeVoice || 'en-US-JennyNeural';
+    const pitch = config.edgePitch || '+0Hz';
+    const rate = config.edgeRate || '+10%';
+    const volume = config.edgeVolume || '+0%';
+    const tempFile = path.join(os.tmpdir(), `opencode-edge-tts-${Date.now()}.mp3`);
+    
+    // Escape text for shell (replace quotes with escaped quotes)
+    const escapedText = text.replace(/"/g, '\\"');
+    
+    // Try Python edge-tts first (more reliable due to aiohttp WebSocket handling)
+    if ($) {
+      try {
+        // Use proper template literal syntax with individual arguments
+        await $`edge-tts --voice ${voice} --rate ${rate} --volume ${volume} --pitch ${pitch} --text ${escapedText} --write-media ${tempFile}`.quiet().nothrow();
+        
+        if (fs.existsSync(tempFile)) {
+          await playAudioFile(tempFile);
+          try { fs.unlinkSync(tempFile); } catch (e) {}
+          debugLog('speakWithEdgeTTS: success via Python edge-tts CLI');
+          return true;
+        }
+      } catch (e) {
+        debugLog(`speakWithEdgeTTS: Python CLI failed: ${e?.message || 'unknown'}, trying npm package...`);
+        // Fall through to try npm package
+      }
+    }
+    
+    // Fallback to msedge-tts npm package
+    try {
+      const { MsEdgeTTS, OUTPUT_FORMAT } = await import('msedge-tts');
+      const tts = new MsEdgeTTS();
+      
+      await tts.setMetadata(voice, OUTPUT_FORMAT.AUDIO_24KHZ_48KBITRATE_MONO_MP3);
+      
+      const { audioFilePath } = await tts.toFile(os.tmpdir(), text, { pitch, rate, volume });
+      
+      await playAudioFile(audioFilePath);
+      try { fs.unlinkSync(audioFilePath); } catch (e) {}
+      debugLog('speakWithEdgeTTS: success via msedge-tts npm package');
+      return true;
+    } catch (e) {
+      debugLog(`speakWithEdgeTTS error: ${e?.message || String(e) || 'Unknown error'}`);
+      return false;
+    }
+  };
 
   /**
    * Windows SAPI Engine (Offline, Built-in)
@@ -628,46 +655,55 @@ public static extern int waveOutGetVolume(IntPtr hwo, out uint dwVolume);
     }
   };
 
-  /**
-   * Main Speak function with fallback chain
-   * Cascade: ElevenLabs -> Edge TTS -> Windows SAPI -> macOS Say -> Sound File
-   */
-  const speak = async (message, options = {}) => {
-    const activeConfig = { ...config, ...options };
-    if (!activeConfig.enableSound) return false;
-    
-    if (activeConfig.enableTTS) {
-      let success = false;
-      const engine = activeConfig.ttsEngine || 'elevenlabs';
-      
-      if (engine === 'openai') {
-        success = await speakWithOpenAI(message);
-        if (!success) success = await speakWithEdgeTTS(message);
-        if (!success) success = await speakWithSAPI(message);
-      } else if (engine === 'elevenlabs') {
-        success = await speakWithElevenLabs(message);
-        if (!success) success = await speakWithEdgeTTS(message);
-        if (!success) success = await speakWithSAPI(message);
-      } else if (engine === 'edge') {
-        success = await speakWithEdgeTTS(message);
-        if (!success) success = await speakWithSAPI(message);
-      } else if (engine === 'sapi') {
-        success = await speakWithSAPI(message);
-        if (!success) success = await speakWithSay(message);
-      }
-      
-      if (success) return true;
-    }
-
-    if (activeConfig.fallbackSound) {
-      const soundPath = path.isAbsolute(activeConfig.fallbackSound) 
-        ? activeConfig.fallbackSound 
-        : path.join(getConfigDir(), activeConfig.fallbackSound);
-
-      await playAudioFile(soundPath, activeConfig.loops || 1);
-    }
-    return false;
-  };
+  /**
+   * Main Speak function with fallback chain
+   * Cascade: Primary Engine -> Edge TTS -> Windows SAPI -> macOS Say -> Sound File
+   * 
+   * Fallback ensures TTS works even if:
+   * - Python edge-tts not installed (falls to npm package, then SAPI/Say)
+   * - msedge-tts npm fails (403 errors - falls to SAPI/Say)
+   * - User is on macOS without edge-tts (falls to built-in 'say' command)
+   * - User is on Linux without edge-tts (falls to sound file only)
+   */
+  const speak = async (message, options = {}) => {
+    const activeConfig = { ...config, ...options };
+    if (!activeConfig.enableSound) return false;
+    
+    if (activeConfig.enableTTS) {
+      let success = false;
+      const engine = activeConfig.ttsEngine || 'elevenlabs';
+      
+      if (engine === 'openai') {
+        success = await speakWithOpenAI(message);
+        if (!success) success = await speakWithEdgeTTS(message);
+        if (!success) success = await speakWithSAPI(message);
+        if (!success) success = await speakWithSay(message);  // macOS fallback
+      } else if (engine === 'elevenlabs') {
+        success = await speakWithElevenLabs(message);
+        if (!success) success = await speakWithEdgeTTS(message);
+        if (!success) success = await speakWithSAPI(message);
+        if (!success) success = await speakWithSay(message);  // macOS fallback
+      } else if (engine === 'edge') {
+        success = await speakWithEdgeTTS(message);
+        if (!success) success = await speakWithSAPI(message);
+        if (!success) success = await speakWithSay(message);  // macOS fallback
+      } else if (engine === 'sapi') {
+        success = await speakWithSAPI(message);
+        if (!success) success = await speakWithSay(message);
+      }
+      
+      if (success) return true;
+    }
+
+    if (activeConfig.fallbackSound) {
+      const soundPath = path.isAbsolute(activeConfig.fallbackSound) 
+        ? activeConfig.fallbackSound 
+        : path.join(getConfigDir(), activeConfig.fallbackSound);
+
+      await playAudioFile(soundPath, activeConfig.loops || 1);
+    }
+    return false;
+  };
 
   return {
     speak,