Transcribe Anything

Turn any spoken audio or video into a transcript and subtitles. The mental model is always the same three moves:

1. Acquire the audio — either it's already a file you have, or you pull it from a URL with yt-dlp.
2. Transcribe it with a Whisper-family model.
3. Emit a .txt transcript and a .srt subtitle file, then clean up the audio (after confirming, unless told otherwise).

The reason this skill exists is that step 1 is where things quietly fail, and where the work runs matters more than the code. Get the routing right and the rest is easy. So start there.

Nothing to configure. Unlike the scheduling skills in this repo, this one needs no accounts, API keys or recorded settings — it installs its own dependencies. The only thing it needs from you is the media (or a URL), and for some sources, permission to run on your own machine rather than in a sandbox. Step 0 works out which.

Step 0 — Decide the input type and where it can run

This decision determines everything else. Don't skip it. The key fact: some platforms block downloads from datacenter/cloud IPs (which is what this sandbox is) but not from a person's home/office connection. Reason it through:

If you're unsure whether a platform blocks, it's cheap to just try it in the sandbox once — a bot-check or 503 tells you immediately to route local.

When the answer is "local only," don't fake it. You cannot run software on the user's machine and this sandbox is blocked, so the honest move is to hand them a runner they execute locally (next section). Never invent a transcript for media you couldn't actually hear — a fabricated transcript is far worse than an honest "run this and paste me the output."

Running in the sandbox (uploaded files & open platforms)

For uploaded files this is the whole job; for open-platform URLs it works once the proxy's certificate is trusted.

Fix SSL first (one time per sandbox session) — yt-dlp and Python requests fail TLS verification against the egress proxy's self-signed cert until you append the gateway CAs to certifi's bundle:

CERTIFI=$(python3 -c "import certifi; print(certifi.where())")
for f in /usr/local/share/ca-certificates/egress-gateway-ca-*.crt \
         /usr/local/share/ca-certificates/swp-ca-*.crt; do
  [ -f "$f" ] && { printf '\n' >> "$CERTIFI"; cat "$f" >> "$CERTIFI"; }
done

Then install and run:

pip install --break-system-packages -q yt-dlp faster-whisper
python3 scripts/transcribe.py "<url-or-/mnt/user-data/uploads/file>" --out-dir /mnt/user-data/outputs

Uploaded files live under /mnt/user-data/uploads/. Pass the path directly — no download, no SSL fix needed for that case.

Running locally (YouTube, Instagram, private, or big batches)

Hand the user scripts/transcribe.py. If they're not set up with Python tooling (no yt-dlp, no Whisper on PATH — common), give them the self-bootstrapping runner instead: scripts/transcribe_local.sh. It builds its own private virtualenv, installs yt-dlp + whisper-ctranslate2 into it, needs no admin password and no system ffmpeg (the av/PyAV wheel bundles ffmpeg libraries, and a single progressive download needs no muxing), and then transcribes. The user runs exactly one command:

bash ~/Downloads/transcribe_local.sh

Key local-only details, explained so you can adapt them:

• --cookies-from-browser chrome lets yt-dlp borrow the user's logged-in session, which is what makes private/age-gated/region-locked content reachable. macOS will prompt for the login keychain password to read the cookie store — that's the OS asking, normal and safe; the user types it into Apple's own dialog. Swap chrome for safari/firefox/brave/edge to match their browser.
• Batches should be resumable. These runs get interrupted by rate limits. Skip any item whose transcript already exists so re-running just continues.
• Offer to wire it as a Claude Code slash command (~/.claude/commands/ transcribe.md containing Run: python3 /full/path/transcribe.py $ARGUMENTS) or a shell alias, since this user reuses these as CLI tools.

For private collections and playlists (enumerating items, browser-driven extraction), read references/private-and-batch.md.

Smoothest batch hand-off (prefer this for collections)

Handing over transcribe.py + transcribe_local.sh + a long pasted list of URLs works, but it has friction and depends on the user's Python version. When you already know the fixed set of items (an enumerated IG collection, a playlist), the smooth path is to give the user one self-contained script with the IDs baked in, run with a single bare command:

bash ~/Downloads/collection_runner.sh

Copy scripts/collection_runner.sh, paste the enumerated shortcodes/URLs into its ITEMS=( ... ) array, set PLATFORM/BROWSER/MODEL, and deliver that one file. It calls yt-dlp + whisper-ctranslate2 directly (so it never hits transcribe.py's import path), reuses an already-built venv, uses the user's browser cookies, is resumable, and leaves photo-only posts alone. This is the flow that runs cleanly end-to-end in practice.

The script

scripts/transcribe.py is the unified CLI. It accepts one or more URLs and/or local file paths, auto-detects whether each needs downloading, and writes .srt + .txt per item. Read the top of the file for the full flag list; the ones that matter most:

• --model — tiny|base|small|medium|large-v3 (default base; bigger = more accurate + slower). small is a good speed/quality balance for talking-head content.
• --engine — faster-whisper (default), whisper-cpp, or openai-whisper. See references/backends.md for when to pick which.
• --language — force a language (e.g. pl, en) to skip auto-detect.
• --cookies-from-browser <browser> — for local private/blocked content.
• --out-dir, --keep-audio, -y/--yes — output location and cleanup policy.

If a plain-CLI Whisper isn't installed but whisper-ctranslate2 is (the self-bootstrap case), the script falls back to it automatically.

Python version gotcha: macOS ships Python 3.9 as python3, which chokes on X | None type hints evaluated at function-definition time. transcribe.py guards against this with from __future__ import annotations at the top — keep that line. If you ever see TypeError: unsupported operand type(s) for | on a user's machine, that import is missing or the venv is using an old Python. collection_runner.sh sidesteps the issue entirely by not importing the script.

Batch behavior (get this right — it's what makes it usable)

When given many items (a playlist, a folder, a list of URLs, an enumerated collection):

• Process them one by one with a clear [3/25]-style progress line.
• Skip items already transcribed (check for the output file) so an interrupted run resumes cleanly on re-invocation.
• Continue past failures — one dead link shouldn't halt the batch.
• Leave no-audio items alone and report them at the end. Not every saved post is a video; photo posts simply have no audio, and that's fine — collect their IDs and list them in a short summary rather than erroring.

Output

Per source you produce two files named after the source (title or ID):

• <name>.txt — plain transcript, paragraph text.
• <name>.srt — timestamped subtitles ready for video editors / uploads.

Write them to --out-dir (default: current directory; in-sandbox use /mnt/user-data/outputs).

Being a good citizen

This skill is for transcribing content the user owns or has legitimate access to — their own recordings, uploads, or their own saved/subscribed media — for personal reference, captioning, notes, or accessibility. Keep two things in mind and mention them when relevant:

• Music/lyrics. If a track is a song, Whisper will attempt the lyrics, but reproducing song lyrics is a copyright problem. Flag music-driven items and note them rather than treating garbled lyric output as a useful "transcript."
• Other people's private content. Don't help pull login-only content the user doesn't actually have access to. Using their own logged-in session to reach their own saved items is fine; circumventing access they don't have is not.

Reference files

Load these as needed — don't read them all up front:

• references/environments.md — sandbox vs. local specifics, the SSL cert fix in depth, the full per-platform blocking picture, and how to test quickly.
• references/private-and-batch.md — private IG saved collections, playlists, channels; enumerating items from a logged-in browser; cookies handling.
• references/backends.md — faster-whisper vs. whisper.cpp vs. openai-whisper vs. parakeet: install, speed/accuracy tradeoffs, and how to choose.