前言¶
在 DeepSeek Harness（DSH）里处理视频或音频时，常见做法是直接让大模型「看懂整段片子」——既费 token，又容易把口播、画面、配乐混在一层判断里。另一类做法是手写脚本调 Whisper 再自己抽帧，目录结构和断点续跑往往要重复造轮子。
dsh-media-caption 的定位相反：给它媒体文件，它只交出逐句转写的 字幕.json 和 关键帧 JPG（含九宫格预览），不调大模型、不生成 Markdown，也不替调用方决定哪些内容重要。下游 Agent 或脚本按 speech 字段决定读字幕、读画面，或两者并用。
这是什么¶
维护者为 CleranceWang。插件仓库：github.com/CleranceWang/dsh-media-caption，社区目录页：skillhub.cn/plugins/CleranceWang/dsh-media-caption。当前 package 版本为 0.1.0，许可证 MIT。
一句话：DSH 插件，用本机 faster-whisper 与 ffmpeg 做 ASR 与抽帧，输出结构化 JSON 与 JPG 素材；判断权在调用方。
核心功能¶
两类产物¶
字幕.json—— 逐句转写，时间戳为毫秒整数；附带是否有人声（speech）、语言及可靠性等字段。frames/*.jpg与previews/sheet.jpg—— 关键帧与九宫格拼图，单帧保持原始分辨率。
插件不做：不调大模型、不生成 md、不替你筛选「重要内容」。
三种内容形态（README 中的读法）¶
| 形态 | 例子 | 该看什么 |
|---|---|---|
| 信息在字幕里 | 口播科普、测评、教程 | 读 字幕.json，帧作辅助 |
| 信息在画面里 | 产品图类视频、TUI 演示、纯音乐 | 读 sheet.jpg，字幕可能为空 |
| 两边互补 | 讲解 + 操作演示 | 字幕与帧都读，互相纠错 |
speech 为 none 且 segments 为空时，不等于处理失败，可能是内容本身无人声。
三个 DSH 工具¶
media_caption_process（标准面）：参数 note（笔记目录名），在配置的输入根下查找：
<输入根>/<笔记目录>/video/xxx.mp4
/audio/xxx.mp3
若输出目录里已有 字幕.json，直接返回，不重算。
media_caption_file（直给面）：参数 file（绝对路径），可选 id。无需按笔记目录命名；身份判定为：显式 id → 笔记目录身份 → 内容指纹 h_<sha1前12>。
media_caption_sweep（批处理）：参数 run（默认 false）、limit（0 表示不限）。run: false 只报告待处理数量；run: true 执行扫盘、入队、逐条处理。受资源门禁约束，显存或内存不足时不启动转写。
产物目录布局¶
<输出根>/<笔记目录名>/
├── 字幕.json
├── frames.json
├── frames/f00.jpg …
├── previews/sheet.jpg（及 sheet-1..N.jpg）
└── audio/audio.mp3 # 中间产物，删了会重抽
字幕.json 示例结构（字段以仓库 README 为准）：
{
"note_id": "42952687912",
"duration_ms": 302464,
"speech": "present",
"language": "zh",
"language_reliable": true,
"segments": [
{ "start": 1200, "end": 3400, "text": "大家好" }
]
}
speech 取值：present（有人声，读字幕）、none（无人声，下游宜看图）。
抽帧数量按 README 公式 N = clamp(round(变化点数 / 8), 9, 27)，结合场景变化吸附与单次 ffmpeg 解码；抽帧失败不抛错，转写仍是主路径。
安装与启用¶
本机依赖（均需自行安装并加入 PATH）¶
| 依赖 | 说明 |
|---|---|
| Node.js ≥ 22 | 插件运行环境 |
| ffmpeg / ffprobe | 音视频处理 |
| faster-whisper-xxl | 命令行版，见 Purfview 发布页 |
| large-v3 模型 | 约 3 GB；魔搭 Systran/faster-whisper-large-v3 或 HuggingFace 同路径 |
模型为含 model.bin 等的目录，将其路径填入配置中的 modelDir，无需改名。模型来源为 openai/whisper-large-v3（MIT），由 Systran 转为 CTranslate2；本插件不打包模型。
配置¶
可读 ~/.dsh/media-caption.config.json，环境变量优先。完整字段见仓库 .env.example。
最小配置示例：
{
"whisper": "D:/path/to/faster-whisper-xxl.exe",
"modelDir": "D:/path/to/faster-whisper-large-v3",
"outRoot": "D:/media/out"
}
需要「丢进输入目录、DSH 启动时扫一轮自动处理」时，显式设置 "autoSweep": true，并配置 inputRoot、dbPath 等。自动扫盘默认关闭；打开后每次 DSH 启动扫一轮，处理完退出，不常驻、不开定时器。SQLite 队列库应放在本机盘，不宜放网络盘。
装入 DSH¶
官方安装命令（来自 README）：
dshm_install id=<github-owner>/dsh-media-caption
将 <github-owner> 换为仓库所有者（如 CleranceWang）。本地开发可软链到 profile 的 node_modules/，不要在 profile 里跑 pnpm install（@deepseek-ai/* 由宿主提供）。安装后重启 DSH。
典型用法¶
- 装好依赖与模型，写好
whisper、modelDir、outRoot（及可选的inputRoot、autoSweep）。 - 执行
dshm_install并重启 DSH。 - 按笔记目录放置媒体后，调用
media_caption_process并传入note；或对任意文件调用media_caption_file。 - 若开启批处理或需手动再跑一轮，使用
media_caption_sweep：run: false先看队列与磁盘缺口，run: true再真正处理。
批处理遵循「位置即状态、一轮一单、进度以磁盘产物为准」；处理流程分步续跑（音轨 → 字幕 → 帧），同文件第二次命中缓存可快速跳过。
适用场景与注意¶
适合：需要在 DSH 工作流里稳定拿到可机器读取的转写与时间对齐帧图，再由 Agent 或自研逻辑做摘要、检索、笔记生成；口播类以 JSON 为主，无声或偏视觉类以 preview 为主。
注意：
- 插件在本机调用 Whisper 与 ffmpeg，首次转写耗时会随时长与硬件变化；README 未提供虚构的性能数据，使用前请在本机试跑。
- DSH 插件以当前 dsh 进程权限运行，安装前应阅读 源码 与 MIT / NOTICE，确认路径与命令符合你的安全策略。
- SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系；星标与分类以目录页实时信息为准。
结尾¶
dsh-media-caption 把视频/音频理解拆成「原料层」：JSON 字幕 + JPG 关键帧，把要不要读字、要不要看图留给调用方。若要安装说明与队列细节，以 GitHub README 为准。
- 目录页：https://www.skillhub.cn/plugins/CleranceWang/dsh-media-caption
- 仓库：https://github.com/CleranceWang/dsh-media-caption
