示範到宣傳短片：用程式碼做卡點直式短片

Kinetix：從程式碼生成 Reels

Kinetix 存在於一個倉庫中（在 PATH 上找到 kinetix、$KINETIX_HOME，或一個包含 runtime/kinetix.js 的 kinetix/ 檢出目錄）。 以下所有指令都是 kinetix <cmd>；先執行 kinetix doctor，如果缺少組件則執行 ./setup.sh。

模型：每一幀都是時間的純函數。 一個 Reel 是 index.html，包含時間軸上的場景； 配樂由 music.py 在相同的節拍網格上構建，因此剪輯、震動和重拍能同步落地。

1. 首先收集真實素材

• 故事來自產品自身的用語。 閱讀其 README、網站文案和應用程式字串，並引用它們。切勿編造統計數字、使用者、獎項或速度。
• 展示真實的內容。 使用應用程式截圖、螢幕錄影，或使用 Playwright 以 2× DPI 捕獲的即時網頁。如果捕獲會命中即時後端，則在瀏覽器中模擬 API (page.route)，而不是建立真實記錄。將模擬或演示素材標記為此類。
• 一次選定數字。 如果來源不一致（1.2 秒 vs 1.5 秒），則一致地使用一個值，並在交接中說明是哪個。
• 語音是可選的。 對於語音台詞，使用使用者擁有金鑰的 TTS API（印度語言使用 tools/tts_sarvam.py），然後執行 kinetix captions。

2. 在網格上規劃

在 150 bpm 下，一個節拍是 0.4 秒，一個小節是 1.6 秒。每個章節邊界和每個大重拍都落在節拍上。一個經過驗證的 50–60 秒結構：

章節	小節數	任務
冷開場	3	2 秒內的 relatable 鉤子：POV + 痛苦點
鋪墊	6–7	用小節剪輯逐步升級，然後是一個 riser
間隙	¼	0.4 秒的近乎靜音（"直到現在…"）
重拍 1	8	Logo 猛擊，然後是產品流程，每個動作一個節拍
半速	4–5	轉折或深度，經過濾波且更安靜
重拍 2	8–10	快速炫耀：素材、真實統計數據、證明
結尾	3	Logo、標語、網址、淡出

文字必須可讀。 快速進入，然後保持：標籤約 0.8 秒，句子每個單詞約 0.3 秒。連續文字每隔一個節拍出現一次。只有非文字重音可以每個節拍都出現。

3. 建立 Reel

kinetix new my-reel            # 垂直；加上 --landscape 可設為 1920x1080

my-reel/index.html 使用執行環境（references/runtime.md）：

const K = Kinetix.init({ width: 1080, height: 1920, bpm: 150, build: [[3.2, 9.2]], drops: [[9.6, 16]], glitches: [9.6], fonts: [...] });
K.scene(9.6, 12.8, `<div class="c big t" style="left:540px;top:800px;font-size:230px">BRAND</div>`,
  (lt, q) => K.slam(q(".t"), lt, 0, { from: 3 }));
K.start({ dur: 19.2 }).then(({ timeline }) => { window.__timelines["main"] = timeline; });  // 保持此字面量不變

場景模式（手機邊框、全息圖素材面板、統計數據猛擊、聊天氣泡、計數器、打字效果）位於 references/recipes.md。 保持品牌風格：從產品中提取顏色、字體和 Logo，並通過 kinetix.css 中的 :root 變數進行主題化。

4. 建立配樂（references/music.md）

• 背景音樂： kinetix music gen "<類型, 樂器, 情緒>" --bpm 150 --seconds 60 -o my-reel/assets/bed.wav。MusicGen 遵循提示中的 BPM，工具會將音訊時間拉伸到精確的網格並寫入 bed.json。如果沒有 GPU 或 MusicGen，Mix(bpm=150, seconds=DUR) 會建立一個純合成混音。
• music.py： m = Mix("assets/bed.wav", seconds=DUR)，然後：
  • 按照與場景相同的時間放置重拍：m.add(t, h.impact())、m.drums(...)、m.sfx("impact/...")
  • 塑造編曲：m.lowpass([(t, hz), ...])、m.bed_level(...)、m.gap(14.0, 14.4)
  • 然後執行 kinetix mix my-reel。
• 檢查動態（你無法聆聽，所以用測量的）。每個章節的 RMS 應從鋪墊上升到重拍，在半速時下降，並在重拍時達到峰值。如果鋪墊比重拍還大聲，則調低鋪墊的合成音軌層。同時渲染一個頻譜圖（ffmpeg ... showspectrumpic）並查看它。
• 語音： 混合後，使用 Whisper 確認它們在混合片段中是可聽見的。

