one-prompt-video

One-Prompt Video

The user gives one sentence; you first do the design: decide the style and what each scene shows visually. Then write a video.json. Things visible in the subject are drawn by your scene code. The script handles timing, music, subtitles, encoding, and self-check.

In the commands below, replace SKILL with the absolute path of this file's directory (e.g., /home/me/skills/one-prompt-video). All commands run in the user's current working directory; file paths are relative to it.

Five Steps

1. Prepare the environment (run once per working directory)

node "SKILL/scripts/setup.mjs"

It checks for Node, drawing libraries, ffmpeg, and Chinese fonts. It installs missing items or tells you how to install them. Proceed only when all show [Passed]. If any show [Missing], tell the user those exact lines.

2. Design (do not ask the user; decide yourself; at the end, tell the user what you decided)

Create a new folder in the current working directory (named after the film title; call it Title/). First write the design into Title/plan.md (about a dozen lines). Write the plan before anything else. A video with only text cards is unwatchable; this step determines the video's quality.

Fill in what the user didn't say

What the user didn't say	Default
Duration	About 30 seconds, 5 to 8 scenes
Landscape or portrait	Landscape 16:9; if the user mentions phone, portrait, Douyin, Xiaohongshu, or video accounts, use 9:16
Language	Same language as the user's speech
Voiceover	None. Default is subtitles + music. This skill does not include a voice service: when the user wants a voiceover, first tell them they need to prepare their own (a command-line TTS or their own recording), then follow references/voice.md to integrate

Choose a style

1. If the user wants atmosphere, story, scenes, characters, or says "no narration," "visual," "like a movie": This film uses no templates; you draw every part of it. Read references/film.md and follow it.
2. For other videos, choose one from the style pack table below. Each style pack comes with scenes, props, characters, transitions, and sound effects, offering richer visuals than built-in themes. Choose by topic: first look at the "Best for" column; if multiple fit, pick the one closest to the physical items in the topic (handmade, food, daily life → papercraft or clay; equipment and processes → isometric; accounts and performance → dashboard). If the user names a specific look ("like a game," "as a chat record," "like a news broadcast"), use the corresponding style pack.
3. Use built-in themes only in two cases: the user explicitly asks for clean, restrained, business-like visuals; or the content is serious and decoration would hinder readability. For videos using built-in themes, at least half of the scenes must be custom-drawn.
4. Decide on one tangible thing that runs through the whole video: a physical object from the topic (a wing, coffee bean, moon, storefront). It appears in the opening scene, reappears later, tying the video together.

Decide each scene

In the plan, list a table with one row per scene, thinking in this order:

What the audience should understand from this scene	What's on screen	How it's done (which layout, or custom draw)	Narration

"What's on screen" describes the image: an object, a process, a chart, a structure. Think of the image first, then the words. Follow these eight rules:

