.\n"
},
{
"path": "README.md",
"content": "\n ![\"uvcc](\"https://files.joelpurra.com/projects/uvcc/demo/2020-09-02/uvcc-demo.2020-09-02.gif\")
\n
\n\n\n USB Video Class (UVC) device configurator\n
\n\n## Overview\n\n- Fine-tune camera controls on the fly, such as brightness, contrast, saturation, gain, white balance/color temperature, zoom.\n- Export/import of settings makes it easy to reliably configure one or more cameras for various situations.\n- Command line interface (CLI) with JSON input/output for automation and repeatability.\n\n## Compatible cameras\n\n- [Elgato Facecam](https://www.elgato.com/facecam) ([4057:0120](./examples/elgato-facecam/4057-120/))\n- [Logitech C920 HD Pro Webcam](https://www.logitech.com/en-us/products/webcams/c920s-pro-hd-webcam.html) ([1133:2093](./examples/logitech-c920/1133-2093/))\n- [Logitech C922 Pro Stream Webcam](https://www.logitech.com/en-us/products/webcams/c922-pro-stream-webcam.html) ([1133:2140](./examples/logitech-c922/1133-2140/))\n- [Microsoft LifeCam Studio](https://www.microsoft.com/en-WW/accessories/products/webcams/lifecam-studio) Model 1425 ([1118:1906](./examples/microsoft-1425/1118-1906/), [1118:2065](./examples/microsoft-1425/1118-2065/))\n- Hopefully other [UVC-compatible webcams and digital camcorders](https://en.wikipedia.org/wiki/List_of_USB_video_class_devices).\n\n### Do you have another UVC-compatible camera?\n\n- Add it to the [`./examples/`](./examples/).\n- Is it not working?\n - [Report an issue.](https://github.com/joelpurra/uvcc/issues?q=is%3Aopen)\n - [Help fix the source code!](./DEVELOP.md)\n\n## Installation\n\nRequires [Node.js](https://nodejs.org/) (`node` and `npm` commands). Published on npm as [`uvcc`](https://www.npmjs.com/package/uvcc).\n\n```shell\nnpm install --global uvcc\n```\n\nOr use [`npx`](https://www.npmjs.com/package/npx) to execute with `npx uvcc`.\n\nOn Linux, you may need to [change device access permissions](./USAGE.md#linux).\n\n## Features\n\n- List available UVC cameras and camera controls.\n- Get/set individual camera controls.\n- Export/import full JSON control snapshots using `stdout`/`stdin`.\n- Per-user/per-directory/custom configuration files to handle multiple cameras.\n\n## Short usage example\n\nFirst start a program which shows a camera preview, such as Photo Booth on macOS or Cheese on Linux.\n\n```shell\n# Display commands and options.\nuvcc --help\n\n# Export current configuration. You can save it to a file, modify, and import later.\nuvcc export\n\n# Turn off automatic white balance to manually set the white balance.\nuvcc set auto_white_balance_temperature 0\n\n# Set the white balance temperature to 2000.\n# NOTE: the white_balance_temperature range for Logitech C920 is 2000-6500.\nuvcc set white_balance_temperature 2000\n\n# Set the contrast to 192.\n# NOTE: the contrast range for Logitech C920 is 0-255, default value 128.\nuvcc set contrast 192\n```\n\n## See also\n\n- Further help and configuration in [USAGE.md](./USAGE.md).\n- The [./examples/](./examples/) directory for some sample output.\n- The [CHANGELOG.md](./CHANGELOG.md), in particular for breaking changes.\n- Read [DEVELOP.md](./DEVELOP.md) to submit a patch or add your camera output to the examples.\n- [USB Video Class](https://en.wikipedia.org/wiki/USB_video_device_class) and [list of USB video class devices](https://en.wikipedia.org/wiki/List_of_USB_video_class_devices) on Wikipedia.\n\n---\n\n[`uvcc`](https://joelpurra.com/projects/uvcc/) Copyright © 2018, 2019, 2020, 2021, 2022 [Joel Purra](https://joelpurra.com/). Released under [GNU General Public License version 3.0 (GPL-3.0)](https://www.gnu.org/licenses/gpl.html). [Your donations are appreciated!](https://joelpurra.com/donate/)\n"
},
{
"path": "USAGE.md",
"content": "# [`uvcc`](https://joelpurra.com/projects/uvcc/) usage\n\nBy default, the first detected UVC camera will be used. See [configuration](#configuration) to target a specific camera. Note that [many cameras are not UVC-compatible](https://en.wikipedia.org/wiki/List_of_USB_video_class_devices).\n\n```shell\nuvcc --help\n```\n\n```text\nuvcc: USB Video Class (UVC) device configurator for the command line (CLI). Used for webcams, camcorders, etcetera.\n\nCommands:\n uvcc get Get current control value.\n uvcc set [value2] Set control value(s).\n uvcc range Get possible range (min and max) for a control.\n uvcc ranges Get all ranges (min and max).\n uvcc devices List connected UVC devices.\n uvcc controls List all supported controls for the camera.\n uvcc export Output configuration in JSON format, on stdout.\n uvcc import Input configuration in JSON format, from stdin.\n\nDevice selection for multi-camera setups.\n Numbers in hex (0x000) or decimal (0000) format.\n --vendor Camera vendor id (vId). [number] [default: 0]\n --product Camera product id (pId). [number] [default: 0]\n --address Camera device address. [number] [default: 0]\n\nOptions:\n --version Show version number [boolean]\n --config Load command arguments from a JSON file.\n --verbose Enable verbose output. [boolean] [default: false]\n --help Show help [boolean]\n\nExamples:\n\n Basic usage:\n uvcc controls Available controls for the camera.\n uvcc set auto_white_balance_temperature 0 Turn off automatic color correction.\n uvcc set saturation 64 Low color saturation (near grayscale).\n uvcc ranges List possible control ranges.\n uvcc set absolute_zoom 200 Zoom in.\n\n Automate config:\n - Not all controls can be imported.\n - Control order matters.\n uvcc export > my-uvcc-export.json Save to file.\n cat my-uvcc-export.json | uvcc import Load from file.\n\n Target a specific device:\n - Only useful for multi-camera setups.\n - For same-model cameras, also specify address.\n - Alt. use system USB settings to find devices.\n uvcc devices List available cameras.\n sudo uvcc devices Avoid LIBUSB_ERROR_ACCESS.\n uvcc --vendor 0x46d --product 0x82d export\n\nuvcc Copyright © 2018, 2019, 2020, 2021, 2022 Joel Purra \n\nThis program comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it\nunder certain conditions. See GPL-3.0 license for details.\n\nSee also: https://joelpurra.com/projects/uvcc/\n```\n\n## Configuration\n\nThe command line arguments can optionally be provided using environment variables, implicit per-user/per-directory configuration files, or explicitly loaded from JSON files.\n\n### Command line\n\n```shell\n# Find your UVC device, note the vendor id (vId) and product id (pId).\n# The ids can be in hexadecimal (0x000) or decimal (0000) format.\n# Example:\n# - The vendor is Logitech (hexadecimal 0x46d, or decimal 1133).\n# - The product is C920 HD Pro Webcam (hexadecimal 0x82d, or decimal 2093).\n# NOTE: listing USB devices might require root (sudo) on some systems.\nuvcc devices\n\n# Use the vendor id and product id to export current configuration.\n# NOTE: explicitly defining vendor/product is usually not necessary.\nuvcc --vendor 0x46d --product 0x82d export\n```\n\n### Environment variables\n\nSet `UVCC_`.\n\n```shell\nUVCC_VERBOSE=true uvcc controls\n```\n\n### Configuration file format\n\nConfiguration files for `uvcc` are in JSON format. If you configure the same camera each time, it is convenient to put `vendor` and `product` in the configuration file.\n\n```json\n{\n \"vendor\": 1133,\n \"product\": 2093\n}\n```\n\n### Implicit configuration file\n\nYou 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.\n\n### Explicit configuration file\n\nInstead 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.\n\n```shell\nuvcc --config \n```\n\n## Examples\n\nSee additional output examples in [./examples/](./examples/).\n\n### Exported configuration\n\n- Save the exported JSON data to a file as a snapshot of the current camera settings using `uvcc export > my-export.json`.\n- The export format is made to be imported again using `cat my-export.json | uvcc import`.\n- Note that some values are read-only, and are thus not exported.\n- Note that the order of the imported values matters, as for example automatic white balance needs to be turned off before setting a custom white balance.\n\n```shell\nuvcc export\n```\n\n```json\n{\n \"absolute_pan_tilt\": 0,\n \"absolute_zoom\": 100,\n \"auto_exposure_mode\": 8,\n \"auto_exposure_priority\": 1,\n \"auto_focus\": 1,\n \"auto_white_balance_temperature\": 1,\n \"backlight_compensation\": 0,\n \"brightness\": 128,\n \"contrast\": 128,\n \"gain\": 28,\n \"power_line_frequency\": 2,\n \"saturation\": 128,\n \"sharpness\": 128,\n \"white_balance_temperature\": 4675\n}\n```\n\n## System-specific details\n\n### Linux\n\nUser access to hardware devices, such as USB cameras, may be restricted by default on Linux. If, for example, `sudo uvcc devices` lists your camera but `uvcc devices` (without `sudo`) does not, then for ease-of-use you may adjust the device access level.\n\nBelow [userspace `/dev`](https://en.wikipedia.org/wiki/Udev) (`udev`) is used to change the access level for a specific device model. Note that relaxing the access level in this way reduces device security.\n\n1. Find your camera model's vendor and product id using, for example, [`lsusb`](https://en.wikipedia.org/wiki/Lspci#lsusb).\n\n ```shell\n lsusb\n ```\n\n Example output for Logitech (vendor id `046d`) C920 HD Pro Webcam (product id `082d`).\n\n ```shell\n Bus 005 Device 013: ID 046d:082d Logitech, Inc. HD Pro Webcam C920\n ```\n\n1. Create a new `udev` rules file for your UVC camera using your favorite text editor.\n\n ```shell\n sudo nano /etc/udev/rules.d/90-uvc-camera.rules\n ```\n\n1. Add one line for your device by vendor and product id, replacing `046d` and `082d` with the ids for your camera.\n\n ```text\n SUBSYSTEM==\"usb\", ATTRS{idVendor}==\"046d\", ATTRS{idProduct}==\"082d\", TAG+=\"uaccess\"\n ```\n\n If you have more than one camera model, just add more lines.\n\n1. Reload the device rules files after editing, and apply the changes.\n\n ```shell\n sudo udevadm control --reload-rules\n sudo udevadm trigger --action='change'\n ```\n\n1. Unplug your camera and plug it back in.\n1. Try `uvcc devices` (without `sudo`) and check if your camera is listed.\n\n---\n\n[`uvcc`](https://joelpurra.com/projects/uvcc/) Copyright © 2018, 2019, 2020, 2021, 2022 [Joel Purra](https://joelpurra.com/). Released under [GNU General Public License version 3.0 (GPL-3.0)](https://www.gnu.org/licenses/gpl.html). [Your donations are appreciated!](https://joelpurra.com/donate/)\n"
},
{
"path": "examples/README.md",
"content": "# [`uvcc`](https://joelpurra.com/projects/uvcc/) output examples\n\nA small sample of `uvcc` camera control output. See individual subdirectories for specific cameras. Note that [cameras with the same \"marketing name\" may have several USB hardware implementations with different vendor/product ids](https://github.com/joelpurra/uvcc/issues/21), so there may be more than one subdirectory.\n\n## How to add or update the output from your camera\n\n- Open the terminal.\n- Create and/or enter the correct camera product marketing name subdirectory.\n - The \"marketing name\" is the product name (usually including a short codename) you would see on the box when you buy a camera.\n - Use [kebab-case](https://en.wikipedia.org/wiki/Kebab_case) naming, with vendor name and product code/name.\n - Do not use the full \"marketing name\", such as \"Logitech HD Pro Webcam C920\".\n - Correct examples:\n - [`logitech-c920`](./logitech-c920/) from `Logitech HD Pro Webcam C920` (`name` in `uvcc devices`).\n - [`logitech-c922`](./logitech-c922/) from the vendor name and `C922 Pro Stream Webcam` (`name` in `uvcc devices`).\n - [`microsoft-1425`](./microsoft-1425/) from the vendor name and the model number `1425` found on the label on the camera cable as well as the box the camera was delivered in.\n- Create and/or enter the correct vendor/product id subdirectory.\n - This is due to [cameras with the same \"marketing name\" having different USB product ids](https://github.com/joelpurra/uvcc/issues/21), and this possibly having different hardware properties.\n - Use the format `-` with decimal number formatting, without leading zero padding.\n - You can find the USB `vendor` and `product` ids in the output of `uvcc devices`.\n - Correct examples:\n - [`logitech-c920/1133-2093`](./logitech-c920/1133-2093/)\n - [`logitech-c922/1133-2140`](./logitech-c920/1133-2140/)\n - [`microsoft-1425/1118-1906`](./microsoft-1425/1118-1906/)\n - [`microsoft-1425/1118-2065`](./microsoft-1425/1118-2065/)\n- Reset the camera to default values.\n - Unplug all cameras.\n - Reconnect only the camera you want to test.\n - This done to get \"fresh\" (hopefully default) values for `uvcc export`.\n- Run [`../../update-example.sh`](./update-example.sh)\n- Verify that the `*.json` files were created/updated.\n- Commit your changes and [submit a pull request](https://github.com/joelpurra/uvcc/compare).\n\n## Is it not working?\n\nNot all cameras are [UVC-compatible](https://en.wikipedia.org/wiki/List_of_USB_video_class_devices). If you can confirm that your camera model supports UVC, perhaps `uvcc` needs some fixes to support it.\n\n- [Report the issue](https://github.com/joelpurra/uvcc/issues?q=is%3Aopen) with as much detail as you can.\n- [Fix the source code](../DEVELOP.md) directly, since it is much easier debugging with access to the camera itself.\n\n---\n\n[`uvcc`](https://joelpurra.com/projects/uvcc/) Copyright © 2018, 2019, 2020, 2021, 2022 [Joel Purra](https://joelpurra.com/). Released under [GNU General Public License version 3.0 (GPL-3.0)](https://www.gnu.org/licenses/gpl.html). [Your donations are appreciated!](https://joelpurra.com/donate/)\n"
},
{
"path": "examples/elgato-facecam/4057-120/controls.json",
"content": "[\n \"absolute_exposure_time\",\n \"absolute_zoom\",\n \"auto_exposure_mode\",\n \"auto_white_balance_temperature\",\n \"brightness\",\n \"contrast\",\n \"power_line_frequency\",\n \"saturation\",\n \"sharpness\",\n \"white_balance_temperature\"\n]\n"
},
{
"path": "examples/elgato-facecam/4057-120/devices.json",
"content": "[\n {\n \"name\": \"Elgato Facecam\",\n \"vendor\": 4057,\n \"product\": 120,\n \"address\": 5\n }\n]\n"
},
{
"path": "examples/elgato-facecam/4057-120/export.json",
"content": "{\n \"absolute_exposure_time\": 156,\n \"absolute_zoom\": 1,\n \"auto_exposure_mode\": 2,\n \"auto_white_balance_temperature\": 1,\n \"brightness\": 88,\n \"contrast\": 4,\n \"power_line_frequency\": 2,\n \"saturation\": 37,\n \"sharpness\": 3,\n \"white_balance_temperature\": 2800\n}\n"
},
{
"path": "examples/elgato-facecam/4057-120/metadata.json",
"content": "{\n \"node\": \"v18.12.1\",\n \"npm\": \"8.19.2\",\n \"uname\": \"Linux dooderson-ThinkPad-T490 5.15.0-56-generic #62-Ubuntu SMP Tue Nov 22 19:54:14 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux\",\n \"uvcc\": \"v6.0.0\"\n}\n"
},
{
"path": "examples/elgato-facecam/4057-120/ranges.json",
"content": "{\n \"absolute_exposure_time\": {\n \"min\": 1,\n \"max\": 2500\n },\n \"absolute_zoom\": {\n \"min\": 1,\n \"max\": 31\n },\n \"brightness\": {\n \"min\": 0,\n \"max\": 255\n },\n \"contrast\": {\n \"min\": 0,\n \"max\": 10\n },\n \"saturation\": {\n \"min\": 0,\n \"max\": 63\n },\n \"sharpness\": {\n \"min\": 0,\n \"max\": 4\n },\n \"white_balance_temperature\": {\n \"min\": 2800,\n \"max\": 12500\n }\n}\n"
},
{
"path": "examples/logitech-c920/1133-2093/controls.json",
"content": "[\n \"absolute_exposure_time\",\n \"absolute_focus\",\n \"absolute_pan_tilt\",\n \"absolute_zoom\",\n \"auto_exposure_mode\",\n \"auto_exposure_priority\",\n \"auto_focus\",\n \"auto_white_balance_temperature\",\n \"backlight_compensation\",\n \"brightness\",\n \"contrast\",\n \"gain\",\n \"power_line_frequency\",\n \"saturation\",\n \"sharpness\",\n \"white_balance_temperature\"\n]\n"
},
{
"path": "examples/logitech-c920/1133-2093/demo/.gitignore",
"content": "recording/\n"
},
{
"path": "examples/logitech-c920/1133-2093/demo/README.md",
"content": "# [`uvcc`](https://joelpurra.com/projects/uvcc/) demo recording\n\nScripted (repeatable) demo recording showcasing `uvcc` capabilities.\n\n- This is a development tool.\n - Requires additional software to function.\n - Does not have usage documentation.\n - The output is intended for the project `README.md`.\n- Written specifically for Logitech C920.\n - Uses a mix of imported `*.json` files and direct `uvcc set`.\n - Not expected to, but might, work with other cameras.\n- Rubber ducks?\n - The rubber ducks used in the (initial) demo video are used for [rubber duck debugging](https://en.wikipedia.org/wiki/Rubber_duck_debugging).\n - They are also mascots for [joelpurra's stream on Twitch](https://www.twitch.tv/joelpurra).\n\n---\n\n[`uvcc`](https://joelpurra.com/projects/uvcc/) Copyright © 2018, 2019, 2020, 2021, 2022 [Joel Purra](https://joelpurra.com/). Released under [GNU General Public License version 3.0 (GPL-3.0)](https://www.gnu.org/licenses/gpl.html). [Your donations are appreciated!](https://joelpurra.com/donate/)\n"
},
{
"path": "examples/logitech-c920/1133-2093/demo/auto.json",
"content": "{\n \"absolute_pan_tilt\": [\n 0,\n 0\n ],\n \"absolute_zoom\": 100,\n \"auto_exposure_mode\": 8,\n \"auto_exposure_priority\": 1,\n \"auto_focus\": 1,\n \"auto_white_balance_temperature\": 1,\n \"brightness\": 128,\n \"contrast\": 128,\n \"gain\": 128,\n \"saturation\": 128,\n \"sharpness\": 128\n}\n"
},
{
"path": "examples/logitech-c920/1133-2093/demo/cold.json",
"content": "{\n \"auto_white_balance_temperature\": 0,\n \"white_balance_temperature\": 2000\n}\n"
},
{
"path": "examples/logitech-c920/1133-2093/demo/crazy.json",
"content": "{\n \"absolute_zoom\": 500,\n \"auto_exposure_mode\": 1,\n \"auto_focus\": 0,\n \"auto_white_balance_temperature\": 0,\n \"brightness\": 255,\n \"contrast\": 0,\n \"gain\": 255,\n \"saturation\": 255,\n \"sharpness\": 255,\n \"white_balance_temperature\": 2000\n}\n"
},
{
"path": "examples/logitech-c920/1133-2093/demo/record-demo.sh",
"content": "#!/usr/bin/env bash\n\nset -o errexit\nset -o noclobber\nset -o nounset\nset -o pipefail\n\nfunction die() {\n\techo \"FATAL:\" \"$@\" >&2\n\texit 1\n}\n\nfunction changeOverlayTextAsync() {\n\t# NOTE: don't wait for zmqsend, even if it usually is quick.\n\techo \"drawtext reinit 'text=${@}\" | zmqsend &\n}\n\n[[ -x \"$(which node)\" ]] || die 'Could not find ffmpeg executable in $PATH.' 'https://nodejs.org/'\n[[ -x \"$(which ffmpeg)\" ]] || die 'Could not find ffmpeg executable in $PATH.' 'https://ffmpeg.org/'\n[[ -x \"$(which gifski)\" ]] || die 'Could not find gifski executable in $PATH.' 'https://gif.ski/'\n\ndeclare -r SCRIPT_BASE=\"${BASH_SOURCE%/*}\"\ndeclare SCRIPT_BASE_ABSOLUTE\nSCRIPT_BASE_ABSOLUTE=\"$(realpath \"$SCRIPT_BASE\")\"\n\n# NOTE: using the local repository version of uvcc, with any local (even uncommitted) changes.\ndeclare UVCC_INDEX\nUVCC_INDEX=\"$(realpath \"${SCRIPT_BASE_ABSOLUTE}/../../../../dist/index.js\")\"\n\ndeclare -r UVCC=\"node -- ${UVCC_INDEX}\"\n\nmkdir -p './recording/'\n\nset -x\n\n# NOTE: requires\n# - ffmpeg compiled with --enable-libzmq\n# - zmqsend from the ffmpeg repository\n# http://www.ffmpeg-archive.org/how-to-build-tools-zmqsend-td4686430.html\n# https://raspberrypi.stackexchange.com/questions/93786/ffmpeg-doesnt-have-tools-zmqsend\ncoproc 'RECORDER' {\n\tffmpeg \\\n\t\t-hide_banner \\\n\t\t-loglevel 'error' \\\n\t\t-f 'v4l2' \\\n\t\t-framerate '24' \\\n\t\t-video_size '1280x720' \\\n\t\t-input_format 'h264' \\\n\t\t-i /dev/video0 \\\n\t\t-ss '2' \\\n\t\t-an \\\n\t\t-sn \\\n\t\t-vf \"\n\t\t\tzmq='',\n\t\t\tscale=sws_flags=spline+accurate_rnd:out_range=tv,\n\t\t\tdrawbox='y=(ih/5):color=black@0.3:width=iw:height=(ih/6):t=fill',\n\t\t\tdrawtext='fontsize=(h/8):fontcolor=black:x=((w-tw)/2):y=(h/5)+(h/36):text=auto.json'\n\t\t\" \\\n\t\t-c:v 'libx264' \\\n\t\t-colorspace 'bt709' \\\n\t\t-color_trc 'bt709' \\\n\t\t-color_primaries 'bt709' \\\n\t\t-color_range 'tv' \\\n\t\t-pix_fmt 'yuv420p' \\\n\t\t-f 'mp4' \\\n\t\t-y \\\n\t\t'./recording/uvcc-demo.mp4'\n\t}\n\n# NOTE: setting -ss '2' to skip the first two seconds of video, to let the camera autoadjust to current lighting conditions.\nsleep 2\n\nchangeOverlayTextAsync 'auto.json'\ncat 'auto.json' | $UVCC import\n\nsleep 5\n\nchangeOverlayTextAsync 'warm.json'\ncat 'warm.json' | $UVCC import\n\nsleep 3\n\nchangeOverlayTextAsync 'cold.json'\ncat 'cold.json' | $UVCC import\n\nsleep 3\n\nchangeOverlayTextAsync 'zoom in, pan/tilt'\n$UVCC set absolute_zoom 500\n\nsleep 1\n\n# TODO: could be smoother by adding more steps.\n$UVCC set absolute_pan_tilt -18000 -18000\n$UVCC set absolute_pan_tilt -36000 -36000\nsleep 0.6\n$UVCC set absolute_pan_tilt -18000 -36000\n$UVCC set absolute_pan_tilt 0 -36000\n$UVCC set absolute_pan_tilt 18000 -36000\n$UVCC set absolute_pan_tilt 36000 -36000\nsleep 0.6\n$UVCC set absolute_pan_tilt 18000 -36000\n$UVCC set absolute_pan_tilt 0 -36000\n\nsleep 1\n\nchangeOverlayTextAsync 'crazy.json'\ncat 'crazy.json' | $UVCC import\n\nsleep 4\n\n# TODO: generate the json for these steps and import, instead of individual step commands.\nchangeOverlayTextAsync 'stepwise color changes'\n$UVCC set brightness 200\n$UVCC set saturation 200\n$UVCC set sharpness 200\n$UVCC set gain 200\n\nsleep 0.5\n\n$UVCC set brightness 150\n$UVCC set saturation 150\n$UVCC set sharpness 150\n$UVCC set gain 150\n\nsleep 0.5\n\n$UVCC set brightness 100\n$UVCC set saturation 100\n$UVCC set sharpness 100\n$UVCC set gain 100\n\nsleep 0.5\n\n$UVCC set brightness 50\n$UVCC set saturation 50\n$UVCC set sharpness 50\n# $UVCC set gain 50\n\nsleep 0.5\n\n# $UVCC set brightness 0\n$UVCC set saturation 0\n$UVCC set sharpness 0\n# $UVCC set gain 0\n\nsleep 2\n\n# NOTE: hardcoded range because dynamically the current absolute_zoom value to get a\n# starting point isn't really reliable, as it depends on camera image output size.\nfor absolute_zoom in {150..100};\ndo\n\t$UVCC set absolute_zoom \"$absolute_zoom\"\ndone\n\n# NOTE: the video is made to loop, so going back to auto.json at the end.\nchangeOverlayTextAsync 'auto.json'\ncat 'auto.json' | $UVCC import\n\nsleep 3\n\n# NOTE: emulate ffmpeg \"q\" (quit) keyboard key press.\necho -n 'q' >& \"${RECORDER[1]}\"\n\n# NOTE: wait for ffmpeg to finish writing the video.\nwait \"${RECORDER_PID}\"\n\n# https://engineering.giphy.com/how-to-make-gifs-with-ffmpeg/\n# https://superuser.com/questions/556029/how-do-i-convert-a-video-to-gif-using-ffmpeg-with-reasonable-quality\n# ffmpeg -hide_banner -loglevel 'error' -i './recording/uvcc-demo.mp4' -filter_complex \"[0:v] fps=4,scale=480:-2:flags=lanczos,split [a][b];[a] palettegen=stats_mode=diff [p];[b][p] paletteuse\" -vsync '0' -loop '0' -y './recording/uvcc-demo.gif'\n\n# https://gif.ski/\nfind ./recording -iname 'demo-*.png' -delete\nffmpeg -hide_banner -loglevel 'error' -i './recording/uvcc-demo.mp4' -vf \"fps='4'\" './recording/demo-%04d.png'\nfind ./recording -iname 'demo-*.png' -print0 | xargs -0 gifski --fps '4' --width '480' --quality '25' --output './recording/uvcc-demo.gif'\n"
},
{
"path": "examples/logitech-c920/1133-2093/demo/warm.json",
"content": "{\n \"auto_white_balance_temperature\": 0,\n \"white_balance_temperature\": 6500\n}\n"
},
{
"path": "examples/logitech-c920/1133-2093/devices.json",
"content": "[\n {\n \"name\": \"HD Pro Webcam C920\",\n \"vendor\": 1133,\n \"product\": 2093,\n \"address\": 66\n }\n]\n"
},
{
"path": "examples/logitech-c920/1133-2093/export.json",
"content": "{\n \"absolute_exposure_time\": 333,\n \"absolute_focus\": 0,\n \"absolute_pan_tilt\": [\n 0,\n 0\n ],\n \"absolute_zoom\": 100,\n \"auto_exposure_mode\": 8,\n \"auto_exposure_priority\": 1,\n \"auto_focus\": 1,\n \"auto_white_balance_temperature\": 1,\n \"backlight_compensation\": 0,\n \"brightness\": 128,\n \"contrast\": 128,\n \"gain\": 97,\n \"power_line_frequency\": 2,\n \"saturation\": 128,\n \"sharpness\": 128,\n \"white_balance_temperature\": 4852\n}\n"
},
{
"path": "examples/logitech-c920/1133-2093/metadata.json",
"content": "{\n \"node\": \"v18.1.0\",\n \"npm\": \"8.8.0\",\n \"uname\": \"Linux compendious 5.15.0-27-generic #28-Ubuntu SMP Thu Apr 14 04:55:28 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux\",\n \"uvcc\": \"v6.0.0\"\n}\n"
},
{
"path": "examples/logitech-c920/1133-2093/ranges.json",
"content": "{\n \"absolute_exposure_time\": {\n \"min\": 3,\n \"max\": 2047\n },\n \"absolute_focus\": {\n \"min\": 0,\n \"max\": 250\n },\n \"absolute_pan_tilt\": {\n \"min\": [\n -36000,\n -36000\n ],\n \"max\": [\n 36000,\n 36000\n ]\n },\n \"absolute_zoom\": {\n \"min\": 100,\n \"max\": 500\n },\n \"backlight_compensation\": {\n \"min\": 0,\n \"max\": 1\n },\n \"brightness\": {\n \"min\": 0,\n \"max\": 255\n },\n \"contrast\": {\n \"min\": 0,\n \"max\": 255\n },\n \"gain\": {\n \"min\": 0,\n \"max\": 255\n },\n \"saturation\": {\n \"min\": 0,\n \"max\": 255\n },\n \"sharpness\": {\n \"min\": 0,\n \"max\": 255\n },\n \"white_balance_temperature\": {\n \"min\": 2000,\n \"max\": 6500\n }\n}\n"
},
{
"path": "examples/logitech-c922/1133-2140/controls.json",
"content": "[\n \"absolute_exposure_time\",\n \"absolute_focus\",\n \"absolute_pan_tilt\",\n \"absolute_zoom\",\n \"auto_exposure_mode\",\n \"auto_exposure_priority\",\n \"auto_focus\",\n \"auto_white_balance_temperature\",\n \"backlight_compensation\",\n \"brightness\",\n \"contrast\",\n \"gain\",\n \"power_line_frequency\",\n \"saturation\",\n \"sharpness\",\n \"white_balance_temperature\"\n]\n"
},
{
"path": "examples/logitech-c922/1133-2140/devices.json",
"content": "[\n {\n \"name\": \"C922 Pro Stream Webcam\",\n \"vendor\": 1133,\n \"product\": 2140,\n \"address\": 43\n }\n]\n"
},
{
"path": "examples/logitech-c922/1133-2140/export.json",
"content": "{\n \"absolute_exposure_time\": 250,\n \"absolute_focus\": 0,\n \"absolute_pan_tilt\": [\n 0,\n 0\n ],\n \"absolute_zoom\": 100,\n \"auto_exposure_mode\": 8,\n \"auto_exposure_priority\": 1,\n \"auto_focus\": 1,\n \"auto_white_balance_temperature\": 1,\n \"backlight_compensation\": 0,\n \"brightness\": 128,\n \"contrast\": 128,\n \"gain\": 0,\n \"power_line_frequency\": 2,\n \"saturation\": 128,\n \"sharpness\": 128,\n \"white_balance_temperature\": 4000\n}\n"
},
{
"path": "examples/logitech-c922/1133-2140/metadata.json",
"content": "{\n \"node\": \"v18.1.0\",\n \"npm\": \"8.8.0\",\n \"uname\": \"Linux compendious 5.15.0-27-generic #28-Ubuntu SMP Thu Apr 14 04:55:28 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux\",\n \"uvcc\": \"v6.0.0\"\n}\n"
},
{
"path": "examples/logitech-c922/1133-2140/ranges.json",
"content": "{\n \"absolute_exposure_time\": {\n \"min\": 3,\n \"max\": 2047\n },\n \"absolute_focus\": {\n \"min\": 0,\n \"max\": 250\n },\n \"absolute_pan_tilt\": {\n \"min\": [\n -36000,\n -36000\n ],\n \"max\": [\n 36000,\n 36000\n ]\n },\n \"absolute_zoom\": {\n \"min\": 100,\n \"max\": 500\n },\n \"backlight_compensation\": {\n \"min\": 0,\n \"max\": 1\n },\n \"brightness\": {\n \"min\": 0,\n \"max\": 255\n },\n \"contrast\": {\n \"min\": 0,\n \"max\": 255\n },\n \"gain\": {\n \"min\": 0,\n \"max\": 255\n },\n \"saturation\": {\n \"min\": 0,\n \"max\": 255\n },\n \"sharpness\": {\n \"min\": 0,\n \"max\": 255\n },\n \"white_balance_temperature\": {\n \"min\": 2000,\n \"max\": 6500\n }\n}\n"
},
{
"path": "examples/microsoft-1425/1118-1906/controls.json",
"content": "[\n \"absolute_exposure_time\",\n \"absolute_focus\",\n \"absolute_pan_tilt\",\n \"absolute_zoom\",\n \"auto_exposure_mode\",\n \"auto_focus\",\n \"auto_white_balance_temperature\",\n \"backlight_compensation\",\n \"brightness\",\n \"contrast\",\n \"power_line_frequency\",\n \"saturation\",\n \"sharpness\",\n \"white_balance_temperature\"\n]\n"
},
{
"path": "examples/microsoft-1425/1118-1906/devices.json",
"content": "[\n {\n \"name\": \"Microsoft® LifeCam Studio(TM)\",\n \"vendor\": 1118,\n \"product\": 1906,\n \"address\": 28\n }\n]\n"
},
{
"path": "examples/microsoft-1425/1118-1906/export.json",
"content": "{\n \"absolute_exposure_time\": 156,\n \"absolute_focus\": 0,\n \"absolute_pan_tilt\": [\n 0,\n 0\n ],\n \"absolute_zoom\": 0,\n \"auto_exposure_mode\": 8,\n \"auto_focus\": 1,\n \"auto_white_balance_temperature\": 1,\n \"backlight_compensation\": 5,\n \"brightness\": 133,\n \"contrast\": 5,\n \"power_line_frequency\": 2,\n \"saturation\": 103,\n \"sharpness\": 25,\n \"white_balance_temperature\": 4500\n}\n"
},
{
"path": "examples/microsoft-1425/1118-1906/metadata.json",
"content": "{\n \"node\": \"v16.6.0\",\n \"npm\": \"7.20.3\",\n \"uname\": \"Darwin MacBook-Pro 20.5.0 Darwin Kernel Version 20.5.0: Sat May 8 05:10:33 PDT 2021; root:xnu-7195.121.3~9/RELEASE_X86_64 x86_64\",\n \"uvcc\": \"3.0.1\"\n}\n"
},
{
"path": "examples/microsoft-1425/1118-1906/ranges.json",
"content": "{\n \"absolute_exposure_time\": {\n \"min\": 1,\n \"max\": 10000\n },\n \"absolute_focus\": {\n \"min\": 0,\n \"max\": 40\n },\n \"absolute_pan_tilt\": {\n \"min\": [\n -529200,\n -432000\n ],\n \"max\": [\n 529200,\n 432000\n ]\n },\n \"absolute_zoom\": {\n \"min\": 0,\n \"max\": 317\n },\n \"backlight_compensation\": {\n \"min\": 0,\n \"max\": 10\n },\n \"brightness\": {\n \"min\": 30,\n \"max\": 255\n },\n \"contrast\": {\n \"min\": 0,\n \"max\": 10\n },\n \"saturation\": {\n \"min\": 0,\n \"max\": 200\n },\n \"sharpness\": {\n \"min\": 0,\n \"max\": 50\n },\n \"white_balance_temperature\": {\n \"min\": 2500,\n \"max\": 10000\n }\n}\n"
},
{
"path": "examples/microsoft-1425/1118-2065/controls.json",
"content": "[\n \"absolute_exposure_time\",\n \"absolute_focus\",\n \"absolute_pan_tilt\",\n \"absolute_zoom\",\n \"auto_exposure_mode\",\n \"auto_focus\",\n \"auto_white_balance_temperature\",\n \"backlight_compensation\",\n \"brightness\",\n \"contrast\",\n \"power_line_frequency\",\n \"saturation\",\n \"sharpness\",\n \"white_balance_temperature\"\n]\n"
},
{
"path": "examples/microsoft-1425/1118-2065/devices.json",
"content": "[\n {\n \"name\": \"Microsoft® LifeCam Studio(TM)\",\n \"vendor\": 1118,\n \"product\": 2065,\n \"address\": 38\n }\n]\n"
},
{
"path": "examples/microsoft-1425/1118-2065/export.json",
"content": "{\n \"absolute_exposure_time\": 156,\n \"absolute_focus\": 0,\n \"absolute_pan_tilt\": [\n 0,\n 0\n ],\n \"absolute_zoom\": 0,\n \"auto_exposure_mode\": 8,\n \"auto_focus\": 1,\n \"auto_white_balance_temperature\": 1,\n \"backlight_compensation\": 5,\n \"brightness\": 133,\n \"contrast\": 5,\n \"power_line_frequency\": 2,\n \"saturation\": 109,\n \"sharpness\": 25,\n \"white_balance_temperature\": 6358\n}\n"
},
{
"path": "examples/microsoft-1425/1118-2065/metadata.json",
"content": "{\n \"node\": \"v18.1.0\",\n \"npm\": \"8.8.0\",\n \"uname\": \"Linux compendious 5.15.0-27-generic #28-Ubuntu SMP Thu Apr 14 04:55:28 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux\",\n \"uvcc\": \"v6.0.0\"\n}\n"
},
{
"path": "examples/microsoft-1425/1118-2065/ranges.json",
"content": "{\n \"absolute_exposure_time\": {\n \"min\": 1,\n \"max\": 10000\n },\n \"absolute_focus\": {\n \"min\": 0,\n \"max\": 40\n },\n \"absolute_pan_tilt\": {\n \"min\": [\n -529200,\n -432000\n ],\n \"max\": [\n 529200,\n 432000\n ]\n },\n \"absolute_zoom\": {\n \"min\": 0,\n \"max\": 317\n },\n \"backlight_compensation\": {\n \"min\": 0,\n \"max\": 10\n },\n \"brightness\": {\n \"min\": 30,\n \"max\": 255\n },\n \"contrast\": {\n \"min\": 0,\n \"max\": 10\n },\n \"saturation\": {\n \"min\": 0,\n \"max\": 200\n },\n \"sharpness\": {\n \"min\": 0,\n \"max\": 50\n },\n \"white_balance_temperature\": {\n \"min\": 2500,\n \"max\": 10000\n }\n}\n"
},
{
"path": "examples/update-example.sh",
"content": "#!/usr/bin/env bash\n\nset -o errexit\nset -o noclobber\nset -o nounset\nset -o pipefail\n\ndeclare -r SCRIPT_BASE=\"${BASH_SOURCE%/*}\"\ndeclare SCRIPT_BASE_ABSOLUTE\nSCRIPT_BASE_ABSOLUTE=\"$(realpath \"$SCRIPT_BASE\")\"\n\ndeclare UVCC_INDEX\nUVCC_INDEX=\"$(realpath \"${SCRIPT_BASE_ABSOLUTE}/../dist/index.js\")\"\n\ndeclare -r UVCC=\"node -- ${UVCC_INDEX}\"\n\nrm -f 'controls.json'\n$UVCC controls > 'controls.json'\n\nrm -f 'devices.json'\n$UVCC devices > 'devices.json'\n\nrm -f 'export.json'\n$UVCC export > 'export.json'\n\nrm -f 'ranges.json'\n$UVCC ranges > 'ranges.json'\n\nrm -f 'metadata.json'\njq \\\n\t--null-input \\\n\t--arg uvcc \"$($UVCC --version)\" \\\n\t--arg node \"$(node --version)\" \\\n\t--arg npm \"$(npm --version)\" \\\n\t--arg uname \"$(uname -a)\" \\\n\t--sort-keys \\\n\t'{\n\t\tuvcc: $uvcc,\n\t\tnode: $node,\n\t\tnpm: $npm,\n\t\tuname: $uname,\n\t}' > 'metadata.json'\n"
},
{
"path": "package.json",
"content": "{\n \"name\": \"uvcc\",\n \"version\": \"7.0.0\",\n \"description\": \"USB Video Class (UVC) device configurator for the command line (CLI). Used for webcams, camcorders, etcetera.\",\n \"homepage\": \"https://joelpurra.com/projects/uvcc/\",\n \"type\": \"module\",\n \"exports\": \"./dist/index.js\",\n \"types\": \"./dist/index.d.ts\",\n \"bin\": {\n \"uvcc\": \"./dist/index.js\"\n },\n \"files\": [\n \"dist/**/*\"\n ],\n \"scripts\": {\n \"clean\": \"rimraf ./dist/\",\n \"build\": \"tsc\",\n \"rebuild\": \"npm run --silent clean && npm run --silent build\",\n \"build:watch\": \"tsc --watch\",\n \"debug:run\": \"node --inspect ./dist/index.js\",\n \"debug:run:break\": \"node --inspect-brk ./dist/index.js\",\n \"test\": \"npm run --silent lint\",\n \"lint\": \"npm run --silent lint:xo && npm run --silent lint:prettier && npm run --silent lint:copyright\",\n \"lint:fix\": \"npm run --silent lint:xo:fix && npm run --silent lint:prettier:fix\",\n \"lint:copyright\": \"find . -not \\\\( -path './.git/*' -or -path './node_modules/*' -or -path './dist/*' \\\\) -type f \\\\( -iname '*.js' -or -iname '*.ts' \\\\) -print0 | xargs -0 grep -L 'This file is part of uvcc' | sed 's/^/File is missing copyright notice: /'\",\n \"lint:prettier\": \"prettier --list-different \\\"**/*.json\\\" \\\"**/*.md\\\" || { echo \\\"Prettier needs to format the above files. Try 'npm run --silent lint:fix'.\\\" && exit 1; }\",\n \"lint:prettier:fix\": \"prettier --write \\\"**/*.json\\\" \\\"**/*.md\\\"\",\n \"lint:xo\": \"xo\",\n \"lint:xo:fix\": \"xo --fix\",\n \"prepublishOnly\": \"git diff-index --exit-code master && npm run --silent rebuild && npm run --silent test\"\n },\n \"dependencies\": {\n \"array-non-uniq\": \"^1.0.0\",\n \"bluebird\": \"^3.7.2\",\n \"chalk\": \"^5.2.0\",\n \"engine-check\": \"^1.0.1\",\n \"filter-obj\": \"^3.0.0\",\n \"find-up\": \"^6.3.0\",\n \"map-obj\": \"^5.0.2\",\n \"read-pkg-up\": \"^9.1.0\",\n \"sort-keys\": \"^5.0.0\",\n \"stream-to-promise\": \"^3.0.0\",\n \"uvc-control\": \"github:joelpurra/node-uvc-control#v2\",\n \"yargs\": \"^17.7.1\"\n },\n \"devDependencies\": {\n \"@sindresorhus/tsconfig\": \"^2.0.0\",\n \"@types/bluebird\": \"^3.5.38\",\n \"@types/engine-check\": \"^1.1.1\",\n \"@types/stream-to-promise\": \"^2.2.1\",\n \"@types/yargs\": \"^17.0.22\",\n \"eslint-config-joelpurra\": \"github:joelpurra/eslint-config-joelpurra#semver:^v11.0.1\",\n \"husky\": \"^4.3.8\",\n \"rimraf\": \"^3.0.2\",\n \"type-fest\": \"^2.19.0\",\n \"typescript\": \"^4.9.5\",\n \"usb\": \"^2.8.0\",\n \"xo\": \"^0.48.0\"\n },\n \"engines\": {\n \"node\": \"^16.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0\"\n },\n \"keywords\": [\n \"usb\",\n \"usb video class\",\n \"uvc\",\n \"camera\",\n \"webcam\",\n \"webcamera\",\n \"controls\",\n \"configuration\",\n \"libusb\",\n \"libuvc\",\n \"uvc-control\"\n ],\n \"bugs\": {\n \"url\": \"https://github.com/joelpurra/uvcc/issues\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/joelpurra/uvcc.git\"\n },\n \"author\": {\n \"name\": \"Joel Purra\",\n \"email\": \"mig@joelpurra.se\",\n \"url\": \"https://joelpurra.com/\"\n },\n \"license\": \"GPL-3.0\",\n \"husky\": {\n \"hooks\": {\n \"pre-commit\": \"npm run --silent test\",\n \"pre-push\": \"npm run --silent test\"\n }\n }\n}\n"
},
{
"path": "src/camera-control-helper-factory.ts",
"content": "/*\nThis file is part of uvcc -- USB Video Class (UVC) device configurator.\nCopyright (C) 2018, 2019, 2020, 2021, 2022 Joel Purra \n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see .\n*/\n\nimport assert from \"node:assert\";\nimport {\n\tReadonlyDeep,\n} from \"type-fest\";\nimport Camera, {\n\tUvcControl,\n} from \"uvc-control\";\n\nimport CameraControlHelperClass from \"./camera-control-helper.js\";\n\nexport default class CameraControlHelperFactory {\n\tconstructor(\n\t\t// eslint-disable-next-line @typescript-eslint/naming-convention\n\t\tprivate readonly UvcControl: ReadonlyDeep,\n\t\t// eslint-disable-next-line @typescript-eslint/naming-convention\n\t\tprivate readonly CameraControlHelper: typeof CameraControlHelperClass,\n\t) {\n\t\tassert.strictEqual(arguments.length, 2);\n\t\tassert(typeof this.UvcControl === \"function\");\n\t\tassert(typeof this.CameraControlHelper === \"function\");\n\t}\n\n\tasync get(camera: ReadonlyDeep): Promise {\n\t\tassert.strictEqual(arguments.length, 1);\n\t\tassert(typeof camera === \"object\");\n\n\t\tconst cameraControlHelper = new this.CameraControlHelper(this.UvcControl, camera);\n\n\t\treturn cameraControlHelper;\n\t}\n}\n"
},
{
"path": "src/camera-control-helper.ts",
"content": "/*\nThis file is part of uvcc -- USB Video Class (UVC) device configurator.\nCopyright (C) 2018, 2019, 2020, 2021, 2022 Joel Purra \n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see .\n*/\n\nimport arrayNonUniq from \"array-non-uniq\";\nimport filterObject from \"filter-obj\";\nimport assert from \"node:assert\";\nimport sortKeys from \"sort-keys\";\nimport {\n\tReadonlyDeep,\n} from \"type-fest\";\nimport Camera,\n{\n\tCameraControl,\n\tUvcControl,\n} from \"uvc-control\";\n\nimport WrappedError from \"./utilities/wrapped-error.js\";\n\ninterface ControlFlags {\n\treadonly isGettable: boolean;\n\treadonly isRanged: boolean;\n\treadonly isSettable: boolean;\n}\n\ntype ControlsFlags = Record;\n\nexport default class CameraControlHelper {\n\tprivate cachedMappedSupportedControls: ReadonlyDeep | null = null;\n\n\tconstructor(\n\t\t// eslint-disable-next-line @typescript-eslint/naming-convention\n\t\tprivate readonly UvcControl: ReadonlyDeep,\n\t\tprivate readonly camera: ReadonlyDeep,\n\t) {\n\t\tassert.strictEqual(arguments.length, 2);\n\t\tassert(typeof this.UvcControl === \"function\");\n\t\tassert(typeof this.camera === \"object\");\n\t}\n\n\tasync getControlNames(): Promise {\n\t\tconst controls = await this.getSupportedControls();\n\n\t\treturn Object.keys(controls);\n\t}\n\n\tasync getGettableControlNames(): Promise {\n\t\tconst gettableControls = await this.getGettableControls();\n\n\t\treturn Object.keys(gettableControls);\n\t}\n\n\tasync getRangedControlNames(): Promise {\n\t\tconst rangedControls = await this.getRangedControls();\n\n\t\treturn Object.keys(rangedControls);\n\t}\n\n\tasync getSettableControlNames(): Promise {\n\t\tconst settableControls = await this.getSettableControls();\n\n\t\treturn Object.keys(settableControls);\n\t}\n\n\tprivate isGettableControl(control: ReadonlyDeep) {\n\t\t// NOTE: relies on uvc-control internals.\n\t\treturn control.requests.includes(this.UvcControl.REQUEST.GET_CUR);\n\t}\n\n\tprivate isRangedControl(control: ReadonlyDeep) {\n\t\t// NOTE: relies on uvc-control internals.\n\t\treturn control.requests.includes(this.UvcControl.REQUEST.GET_MIN)\n\t\t\t&& control.requests.includes(this.UvcControl.REQUEST.GET_MAX);\n\t}\n\n\tprivate isSettableControl(control: ReadonlyDeep) {\n\t\t// NOTE: relies on uvc-control internals.\n\t\treturn control.requests.includes(this.UvcControl.REQUEST.SET_CUR)\n\t\t\t|| (\n\t\t\t\t// TODO: treat optionally settable controls separately?\n\t\t\t\tArray.isArray(control.optional_requests)\n\t\t\t\t&& control.optional_requests.includes(this.UvcControl.REQUEST.SET_CUR)\n\t\t\t);\n\t}\n\n\tprivate async mapSupportedControls() {\n\t\tconst supportedControls = this.camera.supportedControls\n\t\t\t.map((supportedControlName) => this.UvcControl.controls[supportedControlName])\n\t\t\t// TODO: proper ducktyping function.\n\t\t\t.filter((t): t is CameraControl => Boolean(t));\n\n\t\tconst missingControls = supportedControls.filter((control) => !control);\n\n\t\tif (missingControls.length > 0) {\n\t\t\tthrow new Error(`Controls were not found: ${JSON.stringify(missingControls)}`);\n\t\t}\n\n\t\tconst nonUniqueControls = arrayNonUniq(supportedControls);\n\n\t\tif (nonUniqueControls.length > 0) {\n\t\t\tthrow new Error(`Controls were already found: ${JSON.stringify(nonUniqueControls)}`);\n\t\t}\n\n\t\tconst mappedControls = supportedControls.map((control) => {\n\t\t\ttry {\n\t\t\t\tconst uvccControl: [string, ControlFlags] = [\n\t\t\t\t\tcontrol.name,\n\t\t\t\t\t{\n\t\t\t\t\t\t// NOTE: minimal uvcc-specific mapping.\n\t\t\t\t\t\tisGettable: this.isGettableControl(control),\n\t\t\t\t\t\tisRanged: this.isRangedControl(control),\n\t\t\t\t\t\tisSettable: this.isSettableControl(control),\n\t\t\t\t\t},\n\t\t\t\t];\n\n\t\t\t\treturn uvccControl;\n\t\t\t} catch (error: unknown) {\n\t\t\t\tif (error instanceof Error) {\n\t\t\t\t\tconst wrappedError = new WrappedError(error, `Could not map control: ${JSON.stringify(control.name)}`);\n\n\t\t\t\t\tthrow wrappedError;\n\t\t\t\t}\n\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t});\n\n\t\tconst controlsObject: ControlsFlags = {};\n\n\t\tfor (const mappedControl of mappedControls) {\n\t\t\tcontrolsObject[mappedControl[0]] = mappedControl[1];\n\t\t}\n\n\t\tconst sortedControls = sortKeys(controlsObject);\n\n\t\treturn sortedControls;\n\t}\n\n\tprivate async getSupportedControls() {\n\t\tif (this.cachedMappedSupportedControls === null) {\n\t\t\tthis.cachedMappedSupportedControls = await this.mapSupportedControls();\n\t\t}\n\n\t\treturn this.cachedMappedSupportedControls;\n\t}\n\n\tprivate async getGettableControls() {\n\t\tconst controls = await this.getSupportedControls();\n\n\t\treturn filterObject(controls, (_key, control) => control.isGettable);\n\t}\n\n\tprivate async getRangedControls() {\n\t\tconst controls = await this.getSupportedControls();\n\n\t\treturn filterObject(controls, (_key, control) => control.isRanged);\n\t}\n\n\tprivate async getSettableControls() {\n\t\tconst controls = await this.getSupportedControls();\n\n\t\treturn filterObject(controls, (_key, control) => control.isSettable);\n\t}\n}\n"
},
{
"path": "src/camera-factory.ts",
"content": "/*\nThis file is part of uvcc -- USB Video Class (UVC) device configurator.\nCopyright (C) 2018, 2019, 2020, 2021, 2022 Joel Purra \n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see .\n*/\n\nimport assert from \"node:assert\";\nimport {\n\tReadonlyDeep,\n} from \"type-fest\";\nimport Camera, {\n\tConstructorOptions,\n\tUvcControl,\n} from \"uvc-control\";\n\nimport Output from \"./output.js\";\nimport toFormattedHex from \"./utilities/to-formatted-hex.js\";\nimport WrappedError from \"./utilities/wrapped-error.js\";\n\ninterface GetFunctionArguments {\n\taddress: number | null;\n\tproduct: number | null;\n\tvendor: number | null;\n}\n\nexport default class CameraFactory {\n\tconstructor(\n\t\tprivate readonly output: Output,\n\t\t// eslint-disable-next-line @typescript-eslint/naming-convention\n\t\tprivate readonly UvcControl: UvcControl,\n\t) {\n\t\tassert.strictEqual(arguments.length, 2);\n\t\tassert(typeof this.UvcControl === \"function\");\n\t}\n\n\tasync get(vendor: number | null, product: number | null, address: number | null): Promise {\n\t\tassert.strictEqual(arguments.length, 3);\n\t\tassert(vendor === null || (typeof vendor === \"number\" && vendor >= 0));\n\t\tassert(product === null || (typeof product === \"number\" && product >= 0));\n\t\tassert(address === null || (typeof address === \"number\" && address >= 0));\n\n\t\tconst constructorOptions: ConstructorOptions = {\n\t\t\t// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing\n\t\t\tdeviceAddress: address || undefined,\n\t\t\t// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing\n\t\t\tpid: product || undefined,\n\t\t\t// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing\n\t\t\tvid: vendor || undefined,\n\t\t};\n\n\t\ttry {\n\t\t\tconst camera = new this.UvcControl(constructorOptions);\n\n\t\t\tif (vendor && vendor !== camera.device.deviceDescriptor.idVendor) {\n\t\t\t\tthis.output.warning(\"Camera vendor id mismatch.\", \"Input\", vendor, `(${toFormattedHex(vendor, 4)})`, \"Actual\", camera.device.deviceDescriptor.idVendor, `(${toFormattedHex(camera.device.deviceDescriptor.idVendor, 4)})`);\n\t\t\t}\n\n\t\t\tif (product && product !== camera.device.deviceDescriptor.idProduct) {\n\t\t\t\tthis.output.warning(\"Camera product id mismatch.\", \"Input\", product, `(${toFormattedHex(product, 4)})`, \"Actual\", camera.device.deviceDescriptor.idProduct, `(${toFormattedHex(camera.device.deviceDescriptor.idProduct, 4)})`);\n\t\t\t}\n\n\t\t\tif (address && address !== camera.device.deviceAddress) {\n\t\t\t\tthis.output.warning(\"Camera device address mismatch.\", \"Input\", address, `(${toFormattedHex(address, 1)})`, \"Actual\", camera.device.deviceAddress, `(${toFormattedHex(camera.device.deviceAddress, 1)})`);\n\t\t\t}\n\n\t\t\treturn camera;\n\t\t} catch (error: unknown) {\n\t\t\tif (error instanceof Error) {\n\t\t\t\t// NOTE: basically a duplicate of both the arguments to this function and to the uvc-control constructor.\n\t\t\t\tconst getFunctionArguments: GetFunctionArguments = {\n\t\t\t\t\taddress,\n\t\t\t\t\tproduct,\n\t\t\t\t\tvendor,\n\t\t\t\t};\n\n\t\t\t\tconst wrappedError = this.createWrappedError(error, getFunctionArguments, constructorOptions);\n\n\t\t\t\tthrow wrappedError;\n\t\t\t}\n\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tprivate createWrappedError(error: ReadonlyDeep, getFunctionArguments: ReadonlyDeep, constructorOptions: ReadonlyDeep) {\n\t\tlet errorMessage = null;\n\n\t\t// NOTE: relies on uvc-control internals.\n\t\t// NOTE: may rely on user locale.\n\t\tconst guessThatUvcDeviceWasNotFound = typeof error.name === \"string\"\n\t\t\t&& error.name === \"TypeError\"\n\t\t\t&& typeof error.message === \"string\"\n\t\t\t&& (\n\t\t\t\t// NOTE: message formatting differs across versions; could use a regular expression instead.\n\t\t\t\terror.message === \"Cannot read property 'interfaces' of undefined\"\n\t\t\t\t|| error.message === \"Cannot read properties of undefined (reading 'interfaces')\"\n\t\t\t);\n\n\t\terrorMessage = guessThatUvcDeviceWasNotFound ? `Could not find UVC device. Is a compatible camera connected? ${JSON.stringify(getFunctionArguments)}` : `Could create uvc-control object: ${JSON.stringify(constructorOptions)}`;\n\n\t\terrorMessage += ` (${JSON.stringify(String(error))})`;\n\n\t\tconst wrappedError = new WrappedError(error, errorMessage);\n\n\t\treturn wrappedError;\n\t}\n}\n"
},
{
"path": "src/camera-helper-factory.ts",
"content": "/*\nThis file is part of uvcc -- USB Video Class (UVC) device configurator.\nCopyright (C) 2018, 2019, 2020, 2021, 2022 Joel Purra \n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see .\n*/\n\nimport assert from \"node:assert\";\nimport {\n\tReadonlyDeep,\n} from \"type-fest\";\nimport Camera from \"uvc-control\";\n\nimport CameraControlHelperFactory from \"./camera-control-helper-factory.js\";\nimport CameraHelperClass from \"./camera-helper.js\";\nimport Output from \"./output.js\";\n\nexport default class CameraHelperFactory {\n\tconstructor(\n\t\tprivate readonly output: ReadonlyDeep