edit | blame | history | raw

会议录屏 PPT 页面提取 MVP 编码方案 V003

创建人员：dev.developer.project
文件职责：仅闭环真实验收 HOLD/1 的“主课件连续序列前后误收非 PPT 稳定画面”，冻结最小颜色主题序列过滤、离线回放和最多一次完整视频复验。
管理规范/模板：../../../编码规范.md；../../../开发审计规范.md；../../../../common/dev-doc/编码规范.md。
引用文件：CODE-DESIGN-PROJECT-INFO-MEETING-RECORDING-SLIDE-EXTRACTION-MVP-V002.md；../../../开发审计报告.md；../../../../ai-media-processor/draft/会议录屏PPT页面提取方案_v0.1.md。
记录方式：V003 增量方案；只允许修复 msg_20260801214538194_7196a0fa 的唯一问题，V002 及既有实现复审已通过合同继续冻结。

1. 上游结论与冻结范围

  • 事项：DEV-PROJECT-INFO-MEETING-RECORDING-SLIDE-EXTRACTION-MVP-20260801-001。
  • 请求方反馈：msg_20260801214538194_7196a0fa=HOLD/1。完整联系表已确认 slide_002..slide_038 是合格课件主体；slide_001、slide_039..slide_053 是前后非 PPT 稳定画面，不能进入最终 PNG/PDF。
  • 需求澄清：HANDOFF-MEDIA-INFODEV-MEETING-SLIDE-PURE-PERSON-FILTER-CLARIFICATION-20260801-001；正式需求第十二节已明确，整幅主要为人物/普通直播镜头且没有 PPT 主体内容时必须排除，PPT 主体上原有的小型人像窗口必须允许保留。
  • 已接受且不再重审：V002 稳定段、动画合并、全局去重、FFmpeg 时间/回收、目录原子提交、PDF 逐页写出；实现复审 PASS/0；目标测试 22/22、project 回归 41/41；完整运行耗时/资源、PNG/PDF 一致性和源文件保护。
  • 本轮只允许修改 dev/project-dev/extract_ppt_slides.py、对应测试和用法/开发账本；不新增模块、package、CLI 参数或产品产物。
  • 继续禁止：PPTX、OCR、人像识别/裁剪/遮挡、PPT 区域裁剪、语义模型、JSON、GUI、API、批处理、转写联动、数据库、Skill、GPU 依赖。

2. 单一修复：确定性主序列过滤

2.1 紧凑颜色主题特征

扫描帧已有 RGB 缩小图。_gray_feature 在转换灰度前同时生成一个只读紧凑颜色直方图，不保存 RGB 帧：

  1. 每个 RGB 通道右移 5 bit，得到每通道 0..7。
  2. 颜色箱编号固定为 r * 64 + g * 8 + b，共 512 箱。
  3. 用各箱像素数除以当前缩小帧像素数，保存为 float32[512] 归一化直方图。
  4. 直方图随最终稳定候选进入 PageCandidate；动画更新最终稳定态时同步替换 LogicalPage.current_palette。

该特征每页仅 2048 bytes；仍只保存最终逻辑页的紧凑特征，不保存完整采样帧，不改变长视频内存有界合同。

2.2 主序列规则

select_main_sequence(pages) 在稳定/动画/去重完成后、原分辨率 PNG 提取前执行一次。输入输出均为现有 LogicalPage 顺序列表，不修改对象或时间戳。

固定常量：

  • SEQUENCE_THEME_COVERAGE = 0.12：某页某颜色箱占比达到 12% 时，该页是该主题的标记页。
  • SEQUENCE_THEME_MAX_GAP = 1：相邻主题标记之间最多允许夹 1 个非标记页，用于保留白底图表、表格等同一课件内的孤立主题偏离页。
  • SEQUENCE_THEME_MIN_MARKERS = 8。
  • SEQUENCE_THEME_MIN_SHARE = 0.50：标记数至少占全部候选一半。
  • SEQUENCE_THEME_MIN_DENSITY = 0.80：标记数 / 首末标记闭区间页数至少 80%。

确定性步骤：

  1. 对 512 个颜色箱分别取得所有标记页索引。
  2. 当相邻标记索引差 <= SEQUENCE_THEME_MAX_GAP + 1 时归入同一组；每组的保留区间是首末标记的闭区间，允许的单页间隙随区间保留。
  3. 仅保留同时满足最少标记数、全局标记占比和区间密度的组。
  4. 用 (标记数, 区间长度, 区间内该箱占比总和, 更早起点, 更小颜色箱编号) 做固定优先级选择；前三项降序，后两项升序，保证同输入唯一结果。
  5. 若没有合格组，或胜出区间已经覆盖全部候选，则原样返回全部候选，禁止猜测性裁掉页面。
  6. 若有合格真子区间，仅返回 pages[start:end+1]；下游现有 enumerate(..., 1) 自然重新连续命名 slide_001...，PDF 仍按该列表顺序生成。

