¶ VidCraft - AI Video-Produktion
¶ Inhaltsverzeichnis
- Überblick
- Was VidCraft anders macht
- Hauptfunktionen
- Workflow Pipeline
- Systemanforderungen
- Installation
- Konfiguration
- Kurzanleitung
- Projekt-Struktur
- Status-Modell
- MCP Tools Übersicht
- Hooks
- Knowledge Base
- Unterseiten
- Fehlerbehebung
- FAQ
¶ Überblick
VidCraft ist ein Claude Code Plugin für die professionelle Erstellung von KI-generierten Videos mit HeyGen und Synthesia. Es führt dich durch den kompletten Produktions-Lifecycle — von der Konzeptentwicklung über Script und Storyboard bis zur Veröffentlichung mit Subtitles und Thumbnail.
VidCraft generiert die Videos nicht selbst — die Generierung passiert in HeyGen oder Synthesia. Was VidCraft macht: alles davor und alles danach. Konzept, Script, Storyboard, Asset-Planung, Quality Gates, plattform-optimierte Formatierung, Post-Generation-Review, Subtitles, Promo-Texte, Thumbnails. Du kommst mit einem Thema rein und gehst mit einem versandreifen Video raus.
Wofür VidCraft gedacht ist:
- Software-Tutorials, Installations-Guides, Onboarding-Videos
- Erklärvideos, Marketing-Spots, Social-Shorts
- Schulungs- und Trainings-Reihen mit konsistenter Brand-Voice
- Doku-zu-Video-Pipelines (PDF/DOCX/MD → Episode)
- Multi-Plattform-Produktion (HeyGen + Synthesia parallel)
Wofür VidCraft nicht gedacht ist:
- Echte Filmproduktion mit echten Schauspielern (das ist nicht der Use Case von HeyGen/Synthesia)
- Animation-Filme (After Effects, Blender — falsches Tool)
- Belletristik-Schreiben (dafür gibt's StoryForge)
¶ Was VidCraft anders macht
Die meisten Workflows zur AI-Video-Produktion bestehen aus: ChatGPT-Script kopieren → in HeyGen einfügen → hoffen. VidCraft ersetzt das durch eine Pipeline mit Quality Gates, die blockieren, bis das Script wirklich versandbereit ist.
¶ Das 15-Punkt-Script-Gate
Kein Script geht in die Generierung, ohne durch eine 15-Punkt-Checkliste zu laufen — Timing (WPM-Berechnung), Readability (Flesch-Score), Hook-Qualität, CTA-Klarheit, AI-Sprache-Scan, Satzlänge, Szenen-Dauer, und ein Aussprache-Advisory (TTS-unfreundliche Zahlen und Abkürzungen). Siehe Quality System.
¶ Plattform-spezifische Engineers
heygen-engineer und synthesia-engineer sind nicht austauschbar. HeyGen erlaubt ein Background pro Szene, Synthesia ist slide-basiert. Pause-Syntax, Zeichen-Limits, Voice Director Presets, Avatar IV Motion Prompts, Synthesia Gesture Tags — jede Plattform hat eigene Regeln, die in den Skills hart kodiert sind. Siehe Plattformen.
¶ Doku-zu-Video-Pipeline
doc-analyzer parst PDF/DOCX/MD, extrahiert Code-Blöcke, Listen und Überschriften, schlägt Video-Struktur vor und empfiehlt einen Video-Typ. Aus einer Plugin-README wird eine 3-Episoden-Tutorial-Serie — ohne dass du das Script nochmal von Hand zusammensuchst. Siehe Document Analysis.
¶ Hauptfunktionen
- 33 spezialisierte Skills für jede Produktionsphase
- 36 MCP Tools für State Management, Content, Analyse, Quality Gates
- 12 Video-Typen mit Pacing-Regeln, Struktur-Templates und Best Practices
- Document Analysis — PDF/DOCX/MD analysieren und in Video-Content umwandeln
- 15-Punkt Script-Gate mit automatischen Prüfungen vor jeder Generierung
- 20-Punkt Video-Review nach Generierung
- Pre-Generation Gates — blockierend bis Script + Storyboard + Assets bereit sind
- Dual Platform Support — HeyGen und Synthesia parallel
- Multi-Language — Primär- und Übersetzungssprachen konfigurierbar
- Subtitle-Generator — Whisper-basiert mit Übersetzung für YouTube-Upload
- Knowledge Base — Anti-AI-Patterns, Platform-Checklist, Script-Rules eingebaut
¶ Workflow Pipeline
Komplettes durchgerechnetes Beispiel: Workflow-Beispiel
¶ Systemanforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| Python | 3.10+ | Empfohlen: Python 3.12 |
| Claude Code | 1.0+ | CLI, Desktop oder VS Code Extension |
| pip | 22+ | Für venv-Dependencies |
| HeyGen / Synthesia Account | aktuell | Mindestens einer für die Generierung |
| OpenAI Whisper | optional | Für subtitle-generator |
| ffmpeg | optional | Für Audio-Extraktion bei Subtitles |
¶ Installation
git clone https://github.com/markus-michalski/vidcraft.git ~/projekte/vidcraft
- Download von GitHub Releases
- Entpacken nach
~/projekte/vidcraft/
¶ Schritt 2: Plugin installieren
claude plugin install ~/projekte/vidcraft
¶ Schritt 3: Setup ausführen
In Claude Code:
/vidcraft:setup
Dies erstellt automatisch:
- Python venv unter
~/.vidcraft/venv/ - Dependencies: FastMCP, PyYAML, pdfplumber, python-docx, textstat
- Config-Template nach
~/.vidcraft/config.yaml - Cache-Verzeichnis
~/.vidcraft/cache/
¶ Schritt 4: Konfiguration anpassen
nano ~/.vidcraft/config.yaml
Wichtigster Wert: content_root (wo deine Video-Projekte liegen sollen).
¶ Schritt 5: Claude neu starten
Claude Code neu starten. Überprüfen mit /vidcraft:session-start.
¶ Konfiguration
¶ config.yaml
# ~/.vidcraft/config.yaml
paths:
content_root: "~/video-projects"
video_root: "~/video-projects/videos"
assets_root: "~/video-projects/assets"
overrides: "~/video-projects/overrides"
defaults:
language: ["de", "en"] # Einzeln oder Liste für Multi-Language
wpm: 140 # Words per Minute für Timing
platform: "heygen" # Default-Plattform
heygen:
default_avatar: ""
default_voice: ""
synthesia:
default_avatar: ""
default_voice: ""
brand:
name: "Firmenname"
primary_color: "#2563EB"
secondary_color: "#10B981"
tone: ["professional", "friendly"]
¶ Pfade
| Pfad | Beschreibung |
|---|---|
~/.vidcraft/config.yaml |
User-Konfiguration |
~/.vidcraft/cache/state.json |
State Cache (automatisch) |
~/.vidcraft/venv/ |
Python Virtual Environment |
{content_root}/projects/ |
Projekt-Dateien (Markdown) |
{content_root}/IDEAS.md |
Video-Ideen (Append-Style Markdown) |
{video_root}/projects/ |
Generierte Videos |
{assets_root}/projects/ |
Screenshots, Bilder |
¶ WPM-Standards pro Video-Typ
| Typ | WPM | Begründung |
|---|---|---|
| tutorial | 120-140 | Langsam für komplexe Schritte |
| installation-guide | 130-145 | Klar, sequenziell |
| explainer | 140-150 | Mittel bis schnell |
| marketing-spot | 150-160 | Energetisch |
| social-short | 150-170 | Sehr schnell |
¶ Kurzanleitung
¶ Standard-Workflow (Tutorial) — am Beispiel "OXID Gallery Tutorial"
1. /vidcraft:new-project "OXID Gallery Tutorial" tutorial
→ Verzeichnisstruktur unter projects/oxid-gallery-tutorial/
2. /vidcraft:doc-analyzer ~/projekte/oxid-gallery/README.md
→ Analyse: 3.500 Wörter, 12 Sektionen
→ Empfehlung: Tutorial-Serie (3 Episoden)
3. /vidcraft:project-conceptualizer oxid-gallery-tutorial
→ 5-Phasen-Konzept: Zielgruppe, Tonalität, Episode-Struktur
4. /vidcraft:brief-creator oxid-gallery-tutorial
→ Creative Brief mit Goals, Audience, Tone, Constraints
5. /vidcraft:script-writer oxid-gallery-tutorial 01-installation
→ Script mit Narration und Visual Cues
6. /vidcraft:script-reviewer oxid-gallery-tutorial 01-installation
→ 15-Punkt-Check
7. /vidcraft:storyboard-creator oxid-gallery-tutorial 01-installation
→ Szene-für-Szene Visual Direction
8. /vidcraft:screenshot-planner oxid-gallery-tutorial 01-installation
→ Screenshot-Positionen + Recordings definieren
9. /vidcraft:asset-collector oxid-gallery-tutorial 01-installation
→ Asset-Inventar prüfen
10. /vidcraft:pre-generation-check oxid-gallery-tutorial 01-installation
→ Quality Gates blockieren bis alles bereit ist
11. /vidcraft:heygen-engineer oxid-gallery-tutorial 01-installation
→ HeyGen-spezifisches Format (Szenen, Pause-Marker, Avatar, Voice Director)
12. (Manuelle Generierung in HeyGen)
13. /vidcraft:video-reviewer oxid-gallery-tutorial 01-installation
→ 20-Punkt-Post-Generation-Review
14. /vidcraft:subtitle-generator oxid-gallery-tutorial 01-installation
→ Whisper-Transkription + Übersetzung → SRT
15. /vidcraft:promo-writer oxid-gallery-tutorial 01-installation
→ YouTube-Description + Social-Posts (FB/IG/X/LinkedIn)
16. /vidcraft:thumbnail-director oxid-gallery-tutorial 01-installation
→ Thumbnail-Konzept
17. /vidcraft:release-director oxid-gallery-tutorial 01-installation
→ Final-QA + Distribution-Channels
Komplettes durchgerechnetes Beispiel: Workflow-Beispiel
¶ Projekt-Struktur
Jedes Projekt ist ein eigenes Verzeichnis unter {content_root}/projects/:
oxid-gallery-tutorial/
├── README.md # Projekt-Metadaten (YAML Frontmatter)
├── brief.md # Creative Brief
├── concept.md # Konzept-Dokument
├── research/ # Audience, Sources, Doc-Analysen
│ ├── audience.md
│ └── doc-analysis.md
├── episodes/
│ ├── 01-installation/
│ │ ├── README.md # Episode-Metadaten + Status
│ │ ├── script.md # Szenen mit Narration + Visual Cues
│ │ ├── storyboard.md # Visual Direction pro Szene
│ │ ├── shot-list.md # Produktionsreife Shot-Liste
│ │ ├── ASSETS.md # Asset-Inventar
│ │ └── scenes/
│ │ ├── 01-hook.md
│ │ └── 02-step-one.md
│ └── 02-konfiguration/
├── assets/ # Screenshots, Bilder, Recordings
├── output/ # Generierte Videos, SRTs
├── promo/ # YouTube-Description, Social-Posts
└── CLAUDE.md # Projekt-spezifische Rules (optional)
¶ Status-Modell
¶ Projekt-Status
¶ Episode-Status
Not Started → Script Draft → Script Reviewed → Storyboard
→ Assets Collected → Ready for Generation → Generated → QA Passed → Final
¶ Szene-Status
Outline → Script Written → Visual Defined → Assets Ready → Generated → Approved
¶ Idea-Status
raw → explored → developed → ready → promoted (oder shelved)
¶ MCP Tools Übersicht
Der MCP Server vidcraft-mcp stellt 36 Tools in folgenden Kategorien bereit:
| Kategorie | Tools | Beispiele |
|---|---|---|
| State Management | 8 | list_projects, find_project, get_project_full, search |
| Content Operations | 9 | create_project_structure, create_episode, create_scene, update_field |
| Document Analysis | 5 | analyze_document, extract_key_points, suggest_video_structure |
| Platform Integration | 5 | validate_platform_limits, heygen_format_script, synthesia_format_script |
| Script Analysis | 3 | analyze_timing, check_readability, check_pronunciation |
| Quality Gates | 2 | run_pre_generation_gates, validate_project_structure |
| Ideas & Meta | 4 | create_video_idea, get_video_ideas, get_plugin_version, validate_structure |
Hinweis: Die Ideas-Tools heißen vidcraft-spezifisch
create_video_idea/get_video_ideas(umbenannt auscreate_idea/get_ideas), um Bare-Name-Kollisionen mitstoryforge-mcp.create_ideazu vermeiden, wenn beide Plugins gleichzeitig geladen sind.
Wichtig: Skills dürfen Projektdateien nie direkt parsen. Jeder State-Zugriff läuft über MCP Tools.
Detail-Liste mit Parametern: siehe Plugin-Repository servers/vidcraft-server/server.py.
¶ Hooks
VidCraft registriert einen Hook:
¶ Scene Validator (validate_scene.py)
Läuft nach jedem Write/Edit auf Szenen-Dateien. Prüft:
- YAML-Frontmatter-Syntax
- Pflichtfelder (number, slug, status)
- Status-Wert gegen erlaubte Werte
- Narration vorhanden bei Status
Script Writtenoder höher
¶ Knowledge Base
Im knowledge/-Ordner liegen vier Reference-Dokumente, die Skills bei Bedarf nachladen:
| Datei | Inhalt |
|---|---|
ai-language-patterns.md |
AI-typische Phrasen, Filler, Hedging — von voice-checker und script-reviewer genutzt |
platform-checklist.md |
HeyGen + Synthesia Hard-Constraints, Pause-Syntax, Post-Production-Marker |
script-writing-rules.md |
Plattform-unabhängige Narration- und On-Screen-Text-Regeln |
status-workflow.md |
Status-zu-nächstes-Skill-Matrix für next-step |
Diese Dateien sind die Single Source of Truth. Skills referenzieren sie statt Regeln zu duplizieren.
¶ Unterseiten
Tiefere Dokumentation in separaten Seiten:
- Skills im Detail — Alle 33 Skills mit Zweck, Input, Output, Modell
- Video-Typen — 12 Typen mit Pacing-Regeln und Struktur-Templates
- Plattformen — HeyGen vs. Synthesia: Limits, Voice Director, Avatar IV, Express-2
- Quality System — 15-Punkt-Script, 20-Punkt-Video, Pre-Gen-Gates
- Document Analysis — Doc-Analyzer-Workflow im Detail
- Workflow-Beispiel — OXID Gallery Tutorial von Anfang bis Ende
¶ Fehlerbehebung
¶ Problem: MCP Server verbindet nicht
Symptome: Skills zeigen Fehler, keine MCP Tools verfügbar.
Prüfen:
claude plugin list | grep vidcraft
ls ~/.vidcraft/venv/bin/python3
~/.vidcraft/venv/bin/pip list | grep mcp
Lösung:
/vidcraft:setup
¶ Problem: State Cache leer
Symptome: list_projects zeigt nichts, obwohl Projekte existieren.
Lösung:
/vidcraft:session-start
Rebuild passiert automatisch aus den Markdown-Dateien.
¶ Problem: Document Analysis schlägt fehl
Symptome: analyze_document gibt Import-Fehler.
Lösung:
~/.vidcraft/venv/bin/pip install pdfplumber python-docx
¶ Problem: Pre-Generation-Check blockiert immer
Symptome: Auch wenn Script fertig aussieht, blockt der Gate.
Ursache: Status-Felder im YAML-Frontmatter wurden nicht aktualisiert.
Prüfen:
grep -A1 "status:" ~/video-projects/projects/MEIN-PROJEKT/episodes/01-FOO/README.md
Lösung: Status auf Script Reviewed setzen, nachdem script-reviewer durchgelaufen ist.
¶ Problem: HeyGen-Format hat zu viele Szenen
Symptome: Eine Episode wird unerwartet in viele HeyGen-Szenen gesplittet.
Ursache: Szenen brauchen mehrere Backgrounds oder Avatar-Wechsel — HeyGen erlaubt exakt einen Background und einen Avatar pro Szene.
Lösung:
- Szenen auf Background-Wechsel und Avatar-Wechsel prüfen und dort splitten
analyze_timingzeigt Szenen-Längen-Hot-Spots- Bei langen Erklär-Passagen ohne Background-Wechsel: AI Studio auto-splittet bei ~1.000 Zeichen — kein manuelles Eingreifen nötig
¶ Problem: Subtitle-Generator findet kein Video
Symptome: subtitle-generator meldet "no video file found".
Ursache: Final-Video wurde nicht in output/-Verzeichnis abgelegt.
Lösung: Finalisiertes Video manuell nach {video_root}/projects/MEIN-PROJEKT/episodes/01-FOO/final.mp4 kopieren.
¶ FAQ
F: Generiert VidCraft die Videos automatisch?
A: Nein. VidCraft optimiert den Vorbereitungs- und Review-Prozess. Die Generierung erfolgt manuell in HeyGen oder Synthesia. API-Integration ist Roadmap, aber nicht Teil von v1.x.
F: Kann ich beide Plattformen gleichzeitig nutzen?
A: Ja. Jede Episode kann eine eigene Plattform haben. Die kreative Arbeit (Script, Storyboard, Assets) ist plattform-unabhängig — erst heygen-engineer bzw. synthesia-engineer formatieren plattform-spezifisch. Du kannst dasselbe Script also problemlos doppelt rendern.
F: Welche Dokumentformate werden unterstützt?
A: PDF, DOCX und Markdown. Der Doc Analyzer extrahiert Struktur, Code-Blöcke, Listen und Überschriften. Für Web-Quellen nimm den researcher-Skill.
F: Kann ich eigene Video-Typen erstellen?
A: Ja. Mit /vidcraft:video-type-creator [name] erstellst du neue Typ-Definitionen mit Pacing-Regeln, Struktur-Template und Best Practices. Liegt unter video-types/{name}/README.md.
F: Brauche ich einen HeyGen/Synthesia Account?
A: Ja, für die Generierung. VidCraft selbst ist Open Source. Die Plattform-Abos kosten extra (Stand 2026: HeyGen ab ~$24/Monat, Synthesia ab ~$22/Monat).
F: Wie geht das Plugin mit AI-Sprache um?
A: voice-checker scannt Narration auf typische AI-Patterns: abstrakte Nomen-Stacks, Hedging, generische Vergleiche. Die Patterns liegen versionierbar in knowledge/ai-language-patterns.md — Pull Requests willkommen.
F: Funktioniert das auch auf Englisch?
A: Ja. Sprache ist über defaults.language konfigurierbar (einzeln oder Liste). Multi-Language-Projekte legen pro Sprache eigene Script-Varianten ab. Alle Skills sind sprach-neutral.
F: Was unterscheidet VidCraft von einem normalen ChatGPT-Workflow?
A: Pipeline statt Prompt. ChatGPT gibt dir Output, dann fängst du wieder bei null an. VidCraft hält State (Projekt, Episode, Szene), trackt Status, erzwingt Quality Gates und liefert plattform-spezifische Outputs. Das ist der Unterschied zwischen "ein Video gemacht" und "wiederholbarer Produktions-Workflow".
F: Kann ich VidCraft kommerziell nutzen?
A: Eingeschränkt. Lizenz ist PolyForm Noncommercial 1.0.0. Privat, akademisch, für interne Firmen-Workflows ohne externen Verkauf — ja. Für SaaS-Angebote oder kommerzielle Wiederveröffentlichung — nein, ohne separaten Lizenz-Deal. Kontakt über GitHub Issues.
¶ Lizenz
PolyForm Noncommercial 1.0.0 — GitHub Repository
Entwickelt von Markus Michalski