EffectCraft 动态图形工具包是做什么的？

一个经过测试的工作流程，用于在 EffectCraft 中制作 60 秒的企业动态图形视频，使其看起来经过专业设计、保持同步，且没有常见的 bug：场景之间的空白帧、重叠的语音线、被装饰覆盖的文字、消失的数字以及错拍子的音效。

设计来源于选定的外观和布局，而非从零开始。 从五种经过测试的外观中选择一种，将每个场景编写为一个带有你的内容和词语时间点的 scene() 调用，布局会自动处理尺寸、网格、颜色和动画。那些自行发明风格的代理最终往往会得到暗色渐变、发光斑块和居中小字号文字；这是导致生成的宣传片看起来廉价的最主要原因。

任何代理都可以使用此工具包。 所有操作都在 shell 中运行（通过 scripts/ec.py 调用 effectcraft-cli）。MCP 是可选的。工具包位置：包含此文件的文件夹（称为 $KIT）。

非此工具包适用： 简笔画 / 角色故事视频（分屏显示的“错误方式 vs 正确方式”）应使用 stick-figure-story 工具包。

黄金法则（原因见 `references/`）

时间来自数据，而非猜测。 场景计划保存在 timeline.json 中。场景脚本使用 SC("s3") 和 W("s3", "word")（某个词语被说出的绝对时间）。切勿输入类似 23.6 的时间。
查看你构建的每一个场景。 渲染预览帧（ec.py frames）并打开生成的 PNG 图片。运行时无错误的代码仍然可能渲染出错误的结果。
“完成”意味着通过了所有关卡。 timeline.py check 显示 0 FAIL，ec.py qa 显示 0 FAIL，ec.py qa-video 显示 0 FAIL，并且你已经查看了联系表。诚实地报告结果，包括警告信息。
使用一种外观和相应的布局（references/looks.md）。在选择之前，至少比较两种不同的外观。至少三分之一的场景必须是可视化的（手机/图标/流程图/柱状图，或包含物体的自定义场景）。自定义场景代码仅用于布局无法覆盖的内容（如地图、产品模型），并且它仍然使用所选外观的调色板 P(S.bg) 和字体大小 LOOK.type。
在编写任何 EffectCraft 脚本之前，先阅读 references/pitfalls.md。在设计场景之前，阅读 references/motion-design.md、references/looks.md 和 references/techniques.md（节拍网格、峰值对齐音效、连续变形、禁用列表）。
品牌信息不是你可以编辑的（references/brand.md）。展示真实的 logo 文件，绝不要只输入品牌名称作为文字商标。逐字编写标语。不要发明产品名称、按钮标签或统计数据。在 timeline.json 中填写 "brand" 块，以便 ec.py qa 进行检查。
通过 QA 并不等同于好的设计。 在编写场景之前规划好色彩脚本、视觉元素和标志性时刻，并在渲染前进行创意总监级别的影片评分（references/design-review.md，并与 references/benchmark_sheet.png 对比）。 7b. 真实产品 UI（SaaS、应用程序影片）：遵循 references/ui-footage.md：仅捕获示例数据，裁剪到一个面板，使其清晰可读（宽度占 55% 以上）或将其重建为动画 UI，每屏一个镜头，不要使用有色缩略图墙，不要发明数字，并在此工具包内构建以便运行 QA 关卡。
高能量 / 超动态广告（TikTok 风格，每个词都匹配一个画面）：遵循 references/high-energy.md 和 templates/hyper.jsx，而不是使用平缓的布局。
报告渲染显示的内容，而不是你计划的内容。 在撰写报告或交接前，从最终 MP4（而非预览）中提取每个场景中间和最后半秒的帧，并检查每一项声明：每一行文字在屏幕上的显示时间是否足够阅读，每个绘制的步骤是否真的可见，截图是否清晰，时长是否匹配简要和文件名。将每段语音转录与脚本进行对照，并仔细听品牌名称。在测试中，某个代理的交接描述了四个图表步骤、三个承诺和“BridgeAxis Technologies”；但最终影片显示的最后一个步骤在剪辑前仅 0.3 秒，承诺仅显示半秒，截图无法阅读，并且语音说的是“Bridge Access”。timeline.py check 和 ec.py qa 现在会对无法读到的语音错误和持续时间短于 min_read 秒的文字发出警告：请修复这些警告，而不是为它们找理由。使用你的代理可用的最高推理设置运行：那个草率的运行是在“低”设置下进行的。

