youtube
Retrieve YouTube video transcripts and rich metadata (title, channel, duration). Search captions, list language tracks, and export in text, timestamped, SRT, VTT, or JSON format.
Instructions
YouTube transcript and metadata tool. Returns captions + rich metadata for any YouTube video. Actions: 'transcript' (captions only), 'metadata' (title/channel/duration/description/chapters only), 'info' (transcript + metadata in parallel - the common case), 'list_languages' (enumerate available caption tracks), 'search' (find a phrase within a transcript, returns timestamped matches with t= deeplinks). Primary fetch: youtube-transcript-api (fast, clean). Fallback: yt-dlp with json3 subtitles + VTT roll-up dedup. Format options: text (default, lowest tokens), timestamped, srt, vtt, json. Use harvest=True to write clean markdown under harvested/youtube/ for RAG ingestion. Accepts any URL shape (watch, youtu.be, shorts, live, embed) or bare 11-char video_id. Cached 1hr. Auto-paginates long transcripts; use segment_offset to continue from where the last response ended. For long podcasts, prefer harvest=True then retrieve() instead of loading full text into context.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | YouTube URL (any shape). Either url or video_id is required. | |
| query | No | Search phrase. Required for action='search'. | |
| action | Yes | Operation to perform | |
| format | No | Transcript output format. Default: text (lowest tokens). | |
| harvest | No | Save a markdown file under harvested/<harvest_dest>/ for RAG ingestion. Saves context tokens when working with long videos. | |
| video_id | No | 11-char video ID (alternative to url). | |
| languages | No | Preferred language codes in priority order, e.g. ['en', 'en-US']. Default ['en']. | |
| force_ytdlp | No | Skip primary path, go straight to yt-dlp (useful when IP-blocked or when primary returns stale data). Default: false. | |
| harvest_dest | No | Subfolder under harvested/. Default: 'youtube/'. | |
| max_segments | No | Max segments to return. Default: auto-calculated to fit response budget. | |
| rich_metadata | No | Use yt-dlp for rich metadata (slower, full info) vs oEmbed (faster, title+channel+thumbnail only). Default: true. | |
| segment_offset | No | Start from this segment index (0-based). Use next_offset from a previous paginated response to continue. Default: 0. | |
| include_metadata | No | For info action, include metadata alongside transcript. Default: true. |