youtube subtitle extraction via yt-dlp command execution
Downloads YouTube video subtitles by spawning yt-dlp as a subprocess via spawn-rx, capturing VTT-formatted subtitle files from any public YouTube video URL. The implementation wraps the external yt-dlp binary with reactive stream handling, enabling asynchronous subtitle retrieval without blocking the MCP server. Subtitles are fetched in their raw VTT format before post-processing.
Unique: Uses spawn-rx for reactive subprocess management of yt-dlp rather than direct child_process calls, enabling non-blocking async subtitle downloads integrated into the MCP event loop. This approach avoids blocking the stdio transport that communicates with Claude.
vs alternatives: More reliable than YouTube Data API (no quota limits, no API key required) but slower than direct API calls; trades latency for robustness and cost-free operation.
vtt subtitle format parsing and text extraction
Parses raw VTT (WebVTT) subtitle files to remove timestamps, cue identifiers, and formatting metadata, extracting clean readable text for LLM consumption. The processor handles VTT-specific syntax (WEBVTT header, timestamp ranges like '00:00:05.000 --> 00:00:10.000', style blocks) and outputs plain text with line breaks preserved for readability. This enables Claude to work with human-readable transcripts rather than machine-formatted subtitle data.
Unique: Implements VTT-specific parsing logic that strips timing metadata and cue identifiers while preserving dialogue flow, specifically optimized for LLM consumption rather than video playback synchronization. The implementation is lightweight and synchronous, avoiding external dependencies.
vs alternatives: Simpler and faster than full subtitle library solutions (like subtitle.js) because it's purpose-built for LLM text extraction rather than general-purpose subtitle handling.
mcp server integration with stdio transport
Implements a Model Context Protocol server using StdioServerTransport that communicates with Claude.ai via standard input/output streams. The server exposes YouTube subtitle tools as MCP resources/tools, allowing Claude to invoke subtitle downloading as a native capability. This integration enables seamless tool calling where Claude can request subtitles without explicit API management by the user.
Unique: Uses StdioServerTransport for bidirectional communication with Claude via stdin/stdout, avoiding network overhead and authentication complexity. The server is stateless and designed to be spawned as a subprocess by Claude's MCP client, making it trivial to install and manage.
vs alternatives: Simpler deployment than REST API servers (no port management, no CORS, no authentication) but limited to Claude.ai ecosystem; tightly coupled to MCP protocol rather than being framework-agnostic.
youtube url validation and subtitle availability detection
Validates YouTube URLs and detects whether a video has available subtitles before attempting download, preventing wasted subprocess calls to yt-dlp on videos without captions. The implementation leverages yt-dlp's metadata extraction to check subtitle availability without downloading the full subtitle file, enabling fast pre-flight validation. This reduces latency and improves user experience by failing fast on unsupported videos.
Unique: Performs lightweight metadata extraction via yt-dlp without downloading subtitle content, enabling fast availability checks. This two-stage approach (validate → download) prevents wasted processing on unsupported videos while keeping the architecture simple.
vs alternatives: More reliable than regex-based URL validation because it actually queries YouTube metadata, but slower than simple pattern matching; trades latency for accuracy.
subtitle language selection and multi-language support
Detects available subtitle languages for a YouTube video and allows selection of specific language tracks for download. The implementation queries yt-dlp's language metadata to present options to Claude, enabling multi-language video analysis. When a language is specified, yt-dlp downloads the corresponding subtitle track, supporting both manually-uploaded and auto-generated captions in different languages.
Unique: Leverages yt-dlp's built-in language detection to enumerate available subtitle tracks without downloading them, then allows selective download of specific language variants. This enables efficient multi-language workflows without redundant downloads.
vs alternatives: More flexible than single-language subtitle extraction but requires explicit language specification; no automatic language preference inference like some commercial video APIs.