opencode-smart-voice-notify 1.0.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,200 @@
+# OpenCode Smart Voice Notify
+
+> **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.
+
+## Features
+
+### 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, no API key required
+3. **Windows SAPI** (Offline) - Built-in Windows speech synthesis
+4. **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
+- **TTS-first mode**: Speak immediately using TTS
+- **Both mode**: Play sound AND speak TTS at the same time
+- **Sound-only mode**: Just play sounds, no TTS
+
+### Intelligent Reminders
+- Delayed TTS reminders if user doesn't respond within configurable time
+- Follow-up reminders with exponential backoff
+- Automatic cancellation when user responds
+- Per-notification type delays (permission requests are more urgent)
+
+### System Integration
+- Wake monitor from sleep before notifying
+- Auto-boost volume if too low
+- TUI toast notifications
+- Cross-platform support (Windows, macOS, Linux)
+
+## Installation
+
+### Option 1: From npm (Recommended)
+
+Add to your OpenCode config file (`~/.config/opencode/config.json`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-smart-voice-notify@latest"]
+}
+```
+
+### Option 2: From GitHub
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["github:MasuRii/opencode-smart-voice-notify"]
+}
+```
+
+### Option 3: Local Development
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/MasuRii/opencode-smart-voice-notify.git
+   ```
+
+2. Reference the local path in your config:
+   ```json
+   {
+     "plugin": ["file:///path/to/opencode-smart-voice-notify"]
+   }
+   ```
+
+## Configuration
+
+### Automatic Setup
+
+When you first run OpenCode with this plugin installed, it will **automatically create**:
+
+1. **`~/.config/opencode/smart-voice-notify.jsonc`** - A default config file with sensible defaults
+2. **`~/.config/opencode/assets/*.mp3`** - Bundled notification sound files
+
+You can then customize the config file as needed.
+
+### 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
+{
+    // ============================================================
+    // NOTIFICATION MODE SETTINGS
+    // ============================================================
+    // 'sound-first' - Play sound immediately, TTS reminder after delay (RECOMMENDED)
+    // 'tts-first'   - Speak TTS immediately
+    // 'both'        - Play sound AND speak TTS immediately
+    // 'sound-only'  - Only play sound, no TTS
+    "notificationMode": "sound-first",
+    
+    // ============================================================
+    // TTS ENGINE SELECTION
+    // ============================================================
+    // 'elevenlabs' - Best quality (requires API key)
+    // 'edge'       - Free neural voices (requires: pip install edge-tts)
+    // 'sapi'       - Windows built-in (free, offline)
+    "ttsEngine": "elevenlabs",
+    "enableTTS": true,
+    
+    // ============================================================
+    // ELEVENLABS SETTINGS
+    // ============================================================
+    // Get your API key from: https://elevenlabs.io/app/settings/api-keys
+    "elevenLabsApiKey": "your-api-key-here",
+    "elevenLabsVoiceId": "cgSgspJ2msm6clMCkdW9",  // Jessica voice
+    "elevenLabsModel": "eleven_turbo_v2_5",
+    
+    // ============================================================
+    // TTS REMINDER SETTINGS
+    // ============================================================
+    "enableTTSReminder": true,
+    "idleReminderDelaySeconds": 30,
+    "permissionReminderDelaySeconds": 20,
+    "enableFollowUpReminders": true,
+    "maxFollowUpReminders": 3,
+    
+    // ============================================================
+    // SOUND FILES (relative to OpenCode config directory)
+    // ============================================================
+    "idleSound": "assets/Soft-high-tech-notification-sound-effect.mp3",
+    "permissionSound": "assets/Machine-alert-beep-sound-effect.mp3"
+}
+```
+
+See `example.config.jsonc` for the full configuration options.
+
+## Requirements
+
+### For ElevenLabs TTS
+- ElevenLabs API key (free tier: 10,000 characters/month)
+- Internet connection
+
+### For Edge TTS
+- Python with `edge-tts` package:
+  ```bash
+  pip install edge-tts
+  ```
+
+### For Windows SAPI
+- Windows OS (uses built-in System.Speech)
+
+### For Sound Playback
+- **Windows**: Built-in (uses Windows Media Player)
+- **macOS**: Built-in (`afplay`)
+- **Linux**: `paplay` or `aplay`
+
+## Events Handled
+
+| Event | Action |
+|-------|--------|
+| `session.idle` | Agent finished working - notify user |
+| `permission.updated` | Permission request - alert user |
+| `permission.replied` | User responded - cancel pending reminders |
+| `message.updated` | New user message - cancel pending reminders |
+| `session.created` | New session - reset state |
+
+## Development
+
+To develop on this plugin locally:
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/MasuRii/opencode-smart-voice-notify.git
+   cd opencode-smart-voice-notify
+   bun install  # or npm install
+   ```
+
+2. Link to your OpenCode config:
+   ```json
+   {
+     "plugin": ["file:///absolute/path/to/opencode-smart-voice-notify"]
+   }
+   ```
+
+## Updating
+
+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)

package/example.config.jsonc

@@ -0,0 +1,158 @@
+{
+    // ============================================================
+    // NOTIFICATION MODE SETTINGS (Smart Notification System)
+    // ============================================================
+    // Controls how notifications are delivered:
+    //   'sound-first' - Play sound immediately, TTS reminder after delay (RECOMMENDED)
+    //   'tts-first'   - Speak TTS immediately, no sound
+    //   'both'        - Play sound AND speak TTS immediately
+    //   'sound-only'  - Only play sound, no TTS at all
+    "notificationMode": "sound-first",
+    
+    // ============================================================
+    // TTS REMINDER SETTINGS (When user doesn't respond to sound)
+    // ============================================================
+    
+    // Enable TTS reminder if user doesn't respond after sound notification
+    "enableTTSReminder": true,
+    
+    // Delay (in seconds) before TTS reminder fires
+    // Set globally or per-notification type
+    "ttsReminderDelaySeconds": 30,         // Global default
+    "idleReminderDelaySeconds": 30,        // For task completion notifications
+    "permissionReminderDelaySeconds": 20,  // For permission requests (more urgent)
+    
+    // Follow-up reminders if user STILL doesn't respond after first TTS
+    "enableFollowUpReminders": true,
+    "maxFollowUpReminders": 3,              // Max number of follow-up TTS reminders
+    "reminderBackoffMultiplier": 1.5,       // Each follow-up waits longer (30s, 45s, 67s...)
+
+    // ============================================================
+    // TTS ENGINE SELECTION
+    // ============================================================
+    // 'elevenlabs' - Best quality, anime-like voices (requires API key, free tier: 10k chars/month)
+    // 'edge'       - Good quality neural voices (free, requires: pip install edge-tts)
+    // 'sapi'       - Windows built-in voices (free, offline, robotic)
+    "ttsEngine": "elevenlabs",
+    
+    // Enable TTS for notifications (falls back to sound files if TTS fails)
+    "enableTTS": true,
+    
+    // ============================================================
+    // ELEVENLABS SETTINGS (Best Quality - Anime-like Voices)
+    // ============================================================
+    // Get your API key from: https://elevenlabs.io/app/settings/api-keys
+    // Free tier: 10,000 characters/month
+    "elevenLabsApiKey": "YOUR_API_KEY_HERE",
+    
+    // Voice ID - Recommended cute/anime-like voices:
+    //   'cgSgspJ2msm6clMCkdW9' - Jessica (Playful, Bright, Warm) - RECOMMENDED
+    //   'FGY2WhTYpPnrIDTdsKH5' - Laura (Enthusiast, Quirky)
+    //   'jsCqWAovK2LkecY7zXl4' - Freya (Expressive, Confident)
+    //   'EXAVITQu4vr4xnSDxMaL' - Sarah (Soft, Warm)
+    // Browse more at: https://elevenlabs.io/voice-library
+    "elevenLabsVoiceId": "cgSgspJ2msm6clMCkdW9",
+    
+    // Model: 'eleven_turbo_v2_5' (fast, good), 'eleven_multilingual_v2' (highest quality)
+    "elevenLabsModel": "eleven_turbo_v2_5",
+    
+    // Voice tuning (0.0 to 1.0)
+    "elevenLabsStability": 0.5,       // Lower = more expressive, Higher = more consistent
+    "elevenLabsSimilarity": 0.75,     // How closely to match the original voice
+    "elevenLabsStyle": 0.5,           // Style exaggeration (higher = more expressive)
+    
+    // ============================================================
+    // EDGE TTS SETTINGS (Free Neural Voices - Fallback)
+    // ============================================================
+    // Requires: pip install edge-tts
+    
+    // Voice options (run 'edge-tts --list-voices' to see all):
+    //   'en-US-AnaNeural'   - Young, cute, cartoon-like
+    //   'en-US-JennyNeural' - Friendly, warm
+    //   'en-US-AriaNeural'  - Confident, clear
+    "edgeVoice": "en-US-AnaNeural",
+    
+    // Pitch adjustment: +0Hz to +100Hz (higher = more anime-like)
+    "edgePitch": "+50Hz",
+    
+    // Speech rate: -50% to +100%
+    "edgeRate": "+10%",
+    
+    // ============================================================
+    // SAPI SETTINGS (Windows Built-in - Last Resort Fallback)
+    // ============================================================
+    
+    // Voice (run PowerShell to list all):
+    //   Add-Type -AssemblyName System.Speech; (New-Object System.Speech.Synthesis.SpeechSynthesizer).GetInstalledVoices() | % { $_.VoiceInfo.Name }
+    "sapiVoice": "Microsoft Zira Desktop",
+    "sapiRate": -1,
+    "sapiPitch": "medium",
+    "sapiVolume": "loud",
+    
+    // ============================================================
+    // INITIAL TTS MESSAGES (Used immediately or after sound)
+    // These are randomly selected each time
+    // ============================================================
+    
+    // Messages when agent finishes work
+    "idleTTSMessages": [
+        "All done! Your task has been completed successfully.",
+        "Hey there! I finished working on your request.",
+        "Task complete! Ready for your review whenever you are.",
+        "Good news! Everything is done and ready for you.",
+        "Finished! Let me know if you need anything else."
+    ],
+    
+    // Messages for permission requests
+    "permissionTTSMessages": [
+        "Attention please! I need your permission to continue.",
+        "Hey! Quick approval needed to proceed with the task.",
+        "Heads up! There is a permission request waiting for you.",
+        "Excuse me! I need your authorization before I can continue.",
+        "Permission required! Please review and approve when ready."
+    ],
+
+    // ============================================================
+    // TTS REMINDER MESSAGES (More urgent - used after delay if no response)
+    // These are more personalized and urgent to get user attention
+    // ============================================================
+    
+    // Reminder messages when agent finished but user hasn't responded
+    "idleReminderTTSMessages": [
+        "Hey, are you still there? Your task has been waiting for review.",
+        "Just a gentle reminder - I finished your request a while ago!",
+        "Hello? I completed your task. Please take a look when you can.",
+        "Still waiting for you! The work is done and ready for review.",
+        "Knock knock! Your completed task is patiently waiting for you."
+    ],
+    
+    // Reminder messages when permission still needed
+    "permissionReminderTTSMessages": [
+        "Hey! I still need your permission to continue. Please respond!",
+        "Reminder: There is a pending permission request. I cannot proceed without you.",
+        "Hello? I am waiting for your approval. This is getting urgent!",
+        "Please check your screen! I really need your permission to move forward.",
+        "Still waiting for authorization! The task is on hold until you respond."
+    ],
+    
+    // ============================================================
+    // SOUND FILES (For immediate notifications)
+    // These are played first before TTS reminder kicks in
+    // Paths are relative to OpenCode config directory (~/.config/opencode/)
+    // ============================================================
+    
+    "idleSound": "assets/Soft-high-tech-notification-sound-effect.mp3",
+    "permissionSound": "assets/Machine-alert-beep-sound-effect.mp3",
+    
+    // ============================================================
+    // GENERAL SETTINGS
+    // ============================================================
+    
+    "wakeMonitor": true,           // Wake monitor when notifying
+    "forceVolume": true,           // Force volume up if too low
+    "enableToast": true,           // Show TUI toast notifications
+    "enableSound": true,           // Enable audio notifications
+    "volumeThreshold": 50,         // Force volume if below this level
+    "idleThresholdSeconds": 60,    // Consider monitor asleep after this
+    "debugLog": false              // Enable debug logging to file
+}