skills 视频下载器实战:yt-dlp 一键下载,1080p 与纯音频 MP3 多格式自由控制
skills 视频下载器实战:yt-dlp 一键下载,1080p 与纯音频 MP3 多格式自由控制
skills 开源仓库中的 video-downloader 视频下载器,基于 yt-dlp 一键下载 YouTube 视频,支持 1080p 高清、WebM/MKV 多格式容器与纯音频 MP3 提取,参数自由组合、依赖自动安装,是新手也能上手的实用 Skill 工具。
一、video-downloader 是什么?
video-downloader 是 skills 仓库(一个 Claude Code Skills 实用工具集合)中封装好的视频下载技能,底层由强大的开源下载器 yt-dlp 驱动,帮你把 YouTube 视频"按需"存到本地:
- 🎬 质量可选:best / 1080p / 720p / 480p / 360p / worst 六档清晰度
- 🎵 纯音频模式:一键提取最高质量的 MP3,适合做播客素材
- 📦 格式可控:MP4、WebM、MKV 三种容器随心切换
- 🔄 零配置起步:未安装 yt-dlp 时脚本会自动安装
- 📊 下载前预览:先显示视频标题、时长、上传者再开始下载
详细说明见 video-downloader/README_CN.md,技能定义文件为 video-downloader/SKILL.md。
二、快速开始:一条命令下载视频
获取仓库后,最简单的下载方式只需一行命令(在 video-downloader 目录下执行):
python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID"
这条命令会以最佳质量下载视频并保存为 MP4,默认输出目录为 /mnt/user-data/outputs/,文件名自动取自视频标题。运行前你还会看到类似这样的信息预览:
Title: 视频标题
Duration: 12:34
Uploader: 上传者名称
核心实现就一个脚本:scripts/download_video.py。
三、如何指定 1080p / 720p 等清晰度?
用 -q(或 --quality)参数指定清晰度即可:
# 下载 1080p 全高清视频
python scripts/download_video.py "URL" -q 1080p
# 下载 720p 高清,体积更小
python scripts/download_video.py "URL" -q 720p
各档位含义一览:
| 参数 | 含义 | 适用场景 |
|---|---|---|
best(默认) |
最高可用质量 | 追求画质、带宽充足 |
1080p |
全高清 | 大屏观看、存档 |
720p |
高清 | 日常观看,画质体积均衡 |
480p |
标清 | 弱网环境、省流量 |
360p |
较低质量 | 快速预览 |
worst |
最低可用质量 | 极省空间 |
实现原理:脚本会把 1080p 这类值转换成 yt-dlp 的流过滤表达式 bestvideo<a href="https://link.gitcode.com/i/c58eb60c506b6fd454bd909d43a442c4" target="_blank">height<=1080]+bestaudio,见 [download_video.py。注意:部分视频并不提供所有清晰度,选不到时脚本会退回可用的最佳流。
四、MP4 / WebM / MKV 三种格式怎么选?
用 -f(或 --format)指定输出容器,仅对视频下载生效:
python scripts/download_video.py "URL" -f webm
| 格式 | 特点 | 推荐场景 |
|---|---|---|
mp4(默认) |
兼容性最好,几乎通吃 | 绝大多数场景 |
webm |
现代格式,同清晰度下体积更小 | 网页播放、省空间 |
mkv |
Matroska 容器,扩展性强 | 多音轨/字幕存档 |
视频与音频流可能分开下载,脚本会借助 ffmpeg 自动合并成你指定的容器格式(合并参数见 download_video.py),所以系统里通常需要一个预装好的 ffmpeg。
五、纯音频 MP3 下载:播客素材一步到位
只想要声音不要画面?加 -a(或 --audio-only)即可:
python scripts/download_video.py "URL" -a
此时脚本会以最高音质提取音频并转成 MP3(--audio-quality 0,见 download_video.py),质量和格式参数会被自动忽略,结果始终是最优的 MP3。
这个能力在 skills 仓库里还被复用:youtube-to-xiaoyuzhou 技能就调用它先下载纯音频,再走"关键字过滤 → 变声 → 发布到小宇宙播客"的完整流水线,是典型的"一个 Skill 服务多个流程"的设计。
六、自定义保存目录与参数组合
默认输出目录是 /mnt/user-data/outputs/,用 -o 可以改成任意目录,而且所有参数都能自由组合:
# 720p + WebM 格式,存到自定义目录
python scripts/download_video.py "URL" -q 720p -f webm -o /custom/path
# 最佳质量存到下载目录
python scripts/download_video.py "URL" -o ~/Videos/YouTube
# 只要音频,也支持指定输出位置
python scripts/download_video.py "URL" -a -o ~/Music
七、工作原理与依赖说明
下载流程大致是四步(核心逻辑见 download_video.py):
- 检查依赖:检测 yt-dlp 是否存在,没有就自动
pip install(自动安装逻辑) - 获取信息:先
--dump-json拉取标题、时长、上传者并打印 - 选流:按你指定的清晰度/格式挑选最佳视频流 + 音频流
- 下载合并:必要时用 ffmpeg 合并为最终容器(音频则提取为 MP3)
依赖要求很低:
- Python 3.6+:运行脚本所需
- yt-dlp:缺失时自动安装
- ffmpeg:合并音视频流所需,一般系统已预装
八、常见问题与故障排除
| 问题 | 解决办法 |
|---|---|
| 提示找不到 yt-dlp | 脚本会自动安装;失败可手动执行 pip install yt-dlp |
| 提示找不到 ffmpeg | macOS 执行 brew install ffmpeg,Linux 执行 apt install ffmpeg |
| 视频不可用 | 确认链接公开可访问,试试其他清晰度档位 |
| 下载失败 | 检查网络;执行 pip install --upgrade yt-dlp 更新工具;部分视频可能有地区限制 |
几点已知限制:默认不下载播放列表(只处理单个视频);年龄限制视频可能需要登录态;高清晰度下载耗时和空间占用都更大。
九、相关文档速查
- 中文使用文档:video-downloader/README_CN.md
- 英文使用文档:video-downloader/README.md
- 技能定义(Claude Code 调用入口):video-downloader/SKILL.md
- 下载器源码:video-downloader/scripts/download_video.py
- 仓库总览:README.md
💡 上手建议:先跑一条默认命令熟悉流程,再按需叠加
-q、-f、-a、-o四个参数,基本就能覆盖所有下载场景。