YouTube Transcript Native Node

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

intent

Use this skill when the user provides a YouTube URL and needs spoken text or captions extracted for summarization, quoting, searching, or downstream processing. The skill handles creator-uploaded subtitles and auto-generated captions without requiring API keys. It does not perform actual audio transcription; it extracts only existing captions already published on the video. Use it for plain-text summaries, research triage with JSON output, timestamped notes, or quote extraction.

inputs

Required:

• url: full YouTube URL from user (http(s) only; youtube.com, www.youtube.com, m.youtube.com, or youtu.be hosts only).
• goal: intended use case (raw transcript, summary input, quote extraction, timestamped notes, or JSON handoff for downstream tools).

Optional:

• language: subtitle language code (defaults to en). validated as a simple language code before execution.
• timestamps: boolean; include timecodes in output. default false. use only when timestamped notes, quote traceability, or debugging are needed.
• json: boolean; output structured JSON instead of plain text. default false. use as default structured handoff for research triage and downstream tooling.
• dedup_preference: string; auto (default, rolling-window dedup) or --no-dedup (preserve repeated-phrase artifacts). exact consecutive duplicate cue text may still collapse during VTT parsing.
• output_destination: string; chat summary, saved file, downstream summarizer, etc.
• privacy_sensitivity: enum; normal, private/client, or unknown. use to gate execution on sensitive content.

External dependency:

• yt-dlp binary on PATH. not installed or updated by this skill; must be pre-installed with explicit approval. see "Troubleshooting" below if missing.

procedure

1. validate and parse the YouTube URL. accept only http(s) scheme. reject non-YouTube hosts (youtube.com, www.youtube.com, m.youtube.com, youtu.be only). extract video ID. output: validated URL string or validation error.

2. check privacy sensitivity. if privacy_sensitivity is private/client or unknown, ask user explicitly: "this will send the URL to YouTube via yt-dlp; do you approve?" stop if user declines. output: approval signal or rejection.

3. validate language code. if language provided, check it matches a simple subtitle language pattern (e.g., en, es, fr, zh-CN). reject invalid codes. output: validated language string or error.

4. create temporary subtitle directory. use OS temp path. output: temp directory path string.

5. invoke yt-dlp subprocess. construct argv array with --write-auto-subs, --skip-download, --sub-format vtt, --lang {language}, and --output {temp-dir}/%(id)s. spawn with 120-second timeout. do not use shell. output: subprocess exit code, stdout, stderr.

6. handle subprocess failures. if exit code nonzero, check stderr for known patterns: "private video", "video not found", "rate limited", "network error", or missing yt-dlp binary. map to human-readable status. output: error status string or transcript file path.

7. parse .vtt file. read generated subtitle file from temp dir. split on WEBVTT header and cue blocks. extract cue text (skip timecode lines and HTML tags like <v>, <c>, </c>). output: array of text strings or parse error.

8. apply dedup logic. if dedup_preference is auto, use rolling-window dedup to remove consecutive duplicate cue text. if --no-dedup, preserve rolling-window repeats. output: deduplicated or raw cue array.

9. enforce output size limit. if joined transcript exceeds 2,000,000 characters, truncate and flag in output. output: truncated transcript string or flag.

10. format output. if json is true, build object with keys: url, language, timestamps, captions_auto_generated (boolean if detectable), transcript (string or array of cue objects with text and optional start_time, end_time), status, saved_path (if written to file). if json is false and timestamps is false, return plain text only. if timestamps is true, prepend timecodes to each line. output: formatted string or JSON object.

11. clean up temp directory. delete temp subtitle directory and all contents. output: success or cleanup warning.

12. return result packet. include source URL, language used, transcript status (success, no captions, dependency missing, private/blocked, rate-limited, or failed), whether captions are auto-generated, saved path if applicable, concise summary or excerpt (unless raw text requested), and any caveats. output: result packet object or string.

decision points

if privacy_sensitivity is private/client or unknown: ask user for explicit approval to access via yt-dlp before proceeding. if user declines, return early with "user declined privacy gate" status.

if yt-dlp binary is not on PATH: check stderr for "command not found" or "yt-dlp is not recognized". return status "dependency missing" with guidance: "install yt-dlp or add to PATH; do not auto-install." do not invoke skill further.

if subprocess exits nonzero: parse stderr for "private video" (return status "private/blocked"), "video not found" (return status "no captions"), "HTTP Error 429" (return status "rate-limited"), network timeout (return status "network timeout"), or generic error. return status "failed" with brief error detail.

if no .vtt file is generated: return status "no captions available" (video has no subtitles). do not fail hard; report clearly.

if json is true and timestamps is true: output transcript as array of cue objects with text, start_time (HH:MM:SS format), end_time fields. this is for machine traceability workflows only, not human-readable inspection.

if transcript exceeds 2,000,000 characters: truncate at 2,000,000 boundary and include flag "truncated": true in output. prompt user to save to file instead of pasting.

if user goal is "raw transcript": return full plain text (no summary). if goal is "summary" or "quotes", return summary or excerpts only by default, not full transcript.

output contract

Success case:

• HTTP 200 equivalent (script exits 0).
• JSON object (if --json flag used) or plain text string.
• JSON schema (if applicable):

  {
    "url": "https://www.youtube.com/watch?v=...",
    "video_id": "...",
    "language": "en",
    "timestamps_included": false,
    "captions_auto_generated": true,
    "transcript": "clean text here...",
    "status": "success",
    "saved_path": null,
    "character_count": 5432,
    "truncated": false,
    "caveats": "Auto-generated captions may contain errors."
  }
  

