把旁白、真实素材和动画规则收进可审阅的 SVG 场景
现在
偶尔用
这次没有制作新画面;新写法和新套件没有取到真片运行回执
截至 11 月 4 日 · 项目源码和说明文档

回到项目 → 本地视频制作 私有 复制 AI 续作说明

video-scaffold · 功能说明

画面现在有三种做法。讲解视频默认写“图文页分镜表”:一个 JSON 文件说清每页放什么、每个元素在念到哪个词时出现,工具把它搭成画面;原来的逐场 SVG 路线照旧,工具整理提示,人或 AI 只做可审阅的小画面,公共动画模板让它动起来;独立网页作品则可以自由用 Canvas、SVG、WebGL 或网页元素创作。上面“讲解视频默认写图文页分镜表”是 10 月 11 日到 29 日的做法;现在每期先想画面怎么做最好再挑,画面也不局限于 SVG。第四种是 10 月 22 日加的 docfilm:生图的空镜做底板,真截图印上纸或贴进屏幕,打码、手划线、盖章,一份全片镜头单写清每个镜头。

图文页 10 月 21 日起多了一套纪实写法:深底白字的“纪实”主题;一张截图或照片整页铺满、很慢地推近;截图上要遮的地方先打实心黑块再上画面;黄色手绘框和红框圈重点;左上角一直挂着“第 83 天”这样的计数条;页与页、段与段之间可以硬切。截图还能透视贴进生成的手机屏幕,或者只裁出其中一条内容放大成 16:9 的画面。

docfilm 的镜头单里,每个镜头只写几行数据:用哪张底板、哪个场景套件(手机、电脑屏幕、文书台面、原声热敏纸、天数计数、对照卡和台历、地图和时间线、片头片尾,也有流转总图、路线地图、通话卡和通话台账、计分板、层级图、回应表、承诺清单)、镜头怎么动,以及每个动作(印纸、镂空、划线、纸滑进来、盖章、念到某处时强调截图上的一块)踩在全片时间线的哪几个字上。底板、截图、打码框登记一次;原件截图先按打码框盖死再印上纸。字幕默认按标点断句,个别段可以指定在哪断,段末字幕按锚点收;原声里的长段对话可以按时间线分成几屏。

画面上还能叠一层跟着旁白走的信息:念到哪句,顶部的日期、机关和阶段,底部进度,右侧事实,大字日期卡,术语解释和原声角标就换到哪句,观众知道此刻讲的是哪件事、这个词什么意思、这段是不是原声,也不会有一个日期一直挂在那里。要清水印的原件,盖完码、清完水印后整页再过一次本机识字,按本期敏感字表查有没有漏码;识字失败或查不出结果就不出片。

当前情况:本期影片《电子雪貂饲养员》用图文页路线做完,已于 10 月 11 日 12:43 通过本人审定;之后新增的组件、纪实写法和截图工具只在自动测试里跑过,还没用在审定过的成片上,这次也没有逐个重新验证。docfilm 的镜头单、套件、信息层和原件漏码检查按北京时间 10 月 31 日 14:19 最后一次提交的说明和源码核对(11 月 4 日),这次没有渲染,也没有取到真片的运行回执,不能说已实测通过。

项目源码:私有仓库

把旁白、真实素材和动画规则收进可审阅的 SVG 场景
现在
偶尔用
这次没有制作新画面;新写法和新套件没有取到真片运行回执
截至 11 月 4 日 · 项目源码和说明文档

回到项目 → 本地视频制作 私有 复制 AI 续作说明

video-scaffold · 功能说明

画面现在有三种做法。讲解视频默认写“图文页分镜表”:一个 JSON 文件说清每页放什么、每个元素在念到哪个词时出现,工具把它搭成画面;原来的逐场 SVG 路线照旧,工具整理提示,人或 AI 只做可审阅的小画面,公共动画模板让它动起来;独立网页作品则可以自由用 Canvas、SVG、WebGL 或网页元素创作。上面“讲解视频默认写图文页分镜表”是 10 月 11 日到 29 日的做法;现在每期先想画面怎么做最好再挑,画面也不局限于 SVG。第四种是 10 月 22 日加的 docfilm:生图的空镜做底板,真截图印上纸或贴进屏幕,打码、手划线、盖章,一份全片镜头单写清每个镜头。

图文页 10 月 21 日起多了一套纪实写法:深底白字的“纪实”主题;一张截图或照片整页铺满、很慢地推近;截图上要遮的地方先打实心黑块再上画面;黄色手绘框和红框圈重点;左上角一直挂着“第 83 天”这样的计数条;页与页、段与段之间可以硬切。截图还能透视贴进生成的手机屏幕,或者只裁出其中一条内容放大成 16:9 的画面。

docfilm 的镜头单里,每个镜头只写几行数据:用哪张底板、哪个场景套件(手机、电脑屏幕、文书台面、原声热敏纸、天数计数、对照卡和台历、地图和时间线、片头片尾,也有流转总图、路线地图、通话卡和通话台账、计分板、层级图、回应表、承诺清单)、镜头怎么动,以及每个动作(印纸、镂空、划线、纸滑进来、盖章、念到某处时强调截图上的一块)踩在全片时间线的哪几个字上。底板、截图、打码框登记一次;原件截图先按打码框盖死再印上纸。字幕默认按标点断句,个别段可以指定在哪断,段末字幕按锚点收;原声里的长段对话可以按时间线分成几屏。

画面上还能叠一层跟着旁白走的信息:念到哪句,顶部的日期、机关和阶段,底部进度,右侧事实,大字日期卡,术语解释和原声角标就换到哪句,观众知道此刻讲的是哪件事、这个词什么意思、这段是不是原声,也不会有一个日期一直挂在那里。要清水印的原件,盖完码、清完水印后整页再过一次本机识字,按本期敏感字表查有没有漏码;识字失败或查不出结果就不出片。

