# En
> 
- Skill: `ellmos-ai/en-19` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ellmos-ai/en-19`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ellmos-ai/en-19/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ellmos-ai (https://skillmd.com/u/ellmos-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ellmos-ai/en-19
---
> **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
```bash
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).
```bash
# 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
| Option | Effect |
|--------|--------|
| `--format markdown\|json\|plain` | Output format (default: markdown) |
| `--output, -o ` | Write to file instead of stdout |
| `--lang ` | Preferred subtitle languages (default: de en) |
| `--meta-only` | Metadata only, no transcript |
| `--transcript-only` | Transcript only, no metadata |
| `--no-timestamps` | Transcript without timestamps |
| `--no-meta` | Faster: skip yt-dlp metadata |
| `--allow-empty-transcript` | Treat an empty transcript as success (exit 0 instead of 3) |
### 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.
| Code | Meaning |
|------|---------|
| `0` | Success -- transcript present, or `--meta-only`, or `--allow-empty-transcript` |
| `1` | Not a valid video URL/ID |
| `2` | Usage error (assigned by argparse, e.g. unknown option) |
| `3` | No transcript retrieved -- both paths came back empty |
`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
```python
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