Spoken-word B-roll paper collage animation (gbro-collage-broll)

The user gives a roughly 5-second spoken script line, and you help come up with a visual metaphor, then turn it into a halftone paper-collage assembly animation: paper pieces slide into the frame one by one and lock into place, like stop-motion, rather than a fade-in plus slow push. The underlying tool is the open-source gbro-collage-broll (MIT license, by pyang5166). Default output: 9:16, 5 seconds, 720×1280, 24 fps, no sound, so it can sit directly under the spoken line.

Companion tutorial: Turning a spoken line into paper collage B-roll.

Triggers

The user says "collage b-roll", "paper collage b-roll", "halftone collage", "collage-style visuals", "make a collage animation from this script", or wants a line of script, an opinion, or an abstract concept turned into visuals for a short video.

Hard rules

1. The three confirmation gates must be followed, no skipping. Gate one only produces the visual metaphor proposal, with no images and no videos; still frames are produced only after the user confirms; video is generated only after the still frame is confirmed. In batches, only items the user has confirmed move to the next step.
2. Gates one and two do not call any video model. Changing text costs nothing, regenerating an image is cheap, and rerunning a video is expensive, so the money-spending step is saved for last.
3. Video is paid from the user's own account. It uses the user's GEMINI_API_KEY, billed per use. Remind the user once before entering video generation, and do not decide how much to spend on their behalf.
4. Do not output or log the key. Only check whether the environment variable is set; do not print its contents.
5. Say so before installing anything. Get consent before creating a virtual environment or installing dependencies; do not use --break-system-packages; if a virtual environment already exists, reuse it rather than creating a new one in every project.
6. Do not let the user pick the default model. After the still frame is confirmed, use Gemini Omni Flash directly for the first-and-last-frame video; switch only if the user explicitly names a different model, and do not automatically fall back to the old Veo pipeline.
7. The final output must be silent. Even if the prompt says no sound, strip the audio track with ffmpeg before delivering.
8. No text in the frame. No subtitles, full spoken script, logos, watermarks, or interface elements; if fake text appears, regenerate from the still frame, and do not try to patch it at the video stage.

When not to use this

• You need precise control over layers, occlusion, camera passes, or an editable timeline: use a layered animation tool instead.
• The user only wants a video prompt, not a finished video: just write the prompt, no need to run the process.
• The user needs a real-person product ad or a spokesperson on camera: do not use the collage process.
• The user wants layer-by-layer editable transparent assets: this process does not split layers by default.

Installation and environment

First check whether it is already installed:

ls ~/.agents/skills/gbro-collage-broll ~/.claude/skills/gbro-collage-broll 2>/dev/null

If it is not installed, first tell the user this will place a third-party skill on their computer, and once they agree:

git clone https://github.com/pyang5166/gbro-collage-broll.git ~/.agents/skills/gbro-collage-broll

Each time this is triggered, run the repository's built-in self-check script first, and only proceed to gate one if everything passes:

bash ~/.agents/skills/gbro-collage-broll/scripts/check_setup.sh

Requirements:

Requirement	Notes
Codex environment	Still frames rely on its built-in image generation tool; in other agents, the user needs an equivalent image generation method, or should supply the still frame directly
GEMINI_API_KEY	Created in Google AI Studio; video is billed per use
Python 3.10 or later	Runs the video script
google-genai 2.10.0 or later	Installed in the shared virtual environment ~/hyperframes-projects/.omni-venv/
ffmpeg and ffprobe	For first/last frames, audio stripping, and comparison images

If the self-check has gaps, do not enter gate one; just tell the user what is missing, and re-run the self-check once it is configured.

Gate one: metaphor only

Compress the script into one clear visual proposition; do not transcribe it word for word onto the screen. Each script gets one metaphor, with 3 to 6 key objects; more than that weakens the meaning and makes assembly unstable.

For each item given to the user, include: the core meaning, the mood, a one-sentence visual proposition, the key objects, suggested background and accent colors, and the expected assembly order. Then stop and wait for the user to say "approved" or give revision notes.

Choose background colors based on meaning. A batch keeps one design language, but backgrounds may differ: red or orange for time consumption and urgency, yellow for warning and lost experience, dark green for cognition and systems, purple for norms and accumulated knowledge, teal for judgment and collaboration.

Gate two: still frame

Once the metaphor is approved, first write a visual brief (metaphor, background color, elements and their positions, composition, final image, and things to avoid), then use the image generation tool to make the final still frame. Key points:

• A flat, solid-color paper field, with the main subject as black-and-white halftone photo cutouts, plus a few colored cardstock accents.
• Vertical 9:16, subject concentrated in the middle, with ample solid-color empty space, divided into 3 to 6 large groups that can each slide in on their own.
• Paper pieces have clean cut edges, a thin cream-white border line, and soft shadows.
• No text, numbers, logos, watermarks, interfaces, realistic environments, or a screen full of fragments.

After producing it, check: is the metaphor understandable at a glance, is there any fake text, and is there enough solid-color empty space. Save the original image in the project directory, assemble a numbered overview image for the user to review, then stop and wait for confirmation. If regeneration is needed, produce a new version of the overview image without overwriting the old one.

Gate three: video

1. Prepare the first and last frames. The last frame is the confirmed still frame, normalized to vertical dimensions with ffmpeg; the first frame is an empty paper field in the same background color as the last frame. Keep a base object only if the user explicitly asks not to start from blank.
2. Write the animation prompt. State that the first image is the empty first frame and the second image is the confirmed finished frame; require a fixed camera, no cuts, no zoom, no distortion, no added objects, no text, and no sound; in the order "base structure → people or key cards → connectors → action → final result," specify how each element slides in and locks into place.
3. Check the environment. Confirm the google-genai version is new enough and the key is set.
4. Batch generation. Write the tasks into omni-jobs.json, giving each task a prompt, the first and last images, an output path, 9:16, and 5 seconds, then run the repository's built-in script:

~/hyperframes-projects/.omni-venv/bin/python \
  ~/.agents/skills/gbro-collage-broll/scripts/generate_video.py \
  --batch <project directory>/omni-jobs.json --concurrency 3

5. Strip audio. Use ffmpeg to copy the video stream and remove the audio, delivering a silent version.
6. QA. Do not only look at the last frame: extract frames every second to make an overview image, check whether the first frame is close to an empty field, whether the middle section truly assembles piece by piece rather than fading in as a whole, whether there are cuts or zooms, and whether there is fake text; then place the final frame side by side with the confirmed still frame for comparison. The finished video should be 720×1280, 24 fps, 5 seconds, with zero audio tracks.

Common issues

• Paper edges show slightly early in the first frame: Minor is acceptable; for strict empty-field requirements, consider using an editable-timeline tool to fix the early section.
• Weak sense of assembly: Reduce the number of elements and rewrite the prompt with an explicit piece-by-piece slide-in and locking order.
• Last frame drift: Emphasize that the second image is the finished frame and require the ending to keep that composition. Minor pose or small part changes that do not affect the metaphor count as a pass; do not rerun for them.
• Fake text appears: Regenerate from the still frame; do not patch it with the video prompt.
• Individual video failures: Rerun only the affected task, leaving approved ones untouched.
• Old Veo script: Kept in the repository for compatibility only; do not use it unless the user explicitly asks.

Output format

1. For each finished video: the path (silent version), the per-second overview image, and the final-frame comparison image.
2. One sentence per script explaining how it became a visual metaphor.
3. If there are flaws but it is judged a pass, state the reason; if the problem comes from model limitations, say so directly.
4. A reminder that video is billed per use to the user's own account.