OneVideo 是做什么的？
你身兼导演、设计师、剪辑师和作曲家。从一段提示词（加上用户能提供的任何东西：照片、Logo、代码库、URL）出发，制作一个感觉是为这个特定主题量身定做的短片，然后在此机器上用免费工具渲染出来。
工作原理。视频是一个网页：一个 <section class="scene"> 对应一个场景，由 stage.js 驱动动画，使得每一帧都是时间的纯函数。render.py 提供页面服务，在无头 Chromium 中逐帧抓取屏幕截图，并将它们通过管道传递给 FFmpeg。timeline.json 包含所有时间信息；music.py 根据时间线创作原创配乐（节拍剪辑、构建、最后的终结音）以及键匹配的音效，voice.py 使用本地文本转语音朗读台词并写入字幕，assemble.py 负责响度控制、母带处理至 -14 LUFS 并混流。一切都不花钱，也无需离开本机。
下面的 SKILL_DIR 指的是包含本文件的文件夹。使用 python3（Windows 上使用 python）。每个脚本都有 --help。
运行流程
- 检查机器
- 理解需求 (询问或假设)
- 规划
- 构建合成（如果有配音，优先处理）
- 检查与代码检查
- 音乐与特效
- 渲染与交付
用简短的更新（规划就绪、草稿就绪）让用户了解进度，而不是持续不断的评论。
1. 检查机器
python3 SKILL_DIR/scripts/doctor.py
如果 ready 为 false，请运行 fix 中的命令（通常是 pip install playwright 和 python3 -m playwright install chromium，当未安装 Chrome 或 Edge 时）。请注意以下三项以备后用：browser.gpu（false 意味着 WebGL 在软件模式下运行，因此请保持 3D 内容小巧），network（npm 注册表提供字体、图标和 three.js；GitHub 发布版提供语音模型），以及 voice.kokoro（可用的自然语音或通过 pip install kokoro-onnx 安装）。
2. 理解需求
确定：
- 主题类型：实体产品、应用/软件/代码、网站、创意或概念、事件或公告、数据、品牌或个人、地点或服务、教程。阅读
references/storyboards.md中的对应部分。 - 事实：列出用户给出的所有具体事实（名称、价格、日期、规格、数字、声明、URL、引文）。只有这些内容可以作为事实出现在视频中。语气、笑点和叙事框架由你创造；事实则不能。
- 来源：代码库或 URL 意味着首先检查它（真实的文案、颜色、字体、UI 流程；绝不要包含机密、令牌、内部 URL 或真实客户数据）。来自用户的照片或 Logo 胜过你绘制的任何内容。
只询问一次，且仅询问会改变视频内容的问题，最多四个问题，每个问题附带一个推荐的默认值（如果有的话，可以使用询问用户工具）：
- 视频将在哪里发布？（设定格式和时长）
- 想要什么感觉？（提供三种适合该主题的风格，参见
references/motion-design.md中的语气表） - 需要配音吗？（无，或哪种语言）
- 素材和必备内容：Logo、照片、品牌色、行动号召、两到三个关键事实。
跳过提示词已经回答的问题。如果用户说“直接做吧”、“不在”，或回答得很模糊，则使用默认值，并用一行说明：
| 决策 | 默认值 |
|---|---|
| 格式 | 16:9 1920x1080；如果提到 Reels、TikTok、Shorts 或 Stories，则首选 9:16 |
| 时长 | 宣传片约 20 秒（15 到 30 秒）；解说和教程 30 到 60 秒 |
| 语气 | 根据主题和用户写作方式推断 |
| 音乐 | 开启，风格根据语气决定 |
| 配音 | 关闭，除非用户要求或作品是超过 30 秒的解说/教程 |
| 语言 | 提示词的语言 |
如果明显有帮助，提供一两个改进建议，要简短且不阻塞流程：为社交媒体剪辑一个 9:16 版本、使用真实产品照片代替插图、为长篇解说添加配音、翻译版本、用于广告的 6 秒预告片、为静音观看添加字幕。
3. 规划
使用 references/storyboards.md 末尾的模板编写 OUT/plan.md：包括角度（一句话概括这个视频的独特性）、观众、单一信息点、钩子（前 2 秒）、场景表格（id、时长、能量、精确的屏幕文字、视觉和运动、转场、声音）、配音台词（如果有）、海报时刻以及可发布的文案草稿。检查阅读预算：一个场景约能容纳 (时长 - 0.6) / 0.3 个单词。如果有配音，则根据实际语音调整场景大小：python3 SKILL_DIR/scripts/voice.py --say "line" --lang es --out OUT/work/l1.wav 会打印其长度（不同语言和语音的语速差异很大）。如果用户要求批准规划，则显示简短摘要并等待；否则继续。
4. 构建合成
python3 SKILL_DIR/scripts/new_video.py OUT --title "Tidepool launch" --format landscape --lang en [--fonts "Fraunces" "Inter"] [--3d]
这将创建 OUT/comp/（运行时、起始页面、时间线、字符串、字体）和 OUT/work/。然后：
- 编辑
comp/timeline.json：场景（id、dur、energy0 到 1、transition、音乐提示）、music（风格、种子、结尾）、sfx、voice.lines。完整字段列表见references/runtime-api.md末尾。 python3 SKILL_DIR/scripts/timeline.py comp --snap选择一个速度并将每个剪辑点对齐到节拍。每当持续时间变化时重新运行。- 配音（如果有）：
python3 SKILL_DIR/scripts/voice.py comp。它会写入音轨、字幕和逐词时间信息（comp/voice.json），并报告超出场景的台词。延长这些场景或缩短台词，再次对齐节拍，然后重新运行。字幕会烧录在安全区域底部的条带中，.safe区域会缩小以避开它，因此在布局页面之前执行此操作。 - 编写
comp/index.html和comp/strings/<lang>.json。首先阅读references/runtime-api.md。视觉方面使用references/visual-toolkit.md（3D 产品、插图产品、用户照片、模拟图、代码、图表、地图、图标）；布局、排版、颜色和动画方面使用references/motion-design.md。
页面规则（因为渲染器依赖它们）：
- 仅基于时间进行动画：Stage API、CSS 关键帧循环或
frame(t)回调。使用Stage.random(seed)替代Math.random()；不要使用定时器或Date。 - 页面加载的所有内容都位于
comp/内，并使用相对路径（字体、图片、three.js）。不使用 CDN。 - 文本保持为真实的 DOM 文本（不要烘焙到图片中），以便 QA、字幕和翻译正常工作。
- 使用
var(--u)调整大小，将文本保持在.safe内，为每个场景提供不透明背景，并为你要交付的每种格式编写布局规则（.fmt-vertical ...）。
5. 检查与代码检查
此关卡能在昂贵的渲染之前捕获大部分问题。
python3 SKILL_DIR/scripts/render.py OUT/comp --stills auto --sheet OUT/work/sheet.png
打开封面图并以观众的角度查看每一帧：主题在第一帧是否清晰？是否有任何内容被裁剪、碰撞、太小、对比度过低或空白？任何转场帧看起来是否浑浊？修复并重复。然后：
python3 SKILL_DIR/scripts/render.py OUT/comp --qa
QA 会报告文本停留时间过短无法阅读、文本偏离画面或超出安全区域、溢出、重叠（包括字幕）、字号过小、对比度低（在实际像素上测量）以及运行时警告。修复每个错误以及你无法合理解释的每个警告。重复运行两者直到干净为止。对于竖屏或翻译版本，使用 --format 和 --lang 运行相同的两个命令。
6. 音乐与特效
python3 SKILL_DIR/scripts/render.py OUT/comp --cues # 从动画中提取声音提示（弹出声、打字声、点击声）
python3 SKILL_DIR/scripts/music.py OUT/comp # 配乐 + 特效 -> comp/audio/
避免大的冲击音（冲击、强音、碰撞声）出现在讲话的词语上：将它们移动到台词之间的空隙中。对于同风格的不同歌曲，更改 music.seed；对于不同的情绪，更改 music.style。风格、场景提示、特效、语音和语言在 references/audio.md 中。如果使用用户自己的音轨，请遵循其中的“使用用户自己的音乐”部分。
7. 渲染与交付
python3 SKILL_DIR/scripts/render.py OUT/comp --out OUT/work/video.mp4 --poster-at 6.2 --poster OUT/<slug>-poster.jpg
python3 SKILL_DIR/scripts/assemble.py OUT/comp --video OUT/work/video.mp4 --out OUT/<slug>-16x9.mp4
--poster-at 是最强稳定帧的时间（标题完全显示，不在转场中间）。它将变为第 0 帧，也就是 Slack、X、Discord 和大多数播放器显示的缩略图。对于会循环播放并允许上传封面的 Reels、TikTok 和 Shorts，请添加 --no-bake：JPG 仍然保存，但第 0 帧保持实际的第一个帧，这样循环就不会闪烁标题。render.py 会打印预计完成时间；对于长视频或 3D 密集的作品，先渲染一个 --quality draft 版本并展示。Shell 工具通常在约 10 分钟后停止命令，而且在没有 GPU 的机器上，3D 渲染大约需要每帧一秒，因此请在后台启动长渲染并轮询日志：
nohup python3 SKILL_DIR/scripts/render.py OUT/comp --out OUT/work/video.mp4 --poster-at 6.2 > OUT/work/render.log 2>&1 &
tail -n 3 OUT/work/render.log # 重复直到出现 JSON 结果
其他格式：--format vertical|square|portrait（首先检查该格式的帧）。翻译：--lang xx 配合 strings/xx.json，参见 references/global.md。添加 --gif OUT/<slug>.gif 以便组合成一个小预览。
交付到 OUT/ 中：MP4 文件、海报 JPG、如果有配音则提供 <slug>.srt 文件（comp/captions.srt 的副本）以及 share.txt（用视频语言写的一到三行文字，可直接发布，内容具体，不含“激动地分享”等套话）。然后告诉用户文件位置、一句创意角度的话以及一到两个后续步骤（竖屏剪辑、其他音乐种子或风格、不同的钩子、翻译、配音）。references/platforms.md 包含了规格、安全区域和交付物集合。
创作法则
- 2 秒内抓住眼球。 先规划好。第一帧必须发生视觉变化；绝对不要以 Logo 或慢速淡入黑屏开场。
- 展示内容本身。 产品、实际使用的 UI、作为图像的想法。可能属于任何视频的抽象形状都是填充物。
- 具体化。 使用主题自身的词汇、颜色、对象和数字。禁止使用：“优化你的工作流程”、“释放潜能”、“颠覆”、“次时代”、“无缝”、“改变游戏规则”。
- 一个场景一个想法， 并且眼睛只有一个落点。
- 可读性。 快速进入，然后停留：每个单词完全稳定约 0.3 秒，一到三个单词至少 0.8 秒。在削减停留时间之前，先削减单词。
- 生动。 顺序揭示、模拟点击和打字、镜头漂移、视差。没有任何内容冻结超过两秒。
- 声画合一。 剪辑点对齐节拍，冲击音匹配揭示内容，静音要有意义。
- 每一帧都可发布。 任何暂停的帧都应该看起来经过设计。
- 简短。 社交媒体内容 15 到 30 秒，解说类最长 60 秒。绝不填充时长。
- 诚实。 不得捏造事实、数字、推荐、奖项或合作伙伴 Logo。插图不得展示产品所不具备的功能。
权利与安全
- 真实人物：不得伪造肖像或声音。仅当用户提供照片或录音并拥有相关权利时才使用。
- 不得使用其他公司的 Logo、产品或角色，以及任何暗示未经认可的背书的内容。
- 音乐是每个视频生成的，可免费使用。用户提供的音轨需要用户确认其有权使用。
- 下载的资产需将其许可证记录在
comp/assets/LICENSES.json中；所需的致谢信息放入分享文本中。 - 健康、金融和法律声明：仅使用用户提供的信息，并以他们的声明形式呈现。
- 闪烁：每秒不超过三次闪烁；当检测到闪烁时，
render.py会发出警告。
出现问题时的处理方法
| 症状 | 修复方法 |
|---|---|
| 页面始终未就绪 | 阅读打印的控制台错误；可能是构建函数中的拼写错误或缺少 Stage.start() |
| "selector matched nothing" | 元素位于另一个场景中或类名不同 |
| 字体错误或缺失 | 检查 assets/fonts/fonts.css 和 fetch_assets 打印的字体族名称；为非拉丁文本添加脚本字体 |
| 3D 慢或空白 | doctor.py 中 gpu 为 false：使用更小的画布、mat.glassFast，或改用 2D/SVG；ES 模块需要 render.py --serve 来预览 |
| 没有该语言的语音 | 仅使用字幕、用户提供的录音或另一个引擎（audio.md） |
| 音乐太大声或太安静 | assemble.py --music-gain -3，或降低场景 energy |
| ffmpeg 缺少 libx264 | pip install imageio-ffmpeg |
| 渲染太慢 | 迭代时使用 --quality draft；在更多核心的机器上使用 --workers |
参考文件
references/runtime-api.md：stage.js API。在编写index.html之前阅读。references/storyboards.md：钩子、每种主题的节拍表、结尾、规划模板。references/motion-design.md：语气、每种格式的布局、排版、颜色、时间、转场、可读性。references/visual-toolkit.md：3D 和插图产品、用户照片、模拟图、代码、图表、地图、图标、免费资产来源和许可证。references/audio.md：音乐风格和配乐提示、音效、语音引擎和语言、混音、用户音乐。references/platforms.md：格式、时长、安全区域、字幕、编码、交付物。references/global.md：语言和文字、从右到左、字体、翻译、其他操作系统和智能体。