SAOS-3624/dsh-video-storyboard

选用指南

AI 根据 README 整理 · 2026/10/31 18:57:04

使用方式

作为 DeepSeek Harness 插件使用，提供五个工具，可通过命令行或 API 调用。

查看 README 依据

> 每条都跟一句"缺什么、怎么补"。用户反馈里过半不是 bug，是没配 ASR 或装完 ffmpeg 没重启 DSH。 > 新手步骤：[docs/入门-五分钟.zh.md](docs/入门-五分钟.zh.md) · 报错对照：[docs/FAQ.zh.md](docs/FAQ.zh.md) > > **没配转写 = 它只能看图说话。** 能描述"画面上有个女孩在跑"，但说不出她讲了什么。 > 本机 ASR 免费、不联网，装一次十几分钟 —— 这是这个插件价值差别最大的一步， > 别等到问"她说了什么"发现答不上来才回头配。见 [FAQ Q1](docs/FAQ.zh.md)。 多模态模型看视频有两种笨办法： - **逐帧抽图** —— 10 分钟片子按 1 fps 抽就是 600 张图，token 直接爆。 - **只喂字幕** —— 画面里的信息（构图、动作、场景变化）全丢。 本插件走第三条：**把画面压成一张宫格图**（384 token 封顶），旁边配一份**按时间对齐的文本清单**（每格起止时间 + 这一格里的台词 + 切了几刀）。 模型得到的是"这 90 秒里发生了什么、大概在第几秒"，需要细节时再用 `video_zoom` 放大某一段。 ## 五个工具 | 工具 | 干什么 | 何时用 | |---|---|---|

| `video_probe` | 只读容器头：多长、分辨率、帧率、有没有音轨/字幕、已分析过没有 | **第一次接触一部片子时先调它**，不花图片 token | | `video_storyboard` | 出宫格图 + 文本清单 | 主体功能 | | `video_zoom` | 只看某一段（更小的时间窗、更密的格） | 清单看完觉得某段重要，再放大 | | `video_locate` | **纯文本**：一句话 → 时间码 | 知道说了什么、不知道在第几分钟 | | `video_subtitles` | 把画面里的**硬字幕**裁成一张竖长图 + 每条的秒数 | **没有字幕轨、ASR 也转不出来**（PV / 唱歌 / 双语艺术字）—— 只能看的时候 | > `video_storyboard` 的 `quality`（`low`/`medium`/`high`）只影响**贴链接**时的下载清晰度， > 本地文件永远读原片。默认 `medium`（720p）；嫌糊传 `high`，嫌慢传 `low`。 > 价位和清晰度的取舍见 [FAQ「关于钱和清晰度」](docs/FAQ.zh.md)。 ## 安装 **从零开始的完整步骤（含依赖、自检、排错）见 [docs/INSTALL.zh.md](docs/INSTALL.zh.md)。** 三句话版本：

部署要求

需要安装 ffmpeg 和 ffprobe；yt-dlp 可选（仅用于链接下载）；ASR 服务可选（用于转写）。

查看 README 依据

```bash winget install Gyan.FFmpeg # 必须：ffmpeg + ffprobe pip install --user -U yt-dlp # 只有贴 B 站/YouTube 链接才需要 node scripts/install-dev.mjs # 装插件，然后重启 DSH ``` | 依赖 | 必须吗 | 不装会怎样 | |---|---|---| | ffmpeg + ffprobe | **必须** | 第一步就报错 | | yt-dlp | 可选 | 本地文件照常能用，贴链接不行 | | ASR 服务 | 可选 | 能出图，但清单里没有台词 | 插件**不打包** ffmpeg 和 yt-dlp，只调用你自己装的那份。找不到时会给出安装指引，不会静默失败。 ## 怎么用 ### 贴一个链接 ``` https://example.com/some-video ``` **任何 yt-dlp 支持的站点**都行（YouTube、Vimeo、各种自建站……完整列表见 yt-dlp 文档）。 插件会自己下载、缓存，然后用本地文件的那套流程跑。竖屏、DASH、多分P 都处理了。 > ⚠️ **能不能下，取决于你**：请自行确认对目标内容有下载/使用授权，并遵守该站点的条款与

