Linux UVC driver and tools – FAQ

How do I find out whether my camera is a UVC device or not?

  1. First find out the vendor ID (VID) and product ID (PID) of your webcam.
  2. Use the lsusb tool and look for video class interfaces like this: (In this example, the VID is 046d and the PID is 08cb.)
lsusb -d 046d:08cb -v | grep "14 Video"

If your device is a UVC device, you should see a number of lines that look like this:

bFunctionClass         14 Video
bInterfaceClass        14 Video
bInterfaceClass        14 Video
bInterfaceClass        14 Video

In this case the Linux UVC driver should recognize your camera when you plug it in.

If there are no such lines, your device is not a UVC device.

I have an UVC webcam but it is not working. What do you need to troubleshoot it?

If your webcam is UVC-compatible, it should be supported out of the box in any recent Linux distribution. Failures are usually caused by buggy applications or broken hardware (cameras, USB cables and USB host controllers can be faulty).

You should start with trying several applications. qv4l2, guvcview and luvcview are common test tools for UVC webcams, but feel free to try other V4L2 applications as well. In particular be careful that different webcams might use different video formats, and some of them can be unsupported in some applications.

If all applications fail display the same failure, chances are that your hardware is broken (or at least buggy), or that you're lucky enough to have hit a bug in the UVC driver. To diagnose the problem, please follow this procedure:

  1. Read "How do I find out whether my camera is a UVC device or not?".
  2. Enable all uvcvideo module traces:
    sudo echo 0xffff > /sys/module/uvcvideo/parameters/trace
  3. Reproduce the problem. The driver will print many debugging messages to the kernel log, so don't let video capture running for too long. You can disable the uvcmodule traces when you're done:
    sudo echo 0 > /sys/module/uvcvideo/parameters/trace
  4. Capture the contents of the kernel log:
    dmesg > dmesg.log
  5. If your device is not listed in the supported devices list, dump its USB descriptors:
    lsusb -d VID:PID -v > lsusb.log
    (replace VID and PID with your device VID and PID)
  6. Send a clear description of your problem, including the steps to reproduce it, to the linux-uvc-devel mailing list in a plain text e-mail (no HTML message). Attach dmesg.log (and possibly lsusb.log) to the e-mail.

MPlayer exits with 'FPS not specified in the header or invalid'.

When querying devices for their supported frame rate, MPlayer exits with the following message in its log:

FPS not specified in the header or invalid, use the -fps option.
No stream found.

v4l2: ioctl set mute failed: Invalid argument
v4l2: 0 frames successfully processed, 0 frames dropped.

Exiting... (End of file)

Older MPlayer version had trouble detecting video frame rates for digital video devices such as webcams. The problem has been fixed in MPlayer 1.0-rc2 revision 27171. In the meantime, you can override the frame rate with:

mplayer tv:// -tv fps=25

Why does my webcam only produce 15 frames per second while it is advertised as supporting 30 fps?

Beside the obvious reason of false advertising, the actual frame rate depends on exposure time. The longer the webcam exposes a frame, the lower the frame rate will be. If auto-exposure is turned on and the environment is too dark, the webcam can automatically raise the exposure time and thus lower the frame rate.

You can disable auto-exposure and control the exposure time manually through the 'Exposure, Auto' and 'Exposure (Absolute)' controls. If your webcam application doesn't offer a way to access those controls, you can use a panel application such as qv4l2 or a command line application such as yavta to control exposure.

My camera produces corrupted images, is very slow to start or is generally unstable.

(on a Linux kernel between v2.3.37 and v3.5 inclusive)

Starting at kernel v2.6.37 the uvcvideo driver enables USB autosuspend by default. UVC devices that are not in use will be suspended after a delay to save energy (this should not be confused with system suspend, where the whole system is suspended). Unfortunately it turns out that many cameras, including most Logitech UVC webcams, can't resume correctly from USB suspend. This results in several different symptoms, such as large stream start delays or corrupted video streams. The audio interface of the webcam can also be affected.

Starting at kernel v3.6 the USB core works around the issue by resetting the camera after USB resume. If you think your system is affected by the problem, you should update to a v3.6 or newer kernel, or disable autosuspend (either globally or selectively for your device).

To disable USB autosuspend globally, run

echo -1 > /sys/module/usbcore/parameters/autosuspend
This will only take effect for newly plugged devices.

What are quirks and how do I use them?

Not all UVC devices are bug-free. To be fair, most UVC devices are buggy, and some of them are so broken that they will not work with the uvcvideo driver out of the box. They should not have been labelled as UVC-compliant or even been sold, but the harm is done and we need to find a way to cope with it. That's why quirks have been introduced.

When a quasi-UVC device exhibits a UVC non-compliance (either because its developers have interpreted the UVC specification incorrectly, or because they forgot to implement parts of the specification that are not used by the Windows driver), the uvcvideo driver needs to handle that device in a special way. The driver tries to do detect those cases automatically, but needs to be explictly instructed on some cases. Each of those special cases is called a quirk and is identified by a flag. Supported quirks are

