Communitygithub.com

film-build

以程式碼打造產品宣傳影片,製作可確定的 seek(t) 網頁(真實產品 UI、真實 OS 介面、動態文字、打字提示、游標、變形與鏡頭移動),以靜態圖片與草稿進行審查,以 60 fps 並搭配動態模糊進行渲染,且能在不更動 16:9 的情況下適配 9:16 格式。出貨專案套件(init.sh、影片引擎、渲染/同步/探測/拼接表/回歸工具)。屬於 product-film 的第 3 和第 6 階段。適用於建置、修正或渲染上市/宣傳影片的畫面,或製作其直立版本。

film-build 是什麼?

film-build 是一個針對 AI 開發者與 CLI 使用者設計的專業技能(skill),能夠以程式碼方式建構完全確定的產品宣傳影片。它提供一個輕量級引擎 `film/core.js`,支援場景定義(scene)、物件放置(put)、註冊(reg)等功能,影片基於時間參數 t 的純函數渲染,保證每次渲染結果一致。此技能支援 Windows、macOS、Linux 等作業系統,需搭配 Node.js 與 Playwright。核心工作流程包括:將核准的分鏡腳本轉為 shot() 函數、優先以靜態圖片審查、通過 QA 檢查後輸出 30 fps 草稿,最終以 60 fps 搭配動態模糊渲染 MP4。特別的是,它能透過 pk() 輔助函數與工具指令,在單一專案中同時產出 16:9 與 9:16 兩種版本,並使用 PSNR 回歸測試確保 16:9 版本不受改動。此外,內建多種輔助函數(如 typed()、keyed()、cursor()、sprite())可模擬真實打字、游標移動、角色動畫等細節,並提供探測(probe)、拼接表(sheet)、審查(review)等工具,讓開發者能高效迭代、確保影片品質。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/aqeelshamz/product-film-skills/tree/HEAD/film-build

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

影片建置

開始

sh ~/.claude/skills/film-build/kit/init.sh marketing/videos/<film>   # 若目標資料夾非空則拒絕執行
cd marketing/videos/<film> && npm i && npx playwright install chromium   # 若出現 NEXT 提示

套件內含以下檔案:

檔案說明
film/core.js引擎核心:scene({name, from, to, build, run, after})(時間以拍子計,1拍 = 秒 × 2)、put(el, {o, css})、reg(el, base)、C.W/C.H/C.FMT、C.start()
film/film.js入門範本,內含下方所有輔助函數及四個範例鏡頭(線條、提示、分割、角色卡片)。每個輔助函數的註解標示其來自哪次審核回饋。請替換鏡頭內容,保留輔助函數。
film/mock.jswindow.MOCK:真實 UI 元件的 HTML(儀表板、視窗、手機畫面),以螢幕像素為單位
film/index.html從 assets/fonts/{display,ui}.woff2 載入字型(支援本機無襯線字型作為備用)
scripts/render.mjs--sheet、--at t1,t2、--draft、--range a,b、--verify、final、--mux、--fmt 9x16、--all
scripts/sync.mjs將 timeline.json 複製到頁面中
scripts/review.py從渲染後的 MP4 進行審查:聯絡表、最快動作條、手機檢視、9:16 安全區、數據指標
tools/probe.mjscuts(每個剪接點與每個鏡頭的中點,以影片秒數為單位)或任意表達式,例如 "window.UNWARP(12.4)"
tools/sheet.py將多張靜態圖片拼貼成一張附標籤的聯絡表
tools/pack_grid.py將 4×3 的角色表(透明背景或白底)切成 12 格的條狀,用於 sprite();並輸出每個格子的大小
tools/cut_cast.py將單一列的角色輪廓圖切成獨立的靜態角色圖片
assets/characters/四個範例角色(創辦人、開發者、銷售員、學生),12 格條狀,每格 360 px
tools/same.shsave / check 功能,比較前後靜態圖片的 PSNR 回歸值

