示範到宣傳短片：Screen Studio 風格網頁應用示範

webapp-screencast

你編寫指令碼，webapp-screencast 負責錄製與剪輯。輸出：OUT/<name>.mp4（1920×1080，60 fps） 以及一張海報 .jpg。一切皆由你撰寫的檔案（scenario.py、plan.py）和一個 CLI 驅動。

總是使用 --json（在子命令之前）呼叫 CLI：stdout 會是一個 JSON 物件 （ok、error、路徑、時長、警告）；進度訊息則輸出到 stderr。結束碼 0 表示成功，1 表示步驟失敗，2 表示輸入錯誤。

API 與計畫鍵值：請參閱 reference.md。在撰寫 scenario.py / plan.py 之前，請先閱讀該文件。

0. 初始設定（每臺機器執行一次）

webapp-screencast --json doctor

如果缺少 webapp-screencast：pip install git+https://github.com/dr-osmanovich/webapp-screencast.git （若專案有虛擬環境，請使用該環境），然後執行 python -m playwright install chromium。 doctor 會列出每個失敗的檢查項目及其 fix。需要 Node 22+ 和 ffmpeg 才能進行渲染。

1. 瞭解應用程式（在錄製之前）

• 找出如何在本地執行（README、package.json scripts、Makefile、docker-compose）及其 URL。 靜態資料夾可直接由 webapp-screencast 本身提供服務（make --serve DIR）。
• 在儲存庫中找到示範/種子資料與測試帳號（fixtures、seed scripts、.env.example）。 切勿錄製生產環境、真實客戶或病患資料，以及真實憑證。如果沒有安全的示範資料，請停止並詢問使用者。
• 找出如何重設狀態（seed/reset script、清除 localStorage）。每次錄影都從乾淨狀態開始。
• 挑選 3–5 個能展現產品價值的節拍：鉤子 → 動作 → 結果 → 一個細節 → 結束。影片長度 15–30 秒。
• 閱讀實際的元件以取得穩定的選擇器（id、data-testid、角色）。不要憑空猜測。

2. 建立骨架與指令碼

webapp-screencast --json init video/ --base-url http://127.0.0.1:3000 --title "產品名稱"

撰寫 video/scenario.py：CONFIG、可選的 login(page, cfg) 和 prepare(page, cfg)，以及 run(take, page)。有助於減少重錄的規則：

• 在每個節拍使用 take.mark("名稱")；對於所有需要攝影機或標註框選的內容，使用 take.box("名稱", selector)（或帶有 name= 參數的 click(...)）。務必先標記 hook，最後標記 end。
• 動作後使用 page.wait_for_selector(...) 等待應用程式回應，然後使用 take.hold(0.3–0.8)。
• 在 take.type(...) 之前，將滑鼠指標移離文字區域；以 cps 25–35 的速度輸入。
• 在 prepare() 中隱藏 toast、cookie 橫幅、開發者覆蓋層；關閉側邊面板。
• 原生 title= 工具提示在無頭模式下無法顯示——請改用計畫中的 callout。

3. 錄製與檢查

webapp-screencast --json record video/scenario.py --out video/out/footage [--base-url URL]
webapp-screencast --json inspect video/out/footage

檢查 peak_fps 是否在繁忙的節拍中 ≥ 50（macOS 上較低 → GPU 旗標問題，請參閱參考文件），並確認你規劃的所有標記都存在。失敗的選擇器會在 stderr 上產生 Playwright 錯誤：修正 scenario 並重新錄製——影片素材成本很低（≈ 錄影長度 + 10 秒）。

4. 規劃、合成、檢視

撰寫 video/plan.py：使用 inspect 輸出的標記和方框（切勿硬編碼秒數）： 攝影機鏡頭跟隨動作（在節拍上縮放 1.4–1.7，場景之間回到 1.0）、 每個節拍一個短字幕（每個單字 ≥ 0.3 秒，不可重疊）、開場/結尾卡片。

webapp-screencast --json compose video/plan.py --footage video/out/footage --out video/out/composition
webapp-screencast --json snapshot video/out/composition --at 1,5,9,14 --out video/out/stills

修正所有 warnings 條目。檢視靜態畫面（讀取 PNG 或連絡表）：文字清晰可讀、攝影機對準動作、無內容被裁剪、無字幕遮蓋其所描述的內容。僅使用 compose + snapshot 迭代 plan.py——無需重新錄製。

5. 渲染與交付

在 M1 上，每 20 秒的渲染約需 4–5 分鐘——請在背景執行，並記錄到日誌檔案。

webapp-screencast --json render video/out/composition --out video/out/video.mp4
webapp-screencast --json poster video/out/video.mp4 --at 9.0

確認 JSON 顯示 fps: 60 和預期的時長。交付 mp4 和海報路徑。 在 .gitignore 中加入 out/ 目錄；提交 scenario.py + plan.py，以便在使用者介面變更後可以重新製作影片。

當 scenario 和 plan 都已準備就緒時，一鍵執行： webapp-screencast --json make video/scenario.py video/plan.py --out video/out --base-url URL --poster-at 9 （靜態網站使用 --serve DIR，--skip-render 可在檢查後停止）。

與 /brag（或其他 launch-video 技能）搭配使用

Brag 決定故事；webapp-screencast 提供真實素材。

1. 執行 brag 自己的規劃：概念、調性、節拍、標題、文案。在它建立螢幕截圖場景之前停止。
2. 將 brag 的節拍轉換為 scenario.py 的標記（每個節拍一個標記）並錄製。
3. 將 brag 的台詞放入 plan.py：鉤子 → intro.title，節拍說明 → subtitles， 結尾台詞 / CTA → outro；將 brag 的調性對應到 look（精緻 → graphite/ocean， 活潑 → sunset/violet，強調色 = 應用程式 CSS 中的品牌顏色）。
4. 如上所述進行合成、快照、渲染到 brag 的輸出資料夾；然後讓 brag 撰寫分享文案。 目前僅支援橫向 16:9；如果 brag 要求直向，請說明並渲染橫向影片。