Youtube transcript

YouTube Transcript

Overview

Extracts a plain-text transcript from any YouTube video or Short. Prefer existing captions first (fast, no transcription needed); fall back to local audio transcription with faster-whisper only when no captions exist.

When to Use

• User gives a YouTube URL and wants the transcript / captions / subtitles.
• User wants a video summarized, quoted, or analyzed and the words are needed first.
• Any task gated on "what was said" in a YouTube video or Short.

Requirements

Check these exist before starting; install whatever's missing (prefer an isolated venv over polluting the system Python):

• yt-dlp — pip install yt-dlp or brew install yt-dlp
• ffmpeg — required only for the whisper fallback (brew install ffmpeg / apt install ffmpeg)
• faster-whisper — pip install faster-whisper, only needed if Step 3 runs

Workflow

Step 1 — Resolve video id and title

yt-dlp --no-warnings --print "%(id)s" --skip-download "<url>"
yt-dlp --no-warnings --print "%(title)s" --skip-download "<url>"

Use these to name the output file, e.g. <safe-title>_<id>.txt. Sanitize the title (strip to alphanumerics/spaces/._-, replace spaces with _) before using it in a filename.

Step 2 — Try captions (manual, then auto-generated)

Work in a scratch directory. Fetch subtitles without downloading video:

yt-dlp --no-warnings --skip-download \
  --write-subs --write-auto-subs \
  --sub-langs "en.*,en" --sub-format vtt --convert-subs vtt \
  -o "<scratch-dir>/sub.%(ext)s" "<url>"

If a .vtt file appears, clean it to plain text and stop — no transcription needed. Clean it with an inline script (strips WEBVTT headers, timestamp cues, cue numbers, inline tags, and de-duplicates repeated lines — YouTube's auto-captions repeat the same line across consecutive cues):

python3 - "<scratch-dir>/sub.en.vtt" <<'PY'
import re, sys
path = sys.argv[1]
out, seen_last = [], None
with open(path, encoding="utf-8", errors="ignore") as f:
    for line in f:
        line = line.rstrip("\n")
        if not line.strip():
            continue
        if line.startswith(("WEBVTT", "Kind:", "Language:", "NOTE")):
            continue
        if "-->" in line:
            continue
        if re.fullmatch(r"\d+", line.strip()):
            continue
        line = re.sub(r"<[^>]+>", "", line)
        line = re.sub(r"\s+", " ", line).strip()
        if not line or line == seen_last:
            continue
        seen_last = line
        out.append(line)
print(" ".join(out))
PY

Redirect stdout to the output .txt file. Done — read that file for the transcript.

Step 3 — Fallback: download audio and transcribe

Only if no .vtt file was found in Step 2:

yt-dlp --no-warnings -x --audio-format mp3 --audio-quality 0 \
  -o "<scratch-dir>/audio.%(ext)s" "<url>"

Then transcribe locally with faster-whisper:

python3 - "<scratch-dir>/audio.mp3" "<output>.txt" "base" <<'PY'
import sys
from faster_whisper import WhisperModel

audio, out_file, model_size = sys.argv[1], sys.argv[2], sys.argv[3]
model = WhisperModel(model_size, device="auto", compute_type="int8")
segments, info = model.transcribe(audio, beam_size=5, vad_filter=True)
print(f"[detected language: {info.language} (p={info.language_probability:.2f})]", file=sys.stderr)
with open(out_file, "w", encoding="utf-8") as f:
    f.write(" ".join(seg.text.strip() for seg in segments).strip() + "\n")
PY

model_size defaults to base; bump to small or medium for hard-to-hear audio (slower on CPU). Long videos via whisper can take minutes — warn the user and consider running in the background.

Common Mistakes

• Assuming captions always exist. Many videos (non-English, niche, or creator-disabled) have none — always check for a produced .vtt file before falling back to whisper.
• Skipping the language filter. Without --sub-langs, yt-dlp may grab non-English subtitles by default.
• Not de-duplicating caption lines. Auto-captions repeat the same line across consecutive cues; skip a line if it matches the previous one, or the transcript reads with stutter.
• Forgetting ffmpeg before Step 3. Both yt-dlp's audio extraction and whisper need it — check it's installed before starting the fallback, not after it fails partway through.
• Long whisper runs blocking the session. CPU transcription of a long video can take several minutes; run it in the background and poll rather than blocking.