Skip to content

Prerequisites

What needs to exist before the first render.

Most of this is what you would expect from a Remotion and Playwright project. The two items in the silent failures section are the ones that actually cost people an afternoon, because neither of them raises an error.

The whole checklist, copy and paste

Everything below in one block. It checks what you already have before installing anything, because most machines are already most of the way there. Pick your platform.

Windows, PowerShell
# 1. Check what you already have
node --version        # need 18 or newer
ffmpeg -version       # need 4.0 or newer

# 2. Install whatever was missing. Reopen the terminal after ffmpeg,
#    winget only puts it on PATH for new shells.
winget install --id Gyan.FFmpeg -e
npm install playwright && npx playwright install chromium
pip install edge-tts  # narration, optional

# 3. Start the app you want to film, then ask your agent:
#    "run preflight against http://localhost:3000"
macOS, Homebrew
# 1. Check what you already have
node --version        # need 18 or newer
ffmpeg -version       # need 4.0 or newer

# 2. Install whatever was missing
brew install ffmpeg
npm install playwright && npx playwright install chromium
pip install edge-tts  # narration, optional

# 3. Start the app you want to film, then ask your agent:
#    "run preflight against http://localhost:3000"
Linux, Debian or Ubuntu
# 1. Check what you already have
node --version        # need 18 or newer
ffmpeg -version       # need 4.0 or newer

# 2. Install whatever was missing
sudo apt update && sudo apt install -y ffmpeg
npm install playwright && npx playwright install chromium
pip install edge-tts  # narration, optional

# 3. Start the app you want to film, then ask your agent:
#    "run preflight against http://localhost:3000"

Required

  • Node.js 18 or newer

    The one version preflight enforces numerically. npx ships with it, and npx is how the server gets fetched. pnpm is only for building openvidstudio itself from a clone.

  • An MCP capable agent

    Claude Code, Cursor, or any client that reads a standard mcpServers config block. This is the only interface openvidstudio has.

  • Playwright 1.48 or newer, plus Chromium

    The capture tools drive a real browser. The playwright dependency downloads Chromium on install; if that step was skipped, capture fails at the first screenshot.

  • ffmpeg 4.0 or newer

    Used to pull QC frames back out of a render, and to synthesize the sound effect pack with scripts/gen-sfx.sh. Not version checked, but every filter the pipeline uses has been in ffmpeg since the 3.x era.

  • Your app, running

    Capture points a browser at a real URL. If there is nothing serving, there is nothing to film.

Optional

  • edge-tts, or another text to speech source

    The default narration engine, installed with pip and needing Python 3.8 or newer. Preflight treats it as non-blocking, so a render still succeeds without it and simply plays silent. Anything that can write an mp3 per beat works instead.

  • A Higgsfield subscription

    Only for the b roll tier, and only for shots with no product UI in them. Your subscription, your MCP connection.

  • A music bed

    Dropped at public/audio/music-bed.mp3 if you want one.

Two things that fail silently

Neither of these throws. Both produce a video that renders successfully and is quietly wrong, which is worse than a crash.

Narration is skipped, not reported

stitch_composition looks for public/audio/vo/<beatId>.mp3 for every beat. If a file is not at exactly that path it skips the audio layer with no error and no warning. A video missing three of its five narration files renders fine and simply plays silent in those beats. Check the files are on disk before stitching.

Asset paths are fixed

Screenshots go to public/images/<beatId>.png and recordings and imported clips to public/video/<beatId>.mp4. Put an asset somewhere else and the scene references a file that resolves to nothing at render time.

On Windows

  • npx remotion skills add fails with spawn EINVAL. Run npx -y skills@1.2.0 add remotion-dev/skills instead.
  • A render that dies on a webpack wasm-hash error usually clears by deleting node_modules/.cache and retrying.
  • Run npm and pnpm commands from the project's own directory. Some agent harnesses reset the working directory between tool calls.

Once that is all set

Add the server to your MCP client config and restart it. npx fetches the package on first run, so this is the whole install.

mcp.json
{
  "mcpServers": {
    "openvidstudio": {
      "command": "npx",
      "args": ["-y", "@openvidstudio/mcp-server"]
    }
  }
}
Configure the serverRead PIPELINE.md