| name | video-to-markdown |
| description | 视频转 Markdown 技能。从在线视频（YouTube、Bilibili 等）提取语音内容， 生成带时间戳的字幕文本和结构化 Markdown 文档。当用户需要视频总结、 视频笔记、提取视频内容、分析视频要点时使用此技能。 支持长视频处理，输出包含完整字幕和结构化要点。 |
| license | MIT |
| compatibility | 需要安装 yt-dlp、FFmpeg 和 openai-whisper。 Python 3.8+ 和 uv 包管理器。 |
| metadata | {"author":"copilot-tools","version":"1.1.0","tools":["yt-dlp","ffmpeg","whisper"]} |
| allowed-tools | Bash(uv:*) Bash(python:*) Bash(yt-dlp:*) Bash(ffmpeg:*) Read |
视频转 Markdown 技能
从在线视频提取语音内容，生成结构化的 Markdown 文档，包含完整字幕和时间戳。
文件存储规范
| 文件类型 | 存储位置 | 说明 |
|---|
| 临时字幕文件 | tmp/video-to-markdown/docs/ | 脚本生成的原始字幕 Markdown（含完整时间戳字幕） |
| 最终总结文档 | docs/video-to-markdown/ | 经 LLM 分析后的摘要文档，不含完整字幕，与临时文件同名 |
⚠️ 重要:
- 脚本输出的字幕文件统一保存到
tmp/video-to-markdown/docs/ 目录
- LLM 生成摘要后，将仅包含摘要的文档保存到
docs/video-to-markdown/ 目录，保持同名
- 最终总结文档不需要保留完整字幕，只保留结构化摘要
工作流程
- 获取视频信息: 使用 yt-dlp 获取视频元数据
- 下载字幕（优先）: 尝试下载视频自带的人工/自动字幕
- 语音识别（备用）: 如果没有字幕，使用 Whisper 进行语音识别
- 生成临时文件: 输出带时间戳的 Markdown 到
tmp/video-to-markdown/docs/
- LLM 分析: 根据字幕内容生成要点摘要
- 保存最终文档: 将摘要文档（不含字幕）保存到
docs/video-to-markdown/，保持同名
💡 优先使用视频自带字幕：YouTube、Bilibili 等平台的视频大多有字幕，直接下载比语音识别更快更准确。
使用方法
步骤 1: 提取字幕
cd .github/skills/video-to-markdown
uv run scripts/video_to_markdown.py <视频URL> --output ../../../tmp/video-to-markdown/docs/<文件名>.md
步骤 2: 生成摘要
脚本输出字幕内容后，LLM 应根据字幕内容生成结构化摘要。
步骤 3: 保存最终文档
将包含字幕和摘要的完整文档保存到 docs/video-to-markdown/ 目录，保持与临时文件同名。
示例
uv run scripts/video_to_markdown.py "https://www.youtube.com/watch?v=xxxxx" \
--output ../../../tmp/video-to-markdown/docs/视频标题.md
uv run scripts/video_to_markdown.py "https://www.bilibili.com/video/BVxxxxx" \
--output ../../../tmp/video-to-markdown/docs/视频标题.md
uv run scripts/video_to_markdown.py "https://..." --lang zh
uv run scripts/video_to_markdown.py "https://..." --force-whisper --model medium
命令行参数
| 参数 | 说明 | 默认值 |
|---|
url | 视频 URL（必需） | - |
--lang | 优先下载的字幕语言（如 zh, en, ja） | 自动选择 |
--model | Whisper 模型，仅在无字幕时使用 | base |
--output | 输出文件路径（建议使用 tmp/video-to-markdown/docs/） | <video_title>.md |
--force-whisper | 强制使用语音识别，忽略自带字幕 | False |
--keep-audio | 保留下载的音频文件 | False |
--json | 输出 JSON 格式 | False |
输出格式
生成的 Markdown 文件结构：
# 视频标题
> 来源: [原始链接](URL)
> 时长: HH:MM:SS
> 提取时间: YYYY-MM-DD
## 完整字幕
[00:00:00] 字幕内容...
[00:00:05] 字幕内容...
...
---
## 要点摘要
（由 LLM 根据字幕内容生成）
依赖工具
安装 Python 依赖
使用 uv 安装视频处理相关依赖：
uv sync --extra video
安装 FFmpeg
FFmpeg 需要单独安装（非 Python 包）：
winget install FFmpeg
brew install ffmpeg
sudo apt install ffmpeg
验证安装
uv run yt-dlp --version
ffmpeg -version
uv run whisper --help
详细文档
常见场景
| 用户问题 | 处理方式 |
|---|
| "帮我总结这个视频" | 提取字幕后生成要点摘要 |
| "这个视频讲了什么" | 提取字幕并分析主要内容 |
| "把视频转成文字" | 提取完整字幕文本 |
| "视频太长，帮我提炼要点" | 提取字幕后生成结构化摘要 |
注意事项
- 字幕优先: 脚本会优先下载视频自带字幕，比语音识别更快更准确
- 语言选择: 使用
--lang zh 优先下载中文字幕
- Whisper 备用: 仅在视频无字幕时才使用 Whisper，可用
--force-whisper 强制启用
- 模型选择: base 模型速度快但准确度一般，medium/large 更准确但更慢
- 网络要求: 下载视频和字幕需要网络，Whisper 本地运行无需网络
