Ai Promo Video

AI directs. MCP executes. Revideo and FFmpeg deliver the video.

AI Promo Video is an open-source, headless production system for professional promo videos. There is no graphical editor, hosted service, local AI model, or hidden subscription. Users install the project, and the AI they already use in Codex, Claude Code, or Cursor gains the tools and instructions required to plan, capture, animate, render, review, and revise an entire video.

This is not a slideshow generator. Every new production is one editable Revideo and TypeScript composition. The AI searches a broad vocabulary of reusable motion systems, combines only what fits the current story, and writes custom code in the same scene whenever needed. That enables perspective cameras, zoom and tracking, interfaces assembled element by element, choreographed cursors, kinetic typography, masks, filters, particles, SVG, procedural shapes, images, video, shaders, and Three.js scenes without locking the result to a template. FFmpeg handles editing, audio analysis and mixing, inspection, and incremental revisions.

See what it can already do

The videos below play directly on GitHub. The full-resolution final MP4 files also remain versioned with their editable examples.

SignalNest — SaaS motion benchmark · 56 seconds

https://github.com/user-attachments/assets/ca33b482-2330-46d2-a270-008b0d717a9a

A fully procedural composition created to test the visual language of a polished SaaS launch: per-word and per-letter motion, animated gradients, erase and rewrite effects, text pushing other text, typography-driven masks, particles, orbit systems, perspective UI, cards assembled in the scene, automation traces, and a final CTA. Music: “Synth/bass Short or Intro” by griffon_designs, CC0 1.0.

QANode — product assembly and camera motion · 9.6 seconds

https://github.com/user-attachments/assets/09ed9971-f1de-4b95-8300-4b29ab71a49c

The interface begins empty. The camera locks onto the left navigation while each menu item is created, follows the click on Scenarios, shifts its focus, and reveals the list row by row. The product screen was reconstructed as an animatable composition instead of relying on a rigid transition to a screenshot.

AINDA — emotional storytelling · 61 seconds

https://github.com/user-attachments/assets/93ade655-8b51-44e9-9218-bf3950bd7ab7

A test outside the SaaS category designed to prove narrative direction: freely licensed online footage, music-driven editing, pacing, atmosphere, image treatment, and emotional typography. Music: “Emotional Original Soundtrack — BETTER LIFE” by Magmi.Soundtracks, CC BY 4.0. Complete media credits remain with the project.

Why this project exists

Recording an application is only raw material. A strong promo also needs a story, hierarchy, rhythm, camera movement, transitions, scene design, music, and dozens of small decisions that would normally be spread across screen-recording software, After Effects, and a video editor.

This project separates that problem into two parts:

• The Skill is the director. It teaches the AI how to turn a brief into a distinct story and art direction, choose what to capture, discover motion components without treating them as templates, compare music without a default track, and review its own work.
• The MCP server is the production crew. It provides progressive contextual help plus deterministic operations for navigating the product, recording it, searching the motion library and free media, analyzing music, writing scenes, rendering, editing, extracting review frames, replacing only a damaged interval, and cleaning the delivery directory.

No AI model is bundled with the project. Codex, Claude, or Cursor uses the model already selected by the user. For clients that do not discover filesystem Skills, the MCP server exposes the same directing guide through a prompt and resources.

From a request to a finished MP4

When a user asks for “a 30-second promo for this SaaS,” the AI follows this production cycle:

1. Understands the product, audience, promise, duration, format, and references.
2. Inspects the real application and decides which flows must be recorded.
3. Captures clean screenshots or product footage, including user-configured authenticated sessions.
4. Writes the musical intent, then searches local or online sources for music, footage, and assets with known licenses. Bundled tracks are optional and excluded unless explicitly requested.
5. Writes a story, art direction, beat map, musical accents, and camera logic for this production rather than copying a fixed scene arc.
6. Searches the component vocabulary, loads detailed help only for the selected tools/components/transitions, and creates the real Revideo/TypeScript composition from those primitives plus custom code. It never renders a generic template to replace later.
7. Renders H.264/AAC video at 24–60 FPS and up to 4K.
8. Extracts frames from the full film and around every transition so the AI can inspect its own output.
9. Fixes visual anomalies, timing, typography, camera motion, or composition. If a problem is isolated, it rerenders and replaces only that interval.
10. Keeps only the editable project, credits, and approved MP4 in the delivery directory.

