用途与结果
最快了解这个项目
为什么需要它
视频制作最浪费时间的不是写一个文件，而是几分钟甚至更久的渲染完成后才发现文字越界、关键词踩点错了，或中断续作把旧场景和新场景拼在一起。这套脚手架把昂贵步骤拆开：能在浏览器里早看就先看，能用词级证据对齐就不靠目测猜秒数，需要重跑时只复用身份仍匹配的产物；任何关键层不成立，就停在对应阶段而不是交出一条看似完成的视频。
举个实际例子
我可以说：“按这份已经确认的脚本做一条视频。每段旁白一场，念到‘核心结论’时再让重点数字出现；先把所有场景放进预览页给我看，确认后再渲染 4K60，并生成成片、封面和章节，不要自动上传。”脚手架负责把这些阶段串起来，选题、文案事实和最终审美仍由我确认。
最后我会得到什么
先拿到可以听、拖动和按词跳转的场景预览；确认后得到4K60成片、封面、章节，以及选择生成的字幕和可核对交付清单。旁白、时间位置、画面和渲染失败分别说明，最后仍要完整听看一遍。技术层保留所有中间文件、编码和复用条件。
正常时
当前阶段的输入身份、编号与产物一致，构建和检查通过；完整视频还需依次通过人工预览、渲染、合成、verify 与真实观看。
发现问题时
脚本、音频、时间轴、素材或渲染配置发生变化时停止复用陈旧产物；cue 未命中、文字越界、分片少帧或音视频缺失会在对应阶段明确失败。
入口不可用或证据不足时
依赖、模型缓存、Fish 配置、显卡编码或素材不可用时保留已有可验证中间结果和具体原因；显存临时占用报告 BUSY，不自动结束别的 GPU 工作，也不切换到未知服务。
从哪里开始
用 run.ps1 init 建新工程，按已确认旁白、素材和场景推进到预览；实际观看满意后再 render、verify。
需要准备什么
- 视频主题、已审阅的旁白和真实素材
- 想要的画面与交付物
- 新工程的空目录
从开始到拿到结果
- 1开一份新工程
init 建立空白项目，doctor 先说明本机缺什么；标题、旁白、素材和场景由人提供或审阅。
- 2先配音，再做画面
按场编号生成声音与词轴，依真实素材写 SVG 片段，保持每一场编号一致。
- 3先听看再长渲染
build、lint 和有声 preview 把缺场、错位和越界提前找出；画面确认后才 render。
- 4成片要实看
合成音视频、封面和章节，verify 与清单核对文件，人再看完整成片；投稿另行决定。
从这些需求了解功能
从一个实际问题看它怎样处理、交回什么；当前能做到哪一步和仍有哪些限制，也写在对应说明中。
项目指标与相关入口查看规模、覆盖范围和关联能力
当前项目指标
- 画布
- 3840×2160 · 60fps
- 制作方式
- 逐阶段审阅
- 时间轴
- Fish / 共享对齐
- 环境体检
- 10 通过 · 1 未测
它负责
- 从通用模板建立干净的新视频工程，不混入上一个作品的脚本或素材。
- 按已确认的分场旁白生成声音与逐词时间位置，必要时在本机重新对齐。
- 把本场旁白、可用素材和重点词交给人或 AI 审阅，再保存具体画面片段。
- 在长时间渲染前找出缺场、错位和越界；确认预览后按固定时间生成画面。
- 合成旁白、可选背景音乐、封面、章节和字幕，再交出可核对的成片清单。
- 中断后只复用能证明仍属当前输入的文件；清理只碰已知可再生内容。
它不负责
- 不替人决定选题、未经确认的事实、素材和审美；不是输入一句话就自动完成的成片服务。
- 不上传视频、不替人投稿，也没有长期运行的云端编辑或渲染服务。
- 占位素材、环境检查、单元测试和一帧画面都不能当作本期成片。
- 外部配音服务、文字踩点、背景接缝和显卡编码仍受实际环境影响，不承诺任意机器都通过。
产品思想与设计核心
内容先由人确认
事实、旁白和画面取舍由人审阅；工具只把确定的内容按场组织，不暗中替人另选模型创作。
先听看预览，再耗时渲染
缺场、错词、越界和节奏问题尽量在构建和有声预览里发现，避免渲染完才返工。
画面跟着时间轴走
每一帧都按视频时间计算；电脑跑得快慢不会自行改变动画节奏。
旧成果要对得上今天的输入
脚本、声音、素材或场景变了，就重新核对受影响的文件；只有身份和结果都匹配才续用。
检查通过仍要看完整成片
环境检查、结构检查、实际配音、渲染和人工观看各回答不同问题，不能互相代替。
失败留下可继续的位置
有效分片保留；缺素材、错时间或不完整输出会停在那一步，不拼一条看似完成的视频。
制作与投稿分开
这套工具交付成片、封面和章节；上传平台及投稿回执另行处理。
哪些内容由本人提供，哪些会离开电脑
视频并非从空白提示词自动生成。脚本、素材和画面按阶段进入工程；标准配音会把旁白文本送给 Fish Audio，其他核心制作主要在本机。
本人确认每场说什么，以及希望怎样读。
得到对应语音；外部配音服务会接收这份旁白文本。
工具读取真实长度和逐词位置，必要时在本机对齐。
动画能在念到重点词时出现；听起来不准还要在预览里修。
人或 AI 按旁白与素材制作每场画面。
构建出可审阅的场景；同一路径素材换了内容会让旧渲染失效。
按确认的时间与画面渲染，必要时在旁白出现时降低背景音乐。
形成视频与音轨；缺旁白时不交出静音的最终成片。
标题用于封面，章节按视频开头的顺序核对。
得到封面与章节文件，仍要和本期内容人工比对。
“主要在本机制作”不等于完全离线：正常配音会发送旁白；真实外部探针只在明确需要时运行。
项目怎样演化到现在
先把一条视频完整做出来
逐场画面、声音合成、封面和章节都有了能检查的制作路线；长渲染前先预览，帧数不完整就不交付。
阶段依据
- 2026-06-27—2026-06-28 · 先把一条视频完整做出来
501d23e—cf7e9dc
从一次定制变成可复用工程
抽出通用模板和环境检查，明确“电脑准备好了”与“这一期视频做完了”是两种结论。
阶段依据
- 2026-08-15 · 从一次定制变成可复用工程
3f4ef22
新项目先确认结构再制作
新工程会带上通用入口和检查；场景编号即使不连续或到了三位数，也不会把旁白和画面排错。
阶段依据
- 2026-08-30 · 新项目先确认结构再制作
1ae60fd—f227e27
补齐听看预览与交付
按真实旁白时间做画面，能听着预览、修重点词、只重渲改动片段，再生成字幕和交付清单。旧定制入口不再作为当前路线。
阶段依据
- 2026-09-03—2026-09-18 · 补齐听看预览与交付
17040ed—84501b0
完整项目状态与证据边界
已确认事实
- 把已经确定的文案、素材和场景设计，分阶段做成旁白踩点、可预览、可续作渲染的 4K60 视频、封面和章节；它不是自动选题或一键投稿服务。
- 每场一份 script_NN.txt，加上明确素材和审阅后的 SVG（可缩放矢量图）片段；交回有声 preview.html、final_output.mp4、cover.png、chapters.txt，可选全片字幕，以及验证后生成的 delivery.json。
- PUBLIC（公开）仓库 wlyaaaaa/video-scaffold；本机维护目录 E:\Projects\Archives\video-scaffold；本轮正式回读 main=origin/main=84501b04b918c8a9ec1e175b397764bf1af59bf5，工作树干净。
- 2026-09-18 13:02 UTC 的 doctor 静态检查为 10 PASS、1 UNKNOWN（未验证）：Python 3.11.9、Playwright 1.60.0、requests 2.34.2、FFmpeg/ffprobe、背景和模板文件、GPU 协调登记及 ChineseASR 适配入口可见；Fish route（处理路线） 未探测。
- 普通 doctor/status/plan 不启动浏览器或 GPU，不下载模型、不读取密钥文件，也不联系 Fish。doctor-local 才做明确本地探针，doctor-live 才消耗外部账户额度；静态入口存在不证明真实语音、编码或成片成功。
- 视频核心只维护 Playwright、requests 等自身依赖及锁文件，不再安装 faster-whisper、CTranslate2 或 CUDA 语音模型库。ChineseASR 的模型、解释器和权重由它自己的运行时维护；moderngl/numpy 仅在重建背景时按 requirements-background.txt 安装。
- Fish Audio 仍经 https://api.fish.audio/v1/tts 使用 s2.1-pro-free 和云飞声线，旁白文本会离开本机。新词轴优先采用同一音频的 Fish 原生时间戳；缺失时按已确认文案调用 ChineseASR 的 Qwen3-ForcedAligner-0.6B 本地对齐，每场最长 300 秒。有效旧词轴可继续使用，不为改时间轴重新配音。
- 场景 HTML 由静态 SVG、data-anim 和 data-cue 组成；Playwright 逐帧调用 seekTime(t) 截取透明 PNG，再由 FFmpeg 叠到背景并用 av1_nvenc、p6、CQ 22、10-bit yuv420p10le 编码。
- 来源与输出哈希贯穿旁白、词轴、时长、场景、分片及最终交付；01、04、100 等稀疏编号在全链保留。局部场景变化只重渲受影响分片，已成功分片留至显式清理；同名、同大小或同帧数都不能代替来源一致。
- 2026-09-03 的源仓库与新初始化工程各 33/33 是保留的历史回归，不是本轮重新运行。当前源码新增 Windows/Linux 逻辑测试和 Linux CPU 隔离短片持续集成入口，覆盖有声预览、片段导出、交付与增量复用；本轮只回读源码和静态 doctor，不把测试入口存在写成最新测试通过。
- background/background_4k.mp4 为 8,861,084 B、60 秒、3600 帧、10-bit AV1、3840×2160、60fps，SHA-256=6649aba6db11a94a6f516a2a276c33776301e71b8007dab3d850e646fb2b2a73。
- 源仓库保留通用背景、模板、组件、文档与明确标注的占位素材，不拿它们冒充真实作品。旧 build_v2.py 与定制封面已退出活动树，历史仍在 Git；当前唯一生产入口是 run.ps1 / pipeline.workflow，不删除旧工程原件。
当前缺口
- 本轮没有调用 doctor-live；Fish 账户、声线、服务可用性与原生时间戳的真实响应仍未重新验证，静态路由存在不能替代实际 MP3。
- 本轮没有制作或打开一条真实内容视频；生产 AV1 NVENC、共享对齐、完整音画与最终观看分别保留未测状态，历史 33 项回归不能替代它们。
- 重复词可用 data-cue-index 选择出现次数，并用 data-cue-offset 微调；模型时间和词内插值仍不是逐音素真值，必须听音审阅，不能承诺每个触发点天然无误差。
- 背景文件可循环供长视频使用，但着色器中的全部噪声是否在 60 秒接缝严格连续没有本轮视觉验收，不使用“绝对无缝”作为已证结论。
- 交付可以包括字幕与哈希清单，但不生成完整投稿文案或执行上传；源码已有持续集成配置，仍未声明 LICENSE，公开可读不等于已授予开源许可。
来源与公开边界
video-scaffold 是公开的视频生产脚手架，源码负责本地场景、时间轴、渲染和交付检查；Fish Audio 是标准配音阶段的外部服务。网站只解释工具链与最后一次核对结果，不接收访客脚本、素材、密钥或视频，也不提供在线编辑与渲染。
当前关键技术事实
- 它真正解决的事
- 把已经确定的文案、素材和场景设计，分阶段做成旁白踩点、可预览、可续作渲染的 4K60 视频、封面和章节；它不是自动选题或一键投稿服务。
- 普通输入与结果
- 每场一份 script_NN.txt，加上明确素材和审阅后的 SVG（可缩放矢量图）片段；交回有声 preview.html、final_output.mp4、cover.png、chapters.txt，可选全片字幕，以及验证后生成的 delivery.json。
完整执行流程
- 1创建空白项目并先验环境
run.ps1 init 先暂存通用模板，再交给空目标目录；新工程先运行只读 doctor。test 是维护回归入口，不是每次制作必跑；doctor-local 和 doctor-live 分别承担明确本地探针与外部配音探针。
- 2把确认过的旁白按场拆开
按已审阅分镜写 script_01.txt、script_04.txt、script_100.txt 等真实编号并设置标题；所有阶段保持同一编号集合。需要共享对齐时，每场已知文案音频不得超过 300 秒。
- 3生成旁白、时长与词级时间轴
tts 生成 MP3、原生词语时间与 0.2 秒场间停顿；timing 优先复用有效词轴，再选 Fish 原生时间或 ChineseASR 对齐。已有但损坏的时间戳报错，不能当作缺失自动跳过；durations 可独立重建时长而不运行语音模型。
- 4让场景只包含可审阅的静态片段
prompts 注入旁白、可 cue 词与真实素材 URI；人或 AI 只保存 SVG 内部片段，不把整页 HTML、脚本或虚构路径混进去。
- 5先构建、查硬错误并看动态预览
build 校验编号、cue、重复属性、时间及动画名称，lint 检查越界；有声 preview 支持按词跳转、拖动和暂停，cue 编辑器只导出修改片段。保存后重建并听看，再启动长渲染。
- 6按固定时间逐帧渲染并可恢复续作
Playwright 截透明前景，FFmpeg 叠背景，NVENC 分片编码；逐片和整轨检查帧数及来源。输入未变接续缺片，局部场景变化只重做相关分片，成功分片保留到显式清理。
- 7合成旁白并补齐封面和章节
merge 拼接旁白并按需压低 BGM，cover 生成 4K 封面，chapters 生成从 00:00 开始的目录；需要时用 subtitles 导出全片 SRT/WebVTT。
- 8验证、观看，再决定是否投稿
verify 核对当前来源、帧数、时长与交付结构，manifest（清单） 在通过后写 delivery.json；人再实际观看。cleanup --dry-run 可先看清单，实际清理只处理已知可再生文件；投稿仍是独立人工动作。
来源读取与精确判定
这不是从空白提示词自动长出视频的服务。输入按阶段来自本人确认的脚本、素材与场景设计；其中标准配音会把旁白文本发给 Fish Audio，其余核心制作在本机完成。
scripts/script_NN.txt：每场一份已确认旁白，可含适度的 Fish 情绪或停顿标记。脚本内容、模型、声线、格式和尾部停顿共同绑定音频身份。；Fish Audio 返回 raw_audio/audio_NN.mp3；密钥只从环境变量或被忽略的 secret_local.py 读取，网页不显示值。
raw_audio/audio_NN.mp3：FFprobe 读取真实时长；词语时间优先来自该音频的 Fish 原生时间戳，必要时把同一音频与已确认旁白交给 ChineseASR 本地对齐。音频、文案、来源与输出哈希共同约束词轴。；durations.json、srt_data/srt_NN.json 及对应身份记录；词轴同时服务动画触发、有声审阅和可选字幕导出，不默认烧进视频。
assets/ 与 scene_html/fragment_NN.svg：素材以真实 file:/// URI 写入提示词；人工或当前 AI 审阅提示词后，只保存静态 SVG 片段与动画、cue 属性。；构建后的 scene_NN.html；素材字节也进入渲染续作身份，同一路径换图不会沿用旧画面分片。
场景 HTML、背景与可选 bgm.mp3：Playwright 按时间 t 截取透明前景帧，FFmpeg 叠到 4K 背景，NVENC 编码；背景音乐由本人提供并在旁白出现时侧链压低。；video_track.mp4 和带 AAC 旁白的 final_output.mp4；没有旁白时 merge 拒绝生成静音最终交付。
PROJECT_TITLE 与 chapters.json：标题决定封面正文；章节用 1-based 场景编号，第一章必须从 scene 1 开始，编号唯一且递增。；3840×2160 cover.png 和从 00:00 开始的 chapters.txt；它们仍需与本期内容人工核对。
“本地视频工作流”描述场景、识别、浏览器与渲染主要在这台电脑执行，不等于全程离线。标准 TTS 会发送旁白文本；doctor-live 也会发一条真实网络探针，只有明确需要时才运行。
本页用到的名词
需要核对专业含义时，可以在这里查看它在 video-scaffold 项目中的具体用法。
- TTS（文字转语音）
- 把每场脚本文本交给 Fish Audio 合成旁白 MP3；这是标准流程中明确的外部网络步骤。
- word timeline（词级时间轴）
- 每个词的开始和结束秒数；新旁白优先采用 Fish 原生时间戳，缺少时用 ChineseASR 对齐，经过审阅后用于画面触发。
- cue（旁白触发词）
- SVG 元素写入的真实发音词。构建时转换为具体延迟；没有命中就保留 data-cue-missing 并阻断。
- SVG（可缩放矢量图）
- 每场前景的静态结构，文字、线条、图片和 data-anim 属性都写在其中，再由公共模板驱动。
- seekTime(t)（按时间定位画面）
- 把场景设置为第 t 秒应有的状态；渲染逐帧调用它，而不是等待浏览器自己播放。
- Playwright（浏览器自动化工具）
- 打开场景 HTML、检查布局并截取每一帧透明 PNG；无头检查不等于人工看过画面。
- NVENC（NVIDIA 硬件编码器）
- 由显卡把逐帧画面编码为视频；当前配置使用 AV1、p6、CQ 22 和 10-bit 像素格式。
- sidecar identity（伴随身份文件）
- 保存在生成物旁边的小型 JSON，只记录输入配置与 SHA-256，不保存脚本文本或密钥；用于判断旧产物能否复用。
系统里实际有什么
下面是当前产品组件，不是概念分类。每一项都对应真实文件、入口或验证链。
从通用仓库创建空白工作区，并让所有阶段使用同一个命令面。
run.ps1 / pipeline.workflow 是唯一生产入口；init_project.py 先暂存通用模板再交到空目标。解释器按 VIDEO_PYTHON、项目 .venv、机器适配、py -3.11、系统 python 解析，旧定制入口不再在活动树。
保存画布、编码、转场、配音、识别、章节和目录的唯一当前选择。
config.py 保留 3840×2160、60fps、av1_nvenc、4 workers、300 帧分片、Fish s2.1-pro-free 与云飞声线；VIDEO_TIMING_SOURCE=auto|fish|chinese-asr。机器解释器和 GPU/ASR（自动语音识别） 适配只在被忽略的 .video-machine.json 登记。
把每场脚本变成音频、精确秒数和词级触发依据。
pipeline/fish_tts.py 与 fish_native.py 接收声音和原生词轴；durations.py 只读时长，transcribe.py 选择词轴或已登记 ChineseASR，artifact_identity.py 约束输入和输出。视频工程不安装自己的 Whisper。
把脚本、时间轴和素材组织成可审阅的 SVG 场景，而不绑定一个固定大模型。
pipeline/author.py、build_scene.py、components.py、v2lib.py；模板支持基础与高级 data-anim 原语，缺 cue 留下机器可审计标记。
在昂贵渲染前验证确定性时间函数、画布位置和全部场景的动态效果。
templates/scene_base.html、pipeline/lint.py、preview.py 与 serve.py；有声预览可按词定位、暂停和导出 cue 修改片段，临时 HTTP 仅绑定回环端口，关闭会话即停。
逐帧合成透明前景、背景和成片效果，控制并发并防止静默少帧。
pipeline/render.py 按最多 300 帧分片、4 workers 和有界重试生成视频；每 worker 至多缓存 6 个页面。分片有当前输入及输出身份，局部变化不再令无关正确分片全部失效。
把视频轨、旁白、可选背景音乐、封面和章节组合成可检查交付。
pipeline/merge.py、cover.py、chapters.py 和 subtitles.py 组合旁白、BGM、封面、章节和可选 SRT/WebVTT；BGM 侧链压低，最终视频含 AAC 音频。
区分文件存在、结构正确和人已观看，并保留失败后的继续位置。
pipeline/cleanup.py 的 verify/cleanup 与 workflow 的 manifest（清单） 阶段；核对来源、总帧与时长、音视频起点、编码、封面、章节和字幕，再写 delivery.json。dry-run 只列已知可再生项，未知文件与原件保留。
5 层证据分别证明什么
能证明：84501b0 的公开主分支实际包含共享对齐、有声审阅、完整阶段来源校验、增量分片与交付清单。
不能证明：当前 Fish 服务可用、这台电脑能完整跑一条视频，或网页已经发布。
能证明：2026-09-03 保留的源仓库与新工程各 33/33 只证明当时的受控合同；当前源码包含扩展测试和 CI，但本轮没有重新运行源全套或把入口存在称为最新通过。
不能证明：真实 Fish 音色或时间戳、共享对齐的语音准确度、生产 4K60 性能及人工审美。
能证明：2026-09-18 静态 doctor 回读依赖、背景/模板、协调登记和 ChineseASR 适配入口：10 项通过、Fish 实际路线未探测。
不能证明：Fish 网络响应、长视频稳定、成片音画正确或下一次仍不受资源争用。
能证明：只有本期真实 preview、render、merge、cover、chapters、verify 和最终观看才能证明这一期视频的结果。
不能证明：本轮没有执行这些步骤，因此网页不展示演示成片或 READY 结论。
能证明：源 main 远端回读证明修复已发布；网站 Pages 回读只证明本页部署。
不能证明：代码发布、网页发布和视频平台投稿互不替代。
维护入口
pwsh -File E:\Projects\Archives\video-scaffold\run.ps1 init D:\Videos\my-next-video创建新项目：目标必须为空；复制通用工具、背景、文档和测试，创建脚本、素材、音频、时间轴、场景、渲染与输出目录。
pwsh -File .\run.ps1 test项目自检：维护时运行项目离线回归；不是每次制作都要重跑。2026-09-03 的源和新工程各 33/33 是历史证据，本轮未复跑。
pwsh -File .\run.ps1 doctor --json本机环境体检：纯静态只读，不读取密钥文件、不启动浏览器/GPU、不请求 Fish；status/plan 可继续查看工程缺口与重跑原因。真实本地探针另用 doctor-local。
pwsh -File .\run.ps1 doctor-live真实 Fish 探针：明确需要时才发送一句“连通性测试。”并验证 MP3 后删除临时目录；本轮没有运行。
pwsh -File .\run.ps1 <tts|timing|durations|prompts|build|lint|preview|render|merge|cover|chapters|subtitles|verify|manifest>逐阶段制作：只运行本期需要的阶段；timing --source chinese-asr --force 可对同一音频重对齐，preview --open 启动有声审阅，不能跳过人工检查。
pwsh -File .\run.ps1 verify最终交付检查：核对当前来源、真实总帧与时长、音视频流起点、编码/画布/帧率、PNG 封面、章节及 cue；通过后 manifest（清单） 生成 delivery.json。READY 不代表已观看或已投稿。
pwsh -File .\run.ps1 cleanup --dry-run清理可再生物：先预览可再生临时物清单；明确 cleanup 才执行，保留原件、未知文件和最终交付。失败要说明真实残留，不假报清空。
快照怎样更新
本页代表最后一次明确核对并发布的项目状态，不承诺后台实时同步。再次更新时会重新读取该项目当前事实、边界和验证结果；无法确认的内容继续明确标成网页快照边界，不用旧记录猜成当前状态。