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 或任何其他代理中,請用一般文字提問並等待回覆。
- 旁白? 無聲影片,或語音旁白。如果使用者不需要旁白,請跳過所有旁白步驟;無聲影片即為交付成果。
- 旁白的語言(以及字幕的語言,即旁白腳本的語言):普通话 / English / 日本語 / 한국어 / Deutsch / français / español / italiano / português / русский。預設值:應用程式的語言以及使用者撰寫時使用的語言。
- 引擎。 提供此機器實際能使用的選項 — 先執行
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(下載量小)或製作無聲影片。
- 語音,如果引擎有選擇:提供 3-5 種語音,每種附一行說明(例如 Qwen
serena/ryan、Kokorozf_039/zm_013/af_maple、OpenAI 語音 ID),並附上合理的預設值。
將答案寫入故事檔案 — LANGUAGE 與 VOICE = {'engine': …, 'speaker': …} — 以便能再次製作相同的影片。遠端金鑰絕不寫入故事:將其放入環境變數或 demo_env.py key。
不可妥協的原則
- 絕對不要錄製使用者的即時服務或真實資料。 啟動一個臨時實例,使用另一個連接埠與其自己的資料目錄(故事檔案中的
launch()),或專用的示範資料集。如果無法隔離應用程式,請詢問。 - 用數字檢查,而非觀看畫面。
demo_render.py --check與demo_voice.py check是事實來源。當其中任一報告注意:問題時,不要聲稱影片已完成。 - 不要碰觸正在運行的服務。 如果選擇的連接埠已被佔用,請選擇另一個連接埠;切勿停止他人的程序。
- 旁白為可選,且其引擎由使用者選擇。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 也會記錄故事檔案路徑與錄製時間。遠端旁白服務會收到每行字幕的文字內容;本機引擎則不會傳送任何內容。