動態宣傳影片協定
概述
此技能渲染一個 動態、廣告等級的真實產品宣傳影片,而非螢幕錄製或模擬畫面。它驅動實際應用程式在無頭瀏覽器中操作示範環境,捕捉每個畫面的乾淨靜態截圖,並在其上合成運動設計剪輯:動態文字排版、電影推近鏡頭、追蹤縮放的聚光燈高亮、手機螢幕框、節奏性場景切換以及背景音樂。輸出為 16:9 主版本和 9:16 直立版本。
它是 launch-feature 的渲染端對應:launch-feature 撰寫 video-script.md(以散文形式呈現的腳本/節拍);motion-promo 則將節拍清單轉化為完成且配樂的影片。兩者同時運行時,可串聯使用 — launch-feature 腳本 → motion-promo 節拍。
為何選擇 HyperFrames(HTML→MP4)而非螢幕錄製: 確定性、可重複執行、品牌可控,且避免了捕捉即時導航的失敗模式(請參閱規則)。應用程式僅用於產生 靜態截圖 + 設計權杖;所有動畫皆經過精心編排。
使用時機
- 登陸頁面/銷售頁面需要產品示範或主視覺影片。
- 發布新功能,且您需要渲染完成的影片,而不只是腳本。
- 您擁有包含真實資料的示範/沙箱租戶。
請勿用於:內部操作說明(原始螢幕錄製成本更低),或沒有可運行示範環境的應用程式。
前置條件與秘密
不需要 API 金鑰 / 秘密。 HyperFrames render 是無金鑰的(本地 HTML→MP4),字型(Google Fonts)和預設音樂(incompetech)皆為公開 URL。唯一的憑證是 目標應用程式的示範登入資訊,它位於目標儲存庫的 promo.config.mjs 中 — 絕不儲存在此技能中。驗證是一個可插拔的配方:authInject() 返回要注入的值(token 到 localStorage、cookie、API 金鑰、多步驟租戶選擇),或 authFlow(page) 驅動互動式登入 UI(Azure AD / Entra、Okta、Google SSO),引擎會快照該會話(localStorage + sessionStorage + cookies,包含 HttpOnly)。SSO 憑證來自環境變數,而非檔案。無頭瀏覽器無法通過互動式 MFA — 請使用免 MFA 的示範帳戶(條件存取例外)或應用程式密碼。
系統依賴項(您需自行安裝 — 技能無法安裝): Node 20+、系統 Chrome(google-chrome/Chromium)、ffmpeg + ffprobe。需要網路出口以獲取字型/音樂。
自動/按需依賴項: hyperframes 透過 npx 按需獲取(無需預先安裝)。puppeteer-core 是透過 scaffold 建立的 npm 依賴項 — 它使用系統 Chrome,且不會下載 Chromium。
設定: 將 templates/ scaffold 到 video/<slug>/(包含 hyperframes.json;meta.json 由 compose-gen 產生),將 gitignore 重新命名為 .gitignore,然後執行 npm install 和 npm run preflight(驗證 Chrome、ffmpeg/ffprobe 和 puppeteer-core;若缺少任一項則會大聲失敗)。逐步執行管線,或執行 npm run build。
- 目標應用程式的可運行示範/沙箱。
輸入
所有專案特定的內容都位於目標儲存庫中,絕不在這個技能中:
promo.config.mjs— 合約(請參閱templates/promo.config.example.mjs)。 應用程式 URL / 如何提供服務、驗證配方、示範帳戶/租戶、輸出路徑和音樂偏好。設計權杖會自動提取(步驟 2),但可在這裡覆寫。beats.json— 有序的鏡頭清單(請參閱templates/beats.schema.json)。 每個節拍 = 一個畫面(路由或捕獲的靜態截圖)+ 可選的高亮目標 + 說明文案 + 視口(桌面/行動裝置)。
從 templates/ 將兩者 scaffold 到目標儲存庫中的 video/<slug>/。
協定
在目標儲存庫中的 video/<slug>/ 目錄內工作。每個步驟都有其驗證。
0. 修復示範資料(請先執行此步驟 — 這決定了影片的成敗)
示範/沙箱資料通常對於當前週期而言是過時的或歸零的(未支付的當月發票、空的漏斗),這在 「自動駕駛」 旁邊會顯示為 「R$0 營收」 — 與訊息背道而馳。在捕獲之前,撰寫一個冪等、基於當前日期的種子,為每個節拍提供健康的數字(請參閱規則 → 示範資料歸零)。透過查詢每個節拍將顯示的指標來驗證。
1. 在允許 CORS 的來源上,針對示範 API 提供應用程式服務
建置/提供對應於示範 API 的應用程式服務。提供服務的來源必須在 API 的 CORS 允許清單中,否則每個資料請求都會被阻擋,畫面會渲染成空白(請參閱規則 → CORS 來源)。探查 API 的允許清單,並在允許的埠上提供服務。驗證:從該來源對深層路由發出請求應返回 200,且已驗證的 /api/... 請求應返回 2xx。
2. 提取目標應用程式的設計系統
針對正在提供服務且已驗證的應用程式執行 templates/engine/extract-design.mjs。它會取樣計算後的樣式(頁面背景、按鈕/連結的主要/強調色、標題+等寬字型、圓角半徑)→ design.tokens.json。這些權杖會以 CSS 變數的形式餵入合成,使動態覆蓋層、強調色和字型自動符合應用程式的品牌。請檢閱並在 promo.config 中覆寫取樣錯誤的權杖。
3. 為每個節拍捕獲乾淨的靜態截圖
執行 templates/engine/capture.mjs。它會進行驗證(透過設定的 authInject 配方),導航每個節拍的路由至其視口,等待真實資料載入(不僅是 network-idle — 請參閱規則),然後截圖至 assets/<beat>.png。驗證每個靜態截圖都顯示了已載入的內容(大小 > ~10 KB,抽查目標元素是否存在)。
4. 定義節拍 + 產生合成
填寫 beats.json(路由/靜態截圖、高亮 {x,y,w,h,label} 於靜態截圖像素空間中 — 或是 {selector,label,padding?},由 capture.mjs 自動測量,並優於手動調整的座標、說明 {kicker,headline,sub}、視口、持續時間)。執行 templates/engine/compose-gen.mjs → index.html 來自 templates/composition.html,注入權杖和節拍。保持簡潔有力:每個節拍 3–5 秒、硬切、每個節拍一個想法。
5. 獲取免費音樂曲目
執行 templates/engine/fetch-music.mjs → assets/music.mp3。預設來源是 CC-BY(incompetech);CC-BY 需要署名(記錄在 LP 描述中)。如有可用的專案提供/CC0 曲目,則優先使用。
6. 渲染
npx hyperframes render → 無聲 MP4。先執行 hyperframes lint/inspect;將畫布外的裝飾/退出動畫溢出視為干擾,真正的文字裁剪則需要修正。
7. 檢查影格 + 修復高亮對齊
提取每個推近鏡頭開始和結束時的影格並仔細檢查。第一大缺陷:聚光燈高亮在縮放過程中偏離目標 — 因為高亮框必須是縮放容器的子元素(請參閱規則 → 高亮追蹤)。同時驗證:沒有空白/載入中畫面,行動裝置畫面整齊地放置在手機框中,文案清晰可讀。
8. 混入音樂
執行 templates/engine/mux.mjs → 最終配樂 MP4(loudnorm、淡入/淡出、-shortest)。驗證輸出包含音訊串流,且與影片長度匹配。
9. 產生 9:16 直立版本
mux.mjs --reframe 會產生一個 1080×1920 的裁剪版本。請勿中心裁剪(這會切掉底部錨定的說明)— 使用保留整個影格的模糊信箱模式;行動裝置的節拍已經居中顯示。
規則(得之不易 — 請勿重蹈覆轍)
- 高亮追蹤。 覆蓋在螢幕上的聚光燈/高亮矩形,在推近鏡頭時必須是同一獲得
scale轉換之元素的子元素,並位於靜態截圖的像素座標空間中。作為同層級元素,它會保持在原位,而影像則會縮放,導致在鏡頭中偏離目標。 - 示範資料歸零。 當前週期通常是未付或空的。使用一個冪等(確定性 ID,先刪除後插入)且相對於
current_date的種子來修復它,使其能自動修復每個週期。 - CORS 來源。 本地提供服務的建置呼叫已部署的示範 API 是跨來源的。請在 API 允許清單中的來源上提供服務(探查它)— 絕不停用瀏覽器網頁安全性來繞過此問題。
- 等待真實資料。
networkidle2可能在應用程式的資料請求到達之前就解析完成 → 您會捕獲到載入中畫面。在截圖之前,需額外等待成功的/api/...回應(或目標內容選擇器)。 - HyperFrames 優於即時捕獲。 CDP screencast 會在頁面視覺上靜止時停止發送影格,並以低於標稱的 fps 運行;在 HTML (GSAP) 中編寫則可避免這兩者。如果您必須錄製即時內容,請讓游標抖動並以有效 fps 進行編碼。
- 音樂授權。 CC-BY(incompetech/Kevin MacLeod)需要在 LP 描述中加入署名;CC0(Pixabay 等)則不需要。切勿在已發布的頁面上使用未經授權的抓取剪輯。
- 如果片段具有可變 fps,請使用濾鏡而非分離器進行連接 — 分離器會無聲地丟棄影格。
設計系統提取(品牌無關)
合成是品牌中立的;extract-design.mjs 會從目標應用程式本身填入其 CSS 變數:--bg(頁面背景)、--accent(主要/連結顏色)、--fg(標題顏色)、--font-hero/--font-mono(計算後的字型)、--radius。這使得一個技能能夠為任何應用程式產生符合品牌的宣傳影片,而無需手動挑選權杖。務必檢查取樣的權杖 — 低對比或臨時顏色偶爾會取樣錯誤;請在 promo.config.design 中覆寫。
錯誤
- 應用程式無法在無頭模式下驗證 → 設定的
authInject配方有誤;請先驗證 token 在第一次導航之前已確實存入localStorage/cookie。 - 畫面渲染為空白 → 遺漏了 CORS 來源(步驟 1)或等待資料(規則)。
- 渲染超出畫布錯誤 → 真正的文字裁剪需要較小的字型/換行;裝飾/退出溢出是干擾。
- 高亮對齊不正確 → 它不是縮放容器的子元素(規則)。
與行銷人員角色的協作
使用行銷人員角色處理文案:標題鉤、主要標題和每個節拍的價值框架應遵循專案語調(launch-feature 的 voice.md / marketer-hooks.md,如存在)。保持螢幕上的文案為一個標題鉤 + 一個短標題 + 每節拍一行副標題。