Utilities
Fetch YouTube captions as text and JSONL
Public caption tracks to transcript.txt and results.jsonl.
overview
What youtube-transcript does
You have a YouTube watch URL, a youtu.be link, a Shorts URL, or an 11-character video id, and the useful part is the caption track, not the page HTML. Set --url or --video-id. The node talks to youtube-transcript-api, then writes transcript.txt, transcript.json, transcript.meta.json, and a results.jsonl row with backend, language, snippet count, and character count. That folder is what the next node reads.
A file of URLs or JSONL items goes on --items (or any file under /hive/in). Each line can be a URL or an object with url, link, or video_id. One video writes transcript.*; a batch writes 000-<id>.txt and friends. --languages is a comma-separated preference list (default en). --continue-on-error keeps going when one video has no captions.
The default --backend is auto: Dumpling if --dumpling-key or DUMPLING_API_KEY is set, otherwise the free API. Cloud fleet IPs often get blocked on the free path. Set --proxy or YOUTUBE_PROXY, pass --cookies a Netscape cookies.txt, or switch --backend dumpling. A missing caption track is a failed item, not a spoken transcript. Use whisper when you have audio and no captions.
use cases
Where youtube-transcript fits
Summarize one video from captions
Set --url and leave --backend at auto or api. Feed transcript.txt to an agent or script that writes a Markdown summary.
Batch a list of watch URLs
Pass --items a file of URLs or JSONL. Turn on --continue-on-error so one missing track does not stop the rest.
Prefer a language other than English
Set --languages to a comma-separated list such as de,en. The API tries the list in order, then any available track.
Retry when a cloud IP is blocked
Set --proxy or pass --cookies. Use --backend dumpling with --dumpling-key only when you have that key and the free API path failed.
reference
youtube-transcript inputs and flags
| Name | Type | Flag | Description |
|---|---|---|---|
| url | STRING | --url | YouTube watch, youtu.be, or Shorts URL. |
| video-id | STRING | --video-id | 11-character video id. Alternative to --url. |
| languages | STRING | --languages | Comma-separated language codes. Default en. |
| backend | STRING | --backend | auto, api, or dumpling. |
| items | FILE | --items | JSONL or URL list. Defaults to files under /hive/in. |
| proxy | STRING | --proxy | HTTP(S) proxy or webshare://user:pass@host. |
Showing key inputs. youtube-transcript exposes 9 inputs in total.
Full flag reference (9 inputs)
| Name | Type | Flag | Description |
|---|---|---|---|
| url | STRING | --url | YouTube watch / youtu.be / shorts URL. |
| video-id | STRING | --video-id | 11-char YouTube video id (alternative to url). |
| languages | STRING | --languages | Comma-separated preferred language codes (default: en). |
| backend | STRING | --backend | auto | api | dumpling (auto uses Dumpling when a key is set). |
| dumpling-key | STRING | --dumpling-key | Dumpling AI API key. Wire to ${{vars.DUMPLING_API_KEY}} on cloud fleets. |
| proxy | STRING | --proxy | HTTP(S) proxy or webshare://user:pass@host, or YOUTUBE_PROXY. |
| cookies | FILE | --cookies | Netscape cookies.txt for YouTube when cloud IPs are blocked. |
| items | FILE | --items | JSONL/JSON of items with url, link, or video_id (defaults to /hive/in). |
| continue-on-error | BOOLEAN | --continue-on-error | Keep going when an individual video has no captions. |
example
Run youtube-transcript
# one watch URLyoutube-transcript --url https://www.youtube.com/watch?v=dQw4w9WgXcQ --languages en --backend api # file of URLsyoutube-transcript --items urls.txt --continue-on-error{ "index": 0, "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "video_id": "dQw4w9WgXcQ", "ok": true, "backend": "api", "language": "en", "is_generated": true, "snippet_count": 42, "char_count": 1804, "files": { "txt": "transcript.txt", "json": "transcript.json", "meta": "transcript.meta.json" }}guidance
Choosing youtube-transcript
Use youtube-transcript when a public caption track is enough. Use whisper when you have audio and no captions. Use yt-dlp when you need the media file itself. wget only fetches page HTML.
wget
Downloads HTTP files and can mirror a site. It does not read the YouTube caption API.
whisper
Speech-to-text from an audio file. Use it when the video has no caption track.
yt-dlp
Downloads the video or audio. Pair it with whisper when you need speech, not captions.
workflows
Workflows using youtube-transcript
faq
youtube-transcript questions
related
More Utilities tools
cewl
Spider a URL and return a wordlist for password crackers.
dnsgen
Wordlist and mined-word subdomain permutation.
pup
CSS selectors over HTML, the jq counterpart for markup.
unfurl
Extract chosen URL parts from stdin into clean line lists.
whisper
Speech to txt, vtt, srt, and json from an audio file or folder.
yt-dlp
One URL or a URL list into a folder of media files.
Run youtube-transcript yourself
A watch URL feeds the youtube-transcript node. The folder holds transcript.txt, transcript.json, and results.jsonl. The JSON sample below is illustrative for a public youtube.com watch URL, not a fleet run.
Facts on this page come from the live Trickest tool library.