TVideo — 來自真實網頁應用的教學影片
您正在製作短影片,教導最終使用者如何在網頁應用程式中完成一個任務。 觀眾並非技術人員:每個畫面都必須冷靜、可讀且真實。 流程分為兩半,透過三個檔案銜接:
錄製器 (Playwright) ──► video.webm + timeline.json + clicks.json ──► 編輯器 (Hyperframes) ──► MP4
- 錄製器 (
templates/recorder/) 驅動真實應用程式,繪製可見的 游標,並記錄每個步驟開始/結束的時間以及每次點擊的位置。 - 編輯器 (
templates/editor/build.mjs) 將素材放置在品牌化畫布上, 在觀眾需要時間閱讀的地方保持靜止畫面,放大並圈出要點擊的控制項, 在每次點擊時添加點擊音效,然後渲染。
因為編輯是從這些檔案生成的,所以在 UI 變更後重新錄製只需:
錄製 → 導入 → 構建 → 渲染。請保持這種方式 — 永遠不要手動編輯
index.html;請修改 plan.json / tvideo.config.json 並重新構建。
第零階段 — 起飛前檢查
在每次工作階段開始時執行這些檢查 — 如果您在詢問簡短問題,請在您的第一個回覆中同時進行,這樣用戶就不必等待 — 並在錄製前修復漏洞;在中途發現缺少工具會浪費一次錄製。
| 需要 | 檢查 | 修復 |
|---|---|---|
| Node ≥ 20 | node -v | 安裝 Node |
| ffmpeg / ffprobe | ffmpeg -version | brew install ffmpeg / apt |
| Hyperframes CLI + skills | npx hyperframes --version | npx hyperframes skills update general-video (也會安裝 media-use、hyperframes-audio) |
| Playwright 的 Chromium | 在錄製器目錄中:npx playwright install chromium | — |
如果您在本次工作階段中尚未使用 Hyperframes,請閱讀一次 references/hyperframes-notes.md(構建腳本已遵循的構圖規則及其原因)。
第一階段 — 簡報(詢問,不要假設)
在一輪簡短的提問中,蒐集會影響工作的變更事項:
- 應用程式網址和環境。優先選擇暫存/UAT/演示環境。錄製 會真實驅動應用程式:提交表單、建立記錄、發送電子郵件。 清楚說明這一點,並在對任何共享環境進行錄製前獲得同意。
- 登入:一個專用的演示帳號(使用者名稱/密碼透過環境變數 — 絕不
貼入聊天或寫入檔案)。如果登入需要 OTP/2FA,請規劃讓使用者在執行期間貼入驗證碼(請參閱
references/recording.md)。 - 流程:每個任務一個影片。將「如何使用系統」拆分為 30–120 秒的片段(登入、建立 X、編輯/取消 X、下載 Y…)。 詢問觀眾應該以什麼順序觀看它們。
- 語言UI 和字幕的語言 (
TV_LOCALE、lang)。 - 品牌:標誌檔案、1–2 種顏色、字型(如果需要語言支援,則需要; 內建的 IBM Plex Sans Thai 涵蓋泰語 + 拉丁語)。預設為中性海軍藍/綠色。
- 音效:預設為字幕 + 點擊音效。音樂:內建 CC BY 曲目或無。
旁白是可選的,需要 TTS 配額 — 請參閱
references/narration.md。
安全決策(在簡報中、任何錄製之前解決這些問題)
這些影片會散播出去,而錄製會執行真實操作。解釋取捨, 推薦安全選項,並讓使用者決定 — 然後遵循它。
- 螢幕上的資料歸誰所有。 觀眾不得看到的內容:其他客戶的
姓名、真實訂單、個人電子郵件/地址/電話號碼、內部測試
標籤。建議使用虛構的演示帳號。如果使用者堅持使用個人或
真實帳號,請明確說明哪些內容會可見,獲得明確同意,並規劃
對每個個人值使用
mask(在快照上檢查它們)。如果您不確定 某個值是否為真實,請詢問。 - 不可逆或財務步驟(付款、轉帳、發送給真實第三方、 刪除、發布)。永遠不要為了拍攝而完成真實付款或其他不可逆操作。 優先選擇沙盒/測試模式(測試卡、暫存閘道);如果 沒有,請錄製到最終確認畫面為止,在那裡停止,並讓最後的 字幕解釋最終的點擊。在簡報中說明這一點。
- 生產環境 vs 暫存環境。 在真實的生產網站上錄製需要在您之後 獲得明確同意,列出它會建立的內容(訂單、電子郵件、庫存變更) 以及如何清理。優先選擇那裡唯讀或可逆的流程。
- 憑證。 密碼和 OTP 應放在環境變數/使用者控制的本地檔案中,
永遠不要放在聊天記錄或您建立的檔案中。使用者已經輸入過的使用者名稱/電子郵件
不是秘密,但不要將它重複寫入
TV_USERNAME之外的檔案。 - 第三方登入 (Google、Microsoft、SSO、驗證碼)。 那裡的
自動登入通常會觸發機器人檢查或 2FA。讓使用者在有頭瀏覽器中手動登入一次
(
npx playwright codegen --save-storage=.auth/state.json <登入 URL>), 然後使用儲存的 session 進行錄製,並讓TV_USERNAME保持未設定。 - 發布。 在交付之前,重新觀看以檢查個人資料,並在 片尾保留音樂鳴謝 (CC BY 需要署名)。公開頁面的受眾比內部培訓 更嚴格 — 嚴格遵守隱私規則。
第二階段 — 探索和排練
- 每個專案建立一個工作資料夾,例如
tvideo-work/<app>/,然後複製templates/recorder/→recorder/並在裡面執行npm i。 - 探索:打開流程的每個頁面(Playwright MCP / 瀏覽器工具,或
一次性腳本)並選擇穩定的選擇器 — 優先選擇角色/標籤/test-id
而不是 CSS 類別。注意那些拍攝效果不佳的內容(請參閱 recording.md:原生
<select>彈出視窗、日期選擇器、即時滾動跳轉、預訂視窗)。 - 為
recorder/clips/NN-name.spec.ts中的每個片段撰寫一個規格, 遵循clips/01-example.spec.ts:先createTimeline;每個觀眾可見的步驟 是tl.step('<字幕文字>', …)以expect結尾;透過tap()/typeInto()點擊;在折疊區域以下的任何內容之前使用glideTo();在關鍵時刻後使用hold(); 最後用await tl.save()。像使用者一樣選擇值 — 從下拉式選單/日曆中選擇,而不是輸入代碼。 - 排練:
TV_REHEARSE=1 npx playwright test— 不錄製影片,不暫停。在這裡修復 所有失敗;這只會花費幾秒鐘,而不是毀掉一次錄製。
第三階段 — 錄製
npx playwright test (或單一片段:npx playwright test clips/02-)。每個片段
在 test-results/<clip>/ 下寫入 video.webm、timeline.json、clicks.json。
立即將它們複製出來(下一步會這樣做)—
Playwright 會在下次執行時清除 test-results/。
步驟失敗意味著應用程式做了意外的事情(驗證、業務規則、載入緩慢)。 閱讀失敗截圖,修復規格或資料,重新執行該片段。永遠不要為了獲得一次錄製而放寬斷言; 一個通過的錄製但流程錯誤是在教使用者錯誤的內容。
第四階段 — 設定編輯
每個片段一個 Hyperframes 專案,位於錄製器旁邊(例如 tvideo-work/<app>/clip-02/)。
hyperframes init 會寫入自己的起始檔案;將範本複製到它們上面是預期的
(build.mjs 會重新產生 index.html)。從工作資料夾執行:
npx hyperframes init clip-02 --non-interactive --example=blank
cp -R <skill>/templates/editor/. clip-02/
cp clip-02/tvideo.config.example.json clip-02/tvideo.config.json # 品牌、字型、標誌、音樂、語言
cp clip-02/plan.example.json clip-02/plan.json # 標題、片尾、每個 tl.step 一個步驟
ls recorder/test-results/ # 該片段的名稱很長 — 在這裡找到它
bash <skill>/scripts/import.sh recorder/test-results/<that-folder> clip-02
bash <skill>/scripts/sfx.sh clip-02 # 輕點擊、短嗖聲、鈴聲、閃爍聲
在 tvideo.config.json 中:設定 lang 和 readingCharsPerSec(≈15 英文,≈12 泰文
— 較慢的腳本閱讀較慢),品牌顏色,以及 logo(路徑,或
null 表示純文字卡片)。保留 music.credit — 內建曲目是 CC BY 授權。
plan.json 中的步驟與錄製器的 tl.step 一對一、按順序 對應
(如果對應錯誤,構建會拒絕)。plan.json 中的字幕是觀眾閱讀的內容 — 保持
簡短指示(「點擊「儲存」」),而不是旁白。通常 tl.step 標籤
已經是好的字幕;將它們複製過來。
第五階段 — 測量、構建、檢查
- 提取影格以找到座標:
bash <skill>/scripts/frames.sh assets/footage.mp4 frames <t1> <t2> …。 好的時間點:clicks.json 中的每個點擊減去 ~0.3 秒(游標已經在控制項上 — 那是它的位置),以及每個步驟的endMs減去 0.3 秒( 穩定後的結果)。閱讀完整尺寸的 PNG。座標是錄製的 像素(例如 1280×800)。 - 根據需要為每個步驟添加(詳細資訊請參閱
references/editing.md):- 對要點擊的控制項使用
zoom {scale,at}+ring {x,y,w,h}— 縮放 以環為中心(縮放的固定點必須在控制項上,否則 控制項會向邊緣滑動並被裁切); - 當控制項在點擊後消失時使用
holdFirst: true(一個會導航離開的按鈕) — 先顯示點擊前的影格; - 使用
mask {x,y,w,h,text,after}來覆蓋不得發布的值; - 在成功時刻使用
chimeAfter: <s>。
- 對要點擊的控制項使用
node build.mjs然後npx hyperframes check。修復所有錯誤; 字幕淡入期間的對比度警告是預期的且無害。- 親自驗證:
build.mjs會列印每個步驟在 OUTPUT 時間軸中的位置(輸出時間 ≠ 錄製時間 — 片頭和停留會改變它)。 在這些時間視窗內進行快照 —npx hyperframes snapshot --at <t…> --no-end, 每個有環的靜止畫面、每個遮罩、每個步驟中點各一張 — 並閱讀 聯繫表。環必須位於控制項上,遮罩必須精確覆蓋, 字幕必須與螢幕上的內容相符。
第六階段 — 審查和渲染
- 打開預覽:
npx hyperframes render --quality draft -o renders/draft.mp4並open它(Studio 預覽npx hyperframes preview --background也 有效,但它的搜尋在長片段上可能會卡頓;渲染永遠不會)。 - 根據回饋透過編輯 plan/config 並重新構建來迭代 — 或者當素材本身 有問題時(節奏、跳躍、錯誤資料)重新錄製。在源頭修復素材問題, 而不是使用覆蓋層。
- 最終:
npx hyperframes render --quality delivery -o renders/<clip-name>.mp4。 報告路徑、持續時間和大小。 - 如果環境是共享的,清理錄製在應用程式中建立的內容(演示訂單/預訂), 並說明您清理了什麼。
當出現問題時
references/troubleshooting.md 列出了此流程已遇到的失敗
及其真實原因(素材/時間軸漂移、原生選擇器、預訂視窗、
被覆蓋的 test-results、SFX 重疊警告、預覽中的卡頓)。在從頭開始除錯之前先檢查它。
此技能中的檔案
templates/recorder/— Playwright 專案:cursor.ts、timeline.ts、auth.setup.ts、playwright.config.ts、clips/01-example.spec.ts(為 外掛程式倉庫的examples/demo-app編寫,與plan.example.json配對)templates/editor/—build.mjs、plan.example.json、tvideo.config.example.json、assets/fonts(OFL)、assets/music(CC BY)scripts/—import.sh、frames.sh、sfx.sh、voice.mjs(可選 TTS)references/—recording.md、editing.md、narration.md、hyperframes-notes.md、troubleshooting.md