產生影片
取得使用者提供的錄影,並將其轉換為完成的影片。錄影是主軸並驅動時間軸;此技能進行編輯(靜音 + 選擇的錯誤/節奏)和增強(疊加層),然後渲染並產生發佈內容。它不會製作合成影片 —— 對於公關驅動的合成促銷影片,請改用 hyperframes-video。
品質原則(不可協商):每個影片處理步驟都應保留原始品質。 絕不能讓工具以低品質重新編碼影片。去靜音和裁剪操作使用原始影片的近無損 CRF 12 值執行(auto-editor 僅用於偵測靜音,從不進行編碼——其預設值會將影片壓縮至約 0.6 Mbps),渲染時也使用 CRF 12。CRF 可為靜態螢幕錄影產生小檔案;這是高品質,而非有損。
與其他技能的關係(委派,而非重新實作)
/transcribe-video— 所有轉錄工作(返回單字級別的transcript.words.json)。呼叫它;不要手動轉錄。hyperframes— 合成創作規則(視覺識別門、先佈局後動畫、時間軸合約、影片/疊加層分層)。在編寫/掛載任何合成 HTML 之前先呼叫。hyperframes-cli— 每個npx hyperframes指令(init、lint、inspect、preview、render)。gsap— 用於疊加層的 GSAP 時間軸/緩動模式。youtube-copy— YouTube 標題/描述/標籤/章節(P6)。blog-post— 部落格文章(P6)。social-copy— X/Bluesky/LinkedIn/Reddit 文案(P6)。
捆綁的資產
scripts/desilence.mjs— auto-editor 靜音移除 + 前/後時長。scripts/extract-frame.mjs— 單幀抓取(畫面偵測 + 螢幕上高亮)。scripts/bake-cuts.mjs— 用於 P2 的 ffmpeg 裁剪/拼接剪切器(密集關鍵幀)。templates/overlays/*.html— 9 個疊加層子合成模板(按實例填充;子合成是已安裝 CLI 中的獨立 HTML 文件——請閱讀每個文件的標頭註解)。templates/project/{DESIGN.md,styles.css}— 疊加層使用的視覺識別門 + 品牌var(--brand-*)標記。references/—mistake-detection.md、overlay-triggers.md、framing-safe-zones.md、frame-analysis.md。- P6 內容生成委派給
youtube-copy、blog-post和social-copy技能(無自帶 LLM 腳本)。
門控(不可協商)
- P2 錯誤審查是視覺化的,絕非終端形式 — 每當存在 ≥1 個標記時,代理程式必須建立 hyperframes 標記預覽(在影片上標記每個標記區段)並啟動它,讓使用者通過觀看來決定。請勿將標記以終端表格/問題的形式呈現給使用者決定,也不要讓預覽成為可選項或詢問「要我顯示嗎?」——只需建立並打開它。在終端中顯示標記的簡短摘要可以,但決策介面是預覽。永遠不要自動套用裁剪/加速。
- P4 疊加層計劃批准 — 呈現帶有時間戳記的疊加層表格;在獲得批准之前不要建立。
- 預覽始終由代理程式啟動 — 對於 P2 審查和 P5 審查,代理程式會啟動
npx hyperframes preview並自行打開瀏覽器分頁。永遠不要要求使用者執行預覽或打開 URL,也永遠不要用純終端摘要取代即時預覽。 - 明確渲染硬性門控 — 渲染僅在使用者明確的渲染指令(「render」、「ship it」)後執行。渲染後,編輯請求會返回預覽循環,並且在使用者再次明確要求之前不會重新渲染。每次渲染都需要其自己的全新指令。這會覆蓋任何「使用明智的預設值/非互動式/直接發佈」的措辭。
「使用明智的預設值」/「不要問問題」會跳過配置問題(P0)和迭代提示——它永遠不會跳過批准門控、代理程式啟動的預覽或明確渲染門控。
流程
前置檢查 — 檢查依賴項與技能(首先執行,在 P0 之前)
在進行任何工作之前驗證環境;告知使用者缺失了什麼以及如何修復。
- auto-editor(P1 去靜音所需):執行
auto-editor --version。如果未安裝,請停止並告知使用者:「auto-editor 尚未安裝 - 請使用pipx install auto-editor(或pip install auto-editor)進行安裝,然後重新執行。」 如果沒有它,請勿嘗試 P1。 - ffmpeg / ffprobe(必備 — P2 裁剪、P4 畫面分析、P5 渲染、音訊):執行
ffmpeg -version。如果缺失,請停止並告知使用者安裝 ffmpeg 並將其添加到 PATH。沒有它,管道就無法執行。 - Docker(用於
/transcribe-video):docker info。如果守護行程未執行,請發出警告(啟動 Docker Desktop)。 - Node >= 22:
node --version。如果版本過舊,請發出警告。 - 必備技能 — 確認這些技能可用(嘗試呼叫/檢查技能列表);對任何缺失的技能發出警告,並說明它會阻塞哪個階段:
transcribe-video(P2/P3 轉錄)、hyperframes+hyperframes-cli+gsap(P2/P4/P5 合成與渲染)、youtube-copy+social-copy(P6)。blog-post僅在使用者選擇啟用部落格時使用(P6,可選)。
- 用一個簡短區塊總結前置檢查結果(哪些存在,哪些缺失)。僅在使用者明確表示要在沒有必備依賴項/技能的情況下繼續時,才繼續執行(並註明降級的結果)。
P0 — 輸入與配置
- 輸入:原始錄影的路徑(必填)。
- 可選:用於真實程式碼基礎的儲存庫/檔案;視覺風格/品牌(否則執行
hyperframes視覺識別門——從儲存庫中偵測,否則詢問 3 個風格問題;將templates/project/DESIGN.md+ 品牌值寫入styles.css);疊加層密度(稀疏 / 平衡 / 豐富)。 - 單一輸出資料夾(
<OUT>): 此技能產生的所有內容都位於一個資料夾下,預設為<recording-dir>/<video-slug>-produced/(可使用使用者提供的路徑覆蓋)。立即建立它。最終結構:
所有後續階段都寫入<OUT>/ final.mp4 # 渲染後的影片(P5) hyperframes/ # HyperFrames 專案:index.html、styles.css、DESIGN.md、compositions/、renders/(P4–P5) transcript.txt # 最終編輯後的逐字稿(P3 / P6) transcript.srt transcript.words.json youtube.md # P6 socials.md # P6 blog.md # P6 .work/ # 中間檔案:01_desilenced.mp4、02_edit_N.mp4、frames/(可在 P7 中刪除)<OUT>內部——永遠不要將輸出分散到其他地方。下面的<work>=<OUT>/.work。
P1 — 去靜音(無損)
node scripts/desilence.mjs <input> --out <work>/01_desilenced.mp4 --margin 0.3s
desilence.mjs 僅使用 auto-editor 來偵測靜音範圍(--export v3),然後使用 ffmpeg 以近無損 CRF 12 從原始檔案裁剪,保留原始音訊。不要讓 auto-editor 對輸出進行編碼 — 其預設重新編碼會將影片壓縮至約 0.6 Mbps 並永久模糊影片(尤其是臉部);下游的任何位元率都無法恢復。報告前/後時長和移除的秒數。這將成為工作副本。
P2 — 錯誤與節奏審查循環(批准門控)
- 轉錄工作副本:在
<work>/01_desilenced.mp4上呼叫/transcribe-video,使用--out <work>→ 工作逐字稿(中間產物;將被 P3 的最終逐字稿取代)。 - 根據
references/mistake-detection.md偵測標記(裁剪 + 速度加速),對齊到單字邊界。 - 始終(當存在 ≥1 個標記時)建立視覺審查。 建立一個輕量化的 hyperframes 專案,以去靜音後的影片為基底軌道;在每個標記區段的影片上放置視覺上不同的臨時標記(裁剪 = 紅色劃線,加速 = 琥珀色快進,每個標記都標註摘錄及其索引)。代理程式啟動
npx hyperframes preview並自行打開瀏覽器(根據references/framing-safe-zones.md)。這是決策介面——永遠不要用終端表格取代它。一個單行終端備註(「預覽中標記了 3 個標記——請查看並告訴我哪些要裁剪/加速/保留」)是終端應攜帶的最大資訊量。 - 使用者觀看標記後的預覽,並為每個區段選擇:裁剪 / 速度加速(倍數,預設約 1.5–2×)/ 保留 / 新增自己的範圍。
- 套用選擇 →
<work>/02_edit_N.mp4,然後重新預覽:- 裁剪: 使用
node scripts/bake-cuts.mjs <input> --out <work>/02_edit_N.mp4 --cut s,e --cut s,e …(ffmpeg 預設以近無損 CRF 12 進行裁剪/拼接——一次處理即可同時裁剪影片和音訊)。不要對錯誤裁剪使用 auto-editor--cut-out— 其可變參數會錯誤地將最後一個範圍分配為位置輸入,它會進行有損重新編碼,而且使用 select-filter 方法會導致音訊不同步。 - 速度加速: auto-editor
--set-speed-for-range speed,s,e(保留音高);每次呼叫傳遞一個範圍,或將--set-speed-for-range放在命令列的最後,以避免相同的可變參數陷阱。 - 所有裁剪/加速時間戳記都基於去靜音後的時間軸(標記所來自的逐字稿)。在同一輪中針對該時間軸套用裁剪和加速。
- 裁剪: 使用
- 循環,直到使用者說「完成」。漂移防護:在大約 10 輪後,提議重置到較早的中間版本。最終產物:
<work>/final_cut.mp4。
裁剪和加速在此處(P3 之前)被烘焙到影片中,以便最終逐字稿的單字時間戳記與編輯後的時間軸匹配。
P3 — 最終轉錄
在 <work>/final_cut.mp4 上呼叫 /transcribe-video,使用 --out <OUT>,以便 transcript.txt / transcript.srt / transcript.words.json 放置在輸出資料夾的頂層。這個帶有單字時間戳記的逐字稿是所有疊加層(P4)的同步來源,也是內容生成(P6)的輸入。
P4 — 疊加層設計與建立(批准門控)
- 畫面偵測(
references/framing-safe-zones.md):使用extract-frame.mjs取樣幀,分類階段,與使用者確認階段 + 安全區域。 - 疊加層觸發偵測(
references/overlay-triggers.md):掃描帶有單字時間戳記的逐字稿 → 疊加層計劃行{start、est_duration、type、content、safe_zone、why}。對於螢幕上的程式碼,使用references/frame-analysis.md(提取幀 → 定位 → 標準化框 → 穩定性防護)。對於程式碼卡片,如果儲存庫可用則使用,否則合成(標記為合成的)。 - 自我改進循環(≥2 次迭代):考慮密度,強制間隙和停留時間最小值,根據活動階段的 safe_zone 驗證每個疊加層。
- 批准門控: 呈現帶有時間戳記的表格;使用者編輯/移除/重新計時/新增。顯示合成的程式碼以供驗證。在獲得批准之前不要建立。
- 建立(首先呼叫
hyperframes+gsap):npx hyperframes init <OUT>/hyperframes --video <OUT>/.work/final_cut.mp4(專案位於<OUT>/hyperframes;基底:影片軌道 0muted playsinline;音訊在單獨的軌道上,音量為 1,以便播放語音)。閱讀生成的index.html以了解此 CLI 版本的子合成包含語法。- 將
templates/project/styles.css(包含已確認的品牌值)複製到<OUT>/hyperframes。 - 對於每個已批准的行:實例化匹配的
templates/overlays/*.html,為其指定唯一的組成標識符 +data-composition-id,填充其{{tokens}},設定data-start= 逐字稿時間戳記,data-duration= 停留時間,將其掛載到影片上方。放大效果會縮放影片的包裝 div(永遠不會縮放<video>)。 - 輸出尺寸繼承來源錄影。
- 可讀性(不可協商):所有疊加層文字在任何影片背景上都必須清晰可讀。 每個文字群組都位於接近不透明的深色面板上(
rgba(8,10,14,0.92),圓角,微妙的邊框/陰影);標題/正文為白色(var(--brand-text)),次要文字/提示文字/元資料為淺灰藍色(#CBD5E1)。永遠不要對正文/副標題/提示文字使用var(--brand-accent)/var(--brand-primary)— 強調色僅用於橫條、邊框、標記掃掠、圖標和大型顯示詞彙(且僅當它們在面板上達到約 4.5:1 的對比度時)。如果不確定,請將文字設為白色。npx hyperframes validate(WCAG 對比度)必須通過,且無對比度警告。
P5 — 預覽與渲染(強制代理程式啟動預覽 + 明確渲染門控)
npx hyperframes lint+npx hyperframes inspect(溢出 + 安全區域) +npx hyperframes validate(對比度)。修正直到乾淨為止。- 代理程式啟動
npx hyperframes preview並打開瀏覽器。 關於疊加層的自由迭代循環。 - 預渲染審計:每個疊加層都在其階段的安全區域內;停留時間最小值;沒有兩個疊加層同時爭奪同一區域;lint/inspect/validate 乾淨。
- 僅在使用者明確的渲染指令時: 以近無損 CRF 12 渲染。預設的
standard品質會以約 1.4 Mbps 編碼,並明顯壓縮影片;始終傳遞一個較低的 CRF 值:
(從npx hyperframes render --output <OUT>/final.mp4 --crf 12<OUT>/hyperframes執行。CRF 12 是近無損的;不要使用--video-bitrate,因為期望一個大檔案——對於靜態螢幕錄影,CRF 會以全品質產生一個小檔案,這是正確的,不是低品質。)最終的 mp4 保留原始音訊。渲染後,進一步的編輯將返回循環,並需要一個新的明確渲染指令。 - 品質說明: Chrome 捕獲是無損的 1:1 螢幕截圖(經驗證:渲染輸入 == 文字和臉部的輸出),因此低 CRF 渲染會保留提供給它的影片。唯一會破壞品質的是有損的上游步驟——這就是為什麼 P1 去靜音和 P2 裁剪都使用原始影片的近無損 CRF 12 來執行。不要添加額外的重新編碼過程。對於絕對零代損的影片,一個進階方法是將僅包含疊加層的內容渲染為透明的
--format webm/mov,然後使用 ffmpeg 將它們合成到裁剪後的影片之上(然後透過 ffmpeg 應用放大效果)——很少需要。
P6 — 內容生成(委派給專門技能)
通過呼叫專門技能來生成發佈內容,每個技能都基於最終編輯後的逐字稿(P3 — 傳遞帶有時間戳記的 transcript.srt,以便 YouTube 章節獲得準確的時間),並將每個輸出寫入 <OUT>:
youtube-copy→<OUT>/youtube.md(吸引點擊的標題、描述、標籤、章節)。social-copy→<OUT>/socials.md(針對各平台優化的 X/Bluesky/LinkedIn/Reddit 貼文)。blog-post→<OUT>/blog.md(如果使用者選擇,則為完整文章)。- 最終的
<OUT>/結構:youtube.md,socials.md,可選的blog.md。
P7 — 清理與總結
- 除非使用者要求保留,否則從
.work/中刪除可重新產生的中間檔案(01_desilenced.mp4、02_edit_N.mp4、frames/)。 - 報告最終的影片位置 (
<OUT>/final.mp4)、時長、整體編輯統計資料(移除的靜音、裁剪的錯誤、疊加層數量)、以及為每個生成的文案給出一個簡短的摘要。
覆蓋與故障排除
拼寫 auto-editor 與 ffmpeg 參數
- 用於裁剪的
auto-editor --cut-out s,e有一個可變參數 bug:最後一個範圍被視為一個位置輸入。不要使用它。 改用scripts/bake-cuts.mjs進行裁剪,並使用--set-speed-for-range(僅限一個範圍,或將其放在最後)進行加速。 ffmpeg -ss … -to …vs-t:使用-to(絕對停止時間)。-t是持續時間,如果被誤用會導致不可預測的結果。- 帶有
-ssseek 的ffmpeg -c copy:Open GOP 會導致編碼器參考不存在幀,從而導致損壞/停頓。scripts/bake-cuts.mjs通過密集關鍵幀構建來處理這個問題。
品質保證
- 永遠不要讓 auto-editor 對最終影片進行編碼(其預設值為約 0.6 Mbps)。僅將其用於偵測。
- 所有 ffmpeg 裁剪和渲染都使用 CRF 12。 如果客戶端抱怨檔案大小:解釋說 CRF 對於靜態螢幕錄影會產生小檔案,且更改為位元率會無謂地增加位元數,或浪費地編碼靜態元素。CRF 12 是正確的。
- 如果在預覽中疊加層亂碼: 檢查
data-start/data-duration是否為有效的逐字稿時間碼,以及templates/overlays/*.html的data-composition-id是否唯一。
工具可用性
- 如果
npx hyperframes失敗: 確認hyperframes-cli是世界可安裝的 npm 套件或其他方式。 - 如果
/transcribe-video不可用: 無法進行 P2/P3;回退到純手動編輯而不疊加層。告知使用者。 - 如果 Docker 關閉:
/transcribe-video失敗;提供如何手動轉錄的說明,或暫時繞過它(P2 需要它來進行標記;如果跳過,告知使用者限制)。