loopwind

# loopwind A CLI tool for generating images and videos from JSX templates using Tailwind CSS and Satori. Templates live in a `.loopwind/` directory alongside your codebase. ## Quick Start Loopwind is a CLI tool for generating images and videos with React and Tailwind CSS. It's designed to be used with AI Agents and Cursor. ### Installation ```bash curl -fsSL https://loopwind.dev/install.sh | bash ``` This installs loopwind to `~/.loopwind/` and adds the `loopwind` command to your PATH. Requires Node.js 18+. ### Initialize in Your Project Navigate to any project folder and run: ```bash loopwind init ``` This creates `.loopwind/loopwind.json` — a configuration file with your project's theme colors. ### Install AI Skill Give your AI agent expertise in loopwind: ```bash npx skills add https://loopwind.dev/skill.md ``` This installs a skill that teaches Claude Code (or other AI agents) how to create templates, use animation classes, and render images/videos. ### Use with Claude Code With the loopwind skill installed, Claude has deep knowledge of template structure, animation classes, and Tailwind CSS patterns for Satori. Just ask: ``` Create an OG image for my blog post about TypeScript tips ``` ``` Create an animated intro video for my YouTube channel ``` Claude will create optimized templates and render the final output automatically. ### Install a Template #### 1. Official Templates ```bash loopwind add image-template loopwind add video-template ``` Templates are installed to: `.loopwind/<template>/` **Benefits:** - Templates are local to your project - Version controlled with your project - Easy to share within your team ### Render a Template ```bash loopwind render template-name '{"title":"Hello World","subtitle":"Built with loopwind"}' ``` or use a local props file: ```bash loopwind render template-name props.json ``` ## Commands ### `loopwind add <source>` Install a template from various sources: ```bash # Official templates loopwind add image-template loopwind add video-template ``` These will be downloaded to `.loopwind/<template>/` ### `loopwind list` List all installed templates: ```bash loopwind list ``` ### `loopwind render <template> <props> [options]` Render an image or video: ```bash # Image with inline props loopwind render banner-hero '{"title":"Hello World"}' # Video with inline props loopwind render video-intro '{"title":"Welcome"}' # Using a props file loopwind render banner-hero props.json # Custom output loopwind render banner-hero '{"title":"Hello"}' --out custom-name.png # Different format loopwind render banner-hero '{"title":"Hello"}' --format jpeg ``` Options: - `--out, -o` - Output filename (default: `<template>.<ext>` in current directory) - `--format` - Output format: `png`, `jpeg`, `svg` (images only) - `--quality` - JPEG quality 1-100 (default: 92) ### `loopwind validate <template>` Validate a template: ```bash loopwind validate banner-hero ``` Checks: - Template file exists and is valid React - `export const meta` exists and is valid - Required props are defined - Fonts exist (if specified) ### `loopwind init` Initialize loopwind in a project: ```bash loopwind init ``` Creates `.loopwind/loopwind.json` configuration file with your project's design tokens. ## Animation Classes (Video Only) Use Tailwind-style animation classes - no manual calculations needed: ```tsx // Fade in: starts at 0ms, lasts 500ms <h1 style={tw('enter-fade-in/0/500')}>Hello</h1> // Loop: ping effect every 500ms <div style={tw('loop-ping/500')} /> // Combined with easing <h1 style={tw('ease-out enter-bounce-in-up/0/600')}>Title</h1> ``` See [Animation](/animation) for the complete reference. ## Next Steps - [Templates](/templates) - [Embedding Images](/images) - [Animation](/animation) - [Helpers (QR, Template Composition)](/helpers) - [Styling with Tailwind & shadcn/ui](/styling) - [Custom Fonts](/fonts) - [AI Agent Integration](/agents) # Templates Templates are React components that define your images and videos. They use Tailwind CSS for styling and export metadata that loopwind uses for rendering. ## Installing Templates ### Official Templates ```bash loopwind add image-template loopwind add video-template ``` Templates are installed to `.loopwind/<template-name>/`. ### Direct URLs ```bash loopwind add https://example.com/templates/my-template.json ``` ### Local Filesystem ```bash loopwind add ./my-templates/banner-hero loopwind add /Users/you/templates/social-card ``` --- ## Image Templates ### Basic Structure ```tsx // .loopwind/banner-hero/template.tsx export const meta = { name: "banner-hero", type: "image", description: "Hero banner with gradient background", size: { width: 1600, height: 900 }, props: { title: "string", subtitle: "string" } }; export default function BannerHero({ title, subtitle, tw }) { return ( <div style={tw('flex flex-col justify-center items-center w-full h-full bg-gradient-to-br from-purple-600 to-blue-500 p-12')}> <h1 style={tw('text-7xl font-bold text-white mb-4')}> {title} </h1> <p style={tw('text-2xl text-white/80')}> {subtitle} </p> </div> ); } ``` ### Rendering Images ```bash # Render with inline props loopwind render banner-hero '{"title":"Hello World","subtitle":"Welcome"}' # Custom output name loopwind render banner-hero '{"title":"Hello"}' --out custom-name.png # Different format loopwind render banner-hero '{"title":"Hello"}' --format jpeg --quality 95 # Use a props file loopwind render banner-hero props.json ``` ### Output Formats | Format | Best For | |--------|----------| | **PNG** (default) | Transparency, sharp text, logos | | **JPEG** | Photographs, gradients, smaller files | | **SVG** | Vector graphics, scalable designs | --- ## Video Templates ### Basic Structure ```tsx // .loopwind/video-intro/template.tsx export const meta = { name: "video-intro", type: "video", description: "Animated intro with bounce-in title", size: { width: 1920, height: 1080 }, video: { fps: 30, duration: 3 }, props: { title: "string" } }; export default function VideoIntro({ tw, title }) { return ( <div style={tw('flex items-center justify-center w-full h-full bg-gradient-to-br from-blue-600 to-purple-700')}> <h1 style={tw('text-8xl font-bold text-white ease-out enter-bounce-in-up/0/600')}> {title} </h1> </div> ); } ``` ### Rendering Videos ```bash # Render with inline props loopwind render video-intro '{"title":"Welcome!"}' --out intro.mp4 # Faster encoding with FFmpeg loopwind render video-intro '{"title":"Welcome!"}' --ffmpeg # Higher quality (lower CRF = better) loopwind render video-intro '{"title":"Welcome!"}' --crf 18 ``` ### FPS and Duration ```tsx video: { fps: 30, duration: 3 } // 90 frames total ``` | FPS | Use Case | |-----|----------| | **24** | Cinematic look, smaller files | | **30** | Standard web video | | **60** | Smooth animations | ### Video-Specific Props Templates receive these additional props: - **`frame`** - Current frame number (0 to totalFrames - 1) - **`progress`** - Animation progress from 0 to 1 ```tsx export default function MyVideo({ frame, progress }) { // frame: 0, 1, 2, ... 89 (for 3s @ 30fps) // progress: 0.0 at start, 0.5 at middle, 1.0 at end } ``` ### Encoding Options | Encoder | Command | Use Case | |---------|---------|----------| | **WASM** (default) | `loopwind render ...` | CI/CD, no dependencies | | **FFmpeg** | `loopwind render ... --ffmpeg` | Faster, smaller files | Install FFmpeg: `brew install ffmpeg` (macOS) --- ## Animation Classes Use Tailwind-style animation classes for videos: ```tsx // Enter animations: enter-{type}/{delay}/{duration} <h1 style={tw('enter-fade-in/0/500')}>Fade in at start</h1> <h1 style={tw('enter-bounce-in-up/300/400')}>Bounce in after 300ms</h1> // Exit animations: exit-{type}/{start}/{duration} <div style={tw('exit-fade-out/2500/500')}>Fade out at 2.5s</div> // Loop animations: loop-{type}/{duration} <div style={tw('loop-float/1000')}>Continuous floating</div> <div style={tw('loop-spin/1000')}>Spinning</div> // Easing <h1 style={tw('ease-out enter-slide-left/0/500')}>Smooth slide</h1> ``` See the full [Animation documentation](/animation) for all classes. --- ## Common Sizes ### Social Media - **Twitter/X Card**: 1200x675 - **Facebook/OG**: 1200x630 - **Instagram Post**: 1080x1080 - **LinkedIn Post**: 1200x627 ### Web Graphics - **Hero Banner**: 1920x1080 - **Blog Header**: 1600x900 - **Thumbnail**: 640x360 --- ## Example Templates ### Open Graph Image ```tsx export const meta = { name: "og-image", type: "image", size: { width: 1200, height: 630 }, props: { title: "string", description: "string" } }; export default function OGImage({ tw, image, title, description }) { return ( <div style={tw('flex w-full h-full bg-white')}> <div style={tw('flex-1 flex flex-col justify-between p-12')}> <img src={image('logo.svg')} style={tw('h-12 w-auto')} /> <div> <h1 style={tw('text-5xl font-bold text-gray-900 mb-4')}>{title}</h1> <p style={tw('text-xl text-gray-600')}>{description}</p> </div> <p style={tw('text-gray-400')}>yoursite.com</p> </div> </div> ); } ``` ### Animated Intro ```tsx export const meta = { name: "animated-intro", type: "video", size: { width: 1920, height: 1080 }, video: { fps: 60, duration: 3 }, props: { title: "string", subtitle: "string" } }; export default function AnimatedIntro({ tw, title, subtitle }) { return (