# 油管转录代理技能

> 通过 URL 或视频 ID 下载油管视频转录、字幕和封面图像。支持多语言、翻译、章节和说话人识别，以增强内容的可访问性。立即免费开始，只需几秒钟。

- Canonical: https://nanoskill.ai/zh/skills/youtube-transcript
- Markdown: https://nanoskill.ai/zh/skills/youtube-transcript.md
- Author: JimLiu
- Published: 2026-06-03T05:58:31.787Z
- Updated: 2026-07-15T13:36:15.347Z
- Language: zh-CN
- Source type: github
- Popularity signal: 1040

## Sources

- https://github.com/JimLiu/baoyu-skills

## Install

```shell
npx skills add https://github.com/JimLiu/baoyu-skills/tree/main/skills/baoyu-youtube-transcript
```

## About

油管转录下载器技能为从油管视频中提取全面信息提供了强大的解决方案。用户只需提供视频 URL 或 ID，即可轻松下载完整的油管转录、字幕甚至封面图像。该技能专为内容创作者、研究人员以及任何需要将口语内容转换为文本的人设计，提供多语言支持、翻译功能和高级结构化选项等特性。

该技能直接访问油管的 InnerTube API 并智能回退到 \`yt-dlp\`，无需个人 API 密钥即可确保可靠高效的数据检索。它提供灵活的输出格式，包括用于详细分析（带时间戳和章节标记）的 Markdown，以及用于标准字幕集成的 SRT。此外，它支持从视频描述中进行章节分割，并提供人工智能驱动的说话人识别工作流程，生成高度结构化和带归属的文本。

通过智能缓存，该技能最大限度地减少了冗余的网络请求，使对同一视频的后续操作异常快速。无论您是需要分析视频内容、创建可访问的字幕、为全球受众翻译素材，还是简单地提取视频元数据和缩略图，该技能都能简化流程，为油管内容管理提供强大工具。

## Key features

- **直接YouTube访问**: 直接访问YouTube的InnerTube API以快速检索转录文本，如果直接API被阻止，则自动回退到\`yt-dlp\`，确保无需API密钥即可可靠访问。
- **多语言支持与翻译**: 为转录文本指定首选语言，并将其翻译成目标语言，使内容可供全球观众访问。
- **章节分段与说话人识别**: 按视频章节自动分段转录文本，并支持AI后处理进行说话人识别，提供结构化且标注了归属的文本。
- **灵活的输出格式**: 生成带有时间戳的Markdown转录文本或SRT字幕文件，适用于从内容分析到视频播放器的各种用途。
- **智能缓存以提高效率**: 缓存原始视频数据、元数据和分段转录文本，能够快速重新格式化，并减少对同一视频的后续请求的网络调用。

## Use cases

- **生成用于内容分析的YouTube转录文本**: 内容创作者和研究人员可以快速获取完整的YouTube转录文本，包括时间戳和章节标记，以分析视频内容、提取关键信息或将口语内容改编为文本文章。
- **创建字幕文件以提高可访问性**: 视频编辑和可访问性专家可以从YouTube视频生成SRT字幕文件，确保内容可被听力障碍观众或喜欢静音观看内容的人访问。
- **翻译视频内容以扩大全球影响力**: 营销人员和教育工作者可以将YouTube转录文本翻译成多种语言，将其视频内容的覆盖面扩大到非母语使用者，并提高全球参与度。
- **提取元数据和封面图片**: 用户可以轻松提取视频元数据和高质量封面图片，这对于编目、社交媒体推广或创建与视频内容相关的视觉资产非常有用。

## Result preview

探索由该技能提供支持的专业视频分析报告。

![A presentation cover slide featuring a TED Talk analysis titled 'This Is How Kids Should Be Learning with AI'. The slide uses a bold red background with large white headline text centered prominently across the page. Beneath the title, the speaker and event are identified as 'Priya Lakhani | TEDNext 2025', accompanied by the subtitle 'TED Talk Analysis & Knowledge Report'. The lower portion of the slide contains a thumbnail image from the TED presentation showing the speaker on stage alongside the text 'AI Isn't a Shortcut to Learning'. A teal horizontal accent bar runs along the bottom edge, creating visual contrast. The overall design resembles a professional report or presentation cover summarizing key insights from a TED Talk about artificial intelligence and education.](https://file.nanoskill.ai/youtube-transcript-outcome1.png)

![A report page titled '\[ Executive Summary \]' from a TED Talk analysis on artificial intelligence and education. The page summarizes key arguments presented by education entrepreneur Priya Lakhani at TEDNext 2025, discussing the impact of AI in classrooms, the risks of students using AI to avoid learning, and the importance of productive struggle in effective education. Several paragraphs explain how neuroscience-informed AI systems can support deeper learning when designed to challenge rather than replace student effort. A section titled 'Key Statistics at a Glance' highlights major findings using four large color-coded statistic cards. The statistics include 20% of UK students leaving secondary school without adequate reading and writing skills, 74% of teachers considering leaving the profession within three years due to workload, one in five students using AI to complete all homework assignments, and over 40 billion data points collected on how children learn. The layout uses a clean report style with a red section header, structured text blocks, and colorful infographic-style data highlights to emphasize key educational challenges and opportunities.](https://file.nanoskill.ai/youtube-transcript-outcome2.png)

![A report page titled '\[ The Four Pillars of Learning \]' that presents four evidence-based learning principles supported by cognitive science and educational research. The page is organized into four color-coded sections: Retrieval Practice, Spacing, Generation, and Reflection. Each section includes a concise explanation of the learning principle and a highlighted 'Classroom Applications' box containing practical implementation examples. Retrieval Practice emphasizes recalling information from memory through activities such as flashcards, self-testing, and closed-book quizzes. Spacing focuses on distributing learning over time using spaced repetition and interleaved study sessions. Generation encourages learners to produce answers themselves through prediction, fill-in-the-blank exercises, and open-ended questioning. Reflection highlights structured self-assessment and feedback processes that help students evaluate progress, identify learning goals, and address knowledge gaps. The page uses a clean educational report layout with colored headers, explanatory text, and application callout boxes to summarize effective learning strategies for classrooms and AI-supported education.](https://file.nanoskill.ai/youtube-transcript-outcome3.png)

![A report page from a TED Talk analysis featuring two major sections: 'Neuroscience: The London Taxi Study' and 'AI in Education: Well-Designed vs. Poorly Used.' The first section explains a neuroscience study of London black cab drivers who memorize thousands of city streets to pass 'The Knowledge' exam. It describes how brain scans revealed that experienced drivers developed a larger hippocampus, demonstrating that sustained mental effort and navigation challenges can physically strengthen the brain. A highlighted key insight box emphasizes that mental effort is essential for durable learning, expertise development, and human creativity rather than being a flaw in the learning process. The second section presents a side-by-side comparison of educational AI usage. The left panel, labeled 'AI Well-Designed,' lists benefits such as identifying learning patterns, predicting forgetting, encouraging answer generation, providing targeted feedback, personalizing instruction, supporting teachers, and reducing workload. The right panel, labeled 'AI Poorly Used,' outlines risks including students using AI to complete all work, avoiding genuine learning, replacing thinking with shortcuts, creating false confidence, confusing fluency with understanding, and reducing productive struggle. The layout uses contrasting green and red comparison panels, educational report styling, and structured visual hierarchy to highlight the difference between AI that supports learning and AI that undermines it.](https://file.nanoskill.ai/youtube-transcript-outcome4.png)

## Result walkthrough

### 安装

将油管转录代理技能添加到您的人工智能代理。

![A screenshot showing the installation process of the 'baoyu-youtube-transcript' AI agent skill from a GitHub repository using an NPX command. At the top, a blue command banner displays the installation command for adding the skill from the GitHub repository. Below, a conversational interface explains the installation workflow, including handling an interactive installation prompt, detecting that the process did not complete automatically, rerunning the command with a '-y' flag to bypass prompts, and explicitly targeting the Hermes Agent environment. The log then describes creating a symbolic link from the agent skills directory to the Hermes skills directory so the skill can be recognized by the Hermes Agent. A final confirmation states that the 'baoyu-youtube-transcript' skill was successfully installed, linked, and is available for use through a skill invocation command. The interface uses a clean chat-style layout with gray response panels, dark blue command highlighting, and monospaced code snippets for file paths and terminal commands.](https://file.nanoskill.ai/youtube-transcript-install.png)

### 提供内容

分享油管链接并指定您想要的输出格式。

![A screenshot showing a prompt and response workflow for a YouTube transcript analysis skill. The top section contains a dark blue prompt panel describing an AI-powered content research and knowledge extraction system designed to analyze YouTube videos and transform them into structured knowledge assets. The prompt outlines requirements such as extracting complete transcripts, metadata, chapter structures, timestamps, speaker distinctions, key topics, major insights, statistics, examples, and actionable takeaways. It also lists supported output formats including executive summaries, study notes, blog articles, social media content, newsletter drafts, and research reports. Additional instructions emphasize transcript quality evaluation, improved readability, information hierarchy, redundancy removal, and generating a polished final deliverable. The requested output is a visually engaging PDF report with chapter navigation, highlighted takeaways, and presentation-ready layouts. Beneath the prompt, a gray response panel shows the AI acknowledging that the skill has been loaded successfully but explaining that a YouTube URL is still required before transcript extraction and report generation can begin. The interface uses a clean chat-style layout with large rounded panels, white text on a dark blue background, and structured instructional formatting.](https://file.nanoskill.ai/youtube-transcript-task.png)

### 提取见解

生成结构化的转录文本、摘要、关键要点和可重复使用的内容。

![A presentation cover slide for a TED Talk analysis and knowledge report. The slide features a bold red background with a teal accent bar running along the bottom edge. Centered at the top is the large white title 'This Is How Kids Should Be Learning with AI.' Below the title, the speaker attribution reads 'Priya Lakhani | TEDNext 2025,' followed by the subtitle 'TED Talk Analysis & Knowledge Report' in italicized white text. In the center of the slide is a thumbnail image from the TED Talk showing Priya Lakhani on stage. The thumbnail includes the prominent message 'AI Isn't a Shortcut to Learning' alongside the TED logo. The overall design resembles a professional research report cover, using strong typography, high contrast colors, and a clean layout to introduce an educational analysis focused on artificial intelligence, learning science, and the future of education.](https://file.nanoskill.ai/youtube-transcript-outcome.png)

## Skill definition

# YouTube 字幕下载

从 YouTube 视频下载字幕（副标题/隐藏式字幕）。支持手动创建和自动生成的字幕。无需 API 密钥或浏览器——直接使用 YouTube 的 InnerTube API，当 YouTube 阻断直接 API 路径时自动回退至 `yt-dlp`。

首次运行时获取视频元数据和封面图片，缓存原始数据以便快速重新格式化。

## 脚本目录

脚本位于 `scripts/` 子目录中。`{baseDir}` = 此 SKILL.md 的目录路径。解析 `${BUN_X}` 运行时：如果已安装 `bun` → 使用 `bun`；如果 `npx` 可用 → 使用 `npx -y bun`；否则建议安装 bun。将 `{baseDir}` 和 `${BUN_X}` 替换为实际值。

| 脚本 | 用途 |
|--------|---------|
| `scripts/main.ts` | 字幕下载命令行工具 |

## 用法

```bash
# 默认：带时间戳的 Markdown（英文）
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-or-id>

