Nokhwa(녹화): Korean word meaning "to record".
A Simple-to-use, cross-platform Rust Webcam Capture Library
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::*
.
// 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());
}
A command line app made with nokhwa
can be found in the examples
folder.
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 ) |
✅ | ✅ | ✅ | Linux |
MSMF(input-msmf ) |
✅ | ✅ | ✅ | Windows |
AVFoundation | 🚧 | 🚧 | 🚧 | Mac |
libuvc(input-uvc ) |
✅ | ✅ | ✅ | Linux, Windows, Mac |
OpenCV(input-opencv )^ |
✅ | ❌ | ❌ | Linux, Windows, Mac |
IPCamera(input-ipcam /OpenCV)^ |
✅ | ❌ | ❌ | Linux, Windows, Mac |
GStreamer(input-gst ) |
✅ | ✅ | ✅ | Linux, Windows, Mac |
JS/WASM(input-wasm ) |
✅ | ✅ | ✅ | Browser(Web) |
✅: Working, 🔮 : Experimental, ❌ : Not Supported, 🚧: Planned/WIP
^ = No CameraFormat setting support.
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 theVideo4Linux
backend. (linux)input-msmf
: Enables theMediaFoundation
backennd. (Windows 7 or newer)input-uvc
: Enables thelibuvc
backend. (cross-platform, libuvc statically-linked)input-opencv
: Enables theopencv
backend. (cross-platform)input-ipcam
: Enables the use of IP Cameras, please see theNetworkCamera
struct. Note that this relies onopencv
, so it will automatically enable theinput-opencv
feature.input-gst
: Enables thegstreamer
backend. (cross-platform)input-jscam
: Enables the use of theJSCamera
struct, which uses browser APIs. (Web)
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 awgpu
texture.output-wasm
: Generate WASM API binding specific functions.
Other features:
decoding
: Enablesmozjpeg
decoding. Enabled by default.small-wasm
: Enables size optimizations for WASM targets. Useswee_alloc
instead of default, LTO enabled,opt-level
set to "s" for size. Note that the LTO andopt-level
are only enabled if:--release
is enabled.- The target family is
wasm
--no-default-features
is enabled. (disablesmozjpeg
and MJPEG processing)
Please use the following command for wasm-pack
in order to get a functional WASM binary:
wasm-pack build --release -- --features "input-jscam, output-wasm, small-wasm, test-fail-warning" --no-default-features
docs-only
: Documentation feature. Enabled for docs.rs builds.docs-nolink
: Build documentation without linking to any libraries. Enabled for docs.rs builds.test-fail-warning
: Fails on warning. Enabled in CI. You many want to pick and choose to reduce bloat.
If you are making an issue, please make sure that
- It has not been made yet
- Attach what you were doing, your environment, steps to reproduce, and backtrace. Thank you!
Contributions are welcome!
- Please
rustfmt
all your code and adhere to the clippy lints (unless necessary not to do so) - Please limit use of
unsafe
- All contributions are under the MPL 2.0 license unless otherwise specified
nokhwa
may build on older versions of rustc
, but there is no guarantee except for the latest stable rust.