Editorial collage director

Editorial collage director

Make a finished editorial paper-collage film without assuming any particular media provider. The durable idea is simple:

1. The collage look is designed in still images.
2. Motion is a separate stage.
3. Story structure and visual direction each get an explicit human decision gate before expensive generation.

Read references/story-and-pacing.md before drafting the beat map. Read references/visual-direction.md before writing image or motion prompts.

Route capabilities first

Inspect the capabilities and local binaries that are actually available. Never ask for a particular vendor key merely because this skill was triggered.

• For keyframes, prefer the installed image-generation or image-editing capability. When OpenAI's imagegen skill/tool is available, use it.
• For motion, use an available image-to-video or video-editing capability when it materially improves the brief. Otherwise use scripts/animate_stills.py, which creates clean local camera motion from the posters with ffmpeg.
• For narration, use the user's requested voice service if one is already available. The local fallback is scripts/narrate.py, which uses macOS say, espeak-ng, or espeak. A user-recorded narration file is always acceptable.
• Music is optional. Use only user-provided, generated, public-domain, or properly licensed music. A film with narration and intentional silence is better than mystery-source audio.
• Use scripts/assemble.py for the final local render. It can burn caption images when Pillow is installed and always writes an SRT sidecar.

If a richer capability is missing, take the local path. A missing cloud service is not a blocker.

Working directory

Keep generated projects outside this skill directory. Use a project folder such as out/<slug>/ in the user's current repo. The single source of truth is out/<slug>/project.json; see references/project-schema.md and examples/minimal.project.json.

Resolve all relative media paths from the directory containing project.json. Do not place secrets, remote job IDs, or provider-specific model names in the project file.

Workflow

1. Establish the brief

Infer reasonable defaults from the request:

• audience and objective;
• target duration;
• aspect ratio (9:16 for social, 16:9 for landscape, unless specified);
• language;
• input mode;
• factual sourcing needs.

The modes are:

• topic: write a new narrated film from a topic.
• anchor: preserve a supplied person or product as a photographic sticker while building the collage around it.
• talking-head: retain the original performance if a video-edit capability exists; otherwise transcribe it and recompose it as an editorial B-roll film.

For factual subjects, research claims before scripting and keep a source note beside the project. Do not fabricate statistics, quotations, dates, product claims, or endorsements.

2. Draft the beat map, then gate

Choose an arc from references/story-and-pacing.md. Draft project.json with:

• a hook that lands within about three seconds;
• concise narration sized to the duration;
• one visual job per beat;
• usually two shots per beat: an orienting poster and a detail cut-in;
• varied adjacent camera moves;
• a payoff, button, or single clear call to action.

Run:

python3 <skill-dir>/scripts/validate_project.py out/<slug>/project.json --stage plan

Show the beat map to the user before generating media. This is gate 1. If the user explicitly asked for a fully autonomous run, choose the strongest version and record the choice in decisions.beat_map.

3. Run a visual bake-off, then gate

Propose three genuinely different directions that suit the subject's era, culture, and tone. Render the same representative shot in all three. Do not merely recolor one prompt.

Present the candidates as a labeled contact sheet or separate images. Ask the user to pick one. This is gate 2. For an autonomous run, choose the best candidate by inspecting it at full size and record the choice in decisions.visual_direction.

Lock the winner in visual_direction. Reuse its medium, paper treatment, palette, typographic logic, edge language, and lighting across every keyframe.

4. Establish timing with narration

Speech determines the edit. Generate or attach one narration file per beat before resolving shot durations.

Local fallback:

python3 <skill-dir>/scripts/narrate.py out/<slug>/project.json --engine auto

The script writes narration_audio and narration_duration into each beat. If narration is supplied or generated elsewhere, add those fields manually. Keep one voice, pace, and recording character across the film.

5. Generate keyframes

Create one finished poster for every shot. Use the selected visual direction and the prompt structure in references/visual-direction.md.

• Compose the scene from visibly separate paper pieces.
• Preserve clear edges, physical paper shadows, and one dominant background field.
• Keep generated headline text very short. For critical spelling, logos, labels, or names, leave a clean text zone and add typography in post.
• For anchor mode, edit around the supplied subject. Keep the subject pixel-faithful; do not casually regenerate a face, product geometry, or label.
• Inspect each image before motion. Re-roll weak, muddy, overly smooth, or illegible posters now.

Save keyframes under keyframes/ and update each shot's keyframe_path. Then run:

python3 <skill-dir>/scripts/validate_project.py out/<slug>/project.json --stage keyframes

6. Add motion

Use one camera move per shot. Protect headline and label regions from generative motion. Prefer short shots over an over-scripted long shot.

When an image-to-video capability is available, prompt motion rather than redescribing the still. Require a single continuous shot, restrained amplitude, rigid paper behavior, stable lettering, and no invented objects.

The deterministic local path is:

python3 <skill-dir>/scripts/animate_stills.py out/<slug>/project.json

It supports static, push_in, pull_out, pan_left, pan_right, tilt_up, tilt_down, and parallax. Local parallax is an honest whole-frame diagonal drift, not synthetic layer separation.

7. Assemble

Optional fields such as music gain, narration gain, and captions are documented in the schema. This pipeline does not add a watermark.

python3 <skill-dir>/scripts/validate_project.py out/<slug>/project.json --stage motion
python3 <skill-dir>/scripts/assemble.py out/<slug>/project.json

The outputs are final.mp4 and, when captions are enabled, captions.srt.

8. Verify the actual film

Do not stop at a successful ffmpeg exit.

• Use ffprobe to confirm duration, video dimensions, codecs, frame rate, and audio presence.
• Extract frames near the beginning, middle, payoff, and end. Inspect them.
• Check caption safe areas, spelling, face/product fidelity, black frames, repeated motion, abrupt freezes, clipping, narration intelligibility, and music balance.
• If generative motion was used, compare extracted frames with the keyframe. Re-letter critical text in post when it drifted.

Quality bars

• The first three seconds make a promise, pose a real question, or reveal tension.
• Each beat has one narrative job and one dominant visual idea.
• Adjacent shots do not repeat the same move.
• Paper texture and edge behavior are consistent; palette may travel with the story.
• A keyframe reads as a designed editorial poster, not a generic illustration with a grain filter.
• The edit changes meaningfully every three to six seconds.
• Headlines, labels, faces, and products survive motion intact.
• The final delivery includes the project file and source media paths, not only the MP4.

Attribution

This skill is a new provider-independent adaptation inspired by the MIT-licensed Alisa0808/vox-director project. The upstream license and pinned source revision are in LICENSE.txt and NOTICE.md.