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": {}
}
| Key | Meaning |
|---|---|
baseUrl | Where your app runs. Scenario paths are relative to it. |
allowedOrigins | The 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. |
devCommand | How to start your app. See below. |
artifactsDir | Where runs are written, relative to the project root. |
fragmentsDir | Where the fragments scenarios include live, relative to the project root. Default demoflow/fragments. |
render | How 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}/"
}
}
| Template | Allowed in | Value |
|---|---|---|
${PORT} | baseUrl, devCommand.command, each devCommand.args entry, devCommand.readyUrl | --port, else PORT from the environment, else the default. |
${PORT:-3000} | the same | 3000 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. |
$${ | anywhere | A 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:
| Key | Default | Meaning |
|---|---|---|
width, height | 1920, 1080 | The video size in pixels. |
fps | 30 | Frames per second. |
idle.thresholdMs | 1000 | A still stretch longer than this is shortened. |
idle.compressToMs | 400 | …to this long. |
endHoldMs | 2500 | How 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. |
frame | on | See below. |
background | { "preset": "ocean" } | See below. |
cards | see below | Intro, scene and outro cards. |
transitions | on | Dissolves. |
formats | ["mp4"] | The files to render. |
gif | 800 px, 12 fps | The GIF's own size and rate. |
vertical | see below | The 9:16 crop of the *-vertical formats. |
square | see below | The 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 }
}
}
}
- The intro shows the scenario's
nameanddescription. - A scene card appears at every
markerstep withkind: "scene". - The outro is off unless it has a
title;ctaadds a second line, such as a URL. Text is 1 to 80 characters. - A duration is 500 to 10000 ms.
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:
| Format | File |
|---|---|
mp4 | render/ffmpeg.mp4 |
gif | render/ffmpeg.gif |
webm (VP9) | render/ffmpeg.webm |
mp4-vertical | render/ffmpeg.vertical.mp4 |
gif-vertical | render/ffmpeg.vertical.gif |
webm-vertical | render/ffmpeg.vertical.webm |
mp4-square | render/ffmpeg.square.mp4 |
gif-square | render/ffmpeg.square.gif |
webm-square | render/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 }
}
}
| Key | Default | Meaning |
|---|---|---|
followMs | 400 | How long the crop takes to move to the next target, eased in and out. 0 to 2000. |
deadZone | 0.1 | A move shorter than this share of the crop width is skipped, so the camera does not jitter. 0 up to, not including, 0.5. |
captionBand | 0.22 | The 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 }
}
}
| Key | Default | Meaning |
|---|---|---|
followMs | 400 | How long the crop takes to move to the next target, eased in and out. 0 to 2000. |
deadZone | 0.1 | A move shorter than this share of the crop width is skipped. 0 up to, not including, 0.5. |
captionBand | 0.22 | The share of the frame height, at the bottom, that captions sit in. Above 0, at most 0.5. |