The AI gains autonomy without turning generation into a black box: the scene remains readable code, media retains attribution manifests, and every render can be reproduced.

Installation

Requirements: Node.js 20 or newer on macOS, Linux, or Windows.

Quick install

Install AI Promo Video for Codex, Claude Code, Claude Desktop, and Cursor with one command:

npx --yes github:MendesCorporation/ai-promo-video install

The installer downloads a stable local runtime, installs production dependencies and Playwright Chromium, installs the create-ai-promo-video Skill, and registers the ai-promo-video MCP server in all four clients. Existing unrelated Skills and MCP servers are preserved.

Claude has two local surfaces with different extension mechanisms:

• Claude Code, including the Claude app's Code tab, receives the filesystem Skill from ~/.claude/skills and the user-scoped MCP server. Verify it with /create-ai-promo-video and claude mcp get ai-promo-video.
• Claude Desktop's Home chat does not read filesystem Skills. It receives the same director guide through the local MCP server as server instructions, the create-ai-promo-video prompt, the ai-promo://director-guide resource, and the load_director_guide tool for clients that expose tools only. Fully quit and reopen Claude Desktop after installation.

Regular claude.ai web conversations still use separately uploaded cloud Skills and do not read local files or local MCP configuration.

Restart the agent client after installation, then ask it to create a professional promo video.

Install for selected clients only or preview every planned change:

npx --yes github:MendesCorporation/ai-promo-video install --clients codex,cursor
npx --yes github:MendesCorporation/ai-promo-video install --clients claude
npx --yes github:MendesCorporation/ai-promo-video install --clients claude-code
npx --yes github:MendesCorporation/ai-promo-video install --clients claude-desktop
npx --yes github:MendesCorporation/ai-promo-video install --dry-run

The claude alias configures both Claude Code and Claude Desktop.

Windows and WSL

From native Windows PowerShell, use npx.cmd to avoid PowerShell execution-policy conflicts with npx.ps1:

npx.cmd --yes github:MendesCorporation/ai-promo-video install

Run the installer in the same environment as the agent client. Native Windows clients use %USERPROFILE% and %LOCALAPPDATA%; an installer launched inside WSL uses the Linux home directory and configures clients running inside WSL. A WSL installation does not configure native Windows Codex, Claude, or Cursor, and a native installation does not configure their WSL instances.

Install from the repository

git clone https://github.com/MendesCorporation/ai-promo-video.git
cd ai-promo-video
npm run setup
node plugins/ai-promo-video/dist/install.js install

setup installs dependencies, applies the pinned and idempotent Revideo 0.11 shader-context compatibility patch, installs the Chromium build used by Playwright, and compiles the project. The second command installs a stable runtime and configures Codex, Claude Code, and Cursor.

This route is intended for contributors and anyone who wants to inspect or modify the engine before installing it. To run directly from the checkout without installing it globally, use the CLI commands documented below.

Install the Skill manually

The Skill is a regular folder and can be copied without running the universal installer. From a cloned repository, run only the line for your client:

# Codex — global user Skill
mkdir -p "$HOME/.agents/skills"
cp -R plugins/ai-promo-video/skills/create-ai-promo-video "$HOME/.agents/skills/"

# Claude Code — global user Skill
mkdir -p "$HOME/.claude/skills"
cp -R plugins/ai-promo-video/skills/create-ai-promo-video "$HOME/.claude/skills/"

# Cursor — global user Skill
mkdir -p "$HOME/.cursor/skills"
cp -R plugins/ai-promo-video/skills/create-ai-promo-video "$HOME/.cursor/skills/"

