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"
   

2. If user agrees, run:

   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:

   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

2. Parse the output:

   • Success: {"text": "transcribed speech", "duration": 5}
   • Installation needed: {"error": "...", "installation_needed": true, "missing_components": [...], "help": [...]}
   • Transcription error: {"error": "error message", "help": [...]}

3. 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", "installation_needed": true, "missing_components": ["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:

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

2. Verify whisper server:

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

3. Test the script directly:

   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