项目布局

<project>/
  timeline.json        场景计划 + 音效提示 + 音乐（从 $KIT/templates/timeline.example.json 开始）
  audio_meta.json      语音文件 + 词语时间戳（来自语音步骤）
  soundtrack.wav       由 timeline.py mix 生成
  assets/voice|sfx|bgm|icons|fonts
  scripts/lib.jsx      从 $KIT/templates/lib.jsx 复制而来（设置 COMP；外观提供颜色和字体）
  scripts/look.jsx     由 `ec.py look NAME --accent HEX` 写入
  scripts/timing.jsx   自动生成（timeline.py emit）- 切勿编辑
  scripts/wipes.jsx    自动生成（timeline.py emit）- 最后运行
  scripts/reset.jsx, s1.jsx ... s8.jsx
  qa/                  预览帧和联系表

从 <project>/ 目录运行所有命令。ec.py 从 timeline.json 读取项目路径和合成名称。

工作流 A：新视频

0. 需求简报。 在开始构建之前询问：需要匹配的品牌/网站、氛围（响亮/平静/技术/奢华）、时长和宽高比、语音（性别/语调），以及是否需要音乐/音效。猜测创意方向是第一个剪辑被拒的最常见原因。

1. 设置

mkdir -p <project>/{scripts,assets/{voice,sfx,bgm,icons},qa} && cd <project>
cp $KIT/templates/lib.jsx $KIT/templates/reset.jsx $KIT/templates/s1.jsx scripts/
cp $KIT/templates/timeline.example.json timeline.json   # 编辑 project/comp/output 名称
python3 $KIT/scripts/ec.py fonts                         # 安装外观所需的字体（每台机器只需运行一次）

在 scripts/lib.jsx 中设置 COMP 为时间线上的合成名称。注意品牌的强调色（logo、网站 CSS、产品）。如果品牌有网站，读取其 CSS 以获取强调色和字体。将 logo 文件放入 assets/logo/，并在 timeline.json 中填写 "brand" 块：品牌名称、准确的标语、logo 文件，以及任何经批准的产品名称或 URL（references/brand.md）。

2. 脚本和语音。 编写 8 行脚本（吸引点、问题、品牌、2-3 个优点、证明、结尾卡片）；60 秒的时长大约包含 110-130 个词。为每一行生成一个单独的音频文件，并将词语时间戳以如下格式放入 audio_meta.json：

{"voices": [{"id": "s1", "path": "assets/voice/s1.wav", "duration_s": 6.45,
             "words": [{"word": "Every", "start": 0.30, "end": 0.59}, ...]}]}

首先运行 python3 $KIT/scripts/ec.py doctor。 它会列出本机器拥有的工具以及如何安装缺失的部分。当它显示 ready 时，不要研究或安装替代方案（edge-tts, Whisper, piper, Playwright）：下面的工具是经过测试的。如果没有语音，则使用 "in+0.5" 偏移量来代替词语来为场景计时；$KIT/demo/ 是一个完整的无声示例（ec.py demo 可以渲染它）。