For a repository-scoped installation, copy the same folder into .agents/skills/ for Codex, .claude/skills/ for Claude Code, or .cursor/skills/ for Cursor at the repository root.

On native Windows PowerShell, the following copies the Skill to all three user-level discovery locations:

$source = (Resolve-Path "plugins\ai-promo-video\skills\create-ai-promo-video").Path
$destinations = @(
  (Join-Path $HOME ".agents\skills\create-ai-promo-video"),
  (Join-Path $HOME ".claude\skills\create-ai-promo-video"),
  (Join-Path $HOME ".cursor\skills\create-ai-promo-video")
)
foreach ($destination in $destinations) {
  New-Item -ItemType Directory -Force (Split-Path $destination) | Out-Null
  Remove-Item $destination -Recurse -Force -ErrorAction SilentlyContinue
  Copy-Item $source $destination -Recurse -Force
}

These locations follow the current Codex Skills, Claude Code Skills, and Cursor Agent Skills documentation.

The Skill alone provides the directing workflow, production rules, and QA process. It does not provide the capture, search, render, editing, or visual-review tools. For complete video production, use the quick installer so the MCP server is installed as well.

After copying the Skill, restart the client if it does not appear automatically. Invoke it explicitly as $create-ai-promo-video in Codex, /create-ai-promo-video in Claude Code or the Claude app's Code tab, or through Cursor's slash-command menu. Claude Desktop Home requires the MCP installation because it does not scan this folder.

What the installer configures

• Runtime under ~/.local/share/ai-promo-video on macOS/Linux or %LOCALAPPDATA%\ai-promo-video on Windows.
• The create-ai-promo-video Skill under ~/.agents/skills, ~/.claude/skills, and ~/.cursor/skills.
• The ai-promo-video stdio MCP server in Codex, Claude Code, Claude Desktop, and Cursor.
• Production dependencies and Playwright Chromium.

On Windows, the user MCP files resolve under %USERPROFILE%\.codex\config.toml, %USERPROFILE%\.claude.json, and %USERPROFILE%\.cursor\mcp.json. Claude Desktop uses %APPDATA%\Claude\claude_desktop_config.json; Microsoft Store builds are detected under the matching %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude directory.

FFmpeg and FFprobe are supplied by npm dependencies and do not require a separate system installation.

The installation artifact contains only the runtime, Skill, required assets, and manifests. Demonstration videos and production media are not downloaded by the installer.

How to request a video

After restarting the client, the initial request can be simple:

Create a cinematic 30-second promo for the SaaS at http://localhost:3000.
The audience is QA leaders, and the core promise is reducing the time between
detecting and reproducing a defect. Use the product's visual identity, record
the real flow, find freely licensed music, and deliver at 1920x1080.

For more control, provide:

• Product URL and authentication instructions, without putting secrets in the prompt or Git.
• Audience, problem, promise, and CTA.
• Duration, aspect ratio, resolution, and FPS.
• References for pacing, camera movement, typography, and color.
• Authorized local directories containing music, footage, logos, and screenshots.
• Whether the AI may search online and which licenses are acceptable.

Revisions can also be requested in natural language:

Between 7 and 11 seconds, the camera feels static. Lock the zoom onto the left
menu, follow the items as they assemble, and then slide the focus toward the
list. Preserve the rest of the video and inspect the transition frames before
delivering the revision.

The AI can read the existing source, edit only the affected scene or interval, render a patch, and replace that range in the final MP4.

Capture, media, and motion capabilities

