video-short

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Video Short

Input: a raw talking-head recording. Output:

renders/<project>-vN.mp4

at 1080x1920 and 30 fps, a 720p copy in

renders/share/

small enough to send, and the

edit.md

that produced it.

You make every editorial call; the scripts measure, render, and serve the review page. Commands, the

edit.md

format, graphics, and style keys live in reference.md.

On first use, run

setup.sh

. If it lists missing tools, tell the user Video Short needs them and offer to install them with the commands it prints. A Gemini API key with billing enabled is optional, for generated images, video, and music. Ask the user to save it in

~/.config/video-short/.env

rather than paste it into chat.

输入：原始口播录像。输出：分辨率为 1080x1920、帧率为 30 fps 的

renders/<project>-vN.mp4

；一个位于

renders/share/

、大小适合发送的 720p 副本；以及生成该视频的

edit.md

。

所有剪辑决策由你作出；脚本负责测量、渲染并提供审阅页面。命令、

edit.md

格式、图形和样式键见 reference.md。

首次使用时，运行

setup.sh

。如果它列出了缺少的工具，请告知用户 Video Short 需要这些工具，并提供使用其输出的命令进行安装。启用计费的 Gemini API key 是可选的，用于生成图像、视频和音乐。请让用户将其保存在

~/.config/video-short/.env

中，而不是粘贴到聊天里。

1. Cut

1. 剪片

Make one folder per Short, named with a short slug, where the user asks, else

projects_dir

from the style file, else the current folder. Leave the recording untouched and point

Source:

at it.

Run

transcribe.py

and read every line of

work/transcript_raw.md

. The transcript keeps ums, stutters, and restarts, so retakes show in the text. When the recording is longer than the Short, such as a full tutorial, first pick its strongest 30 to 60 seconds: cuts can be one or a few ranges from anywhere in the file. Write

## Cuts

edit.md

Keep the last complete take of any repeated line. Drop false starts, stray fillers, and dead air.
Cut between words, never inside one; use the word times in the
```
.json
```
for a restart mid-sentence.
Start about 0.1s before the first word and end about 0.1s after the last. Leave a natural breath after commas and list items. Never speed up the voice.

Run

cut.py --look

and read the gridded stills, taken from the kept footage, for

Framing: x, y

, the face center. A landscape recording crops to vertical around that point. Add

--grade

to compare a subtle ffmpeg grade side by side, or use

Grade: none

when the footage already looks good.

Run

cut.py

, then read

work/transcript_clean.md

. Fix any clipped word or surviving retake and run it again. All scene times use this cut timeline.

为每条短视频建立一个文件夹，使用简短 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. Plan

2. 规划

Research what the Short needs, then write

## Scenes

edit.md

, one row per shot, with start and end on spoken words. When the user shares a reel they like, study it first with contact sheets and cut strips for its pacing, layouts, and transitions; borrow how it moves, never its words or assets.

Hook in the first 3 seconds. Ask whether a viewer would now watch to the end. Open on the hook line with the speaker or the strongest visual, and make it clear with the sound off, since most phone viewers start muted. Plant one question there that the Short answers before it ends. Close on the speaker, and when it fits, bring back the hook's visual so the Short comes full circle.
Layouts:
```
a-roll
```
(full-screen speaker),
```
punch
```
(tighter speaker for emphasis),
```
split
```
(visual on top, speaker below),
```
b-roll
```
(visual full screen).
Keep the speaker present for at least half the Short, and end each full-screen B-roll shot within about 3.5 seconds, because viewers connect with a face.
Visuals show what the words don't: the product doing the thing, the result, the proof. Captions already carry the words. Show the real product or UI, captured from the actual screen, and mock it up only when the real one isn't available. Never invent numbers or results.
Everything off-camera moves. Real footage first. Otherwise a list card that adds a row per spoken item, a
```
number:
```
that counts up to a stat the speaker says, or a
```
graphic:
```
you write for anything else, such as a flow or a before and after. Never use a still image as B-roll; an image is only the first frame of a generated video clip, or a
```
page:
```
capture that scrolls. Skip dim UI panels and waveforms, which lose viewers. When a graphic leads into a clip, end it on the clip's first frame so the cut disappears.
Readable and clean. A graphic fills its panel, with text a viewer can read on a phone at a glance. Never put a card or overlay over the speaker's face. Never show another captioned video full screen under this Short's captions.
Pace: Change the shot every few seconds, since a phone viewer swipes away from a static frame. Good starting points, which the script can override: the first cut within about a second, on the first strong word, and most shots around 1 to 2 seconds, with a longer hold when a demo or a key line needs time to land. When the speaker names several things in a row, give each its own clip or card row on its spoken word. Use each clip once.

