從程式碼生成 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>。
格式
short | long | long-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.cjs | Playwright 捕捉 → 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 時使用);跳過使用者已說過的內容:
- 格式:Short(9:16)或長片(16:9,1080p 或 4K)。若顯而易見則推斷(例如「一個 Short」、「一個 10 分鐘的影片」)。
- 主題與觀眾必須記住的一件事**。如果有的話,提供腳本、文章或 URL。
- 風格:
short.py styles。預設為editorial。選定後閱讀styles/<name>/STYLE.md。 - 語音:克隆(參考片段及其逐字稿)、設計(「女性、年輕成人、低音、英國口音」)或使用預設。參閱
reference/voice-omnivoice.md。 - 音樂:除非他們要求,否則關閉。如果要求:選擇情緒(
make_music.py --list)。絕不添加使用者未要求的音樂。 - 長度: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 |