• Clean screenshots and recordings from local or remote applications.
• AI-controlled clicks, form filling, key presses, hover, selection, scrolling, navigation, and mouse movement.
• Recursive search across user-authorized local directories.
• Music search through local folders and Openverse, including download and attribution manifests, without a default or fallback track.
• Music comparison through loudness, energy-curve, peak, silence, waveform, and spectrogram analysis.
• Footage search through Wikimedia Commons and, optionally, Pexels.
• Image and asset search through Openverse, Wikimedia Commons, and, optionally, Pexels.
• Openverse and Wikimedia require no API key. Pexels is free but requires PEXELS_API_KEY.
• Images, SVG, vector paths, masks, gradients, filters, shaders, particles, Three.js, and video clips inside the same composition.
• Native landscape, portrait, and square composition profiles with adaptive stages, focal product crops, and editable safe-area defaults for TikTok, Instagram Reels, and YouTube Shorts. Vertical output is recomposed rather than produced by shrinking a landscape scene.
• A searchable motion vocabulary spanning backgrounds, formats, layouts, captions, typography, product presentation, shapes, transitions, camera, cursors, particles, and effects; every item can be restyled, combined, or replaced with custom TypeScript.
• Ten executable transition rigs and seven executable camera rigs live in transitions.ts and camera.ts, with typed controls for vectors, overlap, blur, depth, curves, targets, bounds, perspective, deterministic seeds, and timing. They are editable starting points—not templates or constraints—and the AI may ignore them, rewrite them, combine them, or author an entirely original Revideo, SVG, GLSL, or Three.js system.
• Kinetic typography by block, line, word, or character, including tracking, blur, rise, wipe, typewriter, erase/rewrite, swaps, and typography-driven masks.
• Reusable destination-texture optical glass for authored surfaces plus liquid-glass glyph lenses with refraction, dispersion, responsive highlights, and luminance-aware text contrast.
• Speech-following captions from SRT, WebVTT, cue JSON, or exact word-timing JSON, with word-follow, karaoke, punch, phrase-window, speaker, and adaptive caption-lane systems. Cue-only timestamps are labeled as approximate interpolation instead of being presented as exact alignment.
• Vector glyph outlines and SVG path morphing through OpenType.js and Flubber; seeded flow fields, attraction, dissolution, and shockwaves through Simplex Noise; optional selective bloom, depth of field, chromatic aberration, grain, and vignette through Three.js postprocessing.
• Non-destructive crop, resize, color treatment, blur/redaction, chroma removal, trim, speed, fades, volume, and mute.
• Frame-evaluated music envelopes for precise entrances, drops, pauses, ducks, and fades without rerendering the visuals.

Online results can only be selected when their license is known and allowed. Every download includes origin and attribution metadata.

MCP tools

The server exposes 37 tools:

• Progressive documentation: help. Call it without arguments for a compact index, with query for short candidates, or with an exact target such as component:liquid-glass-text, transition:camera-zoom-through, or tool:render_advanced_video for parameter types, runtime defaults, calibrated ranges where available, choreography, examples, pitfalls, source signatures, and validation rules.
• Product: inspect_saas, capture_saas, record_saas_flows.
• Music: list_music, generate_music_library, search_music, download_music, analyze_music, mix_music.
• Free media: search_free_videos, download_free_video, search_free_assets, download_free_asset.
• Formats and captions: list_format_profiles, prepare_caption_timing, review_caption_timing.
• Motion composition: list_motion_capabilities, search_motion_components, get_motion_component, scaffold_advanced_video, list_advanced_video_files, read_advanced_video_file, save_advanced_video_file, patch_advanced_video_file, render_advanced_video.
• Editing: edit_capture_image, edit_video, replace_video_range.
• Legacy JSON compatibility: validate_video_plan, render_video.
• Visual QA: probe_video, extract_review_frames, create_visual_review_pack, read_visual_files.
• Delivery: clean_delivery_output.

The contextual help tool keeps routine calls small: the full catalog is never injected automatically, and exact documentation is returned only for the requested target. The create-ai-promo-video MCP prompt, the ai-promo://director-guide and ai-promo://motion-library resources, and ten detailed reference resources make the complete workflow available even without native Skill discovery. Captures and review sheets are returned as MCP image content, allowing a vision-capable model to inspect the result. Advanced renders publish live phase and percentage updates through MCP progress and logging notifications. Each render runs in an isolated process group, so cancellation, startup failure, stalls, and timeouts clean up its Chromium and Vite processes automatically.

CLI usage

