retention

🎥 Video Editing for the Agent Era

Inspired by the programmatic, code-first vision of Remotion, Retention brings video creation and retention engineering directly into the AI agent age.

Turn raw, unedited creator recordings into a publish-ready video with millisecond-accurate cuts, 2.5D Ken Burns B-roll cutaways, dynamic zoom animations, PiP demonstrative workspaces, content-aware motion graphics, karaoke captions, and high-CTR thumbnail covers — completely agentically and 100% locally:

• Edit agentically: Hand your RAW footage over to your AI coding agent (Claude Code, Antigravity, Codex, Cursor) and let it cut, animate, add B-roll, caption, and render automatically.

• 100% Native RetentionVolt Intelligence: Includes the entire RetentionVolt database embedded natively in data/ — 85 viral reference videos (13,487 shot/cut events), 49 analyzed high-CTR thumbnails, 15 motion graphics patterns (MG-001..MG-015), and 5 multi-shot retention flows. Zero external cloud dependencies, zero API keys, zero login prompts.

• Edit deterministically: Whisper speech analysis and HyperFrames headless browser composition guarantee millisecond-accurate sync. No timeline dragging, no Premiere, no DaVinci.

Related MCP server: ViralSpin MCP

⚡ 100% Native RetentionVolt Intelligence

Retention embeds the complete RetentionVolt dataset directly inside the repository (data/):

• data/retentionvolt_videos.json (85 Viral Videos • 13,487 Cut/Shot Events): Frame-accurate breakdowns of top creators (MrBeast, Marques Brownlee, Ali Abdaal, Fireship, Alex Hormozi, Cleo Abram, Veritasium, Johnny Harris, etc.) across b_roll (4,789 events), camera_angle_switch (4,081), motion_graphic (1,733), punch_zoom (1,689), slow_push_in (1,110), and talking_head hooks.

• data/retentionvolt_thumbnails.json (49 High-CTR Thumbnails): Complete CTR estimates, facial emotion analysis, color palettes, composition types, and Midjourney/Flux prompt recipes.

• data/retentionvolt_motion_graphics.json (15 Motion Graphics Specs): MG-001 through MG-015 with trigger rules, durations, GSAP easing curves, and glassmorphic CSS specs.

• data/retentionvolt_flows.json (5 Multi-Shot Retention Flows): Proven sequence templates (hook_0_15s, problem_setup, interactive_demo, sponsor_segue, outro_loop).

Every video edited with Retention automatically runs native similarity matching and applies B-roll cutaways, zoom animations, PiP demonstrations, and motion graphics.

🧠 Architecture & Pipeline

flowchart TD
    Raw["1. RAW Footage"] --> Ingest["Import & Metadata Ingest"]
    Ingest --> Transcribe["2. Local Whisper Transcription"]
    Transcribe --> Analyze["3. Narrative Analysis: Hook, Fillers, Cutaway Proposals"]
    Analyze --> RV["3b. Native RetentionVolt DB Match (85 Videos, 13,487 Cuts)"]
    RV --> Broll["3c. 2.5D Ken Burns B-Roll Cutaway Generation"]
    Broll --> Plan["4. Action Plan v1.3 (Cuts + B-Roll + Zooms + PiP Shots + Motion Graphics + Karaoke)"]
    Plan --> Render["5. HyperFrames MP4 Render"]
    Plan --> Thumb["5b. High-CTR Thumbnail Generation"]
    Render --> Review["6. Frame-by-Frame Verification Gate"]
    Thumb --> Review
    Review --> Delivery["7. Publish-Ready Delivery"]

🚀 Quickstart

Prerequisites

• Node.js: ≥ 20 (Node 22 recommended)

• FFmpeg: Available in system PATH

• Python: 3.9+ (for faster-whisper)

Installation

# Clone the repository
git clone https://github.com/Andrea13235/Retention.git
cd Retention

# Install dependencies
npm install

# Run one-time Whisper automated setup
node scripts/setup-whisper.js

# Verify environment readiness
npm run setup-check

# Compile TypeScript
npm run build

# Run comprehensive test suite (50/50 tests passing)
npm test

Configure with your AI Agent (MCP Configuration)

Add to your client configuration (claude_desktop_config.json, Cursor MCP, Codex, or Antigravity):

{
  "mcpServers": {
    "retention": {
      "command": "node",
      "args": ["/absolute/path/to/retention/dist/server.js"]
    }
  }
}

Install as an AI Skill (/Retention.editing & /Retention)

From inside your cloned Retention directory, run:

npm run install-skill

🛠️ MCP Tools

📦 Repository Layout

Retention/
├── SKILL.md                              # Agent workflow: native RetentionVolt pipeline
├── data/
│   ├── retentionvolt_videos.json         # 85 analyzed viral videos (13,487 shot/cut events)
│   ├── retentionvolt_thumbnails.json     # 49 analyzed high-CTR thumbnails
│   ├── retentionvolt_motion_graphics.json# 15 motion graphics patterns (MG-001..MG-015)
│   └── retentionvolt_flows.json          # 5 multi-shot retention flows
├── docs/
│   └── analysis-guide.md                 # Editor craft: cut rules, attention curve, EditPlan reference
├── src/
│   ├── server.ts                         # MCP server (stdio transport)
│   ├── retentionvolt_client.ts           # 100% Native RetentionVolt database engine
│   ├── tools_ingest.ts                   # Step 1: RAW import + ffprobe metadata
│   ├── tools_transcribe.ts               # Step 2: local Whisper, word timecodes, language detect
│   ├── tools_analyze.ts                  # Step 3: hook, sections, fillers, cut-safe cutaway proposals
│   ├── tools_image.ts                    # Step 3c: 2.5D Ken Burns B-roll image & SVG visual synthesis
│   ├── tools_plan.ts                     # Step 4: Action Plan v1.3 (always-on RetentionVolt, B-roll, animations, graphics)
│   ├── tools_render.ts                   # Step 5+6: HyperFrames render, thumbnail generator & frame verifier
│   └── types.ts                          # TypeScript contracts & schemas
└── tests/                                # 50/50 passing tests (unit, pipeline, native DB, e2e)