First capture

Cappy needs Node.js 24+, an instrumented game, FFmpeg/ffprobe, and OBS Studio 28+ with its WebSocket server enabled. Godot games use the included Godot 4.x addon. Cappy does not install these system applications or create OBS scenes.

Install

npm install --save-dev @uppercut-labs/cappy
npx cappy --version

Only run npx cappy after installing the scoped dependency. For one-shot use, run npx @uppercut-labs/cappy instead.

For Godot, copy node_modules/@uppercut-labs/cappy/addons/cappy/ to your game's addons/cappy/, then enable Cappy in Project Settings > Plugins. Register your scenario using the Godot guide.

Configure

Create cappy.config.json in the game project. Replace the example game directory and scene name with your actual configuration:

{
  "schemaVersion": 1,
  "project": { "id": "my-game", "name": "My Game" },
  "game": { "command": "godot", "args": ["--path", "/absolute/path/to/my-game"] },
  "adapter": { "port": 0 },
  "obs": { "url": "ws://127.0.0.1:4455", "passwordEnv": "CAPPY_OBS_PASSWORD", "scene": "Capture" },
  "presets": { "master-only": {} },
  "defaultPreset": "master-only"
}

Set CAPPY_OBS_PASSWORD privately in your shell. Omit passwordEnv only if OBS authentication is off. Add .cappy/ to .gitignore.

In OBS, create the named scene and a source showing only the intended game. Finish any first-run permission or setup dialogs. On macOS, allow Screen Recording when your source needs it.

Check and record

npx cappy doctor --json
npx cappy scenarios --json

Fix every failed check. scenarios launches the game and returns the actual names and parameter schemas. Run one of those scenarios with npx cappy run, followed by its name. Add --param key=value only for parameters the scenario exposes.

For freeform replay, record a bounded session, then use the returned session ID:

npx cappy record --duration 10 --json
npx cappy replay <session-id> --no-capture --json
npx cappy replay <session-id> --json

The last command records through OBS. A successful capture reports data.state: succeeded and leaves a master plus manifest.json under .cappy/captures/<capture-id>/. Repeating a capture allocates the next take; existing takes are never overwritten. Ctrl+C cancels and stops a recording Cappy started.

Only freeform sessions made by record can be replayed. A scenario session from run has no replay payload.

Without OBS

You can inspect scenarios and verify replay --no-capture. That verifies playback, not recording. macOS and Windows have historical real-OBS acceptance; Linux real-OBS capture remains unverified. See host acceptance.

Read Markdown