io.github.GarAlex/promoshot

The whole vocabulary through one door: a batch of the editor's own commands applied as ONE atomic step — delete, move, rename, enable, retime; addLayer/addResource whole; updateLayer / patchResource / patchSettings as JSON merge patches (only the fields you pass change; null removes) — a wipe is {"transitionIn": {"kind": "wipe", "duration": 0.5}}, a swap is upsertKeyframe with resourceID and a transition, a trim is patchResource; setMarkers replaces the timeline's markers and chapters whole. Every command succeeds or nothing is written. The schema of `commands` IS the editor's Command enum.

What changed since you last looked, in the format's own terms: two projects compared by entity — settings by key, resources and layers by id, keyframes by id — as lines you can act on. Copy metadata.json aside before a person's turn, then diff against the copy.

The agent's debugger: why is this layer where it is — the renderer's OWN numbers at a moment. Per layer: visible and why not, the resource shown (swap-aware), the resolved transform and the rect on the canvas in pixels, opacity, rotation, tilt, viewport, gain, the keyframes bracketing the moment, transitions and fades; per project: timing problems and validate's warnings. Defaults to the composition's midpoint.

Create a project folder: metadata.json boilerplate, canvas, palette, a background layer, ids minted. The file it writes is ordinary metadata.json — hand-edit it freely afterwards; the schema stays the source of truth. Never overwrites. A thumbnail comes attached.

Canvas, duration, layers by kind, undefined colours, and any layer whose media is missing.

Eyes on the footage: N evenly spaced frames tiled into one PNG contact sheet, sampled times returned so a cell maps to a moment. Look at this before deciding what a clip shows.

The facts of one source file or SEVERAL, before composing with them: container, duration, streams — codec, size, fps, display rotation, channels. Distilled JSON, not ffprobe's firehose. Each answer carries the `resource` entry that file becomes, ready to paste into `resources` with its pixel size already measured — which is what a `placement` rule needs to resolve against anything other than a square.

Eyes for CUTS: per-frame scene-change scores distilled to cut times and the shots between them — the footage-first answer when a clip has no silence gaps to cut on. Scores are ffmpeg's scene score (0..1, motion-suppressed); 0.4 catches hard cuts.

Ears on the footage: where the sound is NOT — silence spans and their inverse, the sound spans an edit actually wants. Cuts and captions land on these boundaries.

Eyes on a model: a .glb rendered from N yaws round it, tiled into one PNG contact sheet with each cell's yaw. Look at this before choosing a camera for a model layer. (`promo_media_probe` on a .glb names its material slots, clips and bounds.)

Build tier-1 proxies (960 px long edge, every frame a keyframe) for every video resource in a project, in the proxy cache outside the package. Stills, frames and small renders then read them by default (proxy: auto) — what makes an hour-long 4K source scrub and render like a short one.

LOOK at the composition: moments rendered to PNGs and tiled into one contact sheet, attached to this reply as an image. Bare, it samples 12 moments across the whole piece — the fastest way to catch an off-centre card, an empty frame or a mis-aimed viewport. Name `times` for exact moments, or a from/to/fps range for every frame in it (240 at most). Frames from this tool's own previous call in the same folder are replaced, never mixed.

Render a looping GIF — the preview format, needing no ffmpeg. Default 12fps. Returns the path written.

Render one PNG at a moment. Returns the path written, never the bytes.

Render the mp4, audio mixed — needs ffmpeg on PATH. Returns the path written.

The authoring subset of the .promo format plus four complete, validated recipes. Read this once before authoring; promo_schema_full is the whole format.

The whole .promo format, from the same single file the engine compiles in — sprites, masks, motion paths, duration rules, waits, gradients, palette roles and all. 67 KB whole: pass `topics` to take only what this piece needs.

The format as a JSON Schema, types only, GENERATED from the parser's own structs — fill a structured object against this instead of freehanding JSON; the prose lives in promo_schema.

The wizard, for agents: pictures and clips in, a complete show out — the same arrangement the apps' wizard builds. kind classic (one slide at a time, crossfade by default), carousel (cards fly in and settle), or appStore (a store listing: your shots in one device frame over a background, a headline per shot, the canvas the store's own size). Creates the project folder and copies the media in; refine with the other tools afterwards. Never overwrites.

Synthesize narration for every resource whose speech.text says something, spending the PERSON'S OWN provider key from the OS keyring (`promoshot-mcp key set <provider>`) or, where there is none, a secrets file (OPENAI_API_KEY_FILE or /run/secrets/OPENAI_API_KEY), matching each script's provider (default openai/alloy). Unchanged text is reused by receipt, never billed twice. Keys are checked for EVERY pending narration before anything is bought, and each bought receipt is written back at once. Without a key an agent CANNOT narrate — record a voice file into Resources/ and reference it as an ordinary audio resource instead.

Ears for WORDS: a transcript with timings, the draft captions are cut from. Headless this needs whisper.cpp's whisper-cli on PATH and WHISPER_MODEL set; without them an agent cannot transcribe and the refusal says so.

MOTION in the format's own language: create or merge ONE keyframe on a layer. A second placement keyframe is a push-in, viewport keyframes are a Ken Burns ride, colorHex ramps a background. Pass an existing keyframe id to UPDATE — only the fields you pass change. Creating without transitionDuration ramps from the previous keyframe (a stated 0 holds). Swaps, waits and motion paths stay ordinary JSON edits.

SCAFFOLD one layer — image, video or caption — with a placement, a fadeIn, a device/border frame. Media is copied in, sizes and durations probed, the composition re-stretched every call. Pass an existing id to UPDATE: only the fields you pass change, placement merges into the first keyframe, hand-added keyframes survive. This is the scaffold, not the whole format: motion and viewport ride promo_upsert_keyframe; transitions beyond fadeIn are ordinary JSON edits — start from a promo_schema recipe. A thumbnail sampled at the touched layer's midpoint comes attached — LOOK at it before the next edit.

Decode a project with the renderer's own parser and report everything it would silently correct. 'ok' means it will render. A mid-composition thumbnail comes attached — glance at it.

A narration provider's voices — id, name and a line of detail per voice (openai's fixed roster; elevenlabs and google list live) — with the person's own key: the OS keyring (`promoshot-mcp key set <provider>`), else a secrets file (OPENAI_API_KEY_FILE, or /run/secrets/OPENAI_API_KEY) where there is no keyring. Use before promo_speak to pick a voiceID.

The folder this machine keeps assistant-authored projects in. Create new .promo folders here.