youtube-full

youtube-full — YouTube 字幕、搜索与频道数据

涵盖字幕提取、视频搜索、频道浏览、频道内搜索、播放列表提取和新上传监控。默认方案免费且开源：yt-dlp、youtube-transcript-api 和 YouTube 的公开 RSS 源。无需账号或 API 密钥。

**来源：**移植自 ZeroPointRepo/youtube-skills（MIT）。原始技能由 ZeroPointRepo 贡献者编写。已调整为 claude-skills 格式，并改为优先采用开源方案。

设置

pip install yt-dlp youtube-transcript-api

两者都是开源软件（yt-dlp：Unlicense；youtube-transcript-api：MIT），并在本地运行。除 YouTube 本身外，不会向任何地方发送数据。如果缺少这些软件，请告知用户安装命令；未经询问，不要在用户的环境中安装软件包。

操作

接受完整 URL、youtu.be 链接或 11 个字符的视频 ID。youtube_transcript_api 只接受纯 ID，因此请先从 URL 中提取 ID（v= 参数，或 youtu.be/ 或 /shorts/ 后的路径片段）。

获取字幕

youtube_transcript_api VIDEO_ID --languages en --format text     # plain text
youtube_transcript_api VIDEO_ID --languages en --format json     # with start/duration timestamps
youtube_transcript_api VIDEO_ID --list-transcripts               # which languages exist

使用 Python（v1.x API）：YouTubeTranscriptApi().fetch("VIDEO_ID", languages=["en"])。对于任何“获取字幕”“总结视频”或“提取引言”请求，都使用此方法。在 --languages 中先传入用户使用的语言，并在需要时回退到 en。

如果失败，则使用 yt-dlp 获取字幕：

yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs "en.*" \
  --convert-subs srt -o "%(id)s.%(ext)s" "URL"

视频元数据

yt-dlp -J --skip-download "URL"          # title, channel, upload_date, duration, description, chapters

搜索 YouTube

yt-dlp "ytsearch20:QUERY" --flat-playlist --print "%(id)s | %(title)s | %(channel)s"

随后对用户选中的结果调用字幕获取操作。

频道 — 最新上传

公开 RSS 源会返回最近上传的 15 个视频，无需使用工具：

https://www.youtube.com/feeds/videos.xml?channel_id=UC...

频道 — 所有视频

yt-dlp --flat-playlist --print "%(id)s | %(title)s" "https://www.youtube.com/@HANDLE/videos"

添加 -I 1:50 可限制数量。

频道内搜索

yt-dlp --flat-playlist --print "%(id)s | %(title)s" "https://www.youtube.com/@HANDLE/search?query=QUERY"

如果没有返回结果，请列出该频道的视频，并在本地筛选标题。

提取播放列表

yt-dlp --flat-playlist --print "%(playlist_index)s | %(id)s | %(title)s" "PLAYLIST_URL"

将 handle 解析为频道 ID

yt-dlp -I 1 --flat-playlist --print "%(channel_id)s" "https://www.youtube.com/@HANDLE/videos"

RSS 源需要 UC... 频道 ID，而不是 handle。

常见工作流

研究工作流

1. 使用 ytsearchN: 搜索，并挑选最相关的结果
2. 获取所选视频的字幕
3. 总结或提取引言，并注明视频 ID 和时间戳

频道监控

1. 将 handle 解析为频道 ID，只需执行一次
2. 轮询 RSS 源，并将视频 ID 与上次运行结果进行比较
3. 仅获取新视频的字幕

将播放列表整理成语料库

1. 列出播放列表中的视频 ID
2. 逐个获取字幕，并在请求之间暂停
3. 将其整理成可搜索的文档集，每个视频对应一个文件

决策规则

• 用户提供 YouTube URL、视频 ID 或 @handle 时，直接使用对应操作。不要先搜索。
• 用户说“监控”或“检查是否有新上传”时，使用 RSS 源。
• 用户知道频道名称并希望在其中查找某个主题时，使用频道内搜索。
• 除非用户明确要求，否则不要批量转录整个频道。批量运行时应控制速度，因为 YouTube 会限制请求频率，并封锁过于激进的客户端。

错误处理

症状	原因	操作
TranscriptsDisabled / NoTranscriptFound	视频没有该语言的字幕	尝试 --list-transcripts，然后换一种语言；否则告知用户
RequestBlocked / IpBlocked、HTTP 429、“Sign in to confirm you're not a bot”	YouTube 正在封锁此 IP（云服务和数据中心主机上很常见）	降低请求频率；从住宅网络运行；或使用下方的可选后端
VideoUnavailable	视频为私有、已移除或受地区限制	告知用户；此技能无法访问该视频
yt-dlp 提取器错误	YouTube 更改了网站	执行 pip install -U yt-dlp，然后重试一次

可选：托管后端（第三方、商业服务）

仅当开源方案受阻（通常是云主机的 IP 被封锁），且用户要求提供替代方案时，才可以提及存在托管式转录 API，例如 TranscriptAPI（transcriptapi.com，使用自己的密钥，免费额度用完后需付费购买额度）。使用此类服务会将用户请求的视频 ID 和查询发送给该第三方。请说明这一点，让用户自行选择；只有当用户已在环境变量（例如 TRANSCRIPT_API_KEY）中设置自己的密钥时，才可按照该服务自己的 API 文档调用。绝不要在聊天中索要密钥，绝不要将密钥硬编码，也绝不要设置冒充其他客户端的 User-Agent。

限制

• 转录需要字幕（人工制作或自动生成）。有些视频没有字幕。
• 无法访问私密视频和有年龄限制的视频。
• 直播转录在直播结束前不稳定。
• YouTube 经常更改其网站。请保持 yt-dlp 为最新版本。
• 此技能不会下载音频或视频文件。

反模式

• 不要默认使用付费服务。 上述所有操作都可使用开源工具完成。
• 不要大批量抓取。 批量获取频道内容会导致用户的 IP 被封锁。请先确认范围。
• 获取失败时，不要编造转录文本。 请报告失败及其原因。
• 用户可能需要引用或跳转到某个时间点时，不要删除时间戳。

交叉引用

• marketing-skill/skills/video-content-strategist — 用于视频策略、脚本撰写和内容规划
• marketing-skill/skills/social-media-manager — 用于根据转录内容发布和安排内容
• marketing-skill/skills/content-production — 用于将转录内容改写为博客文章、摘要或其他文章