音视频处理工具包 Alnyzzz/dsh-video-skill

dsh-video-skill

一个可下载的 DeepSeek Harness（DSH）技能，让智能体真正能处理视频和音频文件：探测它们、查看画面、剪辑和转换，最后交回用户能播放的文件。

DSH 根本不知道 .mp4 里装了什么，所以智能体以前只会回答「我无法处理视频」。装上这个技能后，它可以：

- 读取时长、分辨率、fps、编解码器、音频布局、旋转、章节；
- 抽帧并生成带标注的缩略图拼版——然后用 read_image 看它；
- 剪辑片段（帧精确或无损流复制）、按体积预算压缩、转换容器、缩放、生成调色板优化的 GIF、检测镜头边界；
- 提取、归一化并测量音频（EBU R128 响度、静音/语音区间）；
- 写出 Markdown + HTML 检查报告，内嵌缩略图拼版。

一切都由一个脚本驱动，底层是 ffmpeg/ffprobe；机器上没有 ffmpeg 时，技能会自己装一套私有的、经过校验的 ffmpeg。

安装

1. 获取文件

git clone https://github.com/Alnyzzz/dsh-video-skill.git
cd dsh-video-skill

（或者点绿色的 Code 按钮下载 ZIP 再解压。）

2. 把技能装进 DSH

Windows
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 # add -Bootstrap to fetch ffmpeg now

macOS / Linux
bash scripts/install.sh # add --bootstrap to fetch ffmpeg now

安装脚本会把 skills/video-toolkit 复制到 <DSH_HOME>/skills/video-toolkit，校验文件包，再跑一次工具链检查。DSH 的文件系统技能服务商会监听这个目录，所以不需要重启——下一步技能就会出现在会话目录里。

手动安装（效果相同）：

Windows
Copy-Item -Recurse .\skills\video-toolkit "$env:DSH_HOME\skills\video-toolkit"

macOS / Linux
mkdir -p "${DSH_HOME:-$HOME/.dsh}/skills"
cp -R skills/video-toolkit "${DSH_HOME:-$HOME/.dsh}/skills/video-toolkit"

其他可用的技能根目录，按 DSH 的优先级顺序：<project>/.dsh/skills、<project>/.agents/skills、dsh-skill-filesystem 插件的 customSkillDirs 里列出的任意目录、<DSH_HOME>/skills、~/.agents/skills。

3. 给智能体配好 ffmpeg（通常自动完成）

让智能体检查工具链，或者你自己跑：

python "<skill>/scripts/video_ops.py" doctor

如果缺 ffmpeg，技能可以装一套私有的——它绝不碰系统目录：

python "<skill>/scripts/video_ops.py" bootstrap --download
or from a build the machine already has:
python "<skill>/scripts/video_ops.py" bootstrap --source "C:\path\to\ffmpeg\bin"
bootstrap --download 会为当前操作系统构建镜像列表（gyan.dev release-essentials、它的 GitHub 镜像、BtbN win64-gpl，以及公共镜像），最多并行下载三个镜像，保留第一个完整归档，验证解压出的二进制能运行，把 ffmpeg 与 ffprobe 配对，再复制到 <DSH_HOME>/video/tools。传输中断或卡住会自动重试/续传。Windows 上如果装了 7-Zip，优先用约 30 MB 的 .7z，否则用 .zip。

ffmpeg 已经装在别处、路径不常见？直接让技能指向它，不用下载：

DSH_FFMPEG_DIR=/opt/ffmpeg/bin # a folder holding ffmpeg + ffprobe
DSH_FFMPEG_FFMPEG=/usr/local/bin/ffmpeg # an explicit binary
python "<skill>/scripts/video_ops.py" doctor --rescan

用法

在聊天里直接说就行：

"Summarize this video: D:\clips\demo.mp4"
"Cut 00:01:10–00:01:28 into a new mp4 and compress it under 20 MB."
"What is in this webm? Make me a GIF of the intro."
"Transcribe the audio of this meeting recording." (needs a local whisper.cpp)
"/video-toolkit report this file"

也可以直接调用命令行：

S="<skill>/scripts/video_ops.py"
python "$S" doctor
python "$S" probe video.mp4
python "$S" sheet video.mp4 --count 12 --cols 4
python "$S" frames video.mp4 --at 00:01:10 --width 1600
python "$S" clip video.mp4 --start 00:01:10 --duration 18 --out highlight.mp4
python "$S" compress video.mp4 --target-mb 20 --max-width 1280
python "$S" gif video.mp4 --start 12 --duration 4 --width 720
python "$S" audio video.mp4 --codec pcm_s16le --rate 16000 --mono --out voice.wav
python "$S" silence video.mp4 --noise-db -35 --min-duration 0.6
python "$S" report video.mp4

每条命令都会打印一个 JSON 对象；--print-command 只显示 ffmpeg 命令行，不实际执行。完整的参数与字段说明见 skills/video-toolkit/references/commands.md。

