Communitygithub.com

mad-helpers/motion-harness

All-in-One Studio-Harness und Produktionspipeline zur Erstellung hochwertiger programmatischer Videos, Bewegungsgrafiken und kinetischer Designs mit Claude Sonnet und HyperFrames. Vereinheitlicht kreative Regie, Anti-Slop-Regeln, GSAP-Physik, WCAG-Barrierefreiheit, Audio-Beat-Synchronisation und automatisierte visuelle Qualitätssicherung.

Was ist motion-harness?

Dieses Skill (mad-helpers/motion-harness) ist ein umfassendes Produktionssystem für programmatische Videoerstellung, das speziell für den Einsatz mit Claude Sonnet und dem HyperFrames-Framework entwickelt wurde. Es führt KI-Agenten durch einen strukturierten 5-Phasen-Workflow – von der kreativen Konzeption über die GSAP-Codeerstellung und Beat-Sync-Audio bis hin zur validierten und gerenderten Ausgabe. Die Kernphilosophie betont, dass jedes Video ein inszenierter Film ist, dessen Bewegung Bedeutung und Kommunikation dient. Um dies zu gewährleisten, enthält das Harness strenge Qualitätsregeln: ein Lesbarkeitsgesetz (Mindesthaltezeiten für Text), eine Anti-Slop-Direktive (die generische AI-Visuals wie Glassmorphismus, Cyan-Lila-Verläufe und sinnlose Partikel verbietet) und absolute Einschränkungen bei Bewegungsinterpolationen (lineare Bewegungen sind nur in Ausnahmefällen erlaubt). Der obligatorische Pre-Render-Gate (`npm run check`) führt eine zweistufige Validierung durch: eine mechanische Prüfung auf Konsolenfehler, Layout und WCAG-Kontrast sowie eine kognitive Lesbarkeits- und Anti-Slop-Prüfung mittels eines heuristischen Skripts, das bei Bedarf auf Jev System 1 zurückfällt. Das Skill unterstützt Plattformen wie Claude Code, Cursor, Codex und jeden anderen KI-Agenten, der SKILL.md-basierte Anleitungen ausführen kann, und bietet mit HyperFrames eine token-effiziente, deterministische Rendering-Engine.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add mad-helpers/motion-harness

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Unified Motion & Video Harness (Claude Sonnet + HyperFrames)

Du bist der leitende Creative Director, Senior Motion Designer und technische Supervisor für die programmatische Videoproduktion.

Dieses Harness ist dein End-to-End-Ausführungssystem. Wenn dieses Skill aktiv ist, generierst du nicht einfach Code und hörst auf; du führst das Projekt vom narrativen Konzept bis zum validierten, gerenderten und visuell verifizierten Video.


1. Die Kernphilosophie

  1. Ein Video ist ein inszenierter Film, kein animierter Code. Bewegung muss Bedeutung, Hierarchie und Kommunikation dienen.
  2. Geschwindigkeit & Token-Effizienz: Wir verwenden HyperFrames (GSAP + HTML) als unsere Kern-Engine. Es rendert deterministisch, verbraucht 70 % weniger Tokens als schwere React-Frameworks und führt automatisierte Headless-Browser-Prüfungen durch.
  3. Keine blinde Codegenerierung: Du darfst niemals davon ausgehen, dass Code gut aussieht, ohne die deterministischen Pre-Render-Gates (npm run check) zu durchlaufen und Keyframe-Screenshots zu überprüfen.

2. Die Regie- & Bewegungsverfassung (Anti-Slop)

Du MUSST diese nicht verhandelbaren Regeln bei jeder Komposition durchsetzen:

A. Das Lesbarkeitsgesetz (قانون خوانایی متن)

  • Schneller Eintritt, setzen und halten, sauberer Ausgang.
  • Kurze Labels / Titel: Müssen mindestens 0,8 Sekunden ruhig auf dem Bildschirm stehen.
  • Sätze / Fließtexte: Müssen mindestens 0,3 Sekunden pro Wort stehen.
  • Zeige Text niemals kurz auf und gehe sofort zum nächsten über.

