Paper Collage Ad

Paper Collage Ad

Turn a product brief and brand assets into a complete paper-collage advertisement. Build the story around one memorable visual metaphor, generate a locked set of finished keyframes, animate the sequence, add narration and sound, validate the rendered MP4, and preserve the reusable production artifacts.

Core outcome

Deliver all of the following:

1. A concise creative concept with one recurring visual world.
2. A time-coded storyboard with one idea and one joke per scene.
3. A locked visual system and approved first keyframe.
4. A consistent finished keyframe for every scene.
5. Narration, music and restrained sound effects.
6. A rendered MP4 with verified audio and video duration.
7. A contact sheet and all manifests needed for reproducibility.
8. Editable scene videos, selected narration and the final audio mix.

Do not stop at prompts or a storyboard when the user asks for a finished advertisement.

Codex edition

Treat this repository as the skill directory. Install it at either ~/.codex/skills/paper-collage-ad/ for global use or <project>/.codex/skills/paper-collage-ad/ for project-local use. Run every command from a shell available to Codex and keep generated project assets outside the skill directory.

The workflow remains framework-neutral: plain Markdown, Node, Bash and FFmpeg make the deterministic steps usable from other agents or a bare shell. The metadata, installation paths, privacy defaults and examples in this edition are maintained primarily for OpenAI Codex.

This skill is self-contained and framework-neutral: plain Markdown, Node and Bash scripts, and FFmpeg. Any agent (Claude Code, Codex, openclaw, or a bare shell) runs it identically. There is no framework-specific runtime.

Resolve <SKILL_DIR> to the folder containing this SKILL.md. Every scripts/... and references/... path below is relative to it; every project artifact is relative to the project directory you create in Phase 1.

Phase 0: Preflight. Before generating anything, verify the toolchain:

bash <SKILL_DIR>/scripts/check-deps.sh

Core tools (ffmpeg, ffprobe, node) must pass. The reference-voice extras are only needed for Phase 5 voice cloning. See references/dependencies.md for the full list.

The four deterministic, runnable steps — each fails loudly if inputs are missing and verifies its own output at the stream level:

Creative generation keeps a model or human in the loop for keyframes, the optional Gemini Omni motion pass, final animation and voice selection. Deterministic assembly and validation remain scripted. Follow Phases 1–6 in order; do not skip the stage gates in references/production-workflow.md.

Phase 1: Lock the brief

Extract or infer the following from existing project material before asking questions:

• Product promise.
• Audience and viewing context.
• Required product facts and CTA.
• Brand assets, colors and typography.
• Length, aspect ratio and language.
• Available generation and rendering tools.

Use existing project conventions when they already answer the brief. For a desktop product with landscape marketing assets, start with 16:9 and five scenes. Treat 30 seconds as a draft constraint only. Do not lock runtime until a representative narration take has been generated and measured. For social-first content, start with 15 seconds and 9:16 only when brevity is a hard requirement.

Create the artifact structure in references/production-workflow.md and keep every project-bound generation inside it.

Use the real brand assets — never invent them. Before any generation, locate the product's real logo, app icon, UI screenshots, brand colors and wordmark inside the project. Feed the real icon/UI as reference images to the image model, and composite the exact wordmark PNG for final delivery. Do not let the model invent a mascot or approximate the logo — a made-up character or a mis-spelled AI wordmark is an instant reject.

Write the one-line creative angle before drafting scenes. Prefer a concrete metaphor that can carry the whole film. Examples include a traffic jam for tool overload, a factory for transformation, a stage performance for orchestration, or a suitcase for consolidation.

Phase 2: Write and confirm the script — HARD GATE

Do not generate a single keyframe, voice take, or clip until the user has approved a written script. This gate is what separates a real ad from paper-scrap garbage. Rushing to hand in a rendered MP4 before the words are agreed is the most expensive mistake — it causes version after version of rework.

Produce, and get the user to explicitly sign off on, three things:

1. Core dramatic action / concept — one sentence: who wants what, blocked by what, plus the one recurring visual metaphor that carries the whole film.
2. Storyboard — beat by beat: scene # · duration · 画面 (what the camera sees) · 旁白/对白. Default 30 seconds or more unless the user asks for shorter.
3. The actual dialogue / narration, written out in full.

Craft rules for the writing (this is an ad concept-short, not a feature list):

• Zero explanation — show features, never narrate them. The voiceover must NOT list capabilities ("opens every format, sorts your photos and documents, one app for all…"). That reads as a spoken product manual and is the #1 reason ad copy feels cringe. The visuals carry the product story; the narration only sets mood and moves the story.
• Few lines, spoken, with subtext. Talk like a real person, not an essay. Say the tip of the iceberg and imply the rest. No AI-essay tone, no piled-on metaphors, no preaching, no exaggerated sales rhythm.
• Hook in the first 5 seconds — a slightly-off everyday image that makes the viewer ask "怎么回事?".
• Tone must match the story. Warm/healing story → gentle storybook narration; satirical → mock-epic or goofy; cool product → sparse and confident. A grand tragic/Shakespearean voice over a cozy little story feels wrong — match, don't clash.
• One clean CTA at the end: brand + one clear action (and a URL if relevant), held at least one second.

Keep each scene responsible for one idea and one main action; preserve recurring characters/props so it reads as one story, not five unrelated posters.

If the environment has a dedicated screenwriting/scriptwriting skill, invoke it to develop the script — but the sign-off gate below is mandatory either way.

GATE: present the script + storyboard + dialogue and get an explicit approval from the user before any production. Nothing is generated until then.

Phase 3: Lock the visual system

