Flutter 展示短片工坊 是做什麼的?
為 Flutter 應用程式建立一支短暫循環的宣傳短片,作為獨立的 macOS Flutter 應用程式置於
<flutter app>/demo 中,逐格離線渲染後進行編碼。短片會使用應用程式的真實畫面、美術素材、字型與內容,並在 flutter_scene (基於 Metal 的 Flutter GPU) 上疊加 3D 圖層、使用 2D 粒子與標題套件,並配合音樂進行剪輯。
以下路徑均相對於此技能的資料夾(即包含此 SKILL.md 的資料夾)。在 Claude Code 中,該資料夾為 ${CLAUDE_SKILL_DIR}。
基本規則
- 絕不修改原始應用程式。 將需要的內容(美術素材、字型、螢幕截圖、內容資料、主題顏色)複製到
demo/中。Scaffold 只會將demo/**加入上層套件的分析器排除清單。 - 每個影格都是時間
t的純函數。 影格之間無狀態、不使用Random()、無時鐘、無模擬:採用封閉形式的運動與種子隨機。這是實現拖曳、區塊匯出、動態模糊與無縫循環的基礎。在撰寫鏡頭前,請先閱讀 references/kit.md。 - 遵循專案的語音規則(AGENTS.md、CLAUDE.md 或類似檔案):應用程式從不使用的詞彙、產品如何自稱、語調。
- 建置前需取得同意。 與使用者訪談,然後撰寫一份他們批准的腳本。
- 僅限 macOS。 需要安裝了 macOS 桌面支援的 Flutter、ffmpeg(使用
brew install ffmpeg安裝),以及安裝了 Pillow(用於聯絡表)和 numpy(用於音訊分析)的 Python 3。
工作流程
1. 訪談
在開始前先提問,並為每個項目提供預設值,以便使用者能快速回答:
- 長度與循環(預設 30 秒,無縫循環)、格式(橫向 1920x1080 與直向 1080x1920,直向針對 Reels、TikTok 和 Shorts 設計),60 fps。
- 配樂:一個檔案(附歌詞?)或無配樂,以及版權歸屬。
- 訊息:要展示的 3–5 個重點、呼籲行動(網址、商店徽章)、要宣稱的內容(免費?評分?數量?)。
- 外觀與風格:誇張程度、應用程式的品牌、任何參考資料。
- 真實畫面:選取哪些畫面,是否可以執行應用程式來擷取它們(測試帳號、預置資料)?是否也需要虛擬的氛圍畫面?
- 螢幕文字:僅關鍵字(預設)或完整標題、產品名稱的拼寫、要避免的詞語。
- 特殊事項:彩蛋、角色、絕對不能顯示的內容。
2. 研究應用程式
閱讀應用程式的主題(顏色、字型)、資源(標誌、角色、圖示)、內容(真實名稱、數字、要顯示的資料)及其主要畫面。記錄其獨特之處。規劃並擷取螢幕截圖,或請使用者提供(請參閱 references/craft.md 中的「真實螢幕截圖」部分)。
3. 分析配樂
python3 scripts/analyze_audio.py <音軌>
將其節奏、拍點相位、段落與人聲線條轉換為具名提示點,如 references/audio-sync.md 所述。如果沒有配樂,仍需選定一個節奏並在其格線上進行剪輯。
4. 撰寫腳本
製作一個包含時間的表格,為每個鏡頭記錄:音樂或歌詞、橫向畫面、直向畫面與螢幕文字(模板請見 references/craft.md)。標記出鉤子、節奏變換點、結尾卡與循環接縫。獲得使用者批准,並反覆修改直到他們同意。
5. 建立專案
zsh scripts/scaffold.sh <flutter 應用程式目錄>
使用此技能 scripts/ 資料夾的完整路徑來執行;它可以從任何目錄執行。它會:
- 在
<app>/demo下使用flutter create --platforms macos建立專案; - 新增 flutter_scene、vector_math 與 audioplayers 依賴,並執行
flutter_scene:init; - 啟用 Flutter GPU(
FLTEnableFlutterGPU)並關閉應用程式的沙箱(匯出器需要執行 ffmpeg); - 從
assets/template/複製入門套件,建立art/、art/screens/、audio/與fonts/目錄,並忽略out/; - 將
demo/**加入上層套件的分析器排除清單。
它可以在 pub 工作空間內運作(demo 依然是一個獨立套件),並會拒絕覆蓋已存在的資料夾。
接著進行設定:
lib/core/timeline.dart:設定kDuration、kBpm、kBeatPhase以及Cue列表。lib/core/format.dart:根據應用程式的主題設定Palette,以及Fonts(將字型檔案複製到demo/fonts/並在pubspec.yaml中宣告)。- 資源:
art/(在pubspec.yaml中列出子資料夾)與audio/track.wav(48 kHz PCM)。
建置一次並渲染範例的靜態圖片以證明設定無誤:
cd <app>/demo && flutter build macos --profile && tool/run.sh stills "0.3,2.3,9" both
6. 建置短片
將 lib/shots/example.dart 替換為對應腳本每個部分的章節,在 Director.sections 中列出這些章節,並在 Director._hits 中設定相機焦點。逐章節進行:
- 使用套件(references/kit.md)與 flutter_scene(references/flutter-scene.md)撰寫該章節(3D 影格,以及在其下方與上方的 2D 圖層)。
- 執行
flutter build macos --profile,然後在該章節的關鍵時刻以兩種格式渲染靜態圖片:tool/run.sh stills "t1,t2,..." both。 - 每種格式製作一張聯絡表並檢查,對於細節重要的地方再檢查單張靜態圖片:
python3 tool/sheet.py out/l.png 4 480 out/stills/landscape_*.png。如果你無法查看圖片,請告知使用者需要檢查哪些靜態圖片以及檢查什麼。修正後重複此步驟。
在匯出前,請使用 references/craft.md 中的審查清單檢查整個短片。使用者可以在預覽應用程式中觀看短片與音樂同步的效果(open build/macos/Build/Products/Profile/*.app);靜態圖片無法顯示時間控制。
7. 匯出
tool/export.sh draft both # 1x,無動態模糊:快速完整檢查
tool/export.sh final both # 2x 超採樣,4 採樣動態模糊
最終匯出對於 30 秒的短片,每種格式大約需要 10–15 分鐘。如果環境允許,請在背景執行,並且不要輪詢。之後,使用 ffprobe 驗證檔案:影格數應為 kDuration * kFps,持續時間應正確,且應包含音訊串流。從 MP4 中擷取幾個影格,包括最後一個影格與影格 0(循環接縫)。
8. 交付與迭代
將路徑(用於上傳的 demo/out/final/<format>.mp4、用於剪輯的 <format>_master.mov ProRes)、檔案大小以及需要檢查的項目提供給使用者。預期會收到修改意見。常見的意見與修正方法請參閱 references/craft.md:文字停留時間過短、文字被遮蓋、不必要的字幕、輪廓接縫、生硬的光線、一組看起來相同的項目、直向文字措辭。在重新渲染前,先在一輪中修正所有意見。
檔案
- references/kit.md:入門套件的架構與 API。
- references/flutter-scene.md:flutter_scene 的設定、外觀與離線注意事項。
- references/audio-sync.md:從音軌中提取的節奏、相位、歌詞與提示點。
- references/craft.md:腳本模板、文字規則、特效配方、螢幕截圖、審查清單。
scripts/scaffold.sh:建立示範應用程式。scripts/analyze_audio.py:節奏、拍點相位、每小節響度、起始點。assets/template/:Scaffold 複製的入門套件。