Name Value Description
UVC_QUIRK_STATUS_INTERVAL 0x00000001 Interpret the status endpoint bInterval value as a number of frame instead of an exponent value.
UVC_QUIRK_PROBE_MINMAX 0x00000002 Don't issue GET_MIN or GET_MAX request on the video probe and commit controls. Try to set this quirk if the device stalls the minimum and maximum video probe and comit requests.
UVC_QUIRK_PROBE_EXTRAFIELDS 0x00000004 Initialize read-only fields of the video probe and commit structure when negotiating formats with the camera. Try to set this quirk if the device stalls the set video probe and commit requests.
UVC_QUIRK_BUILTIN_ISIGHT 0x00000008 The device is an Apple iSight camera. Some versions of those cameras advertise UVC compatibility but use proprietary video data encapsulation that needs to be handled specifically.
UVC_QUIRK_STREAM_NO_FID 0x00000010 Don't use the Frame ID field from the video payload headers. UVC devices are required to toggle the FID bit at every frame, and the uvcvideo driver uses it by default to detect the start of a new frame. Try to set this quirk if the driver doesn't return any frame to applications after successfully starting the video stream.
UVC_QUIRK_IGNORE_SELECTOR_UNIT 0x00000020 Ignore UVC selector units. Selector units allow selecting the active input for multi-input video devices. Many webcams expose a selector unit with a single input, which is pointless by valid nonetheless. However, at least one camera exposes a selector unit but doesn't implement associated requests. The selector unit then has to be ingored. Try to set this quirk if VIDIOC_G_INPUT fail.
UVC_QUIRK_FIX_BANDWIDTH 0x00000080 Try to estimate the bandwidth required for uncompressed streams instead on relying on the value reported by the camera. See FAQ 7 for more information.
UVC_QUIRK_PROBE_DEF 0x00000100 Don't request the video probe and commit default values. Some cameras don't implement the GET_DEF request for the video probe and commit controls, or even completely crash when that request is received. The uvcvideo driver can then use the current values as default values.
UVC_QUIRK_RESTRICT_FRAME_RATE 0x00000200 Ignore all frame intervals reported by the device but the first one. This quirk is used for a specific device that reports buggy frame intervals, making the image severely underexposed when selected.

The uvcvideo driver includes a table of device identifies with their associated quirks. If your device isn't listed and you suspect it might need one or more quirks, you can force them manually through the module quirks parameter. Setting the quirks parameter at runtime will not affect currently connected devices, you will need to either disconnect and reconnect the device or unload the module and reload it with the quirks parameter set to the desired value. Note that setting the quirks parameter affects all UVC devices and overrides the value stored in the devices table, if any.

I get a "No space left on device" (-28) error when trying to stream from more than one camera simultaneously.

USB bandwidth is limited. Even though capturing two mid-resolution video streams at the same time might not seem to require high bandwidth according to today's standards, it can exceeds what good old high speed USB (a.k.a. USB 2.0) can provide.

High speed USB can transmit a maximum bandwidth of 480 Mb/s, including protocol overhead. The USB 2.0 standard requires that no more to 80% of the maximum bus bandwidth be allocated for all periodical transfers on the USB controller. This includes isochronous transfers uses for video, but also isochronous transfers for audio and interrupt transfers for keyboards and mice for isntance. Note that it doesn't matter whether a device really uses the bandwidth that has been allocated, the 80% rule caps bandwidth allocation, not just bandwidth usage.

UVC cameras require a variable bandwidth depending on the video format and resolution, but also on device implementation-specific constraints. To keep production costs as low as possible most UVC devices include very little RAM, seriously limiting buffering capabilities on the device side. This results in images being transferred in bursts, which requires a higher peak bandwidth. As bandwidth is allocated based on the peak value this can quickly exhaust the available USB bandwidth.

To work around the problem you can start with the following options.

If none of those options are possible or effective, read on.

As the uvcvideo driver has no way to know how much bandwidth a device will require, devices are responsible for reporting the amount of needed bandwidth to the driver as accurately as possible. Each alternate setting of the video streaming interface corresponds to one possible bandwidth value for the associated endpoint, and the driver then selects the alternate setting with the lowest bandwidth higher than or equal to the bandwidth requested by the device.

While most devices implement several alternate settings and only request the amount of bandwidth they really need, some just always request the maximum bandwidth available to a single endpoint, equal to 198.608 Mb/s excluding protocol overhead. Twice that bandwidth would exceed the high speed USB limit, resulting in -27 (-ENOSPC) errors.

If the device implements several alternate settings the driver could ignore the requested bandwidth and select a lower bandwidth alternate setting. This behaviour is currently implemented through the FIX_BANDWIDTH quirk when using an uncompressed format. Compressed formats are more difficult to work around as the driver has no way to estimate how much bandwidth the device could really require.

The FIX_BANDWIDTH quirk can be safely enabled without risking any adverse effect on the system stability, as it only affects UVC devices. In rare cases it could theoretically underestimate the required USB bandwidth, resulting in loss of USB packets and corrupt images. No such case has been reported in practice as of today.

You can find how how much bandwidth the device requests and which alternate setting the driver selects by setting the uvcvideo module trace parameter to 0x400. The driver will print bandwidth-related information to the kernel log. The amount of allocated bandwidth can also be modified for test purpose in the uvc_init_video():

/* Isochronous endpoint, select the alternate setting. */
bandwidth = stream->ctrl.dwMaxPayloadTransferSize;