语音（默认）：本地 Kokoro，女声 af_heart。免费，无需账户。模型缓存在 ~/.cache/hyperframes/tts/ 中（首次运行时下载一次）：
```
export HYPERFRAMES_PYTHON=~/.venvs/kokoro/bin/python   # 必需：安装了 kokoro-onnx 的虚拟环境
npx hyperframes tts "Line one text." -v af_heart -o assets/voice/s1.wav   # 每行一个文件
```
如果没有设置 HYPERFRAMES_PYTHON，它会失败并提示“The kokoro-onnx package is not installed”。不要通过 pip 安装任何东西：设置环境变量即可。
词语时间戳：npx hyperframes transcribe assets/voice/s1.wav --json。 它使用 Parakeet 模型，首次运行后会缓存到 ~/.cache/hyperframes/parakeet（引擎 auto 会自动选择它）。Parakeet 适合像 Kokoro 这样清晰的 TTS 语音。不要在这里传递 -e whisper 参数：hyperframes 的 Whisper 引擎（whisper.cpp）尚未设置。对于带有口音的真实录制语音，素材编辑工具包改用 faster-whisper large-v3-turbo（位于 ~/.venvs/asr）。将词语及其开始和结束时间复制到 audio_meta.json 中。
音乐和音效：媒体素材音频引擎（node <skills>/media-use/audio/scripts/audio.mjs --request audio_request.json --out audio_meta.json --only bgm,sfx）。它通过描述从 HeyGen 目录中检索，例如 "bgm": {"mode": "retrieve", "query": "warm calm piano"}。<skills> 对于 Claude Code 是 ~/.claude/skills，对于 Codex/OpenCode/DeepSeek 是 ~/.agents/skills。
HeyGen 文本转语音（通过引擎或 heygen CLI）是另一种语音选择，但免费额度会用完。当额度用完时，使用 Kokoro。音乐和音效检索也需要 heygen CLI 登录（heygen auth login --oauth），除非设置了 HEYGEN_API_BASE；如果没有登录，sfx 仍然可以从媒体素材工具包捆绑的库中获取，并且用户可以自行提供音乐文件。

记下你实际使用的提供商和语音。

3. 时间线

python3 $KIT/scripts/timeline.py beats      # 音乐节奏、节拍、小节起始、落点 -> beats.json（需要 "music"）
python3 $KIT/scripts/timeline.py suggest    # 建议场景的进出点和voice_at；如果已有beats.json，场景会在节拍处结束
# 粘贴到 timeline.json，设置每个场景的 "bg"（light/dark/accent），添加锚定在词语上的音效提示
python3 $KIT/scripts/timeline.py words      # 每个词语及其绝对时间
python3 $KIT/scripts/timeline.py check      # 必须显示 0 FAIL
python3 $KIT/scripts/timeline.py emit       # 写入 scripts/timing.jsx + scripts/wipes.jsx
python3 $KIT/scripts/timeline.py mix        # 写入 soundtrack.wav（-14 LUFS）

在节拍上进行剪辑：timeline.py snap 可以在语音仍然合适的前提下将现有剪辑点移动到节拍上；在场景中，BEAT(n)、DOWNBEAT(n)、nearBeat(t) 和 T.drop 可以将时间冲击和爆点与音乐对齐（references/techniques.md）。音效的 "at" 可以是一个数字、"beat:12"、"downbeat:3"、"drop"、"s2:late"（s2 语音中的单词 "late"；"s2:the#2" = 第二个 "the"）、"wipe:s3"（进入 s3 的转场）、"in:s3" 或 "out:s3"。添加 "offset"、"vol"、"max"（剪辑长度）和 "align": "peak"（声音最响亮的时刻落在锚点上：用于冲击和爆点效果）。

4. 规划，然后编写场景。 首先在 qa/design_review.md 中编写计划（references/design-review.md，第 1-6 部分）：每行一个场景的色彩脚本、每行文字所展示的视觉元素、每个场景的主角以及唯一的标志性时刻。在 timeline.json 中为每个场景设置背景（"bg": "light" | "dark" | "accent"）并重新运行 timeline.py emit。交替使用不同背景，使每次剪辑都像一个新的章节。将 "accent" 用于 1-2 个最响亮、通常是情感高潮的时刻。将品牌展示和结尾卡片放在真实 logo 阅读效果最好的背景上（通常是 light），而不是 accent。然后编写 scripts/s1.jsx ... sN.jsx，每个都是带有布局的 scene() 调用（规格：templates/layouts.jsx 顶部；指南：references/looks.md）：

// scripts/s2.jsx
scene("s2", "list", { label: "问题所在",
  items: [["到达晚了。", "late"], ["海关惊喜。", "customs"], ["追踪告诉你 *什么都没有。*", "tracking", "nothing"]],
  punch: ["太晚了。", "too"] });

