Joel Purra: Developer and more


USB Video Class (UVC) device configurator (uvcc)

Configure USB Video Class (UVC) compliant devices from the command line.

UVC-compliant devices include webcams, digital camcorders, transcoders, analog video converters and still-image cameras.

Features

Use uvcc to fine-tune camera configuration, such as brightness, contrast, saturation, gain, white balance temperature, zoom. Export/import of JSON makes it easy to reliably and repeatedly configure one or more cameras for various situations.

  • Get configuration directly from the webcam.
  • Set configuration values directly on the webcam.
  • List available USB devices, including webcams.
  • List available webcam controls.
  • Export configuration to JSON.
  • Import configuration from JSON.
  • Per-user or per-directory configuration files.
  • See details of available controls from the upstream project uvc-control.

Installation

Requires Node.js (node and npm commands). Published on npm as uvcc.

npm install --global uvcc
  • Optionally omit the --global flag and use ./node_modules/.bin/uvcc from the install directory.
  • Uses libusb through the npm package usb.
  • Tested using Node.js v8.9.4 on macOS 10.13 High Sierra.

Usage

# Find your UVC device, note the vendor id (vId) and product id (pId).
# The ids can be in hexadecimal (0x000) or decimal (0000) format.
# For example Logitech (0x46d) C920 HD Pro Webcam (0x82d).
uvcc devices

# Use the vendor id and product id to export current configuration.
uvcc --vendor 0x46d --product 0x82d export

# Set exposure to manual.
uvcc --vendor 0x46d --product 0x82d set autoExposureMode 1

# Turn off automatic white balance.
uvcc --vendor 0x46d --product 0x82d set autoWhiteBalance 0

# Set the white balance temperature to 2000.
# NOTE: the whiteBalanceTemperature range for Logitech C920 is 2000-6500.
uvcc --vendor 0x46d --product 0x82d set whiteBalanceTemperature 2000

# Set the contrast to 192.
# NOTE: the contrast range for Logitech C920 is 0-255, default value 128.
uvcc --vendor 0x46d --product 0x82d set contrast 192

# Export configuration to a JSON file.
uvcc --vendor 0x46d --product 0x82d export > "uvcc-export.json"

# Load configuration from a JSON file.
cat "uvcc-export.json" | uvcc --vendor 0x46d --product 0x82d import

Help

uvcc --help
USB Video Class (UVC) device configurator. Used for webcams, camcorders,
etcetera.

Commands:
  uvcc get <name>          Get current control value from the webcam.
  uvcc set <name> <value>  Set control value on the webcam.
  uvcc range <name>        Get possible range (min and max) for a control from
                           the webcam.
  uvcc ranges              Get all ranges (min and max) for all available
                           controls from the webcam.
  uvcc devices             List connected USB devices with vendor id (vId) and
                           product id (pId).
  uvcc controls            List all supported controls.
  uvcc export              Output configuration in JSON format, on stdout.
  uvcc import              Input configuration in JSON format, from stdin.

Webcam selection:
  --vendor   Webcam vendor id in hex (0x000) or decimal (0000) format.  [number]
  --product  Webcam product id in hex (0x000) or decimal (0000) format. [number]

Options:
  --version  Show version number                                       [boolean]
  --config   Load command arguments from a JSON file.
  --verbose  Enable verbose output.                   [boolean] [default: false]
  --help     Show help                                                 [boolean]

Examples:
  uvcc --vendor 0x46d --product 0x82d get whiteBalanceTemperature

uvcc Copyright © 2018 Joel Purra <https://joelpurra.com/>

This program comes with ABSOLUTELY NO WARRANTY. This is free software, and you
are welcome to redistribute it under certain conditions. See GPL-3.0 license for
details.

See also: https://joelpurra.com/projects/uvcc/

Configuration

The command line arguments can optionally be provided using environment variables, implicit per-user/per-directory configuration files, or explicitly loaded from JSON files.

Environment variables

Set UVCC_<argument name>.

UVCC_VERBOSE=true uvcc controls

Configuration file format

Configuration files for uvcc are in JSON format. If you configure the same webcam each time, it is convenient to put vendor and product in the configuration file.

{
  "vendor": 1133,
  "product": 2093
}

Implicit configuration file

You can put any command line arguments as properties in a JSON file called either .uvccrc or .uvccrc.json. The file is loaded from the same directory as uvcc is executed in, or the nearest parent directory where it can be found. A convenient location might be your $HOME directory.

Explicit configuration file

Instead of passing command line arguments one by one, an explicit configuration file can be used. Explicitly defining a configuration file will prevent loading of the implicit configuration files.

uvcc --config <my-uvcc-config.json>

Examples

Exported configuration

# Logitech (0x46d) C920 HD Pro Webcam (0x82d).
uvcc --vendor 0x46d --product 0x82d export
{
  "absoluteExposureTime": 333,
  "absoluteFocus": 0,
  "absolutePanTilt": 0,
  "absoluteZoom": 120,
  "autoExposureMode": 1,
  "autoExposurePriority": 0,
  "autoFocus": 1,
  "autoWhiteBalance": 0,
  "backlightCompensation": 0,
  "brightness": 128,
  "contrast": 128,
  "gain": 49,
  "saturation": 128,
  "sharpness": 128,
  "whiteBalanceTemperature": 2500
}

Available control ranges

# Logitech (0x46d) C920 HD Pro Webcam (0x82d).
uvcc --vendor 0x46d --product 0x82d ranges
{
  "absoluteExposureTime": [
    3,
    2047
  ],
  "absoluteFocus": [
    0,
    250
  ],
  "absolutePanTilt": [
    -154614527725568,
    154618822692000
  ],
  "absoluteZoom": [
    100,
    500
  ],
  "autoFocus": [
    0,
    1
  ],
  "backlightCompensation": [
    0,
    1
  ],
  "brightness": [
    0,
    255
  ],
  "contrast": [
    0,
    255
  ],
  "gain": [
    0,
    255
  ],
  "saturation": [
    0,
    255
  ],
  "sharpness": [
    0,
    255
  ],
  "whiteBalanceTemperature": [
    2000,
    6500
  ]
}

Development

Get the source code from the uvcc repository.

Follow git-flow and use git-flow-avh.

# Make sure git-flow is initialized.
git flow init -d

npm run --silent test

Todo

  • Add tests.
  • Compare list of UVC controls with the output from v4l2-ctl.
  • Make available webcam controls dynamic for the actual webcam targeted/used, as there might be more/fewer/other controls on different cameras. Currently controls target Logitech C920 HD Pro Webcam, as per comments in uvc-control, although most should also apply to other UVC cameras.

See also

Acknowledgements

  • Pawel Szymczykowski for uvc-control for node.js. Without his code I would never have gotten close to automating — or perhaps even being able to — changing webcam controls on macOS.

uvcc Copyright © 2018 Joel Purra. Released under GNU General Public License version 3.0 (GPL-3.0). Your donations are appreciated!