name	session-notes-maker
description	将演讲、会议、课程或带 PPT 的视频转换成带幻灯片截图和转录文本的 HTML 文章。适用于用户要求处理视频、PPT 演讲视频、会议演讲、Presentation recording、从视频生成可分享 HTML、提取 PPT 截图并整合转录稿等场景。Skill 内置完整流水线脚本。

Session Notes Maker

目标

使用本 Skill 可以把单个演讲视频转换成会议视频学习资料生成流程中生成的同类产物：

带时间戳的幻灯片截图
带时间戳的转录稿
幻灯片与转录稿整合后的 Markdown
light-plus 模式处理后的 Markdown
适合 PC 阅读宽度的 HTML
只包含 HTML 和实际引用图片的分享目录
可选的 zip 压缩包

内置脚本

本 Skill 可单独分发。它在 scripts/ 目录内置以下可执行脚本：

01_transcribe_video.py
02_extract_slide_timestamps.py
03_integrate_transcript_slides.py
04_polish_slide_transcript.py
05_prepare_codex_batches.py
06_merge_light_polish_scenes.py
markdown_llm_utils.py
05_compress_png_images.py
00_build_session_notes.py
requirements.txt
requirements-whisper.txt

runner 会直接调用这些内置副本，不依赖宿主项目根目录下是否存在同名脚本。

安装 Python 依赖：

pip install -r ~/.cursor/skills/session-notes-maker/scripts/requirements.txt

要启用无火山 Key 的本地转录 fallback，再安装可选 Whisper 依赖：

pip install -r ~/.cursor/skills/session-notes-maker/scripts/requirements-whisper.txt

如果在 Apple Silicon 上希望加速第 2 步的 SSIM 幻灯片去重比较，可额外安装 PyTorch MPS 依赖：

pip install "torch>=2.1" "pytorch-msssim>=1.0"

安装后 02_extract_slide_timestamps.py 默认会用 --ssim_backend auto 自动尝试 MPS；也可以显式传入 --ssim_backend mps 或用 --ssim_backend cpu 回到原 CPU 路径。

还需要安装以下命令行工具：

pandoc：用于 Markdown 转 HTML
ffmpeg：供 MoviePy 处理视频/音频
pngquant 和 oxipng：用于可选的 PNG 压缩

配置

本 Skill 包含 scripts/config.example.py，作为 key 和配置文件的脱敏模板。它保留 prompt、模型和配置结构，但把敏感 key 替换成占位符。

在单独分发和本地使用时，先从模板创建本地密钥文件：

cp ~/.cursor/skills/session-notes-maker/scripts/config.example.py ~/.cursor/skills/session-notes-maker/scripts/config.py

可选填写：

VOLCENGINE_API_KEY：火山引擎新版控制台的 API Key；未填写时自动使用本地 Whisper

默认 Codex sub-agent 路径不需要 OpenRouter Key。API_KEY、BASE_URL 和 MODEL 只为兼容旧的 OpenRouter provider 保留，均为可选配置。

转录脚本默认使用 --provider auto：有效火山 Key 存在时使用录音文件极速版 HTTP 接口；没有 Key 时使用本地 OpenAI Whisper。火山路径把本地音频 Base64 编码后放入 audio.data 直接发送，无需对象存储、公网音频 URL，也无需 submit/query 轮询。旧版控制台鉴权可额外配置 APP_KEY 和 ACCESS_KEY。

本地 Whisper 默认使用 small 模型，可通过 --whisper-model 和 --whisper-device 调整。首次运行会下载所选模型。

极速版单文件限制为 2 小时、100MB，支持 WAV、MP3 和 OGG OPUS。超过限制时应先切分音频，或改用标准版 URL 提交接口。

不要分享或提交 scripts/config.py；它已经被 scripts/.gitignore 忽略。

内置脚本会从自己的 scripts/ 目录导入 config.py，因此单独分发后的 Skill 只需要在本地补齐 scripts/config.py。

工作流程

转录视频
- 如果视频旁边已有 <video>_transcript.txt，直接复用。
- 否则运行 01_transcribe_video.py。
- 脚本从视频抽取 16kHz 单声道 MP3；默认自动选择转录后端：有有效 Key 时通过 audio.data 直传火山引擎 ASR Flash，没有 Key 时运行本地 Whisper。
- 可用 --provider volcengine|whisper 强制指定后端；本地路径支持 --whisper-model 与 --whisper-device。
生成幻灯片时间戳 Markdown
- 运行 02_extract_slide_timestamps.py。
- 默认使用 hybrid-keyframe；动态布局、keyframe 召回不可用或显式传入 --detection-backend accurate 时，回退到 streaming accurate：顺序解码采样帧，在内存中做 SSIM，只写出变化帧。
- 如需回到旧行为（先保存所有采样 PNG，再二次读取做 SSIM），传入 --legacy_extract_all。
- 如果没有可靠的 PPT 截图区域，使用 --interactive 让用户框选。
- 重复运行时，优先复用已保存的 <video>.ppt_rect.json 或显式传入 --ppt-rect。
- hybrid-keyframe 先用 H.264 keyframes 快速召回候选，再只在候选附近做局部 2 秒网格 SSIM 精修。
- 当 PPT 区域固定（显式 --ppt-rect 或 sidecar 已加载）时，默认会走 hybrid-keyframe；否则回退到准确扫描。
- 默认检测宽度为 --detect-width 240，默认输出 --image-format png，优先保证 PPT 文字、线条和图表清晰度。
- 完整 39:10 样本中，accurate 路径用时 34.79s，默认 hybrid-keyframe + PNG 用时 9.34s，同样输出 28 个 slide 起点，速度约为 3.72x；如遇到 keyframe 召回不稳定的视频，可显式传入 --detection-backend accurate。
- 如果用户更看重速度或体积，可显式传入 --image-format jpg --jpeg-quality 90。
整合转录稿
- 运行 03_integrate_transcript_slides.py。
- 输入：第 2 步生成的 <video>.md 和 <video>_transcript.txt。
- 输出：<video>_integrated.md。
使用轻量打磨模式处理
- 默认先用 passthrough 保留对齐稿，再由多个 Codex sub-agent 并行生成 notes，最后用 --polish-provider codex-notes 汇总。
- 这条默认路径不依赖 OpenRouter Key；--polish-provider openrouter 仅作为可选兼容路径保留。
- 运行 04_polish_slide_transcript.py，常用参数：
  - --mode light-plus
  - --provider openrouter|codex-notes|passthrough
  - --codex-notes-dir /path/to/codex_notes
  - --no-review
  - -y
