前言¶
在 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
