影视画面分析器 Raven-Jackdaw/dsh-film-analysis

dsh-film-analysis · 影视画面分析器（DSH 插件）

面向 DeepSeek Harness Web UI 的影视/视听语言分析插件：导入图片或视频，客观测量画面指标，按影视语言框架完成 8 维分析，在画面上标注，生成结构化提示词，并导出分析报告与分镜/镜头表。工具链（ffmpeg、ffprobe、中文 OCR）随 DSH 插件一起安装，无需另装 Python 或 ffmpeg。

语言 / Language：面板界面为中英双语（跟随 DSH 语言设置）；AI 分析输出、内置术语库与生成的提示词为简体中文。UI is bilingual (zh/en); AI analysis output, the built-in term library and generated prompts are in Simplified Chinese.

demo

功能

- 画面测量：尺寸/画幅比、平均亮度、对比度(RMS)、色温倾向(R-B)、饱和度、边缘密度、16 桶直方图、主色板
- 8 维分析表单：景别 / 景深与焦距 / 角度和机位 / 光线和影调 / 色彩色调 / 构图 / 镜头运动 / 声音线索（内置从学习笔记整理的知识点总结，可替换为自己的词库）
- 画面标注：三分/黄金分割辅助线、景别框、轴线、视线/运动箭头、中文文字标签，导出 PNG
- 提示词生成：把「图片路径 + 测量数据 + 8 维表单 + 分析框架」拼成提示词，一键填入会话输入框（或发送）
- 报告导出：Markdown 分析报告 + 分镜/镜头表 CSV
- 视频工具：ffprobe 元信息、按时间点/区间抽帧、多帧接触表（接触表可直接交给视觉模型看全场）
- 更准的中文 OCR（可选增强）：检测到本机 Python 时自动使用 RapidOCR（PP-OCRv4，中文识别率显著高于 tesseract）；没有 Python 时回退内置 tesseract.js
- 本地 Whisper 转写（可选增强）：面板可一键把视频音轨转成带时间码台词（需要本机 Python + faster-whisper；长音频较慢），转写结果直接作为分析输入
- 中文 OCR：离线识别画面字幕/文字（tesseract.js + chi_sim），首次初始化需十余秒
- 大视频：上传上限 8GB（流式写入，不占内存）；更大的视频可直接填绝对路径导入，走本地读取、完全不上传
- 自动拉片 + 面板内一键 AI 分析：自动检测镜头切换（长镜头自动多帧、自动裁黑边），点任一镜头直接在面板里生成「拉片讲解式」详细分析（片段级运动/亮度/声音 + 多帧看图），可复制/重新分析；长镜头自动按 60 秒分段，可逐段分析
- 整片拉片报告：一次模型调用输出全片分镜表 + 逐镜头讲解 + 节奏结构 + 风格主题（面板内显示，带 token 用量与费用估算）
- 按拉片公式输出：内置「叙事顺序 / 叙事段落 / 叙事音乐」+「剪辑时长 / 剪辑规律 / 剪辑组合」六向拉片框架（参考公开教程《适合所有人的拉片公式》），并结合八维视听语言与逐帧时间线；自动统计镜头时长分布、重复节拍组合与每镜头音量/静音数据
- 更准的分析输入（可选）：可导入 .srt/.vtt 字幕或纯文本台词，并填写影片背景/剧情/人物关系；这些作为“可信输入”进入模型，明显减少“声音/人物关系”类推测
- 更高清的分析画面：详细模式使用 1280 宽代表帧；长镜头额外生成 2×3 时间序列接触表，一张图看完整过程
- 结果可视化：AI 镜头分析与整片报告以 Markdown 渲染（标题/粗体/列表/表格/代码块），长文可滚动阅读
- 知识点速查：面板内按章节查看术语、定义、两书分析框架与题库（内置从学习笔记整理的知识点总结；教材原文与完整笔记不随包分发）
- 可调参数：自动拉片的检测灵敏度（0.10–0.60）与分析详细度（快速 / 详细），兼顾成本与速度
- 13 个 Agent 工具：面板里的操作同时暴露为 film_* 工具，会话里的 AI 也能直接调用

安装

方式 D：npm 包（最省事，DSH 用户推荐）

本插件已发布到 npm：dsh-film-analysis（https://www.npmjs.com/package/dsh-film-analysis）

⚠️ 注意：npm 版本可能滞后于本仓库。当前 npm 最新为 0.1.0；需要 v0.3.0 新功能（Whisper 转写 / RapidOCR / 字幕导入等）请用下面的 Release 离线包，或等 npm 更新。

在 DSH 的 cordis 预设会话中对 AI 说：

请用 plugin_manager 安装插件，install_bundle 的 target 是 dsh-film-analysis

首次安装会提示批准 tesseract.js 的构建脚本（内容仅为开源项目捐赠提示，不安装任何东西，可放心允许）；工具链（ffmpeg/ffprobe/中文 OCR）会随 npm 依赖自动下载。

方式 A：下载 Release 里的离线包（推荐，Windows x64）

1. 到 Releases 下载 dsh-film-analysis-win-x64-v0.3.0.zip，解压到固定目录（装好后不要移动）： C:\Users\<你>\dsh-plugins\dsh-film-analysis

