v4l2-camera-ts

Camera library for Linux (V4L2) written in pure TypeScript using libv4l2-ts for the interaction with the kernel.

Features

• Capture frames into buffers
• Set & get controls
• Event interface for capturing frames and control changes

Installation

$ sudo apt install libv4l-dev # or your distros equivalent

$ npm install v4l2-camera-ts

Usage

An example of how to capture frames asynchronously:

import { Camera } from "v4l2-camera-ts";
import fsp from "fs/promises";

async function main() {
	const cam = new Camera();

	cam.open("/dev/video0");

	console.log(cam.queryFormat());

	// the format can only be set before starting
	cam.setFormat({ width: 1920, height: 1080, pixelFormatStr: "MJPG" });
	
	// allocate memory-mapped buffers and turn the stream on
	cam.start();

	// capture 10 frames and write them to JPEG files
	for (let i = 0; i < 10; i++) {
		// asynchronously wait until the camera fd is readable
		// and then exchange one of the memory-mapped buffers
		const frame = await cam.getNextFrame();

		await fsp.writeFile(`./test/frame-${i}.jpg`, frame);
	}

	// turn the stream off and unmap all buffers
	cam.stop();

	cam.close();
}

main();

Instead of using await cam.getNextFrame(), you can also use the event interface by calling cam.startCaptureThread() and then listening for the frame event.

You can find more examples in the scripts/ directory.

Methods & Classes

Camera

get opened: boolean
Returns if open() has been called already.

get started: boolean
Returns if start() has been called already.

get backgroundFrameCaptureEnabled: boolean
Returns if frames are being captured in the background and emitted as events.

get backgroundControlChangeEventsEnabled: boolean
Returns if control change events are being retrieved in the background and emitted as events.

open(path: string): void
Opens the camera at the specified path.

close(): void
Closes the camera. This needs to be the last operation done on the camera, otherwise its going to throw an error about the device being busy.

queryFormat(): GetCameraFormat
Fetches information about the currently set format from the camera. You can use this to determine if your setFormat call was successful.

setFormat(format: SetCameraFormat): void
Set the width, height, pixel format and optionally the fps of the camera. The fps can only be set for some pixel formats however (not for MJPG for example). You can use getSupportedFormatsExtended() to find all supported formats.

queryControls(): CameraControl[]
Returns a list of all controls on the camera as well as all menu entries for menu controls.

getControl(id: number): number
Get the current value for a control. Valid numbers for the id parameter can be found in v4l2_controls in libv4l2-ts. The constants always begin with V4L2_CID_.

setControl(id: number, value: number): number
Sets a control value. Valid numbers for the id parameter can be found in v4l2_controls in libv4l2-ts (always starting with V4L2_CID_) or taken from the output of queryControls(). The function returns the value that was provided in the value parameter.

start(bufferCount: number = 2): void
Create and memory map buffers which are used for data exchange and turn the video stream on. After this call returns, video frames can be retrieved with getNextFrame().

stop(): void
Stops the stream and unmaps all buffers. After this call, buffers returned from getNextFrame() should not be accessed anymore, so make sure to copy all the data out of them before stopping the stream.

async getNextFrame(): Promise<Buffer>
Wait for the next frame to be available, exchange a buffer with the driver and then return that buffer. The buffer will contain data in the format set by setFormat. The returned buffers are not normal Buffers however, since their underlying data points to a memory-mapped region that the V4L2 driver can write into. This means that you need to copy the data out of them (e.g. with Buffer.from(buf)), or they are going to get overwritten by a later call to getNextFrame().

enableBackgroundFrameCapture(): void
Starts a background thread that continuously captures frames from the camera. The frames are then emitted as frame events.

disableBackgroundFrameCapture(): void
Stops the background capture thread.

subscribeControlEvent(id: number, flags?: SubscribeEventFlags): void
Subscribe to control change events for the specified control ID. The optional flags.sendInitial flag can be used to send the current control value as an initial event. flags.allowFeedback controls whether events generated by this process should be sent back to it.

unsubscribeControlEvent(id: number): void
Unsubscribe from control change events for the specified control ID.

unsubscribeAllEvents(): void
Convenience method to unsubscribe from all control change events.

async getNextEvent(): Promise<CameraControlEvent | null>
Waits for the next event to be available and then retrieve it. If the returned event is not a valid control event, null is returned.

enableBackgroundControlChangeEvents(): void
Starts a background thread that continuously retrieves control change events from the camera. The events are then emitted as control-change events.

disableBackgroundControlChangeEvents(): void
Stops the background control events thread.

getCapabilities(): CameraCapabilities
Returns info about the camera including driver name, card name, bus info, driver version and supported capabilities.

getSupportedFormats(): SupportedCameraFormat[]
Returns a list of all supported camera formats.

getSupportedFormatsExtended(): SupportedCameraFormatExtended[]
Returns a list of all supported camera formats including all supported frame sizes and frame intervals (i.e. fps) for each format.

Utility Functions

listDevices(filter?: Partial<DeviceCapabilities>): Promise<DeviceListEntry[]>
Returns a list of all available V4L2 devices on the system, optionally filtered by the provided capabilities. The filters need to match exactly, so if you provide { videoCapture: true }, only devices that support video capture will be returned. The function is supposed to match the functionality of v4l2-ctl --list-devices, but as of right now it only checks and returns videoX devices.

Events

frame (data: Buffer)
Emitted when a new frame is captured with getNextFrame() or when background frame capture is enabled. The data parameter contains a buffer with the frame data which needs to be copied before the next frame is captured.

control-change (event: CameraControlEvent)
Emitted when a subscribed control changes its value and the event is retrieved with getNextEvent() or when background control change events are enabled. The event parameter contains information about the control change.