dsh-plugin-wwrs-ffmpeg

English

本地媒体处理 DSH 插件（开源）：经本地 ffmpeg/ffprobe 做探测、转码、拼接、切片、配音混流与烧字幕。唯一运行时依赖是 @deepseek-ai/dsh-tools（defineTool DSL）。W1 完成：挂载层（src/cordis.ts）、写保护守卫与全部七个工具均已上线，经真实 ffmpeg/ffprobe 执行。

工具

所有路径只收工作区相对路径（绝对路径或越界即大声失败）。全部写工具带 overwrite?: boolean（缺省 false：false 且产物存在 → 成功返回 {skipped:true} 不执行，绝不静默覆盖）。

工具	参数	语义
media_probe	path	经 ffprobe 取时长毫秒 + 宽高；静图无时长 → durationMs: null，不报错
media_transcode	src、out、videoCodec?、audioCodec?、crf?、preset?、extraArgs?、overwrite?	重编码（缺省 libx264+aac faststart）；extraArgs: string[] 原样拼入 argv（风险自负：可覆盖任意编码开关）
media_concat	clips[]（≥1）、out、options?{reencode?=true, fps?, audioBitrate?}、overwrite?	缺省 filter-complex 归一重编拼接（reencode: false = demuxer 直拷）；单片段即转码归一
media_slice	src、out、startMs、endMs（须 endMs>startMs>=0）、overwrite?	切 [startMs,endMs)，重编码
media_mux_voice	video、voiceAudio、out、attenuationDb?、overwrite?	配音按视频时长补齐/截断；缺省替换原音轨，给定分贝值则衰减后混入
media_burn_subtitles	video、srt（须 .srt）、output、options?{forceStyle?, encoding?}、overwrite?	烧字幕（视频重编，音频直拷）
media_extract_audio	src、out、overwrite?	首个音频流提为 aac 128k（无视频）；源无音频流即大声失败

超时：探测 60s，转码系 30min；调用方取消（exec.signal）直达子进程。

合同

无远端调用——执行面是本地 ffmpeg/ffprobe 子进程；二进制经配置节注入面解析（ffmpegBin/ffprobeBin 配置键或环境变量，再包内 .bin，再 PATH）。二进制缺失即大声失败并给出路；绝不静默降级。

配置

键	含义	缺省
workspace	项目根（绝对路径）	WWRS_WORKSPACE 环境变量，再中性锚探测
ffmpegBin	ffmpeg 可执行文件（注入面：配置键或环境变量）	WWRS_FFMPEG_BIN 环境变量，再包内 .bin，再 PATH
ffprobeBin	ffprobe 可执行文件（注入面：配置键或环境变量）	同上三级

工作区解析：config.workspace > 环境变量 WWRS_WORKSPACE > 向上探测 .wwrs/workspace.json > 大声失败。缺失即大声失败并给出路；绝不静默降级。

安装

{
  "dependencies": {
    "dsh-plugin-wwrs-ffmpeg": "link:/path/to/plugin-wwrs-ffmpeg"
  },
  "dsh": { "profile": { "bundles": ["dsh-plugin-wwrs-ffmpeg"] } }
}

验证

跑 pnpm check（prettier 检查 + tsc --noEmit + node --test tests/*.test.ts）。

无浏览器半

纯服务端工具——pnpm check 即全部门，无 check:browser 链。

已知边界

• 只收工作区相对路径——绝对路径或越界即大声失败。
• overwrite: false 且产物存在 → 成功返回 {skipped:true} 不执行，绝不静默覆盖。
• extraArgs 原样拼入 argv，可覆盖任意编码开关（风险自负）。
• 超时：探测 60s，转码系 30min；调用方取消（exec.signal）直达子进程。

许可

MIT.