video-short

视频短片

输入：一段原始的对镜讲话录音。输出：renders/<project>-vN.mp4，分辨率为 1080x1920、帧率为 30 fps；一个保存在 renders/share/ 中、体积小到便于发送的 720p 副本；以及制作该视频的 edit.md。

所有编辑决策由你作出；脚本负责测量、渲染，并提供审阅页面。命令、edit.md 格式、图形素材和样式键均见 reference.md。

首次使用时，运行 setup.sh。如果它列出缺少的工具，请告知用户 Video Short 需要这些工具，并提出按它打印的命令安装。Gemini API 密钥（需启用账单功能）为可选项，可用于生成图像、视频和音乐。请让用户将密钥保存在 ~/.config/video-short/.env 中，而不是粘贴到聊天里。

1. 剪辑

为每条短片创建一个文件夹，并使用简短的 slug 命名；优先使用用户指定的位置，否则使用样式文件中的 projects_dir，再否则使用当前文件夹。不要改动原始录音，并将 Source: 指向它。

运行 transcribe.py，并阅读 work/transcript_raw.md 中的每一行。转录文本会保留嗯、口吃和重新起头的部分，因此重录内容也会显示出来。如果录音长于短片所需时长（例如一段完整教程），先挑出其中最精彩的 30 到 60 秒：剪辑可以由文件中任意位置的一段或几段片段组成。在 edit.md 中写入 ## Cuts：

• 对于重复说出的句子，保留最后一次完整录制。删掉说错后重来、无意的填充词和静音部分。
• 在词语之间剪切，绝不能从词语中间剪切；如果在句中重新起头，请使用 .json 中的词语时间戳。
• 在第一个词前约 0.1s 开始，在最后一个词后约 0.1s 结束。逗号和列表项后保留自然的换气时间。绝不要加快语速。

运行 cut.py --look，然后阅读从保留片段中提取的网格静帧，以确定 Framing: x, y，即人脸中心位置。横向录制的视频会围绕该点裁切为竖屏。添加 --grade，并排比较轻微的 ffmpeg 调色效果；如果原片画面已经很好，则使用 Grade: none。

运行 cut.py，然后阅读 work/transcript_clean.md。修正任何被截断的词或仍保留的重录内容，再次运行。所有场景时间都以这条剪辑时间线为准。

2. 规划

研究这条短片需要什么，然后在 edit.md 中写入 ## Scenes，每个镜头一行，起始和结束位置均落在口播词语上。如果用户分享了喜欢的短视频，先用联系表和剪辑条研究其节奏、布局和转场；借鉴它的运动方式，绝不要使用它的文字或素材。

• 前 3 秒抓住观众。 问问自己：观众现在会不会愿意看到最后？开场用一句吸引人的台词配合说话者或最有冲击力的画面，并确保静音时也能看懂，因为大多数手机观众一开始都关闭了声音。在开场埋下一个问题，并在 Short 结束前给出答案。以说话者收尾；合适时，再次呈现开场画面，让 Short 首尾呼应。
• 布局： a-roll（全屏说话者）、punch（更近距离呈现说话者以突出重点）、split（上方画面，下方说话者）、b-roll（全屏画面）。
• 至少一半的 Short 时间要呈现说话者， 每个全屏 B-roll 镜头都要在大约 3.5 秒内结束，因为观众会与一张脸产生共鸣。
• 画面要呈现文字未表达的内容： 产品如何运行、结果、证据。字幕已经承载了文字内容。展示实际产品或 UI，并从真实屏幕录制；只有在无法获取真实画面时才制作模拟画面。绝不编造数字或结果。
• 所有不在镜头中的内容都要动起来。 优先使用真实素材。否则，可用每说到一项就增加一行的列表卡片、逐步计数直到说话者提到的统计数字的 number:，或用于其他内容（例如流程或前后对比）的 graphic:。绝不要用静态图片作为 B-roll；图片只能作为生成视频片段的首帧，或作为会滚动的 page: 截图。不要使用昏暗的 UI 面板和音频波形，它们会让观众流失。图形过渡到视频片段时，要以该片段的首帧结束，让切换消失。
• 清晰易读。 图形要铺满所在面板，文字要让观众一眼就能在手机上读清。绝不要将卡片或叠加层放在说话者脸上。绝不要在 Short 的字幕下方全屏显示另一段带字幕的视频。
• 节奏： 每隔几秒切换镜头，因为手机观众会划走静止画面。以下是良好的起点，脚本可覆盖这些安排：大约 1 秒内完成第一次剪切，在第一个有力的词上切换；大多数镜头保持 1 到 2 秒，如果演示或关键台词需要时间呈现，则适当延长。说话者连续提到多项内容时，在每项对应的词语说出时，为其提供单独的视频片段或卡片行。每个片段只用一次。

