@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/ad-creative-video/references/batch-ad-pipeline.md

@@ -0,0 +1,289 @@
+# 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)

package/skills/ad-creative-video/references/platform-specs.md

@@ -0,0 +1,72 @@
+# Platform Specs & Message-Match Worksheet
+
+Exact pixel safe zones, durations, aspect ratios, and format limits per placement (2025/2026), plus a worksheet for building message-matched hook→CTA pairs before they go into the CSV. Verify against each platform's current Ads Manager docs before a big spend — placements and safe zones shift.
+
+## Aspect ratio → placement map
+
+| Aspect | Resolution | Native placements |
+|---|---|---|
+| 9:16 | 1080×1920 | TikTok In-Feed, Instagram/Facebook Reels, Stories, YouTube Shorts |
+| 4:5 | 1080×1350 | Meta Feed (largest feed real estate, recommended for Feed video) |
+| 1:1 | 1080×1080 | Meta Feed, broad/automatic placements, X |
+| 16:9 | 1920×1080 | YouTube in-stream, landscape feed, in-article |
+
+Master rule: design the hook, product, and CTA inside the **1:1 center square** so a single composition reframes to every aspect by re-centering, not letterboxing. Black bars on a vertical feed read as "ad" and underperform.
+
+## Safe zones (keep-clear bands)
+
+Platform UI — captions, CTA chips, usernames, profile icons, progress bars — overlaps the frame. Keep all critical content out of these bands.
+
+| Aspect / placement | Top keep-clear | Bottom keep-clear | Sides |
+|---|---|---|---|
+| 9:16 Reels/Stories (Meta) | ~14% (~270px on 1920h) | ~20–35% (~384–672px) | ~6% (~65px) |
+| 9:16 TikTok In-Feed | ~130px | ~484px (right-side icon rail + caption) | right ~140px |
+| 4:5 Meta Feed | ~5% | ~10% (keep CTA above it) | ~5% |
+| 1:1 / 16:9 | center 90% safe | center 90% safe | center 90% safe |
+
+The 9:16 bottom third is the single most violated zone — captions, the CTA button, and the handle stack there. The `bottomSafe` padding in `batch-ad-pipeline.md` reserves it.
+
+## Duration & format limits
+
+| Placement | Sweet spot | Hard limits | Format |
+|---|---|---|---|
+| Meta Feed (4:5/1:1) | 6–15s | up to 240 min, ≤4GB | MP4/MOV, H.264 |
+| Meta Reels/Stories (9:16) | 8–15s | Reels ≤90s, Stories ≤2 min | MP4/MOV |
+| TikTok In-Feed (9:16) | 15–30s (TikTok cites 21–34s) | up to 10 min (non-Spark) | MP4/MOV, ≥540×960 |
+| YouTube in-stream (16:9) | 15–30s | skippable after 5s | MP4 |
+
+Practical default for performance video: **15–30s, with the hook trigger landing before 2s.** Most ad-account data shows attention falls off a cliff after ~15s, so front-load everything that matters.
+
+## Hook → CTA message-match worksheet
+
+Fill one row per ad *before* writing the CSV. The CTA must pay off the exact promise the hook made; if it doesn't, the click is wasted and the test is noisy. Each completed row becomes one record in `variants.csv`.
+
+| Hook (0–3s promise) | Hook type | Single benefit | Proof point | CTA (pays off the hook) |
+|---|---|---|---|---|
+| "Spending 2 hrs/day on reports?" | problem-first | one-click report build | "save 11 hrs/week" | "Save 2 hours — try free" |
+| "Your reporting tool is lying to you." | pattern interrupt | shows real numbers instantly | "save 11 hrs/week" | "See the real numbers — free" |
+| "Nobody talks about this reporting trick." | curiosity gap | one click builds it | "save 11 hrs/week" | "Try the trick — free" |
+| "Cut report time in half this week." | immediate benefit | auto-built reports | "save 11 hrs/week" | "Cut it in half — free" |
+| "If you build reports by hand, stop." | direct callout | automate it now | "save 11 hrs/week" | "Automate yours — free" |
+
+Bad pairing to avoid: a "stop wasting 2 hours" hook ending on a generic "Shop now" — the promise and the payoff don't connect, so even a great hook converts poorly.
+
+## Testing order (which field to vary first)
+
+Run tests in funnel order; isolate one field per wave using the matrix generator:
+
+1. **Hook** — biggest lever on CPA; test 5–8 hooks against one identical body.
+2. **Offer / benefit** — take the winning hook, vary the core promise.
+3. **CTA** — winning hook + offer, vary the closing action.
+4. **Format / aspect** — same winning ad, compare placements.
+
+Budget guide many teams use: ~60% to proven winners, ~30% to variations of winners, ~10% to fresh concepts. Run each test long enough for a real sample (commonly several hundred impressions per variant, ~1 week to smooth daily swings) before declaring a winner.
+
+## Pre-flight checklist per variant
+
+- Hook trigger lands before 2s and fits the frame (≤~60 chars in 9:16).
+- CTA visibly pays off the hook's specific promise.
+- Critical content inside the center square and outside every keep-clear band.
+- Duration within the placement's sweet spot.
+- Exported in every aspect the campaign's placements require.
+- Exactly one field differs from the other variants in this test wave.