# 指定语言（按优先级顺序）
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

# 不带时间戳
${BUN_X} {baseDir}/scripts/main.ts <url> --no-timestamps

# 带章节划分
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# 带说话人识别（需要 AI 后处理）
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# SRT 字幕文件
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

# 翻译字幕
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# 列出可用字幕
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# 强制重新获取（忽略缓存）
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh
```

## 选项

| 选项 | 描述 | 默认值 |
|--------|-------------|---------|
| `<url-or-id>` | YouTube 网址或视频 ID（允许多个） | 必需 |
| `--languages <codes>` | 语言代码，逗号分隔，按优先级顺序 | `en` |
| `--format <fmt>` | 输出格式：`text`、`srt` | `text` |
| `--translate <code>` | 翻译为指定的语言代码 | |
| `--list` | 列出可用字幕，而不是获取 | |
| `--timestamps` | 每个段落包含 `[HH:MM:SS → HH:MM:SS]` 时间戳 | 开启 |
| `--no-timestamps` | 禁用时间戳 | |
| `--chapters` | 从视频描述中进行章节划分 | |
| `--speakers` | 带元数据的原始字幕，用于说话人识别 | |
| `--exclude-generated` | 跳过自动生成的字幕 | |
| `--exclude-manually-created` | 跳过手动创建的字幕 | |
| `--refresh` | 强制重新获取，忽略缓存数据 | |
| `-o, --output <path>` | 保存到指定的文件路径 | 自动生成 |
| `--output-dir <dir>` | 基础输出目录 | `youtube-transcript` |

## 可选环境变量

| 变量 | 描述 |
|----------|-------------|
| `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER` | 在回退时传递给 `yt-dlp --cookies-from-browser`，例如 `chrome`、`safari`、`firefox` 或 `chrome:Profile 1` |

## 输入格式

接受以下任意一种作为视频输入：
- 完整网址：`https://www.youtube.com/watch?v=dQw4w9WgXcQ`
- 短网址：`https://youtu.be/dQw4w9WgXcQ`
- 嵌入网址：`https://www.youtube.com/embed/dQw4w9WgXcQ`
- Shorts 网址：`https://www.youtube.com/shorts/dQw4w9WgXcQ`
- 视频 ID：`dQw4w9WgXcQ`

