> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# Record (detailed)

> Reference for the `Record (detailed)` schema.

## Referenced In

* [record](/reference/schemas/record)

## Fields

| Field       | Type                                                                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Default |        |                     |   |
| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ | ------ | ------------------- | - |
| surface     | one of: - string - object([Browser surface](/reference/schemas/browser-surface)) - object([App surface](/reference/schemas/app-surface)) | Optional. The browser window/tab or app window to record. Omit to record the active surface. The targeted surface stays focused afterward. App surfaces use the object form (\{ "app": … }) and are captured via the `ffmpeg` engine, cropped to the app window by default.                                                                                                                                                                                                                                                                             | —       |        |                     |   |
| path        | string                                                                                                                                   | Optional. File path of the recording. Supports the `.mp4`, `.webm`, and `.gif` extensions. If not specified, the file name is the ID of the step, and the extension is `.mp4`. Pattern: \`(\[A-Za-z0-9\_-]\*.(mp4                                                                                                                                                                                                                                                                                                                                       | webm    | gif)\$ | $\[A-Za-z0-9\_]+)\` | — |
| directory   | string                                                                                                                                   | Optional. Directory of the file. If the directory doesn't exist, creates the directory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | —       |        |                     |   |
| overwrite   | string                                                                                                                                   | Optional. If `true`, overwrites the existing recording at `path` if it exists. If `false`, skips the recording when the file already exists. If `aboveVariation`, always records, but replaces the existing file (and its checkpoint baselines) only when the span's checkpoint screenshots show it meaningfully changed — requires `checkpoints`, so it turns them on with defaults when `checkpoints` is omitted or `false`; set `checkpoints` to an object to tune `maxVariation` or `directory`. Accepted values: `true`, `false`, `aboveVariation` | —       |        |                     |   |
| name        | string                                                                                                                                   | Optional. Identifier for this recording. A later `stopRecord` step can target it by name (`stopRecord: "<name>"`), which is how you stop a specific recording when several overlap. Names must be unique among recordings that are active at the same time. If omitted, the recording is anonymous and is stopped LIFO by an untargeted `stopRecord`. Pattern: `\S`                                                                                                                                                                                     | —       |        |                     |   |
| engine      | one of: - string - object([Recording engine (detailed)](/reference/schemas/recording-engine-detailed))                                   | Optional. Recording engine to use. Either a string shorthand selecting the engine with defaults, or an object for full control. If unset, defaults to the `browser` engine when a visible Chrome context is available and to `ffmpeg` otherwise.                                                                                                                                                                                                                                                                                                        | —       |        |                     |   |
| verify      | object([Recording verify guards](/reference/schemas/recording-verify-guards))                                                            | Optional. Structural assertions on the produced video file, evaluated when the recording stops. Unlike checkpoint drift (a WARNING), a violated guard FAILs the stopRecord step — these are properties you explicitly demand of the artifact.                                                                                                                                                                                                                                                                                                           | —       |        |                     |   |
| checkpoints | one of: - boolean - object([Recording checkpoints (detailed)](/reference/schemas/recording-checkpoints-detailed))                        | Optional. Capture a checkpoint screenshot after every step while this recording is active and compare each against a persistent baseline stored beside the recording (`<path>.checkpoints/` by default). Baselines seed on the first run; on later runs, per-checkpoint variation is reported in the `stopRecord` step's outputs, and variation beyond `maxVariation` surfaces as a WARNING. If `false` or unset, no checkpoints are captured.                                                                                                          | —       |        |                     |   |

## Examples

```json
{
  "surface": "chrome",
  "path": "example",
  "directory": "example",
  "overwrite": "true",
  "name": "example",
  "engine": "browser",
  "checkpoints": true
}
```