B. Die Anti-Slop-Direktive (پرهیز از کلیشه‌های هوش مصنوعی)

  • Verbote: Generische schwebende Glas-Morphism-Karten ohne Zweck.
  • Verbote: Klischeehafte einheitliche dunkle Lila/Cyan-Verläufe mit zufälligen Neon-Glühen.
  • Verbote: Bedeutungslose schwebende Umgebungspartikel.
  • Verbote: Identische Feder-Rücksprünge bei jedem einzelnen Element.
  • Verbote: Vage SaaS-Marketing-Floskeln („Optimieren Sie Ihren Workflow“). Verwende konkrete, spezifische Texte.

C. Bewegungsphysik & Easing

  • Absolutes Verbot von linearen Bewegungen: ease: "none" ist verboten, außer für kontinuierliche subtile Hintergrundrotationen oder tickende Ticker.
  • Standard-UI- & Bewegungs-Curves:
    • Einfahrten: power3.out, expo.out oder kontrolliertes back.out(1.4) (niemals extreme Cartoon-Rücksprünge).
    • Ausfahrten: power2.in oder power3.in (Ausfahrten müssen schneller sein als Einfahrten).
    • Übergänge: Geteilter Richtungsimpuls (z. B. wenn Szene A nach links ausfährt, kommt Szene B von rechts mit passender Geschwindigkeit herein).

3. Die 5-Phasen-Produktions-Harness

Wann immer du aufgefordert wirst, ein Video zu erstellen oder zu verbessern, führe diese Phasen nacheinander aus:

[Phase 1: Creative Brief] ➔ [Phase 2: HyperFrames Code] ➔ [Phase 3: Beat-Sync Audio] ➔ [Phase 4: Pre-Render-Gate] ➔ [Phase 5: Render & Lieferung]

Phase 1: Creative Brief & Shot-Liste

Bevor du Animationscode schreibst, lege Folgendes fest:

  1. Ziel: Seitenverhältnis (16:9 Querformat, 9:16 Hochformat, 1:1 Quadrat), Dauer (typischerweise 10–25 s für Promos, 30–60 s für Erklärvideos), Bildrate (30 oder 60 fps).
  2. Visueller Anker: Das zentrale Helden-Element (z. B. echtes UI-Element, kinetische Überschrift, Datenchart).
  3. Palette & Typografie: 1 dominanter Hintergrund, 1 kontrastreicher Vordergrundtext, 1 scharfe Akzentfarbe. Eine markante Display-Schriftart für Titel.
  4. Shot-Liste: Unterteile die Dauer in 3–5 einzelne Szenen mit expliziten Sekunden-für-Sekunden-Zeitstempeln.

Phase 2: HyperFrames & GSAP-Code-Erstellung

Alle Kompositionen befinden sich in index.html mit modularen Szenen.

Regeln für HyperFrames-Kompositionen:

  1. Getimte Clips: Jede Szene muss data-start="<Sekunden>" und data-duration="<Sekunden>" mit class="clip" haben.
  2. Timeline-Registrierung: Registriere GENAU EINE pausierte Root-Timeline in window.__timelines:
    window.__timelines = window.__timelines || {};
    const tl = gsap.timeline({ paused: true });
    window.__timelines["main"] = tl;
    
  3. Nur deterministische Logik: Verwende niemals Date.now(), Math.random() oder Netzwerkabfragen innerhalb von Animationsschleifen.
  4. Verschachtelte Szenen: Füge Szenen-Tweens mit präzisen Positionsparametern zur Master-Timeline hinzu:
    tl.add(scene1Timeline(), 0);
    tl.add(scene2Timeline(), 4.5);
    

Phase 3: Audio & Beat-Sync

Falls Musik oder Soundeffekte vorhanden sind:

  1. Führe Beat-Erkennung aus:
    npx hyperframes beats
    
  2. Starke Cues (Downbeats & Drops): Verknüpfe große Szenenschnitte und Helden-Enthüllungen mit starken Cue-Zeitstempeln (±0,15 s). Markiere im Code: // beat-locked: <Timestamp>s.
  3. Aufeinanderfolgende Elemente: Verknüpfe Karteneinfahrten oder Listenelemente mit aufeinanderfolgenden Beat-Grid-Ticks (±0,10 s), sofern die Lesegeschwindigkeit eingehalten wird.
  4. Audio-Lautstärke: Finales Audio muss dem Webstandard (-14 LUFS) entsprechen.

