Media

Media: Extraction & Generation

This skill combines two capabilities: extracting metadata, transcripts, comments, chapters, and media from YouTube videos, and generating podcasts, videos, quizzes, reports, and more from research papers using Google NotebookLM.

YouTube Extraction

Instructions and tools for extracting metadata, transcripts, comments, chapters, and media from YouTube videos.

Prerequisites

pip install yt-dlp youtube-transcript-api youtube-comment-downloader

All three packages are pip-installable. No API keys required.

Commands

Extract everything (metadata + transcript + comments)

uv run ${CLAUDE_SKILL_DIR}/scripts/extract.py all "$ARGUMENTS" --max-comments 20 --lang en

Extract metadata only

uv run ${CLAUDE_SKILL_DIR}/scripts/extract.py metadata "$ARGUMENTS"

Extract transcript only

uv run ${CLAUDE_SKILL_DIR}/scripts/extract.py transcript "$ARGUMENTS" --lang en

Extract comments

uv run ${CLAUDE_SKILL_DIR}/scripts/extract.py comments "$ARGUMENTS" --max 20

Extract for research (compact summary with style hints)

uv run ${CLAUDE_SKILL_DIR}/scripts/extract.py research "$ARGUMENTS" --lang en

Download video

uv run ${CLAUDE_SKILL_DIR}/scripts/extract.py download-video "$ARGUMENTS" --quality 720p --output ./cache/downloads

Download audio (WAV)

uv run ${CLAUDE_SKILL_DIR}/scripts/extract.py download-audio "$ARGUMENTS" --output ./cache/downloads

Extract chapters as scenes

uv run ${CLAUDE_SKILL_DIR}/scripts/extract.py chapters "$ARGUMENTS" --lang en

Output

All commands output JSON to stdout by default. Use --output <file.json> to save to a file. Add --no-pretty to disable pretty-printing.

Guidelines

• Start with metadata to check the video exists and get basic info.
• Use transcript for lecture analysis, summarization, or content extraction.
• Use research for a compact, LLM-friendly summary with style hints and top comments.
• Use chapters to get chapter-aligned transcript segments.
• Only use download-video or download-audio when the user explicitly needs local media files.
• Always cite: video title, channel, and URL in any summary.

Content Generation (NotebookLM)

Generate podcasts, videos, quizzes, reports, and more from research papers using Google NotebookLM. This section covers both quick paper-to-podcast workflows and full NotebookLM CLI automation.

Prerequisites

NotebookLM requires a one-time browser login to Google. Check auth status before generating:

uv run ${CLAUDE_SKILL_DIR}/scripts/auth.py check

If not authenticated, guide the user to run:

uv run ${CLAUDE_SKILL_DIR}/scripts/auth.py login

This opens a browser for Google SSO. Credentials are cached at ~/.notebooklm/storage_state.json.

Required package: pip install notebooklm (or uv pip install notebooklm)

Agent Setup Verification

Before starting workflows, verify the CLI is ready:

1. notebooklm status -- Should show "Authenticated as: email@..."
2. notebooklm list --json -- Should return valid JSON (even if empty notebooks list)
3. If either fails -- Run notebooklm login

CI/CD, Multiple Accounts, and Parallel Agents

For automated environments, multiple accounts, or parallel agent workflows:

CI/CD setup: Set NOTEBOOKLM_AUTH_JSON from a secret containing your storage_state.json contents.

Multiple accounts: Use different NOTEBOOKLM_HOME directories per account.

Parallel agents: The CLI stores notebook context in a shared file (~/.notebooklm/context.json). Multiple concurrent agents using notebooklm use can overwrite each other's context.

Solutions for parallel workflows:

1. Always use explicit notebook ID (recommended): Pass -n <notebook_id> (for wait/download commands) or --notebook <notebook_id> (for others) instead of relying on use
2. Per-agent isolation: Set unique NOTEBOOKLM_HOME per agent: export NOTEBOOKLM_HOME=/tmp/agent-$ID
3. Use full UUIDs: Avoid partial IDs in automation (they can become ambiguous)

Available scripts

Quick Reference

Parallel safety: Use explicit notebook IDs in parallel workflows. Commands supporting -n shorthand: artifact wait, source wait, research wait/status, download *. Download commands also support -a/--artifact. Other commands use --notebook. For chat, use -c <conversation_id> to target a specific conversation.

Partial IDs: Use first 6+ characters of UUIDs. Must be unique prefix (fails if ambiguous). Works for ID-based commands such as use, source delete, and wait. For exact source-title deletion, use source delete-by-title "Title". For automation, prefer full UUIDs to avoid ambiguity.

Workflow

1. Generate a podcast from a paper

# From a local PDF
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py podcast ./papers/attention.pdf -o podcast.mp3

# From a URL (arXiv, web page, etc.)
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py podcast https://arxiv.org/abs/2401.12345 -o podcast.mp3

# Debate format (two speakers arguing perspectives)
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py podcast paper.pdf -o debate.mp3 --format debate

