前言¶
在 DeepSeek Harness（DSH）场景中，经常需要处理大量本地视频素材：压缩体积、统一格式、按间隔抽帧、提取音频、加水印或烧录字幕。常见做法要么依赖在线工具（隐私与体积都不划算），要么手动敲 ffmpeg 命令（参数冗长且容易出错），批量时还要自己写循环脚本。
这个插件把常用动作封装成统一命令，支持输入只读、输出独立目录、同名自动加序号，结果可用 ffprobe 核对。基于本机 ffmpeg，不上传原片，不改变源文件。
是什么¶
feely0208/dsh-media-batch 是 DSH 的一个联网工具类插件，用于在本地批量处理视频，包括压缩、转码、抽帧、抽音轨、加水印、烧录字幕。所有操作由 ffmpeg 完成，插件只做参数组织和流程编排。项目维护者为 feely0208。
核心能力¶
| 子命令 | 功能 | 核对产物 |
|---|---|---|
compress |
H.264 CRF 压缩，可调 --crf / --preset |
MP4，ffprobe 可读出 h264、分辨率与时长不变 |
transcode |
换格式（mp4/mov/webm/mkv）、改分辨率、改帧率 | 目标格式文件，ffprobe 编码/分辨率与参数一致 |
frames |
按固定间隔抽帧为 PNG | <名称>_frames/ 下编号 PNG，数量 = 时长 ÷ 间隔 |
audio |
抽音轨为 m4a / mp3 | 纯音频文件，ffprobe 可读出 aac / mp3 |
watermark |
文字水印（中文可用，五档位置） | 视频，同一时间点画面与源片不同 |
subtitle |
烧录 .srt 字幕（需 ffmpeg 带 libass） |
视频，字幕已压进画面 |
支持单文件、多文件或单层目录批量；输出默认 <输入目录>/_输出，--out 可指定。--json 输出供脚本/CI 使用，--probe 探测本机 ffmpeg 能力，--demo 自造 1 秒样例跑完整流程。
文字水印支持两条真实路径：有 drawtext 用 drawtext；没有（缺 libfreetype）自动回退为「Pillow 渲染透明文字 PNG → ffmpeg overlay 合成」，结果里会标明 renderer。
安装与启用¶
dsh plugin --profile web add @deepwhale-cn/dsh-media-batch
依赖 ffmpeg / ffprobe（视频处理全部由它们完成）。缺失时会明确报「缺什么、怎么装」：
brew install ffmpeg
dsh-media-batch --probe # 确认 libx264 / aac / drawtext / libass 等能力
字幕烧录需要 ffmpeg 编译时带 libass；本工具会先探测，没有就明确拒绝。文字水印在缺少 drawtext 时自动回退为 PNG + overlay（额外需要 python3 + Pillow）。
典型用法¶
# 看效果（自造 1 秒样例，不碰你的文件）
dsh-media-batch --demo
# 压缩整个目录
dsh-media-batch compress --crf 28 --input videos/
# 转码 + 改分辨率
dsh-media-batch transcode --format mp4 --width 1280 --input a.mov
# 每 0.5 秒抽一帧
dsh-media-batch frames --every 0.5 --input clip.mp4
# 抽音轨
dsh-media-batch audio mp3 --input clip.mp4
# 文字水印
dsh-media-batch watermark --text "内部资料" --position br --input clip.mp4
# 烧字幕（本机无 libass 会明确报错）
dsh-media-batch subtitle --subtitle a.srt --input clip.mp4
# 给程序：JSON 输出
dsh-media-batch compress --input videos/ --json
退出码：0 成功 / 2 参数或输入错误 / 3 依赖或能力缺失 / 4 执行失败。
自测¶
bash tests/run.sh
测试会自己用 ffmpeg lavfi 造 1 秒样例（含音轨/无音轨各一），逐项核对压缩后体积、编码器、转码分辨率、抽帧数量、抽音轨可被 ffprobe 读出、水印画面与源片不同，并按本机能力走字幕烧录/明确拒绝两条分支；同时验证「输入哈希不变」「不存在文件必须非 0」等反例。
适用场景与注意¶
适合需要批量处理本地视频、希望避免上传隐私素材或手动敲 ffmpeg 命令的场景。插件以当前 DSH 进程权限运行，安装前建议查看源码与许可证。
注意：不下载/不转码受 DRM 保护的流；不处理损坏文件（会报错并保留原片）；不做语音识别（subtitle 只烧录已有 .srt）；本机 ffmpeg 无 libass 时不能烧字幕；不保证压缩后一定更小（极短/低码率视频可能变大）；不做 HDR/杜比处理；批量只扫单层目录；同名输出自动加序号，不覆盖。文字水印字体来自系统字体，若系统字体被裁剪且 ffmpeg 无 drawtext，回退路径会明确报缺字体/Pillow。
小结¶
这个插件把常用的视频批量动作封装成统一命令，基于本机 ffmpeg，不上传原片。适合需要批量压缩、转码、抽帧、抽音轨、加水印或烧录字幕的场景，安装后直接用命令行完成常见操作。更多信息请查看项目主页与源码。
