YouTube Transcript Native Node

YouTube Transcript (Native Node)

Version: 1.1.5 / public ClawHub utility candidate with external binary and YouTube access.

Minimal YouTube caption extractor. Native Node.js, zero npm dependencies, wraps the external yt-dlp binary.

Risk / invocation class

Risk class: external binary wrapper / YouTube network access / third-party content.

Use deliberately. This skill does not call a web API directly, but yt-dlp talks to YouTube and the local environment owns the yt-dlp PATH/binary supply-chain trust boundary.

Input packet

Required:

• url: full YouTube URL from the user.
• goal: raw transcript, summary input, quote extraction, timestamped notes, or JSON handoff.
• privacy_sensitivity: normal, private/client, or unknown.
• language: default en unless another language is requested.

Optional:

• timestamps: needed or not.
• json: needed for downstream tool use.
• dedup_preference: default auto-caption rolling-window dedup, or --no-dedup to preserve rolling-window/repeated-phrase artifacts as much as possible. Exact consecutive duplicate cue text may still be collapsed during VTT parsing.
• output_destination: chat summary, saved file, downstream summarizer, etc.

Stop or ask before use if the video/context is private or client-sensitive and sending access to YouTube via yt-dlp is not appropriate.

Output packet

Return compactly:

• source YouTube URL
• language requested and whether timestamps/JSON were used
• transcript status: success, no captions, dependency missing, private/blocked/rate-limited, or failed
• whether captions appear auto-generated when known
• saved path if the transcript was separately written to a file
• concise transcript summary or excerpt, unless the user requested raw text
• caveats and next safe step

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 beginning with an alphanumeric before invoking yt-dlp.
• Spawns yt-dlp with an argv array and no shell; it does not execute user-provided commands.
• Bounds the subprocess with a 120-second timeout.
• Creates and removes a temporary subtitle directory under the OS temp path.
• Refuses to print transcripts larger than 2,000,000 characters.
• Reads no API keys, env secrets, or credential/config files. Offline regression hooks are inert unless YOUTUBE_TRANSCRIPT_SELFTEST=1 is set by scripts/self-test.mjs; do not set self-test hooks for normal transcript extraction.
• Passes --ignore-config so user-level yt-dlp config does not silently alter wrapper behavior.
• Static-analysis child_process warnings are expected because this skill intentionally wraps trusted yt-dlp.

When to use

Use this when:

• the user provides a YouTube URL and wants spoken text/captions;
• clean plain text is needed for summarization, search, or quoting;
• the video has creator-uploaded subtitles or auto-generated captions.

Do not use this when:

• the user expects actual audio transcription; this extracts existing captions only;
• the platform is not YouTube;
• the video is a live stream that has not ended;
• the video/content is privacy-sensitive and should not be accessed via YouTube/yt-dlp;
• yt-dlp is not installed/on PATH and installing it has not been approved.

Commands

Script: scripts/fetch.mjs

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

POSIX shell examples:

node "/scripts/fetch.mjs" --url "https://www.youtube.com/watch?v=VIDEO_ID"
node "/scripts/fetch.mjs" --url "https://www.youtube.com/watch?v=VIDEO_ID" --json

For all flags, dedup details, output formats, dependency notes, and troubleshooting, load references/youtube-transcript-contract.md.

Operating guidance

• Pass the full user-provided YouTube URL; do not invent/transform URL forms unnecessarily.
• Default to --lang en unless another language is clear.
• Use default plain text for direct human reading and summaries.
• Use --json as the default structured handoff for research triage, summarization, and downstream tooling.
• Use --timestamps only when timestamped notes, quote traceability, or debugging are needed; it is an advanced/evidence mode, not the recommended default for reading.
• Use --json --timestamps only for machine traceability workflows that need timestamp anchors inside JSON; it is not intended as a human-readable inspection format.
• Save long transcripts to a file when useful; do not paste giant transcripts unless requested.
• Summarize first and quote sparingly by default.
• Respect copyright and platform terms; do not republish long/full transcripts unless the user has rights or permission.
• Note that captions may be auto-generated and imperfect.

Required checks before publishing/updating

Minimum no-video/no-network checks:

node --check skills\youtube-transcript-native-node\scripts\fetch.mjs
node skills\youtube-transcript-native-node\scripts\self-test.mjs
node skills\youtube-transcript-native-node\scripts\fetch.mjs --help
node skills\youtube-transcript-native-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

Do not install/update yt-dlp as part of this skill without explicit approval.

Public registry exposure

Classification: public ClawHub utility candidate with external binary + 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/config reads;
• temp-directory behavior and stderr temp-path scrubbing;
• no audio/video download and no audio transcription;
• expected child_process static-analysis warning.
• best-effort scrub of temp- and home-directory paths from the last lines of yt-dlp stderr; unrelated absolute paths emitted by yt-dlp itself may remain.

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

Do not include private/internal/client strategy, operator-specific operational notes, or full third-party transcript samples in a public release.

Changelog

• 1.1.5: Input/docs polish: require --lang to begin with an alphanumeric, add POSIX command examples, sync reference changelog, and neutralize process wording. No categories, topics, topic tags, tags, keywords, or ClawHub catalog metadata added to source.
• 1.1.4: Version refresh; no runtime behavior change.
• 1.1.3: Add stubbed offline yt-dlp fixture tests for dependency-missing, nonzero-exit-with-VTT, 429 hint, temp/home path scrubbing, output-size guard, timeout, and output modes; gate self-test hooks behind YOUTUBE_TRANSCRIPT_SELFTEST=1; continue when usable VTT subtitles are produced despite nonzero yt-dlp exit; kill active yt-dlp child on SIGINT/SIGTERM; broaden local-path scrubbing and scrub unexpected/read-error paths.
• 1.1.2: Add offline self-test fixtures, export parser/allowlist helpers for tests, pass --ignore-config, remove subtitle conversion postprocessor to avoid ffmpeg ambiguity, scrub temp path from yt-dlp error tails, and surface 429 retry guidance.
• 1.1.1: Docs cleanup: normalized input/output packet wording, structured handoff wording, and changelog language; no runtime behavior change.