AI Video Self-Check
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
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. Define Three Things Before Starting
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. Create a Short Segment First
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. Use Built-in Tool Checks
- HyperFrames: Run before each render; only start rendering if there are zero errors.
- 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. Automated Check of Rendered Files
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.
It will report on: duration, presence of audio tracks, loudness, black frames, freezes (static footage), and silent segments, and generate a frame mosaic image
.
- 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. Manually Review Frames
Open the frame mosaic (
) as an image and review each grid cell:
- 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. Blind Test
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. 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
| 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 | is paired with overshooting easing functions (back, elastic), which produce invalid negative values. Use exclusively for blur |
| 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.