Communitygithub.com

YouTube / Audio Transcription

Transcribe a YouTube video or any local audio/video file into a text transcript, SRT subtitles, and JSON using a local whisper engine. Use this whenever the user shares a YouTube URL and wants subtitles, captions, transcript, or a verbatim script — especially when the video has no captions to download — or wants to transcribe an audio or video file. Triggers on requests like "please grab the subtitles/transcript for this YouTube video", "transcribe this video", or "convert this audio file to text". Runs locally and is cross-platform: mlx-whisper on Apple Silicon, faster-whisper elsewhere.

What is Audio Transcription?

This skill provides a robust, fully local solution for transcribing YouTube videos or local audio/video files into text transcripts, SRT subtitles, and JSON output. It is particularly valuable when a YouTube video lacks subtitles or auto-captions, which often happens with re-uploads and some Chinese-language content. The skill automatically selects the optimal whisper engine based on the platform: `mlx-whisper` (GPU-accelerated) on Apple Silicon Macs, and `faster-whisper` (CPU or CUDA) on Intel Macs, Linux, or Windows. It uses `uv` to manage dependencies without polluting the global environment and requires a JavaScript runtime (node, bun, or deno) for YouTube extraction. The workflow downloads audio via `yt-dlp`, normalizes it to a 16 kHz mono WAV file (using ffmpeg or macOS's built-in `afconvert`), and then transcribes it with the chosen whisper engine. The script handles all preprocessing internally, avoiding common pitfalls like `FileNotFoundError: ffmpeg`. Output files include a plain-text transcript, timestamped SRT subtitles, and a rich JSON file with per-segment timestamps and detected language. It also includes a post-processing step that converts Simplified Chinese output to Traditional Chinese and cleans up technical terms, presenting a tidy summary to the user.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/chenwei791129/agent-skills/tree/HEAD/skills/youtube-transcribe

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does Audio Transcription do?

Turn a YouTube video — or any local audio/video file — into a transcript without relying on YouTube-provided captions. Many videos (especially re-uploads and some Chinese-language uploads) have no subtitles and no auto-captions, so downloading captions with yt-dlp --write-subs returns nothing. This skill sidesteps that by downloading the audio and transcribing it locally with a whisper engine chosen by platform.

When to reach for this

  • The user gives a YouTube URL and wants the transcript / captions / subtitles.
  • yt-dlp --list-subs reports has no subtitles / has no automatic captions.
  • The user has a local .m4a/.mp3/.mp4/etc. file to transcribe.

Prerequisites

  • uv installed (used to run yt-dlp and the transcription script without polluting the global env). The script auto-selects the whisper engine, and uv installs only the one your platform needs:
    • Apple Silicon Mac → mlx-whisper (MLX/Metal, GPU-accelerated).
    • Intel Mac / Linux / Windows → faster-whisper (CTranslate2, CPU or NVIDIA CUDA).
  • A JavaScript runtime — node, bun, or deno — on PATH. Recent yt-dlp needs one to extract YouTube; the script auto-detects whichever is present.
  • ffmpeg recommended but not required: if absent, the script falls back to macOS's built-in afconvert (so on non-macOS, install ffmpeg).

Usage

The whole pipeline is one self-contained script. Run it with uv run so dependencies are provisioned automatically:

uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py \
  "https://www.youtube.com/watch?v=VIDEO_ID" \
  --output-dir /tmp/whisper_out

Common options:

  • --language zh — force a language instead of auto-detecting (faster, avoids mis-detection on bilingual intros).
  • --model mlx-community/whisper-large-v3-turbo — the default; good speed/quality on Apple Silicon. Swap for mlx-community/whisper-large-v3 for max quality or a smaller model for speed.
  • --output-name my-video — base filename for outputs (defaults to the video id).
  • --formats txt,srt — pick which outputs to write (default txt,srt,json).

A local file works the same way — just pass a path instead of a URL:

uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py /path/to/talk.m4a --language en

The first run downloads the whisper model (~1.6 GB for turbo) into the Hugging Face cache; later runs reuse it.

Outputs

Written to --output-dir (default: current directory), named after the video id (or --output-name):

  • <name>.txt — plain-text transcript (one blob).
  • <name>.srt — subtitles with timestamps.
  • <name>.json — full result incl. per-segment timestamps and detected language.

After transcribing

The raw whisper output reflects the spoken language verbatim. If the audio is Mandarin, whisper emits Simplified Chinese. Per the user's global rule, when presenting the transcript in chat, convert it to Traditional Chinese and clean up obvious mis-hearings of proper nouns / technical terms (model names, CVE ids, tool names). Offer a tidied, sectioned summary rather than dumping the full wall of text, and tell the user where the full files live.

How it works (and why)

  1. Download audio — yt-dlp -f "bestaudio[ext=m4a]/bestaudio". Format 140 (128 kbps m4a) downloads without solving YouTube's player JS "n" challenge, so we avoid --remote-components ejs:github (it fetches+runs remote code and is typically blocked by the sandbox). The script prefixes uvx if yt-dlp isn't installed, and adds --js-runtimes <node|bun|deno> for whichever runtime exists.
  2. Normalize audio — convert to 16 kHz mono 16-bit WAV with ffmpeg, or macOS afconvert if ffmpeg is missing.
  3. Transcribe — read the WAV into a numpy float32 array and pass it straight to the engine (mlx_whisper.transcribe(...) on Apple Silicon, faster_whisper.WhisperModel.transcribe(...) elsewhere). Both produce the same normalized result shape (text / language / segments). Handing whisper a decoded array means it never shells out to ffmpeg internally — which is the usual cause of FileNotFoundError: ffmpeg on machines without it.

Troubleshooting

  • has no subtitles but you still want text — that's exactly this skill's job; proceed to transcribe the audio.
  • FileNotFoundError: ffmpeg — shouldn't happen via this script (it converts first), but if you call the whisper engine directly on an m4a, convert to WAV first.
  • On non-Apple-Silicon and conversion fails — afconvert is macOS-only, so install ffmpeg (Linux/Windows have no built-in fallback).
  • yt-dlp warns about JS challenge / "Only images are available" — ensure node/bun/deno is on PATH; the script needs one for extraction. Do not reach for --remote-components ejs:github to fix it.
  • Garbled / wrong-language output — pass --language explicitly.

Related Skills