App Store 标题视频是做什么的？

构建两种 App Store 创意素材视频：在应用图标上方循环播放的产品页面标题，以及在搜索结果中应用卡片上播放的搜索结果标题。两者都自动静音播放并无限循环，因此每一帧都必须在无声音的情况下工作，并且最后一帧必须无缝衔接到第一帧。

此技能负责准备文件。它绝不会上传或提交任何内容——用户需在 App Store Connect 中发布。

需要收集的输入

只询问缺失的信息；对话通常已提供部分信息。

版位 — 标题（21:9）、搜索结果（3:2）或两者。每个版位具有不同的尺寸，因此标题渲染不能直接用于搜索。
单一创意 — 视频必须传达的一句话。Apple 自己的指导：“专注于一个单一、清晰的想法。” 两个想法意味着哪个都无法传达。
应用身份 — 应用名称、一句价值主张、品牌颜色、Logo 文件、应用图标 PNG。
真实产品素材 — 如果概念展示了应用，则需要真实的应用截图或画面。创意素材可能突出品牌或内容而非应用本身，因此这是可选的，但当应用出现时，它必须是真实的截图。
时长 — 默认为 8 秒。Apple 接受 5–30 秒。
场合 — 常青、季节性发布、功能更新、品牌重塑。影响该素材是否可以在以后重复使用。

操作流程

该技能的脚本位于此文件旁边的 scripts/ 目录中。在运行它们时，请将路径解析为此 SKILL.md 文件自身的目录——用户的工作目录不是技能目录。

1. 锁定版位并阅读规格

在构建之前，阅读 references/specs.md。其中包含 Apple 的精确表格、应用预览与创意素材的区别以及安全区域规则。

如果 asc CLI 在 PATH 中，asc asset-library specs 会返回 Apple 的实时参考数据——用它来确认这些数字自编写此技能以来没有变化。references/publishing.md 中有查询方法。

这两个版位不可互换：

版位	宽高比	尺寸	典型用途
产品页面标题	21:9	确切为 3840x1646	图标上方全宽横幅
搜索结果	3:2	1920x1280 至 3840x2560	搜索结果中的卡片

2. 选择一个创意并命名海报帧

写下单一创意和海报帧——用户在播放开始前看到的静态画面，以及 Apple 在自动播放关闭时显示的帧。海报帧必须能作为静态图片独立存在。“用你的价值主张或最引人注目的功能来引领”（Apple）。如果海报帧需要字幕才能理解，那么创意尚未完成。

3. 设计接缝，而非片段

视频连续循环播放，人们反复观看，因此 t=0 和 t=D 的状态必须匹配。在制作任何动画前先做好计划：

连续运动 — 完整的 360° 旋转或无限平移的场域可以完美循环，无需额外工作。
返回基础状态 — 缩放或位置动画回其起始值，并且最后一个节拍恰好落在起始帧上。
淡入淡出过渡 — 在开场节拍中淡入，保持，然后在结束节拍中淡出回到基础状态，使衔接成为一个柔和的溶解。

一个片段显示在 [start, start + duration) 范围内，结束状态恰好落在其结束位置是永远不会渲染的。将结束补间提前一帧结束（start + duration - 1/fps），以便最终可见帧确实是基础状态——否则循环会短一帧。

一个在不同于起始帧的帧上结束的片段会被视为错误，而非循环。

4. 使用 HyperFrames 构建

npx hyperframes init <project-dir>

根部的 index.html 声明画布。将其设置为版位的精确像素尺寸——HyperFrames 会以创作时的尺寸进行渲染，并忽略你假设的任何尺寸：

<div id="root"
     data-composition-id="main"
     data-width="3840" data-height="1646"
     data-duration="8" data-fps="30">

成功与否的关键规则：

不要在 #root 上硬编码 1920px/1080px；将其样式设置为 width:100%; height:100%。
没有针对 21:9 或 3:2 的 --resolution 预设——--resolution landscape-4k 是 3840x2160，这是错误的形状，会被拒绝。
给宿主 div、场景根节点和时间线关键帧赋予相同的 id。不匹配会导致每次渲染每个场景等待 45 秒，然后显示静态帧。
在场景内使用 fromTo 而不是 from——宿主会重新定位场景，而 from 会在回拨时发生偏移，这正是破坏循环的原因。
字体必须作为文件打包在 assets/fonts/ 中，并使用 @font-face；只有打包的字体系列才能按名称解析。
将文本和文案作为变量（data-var-text）放入合成中，永远不要烘烤到图像中。
将 compositions/ 中的每个场景作为独立的子合成，以便可以重新渲染单个节拍。

