Editorial Collage Director

An agent skill for turning a topic, script, portrait, product photo, or talking-head clip into a short editorial paper-collage film.

It keeps the best idea from vox-director: design the collage as finished poster keyframes first, then add motion in a separate pass. It removes the Atlas Cloud dependency completely.

There are no hard-coded model IDs, hosted API endpoints, provider keys, vendor job queues, or vendor watermarks. The skill uses whatever image, video, and speech capabilities the agent already has. Its fallback path needs only local ffmpeg; local narration can use macOS say, espeak-ng, or espeak.

What it does

brief
  -> beat map                         gate 1: approve the story
  -> three-direction visual bake-off gate 2: choose the look
  -> poster keyframes
  -> narration-led timing
  -> optional image-to-video
       or deterministic local motion
  -> captions, optional music, final assembly
  -> frame and audio verification

The default local motion path supports static holds, pushes, pulls, pans, tilts, and a clearly labeled whole-frame parallax approximation. Assembly writes final.mp4 and a captions.srt sidecar. If Pillow is installed, captions can also be burned into the video.

Install

Clone the repository into your agent's skill directory, or point an agent that understands SKILL.md at this repository.

For Codex:

git clone https://github.com/Ilm-Alan/editorial-collage-director.git \
  ~/.codex/skills/editorial-collage-director

Restart the agent after installing a new skill.

Requirements

• an agent that can follow SKILL.md and invoke an image-generation capability;
• Python 3.10 or newer;
• ffmpeg and ffprobe;
• Pillow only when burning caption images;
• optional local speech engine: macOS say, espeak-ng, or espeak.

No specific AI media provider is required.

Use

Ask the agent:

Make a 30-second vertical editorial paper-collage explainer about why octopuses have three hearts.

The agent creates a project directory in the current workspace and uses a provider-neutral project.json. A complete example lives at examples/minimal.project.json.

The local stages can also be run directly:

python3 scripts/validate_project.py out/my-film/project.json --stage plan
python3 scripts/narrate.py out/my-film/project.json --engine auto
python3 scripts/validate_project.py out/my-film/project.json --stage keyframes
python3 scripts/animate_stills.py out/my-film/project.json
python3 scripts/validate_project.py out/my-film/project.json --stage motion
python3 scripts/assemble.py out/my-film/project.json

Keyframes are generated or edited by the agent's available image capability and recorded in project.json. When a suitable image-to-video tool exists, the agent may use it in place of animate_stills.py.

Repository layout

SKILL.md                         agent workflow and quality bar
agents/openai.yaml               Codex presentation metadata
references/story-and-pacing.md   arcs, hooks, timing, camera grammar
references/visual-direction.md   bake-off, image prompts, anchor handling
references/project-schema.md     provider-neutral project format
scripts/validate_project.py      stage-aware manifest validation
scripts/narrate.py               local speech fallback
scripts/animate_stills.py        deterministic local motion
scripts/assemble.py              captions, audio mix, final ffmpeg render
examples/minimal.project.json    starter project

Attribution

This is a provider-independent derivative inspired by the MIT-licensed Alisa0808/vox-director. The upstream copyright notice and pinned revision are preserved in LICENSE.txt and NOTICE.md.

License

MIT. See LICENSE.txt.