jeffvincent/voice-memo-transcriber

Voice Memo Transcriber

Overview

This skill automatically transcribes voice memo files into plain text using OpenAI's Whisper (open-source, local processing). It handles multiple audio/video formats, generates both plain text and timestamped SRT files, and provides a summary of the content.

All processing happens locally - no data is sent to cloud services. Voice memos may contain sensitive information, so privacy is maintained throughout.

When to Apply

Use this skill when:

• User provides a voice memo file path and asks to "transcribe" it
• User says "create a transcript" from an audio/video file
• User wants to convert a voice recording to text
• User needs both plain text and timestamped SRT output from audio
• User mentions formats like .m4a, .mp3, .mov, .mp4, .wav, or QuickTime files

Do NOT use this skill for:

• Real-time transcription of ongoing audio
• Speaker diarization (identifying different speakers)
• Translation to other languages
• Editing or cleaning up existing transcripts

Inputs

Required:

• file_path: Absolute path to voice memo file
  • Supported formats: .m4a, .mp3, .mov, .mp4, .wav, .aac, .flac, .ogg, .webm
  • File must exist and contain audio

Optional:

• output_dir: Directory for output files
  • Default: Same directory as source file
  • Must be writable
• whisper_model: Whisper model size (affects accuracy and speed)
  • Default: "base"
  • Options: tiny, base, small, medium, large
  • Larger models = better accuracy but slower processing

Outputs

Generated files (in output directory):

1. [filename].txt - Plain text transcript with no timestamps
2. [filename].srt - Subtitle file with timestamps (HH:MM:SS,mmm format)
3. [filename].mp3 - Audio file (if conversion from another format was needed)

Displayed to user:

• Processing progress updates
• Summary of transcript content (1-3 sentences generated by Claude)
• File paths for all generated outputs
• Total processing time

Instructions for Claude

Step 1: Validate Input

• Check that file_path exists using Read or Bash tool
• Verify file has audio/video extension
• If output_dir specified, verify it exists and is writable
• If whisper_model specified, verify it's one of: tiny, base, small, medium, large

Step 2: Check and Install Dependencies

Run these checks in sequence:

Check ffmpeg:

which ffmpeg

If not found, provide installation instructions:

• macOS: brew install ffmpeg
• Linux: sudo apt-get install ffmpeg or sudo yum install ffmpeg
• Windows: Download from https://ffmpeg.org/download.html

Check pipx:

which pipx

If not found, install:

brew install pipx
pipx ensurepath

Check openai-whisper:

pipx list | grep openai-whisper

If not found, install:

pipx install openai-whisper

Step 3: Prepare Audio File

Determine output directory:

• If user specified output_dir, use it
• Otherwise, extract directory from file_path

Check if file is already MP3:

• If yes, skip conversion
• If no, convert using ffmpeg:

ffmpeg -i "[input_file]" -vn -ar 16000 -ac 1 -b:a 96k "[output_dir]/[basename].mp3"

Flags explained:

• -vn: No video (audio only)
• -ar 16000: 16kHz sample rate (Whisper's native rate)
• -ac 1: Mono audio
• -b:a 96k: 96kbps bitrate (good quality, small size)

Step 4: Transcribe with Whisper

Run Whisper transcription:

whisper "[audio_file]" \
  --model [whisper_model] \
  --output_dir "[output_dir]" \
  --output_format txt \
  --output_format srt \
  --language English

This generates both .txt and .srt files automatically.

Important notes:

• First run will download the model (base model ~140MB)
• Transcription time varies: ~1-5 minutes for 10-minute audio with base model
• Provide progress updates to user while processing

Step 5: Read and Summarize Transcript

• Use Read tool to read the generated .txt file
• Generate a concise 1-3 sentence summary of the content
• Focus on main topics, key points, or action items if present

Step 6: Report Results

Display to user:

✓ Transcription complete!

Files generated:
- Transcript: [path]/[filename].txt
- Subtitles: [path]/[filename].srt
- Audio: [path]/[filename].mp3 (if converted)

Summary:
[Your 1-3 sentence summary here]

Processing time: [X] seconds

Error Handling

File not found:

• Message: "Error: Could not find file at [path]. Please check the path and try again."

Unsupported format:

• Message: "Error: File format not supported. Supported formats: .m4a, .mp3, .mov, .mp4, .wav, .aac, .flac, .ogg, .webm"

Missing dependencies:

• Provide clear installation instructions for the missing tool
• Ask user to install and re-run the skill

Corrupted audio:

• Message: "Error: Could not process audio file. The file may be corrupted or empty."

Insufficient disk space:

• Message: "Error: Insufficient disk space. Transcription requires approximately [size] of free space."

Examples

See resources/EXAMPLES.md for complete examples.

Testing Checklist

See resources/CHECKLIST.md for validation steps.

Security and Privacy

Local Processing:

• All transcription happens on the user's machine
• No data sent to external servers or APIs
• Whisper models cached locally after first download

Sensitive Content:

• Voice memos may contain personal, medical, or business-sensitive information
• All files remain local and private
• Consider adding output directories to .gitignore

File Handling:

• Never commit voice files or transcripts to version control
• Respect user's specified output directory
• Clean up temporary files if conversion was needed (optional - ask user)

Dependencies:

• ffmpeg, pipx, and openai-whisper are all open-source tools
• Models are downloaded from HuggingFace's official repository
• No telemetry or tracking in any dependency