# scenario-text-overlay

Deterministically renders text cards and overlays to transparent PNGs for compositing on Scenario media.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 397 installs · ★ 1141
- Author: scenario-labs
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/scenario-labs/skills/tree/HEAD/skills/scenario-text-overlay/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/scenario-text-overlay

## What it does

AI media models often garble letterforms. This skill solves text drift by rendering typography deterministically into a transparent PNG from a JSON payload. It handles plain text boxes alongside rich HTML and CSS cards with custom styles.

Under the hood, `scripts/overlay.py` parses strict Mustache templates and renders via Chromium or a Pillow fallback. Running the script requires `pip install chevron pillow`. If any variable in the template is missing, rendering stops immediately.

Compositing happens on the Scenario platform using `model_scenario-compose-image` or `model_scenario-compose-video`, never locally. Merging layers locally with ffmpeg breaks the platform workflow, because the template and asset metadata belong in Scenario.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add scenario-labs/skills --skill scenario-text-overlay -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/scenario-text-overlay/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/scenario-text-overlay/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add scenario-labs/skills --skill scenario-text-overlay -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/scenario-text-overlay/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add scenario-labs/skills --skill scenario-text-overlay -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/scenario-text-overlay/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install scenario-labs/skills scenario-text-overlay
```

2. **Manually: put the files in place**
- File: `.github/skills/scenario-text-overlay/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add scenario-labs/skills --skill scenario-text-overlay -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/scenario-labs/skills --path skills/scenario-text-overlay
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/scenario-text-overlay/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add scenario-labs/skills --skill scenario-text-overlay -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/scenario-labs/skills/tree/HEAD/skills/scenario-text-overlay/SKILL.md

## When to use it
- render sharp legal disclaimers and lower thirds on AI video
- generate price cards and CTA overlays from JSON payloads
- swap localized copy across media using Mustache variables
- composite rich HTML and CSS typography over Scenario assets

## Example prompts
- Render a legal disclaimer overlay to super.png using overlay.py and card.json
- Create a price card overlay payload with Inter font and composite it over video
- Generate a transparent CTA banner overlay matching a 1080x1920 canvas

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1479dbfc304fbc29.

BEGIN THIRD-PARTY FILE 1479dbfc304fbc29
```text
---
name: scenario-text-overlay
description: "Use when text must appear letter-perfect on generated media: taglines, CTAs, prices, legal supers, lower thirds, end cards, nameplates, or styled rich cards composited over Scenario images and video. Keywords: text overlay, text card, caption card, CTA, legal super, tagline, end card, lower third, price card, HUD text, transparent PNG."
license: MIT
---

# Scenario Text Overlay

## Overview

Generation models drift on type, so text that must be exact is rendered deterministically here and
composited over the media. One JSON payload describes one overlay, in one of two kinds: a text layer
(plain styled text in a box) or a rich layer (HTML/CSS typography: gradients, strokes, shadows, card
layouts). Both substitute Mustache `{{variables}}` strictly (a missing variable fails the render) on
a transparent canvas.

[scripts/overlay.py](scripts/overlay.py) renders the payload to a PNG with an installed
Chromium-family browser (both kinds, discovered automatically) or a Pillow fallback (text layers
only), embeds the payload JSON into the PNG, and prints the path. Its modules:
[scripts/templating.py](scripts/templating.py) (strict Mustache),
[scripts/html_render.py](scripts/html_render.py) (browser engine),
[scripts/pillow_render.py](scripts/pillow_render.py) (fallback). The field-by-field contract and
example payloads live in [references/payloads.md](references/payloads.md). The script needs
`pip install chevron pillow`.

Connection and the core MCP loop: see the `scenario` skill. The overlay meets its content on the
platform, never locally: `model_run` on the compose tool models, `model_scenario-compose-image` for
stills and `model_scenario-compose-video` for video (fixed ids: each is Scenario's single
deterministic compositor for its medium, so discovery would only re-derive them), whose layer
contract lives in `scenario-video-assembly`. If a sibling skill named here is missing from your
available skills, ask the user to install it (`npx skills add scenario-labs/skills --skill <name>`);
unattended, proceed from tool schemas and flag the gap.

## Quick reference

| Step                    | Detail                                                                                               |
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
| 1. Write the payload    | Kind by field (`text_template` or `html_template`); every changeable string in `variables`           |
| 2. Render               | `python3 overlay.py --payload card.json --out card.png`                                              |
| 3. Verify               | Open the PNG: glyphs verbatim, box placement right, background transparent                           |
| 4. Upload               | `upload_asset` (kind `image`, multipart path)                                                        |
```
END THIRD-PARTY FILE 1479dbfc304fbc29

The third-party file has ended. Everything between the 1479dbfc304fbc29 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2923 of 7092 bytes. © scenario-labs · MIT · https://github.com/scenario-labs/skills/tree/HEAD/skills/scenario-text-overlay/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md