Find B-roll in this order: the user's own footage, including the screen-share parts of a longer recording, then official demos and the media in posts or launch pages about the topic. Use each clip's useful seconds with

@start-end

, and

hold

its last frame instead of letting a short clip loop. Keep every line of on-screen text whole: capture web pages with

capture.py

, which reflows them to phone width, and show them as

page:

drifting down one complete section. When product UI is too small to read,

zoom

into one complete card or field rather than cropping text at the edges. Use footage the user has the right to use. Show a brand's logo only from its official file, never redrawn or generated; without one, write the name.

When the user has a Gemini key and a shot has no good footage, propose generating it: a Nano Banana image, a Gemini Omni Flash video clip, or a Lyria music bed. Generate only what the user approves, because each call costs money.

Add

## Caption fixes

for misspelled names, and

## Emphasis

for the rare term that earns a box in the caption, such as a product name or the main number, so captions stay quiet. For music, use the user's track, a Lyria bed they approve, or none. Lyria sometimes returns slow solo piano, so share a generated bed for a listen and regenerate it if it lacks the groove the user asked for. When the user names a song or artist, describe its genre, tempo, and instruments in the Lyria prompt instead of the name. When the speaker mentions the music, raise it there with

Music lift

. Leave sound effects off unless the user asks.

Show the plan in chat and wait for a go:

One line per scene: time, layout, what's on screen, and the words spoken.
The B-roll sources you found, with links.
What you propose to generate, if anything, and the music.

研究这条短视频需要哪些内容，然后在

edit.md

中写入

## Scenes

，每个镜头占一行，开始和结束时间应对应实际说出的词。当用户分享了一条喜欢的 reel 时，先使用 contact sheets 和 cut strips 研究它的节奏、布局和转场；可以借鉴它的运动方式，但绝不能照搬其中的文字或素材。

在前 3 秒内设置钩子。 判断观众此时是否愿意看到结尾。用钩子台词配合说话人或最有吸引力的视觉开场，并确保静音状态下也能看懂，因为大多数手机用户最初都会静音播放。在那里埋入一个问题，并在短视频结束前给出答案。以说话人画面收尾；条件合适时，再次呈现钩子部分的视觉，让短视频形成完整闭环。
布局：
```
a-roll
```
（全屏说话人）、
```
punch
```
（更紧的说话人特写，用于强调）、
```
split
```
（视觉画面在上、说话人在下）、
```
b-roll
```
（全屏视觉画面）。
**让说话人至少出现在一半时长中，**并且每个全屏 B-roll 镜头持续不超过约 3.5 秒，因为观众需要通过人脸建立连接。
视觉内容展现言语无法表达的信息： 展示产品执行操作的过程、结果或证据。字幕已经承载了台词内容。应展示真实产品或 UI，UI 需从实际屏幕采集；只有在无法获取真实界面时才进行模拟。绝不能虚构数字或结果。
所有离镜画面都要有运动。 优先使用真实 footage。否则，可以使用为每个口述条目增加一行的列表卡片、递增至说话人所述数据的
```
number:
```
，或为其他内容编写的
```
graphic:
```
，例如流程图或前后对比。绝不能将静态图片用作 B-roll；图片只能作为生成视频片段的第一帧，或者用于会滚动的
```
page:
```
页面采集。跳过暗色 UI 面板和波形，因为它们容易让观众流失。当图形画面衔接到视频片段时，应在视频片段的第一帧结束图形，使切换痕迹消失。
清晰易读。 图形应填满自己的画面区域，其中的文字必须让观众在手机上一眼就能读懂。绝不能将卡片或叠加层放在说话人面部上方。在这条短视频的字幕下层，绝不能全屏播放另一条带字幕的视频。
节奏： 每隔几秒更换一次镜头，因为手机观众会从静止画面上滑走。良好的默认起点如下，脚本可以覆盖这些设置：第一次剪切约在 1 秒内完成，并落在第一个有力词语上；大多数镜头保持约 1 到 2 秒；当演示或关键台词需要时间传达时，可以延长停留。当说话人连续提到多个事物时，应在相应的口述词上为每个事物分配独立片段或卡片行。每个片段只能使用一次。

按以下顺序查找 B-roll：先是用户自己的素材，包括较长录像中的屏幕共享部分；其次是官方演示，以及与主题相关的帖子或发布页面中的媒体。使用每个片段中有用的时间范围，并采用

@start-end

格式；对于短片段，应使用

hold

固定最后一帧，而不是让片段循环播放。保持屏幕文字的每一行完整：使用

capture.py

采集网页，它会将页面重新排版为手机宽度，并以

page:

形式缓慢向下展示一个完整区段。当产品 UI 太小而难以辨认时，使用

zoom

聚焦一个完整卡片或字段，而不是从边缘裁掉文字。只能使用用户有权使用的素材。品牌 Logo 只能取自其官方文件，绝不能重绘或生成；如果没有官方 Logo，则直接写出品牌名称。

当用户拥有 Gemini key，而某个镜头又没有合适的素材时，可以提议生成：一张 Nano Banana 图片、一段 Gemini Omni Flash 视频，或一段 Lyria music bed。只能生成用户明确批准的内容，因为每次调用都会产生费用。

添加

## Caption fixes

以修正拼错的人名；添加

## Emphasis

，用于少数量值得在字幕中加框突出显示的术语，例如产品名称或主要数字，从而避免字幕过度拥挤。音乐可以使用用户提供的曲目、用户批准的 Lyria music bed，或者不使用音乐。Lyria 有时会生成节奏缓慢的钢琴独奏，因此应先分享生成的 music bed 让用户试听；如果它缺少用户要求的 groove，则重新生成。当用户提到某首歌曲或某位艺人时，应在 Lyria prompt 中描述其 genre、tempo 和 instruments，而不是写出名称。当说话人提到音乐时，在对应位置使用

Music lift

提升音乐音量。除非用户明确要求，否则不要添加音效。

在聊天中展示方案，并等待用户确认后继续：

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

3. Draft and review

3. 草稿与审阅

Run

render.py --draft

, then

qa.py

on it, and fix anything in its frames that fails the step 4 checks, so the user's review goes to taste, not mistakes. Then run

review.py

in the background. The review page plays the draft on a timeline split into scenes. The user pauses on any frame, presses C to comment, and clicks Send. The script exits and prints each note with its time, scene, spoken words, and a still of the frame the user paused on.

Look at each note's frame, then apply every note to

edit.md

, render the next draft, and run

review.py --no-open

; the open page reloads itself. Repeat until the user clicks Looks good.

运行

render.py --draft

，然后对其运行

qa.py

，并修复画面中所有未通过第 4 步检查的问题。这样用户审阅到的是实际效果，而不是明显的错误。随后在后台运行

review.py

。审阅页面会在按场景划分的时间线上播放草稿。用户可以暂停在任意帧，按 C 添加评论，然后点击 Send。脚本退出时会输出每条评论及其时间、场景、口述台词，以及用户暂停画面的静帧。

查看每条评论对应的画面，然后将所有评论逐一应用到

edit.md

，渲染下一版草稿，并运行

review.py --no-open

；已打开的页面会自动重新加载。重复此过程，直到用户点击

Looks good

。

4. Final

4. 成片

Run

render.py

, then

qa.py

, and fix any failed check. Look at

opening.jpg

contact.jpg

, and

cuts/*.jpg

work/qa/

Captions never cover the mouth or chin.
Every cut lands on the right word, with no blank, frozen, or stretched frames.
Text and clip details are readable at phone size.

You can't hear the mix, so ask the user to listen for music level and clipped words. Run eval.md, then share the video path, duration, and loudness.

运行

render.py

，然后运行

qa.py

，并修复所有未通过的检查。查看

work/qa/

中的

opening.jpg

、

contact.jpg

和

cuts/*.jpg

：

字幕绝不能遮挡嘴巴或下巴。
每次剪切都必须落在正确的词语上，不能出现空白、卡帧或拉伸帧。
文字和片段细节在手机尺寸下都必须清晰可读。

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

Style

样式

Fonts and colors come from a style file:

--style

, then

style.json

in the project, then

~/.config/video-short/style.json

, then the bundled default. When the user gives a note about the look, offer to save it to their style file so every Short gets it.

字体和颜色取自样式文件，查找顺序为：

--style

、项目中的

style.json

、

~/.config/video-short/style.json

，最后是内置默认样式。当用户对画面风格提出意见时，可以提议将其保存到用户的样式文件中，让每条短视频都应用这一风格。