已知限制

不打包 ffmpeg、yt-dlp 或 OCR 引擎，需自行安装；不提供付费内容访问或 DRM 绕过；画面小于约1%的改动可能不可见。

查看 README 依据

```bash winget install Gyan.FFmpeg # 必须：ffmpeg + ffprobe pip install --user -U yt-dlp # 只有贴 B 站/YouTube 链接才需要 node scripts/install-dev.mjs # 装插件，然后重启 DSH ``` | 依赖 | 必须吗 | 不装会怎样 | |---|---|---| | ffmpeg + ffprobe | **必须** | 第一步就报错 | | yt-dlp | 可选 | 本地文件照常能用，贴链接不行 | | ASR 服务 | 可选 | 能出图，但清单里没有台词 | 插件**不打包** ffmpeg 和 yt-dlp，只调用你自己装的那份。找不到时会给出安装指引，不会静默失败。 ## 怎么用 ### 贴一个链接 ``` https://example.com/some-video ``` **任何 yt-dlp 支持的站点**都行（YouTube、Vimeo、各种自建站……完整列表见 yt-dlp 文档）。 插件会自己下载、缓存，然后用本地文件的那套流程跑。竖屏、DASH、多分P 都处理了。 > ⚠️ **能不能下，取决于你**：请自行确认对目标内容有下载/使用授权，并遵守该站点的条款与

> 当地法律。本项目不提供任何绕过付费、会员、DRM 或区域限制的能力，也不代为判断授权。 ### 本地文件 ```bash node bin/storyboard.mjs film.mp4 --cells 9 --out film.png node bin/storyboard.mjs film.mp4 --batch 300 --out film.png # 长片按 5 分钟切窗 node bin/asr-check.mjs film.mp4 --from 100 --seconds 12 # 只测 ASR ``` ## 参数 | 参数 | 默认 | 说明 | |---|---|---| | `input` | — | 本地路径或 http(s) 链接 | | `from` / `to` | 全片 | 只看这一段 | | `cells` | 自动 | 格数；不给就按 motion / 字每秒 / 响度 推 | | `sheets` | 1 | 切成几张图（长片用） | | `scanGap` | 0.35 | 粗扫时两刀最短间隔（秒）。快闪素材调小 | | `pick` | `sharp` | 取帧策略：`sharp` 3 候选选最锐 / `mid` 段中点 / `thumb` 段内最典型 |

- 画面小于约 1% 的改动（PPT 上多一行字）在 64×36 上不可见，再聪明的阈值也救不回来。 - 连续运镜密集时，`cuts=N` 会失真（清单会标注）。 - 极暗素材的取帧锐度判断不稳。 - 分格摊开后子帧最小约 100×56，再小就只剩色块。 ## 证据与复核 每次 `saveStoryboards` 会同时写一份 `<名字>.evidence.json`：每格的起止时间、取帧时刻、刀数、字数、原文。 清单是给模型读的散文，这份是给人和脚本复核的 —— 想知道"第 5 格真的是 3:29 吗"，对着时间码回看原片即可。 ## 文档 | 文档 | 内容 | |---|---| | [docs/INSTALL.zh.md](docs/INSTALL.zh.md) | 从零安装：依赖、自检、排错表 | | [docs/USAGE.zh.md](docs/USAGE.zh.md) | 完整手册：三条安装路径、六个工作流、每个参数 | | [docs/HISTORY.zh.md](docs/HISTORY.zh.md) | 从 v0.1 到现在，按"被什么打脸"组织 | | [CHANGELOG.md](CHANGELOG.md) | 逐版本变更 | | [CREDITS.md](CREDITS.md) | 第三方致谢、社区贡献、测试素材作者 |