Auto-Loom
將任何網頁應用程式轉變為帶旁白、可自行驅動的 MP4 影片。頁面會自動捲動、 高亮元素，並在各路由之間導航，同時 AI 語音會以毫秒級的精準度進行旁白。 無需手動螢幕錄製，也無需笨拙的 Loom 重拍。 只需編輯一行旁白，即可在數分鐘內重新渲染。
運作方式： ElevenLabs 為每個故事板拍次生成一段音訊。
ffprobe 精確測量每段音訊的長度。Playwright 在錄製視窗的同時，
驅動瀏覽器執行每個拍次剛好對應的時長。ffmpeg 將最終的 MP4 與字幕軌道混合。
音訊時長是基準，視覺效果則完全與之同步。
此資料夾即為整個引擎。 同層級的其他技能是這些相同腳本的簡化入口點：
- auto-loom-proof — 軟體工廠的驗證影片：在鏡頭前逐一執行構建的驗收標準
這份 SKILL.md 涵蓋了引擎以及開發者模式：您擁有程式碼庫， 應用程式在 localhost 上執行，並且您可以將穩定的選擇器加入 JSX。
設定（一次性，約 3 分鐘）
cd <此技能資料夾>
bash scripts/setup.sh # 安裝 Playwright + Chromium，建立 .env.local
# 編輯 .env.local → 加入您的 ElevenLabs API 金鑰
node scripts/doctor.mjs # 驗證 node、ffmpeg、playwright、金鑰、語音
還沒有 ElevenLabs 帳戶嗎？請透過維護者的推薦連結註冊： https://try.elevenlabs.io/atherial。
doctor.mjs 會針對任何缺少的項目印出確切的修正方式。需求：Node 18+、
ffmpeg (brew install ffmpeg)、一個 ElevenLabs API 金鑰。語音選項：
references/voices.md。
煙霧測試（30 秒，錄製 example.com）：
node scripts/run.mjs --beats examples/smoke-beats.json
步驟 0 — 先與使用者訪談
不要立即開始建構。請先詢問：
1. 我們要錄製哪個網址或應用程式？它是否在本地端執行？
2. 觀看者是誰 — 姓名與背景？
3. 故事是什麼？我們展示了哪些新的功能或變更？
4. 應該強調哪些特定功能、指標或區塊？
5. 調性是什麼？（客戶更新、內部示範、潛在客戶展示）
6. 應用程式是否需要登入？（請參閱 references/auth.md — 請勿在聊天中詢問密碼）
7. 目標長度 — 30 秒、60 秒、還是 75 秒？
時間緊迫時：只需詢問 1–3，其餘可根據應用程式推斷。
步驟 1 — 撰寫故事板（beats.json）
在接觸任何程式碼之前先撰寫旁白，並取得逐字核准。
腳本規則與運作良好的拍次框架：references/tts-rules.md。
{
"meta": {
"title": "Acme 儀表板逐步介紹",
"slug": "acme-walkthrough",
"cta": "請將您的回饋寄給我，我們將進入下一階段。",
"targetLengthSec": 70
},
"baseUrl": "http://localhost:3000",
"viewport": { "width": 1920, "height": 1080 },
"beats": [
{
"id": 1,
"page": "/dashboard/insights",
"text": "嘿，Jim。我們為您的 AI 能見度追蹤器推出了一些更新。",
"actions": [
{ "fn": "waitFor", "sel": "[data-vn=kpi-row]" },
{ "fn": "scrollToEl", "sel": "[data-vn=kpi-row]", "opts": { "instant": true } },
{ "fn": "hl", "sel": "[data-vn=kpi-row]" }
]
}
]
}
完整結構：schema/beats.schema.json。動作表與選擇器指南：
references/actions.md。登入選項（腳本化步驟或已儲存的工作階段）：
references/auth.md。
在花費任何資源之前先進行檢查：
node scripts/validate.mjs --beats <檔案> # 結構 + TTS + 節奏檢查
node scripts/run.mjs --beats <檔案> --script-only # 印出旁白並停止
驗證器會捕捉未知的動作、遺失的選擇器、TTS 問題（長破折號、裸縮寫、冗長的句子）， 以及無法符合目標長度的節奏。
--script-only 是省錢的審查關卡：它會印出每個拍次的旁白與每個拍次的時間估計，
然後在任何 ElevenLabs 呼叫或錄製之前退出。在這裡取得腳本核准，
然後在沒有此旗標的情況下重新執行以花費配額。
步驟 2 — 對頁面進行插樁（開發者模式）
Playwright 需要穩定的選擇器。有了程式碼庫的存取權限，請將 data-vn
屬性加入元件 JSX：
<div data-vn="kpi-row" className="grid grid-cols-4 gap-4">
<Card data-vn="competitor-chart" ...>
然後在故事板中引用它們：{ "fn": "hl", "sel": "[data-vn=kpi-row]" }。
錄製時請抑制互動式向下鑽研功能。 具有 role="button" / tabIndex={0} 的可點擊卡片，
可能會在高亮期間自動獲得焦點，並在影片中途開啟抽屜。
請使用您的示範模式標誌來限制它們：
{!isDemoMode() && <MetricBreakdownSheet ... />}。
如果應用程式需要在本地端進行驗證，請設定一個示範模式（跳過驗證，使用與旁白數字完全相符的
固定資料），或使用 references/auth.md 中的驗證路徑。
關於 CSP 的注意事項： 錄製器會以 bypassCSP: true 啟動 Chromium，
因此它可以將 presenter.js 注入具有嚴格 CSP 的頁面。
如果您將它指向一個具有即時工作階段的生產應用程式，請注意，Content-Security-Policy
在該自動化瀏覽器環境內將被停用。
步驟 3 — 一個指令
node scripts/run.mjs --beats <檔案>
這會執行：驗證 → 音訊（依文字雜湊快取）→ 預檢（在錄製任何內容之前，執行無頭瀏覽器解析每個選擇器）→ 錄製 → 字幕 → 混合 → 驗證。
輸出會放置在 demo-video-out/<slug>/：
<slug>-demo.mp4— 最終影片（H.264/AAC，軟字幕軌道）<slug>-demo-contact-sheet.png— 供目視檢查的取樣影格qa/beat-NN.png— 每個拍次停留點的擷取螢幕截圖captions.srt、audio/、video/recording.webm
所有旗標：--script-only（印出旁白腳本，並在進行任何 ElevenLabs 呼叫或錄製之前退出 — 步驟 1 的審查關卡）、
--preflight-only（檢查選擇器，不花費任何資源）、--skip-audio
（僅視覺變更 — 音訊會重複使用）、--skip-preflight（跳過無頭選擇器檢查 —
僅在預檢剛剛通過且未有任何變更時使用）、
--burn-captions（將字幕硬編碼到像素中，適用於會剝離軌道的平台）、--no-captions、--out <目錄>、--env <環境變數檔案>。
步驟 4 — 發送前進行驗證
run.mjs 會檢查時長（MP4 音訊總和誤差在 0.5 秒內）、音訊位準（靜音軌道偵測），
並放置 QA 螢幕截圖。您仍需目視檢查：
- 聯絡表 +
qa/beat-NN.png：每個影格顯示其拍次所旁白的內容 — 不應有登入頁面、錯誤狀態或意外的彈出視窗。 - 第一個拍次要指名觀看者；最後一個拍次要逐字傳達 CTA。
疊代
- 編輯旁白 → 重新執行；僅有變更的拍次音訊會重新生成。
- 視覺/節奏編輯 →
--skip-audio。 - 選擇器損壞 →
--preflight-only會顯示是哪個拍次和選擇器出問題。
已知問題
- 熱重新載入會清除注入的 presenter。 已處理 — presenter 會在每個拍次 之前重新注入。但請避免在錄製期間編輯應用程式。
- 連接埠漂移。 如果 3000 被佔用，
yarn dev會使用 3001 — 請更新baseUrl。 - 免費與付費語音。 在免費方案上使用複製/庫存語音會拋出
payment_required錯誤。doctor.mjs會在渲染時間之前捕捉到這個問題。 - i18n 重新導向。
/en/dashboard→/dashboard的重新導向會正確處理； 相同頁面的拍次不會重新導航。 - 傳遞。 MP4 是自包含的 — 可透過電子郵件、Slack、LinkedIn DM、Notion 嵌入， 或匯入 Descript 以在上方加入個人簡介。