references/hyperframes-build.md 包含循环技术片段、检查和快照命令、渲染标志，以及在 3840x1646 浏览器渲染迭代太慢时可以回退的画布到 ffmpeg 流程。规格和验证在任何情况下都是一样的。

5. 仅在概念需要时生成辅助图像

照片、插图和氛围背景来自图像生成。切勿使用图像模型生成应用 UI——它会幻觉出界面，而商店列表中的虚假 UI 比没有 UI 更糟糕。应用使用真实截图；周围的一切使用生成。

mcode-tools connector tools --keyword image
mcode-tools connector tool <tool_name>          # 首先阅读 input_schema
mcode-tools connector call <tool_name> --args '{"prompt":"...","aspect_ratio":"21:9"}'

references/asset-generation.md 包含完整的发现和调用流程，以及如何提示生成特定宽高比。

6. 检查、快照、预览——然后渲染

npx hyperframes check --json                                  # 必须干净
npx hyperframes snapshot --at 0,4,8                            # 读取 PNG
npx hyperframes preview --background                           # 给用户 URL

在显示预览前先查看快照。仅靠检查通过并不意味着帧看起来正确。

仅在用户看过预览并批准后，或当他们要求直接获取文件时，才进行渲染：

npx hyperframes render --quality delivery --fps 30 --format mp4 --output out/<name>.mp4

当源文件是应用的屏幕录制时，添加 --video-frame-format png，以便 UI 文本和纯色在帧提取中保持不变。

在快照上迭代，只渲染一次。 单帧快照几乎是即时的，因此使用 npx hyperframes snapshot --at 0,4,7.9 并读取 PNG 来判断合成。一个完整的 3840x1646 交付渲染 8 秒需要大约 9 秒（在 M 系列 Mac 上）——渲染不是慢的部分，迭代才是。一旦帧看起来正确，再进行渲染。

以交付质量渲染测试，或在信任接缝判断之前重新编码。 草稿质量的渲染存在量化噪声，编码器在最后一帧上的噪声与第一帧上的噪声不同。这会造成一种非几何因素的环绕差异，导致你追踪一个不存在的错误。如果小测试来自 --quality draft，请按照格式整理脚本的方式重新编码（libx264 -crf 18 -pix_fmt yuv420p）并进行验证。

7. 将文件整理为符合规格

即使在 HyperFrames 渲染后也要运行此步骤。错误的帧率和错误的像素尺寸是人们首先遇到的两个拒绝原因。

node <skill-dir>/scripts/conform-video.mjs --in out/header.mp4 --out out/<app>-header.mp4 --placement header
node <skill-dir>/scripts/conform-video.mjs --in out/search.mp4 --out out/<app>-search.mp4 --placement search

每个版位需要自己的合成和自己的渲染。标题画布是 21:9，搜索画布是 3:2——将其中一个裁剪到另一个会破坏合成，并使主体偏离画面。格式整理可以修复分辨率、帧率和编解码器；它无法修复为错误形状构建的合成。将搜索合成的根设置为 data-width="3840" data-height="2560"。

每个版位一个项目根目录。 根合成声明了画布，因此两个版位不能共享一个根。为每个版位设置自己的项目文件夹，包含自己的 index.html 和资源副本——check 和 snapshot 只查看根目录，而 render --composition <file> 渲染一个独立的合成文件。

脚本会缩放和裁剪到精确的画布，强制恒定 30 或 60 fps，编码 H.264 yuv420p（无 Alpha 通道），去除音频，并设置 faststart。它拒绝静默放大，并在源文件太小时发出提示。

8. 在移交前进行验证

node <skill-dir>/scripts/verify-video.mjs out/<app>-header.mp4 --placement header
node <skill-dir>/scripts/verify-video.mjs out/<app>-search.mp4 --placement search

脚本检查尺寸、宽高比、帧率（恒定，确切为 30 或 60）、时长、编解码器、像素格式和音频。它还会判断循环接缝：它将第一帧与最后一帧进行比较，相对于剪辑自身典型的帧间运动量，因此比普通帧步进更具破坏性的环绕会被报告为可见跳跃。它会写一个 *-seam.png 条带，将两帧并排显示以供目视检查。它必须以退出码 0 退出。 如果未退出，修复合成并重新渲染。

