opencode-smart-voice-notify 1.2.4 → 1.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 MasuRii
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 MasuRii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,9 +3,14 @@
 
 # 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)
+
+
 > **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.
 
-A smart voice notification plugin for [OpenCode](https://opencode.ai) with **multiple TTS engines** and an intelligent reminder system.
+A smart voice notification plugin for [OpenCode](https://opencode.ai) with **multiple TTS engines**, native desktop notifications, and an intelligent reminder system.
 
 <img width="1456" height="720" alt="image" src="https://github.com/user-attachments/assets/52ccf357-2548-400b-a346-6362f2fc3180" />
 
@@ -15,10 +20,11 @@ A smart voice notification plugin for [OpenCode](https://opencode.ai) with **mul
 ### Smart TTS Engine Selection
 The plugin automatically tries multiple TTS engines in order, falling back if one fails:
 
-1. **ElevenLabs** (Online) - High-quality, anime-like voices with natural expression
-2. **Edge TTS** (Free) - Microsoft's neural voices, native Node.js implementation (no Python required)
-3. **Windows SAPI** (Offline) - Built-in Windows speech synthesis
-4. **Local Sound Files** (Fallback) - Plays bundled MP3 files if all TTS 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 Notification System
 - **Sound-first mode**: Play a sound immediately, then speak a TTS reminder if user doesn't respond
@@ -27,6 +33,7 @@ The plugin automatically tries multiple TTS engines in order, falling back if on
 - **Sound-only mode**: Just play sounds, no TTS
 
 ### Intelligent Reminders
+- **Granular Control**: Enable or disable notifications and reminders for specific event types (Idle, Permission, Question, Error) via configuration.
 - Delayed TTS reminders if user doesn't respond within configurable time
 - Follow-up reminders with exponential backoff
 - Automatic cancellation when user responds
@@ -43,11 +50,15 @@ The plugin automatically tries multiple TTS engines in order, falling back if on
 - **Smart fallback**: Automatically falls back to static messages if AI is unavailable
 
 ### System Integration
+- **Native Desktop Notifications**: Windows (Toast), macOS (Notification Center), and Linux (notify-send) support
 - **Native Edge TTS**: No external dependencies (Python/pip) required
-- Wake monitor from sleep before notifying
-- Auto-boost volume if too low
-- TUI toast notifications
-- Cross-platform support (Windows, macOS, Linux)
+- **Focus Detection** (macOS): Suppresses notifications when terminal is focused
+- **Webhook Integration**: Receive notifications on Discord or any custom webhook endpoint when tasks finish or need attention
+- **Themed Sound Packs**: Use custom sound collections (e.g., Warcraft, StarCraft) by simply pointing to a directory
+- **Per-Project Sounds**: Assign unique sounds to different projects for easy identification
+- **Wake monitor** from sleep before notifying
+- **Auto-boost volume** if too low
+- **TUI toast** notifications
 
 ## Installation
 
@@ -99,62 +110,101 @@ When you first run OpenCode with this plugin installed, it will **automatically
 
 The auto-generated configuration includes all advanced settings, message arrays, and engine options, so you don't have to refer back to the documentation for available settings.
 
-### Manual Configuration
-
-If you prefer to create the config manually, add a `smart-voice-notify.jsonc` file in your OpenCode config directory (`~/.config/opencode/`):
-
-```jsonc
-{
-    // ============================================================
-    // OpenCode Smart Voice Notify - Quick Start Configuration
-    // ============================================================
-    // For ALL available options, see example.config.jsonc in the plugin.
-    // The plugin auto-creates a comprehensive config on first run.
-    // ============================================================
-
-    // Master switch to enable/disable the plugin without uninstalling
-    "enabled": true,
-
-    // Notification mode: 'sound-first', 'tts-first', 'both', 'sound-only'
-    "notificationMode": "sound-first",
-    
-    // TTS engine: 'elevenlabs', 'edge', 'sapi'
-    "ttsEngine": "elevenlabs",
-    "enableTTS": true,
-    
-    // ElevenLabs settings (get API key from https://elevenlabs.io/app/settings/api-keys)
-    "elevenLabsApiKey": "YOUR_API_KEY_HERE",
-    "elevenLabsVoiceId": "cgSgspJ2msm6clMCkdW9",  // Jessica - Playful, Bright
-    
-    // Edge TTS settings (free, no API key required)
-    "edgeVoice": "en-US-AnaNeural",
-    "edgePitch": "+50Hz",
-    "edgeRate": "+10%",
-    
-    // TTS reminder settings
-    "enableTTSReminder": true,
-    "ttsReminderDelaySeconds": 30,
-    "enableFollowUpReminders": true,
-    "maxFollowUpReminders": 3,
-    
-    // AI-generated messages (optional - requires local AI server)
-    "enableAIMessages": false,
-    "aiEndpoint": "http://localhost:11434/v1",
-    "aiModel": "llama3",
-    "aiApiKey": "",
-    "aiFallbackToStatic": true,
-    
-    // General settings
-    "wakeMonitor": true,
-    "forceVolume": true,
-    "volumeThreshold": 50,
-    "enableToast": true,
-    "enableSound": true,
-    "debugLog": false
-}
-```
-
-For the complete configuration with all TTS engine settings, message arrays, AI prompts, and advanced options, see [`example.config.jsonc`](./example.config.jsonc) in the plugin directory.
+### Manual Configuration
+
+If you prefer to create the config manually, add a `smart-voice-notify.jsonc` file in your OpenCode config directory (`~/.config/opencode/`):
+
+```jsonc
+{
+    // Master switch to enable/disable the plugin without uninstalling
+    "enabled": true,
+
+    // Notification mode: 'sound-first', 'tts-first', 'both', 'sound-only'
+    "notificationMode": "sound-first",
+    
+    // TTS engine: 'openai', 'elevenlabs', 'edge', 'sapi'
+    "ttsEngine": "openai",
+    "enableTTS": true,
+    
+    // ElevenLabs settings (get API key from https://elevenlabs.io/app/settings/api-keys)
+    "elevenLabsApiKey": "YOUR_API_KEY_HERE",
+    "elevenLabsVoiceId": "cgSgspJ2msm6clMCkdW9",  // Jessica - Playful, Bright
+    
+    // OpenAI-compatible TTS (Kokoro, LocalAI, OpenAI, Coqui, AllTalk, etc.)
+    "openaiTtsEndpoint": "http://localhost:8880",
+    "openaiTtsVoice": "af_heart",
+    "openaiTtsModel": "kokoro",
+    
+    // Edge TTS settings (free, no API key required)
+    "edgeVoice": "en-US-AnaNeural",
+    "edgePitch": "+50Hz",
+    "edgeRate": "+10%",
+    
+    // Desktop Notifications
+    "enableDesktopNotification": true,
+    "desktopNotificationTimeout": 5,
+    "showProjectInNotification": true,
+
+    // TTS reminder settings
+    "enableTTSReminder": true,
+    "ttsReminderDelaySeconds": 30,
+    "enableFollowUpReminders": true,
+    
+    // Focus Detection (macOS only)
+    "suppressWhenFocused": true,
+    "alwaysNotify": false,
+
+    // AI-generated messages (optional - requires local AI server)
+    "enableAIMessages": false,
+    "aiEndpoint": "http://localhost:11434/v1",
+    
+    // Webhook settings (optional - works with Discord)
+    "enableWebhook": false,
+    "webhookUrl": "",
+    "webhookUsername": "OpenCode Notify",
+    
+    // Sound theme settings (optional)
+    "soundThemeDir": "", // Path to custom sound theme directory
+    
+    // Per-project sounds
+    "perProjectSounds": false,
+    "projectSoundSeed": 0,
+
+    // General settings
+    "wakeMonitor": true,
+    "forceVolume": false,
+    "volumeThreshold": 50,
+    "enableToast": true,
+    "enableSound": true,
+    "debugLog": false
+}
+```
+
+For the complete configuration with all TTS engine settings, message arrays, AI prompts, and advanced options, see [`example.config.jsonc`](./example.config.jsonc) in the plugin directory.
+
+### OpenAI-Compatible TTS Setup (Kokoro, LocalAI, OpenAI API, etc.)
+
+For cloud-based or self-hosted TTS using any OpenAI-compatible `/v1/audio/speech` endpoint:
+
+```jsonc
+{
+  "ttsEngine": "openai",
+  "openaiTtsEndpoint": "http://192.168.86.43:8880",  // Your TTS server
+  "openaiTtsVoice": "af_heart",                      // Server-dependent
+  "openaiTtsModel": "kokoro",                        // Server-dependent
+  "openaiTtsApiKey": "",                             // Optional, if server requires auth
+  "openaiTtsSpeed": 1.0                              // 0.25 to 4.0
+}
+```
+
+**Supported OpenAI-Compatible TTS Servers:**
+| Server | Example Endpoint | Voices |
+|--------|------------------|--------|
+| Kokoro | `http://localhost:8880` | `af_heart`, `af_bella`, `am_adam`, etc. |
+| LocalAI | `http://localhost:8080` | Model-dependent |
+| AllTalk | `http://localhost:7851` | Model-dependent |
+| OpenAI | `https://api.openai.com` | `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer` |
+| Coqui | `http://localhost:5002` | Model-dependent |
 
 ### AI Message Generation (Optional)
 
@@ -173,12 +223,15 @@ If you want dynamic, AI-generated notification messages instead of preset ones,
      "aiEndpoint": "http://localhost:11434/v1",
      "aiModel": "llama3",
      "aiApiKey": "",
-     "aiFallbackToStatic": true
+     "aiFallbackToStatic": true,
+     "enableContextAwareAI": false  // Set to true for personalized messages with project/task context
    }
    ```
 
 3. **The AI will generate unique messages** for each notification, which are then spoken by your TTS engine.
 
+4. **Context-Aware Messages** (optional): Enable `enableContextAwareAI` for personalized notifications that include project name, task title, and change summary (e.g., "Your work on MyProject is complete!").
+
 **Supported AI Servers:**
 | Server | Default Endpoint | API Key |
 |--------|-----------------|---------|
@@ -188,8 +241,94 @@ If you want dynamic, AI-generated notification messages instead of preset ones,
 | vLLM | `http://localhost:8000/v1` | Use "EMPTY" |
 | Jan.ai | `http://localhost:1337/v1` | Required |
 
+### Discord / Webhook Integration (Optional)
+
+Receive remote notifications on Discord or any custom endpoint. This is perfect for long-running tasks when you're away from your computer.
+
+1. **Create a Discord Webhook**:
+   - In Discord, go to **Server Settings** > **Integrations** > **Webhooks**.
+   - Click **New Webhook**, choose a channel, and click **Copy Webhook URL**.
+
+2. **Enable Webhooks in your config**:
+   ```jsonc
+   {
+     "enableWebhook": true,
+     "webhookUrl": "https://discord.com/api/webhooks/...",
+     "webhookUsername": "OpenCode Notify",
+     "webhookEvents": ["idle", "permission", "error", "question"],
+     "webhookMentionOnPermission": true
+   }
+   ```
+
+3. **Features**:
+   - **Color-coded Embeds**: Different colors for task completion (green), permissions (orange), errors (red), and questions (blue).
+   - **Smart Mentions**: Automatically @everyone on Discord for urgent permission requests.
+   - **Rate Limiting**: Intelligent retry logic with backoff if Discord's rate limits are hit.
+    - **Fire-and-forget**: Webhook requests never block local sound or TTS playback.
+
+**Supported Webhook Events:**
+| Event | Trigger |
+|-------|---------|
+| `idle` | Agent finished working |
+| `permission` | Agent needs permission for a tool |
+| `error` | Agent encountered an error |
+| `question` | Agent is asking you a question |
+
+
+### Custom Sound Themes (Optional)
+
+You can replace individual sound files with entire "Sound Themes" (like the classic Warcraft II or StarCraft sound packs).
+
+1. **Set up your theme directory**:
+   Create a folder (e.g., `~/.config/opencode/themes/warcraft2/`) with the following structure:
+   ```text
+   warcraft2/
+   ├── idle/          # Sounds for when the agent finishes
+   │   ├── job_done.mp3
+   │   └── alright.wav
+   ├── permission/    # Sounds for permission requests
+   │   ├── help.mp3
+   │   └── need_orders.wav
+   ├── error/         # Sounds for agent errors
+   │   └── alert.mp3
+   └── question/      # Sounds for agent questions
+       └── yes_milord.mp3
+   ```
+
+2. **Configure the theme in your config**:
+   ```jsonc
+   {
+     "soundThemeDir": "themes/warcraft2",
+     "randomizeSoundFromTheme": true
+   }
+   ```
+
+3. **Features**:
+   - **Automatic Fallback**: If a theme subdirectory or sound is missing, the plugin automatically falls back to your default sound files.
+   - **Randomization**: If multiple sounds are in a subdirectory, the plugin will pick one at random each time (if `randomizeSoundFromTheme` is `true`).
+   - **Relative Paths**: Paths are relative to your OpenCode config directory (`~/.config/opencode/`).
+
+
 ## Requirements
 
+### 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) |
+
+### For OpenAI-Compatible TTS
+- Any server implementing the `/v1/audio/speech` endpoint
+- Examples: [Kokoro](https://github.com/remsky/Kokoro-FastAPI), [LocalAI](https://localai.io), [AllTalk](https://github.com/erew123/alltalk_tts), OpenAI API, etc.
+- Works with both local self-hosted servers and cloud-based providers.
+
 ### For ElevenLabs TTS
 - ElevenLabs API key (free tier: 10,000 characters/month)
 - Internet connection
@@ -200,16 +339,48 @@ If you want dynamic, AI-generated notification messages instead of preset ones,
 ### For Windows SAPI
 - Windows OS (uses built-in System.Speech)
 
+### For Desktop Notifications
+- **Windows**: Built-in (uses Toast notifications)
+- **macOS**: Built-in (uses Notification Center)
+- **Linux**: Requires `notify-send` (libnotify)
+  ```bash
+  # Ubuntu/Debian
+  sudo apt install libnotify-bin
+
+  # Fedora
+  sudo dnf install libnotify
+
+  # Arch Linux
+  sudo pacman -S libnotify
+  ```
+
 ### For Sound Playback
 - **Windows**: Built-in (uses Windows Media Player)
 - **macOS**: Built-in (`afplay`)
 - **Linux**: `paplay` or `aplay`
 
+### For Focus Detection
+Focus detection suppresses sound and desktop notifications when the terminal is focused.
+
+| Platform | Support | Notes |
+|----------|---------|-------|
+| **macOS** | ✅ Full | Uses AppleScript to detect frontmost application |
+| **Windows** | ❌ Not supported | No reliable API available |
+| **Linux** | ❌ Not supported | Varies by desktop environment |
+
+> **Note**: On unsupported platforms, notifications are always sent (fail-open behavior). TTS reminders are never suppressed, even when focused, since users may step away after seeing the toast.
+
+### For Webhook Notifications
+- **Discord**: Full support for Discord's webhook embed format.
+- **Generic**: Works with any endpoint that accepts a POST request with a JSON body (though formatting is optimized for Discord).
+- **Rate Limits**: The plugin handles HTTP 429 (Too Many Requests) automatically with retries and a 250ms queue delay.
+
 ## Events Handled
 
 | Event | Action |
 |-------|--------|
 | `session.idle` | Agent finished working - notify user |
+| `session.error` | Agent encountered an error - alert user |
 | `permission.asked` | Permission request (SDK v1.1.1+) - alert user |
 | `permission.updated` | Permission request (SDK v1.0.x) - alert user |
 | `permission.replied` | User responded - cancel pending reminders |
@@ -247,6 +418,23 @@ To develop on this plugin locally:
    }
    ```
 
+### Testing
+
+The plugin uses [Bun](https://bun.sh)'s built-in test runner for unit and E2E tests.
+
+```bash
+# Run all tests
+bun test
+
+# Run tests with coverage
+bun test --coverage
+
+# Run tests in watch mode
+bun test --watch
+```
+
+For more detailed testing guidelines and mock usage examples, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
 ## Updating
 
 OpenCode does not automatically update plugins. To update to the latest version: