<div align="center">
<img src="examples/fanfare/logo.svg" alt="" width="72">
# Fanfare
**Turn your README into a launch page and a trailer.**
An agent skill for Claude Code, Codex and Cursor. Your agent reads the repo and writes the story;<br>
Fanfare renders an animated landing page, a short video and a social card. Zero npm dependencies.
[Live demo](https://gleaming0427.github.io/fanfare/) · [Gallery](https://gleaming0427.github.io/fanfare/gallery/) · [Install](#install) · [Examples](#examples) · [How it works](#how-it-works)
<a href="https://gleaming0427.github.io/fanfare/trailer.mp4">
<img src="docs/trailer.gif" alt="Fanfare's ten-second teaser, made with Fanfare: it turns a README into an animated launch page, a video trailer and a social card. Click to watch the full trailer with sound." width="720">
</a>
**[▶ Watch the trailer with sound](https://gleaming0427.github.io/fanfare/trailer.mp4)** (40 s) · [Download the MP4 from the latest release](https://github.com/Gleaming0427/fanfare/releases/latest/download/trailer.mp4)
<a href="https://gleaming0427.github.io/fanfare/gallery/">
<img src="docs/readme/gallery.jpg" alt="Five trailers made with Fanfare: a launch trailer with a screenshot zoom, a feature announcement on a light theme, day 3 of a launch week in neon, a v1.0 milestone in 9:16, a trailer in French" width="720">
</a>
<sub>The trailer, the <a href="https://gleaming0427.github.io/fanfare/">live demo</a> and the <a href="https://gleaming0427.github.io/fanfare/gallery/">gallery</a> were made with Fanfare.</sub>
</div>
## What you get
<table>
<tr>
<td width="50%" valign="top">
<a href="https://gleaming0427.github.io/fanfare/"><img src="docs/readme/page.jpg" alt="The Fanfare launch page: logo, name, tagline, and the install command with a copy button"></a>
<br><b>A launch page</b><br>One self-contained HTML file with the trailer built in. Host it on GitHub Pages, Netlify, anywhere.
</td>
<td width="50%" valign="top">
<img src="docs/social-card.png" alt="The Fanfare social card: logo, name, tagline, install command and repository URL">
<br><b>A social card</b><br>1280×640, for GitHub's social preview and link previews on X, Slack or LinkedIn.
</td>
</tr>
<tr>
<td colspan="2">
<img src="docs/readme/formats.jpg" alt="The same trailer engine in three formats: a vertical 9:16 scene in French, a 16:9 feature scene and a square 1:1 code demo on a light theme">
<br><b>A trailer in three formats, with sound</b><br>MP4 in 16:9 for X and YouTube, 9:16 for Reels, Shorts and TikTok, 1:1 for LinkedIn, with music and sound effects synthesized for your trailer, plus a looping GIF for your README.
</td>
</tr>
</table>
## Install
```bash
npx skills add Gleaming0427/fanfare
```
This works with Claude Code, Codex, Cursor and any agent that reads `SKILL.md` skills. Without npm:
```bash
curl -fsSL https://raw.githubusercontent.com/Gleaming0427/fanfare/main/install.sh | bash
```
## Use
In your project, ask your agent:
> Use Fanfare to make a launch page and a trailer for this repo.
You get a `fanfare/` folder:
| File | What it is |
| --- | --- |
| `index.html` | An animated launch page in one self-contained file. Host it on GitHub Pages, Netlify, anywhere. |
| `trailer.mp4` | A 20–40 second trailer with a soundtrack, 1920×1080, 1080×1920 or 1080×1080. Post it on X, LinkedIn or Product Hunt. |
| `trailer.gif` | The trailer as a GIF, or a short seamless loop with `--gif-teaser`. |
| `social-card.png` | 1280×640, for GitHub's social preview and link previews. |
Fanfare uses your project's own logo file. It never stands in an emoji or an icon: without a logo, the name stands alone.
## How it works
1. **Your agent writes the story.** It reads your README, manifest and docs, then writes `fanfare.json`: tagline, problem, features, a real terminal session, the install command. Facts only: the skill tells it not to invent numbers, users or testimonials.
2. **`render.mjs` builds the page.** One HTML file with a seekable, frame-accurate trailer engine inside. Plain Node.js, nothing to install.
3. **`export.mjs` films it.** It drives your local Chrome over the DevTools protocol, captures the trailer frame by frame and encodes it with ffmpeg. Still no npm dependency.
4. **The soundtrack is written for the trailer.** Music and sound effects are synthesized in code, so there is nothing to license: scene changes land on the beat, keys click while the demo types, the drop hits on the reveal. The MP4 is normalized to −14 LUFS, a common loudness target for online video.
5. **The motion is physical.** Every animation follows a spring, and scenes don't fade: the camera moves from one to the next, the terminal shrinks into the install command, and the install command becomes the call to action. Export at 60 fps with motion blur for the smoothest video.
6. **It shows the product as it is.** From a real screenshot, the camera can pan, move in on an area, ring it with a short note and click it with a cursor: all drawn over the image, never into it. In the terminal, it moves in on the line that shows the result. Fanfare does not rebuild an interface in HTML, which would show a screen that does not exist.
7. **Every video is checked before it is recorded.** The hook must be on screen within 3 seconds, a shot holds 14 words at most and stays long enough to read them, every text must reach the WCAG contrast against what is behind it, the picture never stands still for more than a second, and a GIF must loop without a jump. A trailer that fails is not exported, and the report says what to fix.
Before handing over, the agent screenshots every scene and looks at them, so cramped text gets fixed instead of shipped.
<img src="docs/readme/scenes.jpg" alt="Six scenes of the Fanfare trailer: the problem with underlined words, the name and tagline, a feature, the terminal zoomed on its key line, the install command and the call to action">
## Examples
Each example is one `fanfare.json`; [the gallery](https://gleaming0427.github.io/fanfare/gallery/) plays them with sound.
| Project | Video | Theme and format |
| --- | --- | --- |
| [Fanfare](https://gleaming0427.github.io/fanfare/) | Launch trailer, with a zoom on a real screenshot, and the README teaser above | `mono` with a sage accent, 16:9 |
| [Prospection](https://gleaming0427.github.io/fanfare/examples/prospection/), a trend-scouting agent | Launch trailer, in French | `sunset`, 9:16 |
| [Burrow](https://gleaming0427.github.io/fanfare/examples/burrow/), a fictional job queue | Feature announcement, with a code demo | `paper` (light), 1:1 |
| [Kiln](https://gleaming0427.github.io/fanfare/examples/kiln/), a fictional build cache | Day 3 of a launch week | `neon`, 16:9 |
| [Mooring](https://gleaming0427.github.io/fanfare/examples/mooring/), fictional feature flags | A v1.0 milestone | `ocean`, 9:16 |
Made one? [Share it](https://github.com/Gleaming0427/fanfare/issues/new?template=showcase.yml) for the gallery.
## Five kinds of video
One `fanfare.json` gives a launch trailer (20–40 s), a 10-second teaser loop for the README, a feature announcement, a milestone (a true number from your stats) or one day of a launch week. Set `trailer.type`, or export another kind beside it with `--type`. Each one opens on its hook, and its scenes change layout from one shot to the next.
## Themes and formats
Six presets: `aurora`, `sunset`, `ocean`, `neon`, `mono` and `paper` (light). Or set `theme.accent` to your brand color.
Four moods for the music, picked from the theme or set with `trailer.mood`: `glow` (lush pads), `drive` (bright and busy), `minimal` (sparse) and `warm` (electric piano). `trailer.sound` can keep the sound effects only, or turn the sound off.
Three formats: 16:9 for X and YouTube, 9:16 for Reels, Shorts and TikTok, 1:1 for LinkedIn and Instagram. `--all-formats` exports the three at once.
The interface words can be translated with `labels`, so the page and the trailer can be in any language.
## Without an agent
Write `fanfare.json` yourself ([reference](skills/fanfare/reference/spec.md), [starter](skills/fanfare/assets/template.json)), then:
```bash
node skills/fanfare/scripts/render.mjs fanfare.json # → index.html
node skills/fanfare/scripts/export.mjs index.html --stills # one image per scene, to check
node skills/fanfare/scripts/export.mjs index.html --gif-teaser # → social-card.png, trailer.mp4, looping trailer.gif
node skills/fanfare/scripts/export.mjs index.html --type feature --mp4 # → trailer-feature.mp4, a feature announcement
node skills/fanfare/scripts/export.mjs index.html --quality # the quality checks alone
node skills/fanfare/scripts/export.mjs index.html --mp4 --fps 60 --motion-blur 8 # smoother video, slower to record
```
The `--gif-teaser` option creates a separate ~10-second loop: project name and tagline, features, call to action, then the opening title again. It starts with readable content and leaves the full MP4 intact. Without this option, the GIF follows the full trailer and ends on an empty frame, so it loops too. `--gif-seconds` is available for excerpts but cannot be combined with `--gif-teaser`.
## Requirements
- Rendering: Node.js 18 or newer.
- Exporting: Node.js 22 or newer, Google Chrome, Chromium or Edge, and ffmpeg (`brew install ffmpeg`, `sudo apt install ffmpeg`, `winget install ffmpeg`).
To see what your machine can produce before you start (it launches Chrome once and exports nothing):
```bash
node skills/fanfare/scripts/export.mjs --check
```
## Publishing and sharing
Set `siteUrl` in `fanfare.json` to the final page URL (for example `https://you.github.io/project/`, including the trailing slash for a folder), then render again. This gives social previews an absolute image URL. Publish `social-card.png` alongside `index.html`; uploading just the HTML does not include the social preview image. Remote logo URLs also need network access; use a local logo file to embed it.
The agent writes the story from the README; the renderer takes JSON, not raw Markdown. Trailer length depends on that story, and the current videos use animated text, code and screenshots, without screen recordings. To narrate the trailer, record or generate a voice-over yourself and pass it with `--voiceover`: the music ducks under the voice.
## Roadmap
- Screen recordings as scenes
- A voice-over written from the README
- More scene types and themes
Ideas and pull requests are welcome. [Report a bug or share your result](https://github.com/Gleaming0427/fanfare/issues/new/choose).
## Show it off
Made a launch page with Fanfare? [Share your result](https://github.com/Gleaming0427/fanfare/issues/new?template=showcase.yml) to help improve the tool and propose it for [the gallery](https://gleaming0427.github.io/fanfare/gallery/). You can optionally add this badge:
```markdown
[](https://github.com/Gleaming0427/fanfare)
```
## Security
See [the security policy](SECURITY.md) for private vulnerability reports, installation guidance and the renderer/exporter trust boundaries.
## License
[MIT](LICENSE)