Installing vcam

vcam is a Linux program. It needs a C toolchain, the FFmpeg + libpng development headers, and the v4l2loopback kernel module for its virtual camera output. Screen-capture overlays additionally use wf-recorder on Wayland.

• Dependencies
• Build & install
• Optional: OpenCV filters
• One-time device setup (the Chromium fix)
• Verify
• Uninstall
• Install-time troubleshooting

Dependencies

On Debian / Ubuntu (package names differ on other distros):

sudo apt install \
    libv4l-dev libavcodec-dev libavformat-dev libavutil-dev \
    libswscale-dev libavdevice-dev libpng-dev \
    v4l2loopback-dkms pkg-config build-essential \
    wf-recorder slurp ncat

What each group is for:

• libav\* / libpng — the pipeline links these to decode the webcam's

MJPEG, scale frames, and load PNG/JPEG overlays.

• v4l2loopback-dkms — provides the virtual camera device that browsers

and video-call apps read from.

• wf-recorder, slurp — Wayland screen capture for the --screen

overlay (slurp lets you select a region interactively).

• ncat — vcam-ctl uses it to talk to the running vcam over a Unix

socket.

Runtime helpers vcam will use if present but that aren't hard build deps: swaymsg (monitor layout), v4l2-ctl (device inspection in vcam-setup), grim, xdg-open. See NOTICE for the full list and their licenses.

vcam-ctl and vcam-setup are POSIX sh. vcam-tune requires bash (it uses single-keypress input that has no POSIX equivalent).

Build & install

git clone <repo-url> vcam && cd vcam
make
sudo make install                          # default → /usr/local/bin

The build is warning-clean under -Wall -Wextra -Wpedantic. make produces two binaries: vcam and the test_screen diagnostic.

Choose a different destination if you prefer:

make install PREFIX=$HOME/.local             # ~/.local/bin (no sudo)
make install PREFIX=/usr                      # system-wide
make install DESTDIR=/tmp/pkg PREFIX=/usr     # staged, for packaging

install also drops LICENSE, NOTICE, README.md, and EXPRESSIONS.md into PREFIX/share/doc/vcam. Make sure your chosen bin directory is on PATH.

Optional: OpenCV filters

vcam has seven extra filters powered by OpenCV 5 — cartoon, pencil-sketch, watercolor, optical-flow, background subtraction, face effects, and person-segmentation background effects (see the OpenCV section in README.md). They are off by default: the normal build has no OpenCV dependency at all, and these filters simply aren't compiled in.

OpenCV 5 is the recommended version — the filters are written OpenCV-5-first. Built against 5.x, they use the features new in that release:

• the new graph-based DNN engine (ENGINE_AUTO): 80%+ ONNX operator

coverage (vs ~22% in 4.x), shape inference, constant folding, and operator fusion — the segmentation and face models load through it

• first-class FP16 (cv::hfloat/CV_16F): the person-matte blend in

personfx runs at half precision, halving the memory traffic of its heaviest per-frame step

OpenCV 4.5–4.x also works; the same code then compiles a classic-engine/FP32 fallback path, selected at compile time. Ask a running vcam which path it has with vcam-ctl opencv.

# OpenCV 5 dev files. If your distro still packages 4.x as
# libopencv-dev, build 5.x from source (github.com/opencv/opencv,
# branch 5.x) or use your distro's opencv5 package when available.
sudo apt install libopencv-dev

# Build with OpenCV support
make OPENCV=1
sudo make install     # remembers the OPENCV=1 flavor automatically

After any rebuild, restart the running vcam — vcam-ctl talks to the already-running process, which keeps serving the old binary until you replace it:

pkill vcam
vcam &
vcam-ctl opencv       # should now report your OpenCV version + engine

The build finds OpenCV via pkg-config, probing the module names opencv5, opencv4, and opencv in that order — note that an OpenCV 5 install often still ships its pkg-config file under the opencv4 name for compatibility, which is fine: the version, not the module name, decides which code path is compiled. If nothing is found, make OPENCV=1 stops with a clear message; you can force a name with OPENCV_PC=<name>.

Best matting quality: the ONNX Runtime backend

OpenCV 5's new DNN engine loads the RVM video-matting model but currently miscomputes it (verified: empty mattes). ONNX Runtime is RVM's reference runtime and computes it correctly. Enabling it gives personfx its best-quality engine — temporally stable, hair-level mattes:

vcam-setup --ort              # fetch onnxruntime (MIT, ~60 MB, one-time)
vcam-setup --models-rvm       # fetch the RVM model if you haven't
make OPENCV=1 ORT=1
sudo make install             # the build remembers ORT=1 afterwards
pkill vcam; vcam &
vcam-ctl opencv               # should report the ONNX Runtime backend

vcam picks matting engines in order: ONNX-Runtime RVM → OpenCV-DNN RVM (auto-disabled if it produces empty mattes) → PP-HumanSeg. Every step falls back automatically, so a missing library or model never breaks the filter. ORT_HOME=<dir> overrides the library location.

Model files (for facefx and personfx)

The five classic OpenCV filters work immediately. The two DNN-based ones need small ONNX model files, which you download once:

vcam-setup --models          # → ~/.local/share/vcam/models
# or system-wide:
sudo vcam-setup --models --system

This fetches two models, both free and permissively licensed:

• YuNet face detector — ~230 KB, MIT license
• PP-HumanSeg person segmentation — a few MB, Apache-2.0 license
• MobileFaceNet FER expression recognition (for moodfx) — Apache-2.0

The styleai neural-style filter has its own optional pack (five fast-neural-style networks, MIT license, ~6.5 MB each, from the ONNX Model Zoo mirror on HuggingFace):

vcam-setup --models-style

They're pulled from the official OpenCV model repository on HuggingFace. If you'd rather place them yourself, drop the .onnx files in any of $VCAM_MODEL_DIR, ~/.local/share/vcam/models, or /usr/local/share/vcam/models — vcam checks those in order. Until the models are present, facefx and personfx pass the frame through unchanged and print a one-time hint.

Nothing about these filters is required: if you never build with OPENCV=1, vcam is exactly the pure-C program it always was.

One-time device setup (the Chromium fix)

Chromium-family browsers pick the first /dev/video* they see. If that's your real webcam and vcam is already streaming from it, the browser gets EBUSY → NotReadableError and the page errors out before you can even pick a different device. Firefox doesn't have this problem.

vcam-setup --install writes /etc/modprobe.d/vcam.conf so the v4l2loopback module claims /dev/video0 before USB cameras enumerate. Your real cam then sits at /dev/video1+, and the loopback is what Chromium auto-picks. The exclusive_caps=1 parameter it sets is also mandatory for Firefox to see the device.

sudo vcam-setup --install

Then reboot, or do the manual module reload it prints:

sudo modprobe -r uvcvideo
sudo modprobe -r v4l2loopback
sudo modprobe v4l2loopback
sudo modprobe uvcvideo

Verify

vcam-setup
# → "OK — loopback at /dev/video0 comes before real cam at /dev/video1"

vcam                 # start it (defaults: input /dev/video1, output /dev/video0)
ffplay /dev/video0   # in another terminal, watch the output

In your video-call app, pick vcam as the camera.

Not sure what your webcam supports? Ask it:

vcam --list-formats

Uninstall

sudo make uninstall          # uses the same PREFIX/DESTDIR you installed with

To also undo the device setup, remove /etc/modprobe.d/vcam.conf and reload the modules (or reboot).

Install-time troubleshooting

For usage and runtime issues (filters, recording, screen capture), see the Troubleshooting section in README.md.