YouTube Transcript Native Node

Extract a clean plain-text transcript from existing YouTube captions. native Node.js, zero npm dependencies, wraps the yt-dlp binary on PATH. writes subtitles to a temp dir, parses .vtt captions, strips timestamps and HTML tags, outputs clean text or JSON. no API keys required.

intent

use this skill when a user provides a YouTube URL and wants the spoken text from existing captions. extracts captions only (not audio transcription). returns clean plain text for summaries, quotes, and extraction tasks. runs natively on Node.js without external npm packages. wraps yt-dlp as a trusted external binary. use when caption text is needed for summarization, search, quoting, or downstream tooling.

inputs

required:

• url: full YouTube URL (youtube.com, www.youtube.com, m.youtube.com, or youtu.be domains only). validated before invocation.
• language: language code for subtitle request. defaults to en. validated as a simple subtitle language code before spawning yt-dlp.

optional:

• timestamps: boolean. include timestamp markers in output. defaults to false. used for timestamped notes, quote traceability, or debugging.
• json: boolean. return structured JSON instead of plain text. defaults to false. use for downstream tooling, research triage, and summarization pipelines.
• dedup_preference: string. auto (default) collapses rolling-window duplicate caption text. --no-dedup preserves rolling-window artifacts (exact consecutive duplicate cue text may still collapse during VTT parsing).
• output_destination: string. hint for where result goes: chat summary, saved file, downstream summarizer, etc. informational only.
• privacy_sensitivity: string. normal, private/client, or unknown. if private/client, confirm with user before accessing YouTube.

external dependency:

• yt-dlp binary on PATH. required. install via package manager or download from https://github.com/yt-dlp/yt-dlp/releases. this skill does not install it. set PATH environment variable to include the yt-dlp directory.

environment (optional, for self-test only):

• YOUTUBE_TRANSCRIPT_SELFTEST=1: enables offline regression fixtures in scripts/self-test.mjs. do not set for normal transcript extraction.

procedure

1. validate URL: check that url matches YouTube URL patterns (youtube.com, www.youtube.com, m.youtube.com, youtu.be). reject non-http(s) and non-YouTube hosts. input: url. output: accept/reject signal, error message if invalid.

2. validate language code: confirm language is a simple subtitle language code (e.g., en, es, fr). reject complex/shell-injection patterns. input: language parameter. output: validated language code or error.

3. check yt-dlp availability: spawn yt-dlp --version to confirm binary is on PATH and executable. timeout 10 seconds. input: PATH environment. output: version string or dependency-missing error.

4. create temp directory: create an OS-specific temp subdirectory under system temp path (e.g., /tmp/youtube-transcript-XXXXX or %TEMP%\youtube-transcript-XXXXX). input: none. output: temp directory path.

5. spawn yt-dlp subprocess: invoke yt-dlp --ignore-config --skip-download --write-subs --sub-lang <language> --sub-format vtt -o <temp-dir>/%(id)s <url>. use child_process.spawnSync with argv array (no shell). timeout: 120 seconds. input: url, language, temp-dir path. output: exit code, stdout, stderr.

6. handle yt-dlp exit/errors: check exit code and stderr. if exit code nonzero, check for usable .vtt files in temp dir anyway (some videos produce subtitles despite nonzero exit). if stderr contains "429" or rate-limit hint, emit guidance to retry later. if no .vtt files exist, return no-captions error. input: exit code, stderr, temp-dir contents. output: proceed with parsing or error signal (dependency-missing, private/blocked, rate-limited, failed).

7. find .vtt file: scan temp directory for .vtt subtitle file. expected naming: <video-id>.vtt or <video-id>.<language>.vtt. if multiple .vtt files, prefer exact language match. input: temp-dir path, language. output: .vtt file path or file-not-found error.

8. read and parse .vtt: read .vtt file as UTF-8 text. parse VTT cue blocks: extract timestamp ranges and cue text. strip HTML tags (, , etc.). collapse exact consecutive duplicate cue text (dedup always applies to duplicates; --no-dedup only affects rolling-window heuristics). input: .vtt file path, dedup_preference. output: array of cue objects: {timestamp: "HH:MM:SS --> HH:MM:SS", text: "clean text"} (or {text: "clean text"} if no timestamps).

9. apply formatting: if timestamps is true, join cues with timestamp prefixes (e.g., "[00:00:10] caption text"). if false, join cues with space or newline. input: cue array, timestamps flag. output: formatted string.