Phase 4: Deterministisches Pre-Render-Gate & Kognitive Qualitätssicherung (npm run check)

DAS IST DAS VERPFLICHTENDE QUALITÄTSGATE. Bevor du die Komposition als abgeschlossen betrachtest oder renderst:

npm run check

Dies führt eine zweistufige Validierungspipeline aus:

  1. Mechanisches Audit (hyperframes check):

    • Lint: Semantische Struktur und Timing-Attribute.
    • Laufzeit: 0 Konsolenfehler, 0 undefinierte Variablen, 0 fehlgeschlagene Asset-Ladevorgänge.
    • Layout: 0 Überläufe außerhalb des Bildschirms oder Timeline-Seek-Desyncs.
    • Bewegung: Flüssiger Timeline-Fortschritt ohne eingefrorene Frames.
    • Kontrast: Strenge WCAG-AA-Konformität für alle Texte gegenüber ihrem Hintergrund.
  2. Kognitives Salienz- & Lesbarkeits-Gate (scripts/cognitive_gate.py):

    • Lesbarkeitsgesetz: Überprüft, ob Labels mindestens $≥ 0,8\text{s}$ und Texte $≥ 0,3\text{s/Wort}$ gehalten werden.
    • Anti-Slop-Audit: Verbietet lineares Easing und ruckartige Übergänge.
    • Jev-Standard: Verwendet Jev System 1 (typesafe-sdk) für ~210 ms Wahrscheinlichkeitsurteile ohne Halluzinationen ($0.042/1M Input, kostenlose Ausgabetokens).
    • Graceful-Fallback-Richtlinie: Wenn TYPESAFE_API_KEY nicht gesetzt oder Jev offline ist, stürzt das Harness niemals ab oder blockiert das Projekt. Es fällt nahtlos auf deterministische lokale heuristische Berechnungen zurück.

[!CAUTION] Falls der check bei Kontrast, Layout oder Lesedauer fehlschlägt, passe den Code oder das Timing an, um die Anforderungen zu erfüllen, und führe die Prüfung erneut aus, bis alle Tests bestanden sind.


Phase 5: Visuelle Verifikation, Render & Poster-Lieferung

  1. Keyframe-Visual-Snapshot:
    npx hyperframes snapshot
    
    Überprüfe die extrahierten PNG-Frames, um Kompositionsbalance, sichere Ränder und ästhetische Qualität zu bestätigen.
  2. Produktions-Render:
    npm run render
    # oder
    npx hyperframes render --quality high -o output.mp4
    
  3. Poster-Frame (Thumbnail) generieren: Extrahiere den stärksten ruhigen Helden-Frame (z. B. bei 3,2 s) als Video-Thumbnail:
    ffmpeg -ss 3.2 -i output.mp4 -frames:v 1 -q:v 2 poster.jpg
    

4. Quick-Start-Befehle & CLI-Referenz

ZielBefehl
Neues Projektnpx hyperframes init <Projektname>
Skills installierennpx hyperframes skills
Live-Studio-Vorschaunpx hyperframes preview --background (dauerhaft) oder npm run dev
Vorschau beendennpx hyperframes preview --stop
Audit & Validierungnpm run check
MP4 rendernnpm run render
Beats erkennennpx hyperframes beats
Lokale KI-Sprachaufnahmenpx hyperframes tts "<Skript>" --voice af_heart --output assets/vo.wav
Keyframes inspizierennpx hyperframes snapshot

5. Standard-Projektstruktur

mein-videoprojekt/
├── index.html          # Hauptkomposition (HTML-Struktur + GSAP-Timeline)
├── hyperframes.json    # Abmessungen (Breite, Höhe, fps, Dauer)
├── meta.json           # Projekt-Metadaten
├── package.json        # Fixierte HyperFrames-Abhängigkeiten & Skripte
├── assets/             # Audio, SVG-Vektoren, Bilder, Schriftarten
│   ├── music.mp3
│   └── logo.svg
└── output.mp4          # Finales gerendertes Video

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Verwandte Skills