Controlling UVC Camera Settings on Linux

The short answer

Most USB webcams on Linux are UVC devices handled by the kernel uvcvideo driver. Their image settings are exposed as Video4Linux2 (V4L2) controls. The most direct way to read and change them is the v4l2-ctl command from the v4l-utils package. Graphical front ends such as guvcview, qv4l2 or Cameractrls change the same controls through a window. A change applies to the selected camera device, takes effect immediately, and often does not survive unplugging the camera or rebooting.

• List cameras and their device nodes: v4l2-ctl --list-devices
• Show every control with its range, default and current value: v4l2-ctl -d /dev/video0 --list-ctrls-menus
• Change a control: v4l2-ctl -d /dev/video0 --set-ctrl=brightness=140
• Read a value back: v4l2-ctl -d /dev/video0 --get-ctrl=brightness

How UVC controls work

UVC is a USB class specification, but the camera firmware decides which controls exist and what their ranges and defaults are. Typical controls include brightness, contrast, saturation, sharpness, white balance, exposure, gain, power line frequency, focus and zoom. The driver translates them into V4L2 controls. Two cameras, even from the same brand, can expose different lists, so read the list from your own device instead of copying values from elsewhere.

A single camera often creates more than one device node. On current kernels one node usually handles video capture and another carries metadata only. The --list-devices output groups nodes per camera, and v4l2-ctl -d /dev/video0 --info shows whether a node supports video capture. Controls belong to the device, not to an application, so a value set with v4l2-ctl is seen by any program using that camera.

Control names can vary with the kernel version. On newer kernels automatic exposure usually appears as auto_exposure together with exposure_time_absolute, while older kernels use exposure_auto and exposure_absolute. Menu controls take the numeric values printed in the menu listing. A control flagged as inactive is currently overridden by an automatic mode: manual exposure time generally has no effect until auto exposure is switched to manual, and white balance temperature has no effect while automatic white balance is on.

Resolution, pixel format and frame rate are not controls. They are format parameters negotiated when an application starts the stream. Use v4l2-ctl -d /dev/video0 --list-formats-ext to see which combinations the camera offers. Many cameras offer higher resolutions at full frame rate only in compressed MJPG, with uncompressed YUYV limited by USB bandwidth. Because each application requests its own format when it opens the camera, setting the format beforehand with v4l2-ctl is often replaced by the application's choice.

Applying it to common problems

Banding or flicker under indoor lights: check the power_line_frequency menu and set it to match your local mains frequency, 50 Hz or 60 Hz. For a dark or noisy image, improve the lighting before raising gain, since higher gain brightens the picture at the cost of more visible noise.

Frame rate dropping in a dim room: in automatic mode many cameras lengthen exposure when light is low, which lowers the delivered frame rate. If the camera exposes exposure_dynamic_framerate (exposure_auto_priority on older kernels), setting it to 0 asks the camera to hold the frame rate, at the cost of a darker image. Manual exposure is the other option.

• Switch auto exposure to its manual mode; check the menu listing for the correct value, which is commonly 1 for auto_exposure.
• Set exposure_time_absolute to a value inside the reported range.
• Raise gain only if the image is still too dark.
• Confirm the values with --get-ctrl and watch the live image.

Focus or colour that keeps shifting: turn off continuous autofocus (focus_automatic_continuous, or focus_auto on older kernels) and set focus_absolute. For white balance, turn off white_balance_automatic and set white_balance_temperature. Each value only takes effect once its automatic counterpart is off.

To undo a change, the --list-ctrls-menus output shows a default value for each control, which you can set back explicitly. Reconnecting the camera also returns many models to their defaults.

Keeping settings across reconnects: common approaches are a short shell script of v4l2-ctl commands run after login, or a udev rule that runs the script when the camera is added. Address the camera through its stable link under /dev/v4l/by-id/, because numbering such as video0 can change between boots. Some applications apply their own values when they open the camera, so verify in your setup whether your settings remain after the application starts.

Limits and related questions

Software can only change what the firmware exposes; no tool adds a control the camera lacks. Some built-in laptop cameras are not UVC devices and use a different driver stack, so they may not offer these controls through v4l2-ctl at all.

Camera permission works in layers. Access to the device node usually depends on membership in the video group or on access granted to the logged-in session, which varies by distribution. Browsers and sandboxed packages such as Flatpak or Snap add their own permission prompts, sometimes through a PipeWire camera portal. If a camera responds to v4l2-ctl but not inside an app, check that app's camera permission and the selected camera in its settings.

Controls can usually be changed while another program is streaming, but changing the format typically fails with a device busy error until the stream stops. In video calls the browser negotiates resolution and frame rate with the site, while image controls set on the device still apply unless the application resets them.

Adjusting controls does not record anything. Graphical tools that can also take snapshots or recordings save files to a location set in their own preferences, so check that location if the captures are sensitive.