whisper-video-transcriber

Paste a TikTok, YouTube or Instagram link and get the spoken text back. Audio is transcribed locally with faster-whisper on the CPU, so no cloud service hears your videos. Optionally, Claude breaks the transcript down: hook, structure with timestamps, why it works, call to action and an idea for your own content.

It also runs as an MCP server, so Claude Code (or any MCP client) can call it as a tool: "transcribe this TikTok and tell me why the hook works".

Built for content research in a homelab. On an 8-core LXC (AMD Ryzen 9 mini PC, Whisper medium, int8), a 45 s TikTok took 13.5 s and a 208 s video 53.5 s, roughly 4x faster than real time.

Full walkthrough (Proxmox LXC, Docker, Caddy, firewall, Claude Code):

• English: https://mapplebox.com/self-hosted-video-transcriber-whisper/

• Deutsch: https://mapplebox.de/tiktok-videos-transkribieren-whisper-selbst-hosten/

What's inside

Related MCP server: whipscribe-mcp

Quick start

Needs Docker with the Compose plugin on a Linux host (a Debian LXC on Proxmox works fine) and about 2 GB of disk for the Whisper medium model, which downloads on the first job.

git clone https://github.com/mapplebox/whisper-video-transcriber.git
cd whisper-video-transcriber
cp .env.example .env && chmod 600 .env    # then edit .env
mkdir -p data
docker compose up -d --build
curl http://127.0.0.1:8000/health

Open http://<host>:8000/ for the web UI.

Settings

In .env (never commit it):

In docker-compose.yml: WHISPER_MODEL (small is faster, large-v3 most accurate), WHISPER_COMPUTE, WHISPER_THREADS, DEFAULT_LANGUAGE (empty = auto-detect), MAX_DURATION_SECONDS (default 900).

Security

This is an internal tool. /api/* has no authentication unless you set API_TOKEN, and anyone who can call it can spend your Anthropic credit.

• Put it behind a reverse proxy that only allows your LAN / VPN (e.g. Caddy with remote_ip), never expose port 8000 to the internet.

• Docker-published ports bypass normal INPUT firewall rules. Restrict port 8000 in the DOCKER-USER chain so only the proxy can reach it, for example: iptables -I DOCKER-USER -i eth0 -p tcp --dport 8000 ! -s <proxy-ip> -j DROP Or publish it on 127.0.0.1:8000:8000 if the proxy runs on the same host.

• Keep .env at mode 600.

Claude Code

claude mcp add --transport http --scope user transcriber https://transcribe.example.com/mcp \
  --header "Authorization: Bearer YOUR-MCP-TOKEN"

Tools: transcribe_video, list_transcripts, get_transcript, analyze_transcript. Every transcribe_video call runs the analysis by default (costs API credit); ask for "without analysis" if you only want the text.

Notes

• TikTok: the audio-only stream is often just the attached sound (music), not the voice. The app downloads the smallest muxed video instead, which carries the real audio track.

• YouTube: at the time of writing, yt-dlp needs a JavaScript runtime for full YouTube support. Add Deno to the image: COPY --from=denoland/deno:bin-2.9.7 /deno /usr/local/bin/deno and install yt-dlp[default].

• Instagram: often needs cookies from a logged-in account; this code doesn't pass any.

• Updating yt-dlp: it's unpinned on purpose, rebuild with docker compose build --no-cache.

• The analysis prompt and the web UI are in German. Change ANALYSIS_PROMPT in app/main.py (keep the JSON keys, the UI reads them) and the labels in index.html for another language.

• Only use it for your own research and respect the platforms' terms and creators' rights. Don't republish other people's content.

License

MIT, see LICENSE.