@anthonylzq/node-webcam

Cross platform webcam usage

Install

Requirements

• Node.js >=20.9.0.

Platform	Built-in/native path	Optional fallback requirements	Notes
Linux	Bundled native V4L2 prebuild for linux-x64	ffmpeg, then fswebcam	Other Linux architectures/libc variants fall back when no matching native prebuild exists.
macOS	None yet	ffmpeg, then imagesnap	Camera permissions are controlled by macOS and may require granting access to the terminal/app running Node.js.
Windows	None yet	ffmpeg with an explicit DirectShow device, then CommandCam.exe via setup	Run npx @anthonylzq/node-webcam setup windows for CommandCam fallback, or set NODE_WEBCAM_COMMANDCAM_PATH.

Versioning and migration from 2.x

Version 3.0.0 is a semver-major release line. It intentionally does not publish the new capture API as 2.x because several public APIs changed:

2.x behavior	3.x replacement
Factory root export	Use create(options) from the package root.
create(options, type) platform/backend override	Use create(options); backend selection is automatic and capability-aware.
capture({ type, returnType }) or responseType	Use capture({ location, options }); it always resolves to WebcamCaptureResult.
Buffer/base64 response modes	Use result.buffer or result.toBase64().
list(type) platform override	Use listWebcams({ timeout, signal }) or list() for the current platform.
Deep imports from dist/*	Import only from @anthonylzq/node-webcam.

The explicit root-only exports map is part of the 3.x contract. Backend implementations, native bindings, and build output paths are internal and may change without being exposed as supported subpaths.

Linux

Linux uses the bundled native V4L2 addon when a matching prebuild is available, then falls back to ffmpeg when it is installed, and finally to fswebcam. The native backend currently supports single-planar V4L2 streaming devices that accept MJPEG at the requested resolution exactly. Linux camera listing uses the same capability filter when the native addon is available, so multi-planar-only devices are not advertised until the capture path supports them. That filter uses synchronous native V4L2 open()/VIDIOC_QUERYCAP calls, so avoid running Linux camera listing on latency-sensitive request paths if you have unreliable camera drivers.

# Optional fallback backends
# ubuntu

sudo apt-get install ffmpeg fswebcam

# arch
# fswebcam requires a build from the AUR

yay -S ffmpeg fswebcam

Mac OSX

macOS uses ffmpeg when it is installed, then falls back to imagesnap.

# Optional preferred backend
brew install ffmpeg

# Legacy fallback backend
# Repo https://github.com/rharder/imagesnap

brew install imagesnap

Windows

Windows uses ffmpeg when it is installed and a camera device name is provided, then falls back to CommandCam.exe. CommandCam is installed by an explicit setup command so package installation does not depend on lifecycle scripts:

npx @anthonylzq/node-webcam setup windows

The setup command downloads the CommandCam release asset on Windows, verifies its SHA-256 checksum, and stores it in the user-local node-webcam cache. The CommandCam release tag and checksum are pinned in package.json and only need updates when that binary changes. Set NODE_WEBCAM_COMMANDCAM_PATH to use a manually installed executable instead.

On Windows, prefer device names returned by listWebcams() such as "Integrated Webcam". ffmpeg interprets device as a DirectShow device name. CommandCam supports the same friendly names with /devname and also supports 1-based numeric indexes with /devnum. Numeric strings such as "1" are treated as CommandCam indexes and skip ffmpeg selection. CommandCam only supports BMP output; requests for jpeg, jpg, or png require ffmpeg and fail clearly if the fallback would be CommandCam.

Backend selection

capture() and create() choose the first compatible available backend for the current platform. The public API does not require backend selection.

flowchart LR
  A["capture()"] --> B{"Platform"}
  B -->|Linux| C["native:v4l2"]
  C -->|unavailable| D["ffmpeg:v4l2"]
  D -->|unavailable| E["fswebcam"]
  B -->|macOS| F["ffmpeg:avfoundation"]
  F -->|unavailable| G["imagesnap"]
  B -->|Windows| H["ffmpeg:dshow"]
  H -->|unavailable| I["CommandCam"]

Loading

Platform	Selection order
Linux	native:v4l2 -> ffmpeg:v4l2 -> fswebcam
macOS	ffmpeg:avfoundation -> imagesnap
Windows	ffmpeg:dshow -> CommandCam

Backend capability checks can change that order:

Requested options	Eligible backends
Basic snapshots (width, height, output, device, timeout, save)	Native and ffmpeg backends are considered first when supported by the platform.
Legacy capture options (quality, delay, frames, title, subtitle, timestamp, greyScale, rotation, topBanner, bottomBanner, skip)	Legacy backends only: fswebcam, imagesnap, or CommandCam.
Explicit ffmpegPath on Linux	Skips native Linux and checks ffmpeg first.
signal cancellation	Uses command backends; native Linux capture is skipped because the addon does not yet accept AbortSignal.
bmp output	Requires a BMP-capable backend: ffmpeg on Linux/macOS/Windows or CommandCam on Windows. The fswebcam Linux fallback rejects BMP before command execution.

Selection is re-evaluated for each create() call so camera hotplug, PATH, environment, and permission changes are not hidden by a global cache. ffmpeg availability is checked with ffmpeg -version; it does not open or capture from the camera during selection. The probe has its own short timeout, even when capture timeout is disabled. ffmpeg selection also requires a compatible device signal: Linux devices must exist and pass the V4L2 capture-capability filter when the native probe is available, macOS requires an explicit AVFoundation device, and Windows numeric device strings are reserved for CommandCam. The non-destructive ffmpeg check does not prove that a DirectShow or AVFoundation device name exists; invalid names fail during capture and do not trigger another backend fallback after capture has started. clearBackendCaches() is exported for forwards compatibility and also backs the deprecated clearBackendSelectionCache() alias.

Fallback only happens while selecting a backend. If the selected backend starts a capture and fails because of permissions, an invalid device, a timeout, or an unsupported format, the error is surfaced instead of silently trying the next backend. The backend used for a capture is available as result.backend and result.backendType.

Native webcam performance

The Linux native V4L2 backend avoids spawning a CLI for every capture, so it is usually faster for repeated webcam snapshots. Local benchmark snapshot:

Backend	100 captures total	Mean	Median	p95	Avg bytes
native:v4l2	28.92s	289.24ms	287.97ms	288.72ms	163,029
fswebcam	36.16s	361.59ms	365.52ms	371.97ms	96,015
ffmpeg:v4l2	37.51s	375.09ms	370.60ms	385.05ms	59,196

Relative mean latency, scaled to the slowest backend in this run:

Backend	Mean latency	Relative bar
native:v4l2	289.24ms	███████████████░░░░░
fswebcam	361.59ms	███████████████████░
ffmpeg:v4l2	375.09ms	████████████████████

Benchmark environment: Linux, /dev/video0, 1280x720, 100 captures per backend. Results vary by camera, driver, resolution, codec, CPU, and whether the first capture is warmed up.

Reproduce locally:

npm run benchmark:capture -- --iterations=100 --warmup=3 --backends=native,ffmpeg,fswebcam

The benchmark writes JSON and Markdown reports under tmp/:

tmp/benchmark-results.json
tmp/benchmark-results.md
tmp/benchmarks/<run-id>/results.json
tmp/benchmarks/<run-id>/results.md

Usage

API Usage

All supported public APIs are exported from the package root:

import {
  capture,
  clearBackendCaches,
  create,
  defaults,
  getMetricsReport,
  listWebcams,
  resetMetrics,
  WebcamError,
  type NodeWebcamConfig,
  type WebcamCaptureResult
} from '@anthonylzq/node-webcam'

Deep imports such as @anthonylzq/node-webcam/dist/* are intentionally not supported. The package uses an explicit exports map so internal build layout, native bindings, and backend implementations can change without becoming public API.

• The simplest use case:

  import { capture } from '@anthonylzq/node-webcam'
  
  const main = async () => {
    const result = await capture({
      location: 'picture.jpeg'
    })
  
    console.log('buffer', result.buffer)
    console.log('base64', result.toBase64())
  }

  On Windows without an eligible ffmpeg device, the CommandCam fallback only supports BMP output. Use a .bmp location there, or install/configure ffmpeg for jpeg, jpg, or png captures.

• In case you want to use another file type such as jpg, png or bmp you must indicate it in the options object, otherwise you will get an error:

  import { capture } from '@anthonylzq/node-webcam'
  
  const main = async () => {
    const result = await capture({
      location: 'picture.png',
      options: {
        output: 'png'
      }
    })
  
    console.log('buffer', result.buffer)
  }

  This is because in order to build the captured image correctly the file extension and output type must match.

• If you only need the returned buffer and want to skip file persistence, set save to false:

  import { capture } from '@anthonylzq/node-webcam'
  
  const result = await capture({
    location: 'picture.jpeg',
    options: {
      save: false
    }
  })
  
  console.log(result.buffer)

  You can also provide a custom save handler:

  await capture({
    location: 'picture.jpeg',
    options: {
      save: async (path, buffer) => {
        await uploadSomewhere(path, buffer)
        return false
      }
    }
  })

• In case you need something more advance you can use the create function that will give you a class that will handle the usage of the webcam for you.

  import { create } from '@anthonylzq/node-webcam'
  
  const webcam = create()

• In case you want to list the available cameras in your OS, you can use the listWebcams function:

  import { listWebcams } from '@anthonylzq/node-webcam'
  
  const cameras = await listWebcams()

• The default configuration for all the webcams classes and methods can be found in the defaults object:

  import { defaults } from '@anthonylzq/node-webcam'
  
  console.log(defaults)
  /**
   * {
   *   width: 1280,
   *   height: 720,
   *   quality: 100,
   *   delay: 0,
   *   title: '',
   *   subtitle: '',
   *   timestamp: '',
   *   save: true,
   *   saveShots: true,
   *   output: 'jpeg',
   *   device: '',
   *   verbose: false,
   *   timeout: 0,
   *   frames: 1,
   *   greyScale: false,
   *   rotation: 0,
   *   bottomBanner: false,
   *   topBanner: false,
   *   skip: 0
   * }
   */

• In case you want aggregate capture metrics, you can use the optional metrics helpers:

  import { getMetricsReport, resetMetrics } from '@anthonylzq/node-webcam'
  
  const metrics = getMetricsReport()
  
  console.log(metrics.captures.total)
  console.log(metrics.captures.averageElapsedMs)
  
  resetMetrics()

Maintainer packaging

Publishing is manual. The only supported release-candidate command is:

npm run publish:check

That command rebuilds the Linux x64 glibc native prebuild, writes prebuilds/native-manifest.json, and runs the package validator. The validator checks that the manifest hashes match the native sources, binding.gyp, and the bundled .node prebuild so stale native artifacts fail before publication. Direct npm pack runs a prepack freshness check, but it does not rebuild the native prebuild; use it only for local inspection, not publication. Never publish a tarball produced with npm pack --ignore-scripts because that skips the freshness checks entirely.

Author

• Charlie Abeling - Initial Work - Documentation - chuckfairy.

Maintainers

• Anthony Luzquiños - Rework - Documentation - AnthonyLzq.