youtube-summarizer

youtube-summarizer

用途

此技能可提取 YouTube 视频的文字稿，并使用 STAR + R-I-S-E 框架生成全面、详尽的摘要。它会验证视频是否可用，使用 youtube-transcript-api Python 库提取文字稿，并生成详细文档，涵盖所有见解、论点和要点。

此技能面向需要对教育视频、讲座、教程或信息类内容进行深入分析并整理参考文档的用户。

何时使用此技能

适用于以下情况：

• 用户提供 YouTube 视频 URL，并希望获得详细摘要
• 用户需要记录视频内容以供参考，无需重新观看
• 用户希望从教育内容中提取见解、要点和论据
• 用户需要获取 YouTube 视频的文字稿以便分析
• 用户要求对 YouTube 视频进行“摘要”“概述”或“内容提取”
• 用户希望获得全面的文档，并优先考虑完整性而非简洁性

步骤 0：环境检测与设置

处理前，检测执行环境，以选择合适的文字稿提取策略。

环境检测

# Test 1: Can we run local Python?
python3 --version 2>/dev/null
PYTHON_AVAILABLE=$?

# Test 2: Is youtube-transcript-api installed?
python3 -c "import youtube_transcript_api" 2>/dev/null
LIB_AVAILABLE=$?

支持以下三种模式，并按顺序尝试：

模式	条件	策略
A — Python/CLI	有 Python 3 且已安装库	youtube-transcript-api（功能完整）
B — WebFetch	没有 Python，或处于沙盒环境	获取 YouTube 页面 → 从内嵌 JSON 中提取文字稿
C — 手动	网络层面无法访问 YouTube	请用户直接粘贴文字稿

模式 A 设置（有 Python，但未安装库）

如果有 Python，但未安装 youtube-transcript-api，则提供安装选项：

youtube-transcript-api is required but not installed.

Would you like to install it now?
- [ ] Yes - Install with pip (pip install youtube-transcript-api)
- [ ] No - I'll install it manually

pip install youtube-transcript-api

模式 B 设置（沙盒环境 / Claude Cowork / 没有 Python）

使用 WebFetch 从 YouTube 页面 HTML 中提取内嵌的文字稿。YouTube 会在页面源代码的 ytInitialPlayerResponse JSON 中嵌入完整的字幕轨道 URL。

步骤：

1. 使用 WebFetch 获取 https://www.youtube.com/watch?v=VIDEO_ID
2. 使用正则表达式从 HTML 中提取 ytInitialPlayerResponse JSON 区块
3. 解析 captions.playerCaptionsTracklistRenderer.captionTracks[0].baseUrl
4. 使用 WebFetch 获取该 URL，以检索文字稿 XML
5. 将 XML <text> 元素解析为纯文本

如果 YouTube 页面本身无法访问（代理/沙盒限制），则转到模式 C。

模式 C 设置（网络受限）

向用户明确说明：

⚠️  YouTube is not accessible in this environment.

Options:
1. Run this skill in Claude Code (CLI) — it has full network access and can install Python libraries.
2. Paste the video transcript text directly into this chat — the skill will summarize whatever text you provide.
3. Copy the transcript from youtube.com/watch?v=VIDEO_ID → click "..." → "Show transcript" → paste here.

主要工作流

进度跟踪指南

在整个工作流中，每个步骤开始前都显示可视化进度条，让用户了解进展。进度条格式如下：

echo "[████░░░░░░░░░░░░░░░░] 20% - Step 1/5: Validating URL"

格式要求：

• 宽度为 20 个字符（已完成部分使用 █，未完成部分使用 ░）
• 百分比递增：步骤 1 = 20%，步骤 2 = 40%，步骤 3 = 60%，步骤 4 = 80%，步骤 5 = 100%
• 显示当前步骤/总步骤数（例如：“步骤 3/5”）
• 简要描述当前阶段

步骤 1 前显示初始状态框：

╔══════════════════════════════════════════════════════════════╗
║     📹  YOUTUBE SUMMARIZER - Processing Video                ║
╠══════════════════════════════════════════════════════════════╣
║ → Step 1: Validating URL                 [IN PROGRESS]       ║
║ ○ Step 2: Checking Availability                              ║
║ ○ Step 3: Extracting Transcript                              ║
║ ○ Step 4: Generating Summary                                 ║
║ ○ Step 5: Formatting Output                                  ║
╠══════════════════════════════════════════════════════════════╣
║ Progress: ██████░░░░░░░░░░░░░░░░░░░░░░░░  20%               ║
╚══════════════════════════════════════════════════════════════╝

