DemoFlow

Project config

demoflow.config.json sits at the root of your project. It is data, never code. Only baseUrl is required.

{
  "baseUrl": "http://localhost:3000",
  "allowedOrigins": ["http://localhost:3000"],
  "devCommand": {
    "command": "npm",
    "args": ["run", "dev"],
    "readyUrl": "http://localhost:3000",
    "timeoutMs": 60000
  },
  "artifactsDir": "demo-artifacts",
  "render": {}
}
KeyMeaning
baseUrlWhere your app runs. Scenario paths are relative to it.
allowedOriginsThe origins a run may visit, as bare origins such as https://example.com. The origin of the run's base URL is always one of them.
devCommandHow to start your app. See below.
artifactsDirWhere runs are written, relative to the project root.
fragmentsDirWhere the fragments scenarios include live, relative to the project root. Default demoflow/fragments.
renderHow the video looks. See below.

--base-url on demoflow run overrides baseUrl for one run.

Starting your app

With a devCommand, demoflow run and demoflow record start your app themselves, wait until readyUrl answers, and stop it when they finish. Any HTTP answer below 500 counts as up. If the app exits early, or does not answer within timeoutMs, the command fails and tells you which.

If readyUrl already answers, that app is used as is and never stopped. demoflow run --fresh-app refuses instead, with exit 2 and app-already-running: on stderr, whatever the status of the answer.

Ports: ${PORT} and ${BASE_URL}

To run several copies of an app at once, each on its own port, let the config follow the port of the run:

