VidCraft Configuration

Configure VidCraft: config.yaml with paths and speaking pace, which settings are actually evaluated, project and file structure, and frontmatter fields for project, episode and scene.

VidCraft Configuration

Deutsche Version

Back to overview

Configuration file

VidCraft reads ~/.vidcraft/config.yaml. /vidcraft:setup creates it from the template config/config.example.yaml; /vidcraft:configure edits it interactively. If the file is missing, the MCP server uses built-in defaults. Values from the file override the defaults key by key.

paths:
  content_root: "~/video-projects"
  video_root: "~/video-projects/videos"
  assets_root: "~/video-projects/assets"
  overrides: "~/video-projects/overrides"

defaults:
  language: ["de", "en"]
  wpm: 140
  platform: "heygen"

heygen:
  default_avatar: ""
  default_voice: ""

synthesia:
  default_avatar: ""
  default_voice: ""

brand:
  name: ""
  primary_color: ""
  secondary_color: ""
  font: ""
  tone: ["professional", "friendly"]

Paths may contain ~ and environment variables.

What is evaluated

Key	Effect
`paths.content_root`	Root of all project files (Markdown). Projects live under `{content_root}/projects/`, ideas in `{content_root}/IDEAS.md`. File operations and document analysis of the MCP server are restricted to this directory.
`paths.video_root`	Target for finished video files, resolved as `{video_root}/projects/{project}`.
`paths.assets_root`	Target for screenshots and images, resolved as `{assets_root}/projects/{project}`.
`defaults.wpm`	Words per minute used for the duration estimate of the pre-generation gates. Default: 140.

The remaining keys of the template (paths.overrides, defaults.language, defaults.platform, heygen.*, synthesia.*, brand.*) are not evaluated by the MCP server. A project's language and platform live in the frontmatter of the project README and are set when the project is created (defaults: de and heygen). The brand-checker skill reads brand tone from the project README and the configuration.

Project structure

Each project is a directory under {content_root}/projects/. The slug is derived from the title.

{project-slug}/
├── README.md              # project metadata (YAML frontmatter)
├── episodes/
│   └── 01-episode-slug/
│       ├── README.md      # episode metadata
│       ├── scenes/
│       │   ├── 01-intro.md
│       │   └── 02-step.md
│       └── assets/
├── assets/                # project-wide assets
└── research/              # sources, research

Individual skills create further files, for example brief.md, research/RESEARCH.md, research/AUDIENCE.md, episodes/.../assets/ASSETS.md, episodes/.../shot-list.md, promo/*.md and RELEASE.md. See Skills.

Episode directories and scene files are created with a two-digit number in front of the slug.

Frontmatter

Status lives in the YAML frontmatter of the Markdown files. The MCP server reads the project state from it.

Level	Fields
Project (`README.md`)	`title`, `slug`, `video_type`, `status`, `platform`, `language`, `target_audience`, `description`, `created`, `updated`
Episode (`episodes/*/README.md`)	`title`, `number`, `slug`, `status`, `duration_target`, `platform`, `avatar`, `description`
Scene (`scenes/*.md`)	`title`, `number`, `status`, `visual_type`, `duration`

Scene content sits in the sections ## Narration, ## On-Screen Text, ## Visual Direction and ## Assets. The Workflow page explains the status values.

State cache

The server builds a cache from the Markdown files at ~/.vidcraft/cache/state.json. The query tools read from it. Newly created files or files you edit by hand show up there only after a rebuild: /vidcraft:session-start or the rebuild_state tool. The Markdown files remain the authoritative source. More in Technical.