5. 字幕（可選，需要語音）

captions-lines.json 包含 [{"clip": "assets/line1.wav", "at": 1.62, "text": "exact script", "y": 600}]。然後執行 kinetix captions my-reel。Whisper 以英文模式運行，並將腳本作為提示，因此 Hinglish 和其他羅馬化台詞能保持其拼寫。每個台詞會建立一個頁面。

6. 驗證：先看，再檢查

1. kinetix snap my-reel 1.5,4,9,...，每個場景一次。開啟聯絡表並實際查看。空白幀表示 JS 錯誤或未註冊的時間軸。
2. kinetix check my-reel 每 ½ 秒取樣一次，且必須以 0 個錯誤 結束。
   • 修復真正的問題：文字溢出邊框、重疊、隱藏文字、對比度。
   • 僅標記有意的疊加，絕不標記真實問題：對於文件上的印章使用 data-layout-allow-overlap，對於故意放在精靈之上的文字使用 data-layout-allow-occlusion，對於邊框內的裁剪截圖使用 data-layout-allow-overflow，對於裝飾性背景或巨大的淡出表情符號使用 data-layout-ignore。
   • 在聲稱 "修正" 是可見的之前，比較修正前後的幀。有些發現是檢查器的誤報。

7. 特效與渲染

kinetix fx leak --hue 200 -o overlays/leak-cyan.mov        # 色相：0 琥珀色，70 粉色，200 青色，290 萊姆色
kinetix fx stinger --colors "#c8ff3d,#5a45c9" -o overlays/stinger.mov
kinetix render my-reel -o out.mp4 --overlay overlays/[email protected]:0.8 --overlay overlays/[email protected] --poster 18.3

• Leaks： leak-* 檔案以「濾色」模式疊加為光效，因此文字保持可讀。在重拍前約 0.4 秒開始 leak，使其在重拍時達到峰值，且不要讓 leak 在 Logo 猛擊時達到峰值。
• Stingers： 在剪輯前約 0.3 秒開始，使面板能覆蓋剪輯。
• 海報幀： --poster 將最佳靜止幀燒錄為第 0 幀，這將作為 X、YouTube、Slack 和 Discord 上的縮圖。選擇 Logo 卡片或關鍵畫面，絕不要選擇動畫中間或閃爍的幀。
• 最終檢查： 從最終 mp4 中提取幀（第 0 幀、每個疊加峰值、每個素材場景）並查看它們。

常見陷阱（全部真實發生過）

• 橋接函數返回 { timeline }，而不是 timeline。 GSAP 時間軸是一個 thenable，因此如果從非同步函數中直接返回它，會導致永遠掛起，且每一幀都渲染為空白。
• 顯示字體上的高亮框需要 line-height: 1.12（已在 kinetix.css 中），否則字形會突出，且 check 會標記 text_box_overflow。
• 素材必須是 <video muted data-start data-duration [data-media-start]>，放置在非時間包裝器中，絕不能是 JPG 序列。動畫應用於包裝器，而不是影片本身。
• 圖片切換（畫面 A → B）使用 KinetixBridge.stackSet(img, src)，它會預先解碼變體。在渲染時設定 src 會捕獲未解碼的幀。
• 每個命名字體都需要 @font-face。 對於系統表情符號字體，宣告 src: local("Noto Color Emoji")。
• MusicGen 背景音樂： librosa 的 beat_track 會誤讀 phonk 和 club 節奏（它稱 150 bpm 為 "121" 和 "199"），這就是為什麼 hypebeat 使用起始自相關並將拉伸限制在 ±12%。musicgen-medium 需要約 8 GB 的可用 RAM 才能載入；small 是預設值。
• 字幕： 將所有台詞合併到一個 createTikTokStyleCaptions 呼叫中會將一個台詞的最後一個單詞合併到下一個，因此按台詞分頁（執行環境會這樣做）。
• Remotion： 使用 --gl=swangle（軟體 GL 可在任何地方運作）渲染，並渲染為帶有 Alpha 的 ProRes 4444。ffmpeg 的 VP9 解碼器會丟棄 Alpha。
• 許可證：
  • MusicGen 輸出是 CC-BY-NC，適用於示範和個人頻道，不適用於付費工作。
  • Remotion 對個人和不超過 3 人的公司免費。
  • 捆綁的 SFX 是 CC0。

交接

告訴使用者：

• mp4 的位置
• 內容是什麼，以簡短的逐拍列表形式
• 你驗證了什麼以及如何驗證（聯絡表、檢查結果、響度）
• 你做出的任何數字或主張選擇
• 你無法驗證的內容（你無法聽到；請他們聆聽）

提供發布選項，但未經同意不要發布。