deck-render
这是 expert-video 包内原子工具;制作流程读 workflows/deck-talk.md。通过 PATH 调 deck-render,不拼接脚本路径,不调用上游创作 workflow。
命令
deck-render check-setup
deck-render scaffold /absolute/project/composition --spec /absolute/project/script/deck-spec.json
deck-render check /absolute/project/composition
deck-render preview /absolute/project/composition --output /absolute/project/review/slides-v1
deck-render render /absolute/project/composition --output /absolute/project/render/slides.mp4 --workers 2 --quality delivery
check-setup检查 Node ≥22、ffmpeg/ffprobe、锁定 npm 依赖、Playwright Chromium headless shell 和当前系统默认中文字体(Windows 微软雅黑;Linux/macOS Noto Sans CJK SC),并运行 HF doctor。doctor 中 Whisper/Kokoro/MusicGen 属可选;本工具不用它们。scaffold只写空目录。产物是根index.html、每页一个compositions/scene-NN.html、本地 GSAP 与图片副本、deck-spec.json。先按时间戳确定时长,再生成;之后直接编辑 HTML,不用 scaffold 覆盖设计。- 指定 1080×1920 等竖屏尺寸时,
.page直接按竖屏画布生成;不可把横屏 HTML 用scale(x,y)非等比拉伸。check会拦截.page的非等比缩放。 check顺序执行 HF lint 和 check(runtime/layout/contrast)。错误阻断;警告必须人工查看,不能把退出码 0 当作视觉验收通过。preview先 check,再 snapshot,落 PNG 与contact-sheet.jpg,不是常驻 HTTP 服务。默认按 spec 每页中点取图;手改 HTML 时序后必须同步 spec 或传--at 2,12,24。输出目录必须为空,改版用新目录。render每次先 check,再渲染;--workers 1–24,质量 draft/looks/delivery。输出 MP4 必须与 HTML 根的宽高、fps、duration 一致;结果与耗时落同名.render.json。已有产物需明确--force;临时输出通过校验才替换,不覆盖输入。- wrapper 全部 HF 子进程使用
HYPERFRAMES_NO_TELEMETRY=1,不改用户全局设置;静帧禁用 Gemini 自动描述,不触发模型付费调用。 - 退出码:0 成功;1 参数/质量检查/渲染失败;2 依赖/环境缺失,交 IT engineer。每条外部命令超时 20 分钟。
spec 契约
{
"width": 1920,
"height": 1080,
"fps": 30,
"theme": "light",
"pip": "bottom-right",
"scenes": [
{"type": "title", "title": "一个清晰的命题", "subtitle": "对应口播第一段", "duration": 8, "points": ["第一条要点"]},
{"type": "chart", "title": "示例数据,不代表业务事实", "duration": 10, "source": "演示数据", "caption": "演示数据", "data": [{"label": "甲", "value": 12}, {"label": "乙", "value": 18}]}
]
}
theme= light/dark。pip= top-left/top-right/bottom-left/bottom-right/none;有小窗时整侧留白,底部另留字幕带。默认与 1080p 的pip-compose参数匹配;改小窗尺寸/画幅时复核并调整版式。scenes非空;每页duration为 3–30 秒,页时长之和必须对应唯一口播音轨;翻页取句边界。工具不自动改稿/合页/伸缩音频。script/deck-spec.json是deck-render与video-producer visual-plan-check共用的唯一计划源,不再并列维护segments。有视觉承诺时 scene 填visual_kind、visual_action;一场多节拍用 scene 内beats数组,每个 beat 填duration,可覆盖场级视觉类型/动作。beat 时长之和须等于 scene.duration;无 beats 时整场即一节拍。- scene 的可选
start/end是全片秒数;beat 的可选start/end是场内秒数。按各自 duration 累加校验,无空隙/重叠。可在 scene 或 beat 内放多条cues:[{start,end,text}],时间相对于所属场/节拍,须有序、不重叠、不越界,字幕不额外累加时长。顶层可填duration校验总长。动态图数量按展开后的 beat 统计,每个 beat 的动作须能在预览中独立核验。 - 每页标题最多 32 字;
points最多 4 条、每条最多 48 字。subtitle与source要简短,超出版式须重排,通过 check 与目检。 type= title/points/chart/image。chart 是正数柱状图(1–6 项,label 最多 8 字),必须给制作溯源source和面向观众标明数据来源的caption;负数/零/折线等改写 scene SVG,不伪造数据迁就模板。- image 页给
image绝对路径、source来源与授权,图片复制进 assets。source仅留制作溯源,不渲染;仅caption会显示给观众。caption不写“原图已裁净”“内部素材”等制作备注。 - 默认 1920×1080 / 30fps;宽高为至少 360 的偶数,fps 为 1–60 整数。竖屏用原生版式脚手架,生成后仍须重排与逐页目检。
HTML 纪律
- 根仅编排 scene;子合成
<template>内用局部时间轴,从 0 起,注册 paused GSAP timeline。每页都声明@font-face。内容和 GSAP 放本地,禁外部字体/CDN,禁止Date.now()、随机数、实时时钟驱动动画。 - 每页至少有可解释的元素入场或图表动画;读字停留段允许静止。不能用全屏静图缩放充当图表动画。
- ✅ 用 scene 的 data-start/data-duration 做有限时间轴视频。
- ❌ 用
/slideshow或present做可导航 deck 后直接 render;此路径可能只输出第一页。 preview产物必须人工检查遮挡、中文、图表、翻页,GATE B 批准后再 render;工具 check 不代替内容审片与甲方闸门。
本目录 package.json 仅锁定 hyperframes 0.8.50、gsap 3.14.2。Playwright 版本统一跟随 browser/package.json,驱动共用 browser/node_modules/playwright-core,Chromium headless shell 仅放在 browser/.browsers;不要在技能内安装 Playwright 或下载浏览器。安装/更新通过 scripts/install-deck-render.sh(Windows 为同名 .ps1)复用共享安装器;Linux/macOS 安装 Noto,Windows 使用系统微软雅黑;容器构建时预装进镜像。不要运行 npx 临时下载或自动 upgrade。渲染 CLI 参考:HyperFrames rendering,具体参数以本包锁定版本为准。