Communitygithub.com

yt-video

將 YouTube 影片轉化為程式碼:支援 Shorts(9:16,1080x1920)與長片(16:9,1080p 或 4K)。透過 seek(t) 動畫化的 HTML 頁面、OmniVoice(本地 TTS,支援語音克隆與語音設計指令,透過 MCP 連接)、可選的程式生成音樂,並使用 ffmpeg 渲染為 MP4,最後以腳本驗證。

yt-video 是什麼?

這個 AI 代理技能,yt-video,讓開發者能像動態設計師一樣,但用程式碼來打造 YouTube 影片。它支援 Shorts(直立 9:16)和長片(橫向 16:9,最高 4K 解析度)。核心概念是將影片視為時間的純函數:HTML 頁面根據 seek(t) 繪製任何影格,敘述音軌設定時間,一系列腳本負責渲染、混合音訊,並透過 verify_video.py 驗證最終 MP4 的完整性(包含尺寸、編碼、影格數、影音同步、音量等)。技能內建 8 種風格預設(如 3Blue1Brown 數學風格、KodeKloud DevOps 風格、Fireship 開發新聞風格),以及 OmniVoice 的 TTS 語音克隆與設計功能。工作流程從簡報收集開始,接著以 script.json 撰寫逐場景腳本,透過 MCP 生成語音,建立時間軸,建構 HTML 頁面(使用 K.layout 確保兩種格式相容),最後進行檢查、渲染與驗證。音樂與音效為選用,除非使用者要求,否則不會添加音樂。此技能特別適合將腳本或主題轉化為有旁白的動畫或動態圖形影片,包括 Shorts、Reels、垂直影片或 YouTube 解說影片。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Shyamnath-Sankar/video-generation-skill/tree/HEAD/yt-video

在你喜歡的 AI 中提問

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

說明文件

從程式碼生成 YouTube 影片:Shorts 與長片

您像動態設計師一樣建構影片,但用的是程式碼:HTML 頁面根據時間值繪製任何影格,旁白設定時間,腳本負責渲染、混合,並在任何人上傳前證明結果是有效的。

