@deepwhale-cn/dsh-media-batch

视频批量处理：批量压缩、转码、按间隔抽帧、抽音轨、加文字水印、烧录字幕 —— 基于本机 ffmpeg，不上传、不改原片。

关键词：视频批量压缩 · 视频转码 · 视频抽帧 · 提取音频 · 视频加水印 · 字幕烧录 · ffmpeg 批处理 · media-batch

不装会怎样

一堆录屏、素材、课程视频要压小、要统一成 MP4、要每隔几秒截一张图、要提音频、要打水印或压字幕 —— 在线工具要上传原片（隐私和体积都不划算），ffmpeg 命令又长又容易记错参数，批量还要自己写循环。 这个插件把常用动作包成统一命令：输入只读、输出独立目录、同名自动加序号、结果可 ffprobe 核对。

能做什么

子命令	做什么	可核对的产物
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。

不能做什么

• ❌ 不下载/不转码受 DRM 保护的流；不处理损坏文件（会报错并保留原片）。
• ❌ 不做语音识别：subtitle 只烧录已有 .srt，不生成字幕。
• ❌ 本机 ffmpeg 没编 libass 时不能烧字幕：会明确报「本机 ffmpeg 无字幕烧录能力」并退出，不假装成功。
• ❌ 不保证压缩后一定更小：极短/低码率视频可能变大，结果里会如实给出 smaller: false。
• ❌ 不做多音轨/多字幕流选择（默认取第一路视频 + 可选第一路音频），不做 HDR/杜比处理。
• ⚠️ 批量只扫单层目录；同名输出自动加 -1/-2，不覆盖。
• ⚠️ 文字水印的字体来自系统字体；若系统字体被裁剪、且 ffmpeg 无 drawtext，回退路径会明确报缺字体/Pillow。

安装

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」等反例。

License

MIT © 温州深鲸智能科技有限公司