2. 确认 pnpm --version 可用（没有就 npm i -g pnpm）。
3. 在 DSH Web 新建会话，预设选 cordis / 创造模式，对 AI 说：请用 plugin_manager 安装插件，install_bundle 的 target 是 C:\Users\<你>\dsh-plugins\dsh-film-analysis
4. 出现 application: applied 后刷新页面：会话顶部出现「影视画面分析」标签，输入框下方出现窄条即为成功。

方式 B：从 GitHub 直接安装（适合开发者）

在 DSH 的 cordis 预设会话中：

请用 plugin_manager 安装插件，install_bundle 的 target 是 github:Raven-Jackdaw/dsh-film-analysis

需要本机有 git 且能访问 GitHub；首次安装会从 npm 下载工具链（约 200MB，可能需要批准依赖构建脚本）。

方式 C：从源码构建

git clone https://github.com/Raven-Jackdaw/dsh-film-analysis.git
cd dsh-film-analysis
npm install --ignore-scripts # 安装工具链依赖，约 200MB
然后在 DSH cordis 会话中让 AI 安装当前目录绝对路径

可选：开启 Python 增强（RapidOCR / Whisper 转写）

插件检测到本机 Python 时会自动启用增强；不装也完全可用（OCR 回退 tesseract、无转写按钮）。

1. 安装 Python 3.10+，然后安装依赖：
pip install faster-whisper rapidocr_onnxruntime huggingface_hub

2. 下载一个 faster-whisper 模型到本地目录： huggingface-cli download Systran/faster-whisper-small --local-dir C:\models\faster-whisper-small

3. 在插件配置里填写（不填则自动在 PATH 里找 python）：
- pythonPath：python.exe 绝对路径
- whisperModelPath：上面下载的模型目录
4. 重载插件：面板出现「本地 Whisper 转写」按钮；OCR 自动优先 RapidOCR。

网络受限时可用 HF 镜像（HF_ENDPOINT=https://hf-mirror.com）；只想要中文 OCR 更准的话，单独配 pythonPath 也能启用 RapidOCR。

兼容性

- DSH Web >=0.2.1-rc.2 <0.3.0
- Windows x64 已验证；macOS / Linux 理论可用（ffmpeg/ffprobe 依赖包会自动选择对应平台二进制，未实测）
- 复用 DSH 自带的 sharp（图像处理），不额外打包 libvips

目录结构

index.js # Host 入口：注册工具与面板 HTTP 路由 client.js # Client 入口：conversation.view 全页 + composer.dock 窄条 cordis.patch.yml # bundle patch（插入一行插件） lib/ # 工具链解析、测量、色板、图像/视频/OCR、路由、知识数据 locale/ # 插件显示元数据（zh/en） docs/ # README 图片与知识数据说明

知识数据说明

lib/knowledge.js 内置的是作者从学习笔记整理的知识点总结：148 个术语（定义/页码出处/考点）、两书分析框架、40+30+5 题库与 178 条片例索引。教材原文、扫描件与完整学习笔记不随包分发。
如需使用自己的教材笔记词库，按 docs/knowledge-data.md 的字段结构替换该文件即可（面板会自动读取）。

License

- 本插件代码：MIT（见 LICENSE）
- 运行时依赖：ffmpeg/ffprobe 为 GPLv3 独立程序（由 npm 包按平台安装），tesseract.js 为 Apache-2.0，chi_sim 训练数据为 MIT/Apache-2.0。本仓库不直接分发任何二进制文件。
- 本仓库不包含任何影片/剧照素材；README 演示图为程序生成的合成画面。

Optional Python enhancements: if a local Python 3.10+ is available, the plugin uses RapidOCR (PP-OCRv4) for better Chinese OCR and can transcribe video audio with faster-whisper. Install pip install faster-whisper rapidocr_onnxruntime huggingface_hub, then set pythonPath / whisperModelPath in the plugin config. Everything still works without Python (tesseract fallback).
一个 DeepSeek Harness Web UI 插件，用于影视与视听语言分析：测量画面指标、填写 8 维分析表、标注画面、为对话智能体生成结构化提示词，并导出 Markdown 报告和镜头表 CSV。它还能在面板内检测镜头，一键生成镜头分析和全片逐镜头报告（片段级运动、亮度、音频，加上多帧画面，并显示 token 与费用）。ffmpeg、ffprobe 和中文 OCR 都作为 npm 依赖安装。在 Cordis 预设会话里通过 plugin_manager 安装插件包，然后刷新 Web UI。要求 DSH >=0.2.1-rc.2 <0.3.0；已在 Windows x64 上测试。插件包内含一份知识摘要，提炼自作者的学习笔记（术语、两本书的框架、题库、影片索引）；原版教材文字和完整笔记不随包分发。插件也已发布到 npm，包名 dsh-film-analysis（用 plugin_manager 指定 target dsh-film-analysis 安装；首次安装会请求你批准 tesseract.js 的一个无害 postinstall 脚本）。代码采用 MIT 协议；运行时依赖各自保留自己的协议。面板 UI 支持中英双语；AI 生成的分析、内置术语库和生成的提示词均为简体中文。