当前情况:本期影片《电子雪貂饲养员》用图文页路线做完,已于 10 月 11 日 12:43 通过本人审定;之后新增的组件、纪实写法和截图工具只在自动测试里跑过,还没用在审定过的成片上,这次也没有逐个重新验证。docfilm 的镜头单、套件、信息层和原件漏码检查按北京时间 10 月 31 日 14:19 最后一次提交的说明和源码核对(11 月 4 日),这次没有渲染,也没有取到真片的运行回执,不能说已实测通过。

项目源码:私有仓库

这项功能怎样使用

用途与实际影响

为什么需要它

让 AI 一口气生成整个播放页面,容易重复公共动画、跑错时间或引用根本不存在的素材。把画面拆成“分镜表里的一页”或“一场小画面”,既方便人审阅,也让版式、主题和播放规则只维护一份;缺项能在搭建时定位。纪实类片子大量用真截图:截图上的文字必须是原件、不能被重画,要遮的私人信息要在上画面之前就遮死,所以打码、裁切、贴屏都做成固定工具,而不是每次让 AI 临时画。长片如果按段派人各写一套镜头代码,既费额度又容易千篇一律;docfilm 改成一个导演写全片一份镜头单,框架照单渲染,检查还会提醒连着太久用同一套件、同一种运镜或同一张底板。

举个实际例子

我可以说:“第二页用我给的那张截图,框出右上角的按钮;念到‘三项变化’时依次出三张卡片,最后数字条长到 82。”系统把真实素材和说词时间写进分镜表,字会跟着念到的那个字出现,不会抢先。

纪实一点的说法:“这段用深底,第一页把聊天截图整页铺满慢慢推,把对方头像和名字遮掉,念到‘重点’时用黄框圈出那句话,左上角写第 83 天,换页直接切。”系统在分镜表里写好主题、整图、打码框、标框、计数和硬切;检查时另出“打码前 / 打码后”对照图让我逐张核。

用 docfilm 时我可以说:“第 12 镜用电脑屏幕套件,念到‘这三条’时依次强调截图上那三行,镜头慢慢推近;这一段字幕在‘然后’后面断开。”导演在镜头单里写好锚点、强调框和断句,跑检查,再出这一镜开头、动作做完、结尾几张定格给我看。

要观众跟得上时可以说:“顶部跟着念的这句换日期和阶段;念到这个术语弹一句大白话解释;原声段右下角标明是原声。”AI 写好句子对照表和信息层;排不下、日期卡伸出原件区,检查时直接报错。日期和阶段对不对仍由制作方保证,工具不会从私人材料里自己推断。

最后我会得到什么

得到一份可读、可改的分镜表(或逐场画面片段)和能预览的画面。工具检查页次、重点词、文字时序和动画规则;用了打码的,另得到并排的打码对照图(里面有原图,只供自己核对,不能当已打码的公开素材);docfilm 用了清水印的原件,还多一道整页识字查漏码,命中“必须改”或查不出结果都不出片;用了贴屏的,另得到四格对照图和角点检查图。docfilm 另得到一份全片镜头单和分镜联系表,套件会按实际排版报出每层字的位置和起止,供出片前的文字检查用。具体画面是否准确、好看、打码是否遮全,仍由人审阅。

这项功能怎样使用

用途与实际影响

为什么需要它

让 AI 一口气生成整个播放页面,容易重复公共动画、跑错时间或引用根本不存在的素材。把画面拆成“分镜表里的一页”或“一场小画面”,既方便人审阅,也让版式、主题和播放规则只维护一份;缺项能在搭建时定位。纪实类片子大量用真截图:截图上的文字必须是原件、不能被重画,要遮的私人信息要在上画面之前就遮死,所以打码、裁切、贴屏都做成固定工具,而不是每次让 AI 临时画。长片如果按段派人各写一套镜头代码,既费额度又容易千篇一律;docfilm 改成一个导演写全片一份镜头单,框架照单渲染,检查还会提醒连着太久用同一套件、同一种运镜或同一张底板。

举个实际例子

我可以说:“第二页用我给的那张截图,框出右上角的按钮;念到‘三项变化’时依次出三张卡片,最后数字条长到 82。”系统把真实素材和说词时间写进分镜表,字会跟着念到的那个字出现,不会抢先。

纪实一点的说法:“这段用深底,第一页把聊天截图整页铺满慢慢推,把对方头像和名字遮掉,念到‘重点’时用黄框圈出那句话,左上角写第 83 天,换页直接切。”系统在分镜表里写好主题、整图、打码框、标框、计数和硬切;检查时另出“打码前 / 打码后”对照图让我逐张核。

用 docfilm 时我可以说:“第 12 镜用电脑屏幕套件,念到‘这三条’时依次强调截图上那三行,镜头慢慢推近;这一段字幕在‘然后’后面断开。”导演在镜头单里写好锚点、强调框和断句,跑检查,再出这一镜开头、动作做完、结尾几张定格给我看。

要观众跟得上时可以说:“顶部跟着念的这句换日期和阶段;念到这个术语弹一句大白话解释;原声段右下角标明是原声。”AI 写好句子对照表和信息层;排不下、日期卡伸出原件区,检查时直接报错。日期和阶段对不对仍由制作方保证,工具不会从私人材料里自己推断。

最后我会得到什么

得到一份可读、可改的分镜表(或逐场画面片段)和能预览的画面。工具检查页次、重点词、文字时序和动画规则;用了打码的,另得到并排的打码对照图(里面有原图,只供自己核对,不能当已打码的公开素材);docfilm 用了清水印的原件,还多一道整页识字查漏码,命中“必须改”或查不出结果都不出片;用了贴屏的,另得到四格对照图和角点检查图。docfilm 另得到一份全片镜头单和分镜联系表,套件会按实际排版报出每层字的位置和起止,供出片前的文字检查用。具体画面是否准确、好看、打码是否遮全,仍由人审阅。

