screen-demo 是做什麼的?
將一個 URL 變成展示影片。你是導演:你檢視頁面,將步驟寫成 JSON,腳本會播放它、逐幀捕捉頁面自身的畫面(而非桌面),並編輯影片。滾動、滑鼠游標的移動和打字動作都會以每秒 30 幀的速度逐幀捕捉,即使在沉重的頁面上也能保持流暢;而頁面在點擊或載入後自行發生的動作則來自即時螢幕廣播。
設定(一次性)
- Python 3.10+,並安裝 Pillow 和最新的 Playwright:
python -m pip install -U playwright pillow,然後執行python -m playwright install chromium。 - 將 ffmpeg 加入 PATH(
winget install ffmpeg、brew install ffmpeg)。
用 python tests/selftest.py 測試(本機頁面,無需網路,約需一分鐘)。
工作流程
- 詢問影片用途: URL、2 到 4 個要展示的內容(主視覺、功能、價格、註冊流程)、格式(
landscape16:9 適用於 YouTube 和 README、vertical9:16 適用於 Shorts 和 Reels、square),以及是否要 GIF。僅限使用者自己的網站或應用程式,或是經允許可以展示的公開頁面。 - 檢視頁面:
python scripts/demo.py inspect URL WORK [--format vertical]。閱讀每個WORK/page-N.jpg(以視口大小切片呈現的頁面,每個可點擊元素都以紅色編號標示方框)以及WORK/elements.txt。Cookie 橫幅或彈出視窗會在這裡顯示:步驟的第一步應關閉它(找到「拒絕」或「關閉」按鈕)。 - 撰寫
WORK/tour.json(格式詳見 references/tour-format.md):一個標題卡片,然後是簡短的步驟。一個好的步驟順序:一句說明產品功能的標題、滾動到第一個值得一看的東西、放大它、點擊或輸入一些內容來展示產品運作、高亮結果、每個想法一個標題。總長 15 到 40 秒。目標是 inspect 產生的編號(#12),或css=...、text=...。 - 錄製:
python scripts/demo.py record WORK/tour.json OUT [--gif]。它會播放步驟順序,印出每個失敗的步驟,並渲染出OUT/demo.mp4(和OUT/demo.gif)。 - 在完成前查看
OUT/keys.jpg(每個步驟的一幀畫面):檢查放大錯了東西、標題遮住了重點、某步驟失敗(元素移動或隱藏)、橫幅仍然擋路等。如果只需要修改標題、縮放或標題卡片,請編輯OUT/tour.json並執行python scripts/demo.py render OUT [--gif](無需重新錄製);其他情況則需要重新錄製。 - 交付:
demo.mp4(以及 GIF)的路徑、長度,以及每個展示想法的簡短說明。
規則
- 絕不使用密碼登入、絕不輸入密碼或信用卡號碼(腳本會拒絕密碼和付款欄位)、絕不購買、發送、刪除或發布任何內容、絕不提交包含他人個人資料的表單。需要展示登入後區域的示範時,使用者必須自行提供測試帳號的頁面。
- 拒絕 Cookie 橫幅(最少資料收集),除非使用者另有指示。
- 保持標題簡短(3 到 8 個字);每個標題一個想法;影片本身的動作會完成其餘部分。
- 尊重網站:不展示使用者未被允許展示的頁面。
範例
使用者:「為我的登陸頁面 https://example.com 製作一個 20 秒的展示影片,用於 README,展示註冊功能」
你執行 inspect,閱讀 3 張切片,看到一個 Cookie 橫幅(#2「全部拒絕」)、主視覺區、一個「試用」輸入框(#9)和一個價格卡片(#21);你寫了一個步驟順序:標題卡片、點擊 #2、標題「會自動書寫的筆記」、在 #9 輸入文字、點擊 #10、高亮結果、標題「永久免費」、滾動到 #21、放大;使用 --gif 參數錄製,開啟 keys.jpg,看到縮放框住了價格區塊,回覆 demo.mp4(21 秒)、demo.gif(3 MB)以及四個展示想法。