🎬 maskii-motion-studio

Creative Direction, Motion Design System & Evidence-Based Visual QA Framework for Remotion
Engineered for Programmatic Video Automation, Autonomous AI Agents & High-End Motion Graphics.

⚡ Quickstart via NPX

Set up maskii-motion-studio in any new or existing project with a single command:

npx maskii-motion-studio

🤖 Automatic Remotion Detection & Installation

If your project or machine does not have Remotion installed yet, maskii-motion-studio will automatically detect it and offer to install everything (remotion, @remotion/cli, react, react-dom, and TypeScript type definitions) using your preferred package manager (npm, pnpm, yarn, or bun).

🏛️ Core Principles & Boundaries

1. Audio-Driven 2-Gate Governance:
   • Gate 1 (Audio Generation Halt): The AI synthesizes the Creative Concept and complete ElevenLabs-ready Voiceover Script in Phase 2, then HALTS and waits for the user to upload the real .mp3 audio file.
   • Gate 2 (The Iron Gate): The AI measures the real audio duration via ffprobe, builds the full 6D Implementation Plan calibrated to the exact millisecond and frame budget, and HALTS turn until the user reviews and confirms with GASS or OKE.
2. The Anti-Static Reference Rule (Pure Procedural Motion):
   • Reference images (infographics, slides, mockups, screenshots) provided by the user are strictly blueprints/data sources, NEVER visual assets to be embedded.
   • Strictly FORBIDDEN from inserting static raster images (<Img>, <img>, background plates) into the video canvas.
   • The AI deconstructs reference images into pure code: native kinetic typography, Lucide/SVG vector icons, procedural CSS glass/neon cards, animated state machines, and interactive data flows. The result is a true 100% interactive motion graphic.
3. Calibrated Spring Physics (No Arbitrary Magic Numbers):
   • Never guess spring numbers. Choose from 4 mathematically calibrated presets: punchy_snap, smooth_glide, elastic_bounce, and cinematic_drift.
4. Evidence-Based Visual QA:
   • Every visual claim must be backed by empirical evidence (snapshots, CLI exit codes, measurements).

🔄 The 8-Phase Production Workflow

[Phase 1: Ingestion, Reference Deconstruction & DSS Retrieval]
       │  (Extract typography, palette, data points from references)
       ▼
[Phase 2: Creative Concept & Automated Voiceover Scripting] 
       │  (Propose visual direction & complete ElevenLabs-ready narration script)
       ▼
 🛑 GATE 1: AUDIO GENERATION HALT (Wait for User to Send Generated .MP3 File)
       │
       ▼ (Operator Uploads .MP3 Audio File)
[Phase 3: Audio Ingestion & Exact-Duration Implementation Plan]
       │  (Measure exact audio length via ffprobe, calibrate frame budget @ 30 FPS,
       │   map scene timestamps, kinetic typography, and pure procedural UI plan)
       ▼
 🛑 GATE 2: THE IRON GATE (Halt turn. Zero tools called. Await User Approval Token)
       │
       ▼ (Operator Approves Plan with 'GASS' / 'OKE' / 'LANJUTKAN')
[Phase 4: Pure Procedural Code Implementation]
       │  (100% native React/Remotion code; ZERO static raster image insertion)
       ▼
[Phase 5: Automated Checks] ───────────────────────────────► Lint, Typecheck, Build
       │
       ▼
[Phase 6: Empirical Snapshot QA] ──────────────────────────► 3-Tier Inspection (Tier 1 -> Tier 2 -> Tier 3)
       │
       ▼ (If Deficits Found)
[Phase 7: Revision Plan & Re-QA] ─────────────────────────► 🛑 GATE 3 (Halt & Await Revision Approval)
       │
       ▼ (Operator Approves Revision)
[Phase 8: Export & Knowledge Loop] ────────────────────────► Render MP4 & Retain to Second Brain ('ai-hud')

⚡ Calibrated Spring Physics Presets

Available directly via src/motion-tokens.ts:

| Preset Name | damping | mass | stiffness | Visual Feel & Best Use Case | | :--- | :---: | :---: | :---: | :--- | | punchy_snap | 12 | 0.5 | 140 | Snappy, energetic, with slight elastic overshoot. Ideal for hero titles, kinetic letters, logo pop, and bold value props. | | smooth_glide | 24 | 0.8 | 90 | Elegant, stable, critically damped with zero bounce. Ideal for camera pans, sliding code blocks, architectural cards, and subtitles. | | elastic_bounce | 9 | 0.4 | 160 | Playful, rubbery, high bounce. Ideal for notification pills, success badges, status dots, and micro-interactions. | | cinematic_drift| 35 | 1.2 | 60 | Heavy, deliberate, cinematic inertia. Ideal for ambient background glow scaling, large frame brackets, and slow outro breathing. |

Code Usage:

import { useCurrentFrame, useVideoConfig } from "remotion";
import { getMotionSpring } from "./motion-tokens";

const frame = useCurrentFrame();
const { fps } = useVideoConfig();

const progress = getMotionSpring(frame, fps, "punchy_snap", 10);

🎨 Dual-Layer Brand Tokens System

Separates studio authorship from project identity to prevent aesthetic forcing:

export interface BrandTokens {
  name: string;
  tagline: string;
  repoUrl?: string;
  palette: {
    backgroundVoid: string;    // Deep canvas tone (e.g. #040810)
    surfaceCard: string;        // Elevated panels/cards (e.g. rgba(11, 19, 41, 0.85))
    primaryAccent: string;      // Hero brand color (e.g. #00f0ff)
    secondaryAccent: string;    // Accent glow / highlights (e.g. #fbbf24)
    textPrimary: string;        // Hero text color (e.g. #ffffff)
    textSecondary: string;      // Subtitles & descriptions (e.g. #94a3b8)
    borderGlow: string;         // Framing borders (e.g. rgba(0, 240, 255, 0.35))
  };
  typography: {
    fontHeading: string;
    fontBody: string;
    fontMono: string;
  };
}

📁 Repository Structure

maskii-motion-studio/
├── bin/
│   └── cli.js                  # NPX CLI executable
├── skills/
│   └── maskii-motion-studio/   # Core Skill definition for AI Agents
│       ├── SKILL.md            # Primary governance law
│       ├── templates/          # Standardized Creative Spec & QA templates
│       └── references/         # Deep modular guides (Physics, Brand, Audio, QA)
├── templates/                  # Scaffolding templates for Remotion projects
│   ├── motion-tokens.ts        # Type-safe spring presets & brand tokens
│   └── remotion.config.ts      # Fast Rspack & render config
├── package.json
├── README.md
└── LICENSE

📄 License

MIT © Lucky Hermawan & FRIDAY Cognitive Core.