Promoshot

promoshot

See it work: demo.md — technique prompts and open-ended creative briefs, each given to a fresh agent with only the skill and the MCP, its result beside the hand-built reference. The suite is in demos/.

The rendering engine behind PromoShot (App Store), and an open implementation of its project format. A .promo project is a folder — metadata.json plus its media — and this workspace is everything needed to validate, inspect, and render one to stills, image sequences, or mp4 with mixed audio: no app attached, byte-for-byte the same compositor the apps ship.

The design bet is that the format is the interface. An assistant, a script, or a person writes metadata.json; the engine renders it the same everywhere — the Mac and iOS apps (Metal + VideoToolbox), this repo's CLI, or a headless Linux box with no GPU at all (wgpu on lavapipe, ffmpeg as a subprocess). The format has three faces behind one truth: an authoring subset with four validated recipes (promo schema), the full document (--full), and a types-only JSON Schema generated from the parser's own structs (--types) — and the parser the validator runs is the parser the renderers use, so "validates" means "renders".

Not the other PromoShot

This is the open engine (and App Store app) for [PromoShot](https://promoshot.app) by Alexander Garmash — a full layer / keyframe / timeline editor for screen recordings, video, and photos (Mac; iPhone and iPad open the same .promo projects).

It is not the similarly named App Store apps that turn screenshots into template videos (for example “PromoShot: Screenshot to Video”). If you want keyframes, masks, GPU compositing, and an open .promo format, you want this one: promoshot.app · App Store.

Product listing / PAD

Consumer apps: promoshot.app · App Store. Software directories can ingest this PAD 4.0 file:

https://raw.githubusercontent.com/GarAlex/promoshot/main/promoshot.pad.xml

Crates

Build and verify

./check-all.sh          # fmt, clippy -D warnings, all tests, release build

Rendering video needs ffmpeg (and ffprobe) on PATH — frames are composited on the GPU and piped to it raw; ffmpeg only decodes and encodes. On a headless Linux machine, mesa-vulkan-drivers (lavapipe) is enough of a GPU.

Headless Linux, no GPU

The Linux release tarball carries its own CPU renderer: a lavapipe/ folder (Mesa's lavapipe, its libraries and a Vulkan loader; licences in lavapipe/NOTICES.txt) beside promo. Keep the folder next to the binary and a machine with no Vulkan driver at all — a fresh container, or a redeploy that dropped mesa-vulkan-drivers — still renders. promo picks, in order: a real GPU; the system's lavapipe; the bundled lavapipe (saying so once on stderr); SwiftShader, with a warning, since it is 10–50× slower than lavapipe. With none of them it lists what it tried and the fix (sudo apt-get install -y mesa-vulkan-drivers libvulkan1). PROMO_LAVAPIPE= points at the folder elsewhere; PROMO_LAVAPIPE=off never uses it. The binaries need glibc 2.39 (Ubuntu 24.04, Debian 13). A machine with no fonts at all still renders: text falls back to a built-in face (Tuffy) with a warning; install fonts-dejavu-core and fonts-liberation for real ones.

What a CPU costs, measured on a 703-frame 1080×1920 reel with narration:

(lavapipe in an amd64-emulated ubuntu:24.04 container; SwiftShader took about half an hour on a comparable reel.)

promo video survives being killed. It encodes in segments (10 s of video each; --segment ) into .promo-parts/ beside the output, and the same command run again skips the finished segments and goes on from there, saying how many it found. The segments are joined without re-encoding, the soundtrack is mixed once for the whole range and muxed in at the join — no edge in the sound, in sync to the sample — and the folder is removed on success. The folder is keyed by a digest of the project's files and the render settings, so an edited project starts over instead of reusing stale segments. --from/--to take seconds (12.5) or frames (375f), to split a long render into chunks.

The CLI

cargo build --release -p promo-cli     # -> target/release/promo

promo schema # authoring subset + recipes; --full, --types promo validate [--strict] # "NOT OK" lists what will not render; --strict exits 1 on any finding promo inspect # canvas, layers, missing media, undefined colours promo upsert-keyframe --args '{"layer":"bg","time":2,"zoom":1.2}'

the MCP authoring tools as verbs (init, upsert-layer,

upsert-keyframe, apply, slideshow, explain, diff)

promo still --out f.png --time 2.5 promo frames --out frames/ --fps 30 --from 0 --to 4 promo video --out out.mp4 --fps 30 # resumable; --from/--to 12.5 or 375f

Add --json to any project command for machine output — one object on stdout, errors included, exit codes unchanged.

promo video mixes the soundtrack the apps would: trims and media cuts, held frames, speed with pitch preserved, keyframed volume, a focused narration ducking everything under it, and only the audio tracks the project keeps.

Headless renders are CLEAN — no watermark, and no license, serial or key will ever be asked for. (The Mac and iOS apps watermark free-tier renders; that is their App Store Pro line, and it stays on their side of the fence.)

The MCP server

promoshot-mcp speaks Model Context Protocol over stdio, so any MCP client can author, inspect and render projects. It owns no rendering code — every render shells to promo (found next to the executable, or on PATH, or via --promo), so the CLI stays the single contract.

Connect an agent

Two pieces: the MCP server (tools) and the skill (workflow). Neither is vendor-specific. Agents do not find this repo by themselves.

The apps open what this engine writes from PromoShot 3.0 on. The App Store's 2.3.1 reads projects up to minReaderVersion 17 (no nested compositions, no 3D) and cannot be launched with --mcp-stdio.

1. Build — or don't

cargo build --release -p promo-cli -p promoshot-mcp

binaries: target/release/promo target/release/promoshot-mcp

scripts/install-local.sh # …and on PATH, linked from target/release,

so every later build is what runs

No Rust toolchain? Grab the prebuilt pair from Releases (linux-x64, macos-arm64; each asset's sha256 is on the release), or pull the image: docker pull ghcr.io/garalex/promoshot-mcp — both carry promo and promoshot-mcp together.

Put both on PATH, or pass --promo to the server. Rendering video also wants ffmpeg/ffprobe on PATH. promo skill install then puts the agent skill where every agent tool on the machine reads it — the shared ~/.agents/skills (Codex, Gemini CLI, Cursor, GitHub Copilot, Grok Build) and the own folder of each tool found that reads only its own (Claude Code, Antigravity); promo skill prints it.

2. MCP (required for tools)

Claude Code / Cursor / any mcp.json:

{

"mcpServers": { "promoshot-headless": { "command": "/ABS/PATH/target/release/promoshot-mcp", "args": ["--workspace", "/ABS/PATH/Promo", "--root", "/ABS/PATH/Promo"] } } }

--workspace is where new projects go; --root fences which projects the server will touch — pointing both at one folder is the tidy setup. Both optional. --log appends one line per tool call — when, which tool, how many milliseconds, how it went — for a session's own accounting; the demo pages are built from it.

Client one-liners:

# Claude Code

claude mcp add promoshot-headless /ABS/PATH/target/release/promoshot-mcp

Grok Build

grok mcp add promoshot-headless -- /ABS/PATH/target/release/promoshot-mcp \ --workspace /ABS/PATH/Promo --root /ABS/PATH/Promo grok inspect # confirms the server registered

Docker — the host needs nothing but docker (details below)

docker build -t promoshot-mcp .

then command: docker, args: ["run","-i","--rm","-v","/ABS/PATH/Promo:/projects","promoshot-mcp"]

On a Mac with PromoShot 3.0 installed, the app is a server too — the same tools, with the person's open document, undo and approvals behind them. Switch Automation on in PromoShot's Settings, then register the app itself; it launches when the client starts it:

claude mcp add promoshot -- "/Applications/PromoShot.app/Contents/MacOS/PromoShot" --mcp-stdio

Settings ▸ Automation shows that line with this Mac's own path, and the URL form for clients that take one. promoshot names the app and promoshot-headless the binary, so both can be registered side by side; the skill asks which to use when both are there.

3. Skill (the workflow)

Same file everywhere: skill/SKILL.md.

REPO=https://github.com/GarAlex/promoshot

git clone --depth 1 $REPO /tmp/promoshot

Claude Code (Grok Build also scans this folder)

mkdir -p ~/.claude/skills/promoshot cp /tmp/promoshot/skill/SKILL.md ~/.claude/skills/promoshot/SKILL.md

Grok Build explicit path

mkdir -p ~/.grok/skills/promoshot cp /tmp/promoshot/skill/SKILL.md ~/.grok/skills/promoshot/SKILL.md

OpenAI Codex / many others

mkdir -p ~/.agents/skills/promoshot cp /tmp/promoshot/skill/SKILL.md ~/.agents/skills/promoshot/SKILL.md

Cursor project (in the repo the user is editing, not this engine repo)

mkdir -p .cursor/rules cp /tmp/promoshot/skill/SKILL.md .cursor/rules/promoshot.md

or: mkdir -p .agents/skills/promoshot && cp SKILL.md there

Any agent that reads instructions can be handed the file directly; it assumes only these tools (or the CLI).

4. Verify — ask the agent for a render:

Render examples/ProductCard.promo to a still at 3s.

One promo_validate, one promo_render_still, and a device-framed app demo comes back as a path. From there, "make me a promo for " is the loop the skill teaches.

The tools

Tools: promo_schema (authoring subset + four validated recipes; promo_schema_full is the whole format; promo_schema_types is the format as a generated, types-only JSON Schema — also checked in at docs/promo.schema.json for $schema editor au