mirror of
https://github.com/l1npengtul/nokhwa.git
synced 2026-07-11 04:48:52 +00:00
l1npengtul
110 lines
5.6 KiB
Markdown
110 lines
5.6 KiB
Markdown
# nokhwa
|
|
Nokhwa(녹화): Korean word meaning "to record".
|
|
|
|
A Simple-to-use, cross-platform Rust Webcam Capture Library
|
|
|
|
## Using nokhwa
|
|
Nokhwa can be added to your crate by adding it to your `Cargo.toml`:
|
|
```.ignore
|
|
[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::*`.
|
|
|
|
## Example
|
|
|
|
```.ignore
|
|
// set up the Camera
|
|
let mut camera = Camera::new(
|
|
0, // index
|
|
Some(CameraFormat::new_from(640, 480, FrameFormat::MJPEG, 30)), // format
|
|
)
|
|
.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.
|
|
|
|
## 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`) | ✅ | ✅ | ✅ | Linux |
|
|
| MSMF(`input-msmf`) | ✅ | ✅ | ✅ | Windows |
|
|
| AVFoundation(`input-avfoundatuin`)^^| ✅ | ✅ | ✅ | 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.
|
|
^^ = No FPS 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-msmf`: Enables the `MediaFoundation` backennd. (Windows 7 or newer)
|
|
- `input-avfoundation`: Enables the `AVFoundation` backend. (MacOSX 10.7)
|
|
- `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)
|
|
- `input-jscam`: Enables the use of the `JSCamera` 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 a `wgpu` texture.
|
|
- `output-wasm`: Generate WASM API binding specific functions.
|
|
- `output-threaded`: Enable the threaded/callback based camera.
|
|
|
|
Other features:
|
|
- `decoding`: Enables `mozjpeg` decoding. Enabled by default.
|
|
- `small-wasm`: Enables size optimizations for WASM targets. Uses `wee_alloc` instead of default, LTO enabled, `opt-level` set to "s" for size. Note that the LTO and `opt-level` are only enabled if:
|
|
- `--release` is enabled.
|
|
- The target family is `wasm`
|
|
- `--no-default-features` is enabled. (disables `mozjpeg` and MJPEG processing)
|
|
|
|
Please use the following command for `wasm-pack` in order to get a functional WASM binary:
|
|
```.ignore
|
|
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.
|
|
|
|
## Issues
|
|
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!
|
|
|
|
## Contributing
|
|
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 Apache 2.0 license unless otherwise specified
|
|
|
|
## Minimum Service Rust Version
|
|
`nokhwa` may build on older versions of `rustc`, but there is no guarantee except for the latest stable rust.
|