範本中的輔助函數(請直接使用,無需重新發明)

  • io(五次內外插值)用於鏡頭移動與變形;oq(五次外插值)用於入場;back 用於輕微 overshoot。
  • cam(e, s, fx, fy) 將 1920×1080 平面上的焦點 (fx, fy) 置於影格中心,並以比例 s 縮放。 camD 功能相同,但不會讓畫面超出平面邊緣(覆蓋比例,在 9:16 中至關重要)。
  • posIn(e, root) 讀取元素在移動平面內的位置(用於游標目標、游標跟隨)。
  • typed() 用於逐字顯示文字;keyed() 模擬真實鍵盤:每個字元間隔不規則、空格停頓較長、結束後游標閃爍。
  • wordsHTML() 從第一影格就以最終寬度排列每個單詞,透明直到其出現時間,確保行文字不會重新排列(「文字轉場完全不平滑」)。
  • cursor()/putCursor()/bump():真實的箭頭游標,移動時會滑行、提前到達、點擊時下沉 15%。
  • pop() 用於小型物體落地。
  • sprite(parent, src, cellW, cellH, h) / putSprite(e, t, a, z, loops) 用於繪製角色:在 a 到 z 的範圍內逐步播放其 12 個影格,並帶有輕微的呼吸效果,使其不會完全靜止。其為 <img> 元素,因此引擎會等待其載入。
  • shot(name, t0, t1, build, run) 以秒為單位包裝 scene。
  • 底部的節奏扭曲:SLOW(全域拉伸)、EV(暫停,凍結某個瞬間供閱讀)與插入;window.CUTS 和 window.UNWARP 提供影片時間,用於音效與語音定位。
  • PT / pk(a16, a9) 在單一檔案中選擇不同格式的數值。

引擎規則(確定性)

影片是 t 的純函數。任何影格無論是第一個渲染還是最後一個渲染,都必須顯示相同的結果。

  • 僅使用 2D 變形:禁止 translate3d、will-change、CSS 轉場、Math.random(應使用索引的雜湊值)。
  • 起始時隱藏的元素:使用 reg(el, {o: 0}),絕不要使用行內 opacity:0。
  • 在 after() 或 build 中測量佈局一次,絕不要在 run 內測量(因為它會讀取前一個影格)。
  • 3D 視圖:每影格使用 insertBefore(v, firstChild) 重新插入,以避免快取的光柵殘留。
  • 嵌入的 CSS 動畫(例如產品元件自帶的動畫):暫停它們並設定 animation-delay: calc(-1s * var(--t))。
  • 在第一個影格之前等待圖片和字型載入(使用 decode()、document.fonts.ready)。
  • 將產品 CSS 作用域限定在唯一的根類別下;在影片中使用唯一的類別名稱(.w 曾經造成洩漏)。
  • 使用 classList.add,絕不要使用 className =。
  • 在送出任何渲染之前,必須執行 node scripts/render.mjs --verify 並顯示 12/12。

真實感:在建立任何畫面之前先閱讀 references/realism.md

簡要說明:使用真實解析度的真實應用程式、來自品牌官網的真實標誌、具有該作業系統存在的應用程式的 OS Chrome、真實桌布、在真實啟動器網格上以真實 dp 尺寸顯示的手機(由產品自己的渲染器繪製)、比你想像中更豐富的產品 UI、每當顯示品牌標誌時必須附帶一行的指名使用聲明。