1. Cover the words. Cover all the text in this scene. If the remaining picture still shows what the scene is about, the scene works. If the topic is wings, the screen must have a wing and airflow; if it's a coffee subscription, the screen must show boxes, bean bags, and brewing cards.
2. Draw visible things yourself. Physical objects, processes, and structures from the topic are drawn with layout: "custom" and scene code; see references/custom-scenes.md for the writing method. The most important scene in the whole video must be custom-drawn; at least two scenes per video should be custom-drawn – more than a third is better.
3. Choose layouts by the shape of the information; let the layout speak for itself. Compare sizes with bars, sequences with steps, comparisons with compare, a real quantity with number (ordinal numbers, times, IDs are not quantities; don't use number). Use statement at most once per video; bullets at most once; quote only for real quotations.
4. Don't write secondary labels and descriptions. kicker, subtitle, note, label, cta, and the title of each scene are omitted by default. Only include them if the audience can't understand the scene without them. Don't write relationships the layout already expresses: bar charts don't need a "Quarterly Comparison" title; steps don't need "Step 1"; compare cards don't need "Comparison."
5. Divide work between visuals and narration. Narration (say) speaks in complete sentences about something appearing on screen; visuals only show images, keywords, and numbers. Don't both write the same sentence as large text and put it in subtitles.
6. Consecutive scenes differ. Don't use the same layout for two consecutive scenes; if the previous scene had a centered large title, the next one should be an image or chart.
7. Use highlights sparingly. Large numbers and key statements each appear at most once per video.
8. Start and end. The first scene uses title; within the first two scenes, clarify what the video is about. The last scene uses end, concluding with a statement or a call to action; the ending is smaller and shorter than the opening: one sentence plus the object that runs through the whole video.

If you cannot view images or write scene code, rule #2 cannot be done: use style packs and layouts as normal, but when reporting, honestly tell the user that this video is primarily text-based layouts.

3. Write video.json and scene code

Following the plan, write Title/video.json:

{
  "title": "One Sentence, One Video",
  "theme": "papercraft",
  "aspect": "16:9",
  "seconds": 30,
  "scenes": [
    { "layout": "title", "title": "One Sentence, One Video", "say": "Say one sentence, get a short video." },
    { "layout": "custom", "module": "scenes/pipeline.mjs", "seconds": 7, "cues": 3, "say": "You say one sentence; the model designs, fills in the form, and the script turns it into a video." },
    { "layout": "bars", "unit": "s", "items": [{ "label": "1st attempt", "value": 68 }, { "label": "2nd attempt", "value": 51 }, { "label": "3rd attempt", "value": 57 }], "say": "The small model tested three times, about a minute each." },
    { "layout": "custom", "module": "scenes/laptop.mjs", "seconds": 6, "say": "A regular laptop can make the video." },
    { "layout": "end", "title": "Try it now", "say": "Try it once now." }
  ]
}

• seconds is the target total duration. The script allocates time per scene accordingly. A final video within 3 seconds of this value is normal (each scene must have an integer number of frames, plus about one second of fade-out). If omitted, duration is auto-estimated from word count.
• say is the subtitle for this scene (and the voiceover script if voice is used). One sentence per scene, up to 30 Chinese characters (12 English words).
• Custom-drawn scenes: place scene code in Title/scenes/. After finishing each scene, generate a still image first (--still); confirm it looks recognizable before writing the next scene.
• Text on screen is meant for a quick glance – keep it short. If it doesn't fit, split into two scenes; don't cram one scene.
• Don't fabricate facts. Numbers, quotes, names, and company names the user didn't provide should not be presented as real. For example numbers, indicate they are illustrative in the narration. For product features and effects, only use what the user said; for any explanations you added, list them one by one in the final report for the user to verify.

A complete example using only layouts is at SKILL/assets/example.video.json.

4. Validate and produce the video

node "SKILL/scripts/make.mjs" Title/video.json --check    # Validate first; takes a few seconds
node "SKILL/scripts/make.mjs" Title/video.json --sheet    # Generate overview image; review before final render
node "SKILL/scripts/make.mjs" Title/video.json            # Render the final video

• When --check reports [ERROR], each error includes the scene number, the field, and the correct writing. Fix it and rerun until it passes.
• If you can view images, open Title/out/sheet.jpg and inspect it frame by frame. Each scene shows two frames: the first at scene entry (halfway), the second with all elements present (the definitive one). For each frame, ask four things: Does it still make sense with text covered? Is the subject large enough (60%+ of screen width or height)? Is there any large empty area? Is text overlapping or a word broken across two lines? If any fails, fix and regenerate the overview.
• After rendering, read the printed report (also saved to Title/out/report.txt). If it shows [ISSUE] or [WARNING], fix and rerun; the most common issue is "too much text" – shorten that segment.

5. Tell the user

Clearly state four things: Where the final video is (the path in the report after "Video:"; the filename is the title plus .mp4); what you decided for the user (duration, aspect ratio, style, which scenes are custom-drawn); what content you added; and that you cannot judge visual quality or music – ask them to watch the video. If the final video has no voiceover, also mention: to add voice, they need to integrate their own TTS.

Style Packs

Each style pack is a complete set of visuals: nine layouts each redrawn in its own style, complete with scenes, props, transitions, subtitles, and sound effects. Write the name as theme.

theme	Look	Best for
papercraft	Multi-layer cardstock diorama, paper figures, stop-motion jitter	Light-hearted science, product intro, short stories, lifestyle
clay	Warm clay stop-motion, rounded little characters	Beginner explanations, habits & health, kids' content
collage	Kraft paper, torn paper, tape, cut-out letters	Light science, recaps, show intros
skit	Flat illustration office, two characters reacting to content	Explaining concepts to non-experts, workplace topics
isometric	2.5D machines, conveyor belts, checkpoints	Processes, how things work, system operations
cosmos	Deep space, nebulae, glowing stars and orbits	Big picture, hierarchy, series opening
dashboard	Dark data screen: panels lighting up one by one, gauge arcs, bar charts	Performance, reviews, monitoring, costs (data-driven content)
news	News studio, chyron, scrolling ticker	News digests, weekly reports, data broadcasts
chat	A phone chat log, messages as bubbles	Conversational explanations, case studies, Q&A
comic	Black-framed panels, dot tones, speed lines, sound effects	Stories with twists, contrasts
detective	Cork board, Polaroids, sticky notes, red string	Problem diagnosis, postmortems
arcade	8-bit pixel game: bricks, coins, level maps	Steps, comparisons, light product intros
variety	Multi-layer outlined text, radial lines, mascot, bullet comment bar	Lively short videos, rants, recaps
vhs	Videotape: scan lines, channel switching, old TV, tape timer	Nostalgia, series intros & trailers
chrome	Chrome-effect 3D text, flowing liquid gradients, star flashes	Youthful short phrases, trending topics; not for serious content

Preview images are in SKILL/assets/styles.jpg. If you can view them, check first before choosing. Style packs have rich decorations, so keep text shorter per scene. For news, remember that it formats content as a news program; if the content isn't real news, remind the user in your report.

These are ready-made starting points, but style is not limited: to create a completely new look (bullet journal, vinyl record, subway map – anything), follow references/style-packs.md to write your own style pack.

Twelve Built-in Themes

Themes only change colors, background, and lines; they have no scenes or props. Use them as described in Step 2, "Choose a style," rule 3.

theme	Look	Best for
grid	Beige grid paper, purple, white cards	Concepts, principles
minimal	Large whitespace, thin lines, one blue dot	Quiet, restrained brand films, intros
pop	Clashing colors, radial lines, thick black outlines	Lively, fast-paced short video platforms
keynote	Dark gradient, glass cards, glow	New products, major conclusions, tech topics
blueprint	Blueprint paper, white lines, yellow annotations	Structure, architecture, assembly
whiteboard	Whiteboard, marker, hand-drawn frames	Teacher drawing while explaining, processes and causality
chalk	Dark green blackboard, chalk lines, wood frame	Classroom blackboard: problem solving, formulas, steps
neon	Dark purple night, glowing lines, perspective grid	Technology, gaming, electronic music
terminal	Black screen, green text, monospace, blinking cursor	Code, command line, dev tools
paper	Beige paper texture, serif headline, red	Commentary, reading, humanities
ink	Rice paper, distant mountains, vermillion seal	Traditional culture, poetry, history
bold	Black & white bold text, hard cuts, one shade of red	Opinions, slogans, rankings

Preview images are in SKILL/assets/themes.jpg. If the user wants a different color, use the colors field.

Layouts

Each scene picks one layout or is custom-drawn. One scene covers one point.

layout	When to use	Required	Default omitted	Limits
custom	When the subject has visible things: objects, processes, structures	module, seconds	cues, data	See references/custom-scenes.md
title	Opening	title	subtitle, kicker	Title ≤ 12 characters
bars	Comparing sizes	items (2–6 items, each with label and numeric value)	title, unit (appended to each number), highlight (which bar to emphasize, counting from 1; defaults to the tallest)	label ≤ 8 characters
steps	Sequential steps, process	items (2–5 steps)	title	Each step ≤ 12 characters
compare	Comparing two things	left, right (each has title and 1–4 items)	title	Each item ≤ 12 characters
number	One real quantity, once per video	value	unit, label, note	value format: "25", "80%", "1,280"
statement	One memorable sentence, max once per video	text	highlight (word(s) in text to emphasize)	≤ 24 characters
bullets	Several parallel points, max once per video	items (2–5 text items)	title	Each item ≤ 18 characters
quote	A real quotation	text	by	≤ 40 characters
end	Ending	title	subtitle, cta (button text)	Title ≤ 14 characters

• unit is part of the number; include it when needed. For number, only include label if the number and unit alone don't make the meaning clear.
• Every layout can add say (subtitle) and seconds (fixed duration for that scene).

If the user provides video footage (real footage, screen recording, existing video), there is also clip: include a segment from the footage, mixed in with the layouts above; a video entirely of clip is a straight edit. Syntax: { "layout": "clip", "file": "素材/采访.mp4", "from": 12.4, "to": 18 }. For how to review footage and decide which segment to use, see references/editing.md.

When You Need More

Need	Read
Custom-draw a scene: objects, processes, structures (use this for every video)	references/custom-scenes.md
User wants atmosphere, story, scenes, characters, or the entire video is custom-designed visuals	references/film.md (you write each frame; script handles camera, music, rendering, and self-check; must be able to view images)
All fields, custom colors, custom fonts, fixed scene duration	references/video-json.md
Add voiceover (user must find their own TTS or record themselves), use custom music file	references/voice.md, references/video-json.md
User provides video footage to cut in, or wants to edit an existing video	references/editing.md
User wants to export to Final Cut Pro or CapCut for further editing (add --project to the render command)	references/editing.md
None of the existing themes or style packs fit; need an entirely new look	references/style-packs.md (write a style pack; requires hundreds of lines of scene code and iterative visual tweaks – confirm you can do it)
Installation fails, fonts show boxes, ffmpeg errors	references/troubleshooting.md
User explicitly wants 3D scenes, full-screen shaders, natural landscapes (things a canvas can't render)	references/pipelines.md (reference pipelines; requires custom code – confirm you can do it)
User has Blender, GarageBand, or an API key for Doubao Speech; wants realistic rendering, real instrument music, natural voice	references/external-tools.md (leverage external tools; for capable models – confirm you can do it)

What this skill cannot do: generate realistic people or real footage out of thin air (real footage only from user-provided assets); perform color grading or compositing on footage (export the project to an editing app for such tasks). If these needs arise, tell the user honestly.