Communitygithub.com

TVideo:真實網頁應用一鍵產出帶字幕的 1080p 教學影片

Claude Code 外掛:用 Playwright 帶可見游標錄製你的真實網頁應用,再用 Hyperframes 剪輯,加上任意語言的步驟字幕、要點按鈕的放大與高亮圈、點擊音效、音樂和可選 TTS,每個任務輸出一支 1080p MP4。

TVideo:真實網頁應用一鍵產出帶字幕的 1080p 教學影片 是什麼?

教學影片配方第 1 步(操作教學),來自 JiramedFirst/TVideo(2026-10-08 發布,MIT,README 附 33 秒示範 GIF 與截圖)。請它為測試環境做教學:Claude 先把需求拆成每個任務一支片並與你確認清單,每支寫一個 Playwright 腳本,先不錄影彩排一次驗證所有選擇器,再錄出 video.webm 加 timeline.json 與 clicks.json。Hyperframes 剪輯器把畫面放上品牌畫布,在需要閱讀處停格,放大並圈出要按的控制項,每次點擊配音效,加音樂與可選 HeyGen 配音,輸出 1080p。剪輯由 plan.json 與步驟時間軸產生,介面改版後重錄只要錄製、匯入、建置、輸出。帳密只從環境變數讀取,碰共享環境前會先詢問,絕不完成真實付款。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/JiramedFirst/TVideo/tree/HEAD/plugin/skills/tvideo

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 ≥ 20node -v安裝 Node
ffmpeg / ffprobeffmpeg -versionbrew install ffmpeg / apt
Hyperframes CLI + skillsnpx hyperframes --versionnpx hyperframes skills update general-video (也會安裝 media-use、hyperframes-audio)
Playwright 的 Chromium在錄製器目錄中:npx playwright install chromium—

如果您在本次工作階段中尚未使用 Hyperframes,請閱讀一次 references/hyperframes-notes.md(構建腳本已遵循的構圖規則及其原因)。

第一階段 — 簡報(詢問,不要假設)

在一輪簡短的提問中,蒐集會影響工作的變更事項:

  1. 應用程式網址和環境。優先選擇暫存/UAT/演示環境。錄製 會真實驅動應用程式:提交表單、建立記錄、發送電子郵件。 清楚說明這一點,並在對任何共享環境進行錄製前獲得同意。
  2. 登入:一個專用的演示帳號(使用者名稱/密碼透過環境變數 — 絕不 貼入聊天或寫入檔案)。如果登入需要 OTP/2FA,請規劃讓使用者在執行期間貼入驗證碼(請參閱 references/recording.md)。
  3. 流程:每個任務一個影片。將「如何使用系統」拆分為 30–120 秒的片段(登入、建立 X、編輯/取消 X、下載 Y…)。 詢問觀眾應該以什麼順序觀看它們。
  4. 語言UI 和字幕的語言 (TV_LOCALE、lang)。
  5. 品牌:標誌檔案、1–2 種顏色、字型(如果需要語言支援,則需要; 內建的 IBM Plex Sans Thai 涵蓋泰語 + 拉丁語)。預設為中性海軍藍/綠色。
  6. 音效:預設為字幕 + 點擊音效。音樂:內建 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 需要署名)。公開頁面的受眾比內部培訓 更嚴格 — 嚴格遵守隱私規則。

第二階段 — 探索和排練

  1. 每個專案建立一個工作資料夾,例如 tvideo-work/<app>/,然後複製 templates/recorder/ → recorder/ 並在裡面執行 npm i。
  2. 探索:打開流程的每個頁面(Playwright MCP / 瀏覽器工具,或 一次性腳本)並選擇穩定的選擇器 — 優先選擇角色/標籤/test-id 而不是 CSS 類別。注意那些拍攝效果不佳的內容(請參閱 recording.md:原生 <select> 彈出視窗、日期選擇器、即時滾動跳轉、預訂視窗)。
  3. 為 recorder/clips/NN-name.spec.ts 中的每個片段撰寫一個規格, 遵循 clips/01-example.spec.ts:先 createTimeline;每個觀眾可見的步驟 是 tl.step('<字幕文字>', …) 以 expect 結尾;透過 tap()/typeInto() 點擊;在折疊區域以下的任何內容之前使用 glideTo();在關鍵時刻後使用 hold(); 最後用 await tl.save()。像使用者一樣選擇值 — 從下拉式選單/日曆中選擇,而不是輸入代碼。
  4. 排練: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 標籤 已經是好的字幕;將它們複製過來。

第五階段 — 測量、構建、檢查

  1. 提取影格以找到座標:bash <skill>/scripts/frames.sh assets/footage.mp4 frames <t1> <t2> …。 好的時間點:clicks.json 中的每個點擊減去 ~0.3 秒(游標已經在控制項上 — 那是它的位置),以及每個步驟的 endMs 減去 0.3 秒( 穩定後的結果)。閱讀完整尺寸的 PNG。座標是錄製的 像素(例如 1280×800)。
  2. 根據需要為每個步驟添加(詳細資訊請參閱 references/editing.md):
    • 對要點擊的控制項使用 zoom {scale,at} + ring {x,y,w,h} — 縮放 以環為中心(縮放的固定點必須在控制項上,否則 控制項會向邊緣滑動並被裁切);
    • 當控制項在點擊後消失時使用 holdFirst: true(一個會導航離開的按鈕) — 先顯示點擊前的影格;
    • 使用 mask {x,y,w,h,text,after} 來覆蓋不得發布的值;
    • 在成功時刻使用 chimeAfter: <s>。
  3. node build.mjs 然後 npx hyperframes check。修復所有錯誤; 字幕淡入期間的對比度警告是預期的且無害。
  4. 親自驗證:build.mjs 會列印每個步驟在 OUTPUT 時間軸中的位置(輸出時間 ≠ 錄製時間 — 片頭和停留會改變它)。 在這些時間視窗內進行快照 — npx hyperframes snapshot --at <t…> --no-end, 每個有環的靜止畫面、每個遮罩、每個步驟中點各一張 — 並閱讀 聯繫表。環必須位於控制項上,遮罩必須精確覆蓋, 字幕必須與螢幕上的內容相符。

第六階段 — 審查和渲染

  1. 打開預覽:npx hyperframes render --quality draft -o renders/draft.mp4 並 open 它(Studio 預覽 npx hyperframes preview --background 也 有效,但它的搜尋在長片段上可能會卡頓;渲染永遠不會)。
  2. 根據回饋透過編輯 plan/config 並重新構建來迭代 — 或者當素材本身 有問題時(節奏、跳躍、錯誤資料)重新錄製。在源頭修復素材問題, 而不是使用覆蓋層。
  3. 最終:npx hyperframes render --quality delivery -o renders/<clip-name>.mp4。 報告路徑、持續時間和大小。
  4. 如果環境是共享的,清理錄製在應用程式中建立的內容(演示訂單/預訂), 並說明您清理了什麼。

當出現問題時

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

相關技能