# Deep dive (20-30 min detailed analysis)
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py podcast paper.pdf -o deep.mp3 --format deep-dive --length long

# With custom focus instructions
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py podcast paper.pdf -o podcast.mp3 \
  --instructions "Focus on the methodology and experimental results, skip the related work"

# In another language
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py podcast paper.pdf -o podcast.mp3 --language ja

2. Generate other content types

# Video overview (MP4 with AI visuals)
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py video paper.pdf -o overview.mp4 --style cinematic

# Quiz from paper content
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py quiz paper.pdf -o quiz.json --difficulty hard

# Flashcards for study
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py flashcards paper.pdf -o cards.json

# Report (study guide, briefing doc, or blog post)
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py report paper.pdf -o guide.md --format study-guide

# Slide deck
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py slides paper.pdf -o slides.pdf

# Infographic
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py infographic paper.pdf -o infographic.png

3. Manage notebooks and artifacts

# List all notebooks
uv run ${CLAUDE_SKILL_DIR}/scripts/manage.py list

# List artifacts in a notebook
uv run ${CLAUDE_SKILL_DIR}/scripts/manage.py artifacts <notebook_id>

# Download an existing artifact
uv run ${CLAUDE_SKILL_DIR}/scripts/manage.py download <notebook_id> --artifact <artifact_id> -o output.mp3

# Delete a notebook
uv run ${CLAUDE_SKILL_DIR}/scripts/manage.py delete <notebook_id>

4. Multi-source notebooks (combine papers)

# Create a notebook, add multiple papers, then generate
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py podcast \
  paper1.pdf paper2.pdf paper3.pdf \
  -o combined_podcast.mp3 \
  --title "Survey of Attention Mechanisms" \
  --format deep-dive \
  --instructions "Compare and contrast the approaches across all papers"

5. Research to podcast (automated with subagent)

When the user wants full automation (generate and download when ready):

1. Create notebook and add sources as usual
2. Wait for sources to be ready (use source wait or check source list --json)
3. Run notebooklm generate audio "..." --json -- parse artifact_id from output
4. Spawn a background agent using Task tool:

   Task(
     prompt="Wait for artifact {artifact_id} in notebook {notebook_id} to complete, then download.
             Use: notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 600
             Then: notebooklm download audio ./podcast.mp3 -a {artifact_id} -n {notebook_id}",
     subagent_type="general-purpose"
   )
   

5. Main conversation continues while agent waits

Error handling in subagent:

• If artifact wait returns exit code 2 (timeout): Report timeout, suggest checking artifact list
• If download fails: Check if artifact status is COMPLETED first

6. Bulk import with source waiting (subagent pattern)

When adding multiple sources and needing to wait for processing before chat/generation:

1. Add sources with --json to capture IDs:

   notebooklm source add "https://url1.com" --json  # -> {"source_id": "abc..."}
   notebooklm source add "https://url2.com" --json  # -> {"source_id": "def..."}
   

2. Spawn a background agent to wait for all sources:

   Task(
     prompt="Wait for sources {source_ids} in notebook {notebook_id} to be ready.
             For each: notebooklm source wait {id} -n {notebook_id} --timeout 120
             Report when all ready or if any fail.",
     subagent_type="general-purpose"
   )
   

3. Main conversation continues while agent waits
4. Once sources are ready, proceed with chat or generation

Why wait for sources? Sources must be indexed before chat or generation. Takes 10-60 seconds per source.

7. Deep web research (subagent pattern)

Deep research finds and analyzes web sources on a topic:

1. Create notebook: notebooklm create "Research: [topic]"
2. Start deep research (non-blocking):

   notebooklm source add-research "topic query" --mode deep --no-wait
   

3. Spawn a background agent to wait and import:

   Task(
     prompt="Wait for research in notebook {notebook_id} to complete and import sources.
             Use: notebooklm research wait -n {notebook_id} --import-all --timeout 300
             Report how many sources were imported.",
     subagent_type="general-purpose"
   )
   

4. Main conversation continues while agent waits
5. When agent completes, sources are imported automatically

Alternative (blocking): For simple cases, omit --no-wait:

notebooklm source add-research "topic" --mode deep --import-all
# Blocks for up to 5 minutes

When to use each mode:

• --mode fast: Specific topic, quick overview needed (5-10 sources, seconds)
• --mode deep: Broad topic, comprehensive analysis needed (20+ sources, 2-5 min)

Research sources:

• --from web: Search the web (default)
• --from drive: Search Google Drive

Generation Types

All generate commands support:

• -s, --source to use specific source(s) instead of all sources
• --language to set output language (defaults to configured language or 'en')
• --json for machine-readable output (returns task_id and status)
• --retry N to automatically retry on rate limits with exponential backoff

Audio format reference

Video style reference

Features Beyond the Web UI

These capabilities are available via CLI but not in NotebookLM's web interface:

Command Output Formats

Commands with --json return structured data for parsing:

