pip install -r <skill_dir>/requirements.txt

uv run <skill_dir>/scripts/youtube_api.py search "python tutorial" --max-results 5

uv run <skill_dir>/scripts/youtube_api.py video "dQw4w9WgXcQ"

uv run <skill_dir>/scripts/youtube_api.py transcript "dQw4w9WgXcQ" --language en

uv run <skill_dir>/scripts/youtube_api.py channel "UC_x5XG1OV2P6uZZ5FSM9Ttw"

uv run <skill_dir>/scripts/youtube_api.py comments "dQw4w9WgXcQ" --max-results 10 --include-replies

uv run <skill_dir>/scripts/youtube_api.py related "dQw4w9WgXcQ" --max-results 5

uv run <skill_dir>/scripts/youtube_api.py trending --region US --max-results 10

uv run <skill_dir>/scripts/youtube_api.py enhanced-transcript "vid1" "vid2" \
  --format merged --include-metadata --language en

youtube_api.py search QUERY [OPTIONS]

Arguments:
  QUERY                          Search query string

Options:
  --max-results N                Number of results (default: 10, max: 50)
  --channel-id ID                Filter by channel
  --order ORDER                  Sort: date, rating, viewCount, relevance, title
  --duration DURATION            Filter: short (<4min), medium (4-20min), long (>20min)
  --published-after DATE         ISO date filter (e.g. 2024-01-01T00:00:00Z)
  --published-before DATE        ISO date filter
  --region CODE                  ISO country code (e.g. US, GB, JP)

youtube_api.py video VIDEO_ID

youtube_api.py channel CHANNEL_ID

youtube_api.py comments VIDEO_ID [OPTIONS]

Options:
  --max-results N                Number of comments (default: 20)
  --order ORDER                  Sort: relevance (default) or time
  --include-replies              Include reply threads
  --page-token TOKEN             Pagination token

youtube_api.py transcript VIDEO_ID [OPTIONS]

Options:
  --language CODE                Language code (e.g. en, ko, fr)

youtube_api.py related VIDEO_ID [OPTIONS]

Options:
  --max-results N                Number of results (default: 10)

youtube_api.py trending [OPTIONS]

Options:
  --region CODE                  ISO country code (default: US)
  --max-results N                Number of results (default: 5)

youtube_api.py enhanced-transcript VIDEO_ID [VIDEO_ID...] [OPTIONS]

Arguments:
  VIDEO_IDS                      One or more video IDs (max 5)

Options:
  --language CODE                Language code
  --format FORMAT                Output: raw, timestamped (default), merged
  --start-time SECONDS           Filter from this time
  --end-time SECONDS             Filter until this time
  --search QUERY                 Search within transcript text
  --case-sensitive               Case-sensitive search
  --segment-method METHOD        Segmentation: equal (default), smart
  --segment-count N              Number of segments (default: 1)
  --include-metadata             Include video details with transcript

{
  "success": true,
  "data": { ... },
  "error": null,
  "metadata": {
    "timestamp": "2025-01-26T12:00:00",
    ...
  }
}

import sys
from pathlib import Path
sys.path.insert(0, str(Path("<skill_dir>/scripts")))
from youtube_api import search_videos, get_video_details, get_video_transcript

# Search videos
result = search_videos("python tutorial", max_results=5)

# Get video details
result = get_video_details("dQw4w9WgXcQ")

# Get transcript
result = get_video_transcript("dQw4w9WgXcQ", language="en")

result=$(uv run <skill_dir>/scripts/youtube_api.py search "AI tutorials" --max-results 5)
echo "$result" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['data']['items'][0]['title'])"

# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "google-api-python-client>=2.169.0",
#     "youtube-transcript-api>=1.0.3",
#     "python-dotenv>=1.1.0",
# ]
# ///

import sys
from pathlib import Path
sys.path.insert(0, str(Path("<skill_dir>/scripts")))
from youtube_api import search_videos, get_video_transcript

def research_topic(topic: str, count: int = 10) -> list:
    """Search and get transcripts for top videos on a topic."""
    search_result = search_videos(topic, max_results=count)
    if not search_result["success"]:
        return []
    videos = search_result["data"]["items"]
    for v in videos:
        t = get_video_transcript(v["videoId"], language="en")
        v["transcript"] = t["data"]["text"] if t["success"] else None
    return videos