Crate nokhwa

nokhwa

Nokhwa(녹화): Korean word meaning “to record”.

A Simple-to-use, cross-platform Rust Webcam Capture Library

Using nokhwa

You will need the latest stable Rust and Cargo.

Nokhwa can be added to your crate by adding it to your Cargo.toml:

[dependencies.nokhwa]
// TODO: replace the "*" with the latest version of `nokhwa`
version = "*"
// TODO: add some features
features = [""]

Most likely, you will only use functionality provided by the Camera struct. If you need lower-level access, you may instead opt to use the raw capture backends found at nokhwa::backends::capture::*.

API Support

The table below lists current Nokhwa API support.

• The Backend column signifies the backend.
• The Input column signifies reading frames from the camera
• The Query column signifies system device list support
• The Query-Device column signifies reading device capabilities
• The Platform column signifies what Platform this is availible on.

Backend	Input	Query	Query-Device	Platform
Video4Linux(input-v4l)	YES	YES	YES	Linux
libuvc(input-uvc)	YES	YES	YES	Linux, Windows, Mac
OpenCV(input-opencv)^	YES	NO	NO	Linux, Windows, Mac
IPCamera(input-ipcam/OpenCV)^	YES	NO	NO	Linux, Windows, Mac
GStreamer(input-gst)^	YES	YES	YES	Linux, Windows, Mac
FFMpeg	*	*	*	Linux, Windows, Mac
AVFoundation	*	*	*	Mac
MSMF	*	*	*	Windows
JS/WASM	*	*	*	Web

*: Planned/WIP

^ = No CameraFormat setting support.

Feature

The default feature includes nothing. Anything starting with input-* is a feature that enables the specific backend. As a general rule of thumb, you would want to keep at least input-uvc or other backend that has querying enabled so you can get device information from nokhwa.

input-* features:

• input-v4l: Enables the Video4Linux backend (linux)
• input-uvc: Enables the libuvc backend (cross-platform, libuvc statically-linked)
• input-opencv: Enables the opencv backend (cross-platform)
• input-ipcam: Enables the use of IP Cameras, please see the NetworkCamera struct. Note that this relies on opencv, so it will automatically enable the input-opencv feature.
• input-gst: Enables the gstreamer backend (cross-platform).

Conversely, anything that starts with output-* controls a feature that controls the output of something (usually a frame from the camera)

output-* features:

• output-wgpu: Enables the API to copy a frame directly into a wgpu texture.

You many want to pick and choose to reduce bloat.

Example

// set up the Camera
let mut camera = Camera::new(
    0, // index
    Some(CameraFormat::new_from(640, 480, FrameFormat::MJPEG, 30)), // format
    CaptureAPIBackend::AUTO, // what backend to use (let nokhwa decide for itself)
)
.unwrap();
// open stream
camera.open_stream().unwrap();
loop {
    let frame = camera.get_frame().unwrap();
    println!("{}, {}", frame.width(), frame.height());
}

They can be found in the examples folder.

Modules

backends

Raw access to each of Nokhwa’s backends.

Structs

Camera

The main Camera struct. This is the struct that abstracts over all the backends, providing a simplified interface for use.

CameraFormat

This is a convenience struct that holds all information about the format of a webcam stream. It consists of a Resolution, FrameFormat, and a framerate(u8).

CameraInfo

Information about a Camera e.g. its name. description amd misc may contain backend-specific information. index is a camera’s index given to it by (usually) the OS usually in the order it is known to the system.

NetworkCamera

A struct that supports IP Cameras via the OpenCV backend.

Resolution

Describes a Resolution. This struct consists of a Width and a Height value (x,y).
Note: the Ord implementation of this struct is flipped from highest to lowest.

Enums

CameraIndexType

The OpenCV backend supports both native cameras and IP Cameras, so this is an enum to differentiate them The IPCamera’s string follows the pattern

CaptureAPIBackend

The list of known capture backends to the library.
Note: Only V4L2 and UVC (and by extension AUTO) is implemented so far.

FrameFormat

Describes a frame format (i.e. how the bytes themselves are encoded). Often called FourCC
YUYV is a mathematical color space. You can read more here.
MJPEG is a motion-jpeg compressed frame, it allows for high frame rates.

NokhwaError

All errors in nokhwa.

Traits

CaptureBackendTrait

This trait is for any backend that allows you to grab and take frames from a camera. Many of the backends are blocking, if the camera is occupied the library will block while it waits for it to become available.

VirtualBackendTrait

Functions

mjpeg_to_rgb888

Converts a MJPEG stream of u8 into a Vec of RGB888. (R,G,B,R,G,B,…)

query_devices

Query the system for a list of available devices. Please refer to the API Backends that support Query)
Currently, these are V4L, UVC, and GST.
Usually the order goes Native -> UVC -> Gstreamer.

yuyv422_to_rgb888

Converts a YUYV 4:2:2 datastream to a RGB888 Stream. For further reading

yuyv444_to_rgb888

Convert YCbCr 4:4:4 to a RGB888. For further reading