Skip to main content
Glama
Sign In
demo-vid-mcp

demo-vid-mcp

by sandraschi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

demo-vid-mcp

Demo video pipeline for fleet repos. Records narrated walkthroughs of any webapp by orchestrating Playwright, speech-mcp TTS, and FFmpeg composition — with real background music (songgeneration-mcp), sound effects (sfx-mcp), and crossfade/wipe transitions between pages (vfx-mcp).

Quick Install

uvx mcpb install sandraschi/demo-vid-mcp

Or grab the native Windows installer (Tauri desktop app, no Claude Desktop required) from Releases.

Related MCP server: screenwright

What You Can Do

  • Generate a video: demo_vid_generate(repo="chitchat") — auto-starts the target webapp, records it page-by-page, adds voiceover synced to true speech length, mixes in music/sfx, joins pages with real transitions, composes MP4

  • Or drive a native app live: demo_vid_generate(repo="blender-mcp", script_yaml=<desktop-capture script>) — OBS records a real app window (Blender, Resonite) while mcp_call steps actually invoke that app's own MCP server during the recording, not a staged screencast. See data/scripts/*.yaml for working examples and DEMO_VID_MCP_PLAN.md for the architecture.

  • Draft a script: demo_vid_script_draft(repo="chitchat") — reads the README and generates a narration script, with a per-page Skip/Show/Detail checklist (demo_vid_list_pages)

  • Narration that fits the picture: each page's dwell time is stretched to match its actual spoken length (not a fixed guess), so long lines never get cut off mid-sentence

  • Browse the depot: Categorized gallery of produced videos with inline player, subtitle tracks (.vtt), poster previews, rebuild, delete, and insert into repo README

  • Persistent queue: Background queue manager to schedule and track batch video generation across the fleet

  • Chat about it: Built-in chat with personalities, example prompts, and local LLM integration (Ollama/LM Studio)

Tools

Tool

Description

demo_vid_generate(repo, script_yaml?, base_url?, theme="dark", aspect_ratio="16:9", resolution="720p", page_config?, voice="heart", music_enabled=False, music_prompt?)

Full pipeline: voiceover (speech-mcp, wait-aligned to true speech length) → record page-by-page (Playwright with click ripples) → join pages with real transitions (vfx-mcp) or plain cuts → mix in background music (songgeneration-mcp) and timed sound effects (sfx-mcp, via action: sfx script steps) → compose (FFmpeg) → MP4 + WebVTT/SRT subtitles + poster image. Also auto-detects native desktop-capture mode via obs-mcp.

demo_vid_list_pages(repo)

List a repo's webapp pages with README-sourced purpose and default Skip/Show/Detail level, for building a page-selection checklist

demo_vid_script_draft(repo, page_config?)

Generate a narration YAML from the target repo's README and webapp page structure

demo_vid_script_validate(yaml)

Validate a narration script's structure, timing, aspect ratio, and resolution

demo_vid_list(repo?)

List produced videos with metadata, poster, and subtitle sidecar paths

demo_vid_refine(name, feedback)

Automatically parse user feedback and mutate YAML narration timing, voice, and steps

demo_vid_help

List all tools and usage information

demo_vid_shutdown

Gracefully terminate the server and background queue worker

Webapp

Page

Purpose

Dashboard

Backend status, KPI cards, dead port detection with one-click reconnect

Depot

Categorized gallery with HTML5 player, subtitle toggle, poster previews, rebuild, delete

Queue

Persistent background job queue manager with live polling, status badges, and cancel controls

Generate

Select target repo by category, per-page Skip/Show/Detail checklist, aspect ratio/resolution, draft YAML, and generate or queue

Choreography

Visual script builder — 11 step types (including timed sound effects and native transitions), global options, YAML preview

Speech

Voice picker (shared with Generate/Choreography), speech-mcp health, text-to-preview

Music

Background-music enable + mood/style prompt, songgeneration-mcp health, generate-and-preview

Chat

SOTA chat with personalities, localStorage, example prompts, LLM integration

Settings

LLM provider probe (Ollama/LM Studio), model selection, persistence

Logs

Ring-buffer log viewer with level filter and search

Help

6-tab reference: overview, architecture, tools, config, fleet, troubleshooting

Autostart

demo_vid_generate automatically starts the target repo's backend and Vite frontend before recording. Zombie-kills stale processes first. No manual setup — the pipeline scans for start.ps1 and webapp/ directories.

Themes

Recording is dark-mode by default (fleet identity). Pass theme="light" to record a bright demo — the capture script forces the target webapp's theme class (handles both .dark toggling and persisted localStorage light-mode keys) before navigation, per chat_skills_prefab_standard.md §7.1.

Fleet Services

