tldw - YouTube 视频摘要工具

太长；没看

快速高效地提取并总结 YouTube 视频字幕文本。

概述

tldw 技能接收一个 YouTube URL，提取对应视频的字幕文本，并生成内容的全面摘要。这使你无需观看完整视频即可快速理解其核心内容。

目的

该技能旨在解决视频内容带来的信息过载问题。相比花费 10–60 分钟观看整段视频，你可在数秒内获得关键要点、主要论点与结论的精炼摘要。

适用场景

在以下情况中使用本技能：

• 用户提供 YouTube 视频 URL 并请求摘要
• 你需要在不观看视频的前提下快速理解其内容
• 你需要分析或引用特定视频中的内容
• 你需要从教育类、新闻类或纪录片类视频中提取信息

工作原理

1. 提取：使用 yt-dlp 下载视频字幕（即字幕/标题文本）
2. 清洗：执行去重处理，消除自动生成字幕中常见的冗余与异常内容
3. 处理：在主 agent 会话中直接分析清洗后的字幕文本
4. 摘要：返回结构化摘要，包含主要观点、关键论据与结论

核心特性

• 缓存机制：已下载的字幕文本将本地缓存，避免重复下载
• 去重能力：移除自动生成字幕中常见的连续重复行
• 多格式支持：兼容 VTT、SRT 和 JSON 格式的字幕文件
• Cookie 支持：可通过 Cookie 文件访问年龄限制内容
• 全面摘要：提供论点主旨、关键示例、对比分析及结论
• 快速处理：典型视频通常在数秒内完成摘要

署名说明

本技能基于 stong 开发的 tldw 项目构建。完整署名信息与许可证详情请参阅 ATTRIBUTION.md。

系统要求

系统需求

• Python：3.8 或更高版本
• 磁盘空间：约 60MB（用于虚拟环境及依赖项），外加字幕缓存所需额外空间

必需依赖项

该技能使用 Python 虚拟环境，依赖如下组件：

• yt-dlp：视频字幕下载器（通过 pip 安装）
• Python 标准库：json、re、argparse（内置模块）

所有依赖项均安装于本地虚拟环境 venv/ 中。

可选依赖项

• Cookie 文件：用于访问年龄限制内容或会员专属内容
  • 格式：Netscape Cookie 格式（可从浏览器导出）
  • 放置于技能目录中，并通过 --cookies 参数指定路径

目录结构

tldw/
├── SKILL.md              # 本文档
├── ATTRIBUTION.md        # 原始项目的署名说明
├── LICENSE               # AGPL-3.0 许可证
├── scripts/
│   └── extract_transcript.py   # 主提取脚本
├── cache/                # 缓存的字幕文件（自动创建）
└── venv/                 # Python 虚拟环境
    ├── bin/
    │   └── yt-dlp        # 视频字幕下载器
    └── lib/              # Python 包

配置步骤

按以下步骤完成 tldw 技能的配置：

1. 进入技能目录：

   cd tldw/
   

2. 创建 Python 虚拟环境：

   python3 -m venv venv
   

3. 安装依赖项：

   venv/bin/pip install yt-dlp webvtt-py
   

4. 验证安装是否成功：

   venv/bin/yt-dlp --version
   

5. 缓存目录将在首次运行时自动创建

至此，该技能已准备就绪，可立即使用！

使用说明

基础用法

当用户提供 YouTube URL 并请求摘要时，请遵循以下工作流：

1. 使用提取脚本获取字幕文本
2. 解析 JSON 输出以获取清洗后的字幕文本
3. 直接在主 agent 会话中对字幕进行摘要（切勿将大篇幅字幕交由子 agent 处理）
4. 向用户返回结构化摘要

命令语法

cd tldw/ && 
venv/bin/python scripts/extract_transcript.py 
  --json --cache-dir cache "YOUTUBE_URL"

输出处理

脚本返回如下结构的 JSON：

{
  "transcript": "完整清洗后的字幕文本...",
  "video_id": "video_id_here",
  "title": "视频标题",
  "description": "视频描述...",
  "duration": 1234,
  "uploader": "频道名称",
  "upload_date": "20260101",
  "view_count": 12345,
  "webpage_url": "https://www.youtube.com/watch?v=..."
}

提取 transcript 字段，并直接对其进行处理，生成全面摘要。

命令选项

• --json：以 JSON 格式输出（推荐用于程序解析）
• --cache-dir ：指定缓存目录（默认为 cache/）
• --cookies ：Netscape 格式 Cookie 文件路径，用于访问年龄限制内容

示例工作流

# 1. 提取字幕
cd tldw/ && 
venv/bin/python scripts/extract_transcript.py 
  --json --cache-dir cache "https://www.youtube.com/watch?v=VIDEO_ID"