步骤 1：验证 YouTube URL

**目标：**提取视频 ID 并验证 URL 格式。

支持的 URL 格式：

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://m.youtube.com/watch?v=VIDEO_ID

操作：

# Extract video ID using regex or URL parsing
URL="$USER_PROVIDED_URL"

# Pattern 1: youtube.com/watch?v=VIDEO_ID
if echo "$URL" | grep -qE 'youtube\.com/watch\?v='; then
    VIDEO_ID=$(echo "$URL" | sed -E 's/.*[?&]v=([^&]+).*/\1/')
# Pattern 2: youtu.be/VIDEO_ID  
elif echo "$URL" | grep -qE 'youtu\.be/'; then
    VIDEO_ID=$(echo "$URL" | sed -E 's/.*youtu\.be\/([^?]+).*/\1/')
else
    echo "❌ Invalid YouTube URL format"
    exit 1
fi

echo "📹 Video ID extracted: $VIDEO_ID"

如果 URL 无效：

❌ Invalid YouTube URL

Please provide a valid YouTube URL in one of these formats:
- https://www.youtube.com/watch?v=VIDEO_ID
- https://youtu.be/VIDEO_ID

Example: https://www.youtube.com/watch?v=dQw4w9WgXcQ

第 2 步：检查视频和文字稿是否可用

进度：

echo "[████████░░░░░░░░░░░░] 40% - Step 2/5: Checking Availability"

目标： 使用检测到的模式确认视频存在且文字稿可访问。

模式 A（Python）：

from youtube_transcript_api import YouTubeTranscriptApi, TranscriptsDisabled, NoTranscriptFound
import sys

video_id = sys.argv[1]

try:
    transcript_list = YouTubeTranscriptApi.list_transcripts(video_id)
    print(f"✅ Video accessible: {video_id}")
    for transcript in transcript_list:
        lang_type = "[Auto-generated]" if transcript.is_generated else "[Manual]"
        print(f"  - {transcript.language} ({transcript.language_code}) {lang_type}")

except TranscriptsDisabled:
    print(f"❌ Transcripts are disabled for video {video_id}")
    sys.exit(1)
except NoTranscriptFound:
    print(f"❌ No transcript found for video {video_id}")
    sys.exit(1)
except Exception as e:
    print(f"❌ Error accessing video: {e}")
    sys.exit(1)

模式 B（WebFetch）：

使用 WebFetch 加载 https://www.youtube.com/watch?v=VIDEO_ID。在 HTML 中搜索字符串 "captionTracks"，以确认字幕可用。如果页面无法访问或未找到 captionTracks 键，则转到模式 C。

错误处理：

错误	消息	操作
未找到视频	"❌ Video does not exist or is private"	请用户检查 URL
已停用文字稿	"❌ Transcripts are disabled for this video"	无法继续
没有可用的文字稿	"❌ No transcript found"	无法继续
YouTube 被屏蔽（沙盒）	"⚠️ YouTube is not accessible in this environment"	切换到模式 C

第 3 步：提取文字稿

进度：

echo "[████████████░░░░░░░░] 60% - Step 3/5: Extracting Transcript"

目标： 使用当前模式获取文字稿文本。

模式 A（Python）：

from youtube_transcript_api import YouTubeTranscriptApi

video_id = "VIDEO_ID"

try:
    transcript = YouTubeTranscriptApi.get_transcript(
        video_id,
        languages=['pt', 'en']  # Prefer Portuguese, fallback to English
    )
    full_text = " ".join([entry['text'] for entry in transcript])
    print("✅ Transcript extracted successfully")
    print(f"📊 Transcript length: {len(full_text)} characters")
    with open(f"/tmp/transcript_{video_id}.txt", "w") as f:
        f.write(full_text)
except Exception as e:
    print(f"❌ Error extracting transcript: {e}")
    exit(1)

模式 B（WebFetch）：

1. 使用 WebFetch 获取 YouTube 视频页面：https://www.youtube.com/watch?v=VIDEO_ID
2. 在 HTML 中找到 ytInitialPlayerResponse JSON 块
3. 提取 captions.playerCaptionsTracklistRenderer.captionTracks[0].baseUrl
4. 使用 WebFetch 获取该字幕 URL（返回包含 <text> 元素的 XML）
5. 移除 XML 标签，并将 <text> 片段合并为纯文本

如果页面加载失败或未找到字幕轨道 URL，则切换到模式 C。

模式 C（手动）：

请用户提供文字稿：

⚠️  YouTube is not accessible in this environment (proxy/sandbox restriction).

