# startRecording

The `startRecording` command begins a screen recording of the test Flow. Use this command to collect visual evidence of your test runs, especially when debugging complex UI transitions or intermittently failing tests. The resulting video file is saved in `.mp4` format.

{% hint style="info" %}

#### Important considerations

* You must use the [`stopRecording`](https://docs.maestro.dev/reference/commands-available/stoprecording) command to finalize the video file. 
* The behavior and file location of recordings may differ slightly when running tests via Maestro Studio compared to the CLI.
  {% endhint %}

### Parameters

To use the `startRecording`, you can provide only the file name to be saved, or you can use all the following parameters:

| Parameter  | Type    | Description                                                                                                 |
| ---------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `path`     | string  | Specifies the file path for the recording, relative to the Flow file's directory.                           |
| `label`    | string  | **(Optional)** A descriptive label for the command step that appears in the test report.                    |
| `optional` | boolean | **(Optional)** If `true`, the command does not fail the test if it cannot be executed. Defaults to `false`. |

### Usage examples

#### Basic usage

This example uses the shorthand syntax to start a recording that will be saved as `recording.mp4`.

```yaml
appId: yourAppId
---
- launchApp
- startRecording: recording
- stopRecording
```

You need to use the [`stopRecording`](https://docs.maestro.dev/reference/commands-available/stoprecording) command to instruct Maestro to stop recording the device screen.

#### Custom path and labels

This example uses the expanded syntax to specify a directory, a descriptive label for the reports, and marks the command as optional to ensure the test continues even if the video engine fails to start.

```yaml
- startRecording:
    path: "recordings/user_onboarding"
    label: "Capture onboarding sequence for evidence"
    optional: true
```

### Related commands

* [stoprecording](https://docs.maestro.dev/reference/commands-available/stoprecording "mention")