How to Adjust Webcam Focus in Klipper

The short answer

Klipper itself does not control your webcam. On a typical setup, the camera stream comes from a separate service, usually crowsnest, and Mainsail or Fluidd only displays it. To fix focus, change the camera's own controls on the host computer, such as a Raspberry Pi, with the v4l2-ctl tool. Turn off continuous autofocus, set a fixed manual focus value, and then add those settings to crowsnest.conf so they are applied every time the camera starts.

The focus can only be changed this way if the camera exposes focus controls. Many inexpensive webcams and some camera modules are fixed-focus. With those cameras, software cannot change focus. The only options are physical adjustment, if the lens allows it, or moving the camera to a distance where the image is already sharp.

Why the image keeps pulsing in and out of focus

The repeated blurring and sharpening is called autofocus hunting. A webcam's continuous autofocus keeps searching for a sharp subject. On a 3D printer, the subject is small, close to the lens, moves constantly and is often dimly lit, which can keep the autofocus searching instead of settling. Disabling continuous autofocus and locking the focus at the distance of the print area usually stops the pulsing, because the camera no longer tries to refocus.

Before you start

• SSH access to the computer running Klipper, Moonraker and your camera service.
• A working camera stream that you can view in Mainsail or Fluidd while you make changes.
• The v4l2-ctl tool, which is part of the v4l-utils package on Debian-based systems such as Raspberry Pi OS.
• A USB (UVC) webcam. The steps below use the Video4Linux controls that USB webcams expose. Ribbon-cable camera modules that run through libcamera may handle focus differently, and this guide does not have confirmed evidence for those modules.

If v4l2-ctl is not installed, install it with the following command:

sudo apt install v4l-utils

Step 1: Identify the camera device

List the video devices on the system:

v4l2-ctl --list-devices

One camera often appears as several /dev/videoN entries. The first entry listed under the camera's name is usually the capture device. For a path that stays the same after reboots and replugging, check the by-id folder and use the matching entry in place of /dev/video0 in the commands below:

ls -l /dev/v4l/by-id/

Success check: a device listed under your camera's name, which you will use in the remaining steps.

Step 2: See which focus controls the camera offers

v4l2-ctl -d /dev/video0 --list-ctrls

Look for two kinds of entries. The first is an autofocus switch, usually named focus_automatic_continuous on newer kernels or focus_auto on older ones. The second is a manual focus value, usually named focus_absolute. The output shows each control's minimum, maximum, step, default and current value. Use the exact names and range your camera reports, because they differ between models.

If neither control appears, your camera does not offer software focus control. The remaining software steps will not apply. Instead, check whether the lens can be adjusted by hand, or reposition the camera.

Step 3: Turn off continuous autofocus

Use the control name from your own list:

v4l2-ctl -d /dev/video0 --set-ctrl=focus_automatic_continuous=0

# on older kernels the control may be named:
v4l2-ctl -d /dev/video0 --set-ctrl=focus_auto=0

Autofocus must be off before you set a manual value. While autofocus is active, many cameras ignore focus_absolute or report the control as inactive.

Success check: in the web interface, the image stops pulsing. The image may now be steady but blurry, which is expected until you set the manual focus value.

Step 4: Find the right manual focus value

Set focus_absolute to a value inside the range your camera reported, replacing VALUE:

v4l2-ctl -d /dev/video0 --set-ctrl=focus_absolute=VALUE

Watch the stream and change the value in steps. Begin with large steps to find the rough area where the image becomes sharp, then use smaller steps to fine-tune it. Wait a moment after each change, because the web stream can lag behind the camera. Cameras differ in which direction focuses nearer and in how large one step is, so compare the image instead of assuming a direction. Focus on the area you care about most, such as the nozzle and first layer or the whole printed part.

Confirm the value the camera accepted:

v4l2-ctl -d /dev/video0 --get-ctrl=focus_absolute

Success check: the command returns the value you set, and the stream shows a steady, sharp image of your chosen area. No specific focus numbers can be recommended here, because suitable values depend on the camera model and its distance from the print. Record the value that works for your setup.

Step 5: Make the setting permanent in crowsnest

Settings made with v4l2-ctl are normally lost when the camera is reset, unplugged or the host reboots. If crowsnest provides your stream, open crowsnest.conf, which is usually in the printer configuration folder and can be edited from the Mainsail or Fluidd file editor. Add a v4l2ctl line to your camera section. List the autofocus setting first and separate the controls with commas:

[cam 1]
# ...existing settings stay as they are...
v4l2ctl: focus_automatic_continuous=0,focus_absolute=VALUE

Replace VALUE with the number you found, and use focus_auto instead if that is the name your camera reported. Save the file and restart the camera service:

sudo systemctl restart crowsnest

If you use a different streaming service, you will need to use that service's own method for applying camera controls at startup. This guide does not include confirmed details for other services.

How to know it worked

• After restarting crowsnest, the stream comes back sharp without running any commands manually.
• The get-ctrl command returns your chosen focus_absolute value, and autofocus reads 0.
• After a full reboot of the host, both of the checks above still pass.
• During a print, the image stays steady instead of pulsing.

These checks show that the camera accepts the controls, that crowsnest applies them at startup, and that the image is sharp at the distance you tested. They do not test whether the image stays sharp at other distances. On printers where the bed or toolhead moves toward or away from the camera, some parts of a print may fall outside the sharp zone. The checks also do not cover low-light image quality, stream frame rate or timelapse output, which depend on other camera and streaming settings.

If it still does not work

Symptom | Likely cause | What to try

Command reports that the control is not found | Wrong control name or wrong device | Run --list-ctrls on each video device for the camera and copy the exact names

focus_absolute is rejected or has no effect | Autofocus is still on | Set the autofocus control to 0 first, then set focus_absolute

Focus works manually but resets after reboot | Setting not saved in the startup configuration | Add the v4l2ctl line to crowsnest.conf and restart the service

Settings stop applying after replugging | Device number changed | Point crowsnest at the /dev/v4l/by-id path for the camera

No focus controls are listed at all | Fixed-focus camera | Adjust the lens physically if it allows it, or move the camera

Better lighting on the print area can make the image clearer, but locking manual focus is the main fix for hunting. Mainsail and Fluidd webcam settings cover stream display options such as the stream address, rotation and flip. In those interfaces, these settings are separate from camera focus.