结果怎么看
正常时

每页或每场画面已经审阅,元素出现的词能对上当前旁白,字不早于念到、动画放完才退场;检查通过后进入预览。

发现问题时

词重复、识别错或素材含糊时回到旁白与原图确认,不凭猜测把画面贴上去;字比念到早、动画没放完就退场,会直接被拦下。

入口不可用或证据不足时

缺分镜表、时间位置或画面片段就停止;明确不需要素材的页面仍可制作。

结果怎么看
正常时

每页或每场画面已经审阅,元素出现的词能对上当前旁白,字不早于念到、动画放完才退场;检查通过后进入预览。

发现问题时

词重复、识别错或素材含糊时回到旁白与原图确认,不凭猜测把画面贴上去;字比念到早、动画没放完就退场,会直接被拦下。

入口不可用或证据不足时

缺分镜表、时间位置或画面片段就停止;明确不需要素材的页面仍可制作。

从哪里开始

讲解视频:配音和词轴就绪后,在影片目录的 pages 里写 JSON 分镜表,定义每页的版式和元素在哪个词出现。分镜路线:运行 run.ps1 prompts,按提示把每场 SVG 片段保存为 fragment_NN.svg。独立网页作品在 webfilm 里直接写作品。docfilm:配音和 timeline.json 就绪后写全片镜头单(格式见 docs/SHOTLIST.md),每写一批跑 python -X utf8 docfilm/shotlist.py check <镜头单.json>,再用 shotlist.py board 出分镜联系表。纪实风格在分镜表顶层写 "theme": "documentary",要硬切写 "transition": 0,计数条写 "counter";截图只用一条内容时,先运行 python -m pipeline.frame_crop 裁成 16:9 成帧;要把真截图贴进手机屏,在表顶层写 screen_composites,或单独运行 python -m pipeline.screen_composite。

需要准备什么
  • 每页要表达的内容与画面要求
  • 真实素材(图片、截图、录屏、标志)或明确无素材
  • 需要对齐的重点词
  • 用 docfilm 时:生图的底板(静态画面一律生图,不用代码画)、每张截图对应的打码框 JSON,以及每个动作要踩的那几个字
  • docfilm 要按句显示信息时:句子对照表和要显示的事件值;原件要清水印时:本期敏感字表(UTF-8 文本,每行 严重程度|类别|词,只放本机),写进镜头单的 redact_ocr.terms
  • 用到截图时:哪些地方要打码(按源图像素框出)、要圈哪里;贴屏时场景图和手机屏四个角的位置(可先让工具自动找角出检查图,人确认后再用)
从开始到拿到结果
1整理本页材料
把原文、实际读到的重点词和选定的素材放在一起;没有素材的页也明确标出。docfilm 把底板、截图和打码框在镜头单里登记一次,素材陆续到位陆续登记。要裁条或贴屏的截图先用工具做成成帧或合成图,原图保持不动。
2写分镜表或画面片段
图文页选版式和组件、写元素出现的词;纪实页可用 fullimage 整图、redact 打码、marks 标框、counter 计数;分镜路线只保存这一场可审阅的画面。都要核对事实、布局和动画,不生成另一套不受控的整页程序。
3搭建前对齐
工具检查页次、词和文字时序;缺页、重点词对不上、字抢在念到之前、打码框超出原图,都会停下。用了打码的页同时生成打码前后对照图,要逐张看过。docfilm 清水印的原件在这一步过整页识字;没配敏感字表、识别忙或没结果、命中“必须改”,都会停下。
从哪里开始

讲解视频:配音和词轴就绪后,在影片目录的 pages 里写 JSON 分镜表,定义每页的版式和元素在哪个词出现。分镜路线:运行 run.ps1 prompts,按提示把每场 SVG 片段保存为 fragment_NN.svg。独立网页作品在 webfilm 里直接写作品。docfilm:配音和 timeline.json 就绪后写全片镜头单(格式见 docs/SHOTLIST.md),每写一批跑 python -X utf8 docfilm/shotlist.py check <镜头单.json>,再用 shotlist.py board 出分镜联系表。纪实风格在分镜表顶层写 "theme": "documentary",要硬切写 "transition": 0,计数条写 "counter";截图只用一条内容时,先运行 python -m pipeline.frame_crop 裁成 16:9 成帧;要把真截图贴进手机屏,在表顶层写 screen_composites,或单独运行 python -m pipeline.screen_composite。

需要准备什么
  • 每页要表达的内容与画面要求
  • 真实素材(图片、截图、录屏、标志)或明确无素材
  • 需要对齐的重点词
  • 用 docfilm 时:生图的底板(静态画面一律生图,不用代码画)、每张截图对应的打码框 JSON,以及每个动作要踩的那几个字
  • docfilm 要按句显示信息时:句子对照表和要显示的事件值;原件要清水印时:本期敏感字表(UTF-8 文本,每行 严重程度|类别|词,只放本机),写进镜头单的 redact_ocr.terms
  • 用到截图时:哪些地方要打码(按源图像素框出)、要圈哪里;贴屏时场景图和手机屏四个角的位置(可先让工具自动找角出检查图,人确认后再用)
从开始到拿到结果
1整理本页材料
把原文、实际读到的重点词和选定的素材放在一起;没有素材的页也明确标出。docfilm 把底板、截图和打码框在镜头单里登记一次,素材陆续到位陆续登记。要裁条或贴屏的截图先用工具做成成帧或合成图,原图保持不动。
2写分镜表或画面片段
图文页选版式和组件、写元素出现的词;纪实页可用 fullimage 整图、redact 打码、marks 标框、counter 计数;分镜路线只保存这一场可审阅的画面。都要核对事实、布局和动画,不生成另一套不受控的整页程序。
3搭建前对齐
工具检查页次、词和文字时序;缺页、重点词对不上、字抢在念到之前、打码框超出原图,都会停下。用了打码的页同时生成打码前后对照图,要逐张看过。docfilm 清水印的原件在这一步过整页识字;没配敏感字表、识别忙或没结果、命中“必须改”,都会停下。
技术实现与依据(一)

