Communitygithub.com

自動示範錄製技能

自動為網頁應用錄製精美的示範影片,可選擇有旁白或無旁白。透過故事檔案驅動無頭 Chromium 瀏覽器,記錄點擊、輸入、滾動操作,渲染成 1920x1080 60fps 的影片,並可添加攝影機移動、高亮、步驟編號、字幕和章節,最後以指定語言加入旁白。

自動示範錄製技能 是什麼?

這項技能(autoDemoRecordingSkill)能將一個網頁應用程式自動轉換為完整的示範影片。使用者只需撰寫一個「故事檔案」,定義要展示的操作與對應的旁白文字,技能便會驅動無頭 Chromium 瀏覽器執行操作,記錄畫面與時間軸,最終渲染出高品質的 1920x1080 60fps 影片。影片可選擇無聲(僅含內嵌字幕與視覺標記)或加上語音旁白,支援普通話、英語、日語、韓語、德語、法語、西班牙語、義大利語、葡萄牙語與俄語。旁白引擎可選用本機 GPU(Qwen3-TTS)、本機 CPU(Kokoro)或遠端 API(OpenAI 相容、ElevenLabs、阿里雲 DashScope),並提供數值驗證機制確保畫面與音訊品質。此技能支援 Linux、Windows 與 macOS,且相容於 Claude Code 與 Codex 等 AI 代理平台。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/OrrrGE/autoRecording/tree/main

在你喜歡的 AI 中提問

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

說明文件

autoRecording

將網頁應用程式轉換為完成的示範影片。你撰寫一個故事檔案來定義要顯示的內容與要說的話;腳本負責錄製、繪製、編碼、旁白與檢查。影片可以是無聲的或有旁白的,支援普通話、英語、日語、韓語、德語、法語、西班牙語、義大利語、葡萄牙語或俄語,由本機模型(GPU 或 CPU)或使用者提供的遠端服務發音。

