Explainer Video Maker

Explainer Video Maker

Automated pipeline for narration-driven explainer videos from any topic. Supports documentaries, knowledge sharing, news, data reports, product introductions, and any format suitable for narrated explanation.

Audio drives visuals: each section carries exactly one narration; its audio duration sets the narration's total frame count, which is split across the section's 1-N scenes by each scene's percentage.

Contents

• Prerequisites
• Project Management
• Execution Modes — Auto (default) vs Manual
• Workflow (14 Steps)
• Hard Rules
• References

Prerequisites

Resolve SKILL_DIR to the directory containing this SKILL.md.

SKILL_DIR="${SKILL_DIR:-${CLAUDE_SKILL_DIR}}"
python3 "${SKILL_DIR}/scripts/tool/check_prereqs.py"

External dependencies:

• Python >= 3.10; install the Python packages from ${SKILL_DIR}/requirements.txt (pip install -r "${SKILL_DIR}/requirements.txt"). The Playwright browser download (playwright install chromium) is needed ONLY in standalone environments — when PLAYWRIGHT_CDP_URL is set (e.g. the hermes-desktop container), Playwright attaches to the shared desktop Chromium over CDP and no download is required
• ffmpeg, ffprobe on PATH
• Node.js >= 18, npx
• The two component dependencies below (comfyui-scheduler, remotion-video-template) — installed under the workspace's dep/ directory
• A running ComfyUI server with default workflows imported

Installing the two component dependencies

comfyui-scheduler (the ComfyUI CLI) and remotion-video-template (the Remotion render backend) are separate repositories. Install them under the workspace's dep/ directory — i.e. dep/ inside the workspace root (the directory that contains projects/). Configs store these as workspace-relative paths (e.g. dep/remotion-video-template); the scripts resolve a relative path against the workspace at runtime. init_project.py pre-fills dependence_paths with these paths, so no manual path editing is normally needed.

Repository URLs:

• comfyui-scheduler — https://github.com/calcuforge/comfyui-scheduler.git
• remotion-video-template — https://github.com/calcuforge/remotion-video-template.git

# Run from the workspace root (the directory that contains projects/)
mkdir -p dep
git clone https://github.com/calcuforge/comfyui-scheduler.git dep/comfyui-scheduler
git clone https://github.com/calcuforge/remotion-video-template.git dep/remotion-video-template

pip install -e dep/comfyui-scheduler          # comfyui-scheduler CLI on PATH
( cd dep/remotion-video-template && npm install )   # node_modules

If the dependencies already exist somewhere else, set dependence_paths.remotion_template / dependence_paths.comfyui_scheduler in project_config.yaml to their paths (a ~-path, absolute, or relative to the workspace) instead of the dep/ default.

Project Management

All projects MUST live under the workspace projects/ directory.

Project directory naming: scripts/tool/init_project.py creates the project directory from the scripts/project_config_tpl.yaml template, named via its --project-dir-name argument. The project name is categorized across THREE dimensions (joined with _):

1. Content category (内容分类) — what the video is about: air_crash (空难事件), history (历史), tech (科技), hardware (硬件), ... Derive it from the user's topic.
2. Narrative structure (叙事结构) — how it is told: documentary (纪录片), knowledge_sharing (知识分享), news_broadcast (新闻播报), product_intro, data_report, tutorial, ...
3. Fine-grained parameters (细分参数) — include only what the user explicitly specified and is important: resolution (1080p/4k), orientation (horizontal/vertical), theme, language, target audience, ...

If the name already exists, a numeric suffix is appended automatically: air_crash_documentary_1080p_horizontal, air_crash_documentary_1080p_horizontal2, ...

Example: user asks "制作一个1080P横屏的空难纪录片" → content=air_crash, structure=documentary, params=1080p+horizontal → projects/air_crash_documentary_1080p_horizontal/. Check whether a project whose all three dimensions match already exists; if not, create a new one.

After creation, edit project_config.yaml to set project.name (the same categorized name, e.g. air_crash_documentary_1080p_horizontal), project.video_style, project.target_audience, and other request-dependent fields. project.name MUST be the categorized name — never the specific video title.

Video directory — never reuse. Every video-making request creates a NEW video{N}/ directory (video1, video2, ...). Each time the user asks to make a video, create the next available video{N}/; never reuse or overwrite an existing one. (Resuming an interrupted pipeline continues the same in-progress video{N}/ — that is recovery, not reuse.)

Project directory reuse (the table below is about the project dir, not the video dir):

To determine project reuse: compare ALL categorization dimensions — content category, narrative structure, and every explicitly-specified fine parameter (resolution, orientation, theme, language, target audience). Reuse only if every dimension matches. If the request maps to a different content category or structure, or adds/removes a fine parameter (e.g. 1080p vs 4K, horizontal vs vertical), create a new project — even when one dimension (e.g. documentary) is shared. Each video request still creates a fresh video{N}/ inside.

Project Output Layout

