Skip to main content

7.1 visio-display CLI

visio-display is installed with the visio-schema package (use the [display] extra). It takes one data source plus at least one output. Prebuilt bundles for Windows, macOS and Linux are on GitHub Releases if you'd rather not install Python — unzip and run the visio-display inside.

Examples​

# Live serial (USB) → record to MCAP, no UI
visio-display --serial /dev/ttyACM0 --out capture.mcap

# Live TCP (device port 50001, over the hotspot or your Wi-Fi) → record to MCAP
visio-display --tcp 192.168.4.1:50001 --out capture.mcap

# Replay an MCAP into Rerun for visualization
visio-display --mcap-in capture.mcap --rerun

# Live stream → Foxglove WebSocket bridge (see below)
visio-display --tcp 192.168.4.1:50001 --foxglove

# Open the local console in your browser (device settings, recording keys)
visio-display --serve

# Replay an encrypted recording with its key
visio-display --mcap-in ego_0000.mcap --key-file recording.key --rerun

--mcap-in supports only --out / --rerun; --foxglove is for live streams. --serve is a separate local-console mode.

Options​

  • Source (choose one): --serial PORT · --tcp HOST[:PORT] · --mcap-in FILE
  • Output (at least one): --out FILE.mcap · --foxglove [--port 8765] · --rerun
  • Other: --serve (local web console) · --key-file FILE (recording key for encrypted files)
note

The device's TCP port is 50001 — write it explicitly, e.g. --tcp 192.168.4.1:50001. On Windows the serial port is COMx; on Linux /dev/ttyACM0.

View a live stream in Foxglove Studio​

Foxglove Studio can't connect to the device directly. Start a Foxglove WebSocket bridge with visio-display first:

visio-display --tcp 192.168.4.1:50001 --foxglove
# → Foxglove WebSocket server on ws://localhost:8765

Then in Foxglove Studio: Open connection → Foxglove WebSocket → ws://localhost:8765.

To view an already-recorded file you don't need the bridge — just File ▸ Open local file on the .mcap (see 5. Retrieve data & view in Foxglove).

Software decoding​

If a viewer shows a red cross or a black panel where the video should be, the host is missing H.265 hardware decoding (common on Windows). The visio-display bundles include a software decoder that doesn't depend on the system codec:

  1. Run visio-display from the bundle and choose the .mcap under RECORDING / MCAP FILE → Browse.
  2. Tick Use software decoding.
  3. Click Play in browser (or Open in Foxglove Desktop).

The operator-facing walkthrough, with the free Windows HEVC extension as the first thing to try, is in 5. Retrieve data & view in Foxglove.

The local console (--serve)​

visio-display --serve starts a small web console on your computer. Connect the device and use the Keys area to set, rotate or clear the team's recording key, and to see which key a device is currently using. Keys are stored in your local keychain before they are written to the device. See 12. Recording encryption for the key model and 7.6 Reading encrypted recordings for reading the files afterwards.