| 命令 | 用途 |
| doctor | 用的是哪个 ffmpeg/ffprobe、编码器、滤镜、Python 模块 |
| bootstrap | 安装一套私有且经过验证的 ffmpeg + ffprobe |
| probe | 时长、流、编解码器、fps、旋转、章节 |
| frames | 按时间点 / 数量 / 间隔抽帧，或抽取每一帧 |
| sheet | 生成一张带时间戳标注的缩略图拼图 |
| scenes | 镜头边界，可选每个场景抽一帧 |
| clip | 剪出一段（直接复制或重新编码） |
| compress | 按 CRF 或目标体积压缩 |
| convert | mp4 / mkv / webm / mov |
| scale | 缩放，支持拉伸 / 补边 / 裁剪 |
| gif | 两遍调色板 GIF |
| audio | 提取或转码音轨 |
| normalize | EBU R128 响度标准化 |
| silence | 静音片段与语音区间 |
| loudness | 整体 LUFS / LRA / 真峰值，或 volumedetect |
| report | 生成 Markdown + HTML 报告，内嵌缩略图拼图 |
| transcribe | 通过本地 whisper.cpp 构建做语音转文字 |

环境要求

- DSH，需带 filesystem 技能服务商（任意较新的桌面版）。
- Python 3.9+ —— DSH 自带一份，位于 <DSH_HOME>/dsh-runtimes/dsh-primary-runtime/dependencies/python/python.exe；DSH 的 Python 还内置 Pillow，缩略图上的时间戳标签就是靠它绘制的。
- ffmpeg + ffprobe —— 由 bootstrap 自动安装，或从 PATH / WinGet / Scoop / Chocolatey / Homebrew / apt / 自带 ffmpeg 的应用中获取。
- 不需要任何 Python 包：脚本只用标准库。Pillow 可选（缩略图标签）；没有它，缩略图会退回 ffmpeg 的 tile 滤镜。

在真实机器上的表现

- 先找现成的。 doctor 会探测环境变量覆盖、私有工具目录、PATH、包管理器安装位置，还会扫描用户 app-data 目录和副盘——只扫一次并缓存结果——因为媒体播放器和编辑器常常自带完整 ffmpeg。
- 没验证过的二进制绝不运行。 -version 检查不通过的候选一律丢弃，只有来自私有工具目录、环境变量覆盖、PATH、已知包位置或缓存扫描列表的候选才会被执行。
- 适配不同构建版本。 -crf 属于 libx264/libx265；NVENC 要用 -cq，QSV 用 -global_quality，AMF 用 -qp_i/-qp_p，Media Foundation 用 -quality，mpeg4 用 -q:v。技能会用单帧试编码验证选定的编码器，失败就沿链条回退，并报告 encoder 和 encoder_note，绝不虚报结果。音频同理（缺 libmp3lame → 改用 AAC，并调整扩展名）。
- 如实说明做了什么。 --copy（无损重封装）还是重新编码，engine: Pillow 还是 ffmpeg tile filter，用内置 MP4 读取器而非 ffprobe 时给出 probe_note，确实没有场景或静音可报告时退出码为 4，没有语音转文字后端时退出码为 5。

仓库结构

dsh-video-skill/
├── skills/video-toolkit/ # 技能包（DSH 加载的就是它） │ ├── SKILL.md # 英文操作手册（frontmatter：name + description） │ ├── SKILL.zh-CN.md # 中文操作手册 │ ├── references/ │ │ ├── commands.md # 每条命令、参数和 JSON 字段 │ │ ├── workflows.md # 12 个任务配方 │ │ └── troubleshooting.md # bootstrap、编解码器、沙箱、CJK 路径、大文件 │ └── scripts/ │ ├── video_ops.py # 命令行（所有命令） │ └── video_common.py # 工具发现、bootstrap、辅助函数 ├── scripts/ │ ├── install.ps1 # Windows 安装脚本（复制到 <DSH_HOME>/skills） │ └── install.sh # macOS / Linux 安装脚本 ├── docs/ │ └── SKILL-FORMAT.md # DSH 技能包的结构说明 └── .github/workflows/ci.yml # 每次 push 时做语法 + 包校验

卸载

Remove-Item -Recurse "$env:DSH_HOME\skills\video-toolkit"powershell
Remove-Item -Recurse "$env:DSH_HOME\video" # optional: the private ffmpeg pair

隐私与安全说明

- 这里不会向任何服务器回传数据。唯一的网络活动是你明确执行的 bootstrap --download（或者 --to 指定的目标需要某个当前构建缺少的编解码器，但这种情况不会下载任何东西）。
- 视频和音频文件都在本地处理；这个技能不会让任何一帧画面、一个音频采样或一份转写文本离开你的机器。
- 除非用 --out/--outdir 另行指定，输出文件写在输入文件旁边；在 DSH 的 workspace-write 策略下，工作区是安全的落盘位置。

许可证

MIT —— 见 LICENSE。随包附带或下载的 ffmpeg 构建保留各自的许可证（gyan.dev essentials 是 GPL v3；BtbN win64-gpl 是 GPL v3）。本技能不再分发 ffmpeg。

作者：Alnyzzz