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:

   code

   "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

   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
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:

   bash

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

2. •

   Verify whisper server:

   bash

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

3. •

   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