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; cameraMove {layerID, move: pushIn|pullOut|reveal|orbit|rise, at, duration, degrees?, from?/to? framing} writes a camera move as two keyframes; autoZoom {layerID, amount?: subtle|normal|strong, pace?: calm|normal|brisk, skip?: [[start, end]] source seconds left wide, activity?: a measured activity track stored on the recording in the same step, remove?} plans a screen recording's zooms from its clicks and measured activity into tagged viewport keyframes (a re-plan keeps what a person edited); 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. A model or stage adds its camera (after its 1.05-radii floor) and light, and each slot's binding with where it lands on the canvas and how much of the frame it covers — measured by rendering, so no calibration renders are needed; a stage whose camera aims or flies says per member `inFrame` (whole, cut and which edges, fillsFrame, behindCamera) and its `framing` word; a layer showing a composition adds that composition's layers at the moment, mapped onto the canvas. 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.

What a project contains — canvas, duration, layers by kind with their ids, resources (a file found in Resources/ counted as undeclared) — then any layer whose media is missing or that cannot render, the resources nothing uses, and `@name` colours no palette defines. Confirm a composition matches what you meant before rendering it.

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 — as distilled JSON; on a .glb, its material slots, clips and bounds. 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, `sample` for a count spread over a from/to range, 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 — cheaper to look at than an mp4, and the format for a README or a chat message. Returns the path written.

Render one PNG at a moment and return the path written, never the bytes — SEE the composition at one time before rendering the whole. Writes beside the project, in <Name> Exports/, unless `out` names a path.

Render the whole composition, audio mixed — needs ffmpeg on PATH. H.264 in an mp4 at the project's export size by default, ProRes for an edit-ready master. 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. 73 KB whole: pass `topics` to take only what this piece needs, no section over 5 KB.

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. 80 KB whole: pass `types` for just the definitions you need.

The wizard, for agents: pictures and clips in, a complete show out — the apps' own wizard, one implementation. kind classic (one slide at a time, crossfade by default), carousel (cards fly in and settle), or appStore (a store listing: your shots on one device that moves between them, a headline per shot in the band it leaves, the canvas the store's own size — a 3D body by default, the drawn frame with body slab). narration adds a draft voice per slide, timed by rules so the show re-times when promo_speak lands the sound. 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. A provider with NO key gets a silent placeholder of the estimated length (speech.placeholder: true, no receipt): time the cut against it; the next call with a key voices it. It exports silent and promo_validate says so; `placeholder: false` refuses instead. Provider `local` (voiceID like kokoro-en-q8/af_heart) spends nothing and needs no key: English voices synthesized on this machine, Apache-2.0, safe to publish; takes are .wav. A word the dictionary lacks (a product name) fails with its name — spell it once in Resources/pronunciations.dict (CMU format: `PROMOSHOT P R OW1 M OW0 SH AA2 T`) or write it as words.

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: promo_apply's upsertKeyframe carries any keyframe field.

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, swaps, waits, deletes and reorders are promo_apply commands. 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 say whether it renders as written. NOT OK leads with what will not render or has no effect — a field nothing reads (with the name that was meant), a value that does nothing where it is, missing media; ok means it renders, and any warnings name what the renderer adjusts. Validating costs nothing — do it before asking for a 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. `local` needs NO key: voices synthesized on this machine from installed packages (ids like kokoro-en-q8/af_heart; ones not installed say so — the person runs `promoshot-mcp voices install <package>`). Use before promo_speak to pick a voiceID.

The folder this machine keeps assistant-authored projects in, created if it is missing. Create new .promo folders here.