--- name: fetch-youtube-transcript-cdd0b42df32d description: Download YouTube video transcripts as readable text files. Use when extracting transcripts from videos for analysis, documentation, or content review. argument-hint: [--output DIR] [--language LANG] --- # YouTube Transcript Download Skill ## Purpose Download transcripts from YouTube videos as readable text files with timestamps. This skill wraps the `youtube-transcript-api` tool with a simple interface for quick transcript extraction. ## Usage ```bash /fetch-youtube-transcript [--output DIR] [--language LANG] ``` ## Arguments ### Required - **``**: YouTube video URL or video ID - Full URLs: `https://www.youtube.com/watch?v=VIDEO_ID` - Short URLs: `https://youtu.be/VIDEO_ID` - Video ID only: `VIDEO_ID` (11 characters) - URLs with timestamps and query parameters are supported ### Optional - **`--output DIR`**: Output directory for transcript files - Default: `.work/transcripts/` - Directory will be created if it doesn't exist - Transcript saved as `VIDEO_ID.txt` - **`--language LANG`**: Preferred transcript language code - Default: Auto-select (usually English if available) - Examples: `en`, `es`, `fr`, `de`, `ja` - Falls back to auto-generated if manual transcript unavailable ## Execution Instructions for Claude Code When the user invokes `/fetch-youtube-transcript`, follow these steps: ### 1. Parse Arguments Extract the video URL/ID and optional parameters from the user's command: ```python # Example argument parsing logic import re from pathlib import Path def parse_args(args_string): """Parse /fetch-youtube-transcript arguments.""" parts = args_string.split() if not parts: return None, None, None, "Error: Video URL or ID required" video_url = parts[0] output_dir = ".work/transcripts" language = None # Parse optional flags i = 1 while i < len(parts): if parts[i] == "--output" and i + 1 < len(parts): output_dir = parts[i + 1] i += 2 elif parts[i] == "--language" and i + 1 < len(parts): language = parts[i + 1] i += 2 else: i += 1 return video_url, output_dir, language, None ``` ### 2. Construct Command Build the `uvx` command to run the transcript fetcher: ```bash uvx --from youtube-transcript-api \ python scripts/fetch-youtube-transcript.py \ "" \ --output "" ``` If language is specified, add `--language `. **Important**: - The script is bundled with this plugin at `scripts/fetch-youtube-transcript.py` - Quote the video URL to handle special characters - Use the full path to the script in the plugin cache directory ### 3. Execute Command Run the command using the Bash tool with appropriate error handling: ```python # Construct full command cmd_parts = [ "uvx --from youtube-transcript-api", "python scripts/fetch-youtube-transcript.py", f'"{video_url}"', f"--output {output_dir}" ] if language: cmd_parts.append(f"--language {language}") command = " ".join(cmd_parts) # Execute via Bash tool # The script will handle all video ID extraction and error cases ``` ### 4. Handle Output The script outputs structured information on success: ``` ✅ Transcript downloaded successfully! Video: 4_2j5wgt_ds File: .work/transcripts/4_2j5wgt_ds.txt Entries: 851 ``` Parse this output and report to the user: - Confirm successful download - Show the output file location - Indicate the number of transcript entries ### 5. Handle Errors The script returns non-zero exit codes and error messages for failures: **Common error scenarios:** 1. **Invalid URL format** ``` ❌ Error: Invalid YouTube URL or video ID ``` Report: "The provided URL or video ID is invalid. Please provide a valid YouTube URL or 11-character video ID." 2. **No transcript available** ``` ❌ Error: No transcript found for video Could not retrieve a transcript for the video ID ``` Report: "No transcript is available for this video. The creator may have disabled transcripts." 3. **Video unavailable** ``` ❌ Error: Video unavailable or private ``` Report: "The video is unavailable, private, or has been deleted." 4. **Network errors** ``` ❌ Error: Network request failed ``` Report: "Failed to connect to YouTube. Please check your internet connection." 5. **Invalid output directory** ``` ❌ Error: Cannot create output directory ``` Report: "Failed to create output directory. Please check permissions." ### 6. Report Success On successful execution, provide a clear summary: ``` ✅ Transcript downloaded successfully! 📹 Video ID: 4_2j5wgt_ds 📄 File: .work/transcripts/4_2j5wgt_ds.txt 📊 Entries: 851 transcript segments You can now read the transcript file or use it for analysis. ``` ## Output Format Transcripts are saved as plain text files with the following format: ``` [00:00] Welcome to this video about Product Forge! [00:15] Today we'll be exploring how to build custom Claude Code plugins. [00:32] First, let's talk about the plugin architecture. ... ``` Each line contains: - **Timestamp**: `[MM:SS]` format for easy navigation - **Text**: The spoken content at that timestamp The format is designed for: - Easy reading and searching - Simple parsing if needed for analysis - Clear temporal context ## Examples ### Example 1: Basic Usage Download a transcript using a full YouTube URL: ```bash /fetch-youtube-transcript "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ``` Result: - Transcript saved to `.work/transcripts/dQw4w9WgXcQ.txt` - Auto-selected language (usually English) ### Example 2: Custom Output Directory Save transcript to a specific directory: ```bash /fetch-youtube-transcript "https://youtu.be/dQw4w9WgXcQ" --output ./transcripts ``` Result: - Transcript saved to `./transcripts/dQw4w9WgXcQ.txt` - Directory created if it doesn't exist ### Example 3: Specific Language Request a Spanish transcript: ```bash /fetch-youtube-transcript "dQw4w9WgXcQ" --language es ``` Result: - Spanish transcript if available - Falls back to auto-generated Spanish if manual unavailable - Error if Spanish not available at all ### Example 4: Video ID Only Use just the video ID: ```bash /fetch-youtube-transcript "dQw4w9WgXcQ" ``` Result: - Same as full URL - Simpler syntax for known video IDs ## Error Handling ### Validation Errors **Missing URL:** ```bash /fetch-youtube-transcript ``` Response: "Error: Video URL or ID required. Usage: /fetch-youtube-transcript [--output DIR]" **Invalid URL format:** ```bash /fetch-youtube-transcript "not-a-youtube-url" ``` Response: "Error: Invalid YouTube URL or video ID. Please provide a valid YouTube URL or 11-character video ID." ### API Errors **No transcript available:** - The video creator has disabled transcripts - Automatic captions are disabled - Video is too new (transcripts not yet generated) Response: "No transcript available for this video. The creator may have disabled transcripts or automatic captions." **Video unavailable:** - Video is private or unlisted - Video has been deleted - Video is region-restricted Response: "Video is unavailable. It may be private, deleted, or region-restricted." ### Network Errors **Connection failed:** - Internet connection issues - YouTube API temporarily unavailable Response: "Failed to connect to YouTube. Please check your internet connection and try again." **Rate limiting:** - Too many requests in short time - YouTube API quota exceeded Response: "Request rate limited. Please wait a moment and try again." ## Implementation Tips for Claude Code ### Argument Parsing The script expects arguments in this order: ```bash python script.py [--output DIR] [--language LANG] ``` Parse the user's `/fetch-youtube-transcript` command to extract these values: - Strip the `/fetch-youtube-transcript` prefix - Extract the first argument as video URL - Look for `--output` flag and next argument - Look for `--language` flag and next argument ### Error Detection Monitor the exit code and stderr: - Exit code 0 = Success - Exit code 1 = Error (check stderr for details) Common error patterns in stderr: - `"Invalid YouTube URL"` → URL validation failed - `"No transcript found"` → Transcripts disabled - `"Video unavailable"` → Private/deleted video - `"Network"` → Connection issues ### Path Handling The script is bundled with this plugin at `scripts/fetch-youtube-transcript.py` (relative to the plugin directory). Claude Code will resolve this path automatically when executing from the plugin context. Output directory handling: - Relative paths are relative to current working directory - Absolute paths work as expected - Default `.work/transcripts/` is relative to current directory ### User Communication **Be conversational:** Don't just dump the raw script output. Parse it and present it naturally: Instead of: ``` ✅ Transcript downloaded successfully! Video: 4_2j5wgt_ds File: .work/transcripts/4_2j5wgt_ds.txt ``` Say: ``` I've downloaded the transcript for video 4_2j5wgt_ds. The file is saved at .work/transcripts/4_2j5wgt_ds.txt with 851 transcript entries. ``` **Provide context:** If the user might want to do something with the transcript, suggest next steps: ``` Transcript downloaded successfully! You can now: - Read the file to review the content - Search for specific topics or keywords - Use it as reference material - Process it further with other tools ``` **Handle errors gracefully:** Don't just report the error, explain what it means and what to do: Instead of: ``` ❌ Error: No transcript found ``` Say: ``` This video doesn't have a transcript available. This usually means the creator disabled automatic captions. Unfortunately, there's no transcript to download. ``` ### Working Directory The script path is relative to the plugin directory and Claude Code handles path resolution automatically. Output directory considerations: - Relative paths are relative to current working directory - Default `.work/transcripts/` will be created relative to where the command is run - Use absolute paths if you need transcripts in a specific location ### Testing Verification Before reporting success, verify: 1. Exit code is 0 2. Output file exists at expected path 3. Output file has content (size > 0) This prevents false positives from script failures. ## Technical Details ### Dependencies The skill uses `youtube-transcript-api` via `uvx`: - No installation required - Isolated execution environment - Automatic dependency management ### Script Location The Python script is bundled with the plugin at `scripts/fetch-youtube-transcript.py` (relative to plugin directory). ### Supported URL Formats The script handles these YouTube URL formats: - `https://www.youtube.com/watch?v=VIDEO_ID` - `https://youtu.be/VIDEO_ID` - `https://www.youtube.com/watch?v=VIDEO_ID&t=123s` - `https://m.youtube.com/watch?v=VIDEO_ID` - `VIDEO_ID` (11 characters) ### Language Codes Common language codes for `--language`: - `en` - English - `es` - Spanish - `fr` - French - `de` - German - `ja` - Japanese - `ko` - Korean - `zh` - Chinese - `pt` - Portuguese - `ru` - Russian - `ar` - Arabic Full list: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ### Output File Naming Files are named using the video ID: - Video ID extracted from URL - Extension: `.txt` - Example: `dQw4w9WgXcQ.txt` This ensures: - Unique filenames per video - Easy to identify source video - No special character issues ## Limitations - Requires internet connection to YouTube - Only works with public videos or unlisted videos with link - Requires video to have transcripts enabled (manual or automatic) - Cannot bypass region restrictions - Subject to YouTube API rate limits - Language availability depends on video creator settings ## Future Enhancements Potential improvements for future versions: - Batch download multiple videos from a playlist - Merge transcripts from multiple videos - Format conversion (SRT, VTT, JSON) - Translation of transcripts - Timestamp filtering (download specific time ranges) - Integration with video analysis tools --- Source attribution: jpoutrin Original project: https://github.com/jpoutrin/product-forge/blob/0ebe7aea08747cb1c121bc77652d458b9e8ee782/plugins/content-tools/skills/fetch-youtube-transcript/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2025 jpoutrin Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: jpoutrin Original project: https://github.com/jpoutrin/product-forge/blob/0ebe7aea08747cb1c121bc77652d458b9e8ee782/plugins/content-tools/skills/fetch-youtube-transcript/SKILL.md Attribution basis: Source repository record Fields of work: Education & Research, Marketing Roles: Content Marketer, Marketing Analyst, Researcher Specialties: API Tools: Youtube Transcript Api Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 8bd621e8fcac5adf24de264fdf5c20a76ccaa120c6a38ea86dc4549821550a38