spotlight

Point your AI agent at a website, some footage or a topic, and get back a finished short video.

spotlight made this video about itself, using only what's in this repo. Watch it with sound. spotlight is a skill for AI coding agents. You give it whatever you have: a URL, a folder of phone videos and photos, a code project, a spreadsheet, or a sentence about what you want. The agent works out the story, picks the shots and writes the on-screen text in your language (Persian, Arabic and other right-to-left scripts included). Then it cuts to the music, renders, measures the result, and has a second agent critique it before you see it.

There are three modes:

Examples

A launch video for something you shipped

Run it inside the project, or give it the live site:

/spotlight .
/spotlight https://your-app.com --tone yc-parody

It reads the code or captures the site, finds the two or three moments where the product does its job, and builds the video from your real UI, copy and colours. Besides yc-parody there are tones like polished, cinematic, deadpan and chaotic.

A promo from a folder of event clips

/spotlight ~/Videos/opening-night "Grand opening Friday at 7. First coffee is on us."

It sorts the clips, drops the shaky and dark ones, opens on the strongest moving shot, puts your words on screen and ends on the offer. With --lang fa (or ar, de, ja and so on) the text comes out in that language, and Persian or Arabic letters stay joined and run right to left.

A 20-second promo for Mahoor Coffee, cut from twelve of the café's own phone clips and its logo, with no offer by the owner's choice. Watch it with sound, or see the Persian cut. It went through three critic rounds, which caught the espresso machine maker's slogan, another café's branded cup and captions hidden under Instagram's buttons (plan, reports). The footage and logo belong to the café and are used with permission.

An explainer with real numbers

/spotlight "why we moved support to async" tickets.csv --mode explain

This gives you a 90-second landscape video: a hook question, three to five sections that each make one claim and show the evidence, then a takeaway. Every number on screen comes from your CSV, and sources.md says where each line of text came from.

A 60-second narrated explainer about spotlight's own quality check, built from real check results and a real critic report. An agent that knew spotlight only from its SKILL.md started it, then it went through two more critic rounds. Watch it with sound. Its sources trace every line on screen, and its plan has the command and the three critic rounds (reports).

Your footage, the brand's own words

/spotlight https://bakery.example ~/Pictures/bakery

It captures the site's copy, colours, fonts and logo, then cuts your photos and clips around them.

The same video in another format

Ask for it ("make it square for Instagram") or pass --format landscape. It reuses the work folder, so it re-renders instead of starting over.

What you get

A spotlight-output/ folder, timestamped if one already exists:

• video.mp4: H.264 at 30 fps and -14 LUFS, vertical 1080x1920 unless you ask for landscape or square, with the poster embedded as cover art
• music-only.mp4: the same video over the music alone, when the mix has sound effects or narration
• poster.jpg: the strongest settled frame
• caption.txt: a caption ready to post, in the video's language
• plan.md: the angle, the shot list and the music cues
• sources.md: every line of on-screen text and every number, next to where it came from
• work/: everything needed for a re-cut

How it works

The agent handles the creative side. It writes a brief and a shot plan, then builds the video as a web page where every frame is a function of time, and Chromium captures it frame by frame. A few scripts take care of the fiddly parts:

• footage.py turns any photo or clip into upright, sRGB, frame-exact material. It copes with HEIC, HDR, rotated phone video and odd frame rates, encodes the final video, and checks it for frozen stretches, loudness, true peak and frame count. The check also writes a contact sheet with timestamps.
• site.mjs captures a website's copy, colours, fonts, logo, screens and a full-page image. It has a hard time limit, so endless feeds and stalled servers can't hang the run.
• capture.mjs renders frames in parallel, and the result matches a single-threaded render pixel for pixel.
• The render kit draws charts (bar, line, donut, a counting number) straight from your data, diagrams whose lines draw in, and 3D scenes: a dotted globe or map with routes between real places, and an extruded logo. Every number on a chart is the exact string from your file.
• mix.py mixes the music, sound effects, live sound from your clips and narration. It levels the music, ducks it under the voice and sets each effect's gain so it's heard over the music in its own frequency band. A bundled CC0 library (five moods of music and 18 effects) is used when you don't bring a track.
• voice.py reads narration aloud with Piper, locally, using only voices whose licences allow commercial use.

After the render, a fresh agent that didn't build the video looks through its frames and measurements and writes down what's wrong. The builder fixes those things, and another fresh agent confirms the fixes. This goes on for up to three rounds.

Install

For Claude Code:

claude plugin marketplace add AmirSbss/spotlight
claude plugin install spotlight@spotlight

For any agent that reads SKILL.md, the skills CLI works:

npx skills add https://github.com/AmirSbss/spotlight --skill spotlight

You can also copy skills/spotlight/ into your agent's skills folder; docs/other-agents.md explains how. It has been tested end to end on Claude Code, Codex CLI and Hermes Agent.

Then check that the machine has what it needs:

bash skills/spotlight/scripts/doctor.sh

You need ffmpeg 4.4 or newer with the zscale filter, ImageMagick 6 or 7, Python 3.8+, Node 18+, Chromium or Chrome, and uv (it runs the sound mix). Piper is optional, for narration (uv tool install --python 3.12 "piper-tts>=1.3"), and so is gpt-image-bridge, for the odd AI illustration.

Ground rules

• Every piece of text, price, number and claim in the video comes from something you gave it. AI images appear only as clearly illustrative backgrounds, and the caption says so.
• Your footage, renders and plans stay on your machine. The one exception is the prompt for an optional AI image, and --no-ai turns that off too.
• A video ships only after it passes its own checks: nothing sits still for more than 0.6 s except the end card, the first frame is a finished picture, the call to action stays readable for at least 1.5 s, and the audio sits at -14 LUFS.

Status

Phases 1 to 3 of 4 are done: the three modes, website capture, the check and the critic loop; sound (a bundled CC0 music and sound-effects library, levelled effects and optional local narration); and visuals (charts, diagrams, a routes globe and an extruded logo). Phase 4 adds a finished example per mode, made with spotlight itself; the explainer is in examples/explain and the promo in examples/promo. The design and the plans live in docs/superpowers.

Tests

python3 tests/test_footage.py && python3 tests/test_check.py && python3 tests/test_docs.py && python3 tests/test_assets.py
uv run --project skills/spotlight/scripts python tests/test_mix.py
bash tests/test_capture.sh && bash tests/test_kit.sh && bash tests/test_site.sh && bash tests/test_three.sh
bash tests/test_doctor.sh && bash tests/test_bridge_image.sh && bash tests/test_voice.sh

Credits

spotlight is built on brag (MIT). The critic loop and quality bar are adapted from motion-video-kit (MIT), and the demo's music is CC0. NOTICE.md lists all of it. spotlight is MIT-licensed.