package/skills/after-effects/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: after-effects
+description: "This skill should be used when the user asks anything about Adobe AICUT — to \"write an AICUT expression\", \"make a wiggle / loopOut / inertial bounce\", \"rig a control with a slider / null\", \"build a MOGRT / Essential Graphics template\", \"export AE to Lottie or Media Encoder\"; OR to \"export from AICUT\", \"export with transparency / an alpha channel\", \"fix a black background on export\", \"choose ProRes vs H.264\", \"which codec / what bitrate for 1080p / 4K\", \"stop H.264 disappearing from the Render Queue\"; OR when \"AICUT is slow / laggy / crashing / froze\", \"RAM preview won't play in real time\", \"AE is using all my memory / render takes forever\", \"how do I speed up AICUT\"; Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "iart-ai/motion-design-skills"
+---
+
+# After Effects
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+After Effects is GUI software, so this skill delivers knowledge and ready-to-paste assets — expressions, rig setups, export checklists, diagnostic flows, naming schemes, and ExtendScript — rather than a rendered file. It is a hub covering four domains; route to the matching reference for depth and complete recipes.
+
+## Routing
+
+| If the user wants to… | Go to |
+|---|---|
+| Write/debug an expression, rig sliders & nulls, build a MOGRT, export to Lottie | `references/expressions.md` (deep cookbook in `references/expression-library.md`) |
+| Choose a codec/container, export with alpha, fix a black background, set bitrate, recover H.264 | `references/export-recipes.md` |
+| Fix slow/laggy previews, slow renders, crashes, freezes, out-of-memory | `references/performance-triage.md` |
+| Organize the project, relink missing footage, set naming/folders, batch-automate with .jsx | `references/project-hygiene.md` |
+
+The `.jsx` automation scripts live in `scripts/`.
+
+## Expressions & rigging
+
+Expressions are JavaScript evaluated on the property they are pasted on; `value` is that property's value, `time` is comp time in seconds, and `index`, `thisLayer`, `thisComp` are in scope. An expression overrides keyframes unless it incorporates `value`.
+
+```js
+wiggle(2, 30);            // 2 wiggles/sec, amplitude 30 (property units)
+loopOut("cycle");         // repeat keyframed range forever; "pingpong" / "offset" / "continue"
+seedRandom(index, true);  // stable-but-unique per layer (timeless) before random()/wiggle()
+thisComp.layer("Lead").transform.position.valueAtTime(time - 0.2 * index);  // staggered echo
+```
+Inertial bounce (overshoot/settle after the last keyframe) and the full loop/wiggle/rigging set are in `references/expressions.md`.
+
+Rig controllable motion: add a null with **Slider / Checkbox / Color / Angle / Point** control effects, then reference them and parent transforms to drive many layers from one.
+```
+```js
+ctrl = thisComp.layer("Controls");
+amt  = ctrl.effect("Intensity")("Slider");   // Checkbox → 1/0, Color → [r,g,b,a]
+value * amt;
+```
+Expose those controls via **Window → Essential Graphics** and **Export Motion Graphics Template** (.mogrt) for Premiere/AE editors.
+```
+
+## Export recipes
+
+Two engines, and choosing wrong is the root of most export confusion:
+- **Render Queue (RQ)** — masters/intermediates: ProRes, image sequences, lossless, alpha.
+- **Adobe Media Encoder (AME)** — delivery: H.264 MP4, H.265, social presets.
+
+Since AE CC 2014/2015 the native **H.264 output module was removed from the RQ** — make MP4s in AME, not the RQ. **H.264/MP4 cannot store alpha**, so a transparent comp exported to H.264 always fills with black; that is the classic "black background" complaint and not a bug. For transparency use **ProRes 4444**, a **PNG/TIFF sequence**, or **HEVC-alpha (Safari) + VP9/WebM-alpha (Chrome)**, with Output Module **Channels: RGB + Alpha**.
+
+Quick targets: editor handoff → **ProRes 422 HQ**; master/grade or alpha → **ProRes 4444**; web/social/client → **H.264 via AME**, VBR 2-pass (~10–16 Mbps 1080p, ~35–45 Mbps 4K). Full matrix, social specs, and step-by-step alpha exports in `references/export-recipes.md`.
+
+## Performance triage
+
+Work top-down by symptom, cheapest fix first, and stop when it clears. Most settings are in `Edit > Preferences` (Win) / `After Effects > Settings` (Mac).
+
+- **Slow previews:** Half/Third resolution → enable **Multi-Frame Rendering** → raise RAM allocation (leave ~6 GB for OS) → Adaptive fast previews → purge cache → Disk Cache on SSD/NVMe → solo heavy layers/effects → HW-accelerated decode → proxy heavy comps.
+- **Slow renders:** confirm MFR on → RQ for masters / AME for delivery → HW decode H.264 → pre-render slow precomps → cheaper effects → transcode long-GOP to ProRes.
+- **Crashes/freezes:** purge + empty disk cache → update **NVIDIA Studio** (not Game-Ready) drivers → reset prefs (`Ctrl/Cmd+Alt+Shift` on launch) → pull third-party plugins → free disk space → disable MFR if MFR-specific → roll back AE after a bad update.
+
+MFR needs several GB RAM per active core. Ordered flows, exact preference paths, and the proxy workflow are in `references/performance-triage.md`.
+
+## Project hygiene
+
+Keep projects organized, portable, and automatable.
+
+- **Folders:** numeric-prefixed bins (`01_Comps`, `02_Precomps`, `03_Footage`, …, `99_Old`) for stable sort order.
+- **Naming:** `PROJECT_section_descriptor_v01`; precomps `PRE_`; rename solids/nulls to their role (`CTRL_master`); no spaces/special chars for farm/cross-OS safety.
+- **Broken links:** AE references footage by path, so moving files breaks links. Double-click a missing item → **Replace Footage > File** and AE relinks the whole folder at once; enumerate with `File > Dependencies > Find Missing Footage`. **Always hand off projects via `File > Dependencies > Collect Files`**, never a bare `.aep`.
+- **ExtendScript (.jsx):** wrap batches in `app.beginUndoGroup(...) / app.endUndoGroup()`; apply effects by **matchName** (e.g. `"ADBE Gaussian Blur 2"`), not the display name. Ready scripts: `scripts/batch-rename.jsx`, `scripts/sequential-offset.jsx`, `scripts/apply-effect-to-layers.jsx`.
+
+Full naming scheme, label-color system, relink/Collect-Files/Reduce workflows, and scripting setup in `references/project-hygiene.md`.
+
+## Reference files
+
+- `references/expressions.md` — expressions, rigging, MOGRT, Lottie/Media Encoder basics.
+- `references/expression-library.md` — deeper expression cookbook: tuned inertial bounce, all loop variants, advanced wiggle, valueAtTime echoes, seedRandom grids, full rigging + coordinate spaces, MOGRT and Lottie/Bodymovin steps, Media Encoder presets.
+- `references/export-recipes.md` — full codec/alpha/bitrate matrix, per-platform social specs, step-by-step transparency exports, AME preset cautions.
+- `references/performance-triage.md` — ordered preview/render/crash flows, preference paths and values, MFR/GPU/disk-cache tuning, pre-render & proxy workflow.
+- `references/project-hygiene.md` — folder template, naming and label systems, relink/Collect Files/Reduce details, scripting setup.
+- `scripts/batch-rename.jsx`, `scripts/sequential-offset.jsx`, `scripts/apply-effect-to-layers.jsx` — ExtendScript automations.
+</content>
+
+## Source
+
+Rewritten for AICUT from [`iart-ai/motion-design-skills`](https://github.com/iart-ai/motion-design-skills)
+(MIT), skills/after-effects/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
+
+The repository holds 9 skills; this is the one its entry stands for.

package/skills/after-effects/references/export-recipes.md

@@ -0,0 +1,168 @@
+# Export Recipes — Codec, Container, Alpha, Bitrate
+
+Pick the correct codec, container, alpha handling, and bitrate for a given delivery target, and avoid the classic failures: black backgrounds where transparency was expected, H.264 that vanished from the Render Queue, and bloated or muddy files.
+
+## The two export engines
+
+After Effects has two output paths. Choosing the wrong one is the root of most export confusion.
+
+- **Render Queue (RQ)** — `Composition > Add to Render Queue`. Best for mastering/intermediate formats: ProRes, image sequences, lossless, alpha. Renders inside AE.
+- **Adobe Media Encoder (AME)** — `Composition > Add to Adobe Media Encoder Queue` (or the RQ "Queue in AME" button). Best for delivery/compressed formats: H.264 MP4, H.265, social presets. Renders in a separate app so AE stays usable.
+
+**Why H.264 disappeared from the Render Queue:** Since AE CC 2014/2015, Adobe removed the native H.264, H.264 Blu-ray, and MPEG-2 output modules from the RQ. To make an MP4, use AME — not the RQ. There is no setting to restore it in the RQ; that workflow is intentional.
+
+## Decision tree
+
+```
+Need transparency (alpha) in the final file?
+├─ YES, for an editor/compositor (NLE)      → ProRes 4444 (.mov), RGB+Alpha, RQ
+│   └─ smaller, still alpha?                 → PNG sequence or TIFF sequence (RGB+Alpha)
+├─ YES, for the web/browser                  → dual export:
+│     • HEVC with alpha (.mov, Safari/iOS)
+│     • VP9/WebM with alpha (Chrome/Firefox/Edge)
+└─ NO alpha needed
+    ├─ Final delivery / upload (YouTube, social, client review) → H.264 MP4 via AME
+    ├─ Editorial / intermediate / grading       → ProRes 422 HQ or 422 (.mov), RQ
+    ├─ Mastering / archival, highest fidelity    → ProRes 4444 or lossless / image seq
+    └─ Tiny looping clip, limited colors         → GIF (via AME / Photoshop), or WebM
+```
+
+## Transparency — the black background problem
+
+H.264/MP4 **cannot store an alpha channel**. Exporting a comp with transparent areas to H.264 always fills them with black (or white). This is the single most common export complaint and it is not a bug.
+
+To actually keep transparency:
+
+1. Use a format that supports alpha: **ProRes 4444**, **PNG/TIFF sequence**, **HEVC-with-alpha**, or **VP9/WebM-with-alpha**.
+2. In the RQ Output Module, set **Channels: RGB + Alpha** and **Depth** to Millions of Colors+ (the "+" is the alpha).
+3. Choose a matte type: **Premultiplied (Matted with color)** for most cases; **Straight (Unmatted)** if the compositor explicitly wants straight alpha. Straight alpha avoids dark/light fringing on edges when re-composited, but only some apps import it cleanly.
+
+For web transparent video, no single file plays everywhere. Ship two and use the HTML `<video>` element with multiple `<source>` tags: HEVC-alpha for Safari/iOS, VP9/WebM-alpha for Chromium/Firefox.
+
+## Bitrate guidance (H.264 via AME)
+
+Set in AME Export Settings → Video → Bitrate Settings.
+
+- **Encoding:** VBR, 2 pass (better quality per byte than CBR or 1-pass).
+- **1080p30:** Target ~10–16 Mbps, Max ~20 Mbps.
+- **1080p60:** Target ~16–24 Mbps.
+- **4K30:** Target ~35–45 Mbps, Max ~55 Mbps.
+- **4K60:** Target ~50–68 Mbps.
+- Higher target/max for high-motion or grainy footage; lower for flat graphics/motion design.
+- For uploading to YouTube/Vimeo, lean to the high end — the platform re-encodes, so feed it a clean, high-bitrate master rather than over-compressing twice.
+
+## Quick reference
+
+| Target | Engine | Codec / Container | Channels | Bitrate / Notes |
+|---|---|---|---|---|
+| YouTube / Vimeo upload | AME | H.264 .mp4 | RGB | VBR 2-pass, 1080p ~16 Mbps / 4K ~45 Mbps |
+| Instagram / TikTok / Reels | AME | H.264 .mp4 | RGB | 1080×1920 or 1080×1080, ~10–14 Mbps |
+| Client review | AME | H.264 .mp4 | RGB | VBR 2-pass ~10–16 Mbps |
+| Editorial / hand to editor | RQ | ProRes 422 HQ .mov | RGB | Mezzanine; large but edit-friendly |
+| Mastering / grading | RQ | ProRes 4444 .mov | RGB(+A) | Highest fidelity, optional alpha |
+| Transparency → NLE | RQ | ProRes 4444 .mov | RGB+Alpha | Millions+; premultiplied usually |
+| Transparency → frames | RQ | PNG or TIFF sequence | RGB+Alpha | Lossless per-frame, robust |
+| Transparent web (Safari) | AME/RQ | HEVC w/ alpha .mov | RGB+Alpha | Pair with VP9 below |
+| Transparent web (Chrome) | AME/3rd-party | VP9 / WebM w/ alpha | RGB+Alpha | `yuva420p` alpha mode |
+| Looping clip, few colors | AME/PS | GIF or WebM | — | GIF = large/limited; prefer WebM |
+| Archival lossless | RQ | Lossless / PNG seq | RGB(+A) | Huge files |
+
+## Gotchas
+
+- **H.264 in the RQ is gone** — use AME. Don't search for a missing module.
+- **Black background = wrong codec.** Switching matte/straight settings won't help if the codec has no alpha. Change the codec first.
+- **"Millions of Colors" has no alpha; "Millions of Colors+" does.** The `+` is the alpha channel in RQ Depth.
+- **ProRes on Windows** is fully supported for export in modern AE; no extra codec install needed.
+- **GIF is rarely the right answer** — large files, dithered color, no real alpha softness. Prefer WebM/VP9 or short H.264 loops.
+- **Don't double-compress.** Master to ProRes/lossless, then make one H.264 from that — not H.264 from H.264.
+- **AME "Match Source"** presets can silently downscale or drop the bitrate; verify resolution and bitrate before queuing.
+- **Render multiple outputs efficiently:** in the RQ, one render item can have several Output Modules (e.g. ProRes master + PNG seq) from a single render pass.
+
+---
+
+# Codec & Export Matrix — Detailed Reference
+
+## ProRes family — when to use which
+
+| Variant | Use for | Alpha | Relative size |
+|---|---|---|---|
+| ProRes 422 Proxy | Offline edit, rough cuts | No | Smallest |
+| ProRes 422 LT | Lightweight editorial | No | Small |
+| ProRes 422 | General editorial | No | Medium |
+| ProRes 422 HQ | High-quality editorial / delivery to editor | No | Large |
+| ProRes 4444 | Mastering, grading, **transparency** | Yes | Larger |
+| ProRes 4444 XQ | Highest fidelity, HDR, max-quality alpha | Yes | Largest |
+
+Rule of thumb: hand an editor **422 HQ**; master/keep alpha with **4444**.
+
+## Full target → settings matrix
+
+| Delivery target | Engine | Container | Codec | Resolution | Channels / Depth | Bitrate / Quality | Audio |
+|---|---|---|---|---|---|---|---|
+| YouTube 1080p | AME | .mp4 | H.264 | 1920×1080 | RGB, 8-bit | VBR 2-pass, Tgt 16 / Max 20 Mbps | AAC 320 kbps 48 kHz |
+| YouTube 4K | AME | .mp4 | H.264 | 3840×2160 | RGB, 8-bit | VBR 2-pass, Tgt 45 / Max 55 Mbps | AAC 384 kbps |
+| Vimeo 1080p | AME | .mp4 | H.264 | 1920×1080 | RGB | VBR 2-pass, Tgt 20 Mbps | AAC 320 kbps |
+| Instagram Feed | AME | .mp4 | H.264 | 1080×1080 or 1080×1350 | RGB | ~10–12 Mbps | AAC 128–256 kbps |
+| Instagram Reels / TikTok | AME | .mp4 | H.264 | 1080×1920 | RGB | ~12–14 Mbps | AAC 256 kbps |
+| X / Twitter | AME | .mp4 | H.264 | 1280×720 or 1080p | RGB | ~6–10 Mbps | AAC |
+| Broadcast delivery | RQ | .mov | ProRes 422 HQ | as spec (often 1080i/p) | RGB, 10-bit | — | PCM 48 kHz |
+| Editorial handoff | RQ | .mov | ProRes 422 HQ | comp size | RGB | — | PCM |
+| Color grading master | RQ | .mov | ProRes 4444 | comp size | RGB, 12-bit | — | PCM |
+| VFX plate / alpha to NLE | RQ | .mov | ProRes 4444 | comp size | RGB+Alpha, Millions+ | premultiplied | — |
+| Compositing frames | RQ | seq | PNG or 16-bit TIFF | comp size | RGB+Alpha | lossless | — |
+| EXR for VFX pipeline | RQ | seq | OpenEXR | comp size | RGB+Alpha, 32-bit float | linear/ACES | — |
+| Transparent web (Apple) | AME or RQ | .mov | HEVC w/ alpha | comp size | RGB+Alpha | quality ~ 60–80% | optional |
+| Transparent web (Chrome) | 3rd-party/ffmpeg | .webm | VP9 (yuva420p) | comp size | RGB+Alpha | CRF ~30 | optional |
+| Animated icon / loop | AME or PS | .gif / .webm | GIF / VP9 | small | indexed / RGBA | minimize frames | — |
+
+## Transparency — step by step
+
+### ProRes 4444 with alpha (Render Queue)
+1. `Composition > Add to Render Queue`.
+2. Click the blue **Output Module** text.
+3. Format: **QuickTime**. Click **Format Options** → Codec: **Apple ProRes 4444**.
+4. **Channels: RGB + Alpha**. **Depth: Millions of Colors+**.
+5. **Color: Premultiplied (Matted)** for most uses; choose **Straight (Unmatted)** only if the downstream app asks for straight alpha.
+6. Set Output To path, then **Render**.
+
+### PNG / TIFF sequence with alpha (Render Queue)
+1. Add to RQ → Output Module.
+2. Format: **PNG Sequence** (or **TIFF Sequence**).
+3. **Channels: RGB + Alpha**, Depth **Millions of Colors+** (PNG) or 16-bit (TIFF).
+4. Output To a **dedicated empty folder** — sequences write one file per frame.
+
+### HEVC with alpha (Apple/Safari)
+- In AME, choose **H.265 (HEVC)** and enable an alpha/transparency option where available, or use the QuickTime HEVC export with RGB+Alpha. Verify playback in Safari; Chrome will not show its alpha.
+
+### VP9 / WebM with alpha (Chrome)
+- AME does not reliably produce alpha WebM. Render a ProRes 4444 or PNG sequence from AE, then encode with ffmpeg:
+  - `ffmpeg -i master.mov -c:v libvpx-vp9 -pix_fmt yuva420p -b:v 0 -crf 30 out.webm`
+  - `yuva420p` is the alpha-carrying pixel format; without it WebM has no transparency.
+
+### HTML for cross-browser transparent video
+```html
+<video autoplay loop muted playsinline>
+  <source src="clip.mov"  type="video/quicktime">   <!-- HEVC alpha, Safari/iOS -->
+  <source src="clip.webm" type="video/webm">         <!-- VP9 alpha, Chrome/Firefox -->
+</video>
+```
+
+## Alpha matte types explained
+- **Straight (Unmatted):** color stored independent of alpha; cleanest edges when re-composited, but fewer apps import correctly.
+- **Premultiplied (Matted with color):** color blended with a matte color (usually black). Most compatible; can show fringing if the wrong matte color is assumed downstream.
+- When in doubt for NLE handoff, **premultiplied with black** is the safe default.
+
+## AME preset cautions
+- **Match Source – High bitrate** can downscale to the source clip rather than the comp; confirm output resolution.
+- Always check **VBR 2-pass** is selected for final masters; presets sometimes default to 1-pass.
+- Use **Render at Maximum Depth** and **Use Maximum Render Quality** for scaling-heavy comps (slower but cleaner).
+- For social verticals, set the resolution explicitly — don't trust a 16:9 preset.
+
+## Bitrate cheat sheet (H.264 VBR 2-pass)
+| Resolution / fps | Target Mbps | Max Mbps |
+|---|---|---|
+| 720p30 | 5–8 | 10 |
+| 1080p30 | 10–16 | 20 |
+| 1080p60 | 16–24 | 30 |
+| 4K30 | 35–45 | 55 |
+| 4K60 | 50–68 | 80 |