Skip to main content

USB Webcam

A USB webcam plugged directly into your Home Assistant host can be a great option if a wireless camera is too slow or laggy: there is no network in between, so latency is minimal. Superhome only reads RTSP, so the webcam first has to be exposed as an RTSP stream. On Home Assistant OS the cleanest way to do this is the go2rtc add-on.

Works on any HAOS hardware

These steps work on Home Assistant OS regardless of the machine: a Raspberry Pi or an x86 mini-PC / home server. We validated this procedure on a Raspberry Pi 5. If you are not running Home Assistant OS (for example a plain Linux PC or a standalone Docker worker), skip to the alternative below.

go2rtc has been part of the Home Assistant core since 2024.11, but for USB webcams the dedicated add-on is the better choice. The add-on is started with host video/audio access (video: true), so it sees the webcam on /dev/video0 without any manual device mapping. The go2rtc bundled in the core runs in a container that does not always have access to /dev/video*.

1. Add the add-on repository​

  1. Go to Settings → Add-ons → Add-on Store.

  2. Top-right, open the three-dots menu (⋮) → Repositories.

  3. Paste this URL and press Add:

    https://github.com/AlexxIT/hassio-addons

  4. Close the dialog.

2. Install go2rtc​

  1. Reload the store page (a browser refresh sometimes helps).
  2. Scroll down to the AlexxIT add-ons section and open go2rtc.
  3. Press Install. The image download takes a few minutes on a Raspberry Pi.

3. Start the add-on​

On the add-on Info tab, enable Start on boot and Watchdog, then press Start.

4. Configure the stream​

You can edit the config straight from the go2rtc Web UI (recommended), or edit the file /config/go2rtc.yaml (same folder as configuration.yaml) with an add-on such as File editor or Studio Code Server. To open the Web UI, press Open Web UI on the add-on page: it runs on port 1984.

This minimal configuration is what worked for us, and it is the one to try first:

streams:
  usb_cam:
    - ffmpeg:device?video=/dev/video0#video=h264

In most cases a single USB webcam is /dev/video0, so this works as-is (always use the full path, not just video0). If your camera is not on /dev/video0 (for example you have more than one video device, or this config shows no image), the go2rtc Web UI lists the detected devices: press add to see the available sources and their paths, then put the correct /dev/videoN in the config above.

#video=h264 tells go2rtc to transcode the stream to H264. This is needed because many USB webcams output MJPEG or raw YUV, which RTSP/WebRTC handle poorly.

After saving, restart the add-on. Then, from the go2rtc Web UI home page, click stream next to your usb_cam entry to preview it live. This is the quickest way to confirm the camera works before you wire the URL into Superhome.

Lower CPU usage

If the webcam supports native H264 output, you can skip transcoding with #video=copy, which is much lighter on the host:

streams:
  usb_cam:
    - ffmpeg:device?video=/dev/video0&input_format=h264&video_size=1280x720#video=copy

video_size=1280x720 here is just a placeholder: set it to a resolution your webcam actually supports (e.g. 1920x1080). If you pick a size the camera does not offer, the stream will fail to start. When in doubt, the transcoding config above (#video=h264, no video_size) is the safer first choice.

5. Verify the RTSP URL​

The RTSP URL to use is:

rtsp://<host-ip>:8554/usb_cam

Use the IP address of the machine running HAOS. Before wiring it into Superhome, test it in VLC (Media → Open Network Stream) on a computer in the same network.

6. Use it in Superhome​

Paste the RTSP URL into the rtsp_url field of the Superhome Configuration tab. The connection recovers automatically, with no restart needed.

Keep the go2rtc Web UI on your home network

The go2rtc Web UI (port 1984) is not password protected, and anyone on your local network can open it and see the camera previews. This is fine for normal home use on a trusted network. Just don't expose port 1984 to the internet. If you need to, go2rtc supports authentication in the api section of its config.

Alternative for a normal PC (not HAOS)​

If you are not on Home Assistant OS, for example a plain Linux PC or a standalone Docker worker, you don't have the add-on store, so you set up the RTSP stream yourself. Two easy options:

Option A: run go2rtc directly. go2rtc is a single binary (also available as a Docker image, alexxit/go2rtc). Create a go2rtc.yaml with the exact same streams: block shown above and run it; the resulting URL is the same rtsp://<host-ip>:8554/usb_cam. The webcam still appears as /dev/video0 on Linux.

Option B: use v4l2rtspserver for any UVC webcam:

# Install v4l2rtspserver (Debian/Ubuntu/Raspbian)
apt install v4l2rtspserver

# Run (adjust /dev/video0 and resolution as needed)
v4l2rtspserver -W 1280 -H 720 -F 15 /dev/video0

Then use this URL as rtsp_url:

rtsp://<host-ip>:8554/unicast

Either way, verify the stream in VLC first, then paste the URL into the Superhome Configuration tab exactly as in step 6.