> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowdeck.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Frames

> Capture simulator frames as a contact sheet or individual images

Capture simulator frames with `simulator frames` — either a single **contact-sheet PNG** (default) or **individual full-resolution images** (`--images`).

It records a short video, then either tiles every sampled frame (scaled to 30%, with a timestamp under each cell) into one PNG, or writes one full-resolution PNG per frame into a folder. Ideal for validating an animation — for example driving the simulator from the home screen into an app.

```bash theme={null}
# Show usage examples
flowdeck simulator frames --examples
```

## Contact sheet (default)

```bash theme={null}
# 3 seconds, 5 fps, 4 columns → one PNG on ~/Desktop
flowdeck simulator frames

# Denser sampling
flowdeck simulator frames --duration 2s --fps 10

# Wider grid, specific simulator
flowdeck simulator frames --columns 6 -S "iPhone 16"
```

## Individual images (`--images`)

```bash theme={null}
# Full-resolution PNG per frame, written into a folder
flowdeck simulator frames --images --duration 2s --fps 12 --output ~/Desktop
```

## Options

| Option                | Short | Description                                                                  |
| --------------------- | ----- | ---------------------------------------------------------------------------- |
| `--output <folder>`   | `-o`  | Output folder (default `~/Desktop`); names are generated automatically       |
| `--simulator <sim>`   | `-S`  | Simulator name or UDID (defaults to the booted simulator)                    |
| `--duration <Ns>`     | `-t`  | Recording duration, e.g. `2s` (default `3s`)                                 |
| `--fps <n>`           |       | Frames per second to sample (default 5)                                      |
| `--columns <n>`       |       | Grid columns in the contact sheet (default 4)                                |
| `--images`            |       | Output full-resolution images (one PNG per frame) instead of a contact sheet |
| `--display <display>` |       | Display to capture when multiple are attached: `internal` or `external`      |
| `--json`              | `-j`  | Output as JSON (includes `mode` and `frame_count`)                           |
| `--verbose`           | `-v`  | Show detailed output                                                         |
| `--examples`          | `-e`  | Show usage examples                                                          |

<Note>
  `--output` is a folder. The contact sheet scales frames to 30% of native size; `--images` writes them at full resolution.
</Note>