• If --timestamps, transcript field becomes array:

  "transcript": [
    { "text": "hello world", "start_time": "00:00:05", "end_time": "00:00:07" },
    ...
  ]
  

• If plain text (no --json): returns string with optional timecode prefixes per line.
• Temp directory fully deleted.

Failure cases:

• Status: no captions, private/blocked, rate-limited, network timeout, dependency missing, or failed.
• Brief error detail included.
• No temp files left behind.
• Exit code nonzero if CLI usage.

outcome signal

• user sees clean, ready-to-read plain text or structured JSON transcript.
• timestamps appear in output if requested; timecodes are accurate (HH:MM:SS format).
• auto-generated caption flag alerts user to potential quality issues.
• transcript is immediately usable for summarization, quoting, or downstream tool handoff.
• if transcript is saved to file, user receives file path.
• if dependency is missing, user receives clear "install yt-dlp" message, not a cryptic error.
• if video is private or rate-limited, user gets explicit status, not generic failure.
• full transcript is never printed to chat if it exceeds 2,000,000 characters; user is prompted to save to file.

---

commands

node "<skill-dir>/scripts/fetch.mjs" --url "https://www.youtube.com/watch?v=VIDEO_ID"
node "<skill-dir>/scripts/fetch.mjs" --url "https://www.youtube.com/watch?v=VIDEO_ID" --lang es
node "<skill-dir>/scripts/fetch.mjs" --url "https://www.youtube.com/watch?v=VIDEO_ID" --timestamps
node "<skill-dir>/scripts/fetch.mjs" --url "https://www.youtube.com/watch?v=VIDEO_ID" --json
node "<skill-dir>/scripts/fetch.mjs" --url "https://www.youtube.com/watch?v=VIDEO_ID" --json --timestamps
node "<skill-dir>/scripts/fetch.mjs" --help

operating guidance

• pass the full user-provided YouTube URL; do not invent or transform URL forms.
• default to --lang en unless another language is explicit.
• use plain text for direct human reading and summaries.
• use --json as default structured handoff for research triage, summarization, and downstream tooling.
• use --timestamps only for timestamped notes, quote traceability, or debugging; it is not the recommended default for reading.
• use --json --timestamps only for machine traceability workflows that need timestamp anchors; not intended as human-readable format.
• save long transcripts to a file; do not paste giant transcripts unless requested.
• summarize first and quote sparingly by default.
• respect copyright and platform terms; do not republish long or full transcripts unless the user has rights or permission.
• note that captions may be auto-generated and imperfect.
• do not install or update yt-dlp as part of this skill without explicit approval.

security behavior

• accepts only http(s) YouTube URLs on youtube.com, www.youtube.com, m.youtube.com, or youtu.be.
• validates --lang as a simple subtitle language code before invoking yt-dlp.
• spawns yt-dlp with an argv array and no shell; does not execute user-provided commands.
• bounds subprocess with 120-second timeout.
• creates and removes temporary subtitle directory under OS temp path.
• refuses to print transcripts larger than 2,000,000 characters.
• reads no API keys, env secrets, or credential/config files.
• static-analysis child_process warnings are expected; this skill intentionally wraps trusted yt-dlp.

troubleshooting

"yt-dlp: command not found" or "is not recognized": yt-dlp is not on PATH. install via pip install yt-dlp (or package manager for your OS) and ensure it is in your PATH. this skill does not auto-install.

"private video" or "video not found": video is private, deleted, or does not exist. check URL and user access; there is no fallback.

"HTTP Error 429": rate-limited by YouTube. wait 30 minutes to 1 hour and retry. do not hammer the API.

"network error" or timeout after 120 seconds: network issue or YouTube is unreachable. check internet connection and retry. if persistent, YouTube may be blocking yt-dlp temporarily.

no .vtt file generated: video has no subtitles (creator did not upload, and auto-captions are disabled or unavailable). return status "no captions available" and stop gracefully.

transcript exceeds 2,000,000 characters: transcript is truncated and flagged. prompt user to save to file with --output-file or similar flag if available.

"invalid language code": language parameter does not match expected format. default to en or ask user for clarification.

---

required checks before publishing/updating

minimal no-video/no-network checks:

node --check scripts/fetch.mjs
node scripts/fetch.mjs --help
node scripts/fetch.mjs --url "https://example.com/watch?v=not-youtube" --json

the invalid-host smoke should fail before invoking yt-dlp.

optional environment check:

yt-dlp --version

public / clawhub exposure

classification: publishable utility with external binary and YouTube access.

before public update, run sanitizer/static checks and ensure docs clearly disclose:

• yt-dlp dependency and PATH/binary trust boundary.
• YouTube-only URL allowlist.
• no API keys, env secrets, or config reads.
• temp-directory behavior and cleanup.
• no audio/video download and no audio transcription.
• expected child_process static-analysis warning.

respect copyright and platform terms in examples, docs, and outputs: prefer summaries and brief quotes; do not publish long or full third-party transcripts unless rights or permission are clear.

do not include private, internal, operator-specific strategy, or full third-party transcript samples in a public release.

---

credits: original skill from clawhub. native node.js wrapper around yt-dlp.