Communitygithub.com

JacobLinCool/video-studio-mlx

製作任何應用程式或網站的精美旁白示範/宣傳影片。影片包含真實的螢幕錄製畫面,旁白則由 video-studio-mlx High Level Studio API(/studio/tts,可選聲音複製)生成並經 ASR 驗證。此 API 是唯一固定的依賴項,而非示範的主題。涵蓋旁白優先腳本、錄製目標(macOS 應用程式透過 AppleScript,或網站透過 Playwright)、ffmpeg 合成(框架舞台、PNG 字幕、英雄縮放、旁白錨定的焦點縮放+圓環),以及影格與 ASR 驗證。當使用者需要示範影片、旁白導覽/宣傳片、或與影像同步的配音時使用。不適用於無旁白的螢幕錄製或純截圖。

video-studio-mlx 是什麼?

此技能旨在為使用者指定的任何產品(macOS 應用程式、網站、CLI 等)建立長度約 90–180 秒的旁白示範影片。其核心工作流程遵循「旁白優先」原則:首先透過 video-studio-mlx Studio API(/studio/tts)生成旁白,該 API 會返回每個片段的精確時間長度與逐字時間戳記,這些資料將驅動整個時間線與所有焦點效果。之後再根據旁白進行螢幕錄製,並透過 ffmpeg 進行合成,包括將影片放置於框架舞台、添加 Pillow 渲染的 PNG 字幕、英雄場景的慢速肯·伯恩斯效果、以及由旁白時間戳記錨定的焦點縮放與圓環效果。技能支援兩種錄製後端:針對 macOS 應用程式使用 AppleScript 與 ffmpeg 的 avfoundation 插件;針對網站則推薦使用 Playwright 進行確定性錄製。最終會進行嚴格的驗證步驟,包括提取影格檢查焦點位置,以及對成品影片進行 ASR(自動語音辨識)以確認音訊內容與同步是否正確。使用者需要能夠存取 Studio API 並提供一段參考音訊(用於聲音複製)及其逐字稿。此技能設計為目標無關(target-agnostic),能為多種產品創建專業、統一的示範影片。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/JacobLinCool/video-studio-mlx/tree/HEAD/.agents/skills/studio-demo-video

在你喜歡的 AI 中提問

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

說明文件

工作室示範影片

為使用者指定的任何產品(macOS 應用程式、網站、CLI 等)建立約 90–180 秒的旁白示範。唯一固定的部分是旁白後端:video-studio-mlx Studio API(POST /studio/tts),它會複製聲音並驗證每一行。示範的主題是任意的,且每次都會改變。請記住這個分離:不要假設示範目標是 video-studio-mlx 本身(那只不過是 references/ 中的範例)。

核心原則:旁白優先,精確時間錨定

在任何影像素材之前生成旁白。/studio/tts 返回每個片段的精確時間長度以及逐字時間戳記——這些資料驅動整個時間線和所有焦點效果。然後再大量錄製素材,並將每個片段符合其旁白段落。先剪輯後配音會導致脆弱的重新計時。

你通常無法播放或聽到輸出。請將此視為一個硬性限制:透過提取影格來驗證影片,並透過對成品檔案的片段執行 ASR 來驗證音訊內容/同步。所有內容都應能以這種方式檢查。

流程

  1. 為每個場景編寫分鏡——旁白文字、螢幕動作、字幕,以及(每個場景)旁白提到的元素名稱,以便焦點可以指向它們。目標語速約 2.1 字/秒(≈170 字 ≈ 80 秒)。複製 references/storyboard.example.json 到 <work>/storyboard.json。旁白的措辭應確保每個命名的元素在該場景的素材中確實可見且按順序出現。為耳朵而寫:單字應按照其口語方式拼寫,而非書面形式——展開縮寫和首字母縮略詞(例如 "regular expression" 而非 "regex","version three" 而非 "v3"),避免使用孤立的符號(~、/、&),當不確定時,將數字和單位寫為文字。TTS 會朗讀文字內容,ASR 會根據文字進行驗證,因此僅書面形式的簡寫不僅會發音錯誤,還會扭曲 WER。
  2. 生成旁白——scripts/generate_narration.py <storyboard.json>。將每個場景 POST 到 /studio/tts,從一個固定的聲音(使用者的 ref_audio,或是一個 voice 設計指令——詳見下文)複製聲音,進行 ASR 驗證,並寫入 narration/manifest.json,其中包含每個片段的 duration_s、wer 和逐字的 words。(詳見 references/studio-api.md。)
  3. 錄製目標——為應用程式/網站的每個場景錄製一個片段(參見錄製章節),以及一個命名的元素矩形地圖,用於後續焦點將指向的元素。
  4. 合成——scripts/compose.py <storyboard.json>:將素材放置在漸層舞台的框架內,燒錄 Pillow 字幕,對英雄鏡頭進行慢速縮放,應用由旁白錨定的焦點效果(縮放 + 圓環),場景間加入交叉淡變,將旁白放置在計算出的時間線上,並進行多路複用。
  5. 驗證——為每個場景生成膠片條;在每個焦點的語音字詞時間點提取一個影格,並確認高亮顯示位於指定的元素上;對兩到三個片段執行 ASR,以確認正確的台詞出現在正確的場景中。

