Voice Transcription Skill

This skill enables local voice transcription using whisper.cpp for privacy-preserving speech-to-text.

When to Use This Skill

Use this skill when the user:

• Explicitly asks to record voice or use voice input
• Wants to describe something verbally instead of typing
• Needs to transcribe audio
• Says phrases like "let me speak", "record this", "voice input"
• Would benefit from speaking complex information rather than typing

Automatic Setup

The transcription script now includes:

• Installation detection - Checks if VoiceType is properly installed
• Auto-start - Automatically starts whisper.cpp server if not running

If the script detects missing installation, it will return JSON with "installation_needed": true. When you see this:

1. Offer to run installation:

`` "It looks like VoiceType isn't fully installed. Would you like me to run the installer? I can do this with: /voicetype-install" ``

1. If user agrees, run:

``bash bash install.sh ` Or use the /voicetype-install` command which provides guided installation.

Prerequisites (Automatic)

The script automatically handles:

• ✅ Checks for installation - Verifies venv, whisper binary, and scripts exist
• ✅ Starts whisper server - Auto-starts from .whisper/bin/ if not running
• ✅ Downloads model - First-time use downloads whisper model automatically

You don't need to manually check the server - the script does it!

How to Transcribe Voice

1. Run the transcription script:

``bash source venv/bin/activate && python skills/voice/scripts/transcribe.py --duration 5 ``

The script automatically: - ✅ Checks installation (offers /voicetype-install if needed) - ✅ Starts whisper server if not running - ✅ Records audio from microphone for specified duration (default 5 seconds) - ✅ Transcribes via local whisper.cpp server (localhost:2022) - ✅ Returns JSON with transcribed text

1. Parse the output:

- Success: {"text": "transcribed speech", "duration": 5} - Installation needed: {"error": "...", "installationneeded": true, "missingcomponents": [...], "help": [...]} - Transcription error: {"error": "error message", "help": [...]}

1. Handle installation_needed:

If JSON contains "installation_needed": true: - Inform user: "VoiceType needs to be installed first." - Offer: "Would you like me to run the installer? Use: /voicetype-install or I can run: bash install.sh" - Wait for user confirmation before proceeding

Example Usage Flows

Scenario 1: Normal Transcription (Installed)

User: "Let me record a voice note about the bug I'm seeing"

Assistant:

1. Informs user: "I'll record for 5 seconds. Speak when ready..."
2. Runs transcription script (auto-starts server if needed)
3. Receives: {"text": "The submit button isn't working when I click it on the checkout page"}
4. Responds: "I transcribed: 'The submit button isn't working when I click it on the checkout page.' Let me help you investigate this issue..."

Scenario 2: First-Time Use (Not Installed)

User: "Record my voice"

Assistant:

1. Runs transcription script
2. Receives: {"error": "VoiceType is not fully installed", "installationneeded": true, "missingcomponents": ["Python venv", "whisper.cpp binary"]}
3. Responds: "It looks like VoiceType isn't installed yet. Would you like me to run the installer? I can guide you through it with: /voicetype-install or directly run: bash install.sh"
4. User confirms
5. Runs /voicetype-install or bash install.sh
6. After installation: "Installation complete! Now let's try voice transcription..."

Script Options

The transcription script accepts optional parameters:

• --duration N - Record for N seconds (1-30, default 5)
• Example: python skills/voice/scripts/transcribe.py --duration 10

Troubleshooting

If transcription fails:

1. Check microphone access:

``bash python -c "import sounddevice as sd; print(sd.query_devices())" ``

1. Verify whisper server:

``bash systemctl --user status whisper-server journalctl --user -u whisper-server -n 20 ``

1. Test the script directly:

``bash cd /path/to/voicetype source venv/bin/activate python skills/voice/scripts/transcribe.py ``

Privacy Note

All voice processing happens locally:

• Audio recorded via sounddevice (local microphone)
• Transcription via whisper.cpp server (localhost only)
• No data sent to cloud services
• Audio files are temporary and deleted after transcription