建置迴圈(審查驅動)

  1. 從核准的分鏡腳本中列出鏡頭清單,寫入 film.js,每個鏡頭一個 shot(),鏡頭間重疊以便交接。
  2. 優先製作靜態圖片。 執行 node tools/probe.mjs cuts → 在每個鏡頭中點與每個交接點渲染靜態圖片: node scripts/render.mjs --at … 然後執行 python3 tools/sheet.py review/stills/16x9 review/sheet.jpg <times>。 自行檢視聯絡表。修正。重複。(每次約 1–2 分鐘,相較於完整渲染的 25 分鐘以上。)
  3. 在送出任何審查版本前進行 QA 檢查: 以 ≤ 1.5 秒的間隔逐步播放影片,並檢查每個交接點(以 10–15 fps 的聯絡表檢視每個轉場)。逐行檢查 references/qa.md:重疊、裁剪、空白影格、閱讀時間、文字平滑度、打字效果、標誌注意事項、OS 真實感、手機尺寸。
  4. 將靜態圖片(聯絡表)發送給擁有者進行初步檢視。等待。
  5. 草稿: 執行 node scripts/render.mjs --draft(30 fps,約 4 分鐘),python3 scripts/review.py 1 --draft,檢視條狀圖。將草稿 MP4 發送出去。明確說明這是 30 fps 草稿,沒有動態模糊(看起來會比最終成品更卡)。
  6. 當收到「渲染最終版」指示時: 背景執行 node scripts/render.mjs(60 fps,動態模糊;60 秒的影片約需 25–35 分鐘)。 渲染期間絕不要編輯 film.js:如果需要繼續工作,請先複製專案。
  7. 在每個核准的回合之後提交影片程式碼與時間軸。

節奏

最初的剪輯幾乎總是太快。螢幕上的文字大約需要每個單詞 0.3 秒 + 完全顯示後 1 秒(絕不低於 1.5 秒)。建議優先使用扭曲功能(SLOW 1.1–1.25,EV 在文字行上暫停),而非重新調整每個鏡頭的時間。每次調整節奏後,重新執行 probe.mjs cuts,因為音效和語音位置會改變。

9:16:閱讀 references/formats.md

使用 pk() 在單一檔案中重新構圖同一部影片;使用 tools/same.sh 證明 16:9 版本未經更動(所有靜態圖片的 PSNR = inf);執行 --verify --fmt 9x16;為擁有者製作靜態圖片聯絡表;然後背景執行 --fmt 9x16 最終渲染,接著執行 --mux --fmt 9x16。

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

film-sound

Add sound to a finished product-film picture with real recorded sound effects (CC0 packs such as Kenney's) placed only on real on-screen events, decide with the owner whether there's a music bed, mix to -14 LUFS and mux into the renders without re-rendering. Stage 4 of product-film. Use when a film's picture is approved and needs sound effects or music, or when the owner says the sounds feel fake, synthetic or "AI slop".

film-storyboard

Write the story of a product film as beats (what the viewer sees, the words on screen, the voice, the sound, why the beat exists, and where each claim is proven) and send it to the owner as a one-page storyboard with frames for review, with 2–4 directions when the story is open. Stage 2 of product-film, and the review format reused for the voiceover. Use when planning a launch/promo film's story, shot list, or script, or when the owner says "give me a storyboard", "give me directions", "I'll review and decide".

film-voiceover

Write, review, test and record the voiceover for a product film after its picture is approved, as a script on a storyboard of the film's real frames, with directions to choose from, an eyes-closed coherence check, a pronunciation test for the product name, TTS recording per section (Fish Audio), phrase placement on the film's timeline, mixing and muxing. Stage 5 of product-film. Use when a launch/promo film needs narration, or the owner says the voiceover sounds like AI, doesn't match the frames, or mispronounces the name.

product-film

Make a product launch / promo / explainer film that sells and does not look or sound AI-made, through review gates the owner signs off one at a time. Study a reference video for its grammar (never copy it), then storyboard, build the film in code, add sound, write and record the voiceover, and deliver 16:9 and 9:16. Use when someone wants a launch video, promo, product film, explainer, ad, "a video like this one" for their product, or says the last video looked like "AI slop" or "vibe coded". Entry point for the film-* skills (film-reference-study, film-storyboard, film-build, film-sound, film-voiceover).

相關技能