Video Explainer

---
name: video-explainer
description: Teaches Claude how to use the video explainer tools to create explainer videos from research content. Activates when working with video synthesis, explainer creation, or the video-explainer MCP server.
---

# Video Explainer MCP — Tool Usage Guide

First verify that the optional `video-explainer-mcp` server is connected and `EXPLAINER_PATH` points to the external checkout. It wraps the [video_explainer](https://github.com/prajwal-y/video_explainer) CLI to synthesize explainer videos from text content.

## Core Concept

This server is a **synthesis** companion to `video-research-mcp`. Research extracts knowledge; this server turns it into video. The pipeline is: content → script → narration → scenes → voiceover → storyboard → render.

## Tool Selection Guide

| I want to... | Use this tool |
|---|---|
| Create a new video project | `explainer_create` |
| Feed content into a project | `explainer_inject` |
| Check project progress | `explainer_status` |
| List all projects | `explainer_list` |
| Run the full pipeline | `explainer_generate` |
| Run one pipeline step | `explainer_step` |
| Preview render (blocking) | `explainer_render` |
| Start background render | `explainer_render_start` |
| Check render progress | `explainer_render_poll` |
| Generate short-form video | `explainer_short` |
| Improve a step's output | `explainer_refine` |
| Add iterative feedback | `explainer_feedback` |
| Request a script fact-check report | `explainer_factcheck` |
| Add sound effects | `explainer_sound` |
| Add background music | `explainer_music` |

## Pipeline Order

Steps must run in order. Each step depends on the previous step's output:

```
1. script      — Generate video script from input content
2. narration   — Convert script to narration text
3. scenes      — Generate scene descriptions
4. voiceover   — Synthesize speech audio (TTS)
5. storyboard  — Create visual storyboard
6. render      — Combine into final video
```

Use `explainer_generate` to run all steps, or `explainer_step` for one at a time.

## Content Injection

Before running the pipeline, inject content:

```
explainer_create(project_id="quantum-computing")
explainer_inject(
    project_id="quantum-computing",
    content="# Quantum Computing\n\nKey concepts:\n- Superposition...",
    filename="research.md"
)
```

Content can be:
- Research output from `research_deep`
- Video analysis from `video_analyze`
- Any markdown or plain text

## Background Render Pattern

For long renders (1080p, 4K), use the start/poll pattern:

```
# Start render in background
result = explainer_render_start(project_id="my-video", resolution="1080p", fast=False)
job_id = result["job_id"]

# Poll every 30 seconds
status = explainer_render_poll(job_id=job_id)
# Inspect status, playable, and errors; preserve cancelled, partial, and unknown results
```

## Quality Iteration Loop

After generating the pipeline:

1. `explainer_factcheck(project_id)` — Inspect the report and check decisive claims against primary sources
2. `explainer_feedback(project_id, "Make the intro more engaging")` — Add notes
3. `explainer_refine(project_id, phase="script")` — Improve specific phase
4. Re-run dependent steps: `explainer_generate(project_id, from_step="narration")`

## TTS Provider Selection

The external `video_explainer` CLI owns provider implementations and model settings. This wrapper passes the selected provider; inspect that checkout before assuming current model/endpoint compatibility.

| Provider | Verification needed |
|---|---|
| `mock` | Preview/testing only; inspect placeholder audio |
| `elevenlabs` | Credential, voice/model compatibility, timing, and current pricing |
| `edge` | Upstream support and authentication; not a guaranteed production path |

Set via `EXPLAINER_TTS_PROVIDER` in `~/.config/video-research-mcp/.env`. The wrapper accepts only `mock`, `elevenlabs`, and `edge`; other values fail configuration validation.

## ElevenLabs Voice Settings

Set `ELEVENLABS_API_KEY` locally. The checked upstream `tts:` configuration exposes `provider`, `voice_id`, `model`, and `output_format`. Its ElevenLabs requests hard-code stability `0.5` and similarity boost `0.75`; they do not read the voice/stability/speed environment variables formerly listed here. Inspect the selected external checkout before assuming additional voice controls. For direct HTTP settings, use the TTS production skill.

## Production Order Documents

For complex videos, create a POD (Production Order Document) first — a structured blueprint with script, storyboard, audio direction, and visual specs. PODs live in `docs/plans/` and can be used as input via `/ve:explainer` → "From a Production Order".

## Error Handling

All tools return error dicts on failure:
```json
{
  "error": "description",
  "category": "SUBPROCESS_FAILED",
  "hint": "actionable fix",
  "retryable": false
}
```

Common categories:
- `EXPLAINER_NOT_FOUND` — Set `EXPLAINER_PATH`
- `PROJECT_NOT_FOUND` — Check project ID with `explainer_list`
- `NODE_NOT_FOUND` — Install Node.js 20+
- `FFMPEG_NOT_FOUND` — Install FFmpeg
- `TTS_FAILED` — Check TTS provider and API key
- `RENDER_FAILED` — Check Remotion installation

## Completion gate

A completed pipeline step or render job is not a verified video. Inspect the actual output file, duration, dimensions, frame rate, required shots, narration, and transitions. Mock TTS is a preview limitation. Keep source claims/citations through synthesis, and fact-check decisive claims against primary material. Allow one targeted repair per observed defect inside the generation budget; preserve failed/refused/missing outputs and stop on repeated infrastructure failure. Return the exact playable artifact and remaining limitations.