这里保留实现、关键条件、精确入口、历史记录和验证结果。

图文页分镜表、逐场 SVG 合同、组件与主题、纪实主题与整图、打码、标框、计数条、硬切、截图贴屏和裁条成帧已在源码中;本期图文页影片已审定,新组件和新写法本次未逐个重验(内容核对到北京时间 2026-10-22 01:25 的最后一次提交 626774f,10 月 22 日 06:47 读);docfilm 镜头单、场景套件、信息层、原件整页 OCR、字幕断句和文字层数据按北京时间 10 月 31 日 14:19 最后一次提交 3c1c117 的说明和源码核对(11 月 4 日),这次没有渲染,也没有取到真片运行回执

关键规则与设计选择
1
图文页和分镜路线生成的 SVG 遵守同一份合同:不带整页脚本和独立时钟;独立网页作品可以用 Canvas、SVG、WebGL、网页元素,只要求按绝对时间求画面、声音离线排好。docfilm 不走 SVG:用 numpy、Pillow、scipy 在 3840×2160 内部合成、缩回 1080p,同样每帧只由全片时间决定。
2
字按实际念到的时间逐步出现,强调色不能早于底字;概括性字样要显式标 summary:true,重复前文原话时,原话必须在重现前已完整念过,不能借重现提前显示;后文词和负偏移要在当前词轴范围内说得通。
3
高级动效仍必须是时间 t 的纯函数,不能因为预览能动就引入真实时钟;分镜 prompts 只整理提示,保存 fragment 才是创作动作。
4
截图内容永远来自原件:打码先在派生 PNG 上画实心黑条,再裁切、平移、缩放和透视,原图不改;贴屏最后再覆盖一次黑块,调色和反光不会让黑块变灰。打码对照图含原图内容,只供受控审阅,不能当已脱敏的交付或公开素材。
当前怎样实现
  • 图文页用 pages/*.json 读本期原文、真实音频/词轴和选定素材,PageBuilder 生成 SVG/HTML,复用分镜路线的搭建、布局检查和逐帧出片。
  • 组件分两层:31 个顶层版式(8 个基础版式、22 种图解和卡片组),以及 17 种卡片内图解。基础版式包括页眉、说法堆叠、卡片组、时间线、带图标清单、数值条形、圆形擦除和网格卡片;图解包括流程/分派树、原话档案、层层把关、交接、闸门、结论胶囊、设备流、容量图、网页窗口、简介链接和互动按钮等。两层不能相加成“48 种动画”。
  • config.PAGE_THEMES 集中定义白底绿、纸红和纪实(documentary)三套主题,默认白底绿;字体、颜色、字号、留白和字幕样式都从这里读。纪实主题是 #17181A 深底、白字、深灰卡片、黄色强调和红笔,烧录字幕改为白字压半透明黑底条(box 透明度、box_pad 留边);只换主题不改版式和默认叠化。白底绿是本项目的默认,不是所有创作的统一风格。
  • 素材呈现:screenshot 贴完整原图;screen 可引用真截图,裁切、平移推拉,或把已有录屏按区间抽帧放进窗口播放;强调框和标注单独叠加;brands 登记已有标志图,组件用 logo 引用。fullimage 是一页唯一的视觉元素,等比铺满 16:9、多余裁掉、不加边框,按 at 出现后默认很慢推近再停住(push 可关或指定 scale、direction、start/end,极短页默认静止)。redact: [[x,y,w,h],…] 可写在 fullimage 或 screen 截图上,坐标是源图整数像素、必须完整在图内,录屏 clip 不支持。marks 的 style: "highlight"(黄色略不规则手绘框)和 style: "red"(红框)跟随截图同一变换,不发光不弹跳,可晚于绑词描出并带说明。顶层 counter 是左上角半透明圆角条里的白字,整段保留、不随换页闪,每页可改值或写 false 隐藏。只用本人或 AI 选定的实际文件,不自动截取任意应用,也不重画出来源文字。
  • pipeline/frame_crop.py:按源像素框 [x0,y0,x1,y1] 裁出一条内容,默认输出 1920×1080,裁条按画布宽 90% 居中、过高改按高度缩放,背景用裁条自身铺满、模糊并压暗;支持 --batch 任务表,输出不能覆盖来源图。pipeline/screen_composite.py:把真截图按确认的四角透视贴进场景里的手机屏幕,可从长截图取段、打码、描框、叠加小图、羽化和轻微调色(不生成或重画文字),输出成图和四格对照图(场景原图、贴后、截图打码前、打码后);auto_corners 只出角点检查图和待确认坐标,分镜表出图只接受人确认后的四角。
  • author.py 读取脚本和词轴,注入实际可用词串与素材地址,没有素材时明确写无;有 scripts/visual-direction.md 时把同一份主体、造型、配色、构图和动作目的用到各场,但不放松透明背景、定位与动画分离、绝对时间等通用合同。
  • docfilm 镜头单:顶层登记 timeline、script、plates、assets、inserts(片头片尾),每镜写 t 起点锚点、kit、plate、cam 运镜、do 动作和 in 转场。锚点写 "s3:某几个字"(第 3 段里这几个字,段号从 0 数),可加 #2 取第 2 次出现、加 +0.2 偏移。原件 doc 动作先按打码框盖实心深灰块并自检“框里除标注外的墨全盖住”,过不了报错,再整页印上纸;念到那句时荧光笔刷过,可升起放大句条。上屏的字只能来自定稿和念白,找不到就提醒。
  • docfilm 结构图与记录套件:flow.chart、flow.geo、voice.call、wall.grid、tree.org、cards.appeal、cards.promises,不写 do,参数写在 args,按各套件文件开头的说明(docs/SHOTLIST.md 的“套件与动作”;代码在 docfilm/kits)。哪部片实际用过、整片新版本验收,这次没有取到回执。
  • docfilm 信息层 hud(docfilm/hud.py,术语卡在 kits/terms.py):sentences 句子对照表按 timeline 的逐字时间对到每句,顶部案卷条和底部进度按正在念的那句取数;side 是右侧信息栏,dates 是大字日期卡,hide 是隐藏区间,terms 是术语卡,voice 是原声段角标。直接排在成片像素上,叠在画面之上、字幕之下,CPU 和显卡常驻都能叠;排字放不下先缩一档,还放不下、日期卡伸出原件区都在 check 里报错。数据真实性由制作方保证。
  • docfilm 原件整页 OCR redact_ocr:素材写 clean: "watermark" 时,编译阶段把盖完码、清完水印的整页各过一次 LocalOCR,对本期敏感字表 redact_ocr.terms;每页一次、不按帧跑,按整页像素哈希缓存。没配 terms 直接报错;OCR 忙或失败、没出结果也报错阻止出片;“必须改”命中阻断,其他只提醒;错误只记类别和位置,不写命中的字。独立编译写到本期 redact_ocr.work;release 把图片和缓存放进本次检查目录,经 DOCFILM_CHECK_WORK 传给子进程,结束后恢复调用环境。它只覆盖选定的清水印原件,不证明最终视频所有画面都做过 OCR,更不证明念白对稿。
技术实现与依据(一)

这里保留实现、关键条件、精确入口、历史记录和验证结果。

图文页分镜表、逐场 SVG 合同、组件与主题、纪实主题与整图、打码、标框、计数条、硬切、截图贴屏和裁条成帧已在源码中;本期图文页影片已审定,新组件和新写法本次未逐个重验(内容核对到北京时间 2026-10-22 01:25 的最后一次提交 626774f,10 月 22 日 06:47 读);docfilm 镜头单、场景套件、信息层、原件整页 OCR、字幕断句和文字层数据按北京时间 10 月 31 日 14:19 最后一次提交 3c1c117 的说明和源码核对(11 月 4 日),这次没有渲染,也没有取到真片运行回执

关键规则与设计选择
1
图文页和分镜路线生成的 SVG 遵守同一份合同:不带整页脚本和独立时钟;独立网页作品可以用 Canvas、SVG、WebGL、网页元素,只要求按绝对时间求画面、声音离线排好。docfilm 不走 SVG:用 numpy、Pillow、scipy 在 3840×2160 内部合成、缩回 1080p,同样每帧只由全片时间决定。
2
字按实际念到的时间逐步出现,强调色不能早于底字;概括性字样要显式标 summary:true,重复前文原话时,原话必须在重现前已完整念过,不能借重现提前显示;后文词和负偏移要在当前词轴范围内说得通。
3
高级动效仍必须是时间 t 的纯函数,不能因为预览能动就引入真实时钟;分镜 prompts 只整理提示,保存 fragment 才是创作动作。
4
截图内容永远来自原件:打码先在派生 PNG 上画实心黑条,再裁切、平移、缩放和透视,原图不改;贴屏最后再覆盖一次黑块,调色和反光不会让黑块变灰。打码对照图含原图内容,只供受控审阅,不能当已脱敏的交付或公开素材。
当前怎样实现
  • 图文页用 pages/*.json 读本期原文、真实音频/词轴和选定素材,PageBuilder 生成 SVG/HTML,复用分镜路线的搭建、布局检查和逐帧出片。
  • 组件分两层:31 个顶层版式(8 个基础版式、22 种图解和卡片组),以及 17 种卡片内图解。基础版式包括页眉、说法堆叠、卡片组、时间线、带图标清单、数值条形、圆形擦除和网格卡片;图解包括流程/分派树、原话档案、层层把关、交接、闸门、结论胶囊、设备流、容量图、网页窗口、简介链接和互动按钮等。两层不能相加成“48 种动画”。
  • config.PAGE_THEMES 集中定义白底绿、纸红和纪实(documentary)三套主题,默认白底绿;字体、颜色、字号、留白和字幕样式都从这里读。纪实主题是 #17181A 深底、白字、深灰卡片、黄色强调和红笔,烧录字幕改为白字压半透明黑底条(box 透明度、box_pad 留边);只换主题不改版式和默认叠化。白底绿是本项目的默认,不是所有创作的统一风格。
  • 素材呈现:screenshot 贴完整原图;screen 可引用真截图,裁切、平移推拉,或把已有录屏按区间抽帧放进窗口播放;强调框和标注单独叠加;brands 登记已有标志图,组件用 logo 引用。fullimage 是一页唯一的视觉元素,等比铺满 16:9、多余裁掉、不加边框,按 at 出现后默认很慢推近再停住(push 可关或指定 scale、direction、start/end,极短页默认静止)。redact: [[x,y,w,h],…] 可写在 fullimage 或 screen 截图上,坐标是源图整数像素、必须完整在图内,录屏 clip 不支持。marks 的 style: "highlight"(黄色略不规则手绘框)和 style: "red"(红框)跟随截图同一变换,不发光不弹跳,可晚于绑词描出并带说明。顶层 counter 是左上角半透明圆角条里的白字,整段保留、不随换页闪,每页可改值或写 false 隐藏。只用本人或 AI 选定的实际文件,不自动截取任意应用,也不重画出来源文字。
  • pipeline/frame_crop.py:按源像素框 [x0,y0,x1,y1] 裁出一条内容,默认输出 1920×1080,裁条按画布宽 90% 居中、过高改按高度缩放,背景用裁条自身铺满、模糊并压暗;支持 --batch 任务表,输出不能覆盖来源图。pipeline/screen_composite.py:把真截图按确认的四角透视贴进场景里的手机屏幕,可从长截图取段、打码、描框、叠加小图、羽化和轻微调色(不生成或重画文字),输出成图和四格对照图(场景原图、贴后、截图打码前、打码后);auto_corners 只出角点检查图和待确认坐标,分镜表出图只接受人确认后的四角。
  • author.py 读取脚本和词轴,注入实际可用词串与素材地址,没有素材时明确写无;有 scripts/visual-direction.md 时把同一份主体、造型、配色、构图和动作目的用到各场,但不放松透明背景、定位与动画分离、绝对时间等通用合同。
  • docfilm 镜头单:顶层登记 timeline、script、plates、assets、inserts(片头片尾),每镜写 t 起点锚点、kit、plate、cam 运镜、do 动作和 in 转场。锚点写 "s3:某几个字"(第 3 段里这几个字,段号从 0 数),可加 #2 取第 2 次出现、加 +0.2 偏移。原件 doc 动作先按打码框盖实心深灰块并自检“框里除标注外的墨全盖住”,过不了报错,再整页印上纸;念到那句时荧光笔刷过,可升起放大句条。上屏的字只能来自定稿和念白,找不到就提醒。
  • docfilm 结构图与记录套件:flow.chart、flow.geo、voice.call、wall.grid、tree.org、cards.appeal、cards.promises,不写 do,参数写在 args,按各套件文件开头的说明(docs/SHOTLIST.md 的“套件与动作”;代码在 docfilm/kits)。哪部片实际用过、整片新版本验收,这次没有取到回执。
  • docfilm 信息层 hud(docfilm/hud.py,术语卡在 kits/terms.py):sentences 句子对照表按 timeline 的逐字时间对到每句,顶部案卷条和底部进度按正在念的那句取数;side 是右侧信息栏,dates 是大字日期卡,hide 是隐藏区间,terms 是术语卡,voice 是原声段角标。直接排在成片像素上,叠在画面之上、字幕之下,CPU 和显卡常驻都能叠;排字放不下先缩一档,还放不下、日期卡伸出原件区都在 check 里报错。数据真实性由制作方保证。
  • docfilm 原件整页 OCR redact_ocr:素材写 clean: "watermark" 时,编译阶段把盖完码、清完水印的整页各过一次 LocalOCR,对本期敏感字表 redact_ocr.terms;每页一次、不按帧跑,按整页像素哈希缓存。没配 terms 直接报错;OCR 忙或失败、没出结果也报错阻止出片;“必须改”命中阻断,其他只提醒;错误只记类别和位置,不写命中的字。独立编译写到本期 redact_ocr.work;release 把图片和缓存放进本次检查目录,经 DOCFILM_CHECK_WORK 传给子进程,结束后恢复调用环境。它只覆盖选定的清水印原件,不证明最终视频所有画面都做过 OCR,更不证明念白对稿。
技术实现与依据(二)
1
配音与词轴就绪后,写分镜表或运行 prompts;需要裁条或贴屏的截图先做成帧或在表里登记合成。
2
阅读本页原文、可触发的词与真实素材地址;无素材页面可以继续。
3
人或 AI 选版式、组件、主题,或设计 SVG 片段,并按结构指南审阅;截图页写好打码框和标框。
4
保存分镜表或按规范命名 fragment_NN.svg。
5
搭建时强制页次与时间轴一致,解析触发词、检查文字时序并组合公共模板;打码框越界直接报错并生成打码对照图;已引用素材是否存在在出片身份阶段检查。
  • build_scene.py 支持正常单/双引号属性、有限中文数字变体、data-cue-index 和 data-cue-offset;未命中或非法属性明确失败。
  • scene_base.html 的 seekTime(t) 现有 39 个动画分支(原有 32 个,新增 drop、frames、iris、keys、mark、shake、wave);这是去重后的运行时分支数,不代表 39 种都在真实影片里用过。
  • 页间硬切沿用顶层 transition: 0;段间拼接表 fade_frames: 0 直接拼接视频帧,非负整数可指定叠化帧数(60fps,默认仍 12 帧)。
  • screen_composites 在 stills / render 生成页面前逐项合成,打码或原件变化进入既有素材指纹;plan 保持只读,用同分辨率场景原图代替尚未生成的成图检查布局,不代表合成已通过。打码页在本次 work/redactions/ 生成“左:打码前 / 右:打码后”对照 PNG,并在 plan.redaction_previews 列出路径。
  • docfilm 字幕:默认按标点自动断句;subtitles.splits 可在某段指定在第几个字后断开,或用 lines 直接给出断好的句子(拼回去必须和该段逐字内容完全一致,只改断句不改字)。段末字幕结束取三者最早:下一条字幕开始、下一个插入段开始减叠化、该段结束后 0.25 秒。notes 和动作里写死的绝对秒数在 check 中提醒改用锚点。
  • docfilm 文字层元数据:框架字幕、出处签、信息栏、放大条等由同一份编译结果报出实际文字、起止和墨迹框;本期自写的特写动作要用 text_layers 按实际排版声明,没声明的保持“查不了”,不拿估计框代替。片尾卡要在本期生成脚本里声明,再重新生成镜头单,不直接改生成后的 JSON。
  • pipeline.image_jobs generate 从图片清单生成标明“任务类型:生图”的派单和“计划中”回执,写明用途、提示、参考图和输出位置;accept 读取真实文件的尺寸和哈希并登记。generate 不调用模型,“计划中”不表示图已生成,登记也不能代替实际看图。
执行流程
技术实现与依据(二)
1
配音与词轴就绪后,写分镜表或运行 prompts;需要裁条或贴屏的截图先做成帧或在表里登记合成。
2
阅读本页原文、可触发的词与真实素材地址;无素材页面可以继续。
3
人或 AI 选版式、组件、主题,或设计 SVG 片段,并按结构指南审阅;截图页写好打码框和标框。
4
保存分镜表或按规范命名 fragment_NN.svg。
5
搭建时强制页次与时间轴一致,解析触发词、检查文字时序并组合公共模板;打码框越界直接报错并生成打码对照图;已引用素材是否存在在出片身份阶段检查。
  • build_scene.py 支持正常单/双引号属性、有限中文数字变体、data-cue-index 和 data-cue-offset;未命中或非法属性明确失败。
  • scene_base.html 的 seekTime(t) 现有 39 个动画分支(原有 32 个,新增 drop、frames、iris、keys、mark、shake、wave);这是去重后的运行时分支数,不代表 39 种都在真实影片里用过。
  • 页间硬切沿用顶层 transition: 0;段间拼接表 fade_frames: 0 直接拼接视频帧,非负整数可指定叠化帧数(60fps,默认仍 12 帧)。
  • screen_composites 在 stills / render 生成页面前逐项合成,打码或原件变化进入既有素材指纹;plan 保持只读,用同分辨率场景原图代替尚未生成的成图检查布局,不代表合成已通过。打码页在本次 work/redactions/ 生成“左:打码前 / 右:打码后”对照 PNG,并在 plan.redaction_previews 列出路径。
  • docfilm 字幕:默认按标点自动断句;subtitles.splits 可在某段指定在第几个字后断开,或用 lines 直接给出断好的句子(拼回去必须和该段逐字内容完全一致,只改断句不改字)。段末字幕结束取三者最早:下一条字幕开始、下一个插入段开始减叠化、该段结束后 0.25 秒。notes 和动作里写死的绝对秒数在 check 中提醒改用锚点。
  • docfilm 文字层元数据:框架字幕、出处签、信息栏、放大条等由同一份编译结果报出实际文字、起止和墨迹框;本期自写的特写动作要用 text_layers 按实际排版声明,没声明的保持“查不了”,不拿估计框代替。片尾卡要在本期生成脚本里声明,再重新生成镜头单,不直接改生成后的 JSON。
  • pipeline.image_jobs generate 从图片清单生成标明“任务类型:生图”的派单和“计划中”回执,写明用途、提示、参考图和输出位置;accept 读取真实文件的尺寸和哈希并登记。generate 不调用模型,“计划中”不表示图已生成,登记也不能代替实际看图。
执行流程
名词和入口
本模块用到的名词
名词意思
图文页分镜表一个 JSON 文件,写明每页用什么版式、放哪些元素、各在念到哪个词时出现;工具据此搭出画面。
fragment(场景片段)分镜路线里只放在公共 SVG 舞台内部的本场内容,不重复整页运行时。
data-anim(动画原语)声明元素随时间如何出现、移动或变化;实际状态由 seekTime(t) 计算。
file URI(本地文件地址)把明确素材的绝对路径编码给浏览器使用;没有素材就明确写无,不虚构。
专业定义

分镜表和提示只准备证据与结构;画面是否准确、好看必须由人或 AI 审阅。

解决什么

防止模型生成失控页面、素材引用凭空出现,以及动画表面正常却和旁白没有可追溯关系。

名词和入口
本模块用到的名词
名词意思
图文页分镜表
意思:
一个 JSON 文件,写明每页用什么版式、放哪些元素、各在念到哪个词时出现;工具据此搭出画面。
fragment(场景片段)
意思:
分镜路线里只放在公共 SVG 舞台内部的本场内容,不重复整页运行时。
data-anim(动画原语)
意思:
声明元素随时间如何出现、移动或变化;实际状态由 seekTime(t) 计算。
file URI(本地文件地址)
意思:
把明确素材的绝对路径编码给浏览器使用;没有素材就明确写无,不虚构。
专业定义

分镜表和提示只准备证据与结构;画面是否准确、好看必须由人或 AI 审阅。

解决什么

防止模型生成失控页面、素材引用凭空出现,以及动画表面正常却和旁白没有可追溯关系。

出问题时
边界
  • 组件库和主题提供画面能力,不替人判断事实、审美和信息层级;没有自动审美或事实判断。docfilm 镜头单检查的多样性提醒只是提醒,不规定画风;套件和案例不把某种画风或镜头数固化成通用要求。打码只遮写进 redact 的框,有没有漏遮要人逐张看对照图;对照图含原图,不能当已打码成品发出去。清水印原件的整页识字只查这些原件,不替代人看对照图,也不替代成片识字。
  • 自动找手机屏的角会被反光、灯光、多块白区或暗屏误导,必须看检查图;四点透视还原不了手指遮挡、镜头畸变或弯曲屏幕。
  • 静止主内容超过 3.5 秒只提示;有限动作结束后默认再停 0.25 秒才退场。词轴估计或词内插值的误差仍需听音与有声预览修正。
  • 旧定制生成器和封面只留在 Git 历史,不是当前入口;本期生成的图片和成品留在影片目录,不写进通用源码。
失败与恢复
情况
怎么处理
片段或分镜表含指南禁止的结构,或字早于念到
重复属性、未知动画、非法时间、文字抢先和动画未放完就退场由搭建阻断;其他内容与视觉问题由人或 AI 退回修改,不把合同通过说成完整美学验收。
触发词没在时间轴里找到
明确阻断搭建和核对;先核对音频与词轴,选真实词语、出现次数或偏移,再重建和听看。
已引用的素材路径不存在
提示阶段不虚构,出片身份读取素材时直接失败;没有引用素材的页面不因此失败。
打码框超出原图、贴屏四角交叉或共线、输出会覆盖输入
直接报错,不改原图;改好坐标或输出路径后重跑。
docfilm 镜头单锚点找不到、素材或底板不存在、截图没有打码框、镜头时间倒序或重叠
check、联系表和渲染载入时都直接报错停下;改镜头单后重跑。插删念白段时先用 shotlist renumber 批量移锚点段号。
docfilm 原件打码自检不过(框里还有没盖住的墨,或标注碰到码块)
编译时报错、不出画面;改打码框后重跑。
docfilm 清水印原件的整页识字没过(没配敏感字表、识别忙或失败、没出结果、命中“必须改”)
编译时报错、不出片,报错只写类别和位置;配好字表、等识别空闲或改打码框后重跑。
出问题时
边界
  • 组件库和主题提供画面能力,不替人判断事实、审美和信息层级;没有自动审美或事实判断。docfilm 镜头单检查的多样性提醒只是提醒,不规定画风;套件和案例不把某种画风或镜头数固化成通用要求。打码只遮写进 redact 的框,有没有漏遮要人逐张看对照图;对照图含原图,不能当已打码成品发出去。清水印原件的整页识字只查这些原件,不替代人看对照图,也不替代成片识字。
  • 自动找手机屏的角会被反光、灯光、多块白区或暗屏误导,必须看检查图;四点透视还原不了手指遮挡、镜头畸变或弯曲屏幕。
  • 静止主内容超过 3.5 秒只提示;有限动作结束后默认再停 0.25 秒才退场。词轴估计或词内插值的误差仍需听音与有声预览修正。
  • 旧定制生成器和封面只留在 Git 历史,不是当前入口;本期生成的图片和成品留在影片目录,不写进通用源码。
失败与恢复
情况
怎么处理
片段或分镜表含指南禁止的结构,或字早于念到
重复属性、未知动画、非法时间、文字抢先和动画未放完就退场由搭建阻断;其他内容与视觉问题由人或 AI 退回修改,不把合同通过说成完整美学验收。
触发词没在时间轴里找到
明确阻断搭建和核对;先核对音频与词轴,选真实词语、出现次数或偏移,再重建和听看。
已引用的素材路径不存在
提示阶段不虚构,出片身份读取素材时直接失败;没有引用素材的页面不因此失败。
打码框超出原图、贴屏四角交叉或共线、输出会覆盖输入
直接报错,不改原图;改好坐标或输出路径后重跑。
docfilm 镜头单锚点找不到、素材或底板不存在、截图没有打码框、镜头时间倒序或重叠
check、联系表和渲染载入时都直接报错停下;改镜头单后重跑。插删念白段时先用 shotlist renumber 批量移锚点段号。
docfilm 原件打码自检不过(框里还有没盖住的墨,或标注碰到码块)
编译时报错、不出画面;改打码框后重跑。
docfilm 清水印原件的整页识字没过(没配敏感字表、识别忙或失败、没出结果、命中“必须改”)
编译时报错、不出片,报错只写类别和位置;配好字表、等识别空闲或改打码框后重跑。
依据与来源
真实入口
  • 场景提示与真实素材 URI
  • cue 解析与模板组合
  • 确定性动画运行时
  • 完整 SVG 组件与高级动效
  • 纪实主题、整图慢推、打码、标框、计数条与硬切(config.py、pipeline/pages.py)
  • 截图透视贴屏与裁条成帧(pipeline/screen_composite.py、pipeline/frame_crop.py)
如何验证
  • 回归覆盖真实地址、稀疏/三位数编号、触发词解析与缺失标记;纪实画面、贴屏和裁条另有 test_pages_documentary.py、test_screen_composite.py、test_frame_crop.py、test_pages_tools.py;626774f 源码共有 267 个测试定义(全项目),这次没有运行。
  • 2026-09-03 历史 doctor 曾加载 Chromium 并确认 seekTime,之后未重新运行。
  • 本期图文页影片已于 10 月 11 日 12:43 通过本人审定,这是影片的制作记录;10 月 21 日之后的纪实写法和截图工具还没有用在审定过的成片上。这次网页核对没有打开或重做任何画面,不给每个新组件标“已逐项验收”。
与其他模块的关系

本模块产出可出片的分镜表或场景;预览模块负责低成本检查,出片模块把同一时间函数变成视频帧。

依据与来源
真实入口
  • 场景提示与真实素材 URI
  • cue 解析与模板组合
  • 确定性动画运行时
  • 完整 SVG 组件与高级动效
  • 纪实主题、整图慢推、打码、标框、计数条与硬切(config.py、pipeline/pages.py)
  • 截图透视贴屏与裁条成帧(pipeline/screen_composite.py、pipeline/frame_crop.py)
如何验证
  • 回归覆盖真实地址、稀疏/三位数编号、触发词解析与缺失标记;纪实画面、贴屏和裁条另有 test_pages_documentary.py、test_screen_composite.py、test_frame_crop.py、test_pages_tools.py;626774f 源码共有 267 个测试定义(全项目),这次没有运行。
  • 2026-09-03 历史 doctor 曾加载 Chromium 并确认 seekTime,之后未重新运行。
  • 本期图文页影片已于 10 月 11 日 12:43 通过本人审定,这是影片的制作记录;10 月 21 日之后的纪实写法和截图工具还没有用在审定过的成片上。这次网页核对没有打开或重做任何画面,不给每个新组件标“已逐项验收”。
与其他模块的关系

本模块产出可出片的分镜表或场景;预览模块负责低成本检查,出片模块把同一时间函数变成视频帧。

复制 AI 续作说明

项目:把旁白、真实素材和动画规则收进可审阅的 SVG 场景;仓库:页面未提供仓库地址;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。

把“目标”换成这次要做的事,整段复制给 AI。