- 输出：<video>_integrated_Processed.md。
- 流水线会自动删除文件末尾的“处理过程中使用的提示（Prompts）”附录，最终 HTML 不包含提示词内容。
合并每页 PPT 内的完整发言
- light-plus 的最终阅读稿不能保留逐条 ASR 时间戳。
- 先由第 4 步逐页结合截图完成术语校正，再运行 06_merge_light_polish_scenes.py。
- 严格保持一页 PPT 对应一段讲稿；只合并这一页内部的字幕碎片，不跨 PPT 合并。
- 只在 PPT 标题保留该页整体时间范围，正文不再显示逐句时间戳。

python ~/.cursor/skills/session-notes-maker/scripts/06_merge_light_polish_scenes.py \
  /path/to/video_integrated_Processed.md \
  /path/to/video_light_polished.md \
  --paragraph-target 240

构建可分享 HTML
- 把处理后的 Markdown 复制到分享目录，并命名为 <video>.md。
- 把 ppt_pics/ 复制为 <video>_ppt_pics/。
- 将 Markdown 图片链接改写为 <video>_ppt_pics/...。
- 只保留最终 Markdown 实际引用的图片（PNG/JPG/JPEG/WebP）。
- 使用 pandoc 转换为 standalone HTML。
- 将 HTML 正文宽度调整为适合 PC 阅读的宽度（max-width: 1100px），并让图片自适应正文宽度。
- 如果本地浏览器或分享环境对相对图片路径不稳定，加入 --embed-html-images，把最终 HTML 中引用的本地图片内嵌为 data URI，打开单个 HTML 也能稳定显示。
可选打包
- 如果用户希望更小的包且必须保持 PNG 格式，用 05_compress_png_images.py 原地压缩被引用的 PNG。
- 使用 zip -0 打包分享目录，避免对 PNG 进行耗时的二次压缩。

输出结构

默认输出在：

<video_parent>/<video_stem>_html_output/
├── work/
│   ├── <video_stem>.md
│   ├── <video_stem>_integrated.md
│   ├── <video_stem>_integrated_Processed.md
│   └── ppt_pics/
├── share/
│   ├── <video_stem>.html
│   ├── <video_stem>.md
│   └── <video_stem>_ppt_pics/
└── <video_stem>_html_share.zip

质量检查

报告完成前必须检查：

HTML 文件存在；
所有 <img src="..."> 引用都能在分享目录内找到，或已被 --embed-html-images 内嵌为 data:image/...；
如果用户要求 PNG 格式，确认图片文件仍然是 PNG；
如果用户要求打包，报告最终 zip 路径和大小。

变更日志

2026-07-10: 转录新增本地 Whisper fallback；未配置火山 Key 时自动使用本地 small 模型。
2026-07-01: 默认抽帧路径切换为 hybrid-keyframe，结合 keyframe 快速召回和局部 accurate 精修。
2026-07-01: 默认截图格式保持 PNG，以保证 PPT 文字和线条质量；保留 --image-format jpg|webp 供小体积/极速场景使用。
2026-07-01: 保留 --detection-backend accurate 作为保守回退路径。

实践经验

转录稿驱动的文章固定使用 light-plus，因为它以转录稿为主，只用幻灯片辅助校对和轻度润色。
转录默认使用 --provider auto；火山 Key 缺失时应确认已安装 requirements-whisper.txt，不要把 Key 设为硬性前置条件。
light-plus 最终稿应严格保持一页 PPT 对应一段完整讲稿；逐条时间戳只属于中间校对产物，不应直接进入交付稿。
不要把所有截帧图片都放进最终分享包，只保留最终 Markdown 实际引用的图片。
如果一批视频画面布局一致，先交互式框选一次 PPT 区域，再复用保存的 sidecar 或显式 --ppt-rect。

name	session-notes-maker
description	将演讲、会议、课程或带 PPT 的视频转换成带幻灯片截图和转录文本的 HTML 文章。适用于用户要求处理视频、PPT 演讲视频、会议演讲、Presentation recording、从视频生成可分享 HTML、提取 PPT 截图并整合转录稿等场景。Skill 内置完整流水线脚本。