Required: speech-mcp (voiceover), Playwright (recording), FFmpeg (composition). Optional: songgeneration-mcp (background music — Lyria/ACE-Step/Stable Audio/Studio, tried in order), sfx-mcp (timed sound effects, FreeSound CC0), vfx-mcp (real crossfade/wipe/slide transitions between pages — falls back to a plain cut when unavailable), blender-mcp (3D titles).

Desktop-capture mode (native apps driven live — see DEMO_VID_MCP_PLAN.md): windows-computer-use-mcp (window focus), obs-mcp (recording — window-capture and human-in-video), plus whichever MCP server the demo actually drives (blender-mcp, resonite-mcp, ...).

Ports

Backend: 11134, Frontend: 11135, speech-mcp: 10909, songgeneration-mcp: 10885, sfx-mcp: 11120, vfx-mcp: 11122. See WEBAPP_PORTS.md.

Documentation

Doc

Contents

Roadmap & Architecture

Desktop-capture mode design, the mcp_call step type, the real remaining constraint (no Resonite camera control), v0.3 plans

Installation

All install methods, prerequisites

Configuration

Env vars, config options

Tool Reference

All available tools

Development

Contributing, local setup

Troubleshooting

Common issues

Requirements

  • Python 3.13+ with uv

  • FFmpeg (for composition)

  • speech-mcp (for voiceover)

  • Playwright (for recording, auto-installed)

License

MIT

Available Tools

6 tools
demo_vid_generateA

Generate a demo video for a fleet repo.

Runs the full pipeline: validate script → voiceover (speech-mcp) → record (Playwright) → compose (FFmpeg). Stages run in parallel where possible. Output saved to data/videos/. theme="light" records the target webapp with its light-mode toggle forced on (bright demo); default "dark" matches fleet identity.

Return Format

{"success": bool, "message": str, "video_path": str | None, "stages": {...}}

Examples

await demo_vid_generate(repo="chitchat") await demo_vid_generate(repo="chitchat", theme="light") await demo_vid_generate(repo="chitchat", base_url="http://127.0.0.1:10975")

Inputs: repo (required), theme, base_url, script_yaml. Returns: object

demo_vid_helpA

List all available demo-vid-mcp tools and their purpose.

Return Format

{"success": bool, "tools": [{"name": str, "description": str}], "message": str}

Inputs: no named parameters. Returns: object

demo_vid_listB

List produced demo videos with metadata.

Scans the local data/videos/ directory for .mp4 files and returns file name, size, and creation date for each.

Return Format

{"success": bool, "videos": [{"name": str, "repo": str, "size_kb": int, "created": str}], "count": int}

Examples

await demo_vid_list() await demo_vid_list(repo="chitchat")

Inputs: repo. Returns: object

demo_vid_refineA

Re-generate a video with timing or narration adjustments.

[RATIONALE] This tool is a stub — refinement requires LLM-driven script mutation which is not yet implemented. It returns a helpful message pointing to the working alternative (demo_vid_generate with an updated script).

Return Format

{"success": False, "error": str, "suggestions": list}

Examples

await demo_vid_refine(video_name="chitchat-final", feedback="Make step 2 narration longer")

Inputs: feedback (required), video_name (required). Returns: object

demo_vid_script_draftA

Draft a default narration script for a repo.

Generates a placeholder YAML script that can be edited and passed to demo_vid_generate.

Return Format

{"success": bool, "script": dict, "message": str}

Examples

await demo_vid_script_draft(repo="chitchat")

Inputs: repo (required). Returns: object

demo_vid_script_validateA

Validate a narration script for structure and timing.

Checks that the script has required fields ('steps'), each step has an 'action',
and timing values are reasonable.

## Return Format
{"success": bool, "message": str, "errors": list | None}

## Examples
await demo_vid_script_validate(script_yaml="title: Test

duration_target: 30 steps:

  • action: goto url: / wait: 2 ")

Inputs: script_yaml (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: help lists tools, generate creates videos, list shows existing videos, refine is for adjustments (stub), script_draft creates scripts, script_validate checks them. No overlap or ambiguity.

    Naming Consistency5/5

    All tools follow a consistent 'demo_vid_<verb>' pattern (help, generate, list, refine) with compound names for script operations (script_draft, script_validate) adhering to the same convention. No mixing of styles.

    Tool Count5/5

    With 6 tools covering help, generation, listing, refinement, and script drafting/validation, the count is well-scoped for a focused demo video generation server. No unnecessary tools, and each serves a clear role.

    Completeness4/5

    Core operations are covered: create (generate), read (list), and script management (draft/validate). However, the refine tool is a stub (non-functional), effectively missing a working update operation, and there is no delete tool. This leaves minor gaps but the main workflow is intact.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers