ai-video-check
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAI 视频自检
AI Video Self-Check
用代码做视频，最常见的失败不是代码跑不起来，而是代码跑通了、画面却是坏的：字压字、字看不清、第一帧空白、某一段卡住、整片没声音、观众看不懂。这些问题只有看真实渲染出来的文件才会发现。
这套规则来自 JellyPop的实验室 做过的十几支 AI 代码视频，每一条都是真实踩过的坑。
When creating videos with code, the most common failures are not that the code won't run, but that the code runs successfully but the output video is defective: overlapping text, unreadable text, blank first frame, frozen segments, no audio throughout the video, or viewers being unable to understand the content. These issues can only be detected by reviewing the actual rendered file.
This set of rules comes from over ten AI code-generated videos produced by JellyPop Lab, and every rule is based on real pitfalls encountered during production.
铁律
Iron Rule
说做好了之前，先看实际画面。 代码能跑、预览正常、检查命令通过，都不等于成片没问题。必须打开渲染出来的 mp4，抽帧看，再说完成。没看过的部分，交付时明确说"这一段我没检查"。
Always review the actual footage before claiming the video is done. A successful code run, normal preview, or passing check commands do not guarantee the final video is problem-free. You must open the rendered mp4 file, review extracted frames, and only then declare completion. For parts you have not reviewed, explicitly state "I have not checked this segment" upon delivery.
流程
Workflow
1. 动手前先定三件事
1. Define Three Things Before Starting
写第一行代码之前，先定并写下来：
- 横屏还是竖屏，分辨率，时长。
- 配色：背景、主色、一个强调色。不用纯黑纯白。
- 字体：中文字体和英文字体各一个，用开源授权的字体。视频字号不能按网页来：1080p 横屏正文字幕至少 44px。
再写一句话故事：主角是谁，想要什么，最后怎样。写不出来就先别做画面。
Before writing the first line of code, define and write down:
- Landscape or portrait orientation, resolution, and duration.
- Color scheme: background color, primary color, and one accent color. Avoid pure black or pure white.
- Fonts: one Chinese font and one English font, both with open-source licenses. Do not use web font sizes for videos: for 1080p landscape videos, body subtitle text must be at least 44px.
Then write a one-sentence story: who the protagonist is, what they want, and how it ends. If you can't write this, don't start creating the visuals yet.
2. 先做一小段
2. Create a Short Segment First
先只做前 5 到 10 秒，渲染出来，按第 4、5 步检查，给用户看过再做整片。不要一次做完整条再回头改。
First create only the first 5 to 10 seconds, render it, check it according to steps 4 and 5, show it to the user for confirmation, then proceed to the full video. Do not create the entire video at once before making revisions.
3. 用工具自带的检查
3. Use Built-in Tool Checks
- HyperFrames：每次渲染前跑 ，零 error 才渲染。
npx hyperframes check - Remotion 或其他：没有统一的检查命令，就靠第 4 步的脚本和第 5 步的抽帧。
- HyperFrames: Run before each render; only start rendering if there are zero errors.
npx hyperframes check - Remotion or other tools: If there is no unified check command, rely on the script in step 4 and frame extraction in step 5.
4. 机器检查渲染出来的文件
4. Automated Check of Rendered Files
bash
bash <这个 skill 所在的文件夹>/scripts/render_check.sh <video.mp4> [预期时长秒数]需要 ffmpeg（Mac 上：先装 Homebrew，再 ）。HyperFrames 和 Remotion 都还需要 Node.js。
brew install ffmpeg它会报告：时长、有没有音轨、响度、黑场、冻结（画面不动）、静音段，并生成一张抽帧拼图 。
<video>_sheet.jpg- 黑场或冻结从第 0 秒开始：通常是整片没渲出来（字体加载失败、脚本报错），不是"开场慢"。
- 文件体积异常小（15 秒 1080p 不到 1 MB）也是同一个信号。
- 时长和预期差超过半秒，算问题，要么改片子，要么跟用户说明原因。
- 有意的静止或静音可以保留，但要能说出为什么；结尾全静止加全静音不要超过约 3 秒，观众会以为卡住了。
bash
bash <这个 skill 所在的文件夹>/scripts/render_check.sh <video.mp4> [预期时长秒数]This requires ffmpeg (on Mac: first install Homebrew, then run ). Both HyperFrames and Remotion also require Node.js.
brew install ffmpegIt will report on: duration, presence of audio tracks, loudness, black frames, freezes (static footage), and silent segments, and generate a frame mosaic image .
<video>_sheet.jpg- Black frames or freezes starting at second 0: usually means the entire video failed to render (font loading failure, script error), not that the "opening is slow".
- Abnormally small file size (less than 1 MB for a 15-second 1080p video) is also a sign of the same issue.
- If the duration differs from the expected value by more than half a second, it is considered a problem — either modify the video or explain the reason to the user.
- Intentional static or silent segments can be kept, but you must be able to explain why; full static + full silence at the end should not exceed about 3 seconds, as viewers will think the video is frozen.
5. 自己看帧
5. Manually Review Frames
用读图的方式打开拼图（），逐格看：
<video>_sheet.jpg- 文字有没有互相压住，有没有压在画面主体上。
- 文字和背景对比够不够，小字在手机上还能不能读。
- 每个转场前后各看一帧，上一幕的东西有没有走干净。
- 第 0 帧不能是空白、全虚或只有背景。
- 竖屏视频的关键内容避开底部 25% 和右侧 12%（平台按钮和标题在那里）。
怀疑某一处时，单独截那一帧原尺寸看，不要只看缩略图。
Open the frame mosaic () as an image and review each grid cell:
<video>_sheet.jpg- Check if text overlaps with other text, or if text overlaps with the main subject of the footage.
- Check if the contrast between text and background is sufficient, and if small text is readable on mobile devices.
- Review one frame before and after each transition to ensure elements from the previous scene are fully cleared.
- Frame 0 must not be blank, fully blurred, or contain only the background.
- For portrait videos, keep key content away from the bottom 25% and right 12% of the screen (where platform buttons and titles are located).
If you suspect an issue with a specific part, capture that frame at full resolution and review it — do not rely only on thumbnails.
6. 盲测
6. Blind Test
做视频的会话、读过需求的评审，都已经知道这支片"应该"讲什么，所以都会觉得能看懂。必须找一个什么都没看过的人。
派一个全新的子代理，只给它按时间顺序排好的抽帧拼图（每张图下写时间），不给需求、剧本、代码。如果片子的意思一部分在声音里，附一份声音清单：按时间写听得到什么，不写解读。然后问它：
- 按顺序讲一遍发生了什么。
- 主角是谁，想要什么。
- 最后怎样，结尾的字写了什么，想说什么。
- 哪些地方没看懂（写时间）。
它复述的故事对不上第 1 步那句话，就不算完成。它说没看懂的地方，优先修。
Anyone who worked on the video session or reviewed the requirements already knows what the video "should" be about, so they will all feel they understand it. You must find someone who has seen nothing about the project.
Assign a brand new subagent, and only provide it with the chronologically ordered frame mosaic (with timestamps under each image) — do not provide requirements, scripts, or code. If part of the video's meaning is conveyed through audio, attach an audio list: write what can be heard at each time point, without interpretation. Then ask it:
- Narrate what happened in chronological order.
- Who is the protagonist, and what do they want?
- How does it end? What does the ending text say, and what is the message?
- Which parts did you not understand (note the timestamps)?
If the story it recounts does not match the one-sentence story from step 1, the video is not complete. Prioritize fixing the parts it says it did not understand.
7. 交付时说清楚
7. Be Clear Upon Delivery
交付时说明：检查了什么、用什么查的、哪些没查（比如你听不到声音，就说配乐需要用户自己听）。不说"应该没问题"。
Upon delivery, specify: what was checked, what tools were used for checking, and what was not checked (for example, if you cannot hear audio, state that the user needs to review the soundtrack themselves). Do not say "it should be fine".
代码渲染常见坑
Common Pitfalls in Code Rendering
| 现象 | 原因和做法 |
|---|---|
| 渲染出来整片空白，预览却正常 | 渲染时字体或资源路径被改写、脚本报错。看渲染日志里的报错，跑第 4 步的冻结检测 |
| 某几帧字幕在清楚和模糊之间闪 | |
| 无限循环的背景动画让后面的动画越来越晚 | 不用无限重复，按场景长度算够次数 |
| 玻璃、毛玻璃效果看起来只是一块淡色平板 | 玻璃背后要有明暗不同的东西可以折射 |
| 镜头推到画面一角，中途掠过一片空白 | 先让目标点在屏幕上走直线到落点，再反算镜头位置 |
| 画面意思只靠一行小字解释 | 盲测时假设小字不存在；会被读反就把它升成主文字 |
| 用代码画真人的脸、手 | 基本画不像。需要真人或真实场景，就用真实照片、实拍素材，或交给视频生成模型 |
| 合成音乐不连贯、高音刺耳 | 先出一张频谱图看；需要好听的配乐，用乐器采样或正规曲库，不要全靠代码合成 |
| 两个渲染同时跑 | 互相拖慢好几倍，一个一个来 |
| Symptom | Cause and Solution |
|---|---|
| The entire rendered video is blank, but the preview works normally | Font or resource paths are rewritten during rendering, or a script error occurs. Check the errors in the render log and run the freeze detection from step 4 |
| Subtitles flicker between clear and blurry on some frames | |
| Infinite looping background animations cause subsequent animations to be delayed more and more | Do not use infinite repeats; calculate the required number of iterations based on the scene length |
| Glass/ frosted glass effects just look like a light-colored flat panel | There must be objects with varying brightness behind the glass for refraction to be visible |
| When the camera pushes to a corner of the frame, it passes through a blank area mid-movement | First move the target point in a straight line to its destination on the screen, then reverse-calculate the camera position |
| The meaning of the footage relies solely on a small line of text | Assume the small text does not exist during blind testing; if it could be misread, promote it to main text |
| Drawing real human faces or hands with code | They almost never look realistic. If you need real people or real scenes, use real photos, live-action footage, or hand it off to a video generation model |
| Synthesized music is choppy or has harsh high frequencies | First generate a spectrogram to check; if you need good-sounding background music, use instrument samples or a proper music library — don't rely entirely on code synthesis |
| Running two renders at the same time | They slow each other down by several times; run them one at a time |
越用越准
Gets More Accurate With Use
每次踩到新坑，把它加进上面的表：现象、原因、做法，一行。下次就不会再犯。
Every time you encounter a new pitfall, add it to the table above: one row with symptom, cause, and solution. You won't make the same mistake next time.