node-v4l2

Typesafe Video4Linux2 (V4L2) API for Node.js, written in TypeScript and talking to the kernel directly through syscalls.

• Named after what things are. Formats, fields, colorspaces, buffer flags, events and media bus codes use their V4L2 names ("V4L2_FIELD_NONE", "MEDIA_BUS_FMT_SRGGB10_1X10") instead of numbers.
• Only the arguments that make sense. The API is split by plane type, direction and memory type, so e.g. capture buffers are queued without bytesUsed, output buffers require it (and, for dmabufs, the length of the buffer area), and multi-plane buffers take a list of planes.
• Fortify. An optional checking layer validates requests before they reach the kernel (buffer state, dmabuf sizes, plane counts, device capabilities) and explains EINVALs the kernel returns.

Requirements

• Linux on x86_64 or arm64
• Node.js 24 or newer

Installation

npm install @k13engineering/v4l2

Usage

Capturing frames

import nodeFs from "node:fs";
import { openAndStealV4L2DeviceFd } from "@k13engineering/v4l2";

const fd = nodeFs.openSync("/dev/video0", "r+");
const device = openAndStealV4L2DeviceFd({ fd, fortify: true });

const captureApi = device.singlePlaneApi().captureApi();

const { error: formatError, resultingFormat } = captureApi.setFormat({
  format: { width: 1280, height: 720, pixelFormat: "YUYV" }
});
if (formatError !== undefined) {
  throw formatError;
}

const buffers = captureApi.mmapBufferApi();

const { error: requestError, countAllocated } = buffers.requestBuffers({ count: 4 });
if (requestError !== undefined) {
  throw requestError;
}

for (let index = 0; index < countAllocated; index += 1) {
  buffers.queueBuffer({ index });
}

captureApi.streamOn();

// the device fd is non-blocking: dequeueBuffer() reports no frame as undefined
setInterval(() => {
  const { error, dequeueInfo } = buffers.dequeueBuffer();
  if (error !== undefined) {
    throw error;
  }
  if (dequeueInfo === undefined) {
    return;
  }

  console.log(`frame ${dequeueInfo.sequence}: ${dequeueInfo.bytesUsed} of ${resultingFormat.sizeImage} bytes`);

  // hand the frame to other APIs as a dmabuf
  const { dmabufFd } = buffers.exportBuffer({
    index: dequeueInfo.index,
    accessMode: "O_RDONLY",
    openFlags: { O_CLOEXEC: true }
  });
  // ... use and close dmabufFd

  buffers.queueBuffer({ index: dequeueInfo.index });
}, 10);

When done, call captureApi.streamOff() and device.close().

Memory-to-memory devices and events

Codecs and converters use both directions of the same device, typically with multi-plane buffers:

const device = openAndStealV4L2DeviceFd({ fd, fortify: true });
const decoder = device.multiPlaneApi();

const bitstream = decoder.outputApi();
bitstream.setFormat({ format: { width: 1920, height: 1080, pixelFormat: "H264" } });

const bitstreamBuffers = bitstream.dmabufBufferApi();
bitstreamBuffers.requestBuffers({ count: 2 });
// length: the size of the dmabuf area holding the data, bytesUsed: the amount of data in it
bitstreamBuffers.queueBuffer({ index: 0, planes: [{ dmabufFd: h264DmabufFd, length: h264DmabufSize, bytesUsed: h264Size }] });

device.subscribeEvent({ type: "V4L2_EVENT_SOURCE_CHANGE", pad: 0 });

const { event } = device.dequeueEvent();
if (event?.type === "V4L2_EVENT_SOURCE_CHANGE" && event.changes.V4L2_EVENT_SRC_CH_RESOLUTION) {
  const { format } = decoder.captureApi().getFormat();
  // ... allocate decoded frame buffers for format.planes
}

Subdevices

const sensor = openAndStealV4L2DeviceFd({ fd: subdevFd, fortify: true });

const { resultingMediaBusFormat } = sensor.subdevApi()
  .pad({ padNumber: 0 })
  .whence({ which: "V4L2_SUBDEV_FORMAT_ACTIVE" })
  .setFormat({ mediaBusFormat: { width: 1920, height: 1080, code: "MEDIA_BUS_FMT_SRGGB10_1X10" } });

Finding devices

import { findV4L2DeviceByName, listV4L2Devices } from "@k13engineering/v4l2";

const camera = findV4L2DeviceByName({ name: "UVC Camera" });
// camera?.v4l2Name is e.g. "video0"

API overview

openAndStealV4L2DeviceFd({ fd, fortify })
├── queryCapabilities()
├── singlePlaneApi() / multiPlaneApi()
│   └── captureApi() / outputApi()
│       ├── enumFormats(), enumFrameSizes(), enumFrameIntervals()
│       ├── getFormat(), setFormat(), tryFormat()
│       ├── getCaptureParams(), setCaptureParams()   (capture)
│       ├── getOutputParams(), setOutputParams()     (output)
│       ├── streamOn(), streamOff()
│       └── dmabufBufferApi() / mmapBufferApi()
│           ├── requestBuffers(), queryBuffer()
│           ├── queueBuffer(), dequeueBuffer()
│           └── exportBuffer()                       (mmap)
├── subdevApi()
│   ├── queryDigitalVideoTimings()
│   └── pad({ padNumber }).whence({ which }).getFormat() / setFormat()
├── subscribeEvent(), unsubscribeEvent(), dequeueEvent()
├── borrowFileDescriptor()
└── close()

All types are exported from the package entry point.

Results and errors

Calls return { error, ... } objects. error is an Error with the errno of the failed syscall, so expected failures never throw:

const { error, format } = captureApi.getFormat();
if (error !== undefined) {
  console.error(`failed with errno ${error.errno}`);
}

"Nothing there" is not an error: queryBuffer() reports buffers that are not allocated, dequeueBuffer() an empty queue and dequeueEvent() no pending event as undefined.

Exceptions are reserved for broken contracts: when the kernel replies with something V4L2 does not allow (a different buffer type or index than requested, an unknown enumeration value), when a closed device is used, or when fortify finds that the device lacks a required capability.

Fortify

With fortify: true:

• singlePlaneApi(), multiPlaneApi(), captureApi(), outputApi() and the buffer APIs check the device capabilities, including memory-to-memory devices
• queueBuffer() checks that the buffer is allocated and not queued, that the number of planes matches the format, that dmabufs are dmabufs, large enough and not queued in another buffer, that the given length fits the format and the dmabuf, and that bytesUsed fits the length and the format
• setCaptureParams() / setOutputParams() check that the device supports setting the frame interval

Fortify errors start with fortify: and describe the problem. Without fortify the checks only run when the kernel rejected a buffer with EINVAL, to report the probable reason.

File descriptor ownership

openAndStealV4L2DeviceFd() takes over the file descriptor: it switches it to non-blocking mode and closes it in device.close(). A device that is garbage collected without close() raises an uncaught exception to point out the leak. borrowFileDescriptor() returns the fd for use with poll and similar, without transferring ownership.

Development

npm ci
npm run build       # transpile to dist/
npm run type-check
npm run test        # mocha with c8, 100% coverage required
npm run lint

The tests run against an in-memory emulation of a videobuf2 device (lib/test-support/), the real syscalls on ordinary files, and compile C programs against the installed kernel headers to verify the struct layouts, so gcc and the Linux UAPI headers are required.

License

LGPL-2.1, see LICENSE.