Video & camera configuration — WirePlumber 0.5.17 documentation

# Video & camera configuration

WirePlumber can expose cameras through two different backends: the V4L2 monitor, which talks to the kernel's Video4Linux2 interface directly, and the libcamera monitor, which uses libcamera and is able to drive more complex camera pipelines (notably the ISP-based cameras found on many ARM platforms).

Both monitors are enabled by default. They are grouped under the `hardware.video-capture` feature, which in turn wants `monitor.v4l2` and `monitor.libcamera`; see Well-known features. The `video-capture` profile brings up only the video part of WirePlumber, which is useful when running multiple instances.

Note

Cameras are also subject to access control. Under a sandbox such as Flatpak or Snap, an application only sees camera nodes if it has been granted permission; see Access configuration.

## Choosing a backend

Because both monitors enumerate the same hardware, the same physical camera is often reported twice. WirePlumber arbitrates between them rather than exposing duplicates, using the device numbers each backend reports in the `device.devids` property:

1. V4L2 devices driven by `uvcvideo` (ordinary USB webcams) are created first — for these, V4L2 is preferred.

2. libcamera devices are created next, unless their device numbers were already claimed by a V4L2 UVC device.

3. Remaining V4L2 devices are created last, unless libcamera already claimed them.

The arbitration needs both monitors to have reported, so node creation is delayed by the `monitor.camera-discovery-timeout` setting (1 second by default); see Well-known settings. A device that reports no device numbers at all bypasses the arbitration and is created immediately.

To use libcamera exclusively, disable the V4L2 monitor in your profile:

    wireplumber.profiles = {
      main = {
        monitor.v4l2 = disabled
      }
    }

Conversely, set `monitor.libcamera = disabled` to use V4L2 only.

## V4L2 configuration

monitor.v4l2.properties

  The properties used when constructing the `api.v4l2.enum.udev` SPA plugin, which does the actual device enumeration.

monitor.v4l2.rules

  Rules that are matched against V4L2 devices and nodes as they are created, allowing their properties to be modified. The syntax is the same as for the other monitor rules; see Modifying configuration.

  Device rules are matched against device properties such as `device.name`:

      monitor.v4l2.rules = [
        {
          matches = [
            {
              device.name = "~v4l2_device.*"
            }
          ]
          actions = {
            update-props = {
              device.nick = "My Device"
              device.disabled = false
            }
          }
        }
      ]

  Node rules are matched against node properties such as `node.name`:

      monitor.v4l2.rules = [
        {
          matches = [
            {
              node.name = "~v4l2_input.*"
            }
          ]
          actions = {
            update-props = {
              node.nick          = "My Node"
              priority.session   = 100
              node.pause-on-idle = false
              node.disabled      = false
            }
          }
        }
      ]

  Setting `device.disabled` or `node.disabled` to `true` is how a specific camera is hidden from the graph.

## libcamera configuration

monitor.libcamera.properties

  The properties used when constructing the `api.libcamera.enum.manager` SPA plugin.

monitor.libcamera.rules

  The same as `monitor.v4l2.rules`, but for devices and nodes created by the libcamera monitor. Device names match `libcamera_device.*` and node names match `libcamera_input.*`.

## Examples

Ready-made, commented example fragments for both backends ship with WirePlumber as `v4l2.conf` and `libcamera.conf`; see Example configuration fragments.

## Troubleshooting

My camera does not appear at all. Check that `hardware.video-capture` is enabled in your profile and that the relevant monitor is not disabled. Then check the logs with `WIREPLUMBER_DEBUG=s-monitors*:D`, which shows what each monitor enumerated and which devices were skipped by the arbitration described above.

My camera appears but produces no image. This is usually a backend issue rather than a WirePlumber one. Try the other backend; `libcamera` is often required for cameras that need ISP processing, while plain UVC webcams generally work better with V4L2.