Read references/collage-dimensions.md before generating the first frame. Specify:

• Exact background field and paper grain.
• Halftone dot shape and density.
• Cut-edge treatment and white keyline.
• Drop-shadow offset, softness and opacity.
• Brand color allocation.
• Label placement and typography character.
• Negative constraints.

Generate the first frame as the style anchor. Inspect text, brand mark, materials, shadows, character tone and negative space. Do not generate the complete set until this anchor is acceptable.

For every later frame, provide these references in order:

1. The approved first frame as the strict style reference.
2. The previous scene as the continuity reference.
3. The official brand icon or product image.
4. The most relevant real product screenshot.

Repeat the complete material description in every generation prompt. Generators have no memory between calls.

Use the prompt scaffold in references/prompt-patterns.md. Burn short scene labels into the image only when the generator reliably preserves them. Keep exact text brief and inspect every result for malformed Chinese, incorrect URLs and invented format labels.

Phase 3.5: Gemini Omni motion draft and surgical edit pass (optional)

When the ChatCut plugin is installed and the user has video-generation entitlement, use Gemini Omni (model: "omni", backend gemini-omni-flash-preview) between approved keyframes and final animation. Read references/gemini-omni-flash.md and copy examples/omni-pass.json as the shot plan.

Use this pass for two jobs only:

1. Motion drafting: animate an approved keyframe with firstFrame to test timing, staging and comic beats before spending on a finishing generation.
2. Surgical repair: pass an existing clip through continueFrom to change one localized property while preserving unmentioned content.

Treat Omni as an editing and drafting layer, not a finishing model. It outputs 720p/24fps, supports 3–10 second clips, and only accepts 16:9 or 9:16. Pick exactly one of firstFrame, refImages or continueFrom; omit resolution. It cannot use a last frame, extend a clip, bridge two clips, accept audio references or replace spoken audio.

Write the motion prompt in English, use positive instructions such as locked-off static camera, and track no more than three important subjects. Do not ask Omni to render Chinese or other CJK text. Add exact labels, URLs, UI and wordmarks later with HyperFrames or another deterministic overlay.

Approve or reject each Omni draft before final animation. If 720p is acceptable, an approved output may become the scene source. If delivery requires 1080p, longer duration, exact typography, or whole-shot motion/camera changes, use the Omni clip only as a motion reference and finish with Seedance 2, Kling or HyperFrames. Stop deep edit chains: from round four onward, regenerate from a clean source because quality loss and full regeneration cost compound.

Phase 4: Animate

Route A — AI image-to-video (Seedance / jimeng via arkcli), best for organic motion + native foley. Prefer real element assembly when a capable image-to-video tool is available:

• Start on the empty paper field.
• Slide paper elements in from edges one by one.
• Settle each shadow as its element lands.
• Reveal the label last.
• Hold the complete frame long enough to read.

Use one video model for the delivered set to preserve motion and texture consistency. If prompt-driven assembly fails, use a start-frame and end-frame interpolation model.

Route B — HyperFrames (code-driven, KEY-FREE) — preferred with no video-model key, and preferred for precise scenes even when you have one. HyperFrames renders HTML + GSAP compositions to MP4 locally (node + headless Chrome + ffmpeg, no API key, no limits). It is better than any video model for precise, deterministic motion — the exact stuff models get wrong: a logo whose outer shutter rotates while the center stays perfectly still, a UI that reveals its file list row by row, paper elements sliding/settling in stop-motion cadence, text that bounces on beat. Read references/hyperframes-route.md and start from examples/hyperframes-logo-composition.html.

The non-negotiable rule for paper-cut in HyperFrames: animate real paper assets, never fake paper in CSS. Feed AI-generated cut-paper PNGs (background field + cut-out element layers) and choreograph those with GSAP; a flat CSS/gradient look is the "flat vector pretending to be paper" trap. The precise-logo trick: two stacked copies of the paper-cut icon — the outer one clipped to a circle and rotated, a static inner copy clipped to the center circle locking the ear in place. Bonus: all text is real HTML, so wordmarks and URLs never mis-spell (unlike AI-rendered text).

Hybrid is ideal: cheap motion experiments or localized short-clip repairs → Gemini Omni; organic/physical finishing scenes (files raining, chaos, natural motion + native foley) → Seedance or Kling; precise brand/UI/logo/text scenes → HyperFrames. Anyone without a video-model key can skip Omni and do the whole film in HyperFrames.

When neither is available, render the approved keyframes with the deterministic FFmpeg fallback in scripts/render.mjs. Use short camera movement in the first part of each shot, transition at the scene boundary, and hold the back half for reading. Do not use perpetual breathing, random drift or rapid template transitions.

For actual local cutout assembly instead of whole-frame camera motion, read references/local-layer-animation.md for the method, then drive it with scripts/layer-animate.mjs. Split each finished frame into feathered transparent-PNG paper layers, describe each layer's entrance edge and final position in a manifest matching examples/layer-manifest.json, and run:

node <SKILL_DIR>/scripts/layer-animate.mjs \
  --manifest ./manifests/scene-01-layers.json \
  --output ./renders/scene-01.mp4

The animator slides each layer in from its edge with stepped stop-motion cadence, crossfades the untouched finished frame over the assembled result for the final hold, and verifies dimensions, duration and frame count. Each layer PNG must already include its own soft shadow. This produces a scene MP4 that assemble.mjs can stitch.

Render every scene as its own MP4 before the final assembly. This keeps scene retiming reversible. When extending a rushed cut, slow each scene independently with source-to-target setpts ratios; do not globally slow the mastered MP4.