*word* 标记某行文字的重音部分。时间使用 timeline.py words 中的词语（"word"、"word#2"、"word+0.3"、"in+0.2"），编写时不带标点符号。布局会自动放大或缩小文字以填满画面，因此请直接编写你想要的文案，让布局来处理大小。保持屏幕上显示的文字简短：它们是标题，不是配音。只有当布局无法覆盖某些内容时（如地图、产品模型），才复制使用 $KIT/templates/scene_template.jsx。

使至少三分之一的场景实现可视化。 一部只有文字背景的影片读起来像幻灯片演示，无论字体设计得多好。视觉化布局会在屏幕上放置配音所描述的对象：phone（手机屏幕上的产品：支付页面、订单、跟踪更新）、icons（2-4 个带有标签的手绘象形图）、flow（由一条线连接的各站，随着每个站被说出而填充：客户 → 手机 → 银行、仓库 → 港口 → 门）和 bars（2-4 个增长条：费用、等待时间、之前/之后）。选择那些配音描述事物或过程的场景，而不是空洞的主张。

scene("s4", "flow", { label: "工作原理", title: ["*当天*到账。", "money", "same"],
  nodes: [{ icon: "shop", label: "您销售", at: "sell" }, { icon: "phone", label: "Tapnest", at: "app" },
          { icon: "bank", label: "您的账户", at: "account", note: "当天" }] });

图标由工具包绘制（无需文件）：phone card bank cash clock check tick shop bolt chart truck box pin lock user people chat globe send star plane doc。当其图片/物体层名称中包含 "VIS" 时，自定义视觉场景也算作视觉场景（例如 "s5 VIS map"）；当少于三分之一的场景是视觉场景时，ec.py qa 会发出警告。不要将 layouts.jsx 复制到项目中：ec.py 会从工具包中加载它，复制品会冻结旧版本。

5. 选择外观（首先阅读 references/looks.md）。挑选两种适合品牌但风格不同的外观，采用品牌的强调色，并在你的场景上进行比较：

