| name | youtube-to-docs |
| description | Comprehensive suite for processing YouTube videos. Use this when the user needs to: (1) Extract transcripts, (2) Generate visual infographics, (3) Create audio summaries (TTS) and videos, or (4) Perform full 'kitchen sink' processing of YouTube content. |
YouTube to Docs
Overview
This skill allows you to process YouTube videos to extract transcripts, generate AI summaries, create infographics, and even produce video summaries. You have access to the process_video tool which handles these operations.
Requirements & Dependencies
The process_video tool is a high-level interface that relies on several optional libraries ("extras") and system binaries to function. These are managed automatically when running via the provided MCP configuration or uv.
- Python Libraries: Many features (audio extraction, video generation, cloud storage) require specific extras.
- System Binaries: Features like video creation (
combine_infographic_audio) require ffmpeg (handled by the static-ffmpeg library).
- Automatic Setup: The MCP server (configured in
gemini-extension.json for Gemini CLI and .mcp.json for Claude Code) uses uv run --all-extras to ensure all necessary libraries are installed in a managed environment before execution.
Workflows
1. Transcript Extraction
Use this when the user simply wants the text transcript of a video, without additional AI processing.
- Goal: Get the raw text from a YouTube video.
- Tool:
process_video
- Required Argument:
url (The YouTube link)
- Defaults: By default,
process_video fetches the transcript from YouTube.
- Example Prompt: "Get the transcript for https://www.youtube.com/watch?v=..."
2. Infographic Generation
Use this when the user wants a visual summary or "infographic" representing the video's content.
- Goal: Create a visual summary (image).
- Tool:
process_video
- Required Argument:
url (The YouTube link)
- Optional Arguments:
infographic_model: The image generation model to use.model: The text model for summarization (required context for the image).
- Model Selection Strategy:
- Pro (Default/High Quality): Use if "gemini pro" is requested or no preference is stated.
model='gemini-3.1-pro-preview'infographic_model='gemini-3-pro-image'
- Flash (Speed/Cost): Use if "gemini flash" is requested.
model='gemini-3.1-flash-lite'infographic_model='gemini-3-pro-image'
- Alt Text (Accessibility): By default,
process_video generates multimodal alt text using the summary model (image-to-text) for any created infographic. Use alt_text_model to override the model for this step.
- Confirmation: Proceed without asking for extra confirmation unless parameters are missing.
3. Kitchen Sink (Comprehensive Processing)
Use this when the user asks for "everything", a "kitchen sink" run, or a "video summary". This generates transcripts, text summaries, Q&A, audio summaries (TTS), infographics, and combines them into a video file.
- Goal: Generate all possible artifacts, including a video file.
- Tool:
process_video
- Required Argument:
url (The YouTube link)
- Optional Arguments:
all_suite: Shortcut to set models ('gemini-flash' or 'gemini-pro').combine_infographic_audio: Set to True to create the final video (Requires video extra).verbose: Set to True for detailed logging.translate: Translate all outputs to a target language. Format: {model}-{language} e.g. gemini-3.1-flash-lite-es, or aws-translate-{language} e.g. aws-translate-es to use AWS Translate directly, or gcp-translate-{language} e.g. gcp-translate-es to use Google Cloud Translation directly.
- Model Selection Strategy:
- Pro (Default):
all_suite='gemini-pro' (best for video quality).
- Flash:
all_suite='gemini-flash' (faster).
- Language Handling:
- "spanish" or "es" ->
translate='gemini-3.1-flash-lite-es'
- "french" or "fr" ->
translate='gemini-3.1-flash-lite-fr'
- Default -> omit
translate (English only)
4. Custom / Advanced Usage
Use this when the user specifies particular models or output locations.
- Output Locations:
- Local: Default.
- Google Drive:
output_file='workspace' (Requires workspace extra).
- SharePoint:
output_file='sharepoint' (Requires m365 extra).
- Memory:
output_file='memory' (keeps artifacts in memory, no files on disk).
- Transcription Source:
- Default is YouTube captions.
- To use AI for transcription (STT), set
transcript_source to a model name (e.g., 'gemini-3.1-flash-lite' or 'gcp-chirp3').
- Note:
gcp- models require GOOGLE_CLOUD_PROJECT and optional YTD_GCS_BUCKET_NAME environment variables.
Tool Reference: process_video
| Argument | Description | Required Extra | Examples |
|---|
url | Required. YouTube URL, ID, Playlist ID, or Channel Handle. | - | https://youtu.be/..., @channel |
model | LLM for summaries/Q&A. | gcp / azure | gemini-3.1-flash-lite |
infographic_model | Model for generating the infographic image. | gcp | gemini-3-pro-image |
alt_text_model | Model for generating multimodal alt text for the infographic. | gcp | gemini-3.1-flash-lite |
tts_model | Model for text-to-speech audio. | gcp | gemini-3.1-flash-tts-preview-Kore, gcp-chirp3-Kore |
all_suite | Shortcut to apply a suite of models. | gcp, audio, video | gemini-pro, gemini-flash |
combine_infographic_audio | Boolean. If True, creates an MP4 video. | video | True |
translate | Translate all outputs to a target language. Format: {model}-{language}, aws-translate-{language}, or gcp-translate-{language}. | - | gemini-3.1-flash-lite-es, aws-translate-es, gcp-translate-es |
post_process | Post-process the transcript with JSON operations. Results added as CSV columns. | - | '{"word count": "apple"}', '{"word count": ["apple", "banana"]}' |
output_file | Destination for the CSV report. | workspace / m365 | workspace, sharepoint, memory |
transcript_source | Source for transcript (default: 'youtube'). | audio, gcp (for Chirp) | gemini-3.1-flash-lite, gcp-chirp3 |
Examples
User: "Get me a transcript of this video."
Action: Call process_video(url='...')
User: "Make an infographic for this video using Gemini Pro."
Action: Call process_video(url='...', model='gemini-3.1-pro-preview', infographic_model='gemini-3-pro-image')
User: "Do a kitchen sink run on this video in Spanish."
Action: Call process_video(url='...', all_suite='gemini-pro', combine_infographic_audio=True, verbose=True, translate='gemini-3.1-flash-lite-es')
User: "Summarize this playlist and save it to Drive."
Action: Call process_video(url='PL...', model='gemini-3.1-flash-lite', output_file='workspace')
User: "Count how many times 'apple' appears in this video's transcript."
Action: Call process_video(url='...', post_process='{"word count": "apple"}')
Development & CLI Usage
While this skill primarily uses the process_video tool, you can also run the underlying CLI manually for testing or development.
Note on CLI Syntax: The video URL/ID is a positional argument and is required. Do NOT use --url.
Always use uv to run the tool (do not use python directly) to ensure dependencies are correctly resolved:
uv run youtube-to-docs <video_url_or_id> [options]
uv run youtube-to-docs https://www.youtube.com/watch?v=B0x2I_doX9o
uv run youtube-to-docs B0x2I_doX9o --all gemini-pro --verbose
uv run youtube-to-docs B0x2I_doX9o -m gemini-3.1-flash-lite -tr gemini-3.1-flash-lite-es
uv run youtube-to-docs B0x2I_doX9o -pp '{"word count": ["apple", "banana"]}'
See docs/usage.md for full documentation and docs/development.md for setup details.
MCP Configuration:
The MCP server definition is located in gemini-extension.json (Gemini CLI) and .mcp.json (Claude Code). It is explicitly configured to use uv with --all-extras to ensure the correct environment and dependencies are used:
"command": "uv",
"args": [ ..., "run", "--all-extras", "python", "-m", "youtube_to_docs.mcp_server" ]
