--- name: add-voice-transcription-7edc90e4d9d1 description: Add voice message transcription to Deus using OpenAI's Whisper API. Automatically transcribes WhatsApp voice notes so the agent can read and respond to them. disable-model-invocation: true --- # Add Voice Transcription This skill adds automatic voice message transcription to Deus's WhatsApp channel using OpenAI's Whisper API. When a voice note arrives, it is downloaded, transcribed, and delivered to the agent as `[Voice: ]`. ## Phase 1: Pre-flight ### Check if already applied Check if `src/transcription.ts` exists. If it does, skip to Phase 3 (Configure). The code changes are already in place. ### Ask the user Use `AskUserQuestion` to collect information: AskUserQuestion: Do you have an OpenAI API key for Whisper transcription? If yes, collect it now. If no, direct them to create one at https://platform.openai.com/api-keys. ## Phase 2: Apply Code Changes **Prerequisite:** WhatsApp must be installed first (via `/add-whatsapp`). This skill modifies WhatsApp channel files. Voice transcription is part of the WhatsApp MCP package in `packages/`. Check if the transcription module already exists: ```bash test -f src/transcription.ts && echo "Already present" || echo "Not present" ``` If not present, the WhatsApp MCP package should include voice transcription support. Ensure the WhatsApp channel is installed and up to date by running `/add-whatsapp`. The following files are involved: - `src/transcription.ts` (voice transcription module using OpenAI Whisper) - Voice handling in `src/channels/whatsapp.ts` (isVoiceMessage check, transcribeAudioMessage call) - Transcription tests in `src/channels/whatsapp.test.ts` - `openai` npm dependency in `package.json` - `OPENAI_API_KEY` in `.env.example` ### Validate code changes ```bash npm install --legacy-peer-deps npm run build npx vitest run src/channels/whatsapp.test.ts ``` All tests must pass and build must be clean before proceeding. ## Phase 3: Configure ### Get OpenAI API key (if needed) If the user doesn't have an API key: > I need you to create an OpenAI API key: > > 1. Go to https://platform.openai.com/api-keys > 2. Click "Create new secret key" > 3. Give it a name (e.g., "Deus Transcription") > 4. Copy the key (starts with `sk-`) > > Cost: ~$0.006 per minute of audio (~$0.003 per typical 30-second voice note) Wait for the user to provide the key. ### Add to environment Add to `.env`: ```bash OPENAI_API_KEY= ``` Sync to container environment: ```bash mkdir -p data/env && cp .env data/env/env ``` The container reads environment from `data/env/env`, not `.env` directly. ### Build and restart ```bash npm run build launchctl kickstart -k gui/$(id -u)/com.deus # macOS # Linux: systemctl --user restart deus ``` ## Phase 4: Verify ### Test with a voice note Tell the user: > Send a voice note in any registered WhatsApp chat. The agent should receive it as `[Voice: ]` and respond to its content. ### Check logs if needed ```bash tail -f logs/deus.log | grep -i voice ``` Look for: - `Transcribed voice message` — successful transcription with character count - `OPENAI_API_KEY not set` — key missing from `.env` - `OpenAI transcription failed` — API error (check key validity, billing) - `Failed to download audio message` — media download issue ## Troubleshooting ### Voice notes show "[Voice Message - transcription unavailable]" 1. Check `OPENAI_API_KEY` is set in `.env` AND synced to `data/env/env` 2. Verify key works: `curl -s https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" | head -c 200` 3. Check OpenAI billing — Whisper requires a funded account ### Voice notes show "[Voice Message - transcription failed]" Check logs for the specific error. Common causes: - Network timeout — transient, will work on next message - Invalid API key — regenerate at https://platform.openai.com/api-keys - Rate limiting — wait and retry ### Agent doesn't respond to voice notes Verify the chat is registered and the agent is running. Voice transcription only runs for registered groups. --- Source attribution: sliamh11 Original project: https://github.com/sliamh11/Deus/blob/2f24c38a2ae42d3161492f0729975b286452f4b4/.claude/skills/add-voice-transcription/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Gavriel Copyright (c) 2026 Liam Steiner 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. # Mega AI Hub resource metadata Creator / publisher: sliamh11 Original project: https://github.com/sliamh11/Deus/blob/2f24c38a2ae42d3161492f0729975b286452f4b4/.claude/skills/add-voice-transcription/SKILL.md Attribution basis: Source repository record Fields of work: Sales, Customer Support Roles: Customer Success Manager, Sales Development Rep (SDR), Support Agent Specialties: API Tools: OpenAI API, WhatsApp, Whisper Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 6133ce502cc9a8b51091c95eb7a3d654f318ae093f90facce4a798dfde2cdbae