En

English — Official English version of video-transcriber.

Video Transcriber (English)

Fetches transcripts (subtitles) and metadata (title, channel, date, views, description) of online videos. Prefers manually created subtitles, falls back to auto-generated ones. Output as Markdown, JSON, or plain text.

For every requested language, the fallback tries manual exact and base-language tracks before automatic exact and base-language tracks; arbitrary tracks follow only afterwards. An unreadable JSON3 track does not stop the fallback while another candidate remains available.

Currently supported source: YouTube (youtube.com, youtu.be, youtube-nocookie.com).

For videos, use this tool instead of summarizing content manually — the transcript is the reliable source.

Notice: This tool is not affiliated with, endorsed by, or sponsored by YouTube or Google. Use is at the user's own responsibility. Users are solely responsible for complying with the terms of service of the respective platform and applicable copyright law. No circumvention of DRM, paywalls, or access restrictions. No mass scraping. No redistribution of copyrighted transcripts without the rights holder's consent.

Dependencies and licenses

pip install youtube-transcript-api   # transcripts (required) — MIT license
pip install yt-dlp                   # metadata (optional, fallback: noembed) — Unlicense (Public Domain)

Usage

Windows note: Always set PYTHONIOENCODING=utf-8, otherwise umlauts and special characters break in the output (cp1252 encoding).

# Default: Markdown with timestamps (English)
PYTHONIOENCODING=utf-8 python video_transcriber.py "https://www.youtube.com/watch?v=VIDEO_ID"

# Choose output format (English)
PYTHONIOENCODING=utf-8 python video_transcriber.py URL --format markdown|json|plain

# Save to file (English)
PYTHONIOENCODING=utf-8 python video_transcriber.py URL -o transcript.md

# Prefer languages (default: de en) (English)
PYTHONIOENCODING=utf-8 python video_transcriber.py URL --lang de en fr

Options

Exit codes

An empty transcript is not a success. Before 1.2.0 this case exited with 0: the output file was written, the segment array was empty, and every calling script treated it as done. That silent failure is the defect 1.2.0 removes.

2 stays reserved for argparse so that a typo in the invocation remains distinguishable from a video that simply has no subtitles.

As a Python library

from video_transcriber import extract_video_id, fetch_metadata, fetch_transcript, format_markdown

video_id = extract_video_id("https://www.youtube.com/watch?v=VIDEO_ID")
meta = fetch_metadata(video_id)
transcript = fetch_transcript(video_id, languages=["de", "en"])
output = format_markdown(meta, transcript)

Typical use cases

• Research: make video content citable as text
• Source analysis: examine argumentation/metaphors in talks
• Summaries: transcript as a reliable basis instead of hallucination

Limits

• Only works if the video has subtitles (manual or automatic)
• Automatic subtitles can contain recognition errors
• No audio download, no built-in speech recognition -- the fallback path also fetches the subtitle track only, never video or audio
• The fallback path needs a JSON3 track; if the platform serves other formats only, the run ends with exit 3 rather than partial output

Changelog

1.2.0 (2026-08-24)

• Exit semantics: an empty transcript now exits 3 instead of silently 0. An invalid URL exits 1 as a named constant. --meta-only still succeeds, because no transcript is expected there.
• New option --allow-empty-transcript: deliberately treats an empty transcript as success, for callers that regard subtitles as optional.
• yt-dlp subtitle fallback: engages as soon as the primary path returns no segments (not only on an exception). Uses extract_info(download=False) and reads the subtitle URL only -- no video, no audio, no circumvention of access restrictions.
• Hardened language selection: de-orig/de-DE are now found for --lang de (base-language match). Per requested language, manual exact/base tracks precede automatic exact/base tracks, and unreadable candidates do not stop later fallback attempts.
• source field in the result: youtube_transcript_api or yt-dlp.
• Regression tests: 29 tests with mocked responses (UTF-8, all three output formats, exit codes, language selection, JSON3 parsing).

1.1.0 (2026-06-20)

• Renamed from yt-transcriber → video-transcriber (YouTube branding policy: "yt" is an explicitly forbidden abbreviation; see RECHTSCHECK_2026-06-20.md)
• Script: yt_transcriber.py → video_transcriber.py
• Disclaimer and dependency licenses added (user responsibility, ToS, no endorsement)
• YouTube mentioned descriptively as a source only, not as a name/brand component
• Backward-compat wrapper yt_transcriber.py retained at the old path

1.0.0 (2026-06-12)

• SKILL.md added (the tool already existed as a script + README)
• Script v1.0.0: transcript + metadata, 3 output formats, language preferences