{"id":19,"date":"2026-11-04T18:21:58","date_gmt":"2026-11-04T18:21:58","guid":{"rendered":"https:\/\/globalcorpora.com\/blog\/yt-dlp-download-subtitles-auto-captions\/"},"modified":"2026-11-04T18:21:58","modified_gmt":"2026-11-04T18:21:58","slug":"yt-dlp-download-subtitles-auto-captions","status":"publish","type":"post","link":"https:\/\/globalcorpora.com\/blog\/yt-dlp-download-subtitles-auto-captions\/","title":{"rendered":"yt-dlp Subtitles: Download YouTube Auto Captions for ASR Data"},"content":{"rendered":"<p>YouTube subtitles look like free ASR labels, but a naive yt-dlp run mixes three different things: captions uploaded by the creator, YouTube's own speech recognition, and machine translations of either. This guide shows which yt-dlp subtitle flags fetch which tracks, how to tell them apart in <code>info.json<\/code>, and how to turn rolling auto-caption VTT into clean segment-level JSONL. Everything was checked against the yt-dlp README and source at release <a href=\"https:\/\/github.com\/yt-dlp\/yt-dlp\/releases\/tag\/2026.10.26\">2026.10.26<\/a>.<\/p>\n<h2>TL;DR<\/h2>\n<ul>\n<li><code>--write-subs<\/code> fetches creator-uploaded (manual) tracks. <code>--write-auto-subs<\/code> fetches YouTube's auto-generated captions. If both are on and a language exists in both, the manual track wins.<\/li>\n<li>For training data, request the original-language ASR track as <code>&lt;lang&gt;-orig<\/code> (e.g. <code>en-orig<\/code>). A plain <code>en<\/code> auto-caption on a non-English video is a machine translation.<\/li>\n<li><code>--sub-langs<\/code> takes comma-separated, case-insensitive regexes that must match the whole code, plus <code>all<\/code> and <code>-<\/code> exclusions such as <code>all,-live_chat<\/code>.<\/li>\n<li>Captions-only runs: <code>--skip-download --write-info-json<\/code>, throttled with <code>--sleep-subtitles<\/code>. If you use <code>--download-archive<\/code>, add <code>--force-write-archive<\/code> or nothing gets recorded.<\/li>\n<li>Auto-caption VTT repeats every line across cues. De-duplicate before you use it (a stdlib script is below), or download <code>json3<\/code>\/<code>srv3<\/code> if you need word timings.<\/li>\n<\/ul>\n<h2>Manual subtitles vs auto-generated captions<\/h2>\n<p>yt-dlp's YouTube extractor fills two separate dictionaries in the info dict:<\/p>\n<ul>\n<li><strong><code>subtitles<\/code><\/strong>: tracks uploaded or edited by the creator (caption tracks whose <code>kind<\/code> is not <code>asr<\/code>).<\/li>\n<li><strong><code>automatic_captions<\/code><\/strong>: YouTube's ASR track, plus machine-translated versions of it and, when requested, of the manual tracks.<\/li>\n<\/ul>\n<p>The CLI flags map one-to-one onto these: <code>--write-subs<\/code> reads <code>subtitles<\/code> and <code>--write-auto-subs<\/code> (alias <code>--write-automatic-subs<\/code>) reads <code>automatic_captions<\/code>. In <a href=\"https:\/\/github.com\/yt-dlp\/yt-dlp\/blob\/master\/yt_dlp\/YoutubeDL.py\"><code>YoutubeDL.process_subtitles<\/code><\/a>, manual tracks are added first and an automatic caption is only added for a language code that isn't already present. Either way the file is written as <code>&lt;name&gt;.&lt;lang&gt;.&lt;ext&gt;<\/code>, so <strong>the filename alone doesn't tell you which kind you got<\/strong>. Keep the <code>.info.json<\/code> and check the code against its <code>subtitles<\/code> keys (example below). Note that the cleaned <code>info.json<\/code> drops <code>requested_subtitles<\/code>, so you can't read the selection back from the file.<\/p>\n<p>Without <code>--sub-langs<\/code>, yt-dlp downloads exactly one track: <code>en<\/code> if present, otherwise the first <code>en*<\/code> code, otherwise the first available language.<\/p>\n<h2>See what exists first: <code>--list-subs<\/code><\/h2>\n<pre><code>yt-dlp --list-subs \"https:\/\/www.youtube.com\/watch?v=VIDEO_ID\"<\/code><\/pre>\n<p>This prints two tables (automatic captions and subtitles) with every language code and the formats on offer, and it only simulates unless you add <code>--no-simulate<\/code>. The same tables are available as the output-template fields <code>automatic_captions_table<\/code> and <code>subtitles_table<\/code>. On a typical video the automatic list is long: that's the translations, covered next.<\/p>\n<h2>Selecting languages with <code>--sub-langs<\/code><\/h2>\n<p>The <a href=\"https:\/\/github.com\/yt-dlp\/yt-dlp#subtitle-options\">README<\/a> defines <code>--sub-langs<\/code> as a comma-separated list of language codes, regexes, or <code>all<\/code>, where a leading <code>-<\/code> excludes a code. Two details from the source matter in practice:<\/p>\n<ul>\n<li>Each pattern is compiled case-insensitively and must <strong>fully match<\/strong> the code. <code>en<\/code> does not match <code>en-US<\/code>. <code>en.*<\/code> matches <code>en<\/code>, <code>en-US<\/code>, <code>en-GB<\/code>, <code>en-orig<\/code>, and every <code>en-xx<\/code> translation.<\/li>\n<li>Items are processed left to right, so <code>all,-live_chat<\/code> means \"everything, then remove <code>live_chat<\/code>\". Live-stream replays expose chat as a subtitle track named <code>live_chat<\/code>. You can also use <code>--compat-options no-live-chat<\/code>.<\/li>\n<\/ul>\n<pre><code># every manual track except chat replay\nyt-dlp --write-subs --sub-langs \"all,-live_chat\" --skip-download URL\n\n# English and Japanese manual tracks, any region variant\nyt-dlp --write-subs --sub-langs \"en.*,ja\" --skip-download URL<\/code><\/pre>\n<p>Use broad regexes only with <code>--write-subs<\/code> alone. Combined with <code>--write-auto-subs<\/code>, they pull in translations.<\/p>\n<h2>Auto-translated tracks: how to spot them and why to drop them<\/h2>\n<p>In the YouTube extractor (<a href=\"https:\/\/github.com\/yt-dlp\/yt-dlp\/blob\/master\/yt_dlp\/extractor\/youtube\/_video.py\"><code>extractor\/youtube\/_video.py<\/code><\/a>), each caption track is expanded against YouTube's list of translation languages. The codes you'll see in <code>automatic_captions<\/code>:<\/p>\n<table>\n<thead>\n<tr>\n<th>Key<\/th>\n<th>What it is<\/th>\n<th>Use for training?<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>en-orig<\/code> (any <code>&lt;lang&gt;-orig<\/code>)<\/td>\n<td>The ASR track in the video's spoken language. yt-dlp adds the <code>-orig<\/code> label, with the name \"\u2026 (Original)\", so it can be told apart.<\/td>\n<td>Yes, as a weak label<\/td>\n<\/tr>\n<tr>\n<td><code>en<\/code> when the audio is English<\/td>\n<td>The same original ASR track, kept under the plain code for compatibility.<\/td>\n<td>Yes (duplicate of <code>en-orig<\/code>)<\/td>\n<\/tr>\n<tr>\n<td><code>de<\/code>, <code>fr<\/code>, \u2026 when the audio is English<\/td>\n<td>Machine translation of the ASR track (URL carries <code>tlang=<\/code>).<\/td>\n<td>No<\/td>\n<\/tr>\n<tr>\n<td><code>de-en<\/code> (target-source)<\/td>\n<td>Machine translation of the manual <code>en<\/code> track. Only built when <code>--write-auto-subs<\/code> or <code>--list-subs<\/code> is used.<\/td>\n<td>No<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Translated tracks are text produced by a translation model, time-aligned to someone else's speech. As ASR labels they're simply wrong for the audio, and as translation pairs they're synthetic. Rules that hold up:<\/p>\n<ul>\n<li>Request <code>&lt;lang&gt;-orig<\/code> explicitly for ASR captions. The <code>-orig<\/code> key is added when the ASR track is translatable. If it is missing, fall back to the plain code only after confirming the URL has no <code>tlang<\/code> parameter.<\/li>\n<li>Treat any requested track whose URL contains <code>tlang=<\/code> as a translation and discard it.<\/li>\n<li><code>--extractor-args \"youtube:skip=translated_subs\"<\/code> stops yt-dlp from building translations of <em>manual<\/em> tracks (the <code>xx-yy<\/code> keys) and saves extraction time. In the current source it does not remove the plain-code translations of the ASR track, so the two rules above still apply.<\/li>\n<\/ul>\n<h2>Subtitle formats: <code>--sub-format<\/code>, <code>--convert-subs<\/code>, <code>--embed-subs<\/code><\/h2>\n<p>For YouTube, the extractor currently offers every track in seven formats: <code>json3<\/code>, <code>srv1<\/code>, <code>srv2<\/code>, <code>srv3<\/code>, <code>ttml<\/code>, <code>srt<\/code> and <code>vtt<\/code>. <code>--sub-format<\/code> takes a <code>\/<\/code>-separated preference list. <code>best<\/code> means the last format the extractor lists, which for YouTube is <code>vtt<\/code>. If nothing matches, yt-dlp warns and falls back to <code>best<\/code>.<\/p>\n<ul>\n<li><strong><code>vtt<\/code><\/strong>: the default and the easiest to parse. Auto-captions include per-word start times as inline tags.<\/li>\n<li><strong><code>json3<\/code><\/strong>, <strong><code>srv3<\/code><\/strong>: YouTube's own timed-text formats, useful for word-level timing (below). YouTube doesn't document them.<\/li>\n<li><strong><code>--convert-subs FORMAT<\/code><\/strong> converts to <code>ass<\/code>, <code>lrc<\/code>, <code>srt<\/code> or <code>vtt<\/code> through ffmpeg. TTML is converted to SRT first, with a warning that styling is lost. There's no converter for <code>json3<\/code> or <code>srv*<\/code>, so keep those raw and parse them yourself.<\/li>\n<li><strong><code>--embed-subs<\/code><\/strong> muxes tracks into mp4, webm or mkv output. Used alone, it deletes the sidecar files after embedding. Add <code>--write-subs<\/code> to keep them. It does nothing on a <code>--skip-download<\/code> run, and for datasets sidecar files are easier to process than embedded streams.<\/li>\n<\/ul>\n<h2>Captions-only runs at scale<\/h2>\n<p>Caption files are kilobytes, so a captions-plus-metadata pass is a cheap way to decide which videos are worth downloading audio for:<\/p>\n<pre><code>yt-dlp -a ids.txt --skip-download \\\n  --write-subs --write-auto-subs --sub-langs \"en,en-orig\" --sub-format vtt \\\n  --extractor-args \"youtube:skip=translated_subs\" \\\n  --write-info-json \\\n  --sleep-requests 1 --sleep-subtitles 2 \\\n  --download-archive subs_archive.txt --force-write-archive \\\n  -o \"meta\/%(id)s.%(ext)s\" \\\n  -o \"subtitle:subs\/%(id)s.%(ext)s\"<\/code><\/pre>\n<ul>\n<li><strong>Output templates.<\/strong> The <code>subtitle:<\/code> prefix sets a separate template for subtitle files, and yt-dlp appends the language and extension: <code>subs\/VIDEO_ID.en-orig.vtt<\/code>. <code>-P \"subtitle:subs\"<\/code> sets only the directory. The <code>.info.json<\/code> lands in <code>meta\/<\/code> (there's an <code>infojson:<\/code> prefix too).<\/li>\n<li><strong>Archive gotcha.<\/strong> With <code>--skip-download<\/code>, yt-dlp only writes archive entries if <code>--force-write-archive<\/code> is set. Without it, every re-run starts from zero.<\/li>\n<li><strong>Rate limits.<\/strong> <code>--sleep-subtitles<\/code> sleeps before each subtitle download and <code>--sleep-requests<\/code> between extraction requests. <code>--sleep-interval<\/code> applies to media downloads, not subtitle files. The <code>-t sleep<\/code> preset expands to <code>--sleep-subtitles 5 --sleep-requests 0.75 --sleep-interval 10 --max-sleep-interval 20<\/code>.<\/li>\n<li><strong>Missing tracks.<\/strong> If YouTube requires a PO token for subtitle requests and none is available, the extractor skips subtitles for that client and warns \"There are missing subtitles languages because a PO token was not provided.\" The README documents a <code>subs<\/code> context for the <code>po_token<\/code> extractor argument. Current yt-dlp also needs a JavaScript runtime and <code>yt-dlp-ejs<\/code> for full YouTube support.<\/li>\n<li><strong>Bot checks and IPs.<\/strong> At volume, subtitle and metadata requests hit the same anti-bot systems as video. See <a href=\"https:\/\/globalcorpora.com\/blog\/yt-dlp-sign-in-to-confirm-not-a-bot\/\">fixing \"Sign in to confirm you're not a bot\"<\/a> and <a href=\"https:\/\/globalcorpora.com\/blog\/yt-dlp-proxy-guide\/\">the yt-dlp proxy guide<\/a>.<\/li>\n<\/ul>\n<h2>Python API equivalents<\/h2>\n<p>The CLI flags map to <code>YoutubeDL<\/code> params (the README points to <code>devscripts\/cli_to_api.py<\/code> for translating any command line):<\/p>\n<table>\n<thead>\n<tr>\n<th>CLI<\/th>\n<th>Python param<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>--write-subs<\/code><\/td>\n<td><code>writesubtitles=True<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>--write-auto-subs<\/code><\/td>\n<td><code>writeautomaticsub=True<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>--sub-langs \"en,en-orig\"<\/code><\/td>\n<td><code>subtitleslangs=[\"en\", \"en-orig\"]<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>--sub-format vtt<\/code><\/td>\n<td><code>subtitlesformat=\"vtt\"<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>--list-subs<\/code><\/td>\n<td><code>listsubtitles=True<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>--skip-download<\/code><\/td>\n<td><code>skip_download=True<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>--sleep-subtitles 2<\/code><\/td>\n<td><code>sleep_interval_subtitles=2<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>--sleep-requests 1<\/code><\/td>\n<td><code>sleep_interval_requests=1<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>--force-write-archive<\/code><\/td>\n<td><code>force_write_download_archive=True<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>--convert-subs srt<\/code><\/td>\n<td><code>postprocessors=[{\"key\": \"FFmpegSubtitlesConvertor\", \"format\": \"srt\", \"when\": \"before_dl\"}]<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>--embed-subs<\/code><\/td>\n<td><code>postprocessors=[{\"key\": \"FFmpegEmbedSubtitle\"}]<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>This script fetches captions only and writes a manifest line per track labeled <code>manual<\/code>, <code>auto<\/code> or <code>auto-translated<\/code>, using the precedence and <code>tlang<\/code> rules above:<\/p>\n<pre><code>import json\nimport sys\n\nimport yt_dlp\n\nLANG = \"en\"\nOPTS = {\n    \"skip_download\": True,                       # --skip-download\n    \"writesubtitles\": True,                      # --write-subs\n    \"writeautomaticsub\": True,                   # --write-auto-subs\n    \"subtitleslangs\": [LANG, f\"{LANG}-orig\"],    # --sub-langs \"en,en-orig\"\n    \"subtitlesformat\": \"vtt\",                    # --sub-format vtt\n    \"writeinfojson\": True,                       # --write-info-json\n    \"outtmpl\": {\"default\": \"subs\/%(id)s\/%(id)s.%(ext)s\"},\n    \"extractor_args\": {\"youtube\": {\"skip\": [\"translated_subs\"]}},\n    \"sleep_interval_requests\": 1,                # --sleep-requests 1\n    \"sleep_interval_subtitles\": 2,               # --sleep-subtitles 2\n    \"ignoreerrors\": True,                        # log failures, keep going\n    # \"proxy\": \"http:\/\/USER:PASS@proxy.example.com:8000\",\n}\n\n\ndef track_kind(info, lang, sub):\n    if lang in (info.get(\"subtitles\") or {}):\n        return \"manual\"            # manual wins when both flags are set\n    if \"tlang=\" in (sub.get(\"url\") or \"\"):\n        return \"auto-translated\"   # machine translation: drop for training\n    return \"auto\"\n\n\ndef main(ids_path, manifest_path):\n    with open(ids_path, encoding=\"utf-8\") as f:\n        ids = [line.strip() for line in f if line.strip()]\n    with yt_dlp.YoutubeDL(OPTS) as ydl, \\\n            open(manifest_path, \"a\", encoding=\"utf-8\") as out:\n        for vid in ids:\n            info = ydl.extract_info(f\"https:\/\/www.youtube.com\/watch?v={vid}\")\n            if not info:\n                continue  # extraction failed; already reported\n            for lang, sub in (info.get(\"requested_subtitles\") or {}).items():\n                out.write(json.dumps({\n                    \"id\": vid,\n                    \"lang\": lang,\n                    \"kind\": track_kind(info, lang, sub),\n                    \"file\": f\"subs\/{vid}\/{vid}.{lang}.{sub['ext']}\",\n                }) + \"\\n\")\n\n\nif __name__ == \"__main__\":\n    main(*sys.argv[1:3])<\/code><\/pre>\n<p>Run it as <code>python fetch_captions.py ids.txt captions_manifest.jsonl<\/code>. On an English video with uploaded captions you get <code>en<\/code> (manual) and <code>en-orig<\/code> (auto). On a Spanish video without English captions, <code>en<\/code> is labeled <code>auto-translated<\/code> and <code>en-orig<\/code> doesn't exist.<\/p>\n<h2>Cleaning rolling auto-caption VTT<\/h2>\n<p>YouTube's auto-caption VTT is built for a two-line karaoke display, not for parsing. A typical stretch looks like this (abridged):<\/p>\n<pre><code>00:00:00.160 --&gt; 00:00:02.389 align:start position:0%\n \nin&lt;00:00:00.480&gt;&lt;c&gt; this&lt;\/c&gt;&lt;00:00:00.800&gt;&lt;c&gt; video&lt;\/c&gt;\n\n00:00:02.389 --&gt; 00:00:02.399 align:start position:0%\nin this video\n \n\n00:00:02.399 --&gt; 00:00:04.950 align:start position:0%\nin this video\ngoing&lt;00:00:02.720&gt;&lt;c&gt; to&lt;\/c&gt;&lt;00:00:03.040&gt;&lt;c&gt; talk&lt;\/c&gt;<\/code><\/pre>\n<p>Each cue repeats the previous line on top, and 10 ms \"hold\" cues repeat it again. (The seemingly blank line after the first timing line is a single space, so it doesn't end the cue.) Naively concatenating the cue text triples most words. The fix: strip tags, then drop the longest run of lines at the start of each cue that equals the end of the previous cue. Manual tracks don't have this layout, so the script detects auto-captions by their inline word timestamps and only merges identical back-to-back cues for manual tracks.<\/p>\n<pre><code>#!\/usr\/bin\/env python3\n\"\"\"YouTube WebVTT -&gt; segment-level JSONL ({\"start\", \"end\", \"text\"}), stdlib only.\n\nAuto-generated tracks use a \"rolling\" layout: each cue repeats the previous\nline above the new words, and ~10 ms cues re-show text that was already\nemitted. Those repeats are removed. Manual tracks are passed through, with\nidentical back-to-back cues merged.\n\nusage: python vtt_to_jsonl.py VIDEO.en-orig.vtt &gt; VIDEO.en-orig.jsonl\n\"\"\"\nimport html\nimport json\nimport re\nimport sys\n\nTS = r\"(?:(\\d+):)?(\\d{2}):(\\d{2})\\.(\\d{3})\"\nTIMING = re.compile(rf\"^{TS}\\s+--&gt;\\s+{TS}\")\nWORD_TS = re.compile(r\"&lt;(?:\\d+:)?\\d{2}:\\d{2}\\.\\d{3}&gt;\")  # only in auto captions\nTAG = re.compile(r\"&lt;[^&gt;]*&gt;\")             # &lt;c&gt;, &lt;\/c&gt;, &lt;00:00:01.234&gt;, &lt;i&gt;, ...\nNON_SPEECH = re.compile(r\"\\[[^\\]]*\\]\")   # [Music], [Applause]; None to keep them\n\n\ndef seconds(h, m, s, ms):\n    return int(h or 0) * 3600 + int(m) * 60 + int(s) + int(ms) \/ 1000\n\n\ndef clean(line):\n    text = html.unescape(TAG.sub(\"\", line))\n    if NON_SPEECH:\n        text = NON_SPEECH.sub(\"\", text)\n    return \" \".join(text.split())\n\n\ndef parse_cues(lines):\n    \"\"\"Yield (start, end, [text lines]). A cue ends at an empty line.\"\"\"\n    block = []\n    for line in lines + [\"\"]:\n        if line:\n            block.append(line)\n            continue\n        for i, row in enumerate(block):  # header\/NOTE\/STYLE blocks never match\n            m = TIMING.match(row)\n            if m:\n                g = m.groups()\n                text = [clean(t) for t in block[i + 1:]]\n                yield seconds(*g[:4]), seconds(*g[4:]), [t for t in text if t]\n                break\n        block = []\n\n\ndef overlap(prev, cur):\n    \"\"\"Length of the longest suffix of prev that is also a prefix of cur.\"\"\"\n    for k in range(min(len(prev), len(cur)), 0, -1):\n        if prev[-k:] == cur[:k]:\n            return k\n    return 0\n\n\ndef segments(path):\n    with open(path, encoding=\"utf-8-sig\") as f:\n        raw = f.read()\n    rolling = bool(WORD_TS.search(raw))\n    out, prev = [], []\n    for start, end, lines in parse_cues(raw.splitlines()):\n        if not lines:\n            continue\n        new = lines[overlap(prev, lines):] if rolling else lines\n        prev = lines\n        if not new:\n            continue  # cue only repeats text that was already emitted\n        text = \" \".join(new)\n        last = out[-1] if out else None\n        if last and last[\"text\"] == text and start - last[\"end\"] &lt; 0.05:\n            last[\"end\"] = round(max(last[\"end\"], end), 3)  # same caption held\n            continue\n        out.append({\"start\": round(start, 3), \"end\": round(end, 3), \"text\": text})\n    return out\n\n\nif __name__ == \"__main__\":\n    if len(sys.argv) != 2:\n        sys.exit(\"usage: vtt_to_jsonl.py FILE.vtt &gt; FILE.jsonl\")\n    for seg in segments(sys.argv[1]):\n        print(json.dumps(seg, ensure_ascii=False))<\/code><\/pre>\n<p>On the excerpt above it emits one segment per spoken line, with no repeats:<\/p>\n<pre><code>{\"start\": 0.16, \"end\": 2.389, \"text\": \"in this video\"}\n{\"start\": 2.399, \"end\": 4.95, \"text\": \"going to talk\"}<\/code><\/pre>\n<p>Notes: <code>NON_SPEECH<\/code> strips bracketed tags like <code>[Music]<\/code>. Set it to <code>None<\/code> if you want them as non-speech labels. Auto-captions may also contain <code>&gt;&gt;<\/code> speaker-change markers, which you can split on or strip. Segment boundaries follow YouTube's display lines, not sentences, so re-segment by pauses or punctuation if your model needs utterance-level samples.<\/p>\n<h2>Word-level timing: json3 and srv3<\/h2>\n<p>For forced-alignment checks or word-level supervision, request the native formats with <code>--sub-format json3<\/code> or <code>srv3<\/code> (they can't be converted, so request them directly). YouTube doesn't publish either schema, so treat what follows as observed structure and validate it on a sample:<\/p>\n<ul>\n<li><strong>json3<\/strong>: a top-level <code>events<\/code> list. Each event has <code>tStartMs<\/code>, <code>dDurationMs<\/code> and a <code>segs<\/code> list of text pieces in <code>utf8<\/code>. On auto-caption tracks, words are separate <code>segs<\/code> carrying an offset from the event start (<code>tOffsetMs<\/code>). Open-source parsers such as <a href=\"https:\/\/docs.rs\/fetchium-core\/1.0.0\/src\/fetchium_core\/youtube\/universal.rs.html\">this one<\/a> read the same fields.<\/li>\n<li><strong>srv3<\/strong>: XML with <code>&lt;p t=\"\u2026\" d=\"\u2026\"&gt;<\/code> lines (milliseconds) and <code>&lt;s&gt;<\/code> spans. See this <a href=\"https:\/\/github.com\/FyraLabs\/yttml\/blob\/main\/crates\/srv3-ttml\/internals\/srv3-format.md\">reverse-engineered format description<\/a>.<\/li>\n<\/ul>\n<pre><code>import json\n\ndef json3_words(path):\n    with open(path, encoding=\"utf-8\") as f:\n        events = json.load(f).get(\"events\", [])\n    for ev in events:\n        t0 = ev.get(\"tStartMs\", 0)\n        for seg in ev.get(\"segs\") or []:\n            word = seg.get(\"utf8\", \"\").strip()\n            if word:\n                yield (t0 + seg.get(\"tOffsetMs\", 0)) \/ 1000, word<\/code><\/pre>\n<p>These are word <em>start<\/em> times only. Derive ends from the next word's start, capped by the event's end, and expect them to be approximate.<\/p>\n<h2>Which flags for which need<\/h2>\n<table>\n<thead>\n<tr>\n<th>Need<\/th>\n<th>Flags<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td>See what tracks exist<\/td>\n<td><code>--list-subs<\/code><\/td>\n<\/tr>\n<tr>\n<td>Captions only, no media<\/td>\n<td><code>--skip-download<\/code> + subtitle flags<\/td>\n<\/tr>\n<tr>\n<td>Creator-uploaded English, any region<\/td>\n<td><code>--write-subs --sub-langs \"en.*\"<\/code><\/td>\n<\/tr>\n<tr>\n<td>Original-language ASR only<\/td>\n<td><code>--write-auto-subs --sub-langs \"en-orig\"<\/code><\/td>\n<\/tr>\n<tr>\n<td>Manual if present, plus original ASR<\/td>\n<td><code>--write-subs --write-auto-subs --sub-langs \"en,en-orig\"<\/code>, then check <code>info.json<\/code><\/td>\n<\/tr>\n<tr>\n<td>All manual tracks except chat replay<\/td>\n<td><code>--write-subs --sub-langs \"all,-live_chat\"<\/code><\/td>\n<\/tr>\n<tr>\n<td>Skip translations of manual tracks<\/td>\n<td><code>--extractor-args \"youtube:skip=translated_subs\"<\/code><\/td>\n<\/tr>\n<tr>\n<td>Word-level timing<\/td>\n<td><code>--sub-format json3<\/code> (or <code>srv3<\/code>)<\/td>\n<\/tr>\n<tr>\n<td>SRT files<\/td>\n<td><code>--sub-format srt<\/code> or <code>--sub-format vtt --convert-subs srt<\/code><\/td>\n<\/tr>\n<tr>\n<td>Subtitles inside the video file<\/td>\n<td><code>--embed-subs<\/code> (add <code>--write-subs<\/code> to keep sidecars)<\/td>\n<\/tr>\n<tr>\n<td>Separate subtitle folder<\/td>\n<td><code>-o \"subtitle:subs\/%(id)s.%(ext)s\"<\/code> or <code>-P \"subtitle:subs\"<\/code><\/td>\n<\/tr>\n<tr>\n<td>Throttle subtitle requests<\/td>\n<td><code>--sleep-subtitles N --sleep-requests N<\/code> or <code>-t sleep<\/code><\/td>\n<\/tr>\n<tr>\n<td>Resumable captions-only runs<\/td>\n<td><code>--download-archive FILE --force-write-archive<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Captions as ASR labels vs re-transcribing with Whisper<\/h2>\n<p>Neither caption type is a clean transcript. Manual captions are often edited for reading: they condense speech, drop disfluencies, add speaker names and sound tags, and can be offset in time. Auto-captions are another ASR system's output, so training on them distills its errors. They can also lack punctuation and casing. A practical split:<\/p>\n<ul>\n<li>Use caption availability and language as cheap <strong>filters<\/strong> before you download any audio (pair with the <a href=\"https:\/\/globalcorpora.com\/blog\/yt-dlp-audio-only-download-for-speech-datasets\/\">audio-only download guide<\/a>).<\/li>\n<li>Use <strong>manual<\/strong> captions as labels only after alignment and filtering, e.g. drop segments where your own ASR disagrees beyond a WER threshold you calibrate per language.<\/li>\n<li>Where label quality matters, <strong>re-transcribe<\/strong> with Whisper and keep the captions as a cross-check. Disagreement between the two is a useful quality signal.<\/li>\n<\/ul>\n<p>The Whisper side (model choice, language ID, per-language thresholds) is covered in <a href=\"https:\/\/globalcorpora.com\/blog\/build-youtube-video-dataset-for-multimodal-training\/\">building a YouTube video dataset for multimodal training<\/a>. Whatever you choose, store the track kind (<code>manual<\/code>\/<code>auto<\/code>) and language with every segment so you can re-weight or drop sources later.<\/p>\n<h2>Compliance<\/h2>\n<p>YouTube's Terms of Service restrict automated access and downloading, and captions are content like any other. Copyright and licensing apply: some teams restrict collection to Creative Commons videos (see <a href=\"https:\/\/globalcorpora.com\/blog\/creative-commons-youtube-videos-for-ai-training\/\">our guide to Creative Commons YouTube data<\/a>) and record the license per sample. Voices and transcribed speech can be personal data under regimes like GDPR. Honor takedown and opt-out requests, and keep the lineage you need to do so. Get legal review for your jurisdiction and use case.<\/p>\n<h2>If you'd rather not run this yourself<\/h2>\n<p>Corpora offers <a href=\"https:\/\/globalcorpora.com\/#pricing\">dedicated 1\u201340 Gbps unmetered proxy capacity<\/a> for teams running their own yt-dlp stack. It also offers a fully managed option that delivers video, audio, subtitles and metadata as JSONL\/Parquet with sha256 checksums and manifests to your S3, GCS or Azure bucket, starting with a free sample batch. <a href=\"https:\/\/globalcorpora.com\/#contact\">Contact us<\/a> to scope it.<\/p>\n<h2>FAQ<\/h2>\n<h3>How do I download only subtitles with yt-dlp, without the video?<\/h3>\n<p>Add <code>--skip-download<\/code> to your subtitle flags, e.g. <code>yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs \"en,en-orig\" URL<\/code>. Add <code>--write-info-json<\/code> if you need to tell manual and auto tracks apart later.<\/p>\n<h3>What is the difference between <code>--write-subs<\/code> and <code>--write-auto-subs<\/code>?<\/h3>\n<p><code>--write-subs<\/code> downloads tracks the creator uploaded (the <code>subtitles<\/code> key). <code>--write-auto-subs<\/code> downloads YouTube's automatic captions and their machine translations (the <code>automatic_captions<\/code> key). With both, a manual track takes precedence for the same language code.<\/p>\n<h3>What does <code>en-orig<\/code> mean in yt-dlp?<\/h3>\n<p>It's yt-dlp's label for the auto-generated caption track in the video's original spoken language. Other plain codes in the automatic list are usually machine translations of that track.<\/p>\n<h3>Why does my auto-generated VTT repeat every line?<\/h3>\n<p>YouTube's auto-caption VTT is a rolling two-line display: each cue repeats the previous line and short hold cues repeat it again. Strip the inline tags and remove the overlap between consecutive cues, as the script above does.<\/p>\n<h3>Can yt-dlp give word-level timestamps from YouTube captions?<\/h3>\n<p>For auto-captions, yes, indirectly. Download <code>json3<\/code> or <code>srv3<\/code> (or read the inline timestamps in VTT) and parse the per-word offsets yourself. Manual tracks are usually timed per line only.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Use yt-dlp subtitles options to download YouTube manual and auto-generated captions, drop auto-translated tracks, and clean rolling VTT for ASR datasets.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[29,28,30,31,27,7],"class_list":["post-19","post","type-post","status-publish","format-standard","hentry","category-guides","tag-asr-datasets","tag-auto-generated-captions","tag-speech-data","tag-webvtt","tag-youtube-subtitles","tag-yt-dlp"],"_links":{"self":[{"href":"https:\/\/globalcorpora.com\/blog\/wp-json\/wp\/v2\/posts\/19","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/globalcorpora.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/globalcorpora.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/globalcorpora.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/globalcorpora.com\/blog\/wp-json\/wp\/v2\/comments?post=19"}],"version-history":[{"count":0,"href":"https:\/\/globalcorpora.com\/blog\/wp-json\/wp\/v2\/posts\/19\/revisions"}],"wp:attachment":[{"href":"https:\/\/globalcorpora.com\/blog\/wp-json\/wp\/v2\/media?parent=19"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/globalcorpora.com\/blog\/wp-json\/wp\/v2\/categories?post=19"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/globalcorpora.com\/blog\/wp-json\/wp\/v2\/tags?post=19"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}