| name | audio-to-text-and-video-to-text |
| description | Transcribe audio and video files into text using OpenAI's Whisper API. Use this skill whenever a user wants to convert any audio or video file to text — including MP3, MP4, WAV, M4A, OGG, WEBM, MOV, AVI, FLAC, and more. Trigger this skill for any request involving: "transcribe", "convert audio to text", "speech to text", "get transcript of", "extract audio from video", "meeting notes from recording", "subtitles", "captions", or similar. Also trigger when the user uploads or references a media file and asks what was said, discussed, or mentioned in it. If unsure whether audio/video transcription is involved, use this skill.
|
Transcription Skill
Converts audio and video files into clean, readable text using OpenAI's Whisper API and ffmpeg for media handling.
Overview
This skill handles the full pipeline:
- Media extraction — use ffmpeg to strip audio from video files and convert to a Whisper-compatible format
- Chunking — split large files (>25 MB) into overlapping segments to stay within API limits
- Transcription — send each chunk to OpenAI's Whisper API
- Assembly — merge chunk transcripts, adjusting timestamps, into a single clean output
- Post-processing — optionally clean up with Claude (punctuation, speaker labels, summaries)
Requirements
- ffmpeg must be installed (
which ffmpeg to verify — it's usually pre-installed in claude.ai's environment)
- OpenAI API key stored in the environment as
OPENAI_API_KEY — the user must provide this
- Python packages:
openai, pydub (install via pip if needed)
Quick Start
When a user provides a media file, run the transcription script:
pip install openai pydub --break-system-packages -q
python /home/claude/transcription/scripts/transcribe.py \
--input "/path/to/media/file" \
--output "/mnt/user-data/outputs/transcript.txt" \
--api-key "$OPENAI_API_KEY"
See scripts/transcribe.py for the full implementation.
Supported Formats
| Category | Formats |
|---|
| Audio | mp3, wav, m4a, ogg, flac, aac, opus, wma |
| Video | mp4, mov, avi, mkv, webm, wmv, m4v |
ffmpeg handles extraction from any of these.
Options & Flags
| Flag | Default | Description |
|---|
--model | whisper-1 | Whisper model to use (whisper-1, gpt-4o-transcribe) |
--language | auto-detect | ISO 639-1 language code (e.g. en, ar, fr) |
--format | txt | Output format: txt, srt, vtt, json |
--timestamps | off | Include timestamps in output |
--chunk-size | 20 | Max chunk size in MB (must be ≤ 25) |
--prompt | none | Context hint to improve accuracy (e.g. domain vocab) |
Output Formats
- txt — plain text, ideal for most uses
- srt — SubRip subtitle format (for video players)
- vtt — WebVTT format (for web video)
- json — full Whisper JSON with segments and timestamps
Step-by-Step Workflow
1. Check for the file
Ask the user to upload the file or provide a local path. Check:
ls /mnt/user-data/uploads/
2. Check ffmpeg and install deps
which ffmpeg && ffmpeg -version 2>&1 | head -1
pip install openai pydub --break-system-packages -q 2>&1 | tail -3
3. Get the API key
If OPENAI_API_KEY is not set in the environment, ask the user:
"Please provide your OpenAI API key — it starts with sk-. You can get one at https://platform.openai.com/api-keys"
4. Run the script
python /home/claude/transcription/scripts/transcribe.py \
--input "<file_path>" \
--output "/mnt/user-data/outputs/transcript.txt"
5. Post-process (optional but recommended)
After transcription, offer to:
- Clean up punctuation/formatting with Claude
- Summarize the content
- Extract action items, speakers, or key topics
- Translate to another language
Use the transcript text directly in the conversation for these steps.
Handling Large Files
The script automatically splits files > 20 MB into overlapping chunks (with 1-second overlap for continuity). Each chunk is transcribed separately and the results are merged.
For very long recordings (> 1 hour), warn the user it may take a few minutes and show progress.
Error Handling
| Error | Fix |
|---|
AuthenticationError | Invalid API key — ask user to verify |
RateLimitError | Wait 60s and retry, or use --chunk-size 10 |
InvalidRequestError: file too large | Reduce --chunk-size below 25 |
ffmpeg not found | sudo apt install ffmpeg or brew install ffmpeg |
No audio stream found | File may be corrupt or wrong format |
Example Interaction
User: "Can you transcribe this meeting recording?"
[uploads meeting.mp4]
→ Check file exists in /mnt/user-data/uploads/
→ Run transcribe.py on it
→ Save transcript to /mnt/user-data/outputs/
→ present_files() to the user
→ Offer to summarize or extract action items
Notes for openclaw.ai
- Always save output to
/mnt/user-data/outputs/ so users can download it
- Use
present_files() to share the transcript file with the user after saving
- For business users, suggest the
srt or vtt format if they're adding captions to video
- The
--prompt flag is useful for technical/domain-specific content: pass a few domain keywords to improve accuracy