按以下顺序寻找 B-roll：用户自己的素材，包括较长录制中的屏幕共享片段；然后是关于该主题的官方演示，以及帖子或发布页面中的媒体。使用每个片段中有用的部分，并用 @start-end 指定；用 hold 定格在片段的最后一帧，不要让短片段循环播放。确保每行屏幕文字都完整显示：用 capture.py 截取网页，该工具会将页面重新排版以适应手机宽度；再用 page: 向下展示一个完整板块。产品 UI 太小看不清时，用 zoom 放大完整的卡片或字段，不要裁掉边缘的文字。只使用用户有权使用的素材。品牌 Logo 只能使用官方文件，绝不要重新绘制或生成；如果没有官方文件，就写出品牌名称。

用户有 Gemini 密钥且某个镜头没有合适素材时，可以提议生成素材：Nano Banana 图片、Gemini Omni Flash 视频片段，或 Lyria 配乐。只有获得用户批准后才生成，因为每次调用都需要付费。

添加 ## Caption fixes，修正拼写错误的名称；为少数值得在字幕中加框强调的词语（例如产品名称或主要数字）添加 ## Emphasis，让字幕保持简洁。音乐可使用用户提供的曲目、用户批准的 Lyria 配乐，或不使用音乐。Lyria 有时会生成缓慢的独奏钢琴曲，因此应分享生成的配乐供用户试听；如果缺少用户要求的律动，就重新生成。用户提到歌曲或艺人时，在 Lyria 提示词中描述其流派、速度和乐器，而不要写出名称。说话者提到音乐时，在对应位置用 Music lift 提高音量。除非用户提出要求，否则不要加入音效。

在聊天中展示计划，然后等待用户同意：

• 每个场景一行：时间、布局、屏幕上的内容和说出的台词。
• 找到的 B-roll 来源及其链接。
• 计划生成的内容（如有）以及音乐。

3. 起草与审阅

运行 render.py --draft，然后对生成的内容运行 qa.py，修复其中未通过第 4 步检查的画面，让用户审阅的是风格，而不是错误。然后在后台运行 review.py。审阅页面会在按场景拆分的时间线上播放草稿。用户可在任意画面暂停，按 C 添加评论，然后点击 Send。脚本会退出，并打印每条备注及其时间、场景、说出的台词，以及用户暂停时画面的静帧。

查看每条备注对应的画面，然后将每条备注应用到 edit.md，渲染下一版草稿，并运行 review.py --no-open；已打开的页面会自动重新加载。重复此流程，直到用户点击 Looks good。

4. 最终成片

运行 render.py，然后运行 qa.py，并修复任何未通过的检查。查看 work/qa/ 中的 opening.jpg、contact.jpg 和 cuts/*.jpg：

• 字幕不会遮住嘴部或下巴。
• 每个剪辑都落在正确的词上，没有空白、定格或拉伸的画面。
• 文本和片段细节在手机屏幕上清晰可读。

你无法听到混音，因此请用户检查音乐音量和被截断的词。运行 eval.md，然后分享视频路径、时长和响度。

风格

字体和颜色来自样式文件，依次为：--style、项目中的 style.json、~/.config/video-short/style.json，然后是内置默认值。当用户提出外观方面的意见时，主动提出将其保存到样式文件中，让每条 Short 都采用该风格。