python3 $KIT/scripts/ec.py new
python3 $KIT/scripts/ec.py import soundtrack.wav assets/icons/*.png
python3 $KIT/scripts/ec.py compare editorial swiss --accent FF5B1F   # -> qa/look_compare.png：打开它
python3 $KIT/scripts/ec.py look editorial --accent FF5B1F             # 应用获胜者

6. 构建和预览

python3 $KIT/scripts/ec.py run s1 s2 s3 s4 s5 s6 s7 s8 wipes   # s1 创建合成 + 音轨
python3 $KIT/scripts/ec.py frames 2 4 6.5                      # 打开 qa/frames.png 并查看

预览每个场景的两到三个时刻。要修复某个场景，编辑脚本并运行 ec.py rebuild sN（仅清空该场景，重建它，重新运行转场）。要重建所有内容（例如在更改外观后）：ec.py run reset s1 ... sN wipes。外观提供转场效果；要替换它，编写你自己的 scripts/wipes.jsx，不要包含 "GENERATED" 头部行（之后 emit 会将其保留）。

除了预览帧之外，还要审查音频同步：

7. 质量保证

python3 $KIT/scripts/ec.py qa               # 场景脚本检查 -> qa/qa_report.md
python3 $KIT/scripts/ec.py qa-video output.mp4  # 最终视频检查 -> qa/video_qa_report.md
# 修复所有 FAIL 项。然后生成联系表以供人工审查：
python3 $KIT/scripts/ec.py contact-sheet    # qa/contact_sheet.png：打开它

联系表按顺序显示每一帧。播放 qa/qa_video.mp4（最后 10 秒循环播放）。将联系表与您的设计计划进行比较：每个场景是否按预期出现？是否涵盖了所有要点？您是否修复了所有的 FAIL 和 WARN？即使通过了所有关卡，您的渲染也可能在视觉上仍然不如人意：颜色平淡、文字边缘未对齐、徽标模糊。如果是这样，请重新考虑外观或布局选择，或调整 timeline.json 中的场景背景。

8. 最终输出

python3 $KIT/scripts/ec.py render output.mp4   # 或 output.mov

质量保证总是在渲染的输出上运行，而不仅仅是在预览上。最后，诚实地报告最终的 QA 结果，包括您解决的任何警告。

修复现有项目

当用户要求修复由另一个代理制作的 .ecproj 文件时：

使用 $KIT/scripts/ec.py doctor 诊断项目：它会报告缺失的脚本、未对齐的时间、损坏的依赖项以及项目结构问题。
确保 scripts/timing.jsx 存在并由 timeline.py emit 生成。如果没有，则从 timeline.json 运行 emit。
添加 audio_meta.json 以启用词语级检查。如果没有，则使用 ec.py transcribe-assets 重新转录，或为每个场景添加 "in+N" 偏移量。
确保 scripts/look.jsx 存在。如果没有，则使用 ec.py look <某个外观> --accent <十六进制颜色> 选择一个。
运行 ec.py qa 并修复每个 FAIL。特别寻找：重叠的面板、运行时间过长或过短的场景、缺少或损坏的背景、缺少转场、文本不匹配、未使用的图标、复选框未对齐或放错位置、检查视觉设计是否流畅，以及字体是否未反映外观的字体。
运行 ec.py rebuild <场景> 修复单个问题。
渲染最终输出并应用相同的 QA 流程。

修复项目很棘手，因为原始代理可能尚未完成场景设计。检查 references/pitfalls.md 以了解经典 bug：闪光帧和空白帧、GIF 中间的插件徽标以及从未移除的动态模糊。始终重新构建转场：运行的修复可能已经改变了场景时间。

创建定制的`layout.jsx` 场景布局

本节描述了如何构建 $KIT/templates/layouts.jsx 风格的新布局。该工具包提供了四种基本布局：list、phone、icons、flow 和 bars。如果这些都不合适（例如，您需要仪表盘、地图、拆分屏幕或品牌徽标布局），您可以创建一个。目标不是每次都从零编写代码，而是编写一个新的 scene() 包装器并将其放入 scripts/custom_layouts.jsx。所有布局共享相同的 API，因此使用两个标准调用：

P(name) - 调用外观的调色板。适用于纯字符串。
S.look.bg / S.look.type - 调用外观的字体和背景规则。

请查看 $KIT/templates/layouts.jsx 以获取精确的可复制示例。创建一个复刻，修改中间部分，并导入到您的场景中。

要调试您自己的布局，请直接在一个简单的场景中调用它：

scene("s3", "myLayout", { ...props });

然后运行 ec.py rebuild s3。如果在嵌套场景方面遇到困难，请查看代码。

创意工具提示

ec.py storyboard 从您的场景生成一个故事板 PDF。
ec.py script 打印出为每行语音生成的文本。
ec.py review 在浏览器中打开一个交互式审阅链接。

命令参考

命令	用途
`ec.py doctor`	诊断项目并检查依赖项
`ec.py new`	初始化一个新项目
`ec.py fonts`	安装所有必需的外观字体
`ec.py import <文件...>`	将文件导入 `assets/`
`ec.py compare <外观A> <外观B> [--accent ...]`	在您的场景上比较两种外观
`ec.py look <外观> [--accent ...]`	应用一个外观
`ec.py run <scene...>`	构建并渲染场景
`ec.py rebuild <scene>`	仅重建一个场景
`ec.py frames <time1> <time2> ...`	在特定时间点渲染预览帧
`ec.py qa`	运行场景质量保证
`ec.py qa-video <video>`	在最终视频上运行质量保证
`ec.py contact-sheet`	生成联系表
`ec.py render <output>`	渲染最终视频
`ec.py transcribe-assets`	重新转录资产（对于修复代理很有用）

常见错误和修复

空白帧：转场未正确运行。检查 wipes.jsx 是否已生成并已运行。
重叠的语音：audio_meta.json 中的词语时间重叠。手动调整或重新转录资产。
覆盖文字：如果文字被背景对象遮挡，请改变布局（phone、flow 等）或调整场景的 "bg"。
消失的数字：布局参数中的数字需要是字符串或正确转义。
音频不同步：检查 timeline.py check 是否通过。如果有节奏问题，请运行 timeline.py snap。
外观未显示：确保 look.jsx 存在并且外观名称与 layouts.jsx 匹配。

EffectCraft 动态图形工具包