Create notebook:

$ notebooklm create "Research" --json
{"id": "abc123de-...", "title": "Research"}

Add source:

$ notebooklm source add "https://example.com" --json
{"source_id": "def456...", "title": "Example", "status": "processing"}

Generate artifact:

$ notebooklm generate audio "Focus on key points" --json
{"task_id": "xyz789...", "status": "pending"}

Chat with references:

$ notebooklm ask "What is X?" --json
{"answer": "X is... [1] [2]", "conversation_id": "...", "turn_number": 1, "is_follow_up": false, "references": [{"source_id": "abc123...", "citation_number": 1, "cited_text": "Relevant passage from source..."}, {"source_id": "def456...", "citation_number": 2, "cited_text": "Another passage..."}]}

Source fulltext (get indexed content):

$ notebooklm source fulltext <source_id> --json
{"source_id": "...", "title": "...", "char_count": 12345, "content": "Full indexed text..."}

Extract IDs: Parse the id, source_id, or task_id field from JSON output.

Status values:

• Sources: processing -> ready (or error)
• Artifacts: pending or in_progress -> completed (or unknown)

Language Configuration

Language setting controls the output language for generated artifacts (audio, video, etc.).

Important: Language is a GLOBAL setting that affects all notebooks in your account.

# List all 80+ supported languages with native names
notebooklm language list

# Show current language setting
notebooklm language get

# Set language for artifact generation
notebooklm language set zh_Hans  # Simplified Chinese
notebooklm language set ja       # Japanese
notebooklm language set en       # English (default)

Common language codes:

Override per command: Use --language flag on generate commands:

notebooklm generate audio --language ja   # Japanese podcast
notebooklm generate video --language zh_Hans  # Chinese video

Offline mode: Use --local flag to skip server sync:

notebooklm language set zh_Hans --local  # Save locally only
notebooklm language get --local  # Read local config only

Integration with research skill

The research skill downloads papers to ./papers/. Feed them directly:

# Step 1: Download paper (research skill)
uv run ${CLAUDE_SKILL_DIR}/../research/scripts/download.py 2401.12345 -o ./papers/

# Step 2: Generate podcast
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py podcast ./papers/2401.12345.pdf -o podcast.mp3

Processing Times

Polling intervals: When checking status manually, poll every 15-30 seconds to avoid excessive API calls.

Error Handling

On failure, offer the user a choice:

1. Retry the operation
2. Skip and continue with something else
3. Investigate the error

Exit Codes

All commands use consistent exit codes:

Examples:

• source wait returns 1 if source not found or processing failed
• artifact wait returns 2 if timeout reached before completion
• generate returns 1 if rate limited (check stderr for details)

Rules

Autonomy rules

Run automatically (no confirmation):

• notebooklm status - check context
• notebooklm auth check - diagnose auth issues
• notebooklm list - list notebooks
• notebooklm source list - list sources
• notebooklm artifact list - list artifacts
• notebooklm language list - list supported languages
• notebooklm language get - get current language
• notebooklm language set - set language (global setting)
• notebooklm artifact wait - wait for artifact completion (in subagent context)
• notebooklm source wait - wait for source processing (in subagent context)
• notebooklm research status - check research status
• notebooklm research wait - wait for research (in subagent context)
• notebooklm use <id> - set context (single-agent only -- use -n flag in parallel workflows)
• notebooklm create - create notebook
• notebooklm ask "..." - chat queries (without --save-as-note)
• notebooklm history - display conversation history (read-only)
• notebooklm source add - add sources

Ask before running:

• notebooklm delete - destructive
• notebooklm generate * - long-running, may fail
• notebooklm download * - writes to filesystem
• notebooklm artifact wait - long-running (when in main conversation)
• notebooklm source wait - long-running (when in main conversation)
• notebooklm research wait - long-running (when in main conversation)
• notebooklm ask "..." --save-as-note - writes a note
• notebooklm history --save - writes a note

General rules

• Always check auth status before first generation attempt
• Generation takes 1-5 minutes -- use --wait (default) to poll until complete
• NotebookLM has rate limits -- add delays between bulk generations
• Session cookies expire -- if auth fails, re-run auth.py login
• Downloaded audio is MP3, video is MP4
• Multi-source notebooks produce richer podcasts -- combine related papers when possible
• The --instructions flag is powerful -- use it to focus on specific sections or perspectives

Troubleshooting

notebooklm --help              # Main commands
notebooklm auth check          # Diagnose auth issues
notebooklm auth check --test   # Full auth validation with network test
notebooklm notebook --help     # Notebook management
notebooklm source --help       # Source management
notebooklm research --help     # Research status/wait
notebooklm generate --help     # Content generation
notebooklm artifact --help     # Artifact management
notebooklm download --help     # Download content
notebooklm language --help     # Language settings

Diagnose auth: notebooklm auth check - shows cookie domains, storage path, validation status Re-authenticate: notebooklm login Check version: notebooklm --version Update skill: notebooklm skill install