# 2. 解析 JSON 输出并提取 transcript 字段

# 3. 直接对字幕进行摘要（包含主要观点、关键论据与结论）

# 4. 向用户返回格式化的摘要结果

访问年龄限制内容

如需访问年龄限制或会员专属视频，请从浏览器导出 Cookie：

1. 安装浏览器扩展（例如 “Get cookies.txt LOCALLY”）
2. 在已登录 YouTube 的状态下访问网站
3. 以 Netscape 格式导出 Cookie
4. 保存至 tldw 目录（例如：youtube_cookies.txt）
5. 调用时使用：--cookies youtube_cookies.txt

错误处理

无可用字幕

错误信息： "No subtitles/captions found"

含义： 该视频未提供自动生成或人工添加的字幕。

解决方案： 告知用户该视频因缺少字幕而无法生成文本摘要。

URL 无效

错误信息： "ERROR: unable to download video data"

含义： URL 格式错误、视频不存在，或为私有/已删除视频。

解决方案： 验证 URL 是否正确，并确认该视频是否公开可访问。

年龄限制内容

错误信息： "Sign in to confirm your age" 或其他类似身份验证错误

含义： 该视频需要年龄验证或 YouTube 登录状态。

解决方案： 使用 --cookies 参数配合导出的浏览器 Cookie（参见上方“访问年龄限制内容”章节）。

网络/连接错误

错误信息： "Unable to download"、"Connection timeout"、提取失败等

含义： 网络异常、YouTube 拒绝请求，或 yt-dlp 版本过旧（与当前 YouTube 不兼容）。

解决方案：

1. 首先升级 yt-dlp：

   cd tldw/ && 
   venv/bin/pip install --upgrade yt-dlp
   

2. 重试提取操作
3. 若仍失败：检查网络连接，或稍后重试

YouTube 频繁更新其 API，因此保持 yt-dlp 更新至关重要。

缓存问题

现象： 权限错误、磁盘空间满错误

含义： 缓存目录存在权限问题，或磁盘空间不足。

解决方案： 使用 df -h 检查剩余磁盘空间，并确认 cache/ 目录具有写入权限。

大篇幅字幕处理

注意： 超过 50,000 字符的字幕可能需要更长时间处理。

最佳实践： 在主 agent 会话中直接处理大篇幅字幕。请勿将其委派给子 agent，因实测表明子 agent 在处理大负载时不可靠。

调试方法

如需查看完整错误输出（而非仅最后 100 行）：

cd tldw/ && 
venv/bin/python scripts/extract_transcript.py 
  --json --cache-dir cache "YOUTUBE_URL"

如需检查已缓存的字幕文件：

ls -lh tldw/cache/

限制条件

字幕依赖性

• 该技能 仅适用于具备字幕/标题文本的视频
• 无法处理仅有音频而无字幕的视频（不内置语音转文字能力）
• 自动生成字幕可能存在错误、拼写错误或时间戳异常
• 去重逻辑有助于缓解自动生成字幕的问题，但效果并非完美

语言支持

• 取决于 YouTube 提供的字幕语言种类
• 脚本将提取所有可用字幕（自动生成或人工添加）
• 非英文字幕亦可处理，但摘要质量受限于所用语言模型的语言能力
• 英文字幕通常可获得最佳摘要效果

视频长度

• 超长视频（2 小时以上）可能生成极大字幕（超 100k 字符）
• 处理耗时随字幕长度线性增长
• 虽无硬性长度限制，但实际应用中需考虑上下文窗口容量与处理时效性

仅限 YouTube

• 当前 仅支持 YouTube URL
• 不支持其他视频平台（如 Vimeo、Dailymotion、TikTok 等）
• 尽管 yt-dlp 支持多种平台，但本脚本专为 YouTube 进行了优化

私有/受限内容

• 无法访问真正私有的视频（未对外公开分享）
• 会员专属或频道订阅内容需使用已认证会话导出的 Cookie
• 直播流可能需待直播结束后才提供字幕
• 部分地域限制即使使用 Cookie 也无法绕过

去重逻辑局限性

• 去重逻辑仅移除 连续重复的行
• 偶尔可能误删合法重复短语或副歌等有意重复内容
• 设计初衷主要针对自动生成字幕的异常，不覆盖全部重复场景
• 人工字幕通常无需去重处理

无音频提取功能

• 本技能仅提取 文本字幕，不提取音频文件
• 如需音频提取或处理，请使用其他工具（例如直接调用 yt-dlp 并启用音频相关参数）
• 本技能聚焦于文本内容分析，而非媒体文件处理