brand-cut 是做什么的？
公司 / URL / 代码仓库 -> 研究 -> 品牌套件 -> 产品场景脚本 -> 故事板 -> (配音) -> 原型构建 -> (混音) -> QA -> 渲染矩阵 -> 交付
在制作你的第一个视频之前，请先阅读 LEARNINGS.md。它记录了所有曾导致视频被拒或渲染失败的情况。
0. 规则（具有约束力）
- 每个场景必须是具体的产品时刻，并包含真实 UI。当 AI 出现时，屏幕上必须显示真实的 AI 回答。没有抽象的标语。
- 真实高于营销。 从代码库、文档和真实应用截图中构建；网站仅用于获取基调。屏幕上的每一个主张都必须追溯到来源（
qa/claims.py）。 - 精确的 Logo，颜色取自来源，绝不近似。
- 不要看起来像 AI 生成的。 不允许全大写 /
text-transform: uppercase、表情符号、斜体显示衬线字体、紫色 AI 渐变、闪光、球体、粒子、镜头光晕、霓虹轮廓、假 UI、程序生成的手机或房屋。 - 闪屏安全。 每约 8 秒最多一次全屏闪白，在任何 1 秒内不得超过 3 次闪烁。最终文件必须通过
qa/flashcheck.py的检查。 - 音效。 每次屏幕 UI 操作都需有设计好的音效；音乐在音效和配音下方避让；不要有节拍起伏。
- 格式是安全区域内的原生布局，而非裁剪。60 fps；1080p 以 4K 渲染并缩小。
- 未经用户明确同意，绝对不要发布、上传或发布任何内容，或购买积分。
1. 布局
SKILL.md, LEARNINGS.md 此文件和陷阱清单
research/RESEARCH.md 阶段 0：公司名称 / URL / 代码库 -> 品牌套件 + 事实 + 真实 UI 截图
brand.schema.json 品牌套件模式（schema）
brands/demo/ “Tidewell”，一个虚构品牌；为新品牌复制它
archetypes/ CONTRACT.md + 30 个场景模板（scene.html + README.md）
formats/ presets.json（尺寸、安全内边距、渲染预设、响度）+ safe-*.png 叠加层
shared/ hf.js（运行时：格式、选择、种子随机数生成器）、phone.js（逼真手机）、type.js、uikit/（聊天、通知、日历、收据组件）
audio/ vo.py（ElevenLabs + 预算保护）、mix.py、music.md、sfx/（INDEX.md、INDEX.json、文件）
qa/ flashcheck.py、framecheck.py、safezone.py、claims.py、vo_diff.py、contact.py、run-all.sh
scripts/ new-film.sh、add-scene.py、set-format.py、set-brand.py、brand-css.py、render-matrix.sh、
save-ref.sh、index-refs.py、shazam.py、xcorr.py、beats.py、peaks.py
templates/ SPEC.md（视频合约）、index.html、project/、structures/
reference/ PATTERNS.md（原型库 + 法则）、RESEARCH-digest.md、studies/（18 个参考卷轴分解 + INDEX.md）
examples/ 完成的示例视频及其品牌套件、SPEC 和剧照
系统要求：Node 18+ (npx hyperframes)，Python 3.10+，ffmpeg，uv（uvx 在一次性环境中运行 QA 和音频脚本）。可选：ELEVENLABS_API_KEY 用于配音（没有它，audio/vo.py 将回退到开源 Kokoro TTS；详见 audio/VOICE.md），一个音乐文件夹（$MOTION_LIBRARY/music）。
适用于任何具有 Shell 的 Agent。如果此文件提到“子 Agent”，而你的 Agent 没有，则按顺序执行步骤；“网页抓取”意指你的 Agent 拥有的任何抓取/浏览工具，或者 curl。
2. 管线
- 研究（
research/RESEARCH.md）。如果有代码仓库则使用代码库模式（最准确），否则使用网站模式，如果两者都可用则都使用。输出：brands/<id>/brand.json、带来源的truths、位于brands/<id>/assets/ui/的真实 UI 截图，以及 5-8 个产品时刻。 - 简报。 受众、格式、时长、配音/纯音乐/静音、观众必须理解的一件事。
- 品牌套件。 复制
brands/demo/，填充调色板（9 阶 glowRamp）、包含文件的字体、Logo、UI 截图、故事、事实、声音。使用brand.schema.json进行验证。 - 搭建框架。
scripts/new-film.sh <brand> <dir> <format> [format...] [--palette id]-> 包含品牌块（字体、CSS 变量、window.BRAND）、film.json、SPEC.md、音频存根的 index.html。随时更换主题：scripts/set-brand.py <dir> <brand> [palette]。切换格式：scripts/set-format.py <dir> <fmt>。 - 脚本。 SPEC.md 第 2 节：每个产品时刻一行（真实 UI、屏幕文字、配音台词、证据、严格的尺寸目标）。阅读限制：<= 3 字/秒，每行 <= 42 个字符，最多 2 行。
- 首先处理配音（有声电影）。
audio/vo/script.txt，每行配音台词一行，然后运行python3 audio/vo.py say <dir> --voice <id> --take <name>。它会发起一个带有时间戳的请求，根据对齐进行拆分，剪掉填充词并限制暂停时间。lines.json提供持续时间。使用qa/vo_diff.py <dir> <take>进行检查。预算保护会拒绝任何超出工作上限的调用。 - 基于配音和节拍网格的故事板（
scripts/beats.py <wav> <dur>）。SPEC.md 第 3 节：原型、入/出点、转场（首选非闪屏转场，PATTERNS 第 4 节）、音效事件。 - 音乐。 三个选项，裁剪到与节拍对齐的窗口（在揭示时刻绽放，在 Logo 上解决）；渲染所选。详见
audio/music.md。 - 从原型构建。
python3 scripts/add-scene.py <dir> <archetype> <scene-id> <start> <dur> [--vars JSON]，然后自定义。使用子 Agent：每个场景组一个构建者，每个构建者只拥有自己的文件；然后由独立的评论员审查快照；最后修复。 - 混音。
audio/events.json（音乐、配音台词、来自audio/sfx/INDEX.md并带有时间的音效、避让）->python3 audio/mix.py <dir>->audio/mix.wav，目标响度 -14 LUFS / -1 dBTP。 - QA。
npx hyperframes check无错误，进行草稿渲染，然后运行qa/run-all.sh <dir> <video> <fmt>（帧检、闪屏检查、安全区域、声明、响度、fps）。对照第 0 节规则审查qa/contact.py <video> 10 <prefix>生成的分镜表。 - 渲染矩阵。
scripts/render-matrix.sh <dir> [--4k 16x9]：针对每种格式，以 4K 捕获并缩小至 1080p，混入音频，运行 QA 关卡。首先检查可用磁盘空间。 - 交付。 一个包含视频、
index.html画廊和简短 REPORT.md（内容、使用的积分、音乐和配音替代方案、不足之处）的文件夹。向用户打开它。
3. 格式（formats/presets.json）
| id | 画布 | 安全内边距（上/下/左/右） | 用途 |
|---|---|---|---|
| 16x9 | 1920x1080 | 108/108/192/192 | YouTube、LinkedIn、X、网站 |
| 9x16 | 1080x1920 | 270/680/70/140 | Reels、TikTok、Shorts |
| 1x1 | 1080x1080 | 86/86/135/135 | IG/LinkedIn 信息流 |
| 4x5 | 1080x1350 | 108/108/86/86 | IG/FB 信息流 |
| banner | 1920x600 | 60/60/96/96 | README / 网站头图条（静默循环） |
场景读取 window.BRAND.format 并根据格式（[data-fmt="9x16"]）分支布局。短边始终为 1080 px，因此 px 尺寸可跨格式沿用；在竖屏格式中放大英雄元素。
4. 原型（详见 reference/PATTERNS.md）
glow-field (A01, 全屏 WebGL 光效) | glass-slab (A02, 显示真实流式回答的 AI 面板) | glass-tile-click (A03) | word-blur-in (A04) | tracking-collapse (A05) | chip-marquee (A06) | status-stack (A07, 参考实现) | wordmark-lockup (A08) | phone-tunnel (A09) | drum-wheel (A10) | card-carousel (A11) | network-lines (A12) | composer-send (A13) | card-burst (A14) | checklist-fix (A15) | orbit-chips (A16) | list-swap-toggle (A17) | object-launch (A18) | brutal-type (A19) | icon-ring (A20) | calendar-pick (A21) | product-hero (A22) | chat-thread (A23) | container-morph (A24) | notification-pile (A25) | docusign-sign (A26) | stripe-paid (A27) | logo-sting (A28) | branch-tree (A29) | counter-pill (A30) | logo-wheel (A31, 循环 "works with" 旋转木马)。
视频结构 S1-S8（SaaS 解说、13 秒竖版、高端润色清单、深色电影感、Figma 展示、渐变开场、手工制作片头、验证面板）详见 PATTERNS.md 第 5 节。合约：archetypes/CONTRACT.md（品牌无关的 CSS 变量、window.BRAND、每实例变量、格式原生、闪屏安全、README 中的音效提示）。
5. 研究新的参考卷轴
scripts/save-ref.sh <url>使用 yt-dlp 下载卷轴，并生成 2 fps 概览 + 歌曲 ID；scripts/index-refs.py对其进行索引。- 每 2 秒构建 10 fps 的片段，并在关键时刻以原生 fps 运行；逐帧跟踪一个元素以命名缓动；使用
scripts/beats.py获取节拍网格；调色板十六进制值；逐帧亮度用于闪屏分析。 - 编写
reference/studies/<id>.md：镜头列表、每个元素的构建方法、相机、缓动数值、转场、字体、调色板、深度、音效、文案结构、为何看起来不像 AI、怎样会使其像 AI、所用原型。该目录下的 18 个研究是已完成的示例。
6. 经过验证的外观
- 发光（A01）： 一个 WebGL 着色器；标量场 -> 9 阶渐变，噪波扭曲，抖动；uniform 值来自单调 Hermite 关键帧表，由 GSAP 代理补间驱动。
- 玻璃效果：
backdrop-filter: blur(22px) saturate(1.5) brightness(1.15)，通过 mask-composite 实现渐变斜面，内部高光和阴影，接触阴影，运动时有一次光泽扫描。 - 字体： 500 字重的 grotesk 字体，逐词模糊入场 14 -> 0 px，缩放 1.06 -> 1，power3.out，行重新居中，持续向后拉远。
- 真实 UI： 从其来源或截图中用 HTML/CSS 重现产品的组件（
shared/uikit/是一个起点）；HF.phone将屏幕映射到逼真的手机模型中。