¶ VidCraft - AI Video Production
¶ Table of Contents
- Overview
- What Makes VidCraft Different
- Key Features
- Workflow Pipeline
- System Requirements
- Installation
- Configuration
- Quick Start
- Project Structure
- Status Model
- MCP Tools Overview
- Hooks
- Knowledge Base
- Sub-Pages
- Troubleshooting
- FAQ
¶ Overview
VidCraft is a Claude Code plugin for the professional production of AI-generated videos with HeyGen and Synthesia. It guides you through the full production lifecycle — from concept development to script and storyboard, all the way to publishing with subtitles and thumbnails.
VidCraft does not generate the videos itself — that happens in HeyGen or Synthesia. What VidCraft does: everything before and everything after. Concept, script, storyboard, asset planning, quality gates, platform-optimized formatting, post-generation review, subtitles, promo copy, thumbnails. You walk in with a topic and walk out with a release-ready video.
Who VidCraft is for:
- Software tutorials, installation guides, onboarding videos
- Explainer videos, marketing spots, social shorts
- Training and education series with consistent brand voice
- Doc-to-video pipelines (PDF/DOCX/MD → episode)
- Multi-platform production (HeyGen + Synthesia in parallel)
Who VidCraft is not for:
- Real film production with real actors (not the use case of HeyGen/Synthesia)
- Animation films (After Effects, Blender — wrong tool)
- Fiction writing (use StoryForge for that)
¶ What Makes VidCraft Different
Most AI video workflows look like: copy ChatGPT script → paste into HeyGen → hope. VidCraft replaces this with a pipeline of quality gates that block until the script is actually release-ready.
¶ The 15-Point Script Gate
No script enters generation without running through a 15-point checklist — timing (WPM calculation), readability (Flesch score), hook quality, CTA clarity, AI-language scan, sentence length, scene duration, and a pronunciation advisory (TTS-unfriendly numbers and acronyms). See Quality System.
¶ Platform-Specific Engineers
heygen-engineer and synthesia-engineer are not interchangeable. HeyGen allows one background per scene, Synthesia is slide-based. Pause syntax, character limits, Voice Director presets, Avatar IV Motion Prompts, Synthesia gesture tags — every platform has its own rules, hard-coded into the skills. See Platforms.
¶ Doc-to-Video Pipeline
doc-analyzer parses PDF/DOCX/MD, extracts code blocks, lists, and headings, suggests video structure, and recommends a video type. A plugin README becomes a 3-episode tutorial series — without you assembling the script by hand. See Document Analysis.
¶ Key Features
- 33 specialized skills for every production phase
- 36 MCP tools for state management, content, analysis, quality gates
- 12 video types with pacing rules, structure templates, and best practices
- Document analysis — analyze PDF/DOCX/MD and turn it into video content
- 15-point script gate with automatic checks before every generation
- 20-point video review after generation
- Pre-generation gates — block until script + storyboard + assets are ready
- Dual platform support — HeyGen and Synthesia in parallel
- Multi-language — primary and translation languages configurable
- Subtitle generator — Whisper-based with translation for YouTube upload
- Knowledge base — anti-AI patterns, platform checklist, script rules built in
¶ Workflow Pipeline
Complete worked example: Workflow Example
¶ System Requirements
| Requirement | Version | Notes |
|---|---|---|
| Python | 3.10+ | Recommended: Python 3.12 |
| Claude Code | 1.0+ | CLI, Desktop, or VS Code Extension |
| pip | 22+ | For venv dependencies |
| HeyGen / Synthesia Account | current | At least one for generation |
| OpenAI Whisper | optional | For subtitle-generator |
| ffmpeg | optional | For audio extraction during subtitling |
¶ Installation
git clone https://github.com/markus-michalski/vidcraft.git ~/projekte/vidcraft
- Download from GitHub Releases
- Extract to
~/projekte/vidcraft/
¶ Step 2: Install Plugin
claude plugin install ~/projekte/vidcraft
¶ Step 3: Run Setup
In Claude Code:
/vidcraft:setup
This automatically creates:
- Python venv at
~/.vidcraft/venv/ - Dependencies: FastMCP, PyYAML, pdfplumber, python-docx, textstat
- Config template at
~/.vidcraft/config.yaml - Cache directory
~/.vidcraft/cache/
¶ Step 4: Customize Configuration
nano ~/.vidcraft/config.yaml
Most important value: content_root (where your video projects live).
¶ Step 5: Restart Claude
Restart Claude Code. Verify with /vidcraft:session-start.
¶ Configuration
¶ 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: ["en", "de"] # single value or list for multi-language
wpm: 140 # words per minute for timing
platform: "heygen" # default platform
heygen:
default_avatar: ""
default_voice: ""
synthesia:
default_avatar: ""
default_voice: ""
brand:
name: "Company Name"
primary_color: "#2563EB"
secondary_color: "#10B981"
tone: ["professional", "friendly"]
¶ Paths
| Path | Description |
|---|---|
~/.vidcraft/config.yaml |
User configuration |
~/.vidcraft/cache/state.json |
State cache (automatic) |
~/.vidcraft/venv/ |
Python virtual environment |
{content_root}/projects/ |
Project files (Markdown) |
{content_root}/IDEAS.md |
Video ideas (append-style Markdown) |
{video_root}/projects/ |
Generated videos |
{assets_root}/projects/ |
Screenshots, images |
¶ WPM Standards per Video Type
| Type | WPM | Reason |
|---|---|---|
| tutorial | 120-140 | Slow for complex steps |
| installation-guide | 130-145 | Clear, sequential |
| explainer | 140-150 | Medium to fast |
| marketing-spot | 150-160 | Energetic |
| social-short | 150-170 | Very fast |
¶ Quick Start
¶ Standard Workflow (Tutorial) — example "OXID Gallery Tutorial"
1. /vidcraft:new-project "OXID Gallery Tutorial" tutorial
→ Directory structure under projects/oxid-gallery-tutorial/
2. /vidcraft:doc-analyzer ~/projekte/oxid-gallery/README.md
→ Analysis: 3,500 words, 12 sections
→ Recommendation: tutorial series (3 episodes)
3. /vidcraft:project-conceptualizer oxid-gallery-tutorial
→ 5-phase concept: audience, tone, episode structure
4. /vidcraft:brief-creator oxid-gallery-tutorial
→ Creative brief with goals, audience, tone, constraints
5. /vidcraft:script-writer oxid-gallery-tutorial 01-installation
→ Script with narration and visual cues
6. /vidcraft:script-reviewer oxid-gallery-tutorial 01-installation
→ 15-point check
7. /vidcraft:storyboard-creator oxid-gallery-tutorial 01-installation
→ Scene-by-scene visual direction
8. /vidcraft:screenshot-planner oxid-gallery-tutorial 01-installation
→ Define screenshot positions + recordings
9. /vidcraft:asset-collector oxid-gallery-tutorial 01-installation
→ Verify asset inventory
10. /vidcraft:pre-generation-check oxid-gallery-tutorial 01-installation
→ Quality gates block until everything is ready
11. /vidcraft:heygen-engineer oxid-gallery-tutorial 01-installation
→ HeyGen-specific format (scenes, pause markers, avatar, Voice Director)
12. (Manual generation in HeyGen)
13. /vidcraft:video-reviewer oxid-gallery-tutorial 01-installation
→ 20-point post-generation review
14. /vidcraft:subtitle-generator oxid-gallery-tutorial 01-installation
→ Whisper transcription + translation → 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 concept
17. /vidcraft:release-director oxid-gallery-tutorial 01-installation
→ Final QA + distribution channels
Complete worked example: Workflow Example
¶ Project Structure
Every project is its own directory under {content_root}/projects/:
oxid-gallery-tutorial/
├── README.md # Project metadata (YAML frontmatter)
├── brief.md # Creative brief
├── concept.md # Concept document
├── research/ # Audience, sources, doc analyses
│ ├── audience.md
│ └── doc-analysis.md
├── episodes/
│ ├── 01-installation/
│ │ ├── README.md # Episode metadata + status
│ │ ├── script.md # Scenes with narration + visual cues
│ │ ├── storyboard.md # Visual direction per scene
│ │ ├── shot-list.md # Production-ready shot list
│ │ ├── ASSETS.md # Asset inventory
│ │ └── scenes/
│ │ ├── 01-hook.md
│ │ └── 02-step-one.md
│ └── 02-configuration/
├── assets/ # Screenshots, images, recordings
├── output/ # Generated videos, SRTs
├── promo/ # YouTube description, social posts
└── CLAUDE.md # Project-specific rules (optional)
¶ Status Model
¶ Project Status
¶ Episode Status
Not Started → Script Draft → Script Reviewed → Storyboard
→ Assets Collected → Ready for Generation → Generated → QA Passed → Final
¶ Scene Status
Outline → Script Written → Visual Defined → Assets Ready → Generated → Approved
¶ Idea Status
raw → explored → developed → ready → promoted (or shelved)
¶ MCP Tools Overview
The MCP server vidcraft-mcp provides 36 tools in these categories:
| Category | Tools | Examples |
|---|---|---|
| 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 |
Note: The Ideas tools are vidcraft-specific
create_video_idea/get_video_ideas(renamed fromcreate_idea/get_ideas) to avoid bare-name collisions withstoryforge-mcp.create_ideawhen both plugins are loaded simultaneously.
Important: Skills must never parse project files directly. Every state access goes through MCP tools.
Detailed list with parameters: see plugin repo at servers/vidcraft-server/server.py.
¶ Hooks
VidCraft registers one hook:
¶ Scene Validator (validate_scene.py)
Runs after every write/edit on scene files. Checks:
- YAML frontmatter syntax
- Required fields (number, slug, status)
- Status value against allowed values
- Narration present at status
Script Writtenor higher
¶ Knowledge Base
Inside the knowledge/ folder live four reference documents that skills load on demand:
| File | Contents |
|---|---|
ai-language-patterns.md |
AI-typical phrases, filler, hedging — used by voice-checker and script-reviewer |
platform-checklist.md |
HeyGen + Synthesia hard constraints, pause syntax, post-production marker |
script-writing-rules.md |
Platform-independent narration and on-screen-text rules |
status-workflow.md |
Status-to-next-skill matrix for next-step |
These files are the single source of truth. Skills reference them instead of duplicating rules.
¶ Sub-Pages
Deeper documentation on separate pages:
- Skills in Detail — All 33 skills with purpose, input, output, model
- Video Types — 12 types with pacing rules and structure templates
- Platforms — HeyGen vs. Synthesia: limits, capabilities, Voice Director, Avatar IV, Express-2
- Quality System — 15-point script, 20-point video, pre-gen gates
- Document Analysis — Doc analyzer workflow in detail
- Workflow Example — OXID Gallery Tutorial from start to finish
¶ Troubleshooting
¶ Problem: MCP server not connecting
Symptoms: Skills show errors, no MCP tools available.
Check:
claude plugin list | grep vidcraft
ls ~/.vidcraft/venv/bin/python3
~/.vidcraft/venv/bin/pip list | grep mcp
Solution:
/vidcraft:setup
¶ Problem: State cache empty
Symptoms: list_projects shows nothing despite existing projects.
Solution:
/vidcraft:session-start
Rebuild happens automatically from the Markdown files.
¶ Problem: Document analysis fails
Symptoms: analyze_document throws import errors.
Solution:
~/.vidcraft/venv/bin/pip install pdfplumber python-docx
¶ Problem: Pre-generation check always blocks
Symptoms: Even though the script looks done, the gate still blocks.
Cause: Status fields in the YAML frontmatter were not updated.
Check:
grep -A1 "status:" ~/video-projects/projects/MY-PROJECT/episodes/01-FOO/README.md
Solution: Set status to Script Reviewed after script-reviewer ran.
¶ Problem: HeyGen format has too many scenes
Symptoms: One episode gets split into many HeyGen scenes unexpectedly.
Cause: Scenes require multiple backgrounds or avatar switches — HeyGen allows exactly one background and one avatar per scene.
Solution:
- Review scenes for background or avatar switches and split at those points
analyze_timingshows scene length hot spots- For long explanation passages without background changes: AI Studio auto-splits at ~1,000 chars — no manual intervention needed for length alone
¶ Problem: Subtitle generator can't find video
Symptoms: subtitle-generator reports "no video file found".
Cause: Final video was not placed in the output/ directory.
Solution: Manually copy the finalized video to {video_root}/projects/MY-PROJECT/episodes/01-FOO/final.mp4.
¶ FAQ
Q: Does VidCraft generate the videos automatically?
A: No. VidCraft optimizes the preparation and review process. Generation happens manually in HeyGen or Synthesia. API integration is on the roadmap but not part of v1.x.
Q: Can I use both platforms at the same time?
A: Yes. Each episode can have its own platform. The creative work (script, storyboard, assets) is platform-independent — only heygen-engineer and synthesia-engineer format platform-specifically. So you can render the same script twice without rework.
Q: Which document formats are supported?
A: PDF, DOCX, and Markdown. The doc analyzer extracts structure, code blocks, lists, and headings. For web sources, use the researcher skill.
Q: Can I create custom video types?
A: Yes. Use /vidcraft:video-type-creator [name] to create new type definitions with pacing rules, structure templates, and best practices. Lives under video-types/{name}/README.md.
Q: Do I need a HeyGen/Synthesia account?
A: Yes, for generation. VidCraft itself is open source. Platform subscriptions cost extra (as of 2026: HeyGen from ~$24/month, Synthesia from ~$22/month).
Q: How does the plugin handle AI-language?
A: voice-checker scans narration for typical AI patterns: abstract noun stacks, hedging, generic comparisons. The patterns live versionably in knowledge/ai-language-patterns.md — pull requests welcome.
Q: Does this work in English?
A: Yes. Language is configurable via defaults.language (single or list). Multi-language projects keep separate script variants per language. All skills are language-neutral.
Q: What's the difference between VidCraft and a normal ChatGPT workflow?
A: Pipeline instead of prompt. ChatGPT gives you output, then you start from zero again. VidCraft holds state (project, episode, scene), tracks status, enforces quality gates, and produces platform-specific output. That's the difference between "made one video" and "repeatable production workflow."
Q: Can I use VidCraft commercially?
A: Restricted. License is PolyForm Noncommercial 1.0.0. Private, academic, internal company workflows without external resale — yes. SaaS offerings or commercial republishing — no, not without a separate license deal. Reach out via GitHub Issues.
¶ License
PolyForm Noncommercial 1.0.0 — GitHub Repository
Built by Markus Michalski