projects/
├── project1/
│   ├── project_config.yaml        # Project global preferences
│   ├── voice_file.wav             # TTS reference voice (shared by all videos)
│   ├── bgm.mp3                    # Background music (Step 11, shared by all videos)
│   ├── ad_video/                  # Ad short videos for Step 14 (pre-created, empty; drop ad files here)
│   ├── video1/
│   │   ├── result.mp4             # Final rendered video (Step 13)
│   │   ├── origin_result.mp4      # Step 14 — pre-insertion render, preserved when ads are inserted
│   │   ├── video_config.yaml      # Topic (Step 2) + content summaries (Step 5)
│   │   ├── video_struct.yaml      # Video structure (stories → sections (one narration) → scenes (1-N, percentage))
│   │   ├── video_tasks.yaml       # AIGC task list
│   │   ├── remotion_sections.yaml # Remotion render config
│   │   ├── tmp/                   # General temporary files (cache, discovery results, etc.)
│   │   ├── search_results/
│   │   │   ├── result1.md         # Research result 1
│   │   │   └── result2.md         # Research result 2
│   │   └── stories/
│   │       ├── story1/
│   │       │   ├── script.md      # Chapter narration script (Step 5)
│   │       │   └── narration1/
│   │       │       ├── speech.wav # Narration audio
│   │       │       └── scenes/
│   │       │           ├── video_prompt_{scene_id}.yaml  # Structured video prompt per scene (Step 8a)
│   │       │           ├── origin_scene1.png  # AIGC raw output
│   │       │           ├── scene1.png         # Upscaled asset
│   │       │           ├── origin_scene2.mp4
│   │       │           └── scene2.mp4
│   │       └── story2/
│   └── video2/
└── project2/

Detailed structure reference: templates/demo_projects/

Execution Modes

Auto Mode (default)

The agent makes all decisions autonomously across all 13 steps. No user interaction is required until the final video is ready. Infer sensible defaults from the user's request (language, style, audience, duration).

Manual Mode

The agent pauses for user confirmation at key points:

In manual mode, never proceed to the next step until the user explicitly confirms (e.g., "ok", "continue", "next", "确认", "继续").

人机协作的远程桌面栈（VNC/虚拟桌面/Chromium）: 人机协作仅发生在登录和 验证码场景（访问被登录墙/验证码墙拦住时，如搜索/页面抓取被要求登录、安全验证、 滑块验证）。其余环节全部由程序自动完成，无需也不应启动远程桌面栈。流程： 脚本/agent 遇到登录墙或验证码墙 → 报告被拦的 URL → python scripts/tool/ensure_remote_desktop.py start --url <被拦页面>（幂等，启动缺失服务， 经 CDP :9222 在共享 Chromium 打开该页）→ 提醒用户：优先 hermes channel 推送 （ensure_remote_desktop.py notify "<提醒内容>"，即 hermes send --to <平台> 推到 home channel；自动识别已配置平台——channel directory（hermes send --list）→ ~/.hermes/config.yaml platforms 段（优先有 home channel 的），可用 --to/HERMES_NOTIFY_TO 指定；退出码非 0 表示推送不可用/失败，报错会附修复提示 如 hermes config set <平台>_HOME_CHANNEL <id>）→ 推送失败才退回对话提醒 → 用户经 VNC 完成登录/验证： 提醒中的 VNC 地址一律运行脚本获取——取 ensure_remote_desktop.py start（或 status）JSON 输出的 vnc_viewer_url 字段（脚本优先输出环境变量 VNC_VIEWER_URL 的外网地址，未设置时回退容器本地 noVNC 地址），agent 不要自行 拼接地址 → 确认完成后脚本/agent 继续（搜索脚本经 CDP 使用共享 Chromium 的持久 profile——用户刚完成的登录/验证会被直接复用）→ 全部结束后 ... stop 关闭。 脚本同理：只有登录/验证码才需要协作，且在使用前后自行 start/stop、提醒同样推送 优先。机制：栈由 hermes-desktop 容器（镜像仓库 hermes-hitl-environment）内的 supervisord 按需管理（pulseaudio/xvfb/openbox/chromium/x11vnc/novnc，等价于 bash /scripts/launch-desktop.sh），start/stop 驱动 supervisorctl。

Mode Detection

• Step 1: project_config.yaml does not yet exist. If the user explicitly requests manual interaction ("I want to control each step", "interactive", "手动模式"), run Step 1 in manual mode (ask before creating the config). Otherwise default to auto. Write the chosen mode into project.creation_mode.
• Step 2 onwards: Read project.creation_mode from project_config.yaml to determine behavior. Do NOT rely on conversational memory — always re-read the field from the file.

Workflow

Detailed step-by-step instructions:

• Steps 1–4 (Setup): references/workflow-setup.md
• Steps 5–7 (Content): references/workflow-content.md
• Steps 8–14 (Production): references/workflow-production.md

Mandatory validation gates:

• After Step 1: verify_project_config.py must exit 0
• After Step 1: check_environment.py must exit 0 (ComfyUI + TTS nodes reachable — the ONLY way node availability is determined)
• After Step 4: verify_stories.py must exit 0 (re-do step if not)
• After Step 5: verify_story_scripts.py must exit 0
• After Step 6: verify_video_struct.py must exit 0
• After Step 7: verify_audio.py must exit 0
• After Step 8: verify_stock_assets.py must exit 0
• After Step 9: verify_video_tasks.py must exit 0
• After Step 10: verify_aigc_assets.py must exit 0
• After Step 11: run_bgm.py must exit 0 (skipped when bgm.enabled: false; fill bgm.prompt in project_config.yaml first — it is empty at init)
• After Step 12: verify_remotion_sections.py must exit 0, then verify_remotion_data.py must exit 0
• After Step 14: insert_ad_videos.py must exit 0 (skipped when ad_video.enabled: false or no ad videos found; for insert_position: middle fill ad_video.insert_after_story first), then RE-RUN the Step 13 render so result.mp4 includes the ads