先決條件

  • 可存取的 Studio API(預設 http://127.0.0.1:8100)。設定、複製以及對齊/字時間戳記合約詳見 references/studio-api.md。
  • 一個 3–15 秒的參考 WAV 檔案(24 kHz 單聲道)以及其精確的逐字稿,用於聲音複製——首先使用 /asr 確認逐字稿(複製品質取決於音訊↔文字的對齊,而不是「推薦」的長度)。
  • 整個影片使用一個聲音。 每個場景都是一次獨立的 /studio/tts 呼叫,因此只有當每次呼叫都複製同一個共享參考時,聲音才能保持一致。如果使用者提供了參考,則從中複製;否則,在分鏡中設定一個 voice 設計指令,generate_narration.py 會先設計一個片段並從中複製聲音,後續每個場景都從這個片段複製(已快取,因此重新執行會保持相同聲音)。如果兩者都沒有,則每個場景獨立合成,音色會在場景之間漂移——對於正式影片應避免此情況。
  • 帶有 avfoundation(macOS 錄製)、zoompan、xfade、gblur 的 ffmpeg。drawtext 通常缺失(無 libfreetype)——字幕使用 Pillow 渲染。
  • 對於網站目標:使用 Playwright(或 Puppeteer)進行確定性錄製並取得元素位置。

錄製目標

每個場景需要從目標產品取得兩樣東西:

  1. 一個螢幕錄製的片段(錄製時間要比旁白長——點擊後結果和旋轉圖示會在數秒後出現),以及
  2. 一個命名的元素矩形地圖:對於旁白將提到的每個元素,其矩形在素材畫素(合成片段使用的座標空間)中的位置。

目標的 UI 工具組決定了如何取得這些資訊。兩種後端:

macOS 應用程式——AppleScript + ffmpeg avfoundation

  • 使用 avfoundation "Capture screen N" 錄製,並即時裁切到應用程式視窗。探測一次(錄製約 1.5 秒,提取一個影格,確認 crop=W:H:X:Y)。顯示器是 Retina,因此實際裁切 = DPR × 邏輯座標(DPR 通常是 2)。
  • 使用 System Events 驅動。找到適用於這個應用程式工具組的可靠基本操作——它們因應用而異。 以下是常出現的通用注意事項:
    • 在 SwiftUI/AppKit 列表上,座標點擊通常無法觸發;改為對元素使用 AX select/AXPress。
    • 分段控制項會以 AXRadioButton 的形式暴露;透過角色查詢它們。
    • 在檢視切換後立即進行 AX 查詢可能會發生競爭(回傳空結果)——重試,或完全避免在會話中進行導航。
    • 如果導航不穩定,重新啟動應用程式使其已處於所需狀態(透過啟動引數 / 環境變數 / 應用程式支援的 URL scheme),然後只觸發那個需要拍攝的動作。便宜且確定性高。
  • -capture_cursor 0(AX 動作不會移動滑鼠指標,因此遊標會保持在影格之外)。如果需要可見遊標,在後製中合成一個(參見焦點章節)。
  • 元素地圖: 查詢每個元素的 AX position+size 並轉換為素材畫素:(global − window_origin) × DPR。如果工具組隱藏了欄位矩形,從一個有網格的素材影格中測量。如果素材影格與過時的 AX 數字不一致,請相信素材影格(滾動狀態可能不同);驗證每個焦點影格。

網站——Playwright(推薦勝過螢幕錄製)

  • 使用 recordVideo 錄製;設定 recordVideo.size 等於 viewport,並在合成前將 webm 標準化到你的 FPS。
  • 座標空間(第一大陷阱): Playwright 以 viewport 大小錄製,因此當 recordVideo.size == viewport 時,素材畫素 == CSS 畫素。deviceScaleFactor: 2 只會讓渲染更銳利——它不會縮放錄製的影片,而 recordVideo.size 大於 viewport 只會將多餘的區域填充為黑色(頁面保持左上角 1 倍大小,不會被放大填滿)。所以 boundingBox() 直接給出素材畫素——不要乘以 DPR。(如果你曾經以不同尺寸錄製,請透過 recordedSize / viewport 來縮放矩形。)總是進行驗證:在錄製所有場景之前,先在一個提取的影格上疊加一個已知矩形——錯誤的 DPR 假設會默默地將所有焦點圓環放在錯誤的位置。
  • 在一個固定的滾動位置捕獲所有矩形: 先完成所有滾動,讓它穩定,然後讀取所有的 boundingBox(),然後保持住。圓環存在於素材座標中,並且必須在鏡頭縮放/平移時保持粘附。如果你想要自動焦點,從頁面時鐘發射互動軌跡。
  • 先穩定頁面:停用 CSS 動畫 / prefers-reduced-motion、關閉 Cookie 橫幅、隱藏捲軸,並使用 waitForLoadState('networkidle'),這樣在鏡頭前就不會彈出任何東西。透過在導航前注入 localStorage 的 addInitScript 實現自動認證(如果應用程式支援)。
  • 移動:對於長頁面,捕獲全頁截圖並平移它(垂直的肯·伯恩斯效果),而不是錄製抖動的即時滾動。

實際模型素材——展示真實輸出,隱藏等待。 當一個場景必須即時運行一個慢模型(真實字幕/聊天/推論),錄製真實流程但對等待進行時間壓縮:標記每個 click → result 視窗(從頁面啟動開始的單調時鐘),然後只使用 ffmpeg 壓縮那些視窗(trim+setpts+concat;動作保持 1 倍速),並凍結最後一個影格(tpad=stop_mode=clone),這樣任何場景的持續時間都可以在結果上播放。先透過一個一次性請求熱身模型——冷載入可能是熱呼叫的 10–40 倍(例如視覺模型:~38 秒冷 → ~5 秒熱)。在壓縮後的片段上配音並對齊旁白時間;將這些場景保持為簡單播放(動作本身提供了動感)。 完整配方 + 程式碼片段:references/playwright-recording.md。

一個完整的 macOS 工作範例(精確的選擇器、環境鉤子、裁切矩形、元素矩形以及一個一鍵啟動的錄製器)在 references/video-studio-mlx-app.md 中——該範例恰好示範了承載 Studio API 的同一個應用程式,但請將其具體細節視為說明性質;你的目標將有自己的特性。

合成(scripts/compose.py)

基於配置,與目標無關。每個場景變成一個標準化的 1080p 片段:素材縮放後放入一個帶有框架的卡片中,置於深色漸層舞台(軟陰影)上,一個 Pillow 字幕(步驟說明用的下三分之一長條,英雄場景用的大標題+副標題遮罩),片段 + 字幕淡入淡出,然後是一個共享的最終調色(顏色 + S 曲線 + 冷色陰影 + 暗角 + 底片顆粒 + 去條帶),使得不同的錄製內容看起來像是一部導演的電影("grade": false 可停用,或者傳入一個區塊來調整 strength/tint)。英雄場景會獲得一種電影化處理:在靜止畫面上進行緩動(ease-out)漂移的肯·伯恩斯推進,卡片後方放置一個磨砂深色背景板,以及一個分階段的標題然後副標題淡入效果。片段以每個場景的 xfade 轉場(預設 fade;可為每個場景設定 transition/xfade_dur——fadeblack 連結到英雄場景效果不錯)。音訊:旁白透過 adelay 放置在主時間線上並透過 amix 混合(normalize=0);可選的 music 背景音樂會在語音下方進行側鏈-閃避,最終混音會經過 loudnorm 處理,達到 −16 LUFS(僅語音也會被處理)。

焦點效果——旁白錨定(縮放 + 圓環跟隨詞語)

焦點必須指向旁白正在說的內容,並且正好在它說出的那一刻——因此它是作為 詞語 → 元素 編寫的,時間來自字時間戳記,絕非手動放置秒數,也絕不會在整個場景中鎖定在一個元素上。一個場景宣告一個 view(哪個元素矩形地圖)和一個 focus 列表(元素/檢視名稱就是你自己目標應用程式中的名稱):

"view": "main",
"focus": [
  { "say": "search",   "element": "search_field" },
  { "say": "results",  "element": "result_list" },
  { "say": "generate", "element": "primary_button", "zoom": 1.7 }
]

合成器如何解析它:

  • 何時——resolve_phrase 在片段的 words 中找到與 say 匹配的連續單字序列,並返回 [start,end]。重複的詞語不會有歧義:詞語列表是按位置排列的——透過 occurrence 選擇(預設為第一個)。在片段時間 lead + word_start 時播放。
  • 何處——element 是 elements.json 中該場景的 view 下的一個矩形(或一個 map:key 來參考一個共享地圖,例如一個持續存在的側邊欄)。
  • 鏡頭——多關鍵幀 zoompan(focus_camera),基於絕對 on 的 smoothstep。在兩個焦點之間,它預設會直接滑動 target→target;只有在當下一個目標 BOTH(同時滿足)距離很遠(超出先前縮放的視口)且間隙很長時(focus_gap_full,約 2.2 秒),它才會返回全螢幕檢視——因此對於相鄰/已可見的元素,只會稍微平移,而不是突兀的縮小/放大。平移是恆定速度(持續時間 = 距離 ÷ focus_pan_speed 畫素/秒,下限為 focus_move_min):鏡頭保持先前的構圖,然後以固定的畫素/秒滑動,在下一個詞語開始時到達——近距離和遠距離平移感覺相同,而不是「先慢後快」。"focus_pan": true 會在所有地方強制直接滑動。
  • 圓環——在鏡頭之前以素材座標繪製,因此當縮放/平移時它會粘附在元素上;在詞語前後淡入淡出。
  • 縮放和圓環是解耦的,且縮放會自動限制以適應畫面(fit_zoom):縮小縮放比例,使高亮元素保持完整取景,而一個寬的目標會下降到僅圓環(z=1),以免被裁切。預設情況下不要將它們配對——兩者都只是為了引導視線;選擇適合目標大小的方式。ring:false 會產生溫和的縮放,沒有圓環。

支援資料與擴展:

  • 元素地圖(elements.json):每個檢視中命名的矩形,單位為素材畫素。參見錄製章節以了解如何獲取它們;透過檢查每個焦點影格來驗證。
  • 錄製的尺寸要大於最終呈現的尺寸,這樣縮放時才能保持清晰——鏡頭會將原始素材裁切到舞台上的尺寸,因此約 1.7 倍的縮放仍具有真實畫素。在 macOS 上,Retina 錄製已經超採樣。在網頁上,deviceScaleFactor 不會放大錄製的影片(參見錄製章節)——為了實現超採樣,請使用比舞台卡片更大的 viewport/recordVideo.size 來錄製(例如,以 1920 寬度錄製,放入約 1456 的卡片),而不是提高 DPR。
  • 錄製器可以發射一個互動軌跡(emit_track.py),這樣 track_to_effects 可以為每次點擊自動推導出縮放+圓環;內聯的 focus 是精確路徑。結構是開放的,可以使用相同的矩形 + 字時間來實作 cursor/spotlight 疊加層。

設計說明(為何使用詞語→元素,而不是 API 端提示標記): 字時間戳記本質上就是一個位置列表,因此合成器擁有「哪個元素 / 哪個出現次數」的決定權——Studio API 保持為一個乾淨的基本單元(音訊 + 字時間),可用於示範任何產品。素材必須在該時刻實際顯示命名的元素(未滾動/靜止);旁白的措辭應確保做到這一點。

時間線數學(保持影片和音訊一致)

  • 場景持續時間 d_i = narration_i + pad_i(pad ≈ 2 步驟 / 3.4 英雄)。
  • 場景在主時間線上的起始時間是根據轉場累積的:start_0 = 0,start_i = start_(i−1) + d_(i−1) − T_i,其中 T_i 是進入場景 i 的 xfade 持續時間(每個場景的 xfade_dur,預設 xfade;限制在相鄰兩個片段之下)。當每個 T_i = T 時,這簡化為 Σ d_(<i) − i·T。
  • 將片段 i 的旁白放置於 start_i + lead(lead ≈ 0.8,在傳入的交叉淡變之後)——這是相同的重新計算的 start_i,因此音訊保持同步。確保 tin_i + d_i ≤ 來源片段長度。

驗證

(原文至此截斷)

共 145 行

相關技能