To proceed, paste the video transcript text directly into this chat.
To get it: go to youtube.com/watch?v=VIDEO_ID → click "..." below the video → "Show transcript" → copy all text.

Alternatively, run this skill in Claude Code (CLI) for automatic extraction.

接受用户粘贴的任何纯文本，然后直接继续第 4 步。

文字稿处理（所有模式）：

• 将所有片段合并为连贯的文本
• 尽可能保留标点和格式
• 移除 [Music]、[Applause] 和其他自动生成的噪声标记

第 4 步：生成全面摘要

进度：

echo "[████████████████░░░░] 80% - Step 4/5: Generating Summary"

目标： 应用增强版 STAR + R-I-S-E 提示词，生成详细摘要。

已应用的提示词：

使用第 2 阶段的增强版提示词（STAR + R-I-S-E 框架），并将提取的文字稿作为输入。

操作：

1. 加载完整文字稿文本
2. 应用全面的摘要提示词
3. 使用 AI 模型（Claude/GPT）生成结构化摘要
4. 确保输出遵循定义的结构：
   • 包含视频元数据的标题
   • 执行摘要
   • 按章节详细拆解
   • 关键见解和结论
   • 概念和术语
   • 资源和参考资料

实现：

# Use the transcript file as input to the AI prompt
TRANSCRIPT_FILE="/tmp/transcript_${VIDEO_ID}.txt"

# The AI agent will:
# 1. Read the transcript
# 2. Apply the STAR + R-I-S-E summarization framework
# 3. Generate comprehensive Markdown output
# 4. Structure with headers, lists, and highlights

Read "$TRANSCRIPT_FILE"  # Read transcript into context

然后应用完整的摘要提示词（来自第 2 阶段的增强版）。

第 5 步：格式化并呈现输出

进度：

echo "[████████████████████] 100% - Step 5/5: Formatting Output"

目标： 以简洁、结构清晰的 Markdown 提供摘要。

输出结构：

# [Video Title]

**Channel:** [Channel Name]  
**Duration:** [Duration]  
**URL:** [https://youtube.com/watch?v=VIDEO_ID]  
**Published:** [Date if available]


## 📝 Detailed Summary

### [Topic 1]

[Comprehensive explanation with examples, data, quotes...]

#### [Subtopic 1.1]

[Detailed breakdown...]

### [Topic 2]

[Continued detailed analysis...]


## 📚 Concepts and Terminology

- **[Term 1]:** [Definition and context]
- **[Term 2]:** [Definition and context]


## 📌 Conclusion

[Final synthesis and takeaways]


*(Output follows same structure as Example 1.)*

## 📊 Executive Summary

This video provides a comprehensive introduction to the fundamental concepts of Artificial Intelligence (AI), designed for beginners and professionals who want to understand the technical foundations and practical applications of modern AI. The instructor covers everything from basic definitions to machine learning algorithms, using practical examples and visualizations to facilitate understanding.

[... continued detailed summary ...]

保存选项：

What would you like to save?
→ Summary + raw transcript

✅ File saved: summary-example123-2026-02-01.md (includes raw transcript)
[████████████████████] 100% - ✓ Processing complete!

欢迎观看这份机器学习基础知识的全面教程。在今天的视频中，我们将探讨支撑现代 AI 系统运行的核心概念……

## Error Handling

| Error | Likely Cause | Action |
|-------|-------------|--------|
| Invalid YouTube URL format | URL is not a recognized youtube.com or youtu.be pattern | Show valid URL formats, ask user to provide correct URL |
| Video not found or private | Video was removed, made private, or URL is wrong | Inform user, ask for a public video URL |
| Transcripts disabled | Creator disabled transcripts on this video | Inform user transcripts are unavailable; suggest manual transcription |
| No transcript found | Video has no auto-generated or manual transcript | Inform user; suggest trying a different video or using audio-transcriber |
| `youtube-transcript-api` not installed | Python dependency missing | Offer to install with `pip install youtube-transcript-api` |
| YouTube blocked — proxy/sandbox error | Running in Claude Cowork or other sandboxed environment | Switch to Mode B (WebFetch); if also blocked, switch to Mode C (manual paste) |
| Network error / timeout | Internet connectivity issue or YouTube rate-limiting | Retry once; if it persists, inform user and ask to try again later |
| Transcript in unexpected language | Video is in a language not supported by the analyzer | Report detected language; proceed with available transcript |

**Version:** 1.2.0
**Last Updated:** 2026-02-02
**Maintained By:** Eric Andrade