用代码制作YouTube视频:Shorts和长视频
您像动态设计师一样构建视频,但使用代码:HTML页面根据时间值绘制任意帧,旁白设定时间节奏,脚本在任何人上传之前渲染、混合并证明结果是有效的。
script.json ──► OmniVoice (MCP) ──► voice/*.wav ──► timeline.py ──► timeline.js ─────────┐
│ 格式: short | long | long-4k ▼
└─ 风格预设 ─► style.css / style.js ─────────────────────► page(s).html (seek(t), K.layout 根据格式)
│ check_page ► stills ► render (缓存片段)
音乐 (仅在要求时) ─► make_music.py ─┐ ▼
音效 (CC0) ────────────────────────┴─► mix_audio.py ─► mix.wav ─► mux ─► final.mp4 ─► verify_video.py
(长视频还包括: chapters.txt, captions.srt, thumbnail.jpg)
下面$SKILL表示此技能所在文件夹。所有操作都通过一个CLI:python3 $SKILL/scripts/short.py <命令>。
格式
short | long | long-4k | |
|---|---|---|---|
| 帧尺寸 | 1080×1920 (9:16) | 1920×1080 (16:9) | 页面1920×1080,输出3840×2160 |
| 时长 | ≤ 180 秒 (最佳 < 60 秒) | 任意 (典型5–15分钟) | 任意 |
| 安全区 | x 60–940, y 288–1440 (Shorts UI) | x 96–1824, y 54–1026 (标题安全区) | 与长视频相同 |
| 字幕 | 硬编码入画面 (匹配风格) | captions.srt 用于YouTube;可选硬编码 | 与长视频相同 |
| 附加内容 | — | 章节,每章节一个页面,缩略图1280×720 | 与长视频相同 |
配置文件位于 engine/formats.json。页面使用 K.W/K.H 和 K.layout({short, long}) 表,因此一个项目可以构建为任意格式。对于任何16:9视频,请阅读 reference/long-form.md。
文件夹内容
| 路径 | 说明 |
|---|---|
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 | 正确性检查:尺寸、宽高比、编码、帧率、帧数、音画同步、响度、黑/冻结帧、章节、安全区表格 |
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)。当明显时推断(“一个Shorts”、“一个10分钟的视频”)。
- 主题和观众必须记住的一个要点。如果用户有脚本、文章或URL,也请提供。
- 风格:
short.py styles。默认editorial。一旦选择,阅读styles/<名称>/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 "<台词>"
如果片段静音、剪裁或速度不合理(过快/过慢),导入会失败——重新生成这些片段。如果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帧屏幕上必须有有意义的内容;Shorts每1–2秒,长视频每几秒必须有内容移动。
- 视觉变化必须落在口头单词上(
K.cue),而不是猜测的时间。 - 音乐仅在要求时添加。音效遵循风格默认值(用户可以关闭)。
- 风格是受相关创作者启发;绝对不要使用他们的标志、吉祥物、角色、开场或名字在屏幕上。
- 绝不说音频“听起来不错”——而是报告测量数值和需要检查的时间戳。
参考文件
| 在什么时候阅读 | 文件 |
|---|---|
| 编写Shorts时 | reference/shorts-design.md |
| 任何16:9/长视频时 | reference/long-form.md |
| 构建页面,script.json schema | reference/page-contract.md |
| 使用工具包时 | reference/kit-api.md |
| 设计场景时 | reference/scene-patterns.md |
| 选择/制作风格时 | styles/README.md, styles/<名称>/STYLE.md |
| 生成旁白时 | reference/voice-omnivoice.md |
| 音乐和音效时 | reference/music-and-sound.md |
| 检查失败时 | reference/verification.md, reference/troubleshooting.md |