# v4l2_view_cli

A live camera viewer. Opens a V4L2 capture device, selects the best available format, and displays the video stream in an X11 window with a real-time FPS and format overlay. Bypasses the node system entirely — useful for verifying a camera works before wiring it into a node.

---

## Build

From the repository root:

```sh
make cli
```

The binary is placed in `build/cli/`.

Requires GLFW, OpenGL, libjpeg-turbo, and a V4L2-capable kernel.

---

## Usage

```sh
./v4l2_view_cli [--device PATH]
                [--width N --height N]
                [--format mjpeg|yuyv]
                [--scale stretch|fit|fill|1:1]
                [--anchor center|topleft]
                [--x N] [--y N]
```

| Option | Default | Description |
|---|---|---|
| `--device PATH` | `/dev/video0` | V4L2 device to open |
| `--width N` | auto | Capture width; if omitted, selects highest-FPS mode |
| `--height N` | auto | Capture height |
| `--format` | auto | Prefer `mjpeg` or `yuyv`; auto selects best available |
| `--scale` | `fit` | Frame scaling in window |
| `--anchor` | `center` | Frame alignment in window |
| `--x N` | `0` | Window X position |
| `--y N` | `0` | Window Y position |

Press **Q** or **Escape** to close the window.

### Auto format selection

Without `--width`/`--height`, the tool selects the format with the highest frame rate, and within that the largest resolution. This is the same logic the node's ingest module uses.

### Overlay

Every 0.5 seconds the overlay updates with:

```
MJPEG 1280x720 @ 30.0 fps
```

### Example

```sh
./v4l2_view_cli --device /dev/video0 --scale fit
```

---

## Relationship to the Video Routing System

`v4l2_view_cli` is a standalone sanity-check tool. It exercises the same V4L2 format enumeration, mmap capture, MJPEG decode, and xorg rendering path that the node's ingest + display pipeline uses — but without any transport or protocol overhead.

See also: [`stream_send_cli.md`](stream_send_cli.md) to capture and send over the network; [`xorg_cli.md`](xorg_cli.md) for static test patterns.