@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/remotion-ads/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: remotion-ads
+description: "Professional video ad creation with AICUT — Instagram Reels (9:16), website explainers (16:9), and carousels (4:5). Use when creating video ads, animated social content, or educational explainer videos. Includes ElevenLabs voiceover with word-level captions, AI icon generation, background music, ad copywriting frameworks, and Meta campaign management. Also use when the user provides a URL and wants to create a video for that page. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "Maartenlouis/remotion-ads"
+---
+
+# AICUT Ads
+
+## 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.
+
+
+Create professional video ads and explainer videos with Remotion, ElevenLabs voiceover, and animated captions.
+
+## Setup
+
+1. Copy `references/brand-config-template.md` → `references/brand-config.md`
+2. Fill in brand colors, fonts, voice, caption styling, and content rules
+3. Create pronunciation dictionary from `assets/dictionaries/template.pls`
+
+See [references/setup.md`setup.md` for dependencies and folder structure.
+
+---
+
+## Supported Formats
+
+| Format | Aspect | Resolution | Duration | Scenes |
+|--------|--------|-----------|----------|--------|
+| Instagram Reels | 9:16 | 1080×1920 | 15-60s | 4 (Hook→Problem→Solution→CTA) |
+| Instagram Reels (Ohneis) | 9:16 | 1080×1920 | 15-45s | Beat-driven (word-level) |
+| Website Explainers | 16:9 | 1920×1080 | 60-160s | 6 (Hook→Problem→Context→Solution→Process→CTA) |
+| Carousels | 4:5 | 1080×1350 | Static | 5-10 slides |
+
+See [references/formats.md](references/formats.md) for safe zones and crop specs.
+See [references/ohneis-style.md`ohneis-style.md` for beat-driven cinematic reel template.
+See [references/website-videos.md`website-videos.md` for 16:9 long-form format.
+
+---
+
+## Workflow
+
+### From scratch
+
+# 1. Write scene JSON
+
+# 2. Generate voiceover with word timestamps
+node scripts/generate.js \
+  --scenes scenes.json \
+  --with-timestamps \
+  --dictionary your-brand \
+  --output-dir public/audio/ad-example/
+
+# 3. Create Remotion composition using actualDuration from info.json
+
+# 4. Render
+npx remotion render AdExample out/ad-example.mp4 --codec=h264 --crf=18
+
+### From a URL (page → video)
+
+# 1. Extract page data into scene JSON
+node scripts/url-to-scenes.js --url https://example.com/page --format reels --output scenes.json
+
+# 2. Review/edit the generated scenes.json
+
+# 3. Continue with voiceover + composition as above
+```
+See [references/url-to-video.md`url-to-video.md` for the full URL-to-video workflow.
+
+---
+```
+
+## Safe Zones (Critical)
+
+### Reels (1080×1920)
+
+```
+┌──────────────────────────┐ 0px
+│     TOP DANGER (285px)   │
+├──────────────────────────┤
+│ ←80px  SAFE AREA  120px→ │
+│      880×1235px          │
+├──────────────────────────┤
+│   BOTTOM DANGER (400px)  │
+└──────────────────────────┘ 1920px
+```
+```tsx
+const SAFE = { top: 285, bottom: 400, left: 80, right: 120 };
+
+### Website Videos (1920×1080)
+
+```tsx
+const SAFE = { top: 60, bottom: 60, left: 80, right: 80 };
+```
+---
+```
+
+## Scene JSON Format
+
+```json
+{
+  "name": "ad-example",
+  "voice": "VoiceName",
+  "character": "narrator",
+  "dictionary": "your-brand",
+  "scenes": [
+    { "id": "scene1", "text": "Hook text.", "duration": 3.5, "character": "dramatic" },
+    { "id": "scene2", "text": "Problem.", "duration": 4.5 },
+    { "id": "scene3", "text": "Solution.", "duration": 4.0, "character": "expert" },
+    { "id": "scene4", "text": "CTA.", "duration": 3.0, "character": "calm" }
+  ]
+}
+
+### Voice Character Presets
+
+| Character | Style | Stability | Similarity | Style Param |
+|-----------|-------|-----------|------------|-------------|
+| `dramatic` | Intense, emotional | 0.3 | 0.8 | 0.7 |
+| `narrator` | Professional, smooth | 0.5 | 0.75 | 0.4 |
+| `expert` | Authoritative | 0.6 | 0.85 | 0.3 |
+| `calm` | Soothing, reassuring | 0.7 | 0.8 | 0.2 |
+| `conversational` | Casual, friendly | 0.45 | 0.7 | 0.5 |
+
+---
+
+## Composition Template
+
+```tsx
+import { AbsoluteFill, Audio, Series, staticFile } from "remotion";
+
+// Import from your brand-config.md values
+const COLORS = { primary: "#000", accent: "#888", dark: "#111", background: "#fff" };
+
+export const AdTemplate: React.FC = () => {
+  const { fps } = useVideoConfig();
+  // Use actualDuration from info.json, not estimated
+  const DURATIONS = { scene1: 3.42, scene2: 4.35, scene3: 4.12, scene4: 3.31 };
+  const pad = 5;
+
+  return (
+    <AbsoluteFill>
+      <Audio src={staticFile("audio/ad-example/ad-example-combined.mp3")} />
+      <Series>
+        <Series.Sequence durationInFrames={Math.round(DURATIONS.scene1 * fps) + pad}>
+          <Scene1Hook />
+        </Series.Sequence>
+        {/* ... remaining scenes */}
+      </Series>
+    </AbsoluteFill>
+  );
+};
+```
+See [references/components.md](references/components.md) for reusable scene components.
+See [references/voiceover.md`voiceover.md` for TransitionSeries audio sync.
+
+---
+```
+
+## Reference Files
+
+Load these on demand based on the task:
+
+### Core (read first)
+
+| File | When to read |
+|------|-------------|
+| [setup.md`setup.md` | Project initialization |
+| [brand-config-template.md](references/brand-config-template.md) | Configuring brand: colors, fonts, voice, captions, compliance |
+| [formats.md](references/formats.md) | Dimension specs, safe zones, crop previews |
+
+### Video Creation
+
+| File | When to read |
+|------|-------------|
+| [ohneis-style.md`ohneis-style.md` | Beat-driven cinematic reel template: mixed-font typography, hard cuts, moody photos |
+| [voiceover.md`voiceover.md` | ElevenLabs TTS, models, scene JSON, timing sync, dictionaries |
+| [captions.md](references/captions.md) | Animated captions: TikTok-style, word-by-word, karaoke |
+| [animations.md](references/animations.md) | Spring configs, transitions, animation components |
+| [components.md](references/components.md) | Reusable scene template components |
+| [html-in-canvas.md](references/html-in-canvas.md) | Render live DOM into a canvas with 2D filters or WebGL2 shaders (vintage, progressive blur, page-tour mockup) |
+| [website-videos.md`website-videos.md` | 16:9 long-form format, 6-scene structure |
+| [url-to-video.md`url-to-video.md` | Create videos from existing web pages |
+
+### Audio
+
+| File | When to read |
+|------|-------------|
+| [sound-effects.md`sound-effects.md` | ElevenLabs SFX generation |
+| [music.md](references/music.md) | Background music via ElevenLabs or Suno |
+
+### Assets & Static
+
+| File | When to read |
+|------|-------------|
+| [local-assets.md](references/local-assets.md) | Background images, icons, illustrations |
+| [carousels.md](references/carousels.md) | 4:5 carousel design and batch rendering |
+
+### Copywriting
+
+| File | When to read |
+|------|-------------|
+| [ad-copywriting.md](references/ad-copywriting.md) | Script frameworks, hook formulas, CTA patterns |
+| [copy-frameworks.md](references/copy-frameworks.md) | Headline templates, section formulas |
+| [natural-transitions.md`natural-transitions.md` | Human-sounding transitions, AI-tell avoidance |
+
+### Distribution
+
+| File | When to read |
+|------|-------------|
+| [paid-ads.md`paid-ads.md` | Meta campaign strategy, targeting, budgets |
+| [social-content.md`social-content.md` | Content calendar, repurposing framework |
+
+---
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/generate.js` | ElevenLabs voiceover with dictionaries, request stitching (note: `--with-timestamps` flag is currently a no-op) |
+| `scripts/gemini-tts.mjs` | Gemini TTS — single-request generate + silence split with text-proportion boundary picker |
+| `scripts/suno-direct.ts` | Suno background music generation |
+| `scripts/url-to-scenes.js` | Extract page content into scene JSON |
+
+---
+
+## Pre-Upload Checklist
+
+### Reels
+- [ ] 1080×1920, H.264, 30fps
+- [ ] All text within safe zones
+- [ ] No content in top 285px or bottom 400px
+- [ ] Font sizes ≥ 48px
+- [ ] Voiceover synced, captions timed
+- [ ] ~15s total duration
+
+### Website Videos
+- [ ] 1920×1080, H.264, 30fps
+- [ ] Font sizes ≥ 36px
+- [ ] 60-160s duration
+- [ ] 6-scene structure with appropriate voice characters
+
+### Carousels
+- [ ] 1080×1350, PNG
+- [ ] 80px padding from edges
+- [ ] 5-10 slides with swipe indicators
+
+## Source
+
+Rewritten for AICUT from [`Maartenlouis/remotion-ads`](https://github.com/Maartenlouis/remotion-ads)
+(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/remotion-ads/references/ad-copywriting.md

@@ -0,0 +1,229 @@
+---
+title: Ad Copywriting
+description: Frameworks and formulas for writing video ad scripts, carousel copy, and social captions
+section: copywriting
+priority: medium
+tags: [copywriting, scripts, hooks, cta, headlines, captions, marketing]
+---
+
+# Ad Copywriting for Video & Carousel Ads
+
+Frameworks for writing compelling ad scripts, carousel slide copy, and social media captions for Instagram Reels and static ads created with Remotion.
+
+> "If you have to choose between clear and creative, choose clear."
+
+---
+
+## Before Writing
+
+Gather this context (ask if not provided):
+
+1. **Product/Service**: What does it do? What problem does it solve?
+2. **Target Audience**: Who are they? What pain points do they have?
+3. **Differentiator**: What makes this different from competitors?
+4. **Desired Action**: What should viewers do after watching? (Visit link, DM, book a call)
+5. **Platform**: Instagram Reels, Stories, Feed, or carousel?
+
+---
+
+## Video Ad Script Structure (4 Scenes)
+
+### Scene 1: Hook (2-4 seconds)
+
+The first 1-2 seconds determine if someone watches or scrolls. Use these formulas:
+
+**Curiosity Hooks**
+- "I was wrong about [common belief]."
+- "The real reason [outcome] happens isn't what you think."
+- "[Impressive result] — and it only took [surprisingly short time]."
+
+**Problem Hooks**
+- "Never [unpleasant event] again."
+- "[Question highlighting the main pain point]?"
+- "Stop [pain]. Start [pleasure]."
+
+**Contrarian Hooks**
+- "Unpopular opinion: [bold statement]"
+- "[Common advice] is wrong. Here's why."
+- "I stopped [common practice] and [positive result]."
+
+**Audience Hooks**
+- "[Key feature] for [target audience]."
+- "You don't have to [skill/resource] to [achieve outcome]."
+
+### Scene 2: Problem (3-5 seconds)
+
+Articulate the viewer's problem better than they can. Create recognition.
+
+**Openers:**
+- "You know the feeling..."
+- "If you're like most [role]..."
+- "Every day, [audience] struggles with..."
+
+**Structure:**
+1. The specific frustration
+2. The time/money/stress wasted
+3. The impact on their life
+
+### Scene 3: Solution (3-5 seconds)
+
+Bridge from problem to your solution):
+
+**Structure:**
+1. Outcome headline (what they get)
+2. How it works (1-2 sentences)
+3. Proof point (number, testimonial, or example)
+
+### Scene 4: CTA (2-4 seconds)
+
+Specific > generic. Never use "Learn more" or "Click here."
+
+**Strong CTAs:**
+- "Book your free consultation"
+- "Get your custom quote"
+- "Send us a message"
+- "Link in Bio for [specific thing]"
+
+---
+
+## Headline Formulas
+
+### Outcome-Focused
+- `{Achieve outcome} without {pain point}`
+- `{Achieve outcome} by {how product makes it possible}`
+- `Turn {input} into {outcome}`
+- `[Achieve outcome] in [timeframe]`
+
+### Problem-Focused
+- `Never {unpleasant event} again`
+- `{Question highlighting the main pain point}?`
+- `Stop [pain]. Start [pleasure].`
+
+### Differentiation-Focused
+- `The {opposite of usual process} way to {achieve outcome}`
+- `The [category] that [key differentiator]`
+- `Finally, [category] that [benefit]`
+
+### Proof-Focused
+- `[Number] [people] use [product] to [outcome]`
+- `{Key benefit of your product}`
+
+---
+
+## Carousel Slide Copy (5 Slides)
+
+### Slide 1: Hook
+- Bold headline using a formula above
+- Subtext that creates curiosity
+- "Swipe to learn more" or arrow indicator
+
+### Slides 2-4: Content
+- One key point per slide
+- Headline + 2-3 bullet points maximum
+- Use icons instead of plain bullets
+- Benefits, not features
+
+### Slide 5: CTA
+- Recap core value proposition
+- Clear call to action
+- Brand logo and contact info
+- Trust signals (ratings, credentials)
+
+### Carousel Copy Rules
+
+1. **Front-load value**: First slide must earn the swipe
+2. **One idea per slide**: Don't cram multiple concepts
+3. **Progressive disclosure**: Each slide builds on the last
+4. **Visual hierarchy**: Headline > bullets > fine print
+5. **End with action**: Last slide must tell them what to do next
+
+---
+
+## Social Caption Copy
+
+### Caption Structure
+
+```
+[Hook - first line before "more" truncation]
+
+[Body - 2-3 short paragraphs]
+
+[CTA - what to do next]
+
+[Hashtags - 5-10 relevant]
+```
+
+### Caption Hooks (First Line)
+
+- Direct question: "Dealing with [problem] right now?"
+- Bold statement: "[Number]% of [audience] don't know this."
+- Story opener: "Last week, a client came to us with..."
+- Value promise: "[Number] things you should know about [topic]:"
+
+### Caption Length by Platform
+
+| Platform | Optimal Length | Notes |
+|----------|---------------|-------|
+| Instagram Reels | 50-100 chars | Short, let video do the talking |
+| Instagram Feed | 150-300 chars | Hook + key info + CTA |
+| Instagram Carousel | 200-400 chars | Summary + CTA |
+
+---
+
+## Writing Principles
+
+### Do
+- Use the audience's own language
+- Lead with benefits, not features
+- Be specific: "32% more conversions" beats "more conversions"
+- Use active voice: "We fix your problem" not "Your problem is fixed by us"
+- Write at a 6th-grade reading level
+- Front-load key messages (viewers may scroll away)
+
+### Don't
+- Use jargon the audience doesn't use
+- Make vague promises: "the best" or "world-class"
+- Write walls of text (especially on video)
+- Use more than one CTA per piece
+- Start with your brand name (earn attention first)
+
+---
+
+## Transitions to Avoid (AI Tells)
+
+These phrases signal AI-generated content and should be avoided:
+
+- "That being said,..."
+- "It's worth noting that..."
+- "At its core,..."
+- "In today's digital landscape,..."
+- "When it comes to the realm of..."
+- "This begs the question..."
+- "Let's delve into..."
+
+Use natural alternatives:
+- "However,..." / "But,..."
+- "What matters most is..."
+- "Here's the thing:"
+- "So what does this mean?"
+
+---
+
+## Script Review Checklist
+
+- [ ] Hook grabs attention in first 1-2 seconds
+- [ ] Problem is specific and relatable
+- [ ] Solution is clear and credible
+- [ ] CTA tells viewer exactly what to do
+- [ ] No jargon the audience wouldn't use
+- [ ] Each scene is 2-5 seconds (fits 15s total)
+- [ ] Copy matches the voiceover character preset
+- [ ] No AI-sounding phrases or filler
+
+---
+
+## Related Rules
+
+- [voiceover.md](../voiceover.md) - Match script to voice character presets
+- [captions.md](../captions.md) - Animated captions for the script
+- [carousels.md](../carousels.md) - Carousel slide layout specs