然后提取海报帧并独自查看——这是商店在播放开始前显示的静态画面，因此如果它需要字幕才能理解，视频就需要改进。选择最强的帧，不一定是第一帧：

ffmpeg -v error -y -ss 00:00:04.000 -i out/<app>-header.mp4 -frames:v 1 out/<app>-poster.png

报告你选择的时间码。海报帧是在 Asset Library 中对素材设置的，并且在素材获得批准后无法编辑，因此必须在提交前做出选择。

9. 移交

向用户提供：

最终文件路径，每个版位一个
验证报告
海报帧及其是哪一帧
发布步骤

一个创意素材必须通过三个独立的关卡——上传、批准和放置——仅批准并不会发布它。references/publishing.md 中包含了两种途径以及精确的 asc 命令：

asc asset-library view --app APP_ID                     # 查找库 ID
asc asset-library videos upload --library-id ID --file ./header.mp4
asc asset-library videos set-poster-frame --id VIDEO_ID --time-code 00:00:04:00
asc localizations list --app APP_ID                     # 查找本地化 ID
asc localizations placements create --localization-id LOC --video-id VID \
  --placement-type PRODUCT_PAGE_HEADER_ASSET           # 或 APP_STORE_SEARCH_RESULTS_ASSET

对于已经上线的应用，App Store Connect 中的简化版本是：应用 → 你的应用 → 侧边栏 → Asset Library → + → Upload Creative Assets → 上传两个文件 → 设置海报帧 → Add for Review → Submit for Review → 等待 APPROVED → live version → Product Page Information → "Header and Search Results" → Browse Assets → 选择素材 → Next → Publish。这样会直接上线，无需新版本和新的审核。如果应用还没有上线版本，则将素材附加到下一版本并提交。

告诉用户在 Header and Search Results 选项卡中使用 Preview 检查结果——它会在 iPhone 和 iPad 上、跨方向、语言和深色模式下展示素材，并且不同版位的裁剪也不同。海报帧在素材获得批准后无法编辑，因此在提交前选择一个。

就此打住。不要自己运行上传、提交审核或发布。上传和发布是用户的步骤。

输出约定

out/<app>-header.mp4 — 3840x1646, H.264 yuv420p, 恒定 30 或 60 fps, 5–30 秒, 无 Alpha 通道, 无音频, 小于 500 MB
out/<app>-search.mp4 — 3:2 在 1920x1280–3840x2560 范围内，相同的编码规则
一份所有检查均通过的验证报告
一个海报帧及其时间码
一份简短的移交说明，包含来自 references/publishing.md 的发布步骤

两个版位各自有自己的文件。不要只移交一个文件用于两者。

故障处理

症状	处理方法
`ffprobe` / `ffmpeg` 未找到	`brew install ffmpeg` (macOS) 或 `choco install ffmpeg` (Windows)；脚本需要它们进行检查和格式整理
HyperFrames 无法启动 Chrome	`npx hyperframes browser ensure`，然后 `npx hyperframes doctor --json` 并检查 `.ok`
渲染感觉慢	通常并非如此。一个 3840x1646、8 秒的交付渲染在 M 系列 Mac 上大约需要 9 秒。如果确实很慢，请检查渲染器是否有 GPU 工作线程，并在 `hyperframes snapshot` 帧上迭代，而不是重新渲染。如果只需要查看效果，`--quality looks` 比 `--quality delivery` 更快
编码器将文件标记为 level 4.1	两个画布都超过了 level 4.1 的宏块上限——3840x1646 是 24720 个宏块，1920x1280 是 9600，而限制是 8192。使用 `-level 5.1` 重新编码
接缝检查失败	修复最后一拍，使状态返回基础状态。交叉淡入淡出（`--seam-crossfade`）是备选方案，而非修复，因为它会消耗 `C` 秒的内容
文本在缩略图尺寸下不可读	放大它。Apple 指出素材在商店中的显示方式不同，因此最小的渲染才是真正的测试
上传在 App Store Connect 中被拒绝	在实际上传的文件上重新运行 `verify-video.mjs`，而不是本地原始文件。`asc asset-library videos upload` 也会在上传前根据 Apple 的实时规格验证文件，因此其错误信息会指出你遗漏的规则
Apple 拒绝版位	该位置可能已被占用——创建版位不会替换现有版位。使用 `asc localization`

App Store 标题视频