ShotAI

ShotAI is a camera-language expert agent for Codex.

It is built for one problem: HTML video generators easily become animated PPT. ShotAI changes the unit of thinking from slides to shots, then forces every video plan through camera language, visual depth, dynamic assets, overlay discipline, and fail-closed verification.

Positioning

ShotAI is not a generic HTML video template pack.

It is a director-layer agent that answers:

• Should this shot use fullscreen material plus transparent packaging?
• Should packaging lead the composition while material appears only in an inset/local window?
• Should this shot be pure visual packaging: SVG, Canvas, WebGL, chart, or infographic?
• What is the shot?
• Where is the camera?
• What moves in foreground, midground, and background?
• What should be real footage, AI video, UI recording, 3D, or image-motion material?
• What should HTML own as an overlay layer only?
• Does the result still look like PPT?

Core Idea

Use HTML for information layers, not for the whole film.

Video / image-motion / UI recording / 3D / live footage
        +
HTML overlay: titles, captions, HUD, UI/data graphics, brand packaging
        +
Camera treatment, transitions, rhythm, audio cues
        =
Shot-first product video

Every shot must first declare a visual_composition_mode:

• asset_fullscreen_overlay: footage, UI recording, 3D, or image-motion material fills the frame; packaging supports it.
• packaging_dominant_asset_window: packaging is the main composition; material appears inside a deliberate local window.
• pure_visual_packaging: SVG, Canvas, WebGL, chart, or infographic is the full-frame visual.

ShotAI forbids the shortcut "has material means fullscreen" or "no material means pure visual." The Visual Director Agent must combine these forms based on the user's goal, theme, available material, shot beat, and rhythm.

Agent Suite

• Storyboard Agent: turns the brief into shots, never slides.
• Visual Director Agent: defines camera motion, shot scale, depth, rhythm, transitions, subtitle composition, and shot-scoped SVG/Canvas/WebGL language.
• Asset Agent: selects or requests video, image-motion, UI recording, 3D, stock, or product footage.
• Effects Filter Agent: designs shot-specific lighting, filters, LUTs, HUD, scanlines, particles, and VFX overlays with source/license/evidence paths.
• Image Videoization Agent: turns still images into moving shot material with camera motion, parallax layers, masks, light, detail motion, and edit rhythm.
• HTML Overlay Agent: writes the information layer only, with shot-scoped overlay behavior.
• Video Verifier Agent: rejects PPT-like structure and weak visual language.
• Video Packaging Director Agent: upgrades existing videos with dynamic motion-graphics packaging without replacing the source footage.

What ShotAI Forbids

• scene, page, or slide as the contract unit.
• One global caption or effect style controlling every shot.
• HTML-only videos pretending to be cinematic footage.
• Static overlay PNGs presented as dynamic packaging.
• Production requirements leaking into visible subtitles.
• Fake success when render, probe, or verifier evidence is missing.

Existing-Video Packaging

ShotAI can package an existing video without regenerating it:

1. Probe the source video.
2. Generate contact sheets.
3. Build a timecode-bound packaging plan.
4. Render dynamic transparent HTML/Canvas overlay frames.
5. Apply theme-bound crop, zoom, pan, micro-shake, color, and sharpening with FFmpeg.
6. Preserve original audio unless sound redesign is requested.
7. Verify final MP4 metadata, black frames, and overlay frame diversity.

Installation In A Local Codex Marketplace

Place this repository under a Codex local marketplace:

codex-local-marketplace/
  .agents/plugins/marketplace.json
  plugins/shotai/

Marketplace entry:

{
  "name": "shotai",
  "source": {
    "source": "local",
    "path": "./plugins/shotai"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Design"
}

Enable it in ~/.codex/config.toml:

[plugins."shotai@xin-local-plugins"]
enabled = true

Verification

Run the contract verifier:

python3 scripts/verify_shotvideo_contract.py examples/sample_contract.valid.json
python3 scripts/verify_shotvideo_contract.py examples/sample_contract.ppt_like.json

Run the existing-video packaging verifier:

python3 scripts/verify_video_packaging_project.py templates/video_packaging_overlay

Run tests:

python3 -m unittest discover tests

Distribution Message

ShotAI is for teams that want AI-generated videos to feel directed, not assembled from slides. It gives Codex a shot-first video director with camera-language planning, overlay discipline, and hard verification gates.