## 输出格式

| 格式 | 扩展名 | 描述 |
|--------|-----------|-------------|
| `text` | `.md` | 带前置元数据（包括 `description`）、标题、摘要、可选的目录/封面/时间戳/章节/说话人的 Markdown |
| `srt` | `.srt` | 供视频播放器使用的 SubRip 字幕格式 |

## 输出目录

```
youtube-transcript/
├── .index.json                            # 视频 ID → 目录路径映射（用于缓存查找）
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # 视频元数据（标题、频道、描述、时长、章节等）
    ├── transcript-raw.json              # 来自 YouTube API 的原始字幕片段（缓存）
    ├── transcript-sentences.json        # 按句子分割的字幕（按标点分割，跨片段合并）
    ├── imgs/
    │   └── cover.jpg                    # 视频缩略图
    ├── transcript.md                    # Markdown 字幕（由句子生成）
    └── transcript.srt                   # SRT 字幕（由原始片段生成，如果使用 --format srt）
```

- `{channel-slug}`：频道名称的短横线命名
- `{title-full-slug}`：完整视频标题的短横线命名

`--list` 模式仅输出至标准输出（不保存文件）。

## 缓存机制

首次获取时，脚本会保存：
- `meta.json` — 视频元数据、章节、封面图片路径、语言信息
- `transcript-raw.json` — 来自 YouTube API 的原始字幕片段（`{ text, start, duration }[]`）
- `transcript-sentences.json` — 按句子分割的字幕（`{ text, start: "HH:mm:ss", end: "HH:mm:ss" }[]`），按句子结束标点（`.?!…。？！` 等）分割，时间戳按字符长度比例分配，兼顾中日韩文字合并
- `imgs/cover.jpg` — 视频缩略图