该规则识别的是“候选序列中占明显多数、内部高密度共享背景主题的最长主体段”，不判断文字、人像或 PPT 语义，不分析画面区域，不增加用户可调阈值。纯人物页因位于主课件主体段之外而被排除；PPT 页面右上角等位置的小型人像窗口不被单独分析，保留页面仍输出完整原画面。

2.3 失败与安全语义

  • 核心扫描生成的逻辑页必须带合法 float32[512] 直方图；形状、非有限值或归一化错误属于内部合同错误，明确 SlideExtractionError，不静默跳过。
  • 单元桩为兼容既有构造器可使用显式直方图 helper；产品主链不得用空直方图 fallback。
  • 过滤后不得为空；若无合格主题段则保留原候选，已有“无稳定页面”错误语义不变。
  • 原视频只读、既有输出拒绝覆盖、暂存清理、一次目录 rename 和中断回收均不变。

3. 已有 53 页离线证据

只读使用已保留候选：

dev/project-dev/tmp/DEV-PROJECT-INFO-MEETING-RECORDING-SLIDE-EXTRACTION-MVP-20260801-001/real-full.slides/pages/

按本方案从 53 张 PNG 缩小到 320x180 后计算相同直方图，未读取源视频、未运行 FFmpeg：

  • 唯一主组颜色箱=1，量化中心约 (16,16,48)。
  • 标记页=2,4,5,6,7,8,10..38，共 35 页。
  • 允许单页间隙后区间=2..38，区间长度=37，密度=35/37=0.946，全局占比=35/53=0.660。
  • 该区间保留白底 slide_003 和表格 slide_009 两个孤立偏离页，并准确排除 slide_001 与 slide_039..053。
  • 次高组仅 8 个标记；尾部黑色软件/人像相关组最多 6 个标记且密度 0.750，不满足门禁。

这组证据只用于冻结最小规则和常量，不冒充修改后产品主链或完整视频验收。

4. 实现与测试门禁

4.1 代码改动

仅在原脚本内：

  1. 增加 5 个命名常量和 512 箱直方图 helper。
  2. 在 FrameFeature、PageCandidate、LogicalPage 传递最终候选直方图。
  3. 增加纯函数 select_main_sequence。
  4. extract_slides 在 scan_video 后调用一次过滤；CLI 仅额外显示“稳定候选数 / 主课件页数”，公开参数和文件结构不变。

4.2 单元与回归

必须增加：

  1. 颜色量化：深蓝和黑色进入不同颜色箱；直方图 512 项、有限、和为 1。
  2. 53 页结构桩：标记 2,4..8,10..38，结果对象身份严格为原 2..38，两个单页间隙保留。
  3. 无合格组：少于 8 个标记、占比不足 50%、密度不足 80% 分别保持全列表。
  4. 全部候选属于一个主题时保持全部；不改变原对象、时间戳或次序。
  5. 非法直方图明确失败；不得静默保留或裁剪。
  6. 主流程桩证明过滤在原图提取前且只调用一次；正式输出重新从 slide_001 连续编号。

回归门禁：py_compile、CLI help、目标测试、dev/project-dev/test 全部测试、治理校验；既有合成 A 完整/B、短片 5 页和所有中断/原子提交测试不得回退。

4.3 既有候选离线回放

实现自测时先只读 53 张既有 PNG：

  1. 用产品相同直方图 helper 和 select_main_sequence 断言选中原索引 2..38。
  2. 在任务临时根生成新的离线联系表；可将选中的现有 PNG 复制并重新编号到独立离线目录，再调用现有 PDF writer，验证 37 PNG / 37 PDF 页逐页 RGB 和顺序一致。
  3. 不读取源视频、不调用 FFprobe/FFmpeg、不修改旧 real-full.slides。

5. 审核与最多一次完整复验

  1. V003 先由 dev.reviewer.project 做限定方案审核；PASS 前不得改代码。
  2. 实现、单元测试和 53 页离线回放完成后，提交限定实现审核；只检查本 V003 过滤、测试和既有合同无回退。
  3. 限定实现审核 PASS 后，完整源视频最多再运行一次，使用新的独立输出 real-full-v2.slides 和证据目录；不得覆盖或删除旧 53 页输出。
  4. ana-data/news-小郑/20260729192357-2026小郑掘金产业链之算力行业付费直播-视频-1-共享屏幕.slides.pdf 是当前 53 页旧证据，只读保留；本开发轮不得覆盖、替换、移动、重命名或删除，归档替换只能在请求方最终验收后另行决定。
  5. 最终预期：exit=0；PNG=37、重新编号 slide_001..slide_037；PDF=37 页且逐页 RGB/顺序一致；新联系表只含原 slide_002..slide_038 的课件主体；无暂存残留；资源仍有界；源大小、创建时间、修改时间和 SHA-256 前后相等。
  6. 若唯一一次完整复验失败，停止媒体重跑，只回传一个具体失败与证据，不继续调参或扩大架构。

6. 当前状态

PENDING_V003_LIMITED_DESIGN_REVIEW