paper-collage-film
一部拼貼電影 = 一段連續的停格動畫鏡頭旅程，穿越撕紙世界，配合音樂剪輯，最終以標題、翻頁揭開標誌和行動呼籲作結。除了照片剪裁，一切都是程式碼。assets/template/ 是一個完整的10秒影片（kaye.creatives YouTube發佈版），可直接渲染使用 — 請在此基礎上調整，而非從零開始。
使用此技能的使用者期望（詳見 references/lessons.md）
- 先看參考資料。 開啟收到的每個連結，以每秒12幀的速度擷取畫面，並閱讀相關文件。若有多個參考，找出他們最喜歡的那個。
- 從參考中學習技巧，從品牌中發掘故事。 複製動作語法，絕不複製情節（不做一一對應的映射）。
- 優先使用程式碼；僅生成照片剪裁。 除非要求，否則不生成背景、人物或AI角色，也不使用影片生成。
- 以渲染的文件而非猜測來做出選擇：標題字型 →
tools/font_sheet.sh，顏色 →tools/palette_sheet.sh；使用者以數字作答。 - 快速且可見：儘早發送節拍表、剪裁表和草稿，提供實際時間預估，使用並行代理（請參閱 references/agent_workflow.md）。
- 使用使用者的語言交談；除非要求，否則螢幕上的文字使用英文。避免全畫面閃爍（光敏感性）。
0 · 接收階段（僅詢問一次，在一則訊息中，且只問無法推斷的資訊）
- 確切的品牌/帳號拼寫和每個螢幕上的文字
- 影片長度
- 格式（見下方說明）
- 文字的語言（西里爾字母會影響字型選擇）
- 行動呼籲（CTA）：訂閱/追蹤/造訪
- 標誌檔案或文字標誌
- 音樂：合成音軌或他們自己的曲目
- 是否願意花費約 N×2 的點數在剪裁上
格式。 拼貼版面僅為 1920×1080 繪製（collage.js 和 scenes.js 使用絕對座標）。若要製作9:16的Reels但不重新規劃版面：渲染16:9的影片，然後將其全寬放置（1080×608）在一個1080×1920的頁面上，並在頂部和底部加上撕紙條帶，這些條帶上包含標題、帳號和行動呼籲。真正的垂直影片意味著需要重新放置每個座標 — 請將其視為額外時間並報價。
1 · 專案（1分鐘）
<skill>/scripts/new_project.sh <output_root> <slug> # 新品牌：關閉調色盤（使用原始紙張顏色）
<skill>/scripts/new_project.sh <output_root> <slug> --example # 重現已發佈的 kaye.creatives 影片（夜間調色盤）
cd <project> # 從專案目錄執行以下所有命令（代理：每次呼叫前加上 `cd <project> &&`）
建立 comp/、audio/score.html、tools/（包含已編譯的 extract/encode/mux/greenkey）、cutouts/、refs/、review/ 等目錄。需要 macOS（Swift、AVFoundation、afconvert）、Chrome/Brave、Node ≥ 22（NODE_BIN=/path/to/node 可強制指定；若有備用連結，則使用 export PATH="<project>/tools/bin:$PATH" 以便直接呼叫 node — tools/*.sh 會自行處理）。需要網路連線以載入 Google Fonts。
缺少的剪裁會渲染為帶標籤的灰色卡片，因此即使是在生成之前，草稿也能正常運作。範例載入的剪裁有：cam_side cam_front car helmet phone plane_front plane_side clap reel laptop headphones midi phone_gimbal cassette cloud_1..4 rocks_a/b/c tree_a/b grass_strip。
2 · 參考資料（10–15分鐘）
下載參考影片（Pinterest：解析 pin.it 連結 → 前往 pin 頁面 → 使用 v1.pinimg.com/videos/…/720w.mp4 或 /mc/720p/ H.264 URL；GIF：使用 ImageIO/Swift 分割畫面 — 不要用 ffmpeg）。使用 tools/extract ref.mp4 refs/f 12 960 0.85，然後使用 tools/sheet.mjs 生成聯繫表（標題 = 幀數/12 秒；tools/strip.sh 假設為24 fps，因此其標籤在12 fps幀上會是實際時間的一半）。仔細觀看。撰寫 refs/analysis.md，內容需包含 references/reference_san_diego.md 的標題：剪輯時機、動作曲線、調色盤十六進位碼、相似字型、必須複製的清單 — 並將每個參考中的裝置映射到 CL/CLX 裝置或標記為「新裝置」；列出需要刪除的 San Diego 裝置。使用者的參考資料會覆蓋下方 San Diego 的數值。
動作語法（San Diego 測量數據 — 請參閱 references/reference_san_diego.md）
- 所有動作採用 雙幀模式（每秒12個繪圖）：動作時間
q(t) = floor(t*12)/12，每個繪圖有1–2像素的圖層抖動。 - 在標誌出現前沒有硬剪輯：使用縮放穿越、翻頁、撕紙過場、萬花筒中的六邊形孔洞、在條帶火箭後方傾斜上移。
- 掉落：3個繪圖（邊緣進入 → 半空中 −8° → 著陸）+ 1個穩定繪圖（1.03→1）；彈出則在1–2個繪圖內完成。
- 推入細節：約1秒內指數縮放從1倍到6倍，縮放中心點線性插值到細節上。
- 萬花筒：鏡像環，不旋轉，縮放每約0.35–0.38秒加倍；重複的貼紙僅作為一個環出現。
- 標題從上方落下，使用指數淡出，持續9個繪圖，無過衝，白色紙張輪廓加上透視擠壓效果。
- 翻頁約0.42秒，帶有深色捲曲的背面 → 帶有文字標誌的撕紙條帶；另一種風格是閃爍，持續2-1-2-3-2-2幀，位於條帶內部。
3 · 故事 + 節拍表（約15分鐘內發送）
撰寫 script.md：時間 | 音樂 | 看到的畫面 | 螢幕上的文字（逐字），以120 BPM網格為基礎（節拍0.5秒，24 fps）。選擇長度：
10秒（已發佈的範例）
| 時間 | 節拍 |
|---|---|
| 0–1.0 | 拼貼頁面；▶ 掉落（0.5秒著陸）；頻道標籤；游標在0.875秒按下 ▶ |
| 1.0 | 頁面從中央撕開 → 世界1（F1賽車穿越對角線條帶，中心點1.75秒；頭盔撞擊2.0秒；標籤） |
| 2.5 | 撕紙過場 → 膠捲攝影機，加速推入鏡頭，2.9–3.4秒紙製光圈（標籤） |
| 3.5–4.5 | 萬花筒環，4.2/4.3/4.4秒飛行物，六邊形孔洞 → 桌面 |
| 4.5–5.5 | 桌面：4.5秒筆電，4.75/5.0/5.25秒裝備，提示輸入，5.15秒「generate ✦」→ 結果 |
| 5.5–5.95 | 傾斜上移，條帶火箭帶走 ▶ |
| 6.0 | 標題「KAYE / CREATIVES」（Fraunces Black Italic字型），放射狀爆發，雙翼飛機穿越 |
| 7.5–7.92 | 翻頁 → 標誌條帶 |
| 8.0–8.5 | 條帶內部的標誌閃爍 |
| 8.5–10 | SUBSCRIBE 出現，9.0秒點擊 → SUBSCRIBED ✓，9.15秒鈴鐺，緩慢推近 |
6秒片頭（每個影片前播放：無翻頁、無桌面、無行動呼籲）：0–0.5秒主要物件掉落 · 0.75–1.5秒推入細節，1.0–1.42秒光圈 · 1.5–2.5秒萬花筒，2.17/2.33秒飛行物，2.33–2.5秒孔洞 · 2.5–2.96秒火箭傾斜上移 · 3.0秒標題（3.75秒著陸）+ 爆發 · 4.5–4.92秒翻頁 · 5.0–5.5秒條帶閃爍 · 5.5–6秒最後一擊並保持。配樂：持續時間6，下降0.5，中段1.5，鋪墊2.5，結束2.95，升起3.0，結尾5.5。標誌在螢幕上停留 ≥ 1.0秒。
15秒宣傳片（模仿15秒的參考）：0–0.5秒主要物件掉落 · 0.5–2.5秒彈出 · 2.5–3.5秒推入 + 光圈 · 3.5–5.5秒萬花筒，5.33秒孔洞 · 5.5–7.5秒世界2，由飛行物引領的爆發 · 7.5–9.5秒世界3 / 產品時刻 · 9.5–10.5秒火箭 · 10.5秒標題（11.25秒著陸） · 12.5–12.92秒翻頁 · 13.0–13.5秒閃爍 · 13.5–15秒行動呼籲。
30秒：請參閱 assets/examples/kaye_30s_scenes.js 和 kaye_30s_score.html（手機廣告、勒索信字型、縮圖牆）。
為其他品牌重新換皮
| 裝置 | kaye（YouTube） | 例如咖啡店 |
|---|---|---|
| 主要物件掉落 | ▶ 播放按鈕 | 杯子 / 咖啡豆袋（使用 CL.sprite + CL.drop） |
| 彈出 | 相機道具 | 可頌、咖啡豆 |
| 撕紙 → 世界1 | F1賽車穿越條帶 | 烘焙機滾筒、農場 |
| 推入 + 光圈 | 相機鏡頭（cam_front） | 杯中的咖啡油脂（在精靈像素中測量中心點和半徑；光圈公式請參閱 api.md） |
| 萬花筒環 | 汽車、膠捲 | 咖啡豆、杯子（每個環一個貼紙） |
| 桌面 + 螢幕 | 提示 UI | 櫃檯 + 訂單票（使用 CLX.tag / CLX.ransom）— 或者刪除此部分 |
| 火箭 | 條帶上的 ▶ | 杯子在條帶形成的煙霧上 |
| 標題 / 條帶 | 頻道名稱 / kaye.creatives | 店名 / 標誌或 @帳號 |
| 行動呼籲 | SUBSCRIBE + 鈴鐺 + 游標 | 帳號 + 地址晶片（CLX.tag），營業時間星星（CLX.star） |
CLX.play、subscribe、thumb、screen 和 cursor 是YouTube專屬裝置。collage.js中的背景使用固定的剪裁名稱（CL.page：grass_strip + rocks_；CL.diag：rocks_ + cassette；CL.cloudsky：cloud_1..4）：零程式碼的換皮方式是生成相同名稱的替代物品（grass_strip = 一條撕碎的咖啡豆條帶，rocks_* = 黑白半色調的麻布袋）；否則將 pageLayers 複製到 scenes.js 中。更新 warm() 中的 cuts: 清單以包含新名稱。 |
4 · 剪裁（5分鐘，每個約2點數）
僅處理程式碼無法繪製的部分 — 提示詞範本、範例集和去背請參閱 references/cutouts.md。使用 tools/greenkey keyframes/raw/x.png cutouts/x → 輸出包含alpha通道的PNG，多物件圖層會自動分割。在彩色背景上渲染檢查表並發送。
真正的標誌檔案 → 放到 cutouts/logo.png，使用 CL.sprite 在翻頁效果的 drawUnder 內部繪製；閃爍效果的外觀 = logoBand 樣式背景 + 該精靈。對於文字標誌，設定大小為 min(190, 0.78·W / measured width)。
5 · 以程式碼編輯
comp/scenes.js 即為影片：包含 COPY（螢幕上的文字）、場景函式（pageScene、f1Scene、camScene、kalDraw、deskScene、titleBg、titleScene、endScene）、轉場（wipe、ripDraw、tearDone）、K.setup({bars}) 的推近縮放。COPY之外的文字：提示UI的「PROMPT」/標題（CLX.screen o.title）、「posters」閃爍效果中的海報字形（collage_fx.js）— 請一併檢查。API：請參閱 references/api.md；範例的實際時間和潛在問題：請參閱 references/edit_notes_10s.md。
修改時間軸的方式是重新映射時間點，而非直接編輯文字值：使用 Cut(a, b, (ctx, t) => titleScene(ctx, t + (6.0 - a)))。確保偏移量為 1/12 秒的倍數。繪製相鄰場景的區塊會一起移動（kalDraw→deskScene 透過 drawNext，titleBg→deskScene 在 71/12 之前，endScene→titleScene/titleBg）。然後更新 K.setup({bars})、配樂提示和靜止畫面的時間。超過影片時長的時間將被限制到最後一幀。
標題字型存在於4個地方：comp/index.html 中的 <link>（載入字型家族中的一種樣式）、comp/film.js 中的 fonts() 列表（否則精靈會使用備用字型渲染）、COPY.titleFont，以及 comp/font_sheet.html 中用於候選字型的 <link>。西里爾字母文字：Ultra、Fraunces、Cinzel、Bevan、Abril Fatface、Shrikhand、Chango、Rye、Lilita One、Bungee、Chewy 和 Gluten 不支援西里爾字母 — 請使用 Rubik / Rubik Spray Paint、Unbounded、Yeseva One、Lobster、Playfair Display、Russo One 作為標題和 logoBand o.font，並檢查勒索信字型晶片。
靜止畫面：使用 node tools/capture.mjs comp/index.html review/st --stills 0.5,1.75,…。
6 · 音樂
audio/score.html 在瀏覽器中合成配樂（無需樣本）：放克律動 + 紙張擬音（拍擊、撕扯、呼嘯、爆裂、打字、點擊、鈴聲）、限制器。在其第一個 <script> 中設定 window.SCORE_CONFIG {dur, drop, mid, build, vac, lift, end}，數值來自節拍表，並使用 window.SCORE_CUES = {…} 移動提示點；刪除 paper() 中影片不需要的事件行（搜尋 CUE.car、CUE.plane、CUE.type、CUE.gen、CUE.subClick、CUE.ding）— 將提示設為 null 會引發錯誤。使用 ?lv_<name>=0 靜音特定圖層。
node tools/render_audio.mjs "<project>/audio/score.html" audio/score.wav
afconvert -f m4af -d aac -b 256000 audio/score.wav audio/score.m4a
python3 tools/music_window.py audio/score.wav --hits 0.5:0.35,1.0:1.0,6.0:1.0,7.5:0.45,8.5:1.0 # 每個大節拍在其視窗中音量最大
python3 tools/music_window.py audio/score.wav --timeline 0.25
如果使用他們自己的曲目：執行 python3 tools/music_window.py track.mp3 --len <dur> → 選擇一個視窗 → 執行 python3 tools/cut_audio.py track.mp3 <start> <dur> audio/score.m4a → 根據曲目的節拍重新調整畫面的時間（網格 = 曲目的 BPM）。你無法聽到音頻 — 請透過數值驗證（請參閱 references/music_notes_10s.md）並告知使用者。
7 · 草稿 → 選擇 → 最終版本
tools/render_film.sh draft # 10秒影片約需30秒 → 產出 <slug>_draft.mp4（以及 .frames_draft）
tools/strip.sh .frames_draft review/strip.png 1
tools/font_sheet.sh "LINE1|LINE2" # 在實際處理和影片的調色盤中顯示編號的標題字型
tools/palette_sheet.sh 0.75 3.75 6.9 8.75 # 在關鍵幀上顯示 comp/grade.js 的每個調色盤（0 = 原始顏色）
tools/render_film.sh final audio/score.m4a <slug>_final.mp4 # PNG 幀，30 Mbps
在 comp/index.html 中使用 window.PALETTE = '<name>' 套用所選的調色盤（null = 原始顏色）。grade.js 會重新著色每個像素，包括照片和標誌：若要使用品牌顏色，請在角色中新增一個包含品牌十六進位碼的 PALS 條目（紅色 → 主色），並檢查產品照片和標誌是否仍然正確 — 或者設定為 null 並直接編輯 CL.C / CLX.PAL。
發送前進行品質檢查（親自查看畫面）
- 同步：畫面事件與
--hits/--timeline峰值對齊，誤差 ≤ 1 幀。 - 雙雙幀模式：幀對的哈希值僅在刻意的1幀事件處不同。
- 連接：無空白/跳動幀；除標題/標誌停留外，無靜止超過約1秒的內容。
- 無任何元素遮蓋主要物件、標題、按鈕標籤、URL（需注意游標路徑！）。
- 標籤在紙張晶片上 ≥ 36 像素，每個顯示 ≥ 0.8 秒；標題 ≥ 1.5 秒；標誌 ≥ 1.5 秒（對於 ≤ 8 秒的影片，≥ 1.0 秒）。
- 無全畫面閃爍；條帶閃爍的亮度步進方向一致。無遺留的灰色「缺少剪裁」卡片。
- 時長精確（透過 afinfo 檢查），音頻存在，峰值 ≤ −1 dBFS。
- 每個專案一次只進行一個渲染（
render_film.sh會清除其幀資料夾）。
檔案
| 需求 | 位置 |
|---|---|
| 測量到的 San Diego 語法、鏡頭、調色盤、字型 | references/reference_san_diego.md |
| CL / CLX API | references/api.md（以及 collage.js / collage_fx.js 的標頭註解） |
| 剪裁提示詞、範例集、去背說明 | references/cutouts.md |
| 配樂提示圖與測量數據 | references/music_notes_10s.md |
| 編輯注意事項與陷阱 | references/edit_notes_10s.md |
| 代理工作流程 | references/agent_workflow.md |
| 拼貼 JavaScript 引擎 | comp/collage.js |
| 拼貼效果（閃爍、海報、勒索信字型） | comp/collage_fx.js |
| 主要影片邏輯與場景 | comp/scenes.js |
| 調色盤（色調映射 LUT） | comp/grade.js |
| 頁面版面配置定義 | comp/collage.js |
| 影片渲染腳本 | tools/render_film.sh |
| 字型選擇表生成器 | tools/font_sheet.sh |
| 調色盤選擇表生成器 | tools/palette_sheet.sh |
| 從網頁捕捉靜止畫面 | tools/capture.mjs |
| 音頻渲染 | tools/render_audio.mjs |
| 音頻裁切 | tools/cut_audio.py |
| 音頻窗口分析 | tools/music_window.py |
| 綠幕去背 | tools/greenkey |
| 生成聯繫表 | tools/sheet.mjs |
| 生成條帶圖 | tools/strip.sh |
| 參考資料分析範本 | references/reference_san_diego.md |
| 剪裁提示詞與範例 | references/cutouts.md |
| 配樂提示點 | references/music_notes_10s.md |
| 編輯注意事項 | references/edit_notes_10s.md |
| 代理工作流程 | references/agent_workflow.md |
| 10秒範例場景 | assets/examples/kaye_10s_scenes.js |
| 10秒範例配樂 | assets/examples/kaye_10s_score.html |
| 30秒範例場景 | assets/examples/kaye_30s_scenes.js |
| 30秒範例配樂 | assets/examples/kaye_30s_score.html |
| 10秒範例影片 | assets/examples/kaye_creatives_10s.mp4 |
| 30秒範例影片 | assets/examples/kaye_creatives_30s.mp4 |