同一视频的后续运行使用缓存数据（无网络请求）。使用 `--refresh` 强制重新获取。如果请求了其他语言，缓存会自动刷新。

当 YouTube 在直接 InnerTube 路径上返回反机器人/被屏蔽的响应时，脚本会尝试使用备用客户端身份，然后如果可用，则回退至 `yt-dlp`。如果需要回退但 `yt-dlp` 不可用，代理应自行决定如何使 `yt-dlp` 可用并继续，而不是将安装决定推给用户。

SRT 输出（`--format srt`）由 `transcript-raw.json` 生成。文本/Markdown 输出使用 `transcript-sentences.json` 以获得自然句子边界。

## 工作流程

当用户提供 YouTube 网址并想要字幕时：

1. 如果用户未指定语言，先使用 `--list` 运行，以显示可用选项
2. 运行脚本时**始终对 URL 使用单引号**——zsh 将 `?` 视为通配符，因此不加引号的 YouTube 网址会导致“未找到匹配项”：应使用 `'https://www.youtube.com/watch?v=ID'`
3. 默认：使用 `--chapters --speakers` 运行以获得最丰富的输出（章节 + 说话人识别）
3. 脚本自动保存缓存数据和输出文件，并打印文件路径
4. 对于 `--speakers` 模式：在脚本保存原始文件后，按照下面的说话人识别工作流程进行后处理，添加说话人标签

