# stream_recv_cli

Listens for an incoming TCP stream of `VIDEO_FRAME` protocol messages and displays the frames in an X11 window with a per-stream fps/Mbps overlay. Pair with [`stream_send_cli`](stream_send_cli.md) to test end-to-end video transport without a full node.

---

## Build

From the repository root:

```sh
make cli
```

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

Requires GLFW, OpenGL, and libjpeg-turbo.

---

## Usage

```sh
./stream_recv_cli [--port PORT] [--stream-id N]
                  [--scale stretch|fit|fill|1:1]
                  [--anchor center|topleft]
                  [--x N] [--y N]
```

| Option | Default | Description |
|---|---|---|
| `--port PORT` | `7700` | TCP port to listen on |
| `--stream-id N` | `0` | Filter by stream ID; `0` accepts any stream |
| `--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.

### Example

```sh
./stream_recv_cli --port 7700 --scale fit
```

### Statistics overlay

Updated every 0.5 seconds:

```
stream 1: 30.1 fps  18.3 Mbps
```

---

## Architecture note

The tool is multi-threaded: transport receive runs on a background thread and deposits frames into a shared slot (mutex + condition variable); the main thread owns the GLFW/OpenGL context and pulls from that slot on each render cycle. This is the same pattern used by the node's display sink.

---

## Relationship to the Video Routing System

`stream_recv_cli` tests the sink end of the display pipeline: `VIDEO_FRAME` receive → MJPEG decode → xorg render. The node's display sink (started via `START_DISPLAY`) performs the same operation, driven by the control channel.

See also: [`stream_send_cli.md`](stream_send_cli.md) for the send side; [`controller_cli.md`](controller_cli.md) to use the full node pipeline.