App Store 標題影片是做什麼的？

建立兩種 App Store 創意素材影片：一種是產品頁面標題，循環顯示在 App 圖示上方；另一種是搜尋結果標題，在搜尋結果中於 App 卡片上播放。兩者皆為自動靜音播放且無限循環，因此每個畫面都必須在無聲狀態下傳達資訊，且最後一格畫面必須無縫銜接第一格。

此技能僅負責準備檔案，絕不進行上傳或提交——發布作業由用戶在 App Store Connect 中完成。

需收集的輸入資料

僅詢問缺少的部分；對話通常已提供部分資訊。

位置 — 標題 (21:9)、搜尋結果 (3:2)，或兩者都需要。每種位置尺寸不同，因此標題的渲染結果無法直接套用於搜尋。
單一概念 — 影片必須傳達的一句話。Apple 的指導原則：「專注於單一、清晰的理念。」兩個理念等同於兩者都無法傳達。
App 身份資訊 — App 名稱、一行價值主張、品牌顏色、Logo 檔案、App 圖示 PNG。
真實產品素材 — 實際 App 的截圖或片段（如果概念中會顯示 App）。創意素材可能強調品牌或內容而非 App 本身，因此此項為選填，但當 App 出現時，必須使用真實擷取畫面。
長度 — 預設 8 秒。Apple 接受 5–30 秒。
場合 — 常態、季節性發布、功能更新、品牌重塑。影響素材日後是否能重複使用。

操作流程

此技能的腳本位於 scripts/ 目錄中，與此檔案相鄰。請根據此 SKILL.md 所在目錄解析該路徑後再執行腳本——用戶的工作目錄並非技能目錄。

1. 鎖定位置並閱讀規格

在開始構建之前，先閱讀 references/specs.md。其中包含 Apple 的詳細表格、App 預覽與創意素材的區別，以及安全區域規則。

如果 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 包含循環技巧片段、檢查和快照命令、渲染標誌，以及一個 canvas-to-ffmpeg 管道，可在 3840x1646 的瀏覽器渲染速度過慢時作為備用方案。無論使用哪種方式，規格和驗證程序都相同。

5. 僅在概念需要時生成輔助圖像

照片、插圖和氛圍背景來自圖像生成。切勿使用圖像模型生成 App 介面——它會產生幻覺介面，而商店列表中的虛假介面比沒有介面更糟。App 使用真實截圖；周圍的所有元素則使用生成方式。

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

當來源為 App 的螢幕錄製時，加上 --video-frame-format png，以確保 UI 文字和平面色彩在幀提取過程中得以保留。

在快照上迭代，僅渲染一次。 單一幀快照近乎即時，因此使用 npx hyperframes snapshot --at 0,4,7.9 判斷組合效果並讀取 PNG。一個完整的 3840x1646 品質渲染，8 秒長度在 M 系列 Mac 上約需 9 秒——渲染並非瓶頸，迭代才是。在幀畫面正確後才進行渲染。

以交付品質渲染測試，或在信任接縫判斷前重新編碼。 草稿品質的渲染會產生量化噪聲，編碼器在最後一幀產生的噪聲與第一幀不同。這會顯示為幾何形狀以外的接縫差異，導致您追逐一個不存在的錯誤。如果小型測試使用 --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，在 App Store Connect 中的簡短版本為：App → 你的 App → 側邊欄 → Asset Library → + → Upload Creative Assets → 上傳兩個檔案 → 設定海報幀 → Add for Review → Submit for Review → 等待 APPROVED → 上線版本 → Product Page Information → "Header and Search Results" → Browse Assets → 選取素材 → Next → Publish。此操作無需新版本和新的審查即可上線。如果 App 尚無上線版本，請將素材附加到下一版本後提交。

告知用戶在標題和搜尋結果頁籤中使用 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，編碼規則同上
一份所有檢查項目皆為 PASS 的驗證報告
海報幀及其時間碼
一份簡短的交接說明，包含來自 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 localizations placements list` 檢查現有位置。移除舊位置，然後建立新位置
渲染成功但幀畫面錯誤	使用 `npx hyperframes report` 取得視覺診斷報告，內含每幀指標。查看每個場景的 `compositions/report.json`，確認視覺元素確實如預期出現

App Store 標題影片