transcribe
A Claude Code plugin that transcribes audio and video files into organized markdown documents with speaker diarization.
Features
- Transcribes any audio format (m4a, mp3, wav, ogg, flac, etc.)
- Transcribes any video format (mp4, mkv, mov, avi, webm, etc.) — extracts audio automatically
- Speaker diarization (identifies who said what)
- Three output formats: Summary + Transcript, Summary only, or Transcript only
- Guided first-time setup — walks you through everything below
- Supports local or remote (SSH) server deployment
Prerequisites
On your local machine (where Claude Code runs)
| Dependency | Purpose | Install |
|---|
| Claude Code | Plugin host | claude.com/claude-code |
| ffmpeg / ffprobe | Video-to-audio extraction, duration probing | sudo apt install ffmpeg (Debian/Ubuntu) or brew install ffmpeg (macOS) |
| Python 3.8+ | Only needed if running the MCP server locally | sudo apt install python3 python3-venv |
| SSH client | Only needed if the MCP server is on a remote host | Pre-installed on most systems |
On the MCP server host (local or remote)
| Dependency | Purpose | Install |
|---|
| Python 3.8+ | Runs the transcription server | sudo apt install python3 python3-venv python3-pip |
| ffmpeg | Converts audio to MP3 before uploading to AssemblyAI | sudo apt install ffmpeg |
| AssemblyAI API key | Speech-to-text engine | Free account at assemblyai.com |
Installation
# Add the marketplace (one-time)
claude plugin marketplace add https://github.com/3D-Stories/transcribe.git
# Install the plugin
claude plugin install transcribe@transcribe
To update later:
claude plugin update transcribe@transcribe
To reinstall from scratch:
claude plugin remove transcribe@transcribe
claude plugin install transcribe@transcribe
Usage
/transcribe path/to/recording.mp4
/transcribe meeting-notes.m4a
On first run, the skill walks you through setup (see Architecture for what gets installed where).
Output
Transcripts are written to a transcripts/ directory in your project:
transcripts/<filename>_summary.md — structured summary with key decisions, action items, and timelinetranscripts/<filename>_transcription.md — full speaker-labeled transcript with timestamps
Architecture
The plugin has two parts: the skill (runs inside Claude Code) and the MCP server (runs on a host you choose).
┌─────────────────────────────────────────────────────────┐
│ Your machine (Claude Code) │
│ │
│ /transcribe skill │
│ ├── Validates input file │
│ ├── Extracts audio from video (ffmpeg) │
│ ├── Estimates cost, asks for approval │
│ ├── Transfers audio to MCP server host (SCP or cp) │
│ ├── Calls transcribe_audio() on the server │
│ └── Structures results into markdown │
│ │
│ .transcribe-config.json ← points to the server │
└──────────────────────┬──────────────────────────────────┘
│ SCP + SSH (or local if same machine)
┌──────────────────────▼──────────────────────────────────┐
│ MCP Server Host (local or remote) │
│ │
│ <install_path>/ e.g. /opt/mcp-servers/ │
│ └── transcribe-mcp/ transcribe-mcp/ │
│ ├── server.py ← FastMCP server wrapping │
│ │ AssemblyAI API │
│ ├── .venv/ ← Python virtualenv with │
│ │ assemblyai, python-dotenv, │
│ │ mcp packages │
│ ├── .env ← ASSEMBLYAI_API_KEY=... │
│ │ (chmod 600) │
│ └── requirements.txt │
└─────────────────────────────────────────────────────────┘
What gets installed where
3D-Stories
