應用程式宣傳影片 (Remotion + 真實 iPhone + 真實 UI)
此方法已在四個小型 iOS 應用程式 (Unblock, Talljakt, Georama 和 Quiz) 上開發，其設計方式使其可以為任何應用程式重複使用。所有特定於應用程式的內容都位於 examples/ 中。可重複使用的部分位於 templates/ 中。詳細技術、陷阱和可調變數位於 references/techniques.md 中。開始建構之前請先閱讀該文件。
語言： 使用使用者使用的語言與其交談。如果他們開始使用挪威語，請用挪威語回答。影片中文字的語言是另一個獨立的選擇（下面的問題 3）。
0. 先進行簡短訪談
一起提出這些問題 (AskUserQuestion 或一次發送一條訊息)。建議預設值，讓使用者只需回答「預設值」：
- 長度： 20–60 秒。預設約 30 秒。
- 格式： 9:16 垂直 1080×1920。預設 60 fps。也可以是 1:1 或 16:9？
- 螢幕文字的語言。
- 用途： 私人分享、社交媒體（Reels/TikTok，安全區域）或 App Store 預覽。App Store 預覽必須是真實錄製，最長 30 秒，不能使用虛構的 3D 效果，因此此方法不太適合。
- UI 從螢幕中浮出的程度： 無（低調：僅使用真實錄製、焦點縮放和應用程式自身的轉場效果，參見
examples/kjop）、微妙（一兩個英雄時刻）、中等 或 完全（所有元素都浮出）。預設是 微妙到中等；無 適合普通的日常應用程式（列表、表單、設定）。完全浮出適合其組成部分為自然物理物體的應用程式（遊戲拼塊）；對於普通應用程式（列表、表單、卡片），只浮出 1–3 個關鍵元素，其餘保持在螢幕上。 - 創意自由度： 代理程式是否應該自行構思概念？
- 音樂： 程式碼生成（預設，無需許可證）或使用他們自己的曲目？為每個應用程式賦予其獨特的聲音調色板，這樣兩個影片聽起來就不會一樣（參見
references/techniques.md#sound）。 - 要展示哪些功能（3–5 個），以及應用程式的「英雄」元素或時刻是什麼？
- 結尾： 兩個經過驗證的選項；根據應用程式選擇，如果不清楚則詢問。(a) 使用應用程式自身元素構建的標誌組合（Unblock：標誌由 3D 拼塊組合而成，黃銅拼塊最後落下）。(b) 手機上的主畫面，上方有標語，圖示 + 名稱是最後一行（Talljakt：「六個數字。 / 一個目標。 / [圖示] Talljakt。」）。
- 手機顏色： 宇宙橙、深海藍或銀色。選擇與應用程式強調色相匹配的顏色。
答案主要用於引導概念、從螢幕浮出的程度、節奏（bpm）和顏色。
0a. 預檢：檢查工具鏈
在建構任何東西之前，檢查已安裝的內容並用一個簡短的列表報告。主動提供安裝缺失的項目，但僅在使用者同意後才安裝（這些是系統變更）。跳過任何已存在的項目。
| 工具 | 檢查方式 | 安裝方式 |
|---|---|---|
| Xcode + 命令列工具 | xcodebuild -version, xcode-select -p | App Store (Xcode)，然後 xcode-select --install |
| 帶有 iPhone 17 Pro 設備類型的 iOS 模擬器執行時 | xcrun simctl list runtimes, xcrun simctl list devicetypes | grep "iPhone 17 Pro" | Xcode → 設定 → 元件，或 xcodebuild -downloadPlatform iOS |
| baguette | baguette --version | brew install baguette |
| Blender | ls /Applications/Blender.app | brew install --cask blender |
| Node 22 | node --version | nvm install 22 (或 brew install node@22) |
| ffmpeg | ffmpeg -version | brew install ffmpeg |
| Python 3 + Pillow | python3 -c "import PIL" | python3 -m pip install --user pillow |
| Homebrew (用於上述工具) | brew --version | 來自 brew.sh 的官方安裝腳本，由使用者執行 |
然後設定 Remotion 專案 (references/techniques.md#setup) 並轉換一次 iPhone 模型（下面的步驟 6）。兩者都是專案本地的，除了在儲存庫中工作外，不需要額外權限。
0b. 交付資料夾（每台 Mac 一次）
完成的影片會交付到機器上的一個固定資料夾，而不僅僅是專案的 out/ 目錄。該選擇會儲存在每台 Mac 的 ~/.config/app-promo/destination（一行，完整路徑）中。
- 在開始時讀取該檔案。如果存在，則直接使用該資料夾，無需詢問。
- 如果該檔案缺失，詢問一次 (AskUserQuestion)：
~/Movies/App Promos（推薦）、專案的out/資料夾、桌面或自訂路徑。建立該資料夾並將路徑寫入~/.config/app-promo/destination。 - 使用者可以隨時要求更改；更新該檔案。
1. 工作流程
- 閱讀應用程式。 README、顏色標記（搜尋
Color(、hex、主題結構體）、字型、文案。在影片中使用應用程式自身的文案，如果合適的話。 - 尋找除錯入口點 以顯示狀態而無需實際操作：啟動參數 (
--design-*)、URL scheme (myapp://design-home?state=…) 或 fixture。如果沒有，則在添加僅用於 DEBUG 的鉤子到應用程式之前詢問。 - 在專用的 iPhone 17 Pro 模擬器上建置並安裝。 螢幕截圖必須是 1206×2622 才能匹配手機模型的螢幕。參見
references/techniques.md#simulator。 3b. 對於真實螢幕錄製： 閱讀 references/recording.md。首先準備場景和點擊點，在錄製時進行短暫拍攝，不要進行 UI 檢查、建置或影片分析，並在 Remotion 之前檢查原始時序。對整個流程進行一次連續拍攝（如examples/quiz中所示）可以保持所有數字、進度條和歷史記錄的一致性。 - 為每個狀態拍攝螢幕截圖。 對於靜態/剪出序列，使用真實點擊來播放它們，並在每次點擊後截圖（參見
references/consistency.md）。對於影片，請在單獨的排練中進行該檢查，永遠不要在最終拍攝過程中。鎖定狀態列（9:41、100%、放電中或綠色充電指示器）。使用baguette describe-ui取得元素框架。 - 剪出 UI 元素 使用特定於應用程式的
tools/prep_<app>.py，該腳本使用templates/tools/prep_helpers.py：精靈圖、空白背景和一個包含矩形資訊的 JSON。在視覺上檢查每一組（在洋紅色背景上合成）。 - 轉換 iPhone 模型 從 baguette (USDZ) 使用 Blender (
templates/tools/convert_model.py) 轉換為 GLB。 - 設定 Remotion 專案，或重複使用一個：複製
templates/src/three/*、Title.tsx、brand.ts、remotion.config.ts、tools/sheet.sh和tools/prep_helpers.py。 - 編寫節拍表 (
timeline.json)，以 bpm 網格上的幀為單位（120 bpm 在 60 fps 下 = 每拍 30 幀）。圖片和聲音都讀取此檔案。 - 將場景建構為連續的「一次性拍攝」： 相機保持靜止，手機支架移動。螢幕變化由轉場效果隱藏：旋轉、應用程式自身的導航、從元素開始的縮放或擦拭、推動、翻轉、甩鏡、匹配剪輯或快轉。變化使用，每個影片最多兩次旋轉。參見
references/techniques.md#transitions。 - 使用關鍵影格的聯繫表進行迭代 (
tools/sheet.sh f1 f2 …)。查看它們。渲染完整影片（快速：約 1–2 分鐘渲染 30 秒）。 - 檢查點： 在建構其餘部分之前，向使用者展示前約 12 秒。
- 生成音軌 (
tools/<app>_audio.mjs，從範例複製）使用相同的時間軸。渲染，測量響度 (ffmpeg -af ebur128，目標 −14 到 −16 LUFS) 並為使用者開啟檔案。
12b. 一致性檢查（交付前必須進行）。 手機螢幕上的內容與螢幕外突出顯示的內容之間的不匹配看起來像 AI 生成品的偽影。瀏覽 references/consistency.md 並在每個轉場、螢幕變化和浮出效果前後 ±2 幀渲染聯繫表。
13. 分享文字： 編寫一段簡短文字，以便貼到影片分享的任何地方（格式如下）。將其複製到剪貼簿 (pbcopy) 並在回覆中以程式碼區塊顯示。不要將其儲存為檔案。
14. 交付： 將最新批准的渲染結果複製到交付資料夾 (0b)，命名為 <App> promo.mp4。覆蓋相同應用程式的先前交付內容；版本歷史記錄 (-v2, -v3 …) 保留在 out/ 中。在回覆中提供交付檔案的路徑。
分享文字格式
文字通常發佈在 Slack 中，因此使用 Slack 格式 (mrkdwn)：使用 單個星號 的粗體標題和以 "• " 開頭的項目符號（貼上的 "- " 不會成為列表）。使用影片的語言書寫。
*<App> – <2–4 個簡短句子/單詞的標語，理想情況下來自影片>。*
<一句話：應用程式是什麼，為誰或什麼而設。>
• <重點：核心操作，具體且主動>
• <重點：應用程式提供的選擇（主題、模式、區域、節奏…）>
• <重點：…>
• <重點：獎勵/分享/使其特別之處>
規則：4–5 個要點，要點末尾不要句號，直接與讀者對話，使用具體動詞，不要使用行銷陳腔濫調。從應用程式的實際使用方式開始：前 2–3 個要點具體解釋機制，然後再介紹選項和附加功能。然後描述應用程式讓您能夠做什麼，而不僅僅是影片展示的內容：將選項按要點分組（「練習國家、首都或旗幟」），以便讀者看到範圍。使用應用程式自身對事物的命名，並在程式碼中檢查每個模式的實際作用（README 會過時）。參見 examples/*/share.txt。
2. 一個行之有效的概念範本
一個英雄、一個將所有內容聯繫在一起的動作、應用程式自身的文案：
| 部分 | Unblock | 通用說明 |
|---|---|---|
| 鉤子 0–2.5 秒 | 拼塊落入漂浮在黑暗中的棋盤上，沒有手機。「卡住了。」 | 應用程式解決的問題，使用應用程式自身的元素展示，不帶手機 |
| 揭曉 | 當鏡頭拉遠時，手機圍繞棋盤自行建構 | 同一個元素原來是在應用程式內部 |
| 核心循環 | 在節拍上進行 4 步，螢幕外的計數器 | 3–4 拍內的主要動作 |
| 英雄時刻 | 英雄元素從螢幕中浮出並飛向鏡頭，黃銅閃光 | 一個大時刻（螢幕外效果，或應用程式自身最佳動畫的慢動作） |
| 回報 | 結果畫面，3D 星星跳出 | 獎勵或結果 |
| 功能（其間有變化的轉場） | 關卡選擇器、每日卡片、分數 | 2–3 個功能，每個有一個突出顯示的元素 |
| 片尾 | 由 3D 拼塊建構的標誌，標語 | 使用應用程式元素構建的標誌組合，或帶有標語+名稱的主畫面 |
如果應用程式有一個真正出色的原生動畫（Quiz："Show answer" 按鈕撕裂成 Wrong/Right），就將它作為英雄：近距離放大，使用速度曲線減慢，賦予它自己的音效，並且不要加說明文字。
2b. 來自優質應用程式宣傳片的視覺手法
好的參考使用螢幕和內容，而不僅僅是佈局。每個影片至少規劃 3–4 個：
- 裁切螢幕： 靠近到只顯示一部分（一個計時器、一排按鈕、一個方程式）。手機被畫面邊緣裁切。使用
focus姿勢。 - 手機旁或前方的內容卡片： 來自應用程式的真實卡片或海報（分享卡、結果卡、建議）作為扁平、略微旋轉的平面，位於手機後方或前方。
- 同時顯示多張內容卡片： 展開 3–5 個變體（頁面、解決方案、海報）。
- 多台裝置： 當故事涉及分享或「對每個人都一樣」時，並排放置兩台手機，上方有名稱標籤。如果應用程式支援，使用 Phone + Watch/iPad（baguette 有 iPad 和 Watch 模型）。
- 應用程式的元素作為裝飾： 真實的拼塊、按鈕、晶片或圖示在背景中飄移（模糊 = 遠處），或放大成手機上方的排版。一個主題化的動機（脈搏線、蠟筆筆觸、方格紙）。
- 應用程式所產出的東西，作為物件： 印刷品、海報、卡片，理想情況下不帶手機。
- 語音或思想泡泡 用於在手機外部發生的事情（Quiz：口頭答案在卡片旁邊彈出，然後落在 Right/Wrong 按鈕上以「按下」它）。
2c. 文字與構圖
- 頂部的大尺寸居中標題承載資訊： 每行 2–4 個單詞，最多兩行，第二行或關鍵詞使用強調色。
- 底部的小尺寸說明文字，謹慎使用，僅在標題需要澄清時使用（在 30 秒影片中出現 2–3 次）。它們必須可讀：至少約 50 像素，放在帶有淺色背景和陰影的晶片中（非鬆散文字），放置在低處以免與手機畫格交叉，至少顯示 2 秒。
- 只宣稱應用程式實際能做到的事。 在撰寫某個功能之前，先檢查它的實際作用。
- 支援全螢幕文字卡片： 一個彩色表面（應用程式的主色）帶有大尺寸居中的兩行標題，從最後聚焦的元素擦拭進入，並通過滑向下一場景離開。作為結尾前的喘息或橋樑，最好是一個挑戰觀眾的問題（「你能及時找到它嗎？」？）。不要直接從激烈的動作跳到結束畫面。參見
examples/talljakt和examples/quiz中的QuestionCard。 - 不要在角落放置固定的應用程式圖示和名稱。 只在結尾處、在標誌中或作為標語的最後一行顯示名稱。
- 保持畫面乾淨：每個場景一個想法。如果一個功能沒什麼可展示的（一個設定），把它作為說明文字或另一個場景中的短暫焦點來處理，而不是給它一個獨立的場景。避免同時出現標題 + 縮放的手機 + 一行元素 + 說明文字。
- 節奏：不要有空閒時間。 每個場景在開始後約 1 秒內必須有一個事件，並且沒有標題在靜止畫面上停留超過約 1.5 秒。重複的步驟（測驗中的問題 2–13）可以快轉。
- 將選擇展示為行動，而非文字。 如果應用程式有模式或設定，展示預設值被選中（卡片稍微抬起）、點擊替代選項（它抬起，螢幕狀態改變），然後點擊開始按鈕進入該模式。
- 互動若不夠清晰（開啟選單、選擇選項），則應在應用程式實際響應的內容上添加點擊指示器（一個圓圈按下並產生漣漪擴散）。
3. 原則
- 真實 UI 勝過重現的 UI。 使用螢幕截圖、錄製和剪出，而不是應用程式的 HTML 副本。必須更改的文字（計數器、分數）使用 PIL 以應用程式的字型繪製，並與原始版本進行驗證。
- 控制「從螢幕浮出」的程度。 它是調味料。預設是一個英雄時刻和 1–2 個浮出的功能。
- 縮放和焦點是強調的主要工具。 將鏡頭移向螢幕上在該時刻重要的部分（一個按鈕、一個結果文字、一個進行中的動畫）。相機變換應始終由螢幕上的敘事驅動。
- 保持動態： 空狀態、動畫過程、錯誤。避免只展示完美的完成狀態。
- 包羅萬象的媒體： 分享影片 (
examples/*/share.txt) 必須與視覺風格相匹配。兩個都從examples/中的範例開始，並根據應用程式進行調整。 - 避免常見的初學者錯誤： 背景音樂太響、UI 不一致、文字錯誤、對應用程式的聲明不準確、節奏緩慢、缺乏變化。仔細進行一致性檢查。
4. 調試與常見問題
- 模型不對齊： 檢查 convert_model.py 中的螢幕尺寸常數。模擬器截圖必須精確為 1206×2622。
- 音頻不同步： 檢查 timeline.json 中的時間戳。確保音軌生成腳本使用相同的節拍網格。
- 動畫卡頓： 降低 3D 場景中的多邊形數量。檢查 Blender 轉換設置。
- 文字不可讀： 使用至少 50 像素的字體大小。在截圖或 PIL 生成的文字上添加陰影或背景。
- UI 元素閃爍： 檢查 prep 腳本中的精靈圖邊界。確保背景去除蒙版是乾淨的。
有關更多細節和可調變數，請參見 references/techniques.md。
5. 範例
查看 examples/ 以獲取現有應用程式的完整工作流程：
examples/unblock/- 拼圖遊戲的宣傳影片examples/talljakt/- 數字猜謎遊戲的宣傳影片examples/georama/- 地理知識問答的宣傳影片examples/quiz/- 一般知識問答的宣傳影片examples/kjop/- 購物清單應用程式的低調宣傳影片
每個範例都包含一個 share.txt、timeline.json、prep 腳本和音軌生成器。
6. 貢獻
如果你開發了一個新的功能應用程式宣傳片，請提交一個 PR，在 examples/ 中添加一個新資料夾，並附上你的 prep 腳本、timeline.json、音軌和 share.txt。