story.py ──demo_record.py──► timeline.json + frames/*.jpg
                                  │
                           demo_render.py ──► silent.mp4  (1920×1080, 60 fps)
                                  │
                           demo_voice.py  ──► silent-配音版.mp4 / silent-narrated.mp4   (可選)

0. 開始前先詢問

在回答以下問題之前,請勿開始錄製。在 Claude Code 中使用 AskUserQuestion;在 Codex 或任何其他代理中,請用一般文字提問並等待回覆。

  1. 旁白? 無聲影片,或語音旁白。如果使用者不需要旁白,請跳過所有旁白步驟;無聲影片即為交付成果。
  2. 旁白的語言(以及字幕的語言,即旁白腳本的語言):普通话 / English / 日本語 / 한국어 / Deutsch / français / español / italiano / português / русский。預設值:應用程式的語言以及使用者撰寫時使用的語言。
  3. 引擎。 提供此機器實際能使用的選項 — 先執行 python3 scripts/demo_env.py,僅提供其列為可用的引擎:
    • 本機 Qwen3-TTS (本機 GPU):最佳品質;需要 NVIDIA GPU 約 6 GB 可用 VRAM 與 Qwen 模型。
    • 本機 Kokoro (本機 CPU):無需 GPU,可在 Windows 與 macOS 上運作;普通話與英語表現良好;語音是固定的(無語音克隆)。
    • 遠端 API:使用者提供提供者(OpenAI 相容端點,包括自架、ElevenLabs 或阿里雲 DashScope Qwen-TTS)、金鑰,以及可選的 base URL、模型與語音 ID。 經驗法則:本機模型已就緒 → 使用它;使用者提供 API 金鑰 → 使用 API;兩者皆無 → 詢問是否要安裝 Kokoro(下載量小)或製作無聲影片。
  4. 語音,如果引擎有選擇:提供 3-5 種語音,每種附一行說明(例如 Qwen serena / ryan、Kokoro zf_039 / zm_013 / af_maple、OpenAI 語音 ID),並附上合理的預設值。

將答案寫入故事檔案 — LANGUAGE 與 VOICE = {'engine': …, 'speaker': …} — 以便能再次製作相同的影片。遠端金鑰絕不寫入故事:將其放入環境變數或 demo_env.py key。

不可妥協的原則

  1. 絕對不要錄製使用者的即時服務或真實資料。 啟動一個臨時實例,使用另一個連接埠與其自己的資料目錄(故事檔案中的 launch()),或專用的示範資料集。如果無法隔離應用程式,請詢問。
  2. 用數字檢查,而非觀看畫面。 demo_render.py --check 與 demo_voice.py check 是事實來源。當其中任一報告 注意: 問題時,不要聲稱影片已完成。
  3. 不要碰觸正在運行的服務。 如果選擇的連接埠已被佔用,請選擇另一個連接埠;切勿停止他人的程序。
  4. 旁白為可選,且其引擎由使用者選擇。Qwen 需要 NVIDIA GPU;Kokoro 可在任何 CPU 上執行;遠端服務需要金鑰並將字幕傳送至該服務 — 使用前請告知使用者。

目錄結構

SKILL.md                  本檔案
scripts/demo_env.py       檢查機器;建立技能的 Python 環境;擷取模型;記住金鑰
scripts/demo_record.py    驅動應用程式並錄製影格與時間軸
scripts/demo_render.py    繪製並編碼無聲影片;數值檢查
scripts/demo_voice.py     旁白:台詞、錨點、錄製、聆聽、建構、檢查
scripts/demo_tts.py       引擎:Kokoro (CPU) 與遠端服務
scripts/demo_text.py      字幕如何發音、計數與比較,依語言區分
scripts/demo_common.py    共享的路徑、設定、瀏覽器、機密資訊
story_template.py         複製此檔案以為應用程式撰寫故事
examples/selftest/        一個頁面與兩個故事(中文 story.py、英文 story-en.py)
references/               environment.md, director.md, narration.md, engines.md

以下所有指令皆相對於此技能的目錄;在 Windows 上請用 py -3(或 python)代替 python3。透過將此目錄複製到 ~/.claude/skills/autoDemoRecordingSkill(Claude Code)或 ~/.agents/skills/autoDemoRecordingSkill(Codex)來安裝為個人技能。

1. 檢查機器

cd ~/.claude/skills/autoDemoRecordingSkill
python3 scripts/demo_env.py            # 唯讀:哪些存在、哪些缺少、如何取得、哪些引擎可發音
python3 scripts/demo_env.py setup      # 錄製/渲染/檢查所需的套件(約數百 MB)
python3 scripts/demo_env.py setup --models   # + Whisper large-v3 與 CAM++ 檢查(約 3 GB)
python3 scripts/demo_env.py setup --kokoro   # + Kokoro,CPU 語音引擎(約 400 MB)

對於 Qwen 引擎,還需準備一個包含 CUDA torch 與 faster-qwen3-tts 的 Python 環境,以及兩個 Qwen3-TTS 1.7B 模型;對於遠端引擎,使用 python3 scripts/demo_env.py key openai=…(或環境變數)記住其金鑰一次。記錄所有非預設位置一次:

python3 scripts/demo_env.py set chromium=/path/to/chromium tts_python=/path/to/python \
    tts_custom=/path/to/Qwen3-TTS-12Hz-1.7B-CustomVoice tts_base=/path/to/Qwen3-TTS-12Hz-1.7B-Base

技能的自身檔案位於 ~/.cache/auto-demo-recording(可透過 AUTO_DEMO_HOME 覆蓋)。references/environment.md 有 Windows、macOS 與 Linux 的詳細資訊。

2. 透過自我測試驗證安裝

PY=~/.cache/auto-demo-recording/venv/bin/python
S=~/.claude/skills/autoDemoRecordingSkill
$PY $S/scripts/demo_record.py --story $S/examples/selftest/story.py --work /tmp/demo-selftest
$PY $S/scripts/demo_render.py --work /tmp/demo-selftest --check
$PY $S/scripts/demo_render.py --work /tmp/demo-selftest --out /tmp/demo-selftest/selftest.mp4
$PY $S/scripts/demo_voice.py --work /tmp/demo-selftest      # 僅當需要旁白時執行

story-en.py 是相同的測試,但使用英文字幕與英文旁白路徑。錄製會輸出 JSON 摘要(長度、影格、瀏覽器、錯誤)。selftest.mp4 應為 1920×1080、60 fps,長度約 64 秒。

3. 撰寫故事

將 story_template.py 複製到應用程式旁(或任何位置)並填入內容。合約如下:

名稱說明
TITLE、SUBTITLE、CHAPTERS頂部區域的文字;章節也會繪製在頁面上
LANGUAGE字幕與旁白的語言(zh、en、ja、ko、de、fr、es、it、pt、ru)
VIEW、DENSITY頁面尺寸(CSS px)與裝置比例;寬/高必須為 64:31
PORT臨時實例的連接埠
LOOK{'accent': '#2f6fed', 'note': '#ee5c18', 'fast': '快进'} — fast 為字幕區域的語言用詞
VOICE旁白:engine、speaker,以及遠端服務的 model / base_url(絕不含金鑰);參見 references/engines.md
READING字幕的朗讀速度;預設值:該語言自身的速度(普通話為每秒 5.5 個字元)
launch(work, port){'command': [...], 'url': ..., 'env': {...}, 'wipe': [...], 'cwd': ..., 'ready': ..., 'timeout': ...};或改定義 URL
guard(d)可選;若頁面未處於預期的初始狀態則提前失敗
story(d)實際的導演指令:await d.say(...)、await d.click(...) 等

d 物件是導演。其完整 API、時間模型、標記/放置規則與常見模式請參閱 references/director.md。在撰寫故事前請先閱讀該文件;本檔案其餘部分僅說明工作流程。

良好故事的規則:

  • 每條字幕一個想法;告訴觀眾應注意什麼,以及頁面實際顯示的結果。
  • 優先使用 d.say() 然後 d.read() 再繼續;字幕同時也是旁白腳本。
  • 以 LANGUAGE 語言撰寫字幕。對於無聲影片,字幕仍會在畫面上朗讀,因此請保持簡短。
  • 為點擊編號(await d.click(locator, '添加'))且僅標記重要事項。
  • 以加速方式播放長時間等待(await d.until(..., speed=4))而非剪除它們。

4. 錄製

$PY $S/scripts/demo_record.py --story /path/to/story.py --work /tmp/demo-work --quick
$PY $S/scripts/demo_record.py --story /path/to/story.py --work /tmp/demo-work

--quick 是快速試運行:它跳過觀眾暫停,僅等待應用程式。用於捕捉選擇器與狀態錯誤。之後再進行真正的錄製;work/timeline.json 會被覆蓋,舊的影格會被移除。

錄製前,腳本會清除 frames 目錄與 wipe 中列出的路徑,檢查連接埠是否空閒,啟動故事中的命令,並等待應用程式回應。應用程式的日誌位於 work/server.log。在 Windows 上,應用程式及其啟動的所有程序會以 taskkill /T 終止;在其他平台上,整個程序組會被終止。

5. 檢查與渲染

$PY $S/scripts/demo_render.py --work /tmp/demo-work --check
$PY $S/scripts/demo_render.py --work /tmp/demo-work --out /tmp/demo-work/demo.mp4

--check 在不觀看畫面的情況下驗證:標記區域非空且符合 expect 顏色、標籤未壓在頁面內容上、方框位於攝影機範圍內、步驟/點擊可見、字幕長度適中,且字形存在於字型中。修正故事或時間後重新錄製。渲染還會比較取樣輸出影格與其繪製的影格,並寫入 work/render.json。

如果使用者不需要旁白,無聲影片即為交付成果 — 在此停止並回報。

6. 旁白(僅在使用者要求時執行)

$PY $S/scripts/demo_voice.py --work /tmp/demo-work            # 所有步驟
$PY $S/scripts/demo_voice.py lines --work /tmp/demo-work      # 先檢查發音/時間

它會將有旁白的影片寫在無聲影片旁:中文為 <name>-配音版.mp4,其他語言為 <name>-narrated.mp4。步驟可中斷續傳:參考片段 →(Qwen:試錄)→ 正式錄製 → 語音/說話者檢查 → 選擇/調整/混音 → 驗證。請閱讀 references/narration.md 以了解設定、發音修正與緊湊台詞,以及 references/engines.md 以了解引擎、其語音、金鑰與成本。最終的 check 必須顯示 没有發現問題;任何 听写有出入 行代表語音發出了不同的內容 — 修正字幕、加入 say 覆寫、重新朗讀該行,或選擇另一種語音。

7. 回報

提供使用者輸出路徑(無聲影片,以及若有要求則包含有旁白影片)、時長、解析度/fps、字幕/標記數量、旁白引擎與語音,以及旁白檢查結果。提及任何仍存在的 注意: 警告,且絕不隱藏失敗的檢查。

初步疑難排解

  • 缺 … → 執行 python3 scripts/demo_env.py 並遵循 → 行的指示。
  • 連接埠已被使用 → 修改故事中的 PORT;請勿停止現有服務。
  • 點不到這個元素 → 元素被遮蓋或位於畫面外;先滾動/縮放,或選擇其他目標。
  • 頁面寬度不符 → 頁面在 VIEW 下無回應;調整 VIEW 或頁面,並保持 64:31 比例。
  • 旁白台詞太緊 → 縮短該字幕或給予更多時間,然後重新錄製。
  • Kokoro 的词表里没有这些词 → Kokoro 會跳過這些詞;將它們以拼寫方式加入 VOICE['say'] 中(例如 "API": "A P I"、"exported": "export ed"),或使用 Qwen 或遠端引擎處理英語。
  • 字型方框(□□□)→ 在 Linux 上安裝 Noto Sans CJK;Windows 與 macOS 自帶中文字型;或設定 DEMO_FONT_*(參見 references/environment.md)。

在 Codex 下運作

Codex 會載入相同的 SKILL.md。它沒有 AskUserQuestion 工具:以一般文字詢問步驟 0 的問題。它可能使用不同的 PATH — 請使用 py -3 或技能的 Python 完整路徑。透過 git clone … ~/.agents/skills/autoDemoRecordingSkill 安裝技能(或讓 Codex 的技能安裝器將其放置於 ~/.codex/skills);兩者皆會被發現。agents/openai.yaml 為其提供顯示名稱與起始提示。

隱私

工作資料夾包含應用程式顯示的任何內容的螢幕截圖。請使用包含範例資料的臨時實例,絕不要使用真實帳戶、客戶或生產記錄。未經審查,請勿提交 work/ 或渲染的影片。timeline.json 也會記錄故事檔案路徑與錄製時間。遠端旁白服務會收到每行字幕的文字內容;本機引擎則不會傳送任何內容。

相關技能