Claude
a7b0e631b9
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VU6qqzefQ2TxgZetJ7beKU
290 lines
12 KiB
Markdown
290 lines
12 KiB
Markdown
# Batch Ad Pipeline — full template, parser, matrix, render
|
||
|
||
This is the complete, runnable implementation behind the SKILL.md overview: a data-driven Remotion ad template, a CSV→props parser with validation, a one-variable test-matrix generator, a brand-lock theme, and the batch + multi-aspect render scripts. Hardcode nothing a marketer might want to A/B test.
|
||
|
||
## 1. The brand-lock theme
|
||
|
||
Keep every brand-controlled value in one object so 40 variants stay consistent and only the *tested* fields change per row. The variant data supplies copy and per-campaign accents; the theme supplies the locked look.
|
||
|
||
```ts
|
||
// theme.ts
|
||
export const theme = {
|
||
fontFamily: "Inter, system-ui, sans-serif",
|
||
ink: "#0B0B0F",
|
||
paper: "#FFFFFF",
|
||
radius: 20,
|
||
hookSize: 76, // px, on the 1080-wide master
|
||
bodySize: 44,
|
||
proofSize: 52,
|
||
ctaSize: 40,
|
||
pad: 80, // outer padding; also the side safe margin
|
||
durationInSeconds: 25,
|
||
} as const;
|
||
```
|
||
|
||
## 2. Aspect config
|
||
|
||
Drive layout from a single aspect prop so one composition reframes to every placement. Dimensions and the keep-clear bottom band differ per aspect.
|
||
|
||
```ts
|
||
// aspects.ts
|
||
export type Aspect = "9x16" | "4x5" | "1x1" | "16x9";
|
||
export const ASPECTS: Record<Aspect, {w: number; h: number; bottomSafe: number}> = {
|
||
"9x16": {w: 1080, h: 1920, bottomSafe: 540}, // captions + CTA + username stack here
|
||
"4x5": {w: 1080, h: 1350, bottomSafe: 135},
|
||
"1x1": {w: 1080, h: 1080, bottomSafe: 110},
|
||
"16x9": {w: 1920, h: 1080, bottomSafe: 110},
|
||
};
|
||
```
|
||
|
||
## 3. The data-driven template
|
||
|
||
Every animated value is a pure function of `useCurrentFrame()` — no CSS transitions, no GSAP/library timers (they desync deterministic rendering and flicker in the export). The component reads one `variant` plus an `aspect`; the renderer never edits this file.
|
||
|
||
```tsx
|
||
// AdTemplate.tsx
|
||
import {
|
||
AbsoluteFill, useCurrentFrame, useVideoConfig, interpolate, spring, Sequence,
|
||
} from "remotion";
|
||
import {theme} from "./theme";
|
||
import {ASPECTS, Aspect} from "./aspects";
|
||
|
||
export type Variant = {
|
||
id: string;
|
||
hook: string; // 0–3s scroll-stopper
|
||
benefit: string; // the single payoff claim
|
||
proof: string; // one concrete number / result
|
||
cta: string; // message-matched to the hook
|
||
accent: string; // per-campaign accent color
|
||
bg: string; // background color
|
||
};
|
||
|
||
export const AdTemplate: React.FC<{v: Variant; aspect: Aspect}> = ({v, aspect}) => {
|
||
const frame = useCurrentFrame();
|
||
const {fps} = useVideoConfig();
|
||
const {bottomSafe} = ASPECTS[aspect];
|
||
|
||
// Hook rises + fades in over the first 8 frames, holds, then eases up and out at 8s.
|
||
const hookY = interpolate(frame, [0, 8], [48, 0], {extrapolateRight: "clamp"});
|
||
const hookOpacity =
|
||
interpolate(frame, [0, 8], [0, 1], {extrapolateRight: "clamp"}) *
|
||
interpolate(frame, [fps * 7, fps * 8], [1, 0], {extrapolateLeft: "clamp", extrapolateRight: "clamp"});
|
||
|
||
// CTA springs in for impact in the last 3s and holds.
|
||
const ctaProgress = spring({frame: frame - fps * 22, fps, config: {damping: 14, stiffness: 120}});
|
||
|
||
return (
|
||
<AbsoluteFill style={{backgroundColor: v.bg, fontFamily: theme.fontFamily, color: theme.ink}}>
|
||
<AbsoluteFill style={{padding: theme.pad, paddingBottom: bottomSafe, justifyContent: "center"}}>
|
||
|
||
{/* HOOK 0–8s */}
|
||
<Sequence durationInFrames={fps * 8}>
|
||
<h1 style={{fontSize: theme.hookSize, fontWeight: 800, lineHeight: 1.05,
|
||
transform: `translateY(${hookY}px)`, opacity: hookOpacity}}>
|
||
{v.hook}
|
||
</h1>
|
||
</Sequence>
|
||
|
||
{/* BENEFIT 8–18s */}
|
||
<Sequence from={fps * 8} durationInFrames={fps * 10}>
|
||
<FadeUp delay={0}>
|
||
<p style={{fontSize: theme.bodySize, fontWeight: 600}}>{v.benefit}</p>
|
||
</FadeUp>
|
||
</Sequence>
|
||
|
||
{/* PROOF 18–22s */}
|
||
<Sequence from={fps * 18} durationInFrames={fps * 4}>
|
||
<FadeUp delay={0}>
|
||
<strong style={{fontSize: theme.proofSize, color: v.accent,
|
||
fontVariantNumeric: "tabular-nums"}}>{v.proof}</strong>
|
||
</FadeUp>
|
||
</Sequence>
|
||
|
||
{/* CTA last 3s, message-matched to the hook */}
|
||
<Sequence from={fps * 22}>
|
||
<button style={{
|
||
alignSelf: "flex-start", marginTop: 40, padding: "22px 44px",
|
||
fontSize: theme.ctaSize, fontWeight: 700, border: "none",
|
||
borderRadius: theme.radius, color: theme.paper, backgroundColor: v.accent,
|
||
transform: `scale(${interpolate(ctaProgress, [0, 1], [0.85, 1])})`,
|
||
opacity: ctaProgress,
|
||
}}>
|
||
{v.cta}
|
||
</button>
|
||
</Sequence>
|
||
</AbsoluteFill>
|
||
</AbsoluteFill>
|
||
);
|
||
};
|
||
|
||
const FadeUp: React.FC<{children: React.ReactNode; delay: number}> = ({children, delay}) => {
|
||
const frame = useCurrentFrame();
|
||
const o = interpolate(frame - delay, [0, 10], [0, 1], {extrapolateLeft: "clamp", extrapolateRight: "clamp"});
|
||
const y = interpolate(frame - delay, [0, 10], [24, 0], {extrapolateLeft: "clamp", extrapolateRight: "clamp"});
|
||
return <div style={{opacity: o, transform: `translateY(${y}px)`}}>{children}</div>;
|
||
};
|
||
```
|
||
|
||
## 4. Register the composition (aspect + variant as props)
|
||
|
||
```tsx
|
||
// Root.tsx
|
||
import {Composition} from "remotion";
|
||
import {AdTemplate} from "./AdTemplate";
|
||
import {ASPECTS} from "./aspects";
|
||
import {theme} from "./theme";
|
||
|
||
const defaultVariant = {
|
||
id: "demo", hook: "Spending 2 hrs/day on reports?", benefit: "Auto-build them in one click.",
|
||
proof: "Teams save 11 hrs a week.", cta: "Save 2 hours — try free", accent: "#4F46E5", bg: "#FFFFFF",
|
||
};
|
||
|
||
export const RemotionRoot = () => {
|
||
const aspect = "9x16" as const; // overridden per-render via --props
|
||
const {w, h} = ASPECTS[aspect];
|
||
return (
|
||
<Composition
|
||
id="AdTemplate"
|
||
component={AdTemplate}
|
||
durationInFrames={theme.durationInSeconds * 30}
|
||
fps={30}
|
||
width={w}
|
||
height={h}
|
||
defaultProps={{v: defaultVariant, aspect}}
|
||
// Resolve real dimensions from the incoming aspect prop at render time:
|
||
calculateMetadata={({props}) => {
|
||
const a = ASPECTS[(props as any).aspect ?? "9x16"];
|
||
return {width: a.w, height: a.h};
|
||
}}
|
||
/>
|
||
);
|
||
};
|
||
```
|
||
|
||
`calculateMetadata` lets a single composition output any aspect from the `aspect` prop — no separate composition per ratio.
|
||
|
||
## 5. CSV → typed props, with validation
|
||
|
||
The dataset is the input. Parse, validate every row (a bad hex or empty CTA must fail loudly, not render a broken ad), and write one props file per variant.
|
||
|
||
```js
|
||
// csv-to-props.js usage: node csv-to-props.js variants.csv ./props [aspect]
|
||
const fs = require("fs");
|
||
const path = require("path");
|
||
|
||
const [, , csvPath, outDir, aspect = "9x16"] = process.argv;
|
||
const REQUIRED = ["id", "hook", "benefit", "proof", "cta", "accent", "bg"];
|
||
const isHex = (s) => /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(s);
|
||
|
||
const parseCSV = (text) => {
|
||
const [head, ...lines] = text.trim().split(/\r?\n/);
|
||
const cols = head.split(",").map((c) => c.trim());
|
||
return lines.filter(Boolean).map((line) => {
|
||
// simple split; wrap fields containing commas in double quotes in the CSV
|
||
const cells = line.match(/("([^"]|"")*"|[^,]*)/g).filter((_, i, a) => i < a.length - 1);
|
||
const row = {};
|
||
cols.forEach((c, i) => (row[c] = (cells[i] ?? "").replace(/^"|"$/g, "").replace(/""/g, '"').trim()));
|
||
return row;
|
||
});
|
||
};
|
||
|
||
const rows = parseCSV(fs.readFileSync(csvPath, "utf8"));
|
||
fs.mkdirSync(outDir, {recursive: true});
|
||
|
||
const seen = new Set();
|
||
let errors = 0;
|
||
rows.forEach((row, n) => {
|
||
const where = `row ${n + 2} (${row.id || "no-id"})`;
|
||
REQUIRED.forEach((k) => { if (!row[k]) { console.error(`✗ ${where}: missing "${k}"`); errors++; } });
|
||
if (seen.has(row.id)) { console.error(`✗ ${where}: duplicate id`); errors++; }
|
||
seen.add(row.id);
|
||
if (row.hook && row.hook.length > 60) console.warn(`⚠ ${where}: hook >60 chars may clip in 9:16`);
|
||
["accent", "bg"].forEach((k) => { if (row[k] && !isHex(row[k])) { console.error(`✗ ${where}: "${k}" not a hex color`); errors++; } });
|
||
if (errors) return;
|
||
fs.writeFileSync(path.join(outDir, `${row.id}.json`), JSON.stringify({v: row, aspect}, null, 2));
|
||
});
|
||
|
||
if (errors) { console.error(`\n${errors} error(s) — no broken ads written.`); process.exit(1); }
|
||
console.log(`✓ ${rows.length} variant prop files written to ${outDir}`);
|
||
```
|
||
|
||
Example `variants.csv` (one fully message-matched ad per row):
|
||
|
||
```csv
|
||
id,hook,benefit,proof,cta,accent,bg
|
||
v01_problem,Spending 2 hrs/day on reports?,Auto-build them in one click.,Teams save 11 hrs a week.,Save 2 hours — try free,#4F46E5,#FFFFFF
|
||
v02_interrupt,Your reporting tool is lying to you.,See the real numbers instantly.,Teams save 11 hrs a week.,See the real numbers — free,#DC2626,#0B0B0F
|
||
v03_curiosity,Nobody talks about this reporting trick.,One click builds the whole report.,Teams save 11 hrs a week.,Try the trick — free,#059669,#FFFFFF
|
||
```
|
||
|
||
Note the CTA mirrors the hook in every row — that is the message-match discipline encoded into the data.
|
||
|
||
## 6. Test-matrix generator — one variable at a time
|
||
|
||
A test only teaches something if exactly one field changes. This expands a base variant plus a list of values for ONE field into a CSV, so a hook test or a CTA test stays clean and combinatorial mistakes are impossible.
|
||
|
||
```js
|
||
// make-matrix.js usage: node make-matrix.js > variants.csv
|
||
const base = {benefit: "Auto-build them in one click.", proof: "Teams save 11 hrs a week.",
|
||
cta: "Save 2 hours — try free", accent: "#4F46E5", bg: "#FFFFFF"};
|
||
|
||
// Vary ONLY this field; everything else is held identical across the test.
|
||
const FIELD = "hook";
|
||
const values = [
|
||
"Spending 2 hrs/day on reports?",
|
||
"Your reporting tool is lying to you.",
|
||
"Nobody talks about this reporting trick.",
|
||
"Cut report time in half this week.",
|
||
"If you build reports by hand, stop.",
|
||
];
|
||
|
||
const esc = (s) => (/[",]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
|
||
const cols = ["id", "hook", "benefit", "proof", "cta", "accent", "bg"];
|
||
console.log(cols.join(","));
|
||
values.forEach((val, i) => {
|
||
const row = {...base, [FIELD]: val, id: `${FIELD}_${String(i + 1).padStart(2, "0")}`};
|
||
console.log(cols.map((c) => esc(row[c])).join(","));
|
||
});
|
||
```
|
||
|
||
To run a CTA test next, set `FIELD = "cta"`, paste the *winning* hook into `base.hook`, and list CTA variants. Same one-variable rule, next stage of the funnel.
|
||
|
||
## 7. Batch + multi-aspect render
|
||
|
||
Render every variant in every aspect a campaign needs. Concurrency keeps large batches fast.
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
# render-all.sh one MP4 per (variant × aspect)
|
||
set -euo pipefail
|
||
|
||
node make-matrix.js > variants.csv # 1) build the one-variable test matrix
|
||
ASPECTS=("9x16" "4x5" "1x1") # placements this campaign needs
|
||
|
||
for ar in "${ASPECTS[@]}"; do
|
||
node csv-to-props.js variants.csv "props/$ar" "$ar" # 2) typed, validated props per aspect
|
||
for f in "props/$ar"/*.json; do
|
||
id=$(basename "$f" .json)
|
||
npx remotion render AdTemplate "out/${id}_${ar}.mp4" \
|
||
--props="$f" --concurrency=4 --log=error # 3) render
|
||
done
|
||
done
|
||
|
||
echo "Done. $(ls out/*.mp4 | wc -l) ad variants in ./out"
|
||
```
|
||
|
||
5 hooks × 3 aspects = 15 MP4s from one template and one command. Add a CTA stage and the same template produces the next test wave with zero new component code.
|
||
|
||
## Common pitfalls
|
||
|
||
- **Two variables changed at once** — the winner is uninterpretable. The matrix generator prevents this; keep using it.
|
||
- **Hook clips in 9:16** — long hooks overflow; the parser warns past 60 chars. Keep hooks short and high in the frame.
|
||
- **CTA hidden behind platform UI** — anything in the 9:16 bottom third gets covered by captions and the CTA button. The `bottomSafe` padding reserves that band.
|
||
- **Drift across variants** — accent/copy live in the data, everything else in `theme`. If a variant looks off-brand, the fix is the theme, not the row.
|
||
- **Animation flicker in export** — caused by CSS transitions or library timers. Every value must derive from `useCurrentFrame()`.
|
||
|
||
---
|
||
## Built by the team behind iart.ai
|
||
|
||
This skill is part of an open motion-graphics collection from iart.ai — the AI motion agent that turns data, scripts, and designs into editable motion graphics (Remotion → MP4). If you'd rather not hand-build this, iart.ai can mass-produce ad-creative variants from one template × a data table — change the text/data and re-export. → [iart.ai](https://iart.ai/?utm_source=github&utm_medium=reference&utm_campaign=ad-video-skills&utm_content=ref_footer&utm_term=ad-creative-video)
|