Some setups show more than the VNC screen can: a capture card that records a passed-through GPU's output, a camera pointed at a lab machine, or a stream from software inside the guest. With custom video streams, the Built-in VNC console can switch between the guest's VNC screen and such HTTP video streams, all in one place. You configure them with a short JSON snippet in the guest's Notes in Proxmox. This is an advanced feature for the built-in VNC console on iPhone, iPad and Mac, and part of Aprox Pro.

Where to find it

  • Configuration: the guest's Notes in Proxmox VE (in the Proxmox web UI: the guest › Summary › Notes).
  • Display picker: in the toolbar of the Built-in VNC console, once streams are configured.

Custom video streams work only with the Built-in VNC console type. Set Settings › Graphical Console (or Serial Console) to Built-in VNC. See Built-in VNC console.

Supported streams

Any HTTP or HTTPS address your device can reach that serves video, for example:

  • MJPEG streams, as many IP cameras and capture tools provide;
  • HLS streams (.m3u8);
  • H.264 or HEVC video.

The device running Aprox loads the stream itself, so it must be able to reach the stream's address. The stream does not go through Proxmox.

Add a stream

  1. In the Proxmox web UI, open the guest › Summary and edit its Notes.

  2. Add a JSON object with a custom_video_streams list. Each entry has a display_index (a number) and a url:

    {"custom_video_streams":[{"display_index":1,"url":"http://cam.local/stream.mjpg"}]}

    The Notes can contain other text as well. Aprox finds the JSON object anywhere in them. If the Notes contain other JSON objects, put this one first.

  3. Save the Notes.

  4. In Aprox, open the guest's console with Built-in VNC.

To add several streams, list several entries:

{"custom_video_streams":[
  {"display_index":1,"url":"http://capture.local:8080/stream.mjpg"},
  {"display_index":2,"url":"https://cam.example.com/live/index.m3u8"}
]}

Switch between displays

  1. Open the guest's console with Built-in VNC.
  2. Use the display picker in the toolbar ("Switch between VNC and custom video streams").
  3. Choose a display:
    • Display N — VNC: the guest's normal VNC screen, with keyboard and mouse.
    • Display N — Stream: one of your video streams, view only.

Displays are numbered by display_index. The VNC screen takes the lowest number that no stream uses. In the first example above, the VNC screen is Display 0 and the camera is Display 1. If you give a stream display_index 0, the VNC screen moves to the next free number.

Good to know

  • No picker? The picker appears only when the Notes contain a valid custom_video_streams list. Check the JSON for typos, such as missing quotes or commas, and reopen the console.
  • Stream stays black. Open the stream's URL in a browser on the same device to check that the address is right and the device can reach it.
  • Not on Android. Android's built-in VNC console shows the VNC screen only.