当用户仅想要封面图片或元数据时，使用任何选项运行脚本都会缓存 `meta.json` 和 `imgs/cover.jpg`。

当重新格式化同一视频时（例如，先是文本然后 SRT），会重用缓存数据——无需重新获取。

## 章节与说话人工作流程

### 章节（`--chapters`）

脚本从视频描述中解析章节时间戳（例如 `0:00 引言`），按章节边界分割字幕，将片段分组为可读段落，并以 `.md` 文件保存，包含目录。无需进一步处理。

如果描述中不存在章节时间戳，则字幕以分组段落形式输出，不含章节标题。

### 说话人识别（`--speakers`）

说话人识别需要 AI 处理。脚本输出一个原始 `.md` 文件，包含：
- 带有视频元数据的 YAML 前置内容（标题、频道、日期、封面、描述、语言）
- 视频描述（用于提取说话人姓名）
- 描述中的章节列表（如果可用）
- SRT 格式的原始字幕（预计算的开始/结束时间戳，节省 token）

在脚本保存原始文件后，生成一个子代理（为了节约成本，可使用 Sonnet 等较便宜的模型）来处理说话人识别：

1. 读取保存的 `.md` 文件
2. 读取 `{baseDir}/prompts/speaker-transcript.md` 处的提示词模板
3. 按照提示词处理原始字幕：
   - 使用视频元数据识别说话人（标题 → 嘉宾，频道 → 主持人，描述 → 姓名）
   - 根据对话流、问答模式和上下文线索检测说话人转换
   - 划分章节（如果有描述中的章节则使用，否则根据话题转换创建）
   - 使用 `**说话人姓名：**` 标签、段落分组（2-4 个句子）和 `[HH:MM:SS → HH:MM:SS]` 时间戳进行格式化
4. 用处理后的字幕覆盖 `.md` 文件（保留 YAML 前置内容）

当使用 `--speakers` 时，隐含了 `--chapters`——处理后的输出始终包含章节划分。

## 错误情况

| 错误 | 说明 |
|-------|---------|
| 字幕已禁用 | 视频没有任何字幕 |
| 未找到字幕 | 请求的语言不可用 |
| 视频不可用 | 视频已被删除、设为私密或存在地区限制 |
| IP 被屏蔽 | 请求过多，请稍后重试 |
| 年龄限制 | 视频需要登录以进行年龄验证 |
| 检测到机器人 | 脚本会尝试使用备用客户端，然后尝试 `yt-dlp`；如果缺少回退工具，代理应自行解决，否则如果仍然失败，请尝试 `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER=safari`（或您的浏览器） |

## FAQ

### 什么是 YouTube 转录下载器技能？

YouTube 转录下载器技能是一个工具，允许您仅使用视频的URL或视频ID，即可从YouTube视频下载转录文本、字幕和封面图片。它支持多种功能，如多语言检索、翻译、章节分段和说话人识别。

### 该技能如何在没有API密钥的情况下获取YouTube转录文本？

该技能直接使用YouTube的InnerTube API来获取转录文本。如果直接访问被阻止，它会自动回退到\`yt-dlp\`，以确保无需单独的API密钥即可可靠地检索转录文本。

### 我可以获取英语以外的其他语言的转录文本吗？

是的，您可以使用\`--languages\`选项指定用逗号分隔的语言代码列表。该技能将尝试按指定的优先级顺序获取转录文本。您还可以使用\`--translate\`选项将转录文本翻译成另一种语言。

### 它支持说话人识别和章节分段吗？

是的，该技能支持使用\`--chapters\`选项从视频描述中进行章节分段。对于说话人识别，您可以使用\`--speakers\`选项，它会输出一个原始文件，供AI后处理来标记说话人。

### YouTube转录文本有哪些可用的输出格式？

您可以以Markdown（\`.md\`）格式输出转录文本，包括时间戳、章节和可选的说话人数据，或者输出为SRT（\`.srt\`）字幕文件，该文件与大多数视频播放器兼容。

### 是否有缓存机制，它是如何工作的？

是的，该技能会缓存视频元数据、原始转录数据和分段句子。后续对同一视频的运行将使用这些缓存数据，从而加快处理速度。您可以使用\`--refresh\`选项强制重新获取。