{
  "baseUrl": "http://127.0.0.1:${PORT:-3000}",
  "devCommand": {
    "command": "npx",
    "args": ["vite", "--port", "${PORT}", "--strictPort"],
    "readyUrl": "${BASE_URL}/"
  }
}
TemplateAllowed inValue
${PORT}baseUrl, devCommand.command, each devCommand.args entry, devCommand.readyUrl--port, else PORT from the environment, else the default.
${PORT:-3000}the same3000 when neither --port nor PORT gives a port.
${BASE_URL}devCommand.command, args, readyUrl--base-url, else baseUrl once filled. Never read from the environment.
$${anywhereA literal ${, e.g. "sh", "-c", "echo $${HOME}".

Any other name, such as ${HOME}, is an error, and so is ${ in allowedOrigins or artifactsDir. demoflow run and demoflow record need a port for every ${PORT}; check, list, runs and render load the config without one. Whenever a port is used, it is also set as PORT in the app's environment, which Next.js, Vite-based and Express apps read.

Two checkouts of the same app, started at the same time:

(cd checkout-a && npx demoflow run demoflow/tour.demo.json --port 4101 --fresh-app)
(cd checkout-b && npx demoflow run demoflow/tour.demo.json --port 4102 --fresh-app)

Each starts its own app on its own port and records it. Prefer a dev command that fails when its port is taken, like vite --strictPort: an app that grabs the port after the --fresh-app check then fails the start instead of being recorded.

devCommand runs without a shell on every OS, and DemoFlow fills each argument itself, so the same config works on Linux, macOS and Windows. A filled value stays one argument. %PORT% and $PORT are passed as literal text: write ${PORT}.

Artifacts

Runs are written to <home>/runs/<id>/. The home is the first of: --out, the DEMOFLOW_HOME environment variable, artifactsDir in the project config, artifactsDir in the global config.json, and the OS data directory.

Render

Every render key is optional. These are the defaults:

KeyDefaultMeaning
width, height1920, 1080The video size in pixels.
fps30Frames per second.
idle.thresholdMs1000A still stretch longer than this is shortened.
idle.compressToMs400…to this long.
endHoldMs2500How long a successful video stays on screen after the last step, 0 to 10000 ms. The run records it, so a result that shows late is in the video. A failed run ends at the failure. To hold after any step, see hold.
frameonSee below.
background{ "preset": "ocean" }See below.
cardssee belowIntro, scene and outro cards.
transitionsonDissolves.
formats["mp4"]The files to render.
gif800 px, 12 fpsThe GIF's own size and rate.
verticalsee belowThe 9:16 crop of the *-vertical formats.
squaresee belowThe 1:1 crop of the *-square formats.

Frame

The page is drawn in a rounded, shadowed window on the background.

{ "render": { "frame": { "enabled": true, "marginRatio": 0.06, "radius": 12, "shadow": true } } }

enabled: false renders the page full-bleed. marginRatio is the margin on every side as a share of the video height (under 0.25). radius is in pixels at 1080p and scales with the output.

Background

One of a preset, a solid colour, or a two-stop gradient. Images are not supported.

{ "render": { "background": { "preset": "sunset" } } }
{ "render": { "background": { "color": "#1e3a5f" } } }
{ "render": { "background": { "gradient": { "from": "#1e3a5f", "to": "#0b2e4f", "angle": 90 } } } }

The presets are ocean, sunset, forest, dusk, graphite and paper. angle is in degrees as in CSS linear-gradient: 0 runs towards the top, clockwise.

Cards

Cards are full-screen titles between the page frames.

{
  "render": {
    "cards": {
      "intro": { "enabled": true, "durationMs": 2000 },
      "scenes": { "enabled": true, "durationMs": 1500 },
      "outro": { "title": "Try DemoFlow", "cta": "example.com/signup", "durationMs": 2500 }
    }
  }
}

Transitions

A dissolve between a card and the page.

{ "render": { "transitions": { "enabled": true, "durationMs": 300 } } }

durationMs is 100 to 1000 and at most half the shortest card that is on. The default is 300, or half the shortest card when that is less.

Output formats

A run renders an MP4 by default. formats asks for more, all encoded in one pass, each at most once:

FormatFile
mp4render/ffmpeg.mp4
gifrender/ffmpeg.gif
webm (VP9)render/ffmpeg.webm
mp4-verticalrender/ffmpeg.vertical.mp4
gif-verticalrender/ffmpeg.vertical.gif
webm-verticalrender/ffmpeg.vertical.webm
mp4-squarerender/ffmpeg.square.mp4
gif-squarerender/ffmpeg.square.gif
webm-squarerender/ffmpeg.square.webm
{
  "render": {
    "formats": ["mp4", "gif"],
    "gif": { "width": 800, "fps": 12 }
  }
}

The GIF's width may not exceed render.width, nor its fps render.fps; its height follows the video's aspect ratio. demoflow run --format gif --format mp4 replaces formats for one run.

Vertical video

The *-vertical formats are 9:16 videos for phones, rendered from the same run. mp4-vertical and webm-vertical are 1080×1920. gif-vertical is a GIF whose height is render.gif.width and whose width is round(height × 9 / 16): 450×800 by default. It uses render.gif.fps. Ask for any mix of them.

The page is still recorded at its normal size. A 9:16 crop follows each step's target and stays on the page. Each step's zoom still applies inside it, and captions sit larger in a band at the bottom. render.vertical tunes it, all optional, and is used only when formats has a *-vertical format:

{
  "render": {
    "formats": ["mp4", "mp4-vertical"],
    "vertical": { "followMs": 400, "deadZone": 0.1, "captionBand": 0.22 }
  }
}
KeyDefaultMeaning
followMs400How long the crop takes to move to the next target, eased in and out. 0 to 2000.
deadZone0.1A move shorter than this share of the crop width is skipped, so the camera does not jitter. 0 up to, not including, 0.5.
captionBand0.22The share of the frame height, at the bottom, that captions sit in. Above 0, at most 0.5.

Square video

The *-square formats are 1:1 videos, the size of feed posts, rendered from the same run. mp4-square and webm-square are 1080×1080. gif-square is a GIF whose side is round(render.gif.width × 3 / 4): 600×600 by default, the pixels of the landscape GIF. It uses render.gif.fps. Ask for any mix of landscape, vertical and square files.

The square crop works like the vertical one, with its own camera: it follows each step's target, stays on the page, honours zoom, and captions sit in a band at the bottom, cut to two lines. render.square takes the same three fields as render.vertical, with the same ranges and defaults, tunes the square crop alone, and is used only when formats has a *-square format:

{
  "render": {
    "formats": ["mp4", "mp4-vertical", "mp4-square", "gif-square"],
    "square": { "followMs": 400, "deadZone": 0.1, "captionBand": 0.22 }
  }
}
KeyDefaultMeaning
followMs400How long the crop takes to move to the next target, eased in and out. 0 to 2000.
deadZone0.1A move shorter than this share of the crop width is skipped. 0 up to, not including, 0.5.
captionBand0.22The share of the frame height, at the bottom, that captions sit in. Above 0, at most 0.5.