script.json ──► OmniVoice (MCP) ──► voice/*.wav ──► timeline.py ──► timeline.js ─────────┐
   │ format: short | long | long-4k                                                         ▼
   └─ style preset ─► style.css / style.js ─────────────────────► page(s).html (seek(t), K.layout per format)
                                                                     │ check_page ► stills ► render (cached chunks)
music (only if asked) ─► make_music.py ─┐                            ▼
sound effects (CC0) ─────────────────────┴─► mix_audio.py ─► mix.wav ─► mux ─► final.mp4 ─► verify_video.py
                                          (long-form also: chapters.txt, captions.srt, thumbnail.jpg)

$SKILL 代表此技能的資料夾。所有操作都透過一個 CLI 執行:python3 $SKILL/scripts/short.py <command>。

格式

shortlonglong-4k
畫格1080×1920 (9:16)1920×1080 (16:9)page 1920×1080, output 3840×2160
長度≤ 180 秒(最佳 < 60 秒)任意(通常 5–15 分鐘)任意
安全區域x 60–940, y 288–1440(Shorts UI)x 96–1824, y 54–1026(標題安全)與 long 相同
字幕內嵌(樣式)captions.srt 供 YouTube 使用;可選內嵌與 long 相同
額外項目—章節、每章一頁、縮圖 1280×720與 long 相同

設定檔位於 engine/formats.json。頁面使用 K.W/K.H 以及 K.layout({short, long}) 表格,因此一個專案可以建構成任一種格式。閱讀 reference/long-form.md 以了解任何 16:9 影片。

資料夾內容

路徑說明
scripts/short.py管線 CLI:doctor、styles、init、style、kit、timeline、check、stills、thumb、music、mix、render、mux、verify、build
scripts/timeline.py語音時長 → 場景時間、單字提示、字幕、音效提示、節拍對齊、頁面段落、章節、SRT
scripts/import_voice.py匯入 OmniVoice 片段:轉換、修剪靜音、拒絕失敗的 TTS 錄音
scripts/make_music.py合成的背景音樂(7 種情緒),基於節拍網格,任意長度。僅在使用者要求音樂時使用
scripts/mix_audio.py語音 + 音樂(閃避)+ 音效 → −14 LUFS,真實峰值 ≤ −1.5 dBTP
scripts/verify_video.py正確性檢查:大小、長寬比、編碼、fps、影格數、影音同步、音量、黑/凍結影格、章節、安全區域圖表
engine/formats.json格式設定檔(尺寸、安全區域、字幕預設、限制)
engine/render.cjsPlaywright 捕捉 → ffmpeg H.264(動態模糊、影格範圍、4K 的 2× 捕捉)、連絡表
engine/check_page.cjs渲染前檢查:頁面合約、字型、確定性、安全區域、字幕、文字大小、空白影格
engine/kit.js動畫工具包(彈簧、提示、字幕、轉場、每種格式的佈局、類似 Manim 的繪製/書寫)
template/一個完整可運作的影片(編輯風格),可建構成兩種格式
styles/8 種風格預設:style.json + STYLE.md;3b1b-math 和 kodekloud-devops 有兩種格式的完整示範
assets/字型(OFL/MIT)和 CC0 音效
reference/當您進行到對應步驟時閱讀(結尾有表格)

工作流程

0. 設定(首次在機器上)

bash $SKILL/scripts/setup.sh          # playwright + chromium 安裝至 ~/.cache/yt-video, numpy/scipy
python3 $SKILL/scripts/short.py doctor

1. 簡報(一輪提問,然後開始工作)

在一則訊息中提問(可用 AskUserQuestion 時使用);跳過使用者已說過的內容:

  1. 格式:Short(9:16)或長片(16:9,1080p 或 4K)。若顯而易見則推斷(例如「一個 Short」、「一個 10 分鐘的影片」)。
  2. 主題與觀眾必須記住的一件事**。如果有的話,提供腳本、文章或 URL。
  3. 風格:short.py styles。預設為 editorial。選定後閱讀 styles/<name>/STYLE.md。
  4. 語音:克隆(參考片段及其逐字稿)、設計(「女性、年輕成人、低音、英國口音」)或使用預設。參閱 reference/voice-omnivoice.md。
  5. 音樂:除非他們要求,否則關閉。如果要求:選擇情緒(make_music.py --list)。絕不添加使用者未要求的音樂。
  6. 長度:Shorts 20–45 秒(最長 180)。長片:他們的目標;規劃章節。

2. 撰寫腳本,然後取得批准

閱讀 reference/shorts-design.md(Shorts)或 reference/long-form.md(16:9)。撰寫 script.json(結構在 reference/page-contract.md 中):每個場景一個想法;每個場景的 visual 必須指定哪個說出的單字上要發生視覺變化;長片場景需有 chapter 標題,較長的影片則每章一個 page。向使用者展示場景表格(id、台詞、視覺、提示單字;長片需有章節),並等待批准或編輯後再生成音訊。絕不虛構事實、數字、引文或結果;UI 模擬中的範例值可以接受,但需列出為說明性質。

3. 建立專案

python3 $SKILL/scripts/short.py init videos/<slug> --style <style> --format short|long|long-4k

複製範本(或風格的 demo/)、kit.js、字型和風格標記。將您已批准的 script.json 放置到位(保留其 format)。

4. 使用 OmniVoice(MCP)進行旁白 → voice/<scene-id>.wav

遵循 reference/voice-omnivoice.md:找到 OmniVoice MCP 工具,使用相同的語音設定為每個場景生成一個片段,然後匯入每一個:

python3 $SKILL/scripts/import_voice.py <clip> videos/<slug> <scene-id> --text "<the line>"

它會在遇到靜音、裁剪或速度不合理快/慢的片段時失敗 — 重新生成這些片段。如果 OmniVoice 無法連線,請告知;您仍然可以基於估計的時間建立視覺內容,稍後再加入語音。

5. 時間軸

python3 $SKILL/scripts/short.py timeline videos/<slug>

寫入 timeline.js(場景和單字時間、段落、章節)以及 out/captions.srt,如果有章節則還會寫入 out/chapters.txt。視覺效果透過 K.cue('scene', 'word') 對齊單字。

6. 建構頁面

閱讀 reference/page-contract.md、reference/kit-api.md、reference/scene-patterns.md 以及該風格的 STYLE.md。當影片可能以兩種格式存在時,為每個佈局提供 K.layout({short, long}) 條目。每個視覺變化都應落在提示單字上。

7. 渲染前檢查(低成本,能捕捉大部分錯誤)

python3 $SKILL/scripts/short.py check  videos/<slug>      # 每個頁面必須通過
python3 $SKILL/scripts/short.py stills videos/<slug>      # out/stills*.png,安全區域以紅色標示

**親自檢視靜止畫面。**修正任何空白、被裁剪、重疊、無法閱讀、不符合風格或未對應到單字的內容。影格 0 必須已顯示鉤子。

8. 音樂(僅在要求時)與混合

python3 $SKILL/scripts/short.py music videos/<slug>       # 音樂關閉時無作用
python3 $SKILL/scripts/short.py mix   videos/<slug>

參閱 reference/music-and-sound.md。

9. 草稿 → 審閱 → 最終版

python3 $SKILL/scripts/short.py build videos/<slug> --draft   # 30 fps,無動態模糊,1080p:快速審閱副本
python3 $SKILL/scripts/short.py build videos/<slug> --final   # 動態模糊,crf 16,long-4k 時為 4K

build 依序執行 timeline → check → music → mix → render → mux → verify,並在第一個失敗處停止。渲染會分塊並快取,因此編輯後重新建構只會重做有變更的部分。先傳送草稿;在開始最終版之前告知預計耗時(長片最終版可能需要一些時間;請在背景執行)。

10. 驗證與交付

verify_video.py 在 build 內部執行;只有在印出 VERIFY PASSED 時,MP4 才算完成。開啟 out/verify_sheet_<mode>.png(影格 0 + 每個場景一個影格,UI/安全區域以紅色標示)並檢視它。reference/verification.md 解釋了每一項檢查。

對於長片,還要執行 short.py thumb videos/<slug>(或渲染一個專用的 thumbnail.html)。

交付內容:MP4、專案資料夾(index.html 可在瀏覽器中搭配真實音軌預覽),以及一則簡短的備註:場景或章節、說明性質的內容、語音設定、音樂情緒(或「無音樂」)、驗證摘要(LUFS、真實峰值、時長);對於長片還需包含 chapters.txt、captions.srt 和縮圖。您無法聆聽:請提供時間戳記供使用者以耳朵檢查(鉤子、音效最密集的時刻、音樂最大聲的時刻、每個章節的開頭)。

最重要的規則

  • seek(t) 是時間的純函數。在渲染路徑中不得使用 Math.random、Date.now、CSS 動畫/轉場或計時器。檢查器會強制執行此項。
  • 文字必須保持在格式的安全區域內。永遠不要硬編碼 1080/1920:請使用 K.W、K.H、K.SAFE、K.layout。
  • 影格 0 上必須有有意義的內容;每 1–2 秒(Shorts)或每幾秒(長片)必須有東西移動。
  • 視覺效果必須落在說出的單字上(K.cue),而不是在猜測的時間上。
  • 僅在要求時才加入音樂。音效遵循風格的預設(使用者可以關閉)。
  • 風格是受所列創作者啟發;永遠不要使用他們的標誌、吉祥物、角色、片頭或在畫面上顯示他們的名字。
  • 永遠不要說音訊「聽起來不錯」— 請報告測量的數字和需要檢查的時間戳記。

參考檔案

何時閱讀檔案
撰寫 Short 時reference/shorts-design.md
任何 16:9 / 長片reference/long-form.md
建構頁面、script.json 結構reference/page-contract.md
使用工具包reference/kit-api.md
設計場景reference/scene-patterns.md
挑選/製作風格styles/README.md, styles/<name>/STYLE.md
生成旁白reference/voice-omnivoice.md
音樂與音效reference/music-and-sound.md
檢查失敗時reference/verification.md, reference/troubleshooting.md

相關技能