sph-downloadlisted
Install: claude install-skill ythx-101/sph-download
# 视频号下载
`scripts/sph` 把一条视频号分享链接保存到本地:视频、封面和一份元数据。
原理:视频号的公开预览页可以匿名看到文案、作者和封面;元宝网页端能解析视频号分享链接,带上用户自己的元宝登录态请求一次,就能得到可直接播放的视频地址。
下面的路径都相对于本技能所在目录(记作 `<skill_dir>`)。
## 前提
- Python 3.10+、`ffmpeg`(含 `ffprobe`)。
- 用户自己的元宝登录态,默认存在 `~/.config/sph-download/yuanbao.cookie`。没有的话先走「登录」一节。
- 只保存用户有权保存的内容。视频版权归原作者。
## 单条
```bash
<skill_dir>/scripts/sph "<链接>" --out <输出目录> --save-frames
```
产物在 `<输出目录>/<短码>/`:`video.mp4`、`cover.jpg`、`meta.json`、`frames/frame_01~03.jpg`。一条大约 5~10 秒。
按退出码处理:
| 退出码 | 含义 | 怎么办 |
| --- | --- | --- |
| 0 | 成功 | 往下交付 |
| 1 | 链接无效、网络错误、文件超过大小上限或校验失败 | 把报错原样告诉用户 |
| 2 | 没有配置登录态(只存了元数据和封面) | 走「登录」一节后重跑 |
| 3 | 登录态失效 | 走「登录」一节后重跑,不要反复重试 |
| 4 | 这条链接拿不到视频(已删除、纯图文等) | 如实告诉用户 |
**交付前必须亲眼看一帧**:打开 `frames/frame_02.jpg`,确认画面正常,内容和 `meta.json` 里的 `description` 对得上。花屏、黑屏或对不上就不要交付。然后把 `video.mp4` 交给用户,附上作者、文案第一句、时长和分辨率。
只要文案和封面、不要视频时加 `--meta-only`,这种情况不需要登录态。
## 批量
把链接写进一个文本文件,每行一个(`#` 开头和空行会跳过,重复的只跑一次):
```bash
<skill_dir>/scripts/sph_batch.sh <清单.txt> --out <输出目录> -- --save-frames
```
- 严格串行,每条之间随机等 5~10 秒,任意 60 秒内最多开始 6 条。不要并发,不要自己写循环替代它。
- 已经有 `video.mp4` 的短码会跳过,所以中断后重跑同一条命令就能续上。
- 遇到退出码 3 会立刻停下。重新登录后重跑。
- 每条的结果记在 `<输出目录>/batch.tsv`。脚本退出码:0 全部成功,1 有失败的,3 登录态失效,5 磁盘空间不足。
- `--` 后面的参数原样传给 `sph`。
## 登录
登录态是用户自己的元宝账号,取得它需要用户参与。两种方式,任选其一。
**方式一:用户手动复制(最稳)。** 请用户在自己的浏览器里登录元宝网页端,打开开发者工具的 Network 面板,随便点开一个发往元宝的请求,复制请求头里完整的 `Cookie`,然后自己保存到文件:
```bash
mkdir -p ~/.config/sph-download && umask 077 && cat > ~/.config/sph-download/yuanbao.cookie
# 粘贴后按 Ctrl-D
```