Everything available through MCP can also be invoked from the terminal:

# Inspect, capture, and record a product
node plugins/ai-promo-video/dist/cli.js inspect http://localhost:3000 --screenshot ./inspect.png
node plugins/ai-promo-video/dist/cli.js capture ./capture.local.json
node plugins/ai-promo-video/dist/cli.js record ./capture.local.json

# Search for free music and media
node plugins/ai-promo-video/dist/cli.js music:search "focused technology" --provider openverse
node plugins/ai-promo-video/dist/cli.js music:analyze ./music/candidate.mp3 --review-dir ./music-review
node plugins/ai-promo-video/dist/cli.js video:search --query "software team" --provider all --orientation landscape
node plugins/ai-promo-video/dist/cli.js asset:search --query "abstract technology" --provider all --kind image

# Create and render unrestricted motion
node plugins/ai-promo-video/dist/cli.js motion:capabilities
node plugins/ai-promo-video/dist/cli.js motion:search --query "camera follows interface assembly" --categories camera,product
node plugins/ai-promo-video/dist/cli.js format:list
node plugins/ai-promo-video/dist/cli.js advanced:init ./advanced --name "Launch promo" --format portrait --platform tiktok
node plugins/ai-promo-video/dist/cli.js advanced:render ./advanced/project.tsx --output ./output/promo.mp4

# Prepare captions that follow speech and review their timing
node plugins/ai-promo-video/dist/cli.js caption:prepare ./captions.srt --output ./advanced/caption-timing.json
node plugins/ai-promo-video/dist/cli.js caption:review ./advanced/caption-timing.json

# Render and replace only a revised interval
node plugins/ai-promo-video/dist/cli.js advanced:render ./advanced/project.tsx --output ./output/patch.mp4 --start 4.5 --end 10
node plugins/ai-promo-video/dist/cli.js video:replace-range ./replace.json

# Inspect and review the output visually
node plugins/ai-promo-video/dist/cli.js probe ./output/promo.mp4
node plugins/ai-promo-video/dist/cli.js review ./output/promo.mp4 --output-dir ./review --times 2,8,14,20,27,29

image:edit and video:edit accept JSON instructions. Credentials belong only in gitignored *.local.json files.

Project structure

plugins/ai-promo-video/
├── src/mcp/server.ts                 server and agent contract
├── src/install.ts                    universal installer
├── src/capture/                      product inspection and recording
├── src/advanced/                     motion catalog and editable Revideo projects
├── src/captions/                     caption import, word timing, and timing QA
├── src/media/                        editing and incremental revisions
├── src/library/                      local and online free-media search
├── assets/revideo-template/          neutral scaffold and reusable motion primitives
└── skills/create-ai-promo-video/     direction, workflow, and QA criteria

The JSON engine remains only for existing version 1 compatibility. New productions start directly as neutral Revideo compositions, whether they use mostly library primitives or extensive custom code.

Licensing and privacy

The project code is licensed under MIT. Revideo and Three.js are open source, Playwright controls the browser, and FFmpeg performs encoding and media editing. Dependencies retain their own licenses, including the packaged FFmpeg binary.

The project does not send the SaaS to its own model because it includes neither a model nor a hosted service. However, the user's selected agent may receive prompts, screenshots, or review frames according to that client's policies. Secrets, tokens, private URLs, and customer data must not be stored in scenes, manifests, or commits.

Development and validation

npm run build
npm test
npm run test:revideo-shader

The shader regression test renders source and destination-texture shaders with reactive parameters across two workers. npm run revideo:patch:check verifies the local Revideo compatibility patch without changing files. The install fails safely if Revideo's pinned version or expected runtime shape changes, instead of modifying an unknown build.

Rendering is deterministic for the same source, assets, versions, and platform. Revideo telemetry is disabled by the advanced renderer. The CLI prints live render progress to stderr while preserving the machine-readable result on stdout. Before delivery, the Skill requires duration and codec inspection, full-film sampling, transition review, and correction of visual anomalies.