10. apply output mode: if json is true, serialize as JSON object with metadata: {url, language, timestamps_included, auto_generated_hint, transcript: [...]}. if false, return plain text. input: formatted string, cue metadata, json flag. output: string (plain text or JSON).

11. size guard: if output exceeds 2,000,000 characters, truncate with warning. do not output beyond limit. input: formatted output. output: capped output or truncation error.

12. scrub paths from stderr: attempt to remove temp-dir and home-directory absolute paths from any error messages for privacy. input: stderr from yt-dlp. output: scrubbed stderr string.

13. clean up temp directory: remove temp directory and all contents. input: temp-dir path. output: success or warning if cleanup fails.

14. return result: compile final output packet with transcript, metadata, status, caveats, and next steps. input: formatted transcript, status, temp-dir path (if saved separately), error messages, metadata. output: structured result object or string.

decision points

if privacy_sensitivity is "private" or "client":

• ask user to confirm that accessing this video via YouTube and yt-dlp is appropriate before proceeding. if user declines or is unsure, stop and do not invoke yt-dlp.

if yt-dlp is not on PATH:

• return "dependency-missing" error. do not proceed. guide user to install yt-dlp via package manager or direct download.

if yt-dlp exits nonzero but .vtt file exists and is readable:

• attempt to parse the .vtt file anyway. many videos produce usable subtitles despite nonzero exit (e.g., due to missing metadata). flag the behavior in output metadata ("partial success, yt-dlp reported error but captions extracted").

if yt-dlp exits nonzero and no .vtt file exists:

• check stderr for "429" or rate-limit patterns. if present, return "rate-limited" status with guidance to retry after delay. else return "failed" status with yt-dlp stderr (scrubbed).

if no captions exist for the video:

• return "no-captions" status. note that the video may have no creator captions or auto-generated captions. suggest checking YouTube directly or requesting transcript from creator.

if video is private, deleted, or blocked:

• yt-dlp stderr will indicate access denied. return "blocked" status with note that user/operator does not have access. do not attempt parsing.

if output exceeds 2,000,000 characters:

• truncate to 2,000,000 characters. emit truncation warning. do not exceed limit under any condition.

if timestamps is true and json is true:

• include timestamps in JSON cue objects. this is an advanced mode for machine traceability workflows. not intended as human-readable output.

if json is true:

• default to including auto_generated_hint in metadata (boolean, "true" if captions appear auto-generated from vtt metadata or heuristics, "unknown" otherwise).

if dedup_preference is "--no-dedup":

• preserve rolling-window duplicate phrases during formatting. exact consecutive duplicate cue text is still collapsed at the VTT parsing level (unavoidable).

output contract

return a result object or string with these fields:

• url: the input YouTube URL (unchanged).
• language: the requested language code (e.g., "en").
• status: one of "success", "no-captions", "dependency-missing", "rate-limited", "blocked", "private-declined", "failed", "truncated".
• timestamps_included: boolean. whether output includes timestamp markers.
• json_format: boolean. whether output is JSON or plain text.
• auto_generated: boolean or "unknown". whether captions appear auto-generated.
• transcript: the extracted text (plain text string or JSON array of {timestamp, text} or {text} objects).
• character_count: integer. length of transcript in characters.
• file_saved: string or null. path to transcript file if separately saved; else null.
• caveats: array of strings. warnings (auto-generated, truncated, rolling-window artifacts preserved, etc.).
• next_steps: array of strings. guidance on retry, alternative approaches, or follow-up actions.

if json flag is false, return plain text transcript as primary output with metadata as a brief summary header.

if output is saved to a file, note the file path in file_saved and indicate in result.

outcome signal

the user knows the skill worked when:

• a readable plain-text or JSON transcript appears in chat or is saved to a file.
• the transcript contains recognizable spoken dialogue or captions from the video.
• the status field is "success" or "truncated" (truncation is partial success).
• timestamps are present (if requested).
• the result includes the original URL, language requested, character count, and any caveats (e.g., "auto-generated", "partial success").
• if the user requested a summary or quotes, the text is usable for extraction.

failure signals:

• status is "no-captions", "blocked", "failed", "dependency-missing", or "rate-limited".
• no transcript text appears; only error messages or "try again later" guidance.
• the result notes that yt-dlp is not installed or unreachable.
• the user confirms the video is private or client-sensitive and declines to proceed.