Sp Create Video

Create video

A board shows the product. This puts the product in the world: someone in an office takes out their phone, your screens are on it, their thumb moves the flow along, and the audio is the room's own sound.

The model generates the scene and must not generate the interface. Every step below keeps the interface out of its hands. A generative model shown a screenshot will redraw it — right colours, right shapes, invented words — and a demo video with invented words in it is worse than no video.

Boards come from canvases/<slug>/; see sp-canvas for running the canvas and its references/layout.md for the folder rules. sp root prints the tree that ships the scripts below:

bashCopy code
KIT="$(sp root)"
B=canvases/<slug>; V="$B/scratch/video"; mkdir -p "$V/out"

sp not found? Run sh <sp-canvas skill dir>/scripts/install.sh (Windows: install.ps1). A [super-prototyping:notice] line on a tool's stderr carries its own rule: finish the step, then do what it says.

Everything this skill makes is derived and large, so all of it lives in $V/ — plates, frames, takes, contact sheets — and scratch/ is already gitignored. Never commit an mp4. The one thing that belongs in the folder proper is the motion board, because it is a board.

Spending rule

Every take is the user's money: roughly $2 or ¥11 at 720p/10s, several times that at 1080p/15s, minutes each. Before the first submission say what you are about to shoot, at what resolution, and how many takes you expect. Then shoot one, show it, and ask. Never loop takes unattended, and never re-submit a failed one without saying what you changed.

The key lives in $V/.ark_key (chmod 600, never printed, never echoed into a log) or in ARK_API_KEY. If there is no key yet, stop and ask the user for one. Ark is ByteDance's model API, sold as BytePlus ModelArk outside China and Volcengine Ark inside it. A key works only where it was issued: ark.py calls ModelArk, and takes --region cn for a Volcengine key.

1. Pick the route

The routes are not exclusive: a reference video plus a full-resolution still as a reference image is the combination that reads sharpest.

2. Make the interface move

The reference video is a board of your own, animating: NN-<flow>-motion.html in the canvas folder, one CSS timeline, emitted by the same gen.py as every other board. Then frames, then an mp4:

bashCopy code
node "$KIT/skills/sp-create-video/scripts/frames.mjs" "$B/19-flow-motion.html" \
  --fps 24 --seconds 10 -o "$V/out/ui" --scale 3          # bun runs it too
ffmpeg -y -framerate 24 -i "$V/out/ui/f%04d.png" -c:v libx264 -crf 16 \
  -vf "crop=trunc(iw/2)*2:trunc(ih/2)*2" -pix_fmt yuv420p "$V/out/mockup.mp4"
ffmpeg -y -i "$V/out/mockup.mp4" -ss 6 -frames:v 1 "$V/ref-phone-hd.png"

Send both. The video carries the motion, the still the sharpness; with the video alone the screen text comes back correct but soft.

Watch mockup.mp4 before going further. Pacing that feels fine scrubbing a board often turns out to be twice too fast in real time, and every later step inherits it.

references/reference-video.md — the motion board's constraints, the --knots re-timing, getting the mp4 somewhere Ark can fetch it (a data: URI is refused), and what a take costs. Read it before the first take.

3. Write the prompt

Into $V/prompt.txt, four blocks: look and style, scene and person, screen contract, sound and negative list. The second is the product; the last one is why the clip has no subtitles, no music and no voice-over.

references/prompting.md — the four blocks, the screen contract that stops the redraw, the three camera choices (locked POV, free direction, the UGC look that actually reads as real), thumb choreography, and a table from the failure you are looking at to the sentence that fixes it. Read it before writing a prompt, and again after any take comes back wrong.

4. Shoot a take

$U below is the public base for mockup.mp4, from the reference above. Ark fetches the video from there; it refuses an inline one.

bashCopy code
python3 "$KIT/skills/sp-create-video/scripts/ark.py" \
  --prompt-file "$V/prompt.txt" --video "$U/mockup.mp4" --key-file "$V/.ark_key" \
  --image "$V/ref-phone-hd.png" --res 720p --dur 10 --tag walk -o "$V/out"

It submits, polls, downloads walk-1.mp4 and writes walk-1.json beside it with the prompt, the seed and the usage. That JSON is the only account of what made a clip; keep it, and quote the seed when you report.

Takes run for minutes, so run it in the background against a log and check back rather than holding the session:

bashCopy code
python3 ... > "$V/out/walk-1.log" 2>&1 & disown

Add --dry to print the request without sending it — do that once, before the first real submission of a session, and read back what you are about to buy.

5. Read the take before believing it

bashCopy code
ffmpeg -v error -i "$V/out/walk-1.mp4" -vf "select=not(mod(n\,24)),tile=5x2" \
  -frames:v 1 "$V/out/walk-1-sheet.png"
ffmpeg -v error -i "$V/out/walk-1.mp4" -vf "crop=iw/3:ih:iw/3:0,scale=iw*2:ih*2" \
  -ss 6 -frames:v 1 "$V/out/walk-1-zoom.png"

Look at the sheet, then at the zoom, as images. Answer these before showing it to anyone:

• Is the text on the screen your text, word for word? Read it, do not glance at it. This is the failure mode of the whole exercise.
• Does the interface change on the frame the thumb lands?
• Any subtitle, caption, watermark or invented logo anywhere in frame?
• Does the phone drift, zoom or roll when it was meant to be locked?
• Does the audio have music or a voice in it? There should be a room.

Report what you saw, including the seed and what the take cost. A take that fails the first question is on the wrong route. Go back to step 1.

6. When it still will not hold the interface

references/compositing.md — the green-plate route: the plate images with their tracking markers, shooting a locked plate, and composite.py, which corner-pins your rendered frames back onto the screen so the pixels are exactly yours and the thumb stays on top. It is a day of work and it is the only way to be certain, so spend a take or two on the prompt first.