Camera 1: Spike — camera capture on Linux: V4L2, PipeWire or a crate (#953) #975

Closed
charles wants to merge 0 commits from camera-1-spike-capture-linux into camera
Owner

What this builds

The Linux camera capture spike (Camera 1). The spike succeeded: Camera 10 uses V4L2 through the v4l crate 0.14.0 (feature v4l2 only, no libv4l). The evidence is in docs/superpowers/research/2026-11-19-camera-spikes.md §1.

  • The choice, test by test (spikes §1.1). cargo deny is green. v4l gives mode enumeration (formats, sizes, intervals), memory-mapped streaming, and the raw errno of open and of every ioctl, STREAMON included. Dropping the stream and the device closes the descriptor synchronously. Each claim cites a file and line of the crate source.
  • The crate's panics (spikes §1.3). v4l panics on some device answers. query_caps calls from_utf8().unwrap() on the card name. format/set_format expect every colour space they know, and they miss V4L2_COLORSPACE_BT878. enum_formats does the same from_utf8().unwrap() on the format description. The Drop of the stream and of its buffers panics on any error except ENODEV. For each of these the table names what Camera 10 calls instead: the raw ioctl through v4l::v4l2::ioctl with v4l::v4l_sys structures, an explicit stop before drop, and the session run under catch_unwind. The probe already follows these rules.
  • Other candidates (spikes §1.2). nokhwa's Linux back end is built on v4l itself, so it has the same panics plus coarse errors. Its listing opens no device, which settles that "unverified" in spec §7.1. It was not chosen, and neither was PipeWire (Q1).
  • camera::v4l2_sysfs. list(root) -> Vec<(name, node, by_id)> returns the video<N> nodes with sysfs index 0, plus their dev/v4l/by-id links. nodes(root) returns every node, for the probe, and clean_name cleans the names. It reads sysfs and links only, never opens a node, and is pure over a root path.
  • V4L2 facts for Camera 10 (spikes §1.5), read from the kernel sources at master: EACCES/EPERM → not allowed. EBUSY comes from S_FMT, S_PARM, REQBUFS or STREAMON on UVC, because UVC never refuses a second open. After an unplug, ioctls return ENODEV and poll reports EPOLLERR|EPOLLHUP|EPOLLPRI. The owner's close stops streaming. Also covered: how a metadata node shows in sysfs and in device_caps.
  • examples/camera_probe.rs with list, modes <n> and capture <n> [seconds] [FOURCC] [WxH]. It writes no file, prints no picture data, and shows by-id links as a short hash. It refuses to do anything with FLUXER_CAMERA_FORBID set. [[example]] test = true runs its pure tests under cargo test.
  • README: the camera module row, a "Cameras on Linux" section with the probe commands, and the new dependency.

How it was tested

  • Tests that open nothing: sysfs_lists_capture_nodes_only (a temp tree with a UVC camera's two nodes, a loopback and a sub-device), sysfs_missing_dir_is_empty, names_are_cleaned, nodes_are_ordered_by_number_and_tolerate_missing_attributes, by_id_link_to_another_node_or_dangling_is_ignored. In the probe: probe_refuses_when_forbidden, commands_parse, bad_commands_are_refused. Each was seen failing before its implementation.
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci passes locally (fmt, clippy, deny, core isolation, parity, tests, screenshots).
  • No camera was opened. I did not run the probe and touched no /dev/video*. On this machine I only read sysfs and the /dev/v4l/by-id link names, to check the listing rule's assumption: one UVC webcam gives index 0 and 1. No FLUXER_DESKTOP_TESTS / FLUXER_CAMERA_TESTS tests exist or were run.

What Charles checks

The probe commands of spikes §1.6, also posted as a comment on #953 (non-blocking):
camera_probe list, modes 0, capture 0. Check that the light stays off for list and modes, and goes off when capture prints closed. Paste the output into #953; it settles spec §19 Q4.

Deviations from the plan

  • v4l is a Linux dev-dependency of fluxer-capture for now, because only the probe uses it. Camera 10 moves it to [dependencies].
  • crates/fluxer-capture/src/camera/mod.rs is created here with only pub mod v4l2_sysfs; (Linux), and lib.rs gains pub mod camera;. Both are registration files, so Camera 2 (mf_errors) and Camera 6 add their lines next to it.
  • v4l2_sysfs is Linux-only (cfg(target_os = "linux")): the tests build symlink trees with std::os::unix.
  • Beyond the plan's four tests I added nodes, SysfsNode, clean_name and two more tests. A loopback node (OBS virtual camera) counts as a camera, as in browsers.
  • The decision rule did not ask about panics. Section 1.3 records them because device data must not panic the client.

Closes #953

🤖 Generated with Claude Code

https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K

## What this builds The Linux camera capture spike (Camera 1). The spike succeeded: Camera 10 uses **V4L2 through the `v4l` crate 0.14.0** (feature `v4l2` only, no libv4l). The evidence is in `docs/superpowers/research/2026-11-19-camera-spikes.md` §1. - **The choice, test by test** (spikes §1.1). `cargo deny` is green. `v4l` gives mode enumeration (formats, sizes, intervals), memory-mapped streaming, and the raw `errno` of `open` and of every ioctl, `STREAMON` included. Dropping the stream and the device closes the descriptor synchronously. Each claim cites a file and line of the crate source. - **The crate's panics** (spikes §1.3). `v4l` panics on some device answers. `query_caps` calls `from_utf8().unwrap()` on the card name. `format`/`set_format` `expect` every colour space they know, and they miss `V4L2_COLORSPACE_BT878`. `enum_formats` does the same `from_utf8().unwrap()` on the format description. The `Drop` of the stream and of its buffers panics on any error except `ENODEV`. For each of these the table names what Camera 10 calls instead: the raw ioctl through `v4l::v4l2::ioctl` with `v4l::v4l_sys` structures, an explicit `stop` before drop, and the session run under `catch_unwind`. The probe already follows these rules. - **Other candidates** (spikes §1.2). `nokhwa`'s Linux back end is built on `v4l` itself, so it has the same panics plus coarse errors. Its listing opens no device, which settles that "unverified" in spec §7.1. It was not chosen, and neither was PipeWire (Q1). - **`camera::v4l2_sysfs`**. `list(root) -> Vec<(name, node, by_id)>` returns the `video<N>` nodes with sysfs `index` 0, plus their `dev/v4l/by-id` links. `nodes(root)` returns every node, for the probe, and `clean_name` cleans the names. It reads sysfs and links only, never opens a node, and is pure over a root path. - **V4L2 facts for Camera 10** (spikes §1.5), read from the kernel sources at master: `EACCES`/`EPERM` → not allowed. `EBUSY` comes from `S_FMT`, `S_PARM`, `REQBUFS` or `STREAMON` on UVC, because UVC never refuses a second `open`. After an unplug, ioctls return `ENODEV` and `poll` reports `EPOLLERR|EPOLLHUP|EPOLLPRI`. The owner's `close` stops streaming. Also covered: how a metadata node shows in sysfs and in `device_caps`. - **`examples/camera_probe.rs`** with `list`, `modes <n>` and `capture <n> [seconds] [FOURCC] [WxH]`. It writes no file, prints no picture data, and shows by-id links as a short hash. It refuses to do anything with `FLUXER_CAMERA_FORBID` set. `[[example]] test = true` runs its pure tests under `cargo test`. - README: the `camera` module row, a "Cameras on Linux" section with the probe commands, and the new dependency. ## How it was tested - Tests that open nothing: `sysfs_lists_capture_nodes_only` (a temp tree with a UVC camera's two nodes, a loopback and a sub-device), `sysfs_missing_dir_is_empty`, `names_are_cleaned`, `nodes_are_ordered_by_number_and_tolerate_missing_attributes`, `by_id_link_to_another_node_or_dangling_is_ignored`. In the probe: `probe_refuses_when_forbidden`, `commands_parse`, `bad_commands_are_refused`. Each was seen failing before its implementation. - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` passes locally (fmt, clippy, deny, core isolation, parity, tests, screenshots). - **No camera was opened.** I did not run the probe and touched no `/dev/video*`. On this machine I only read sysfs and the `/dev/v4l/by-id` link names, to check the listing rule's assumption: one UVC webcam gives index 0 and 1. No `FLUXER_DESKTOP_TESTS` / `FLUXER_CAMERA_TESTS` tests exist or were run. ## What Charles checks The probe commands of spikes §1.6, also posted as a comment on #953 (non-blocking): `camera_probe list`, `modes 0`, `capture 0`. Check that the light stays off for `list` and `modes`, and goes off when `capture` prints `closed`. Paste the output into #953; it settles spec §19 Q4. ## Deviations from the plan - `v4l` is a **Linux dev-dependency** of `fluxer-capture` for now, because only the probe uses it. Camera 10 moves it to `[dependencies]`. - `crates/fluxer-capture/src/camera/mod.rs` is created here with only `pub mod v4l2_sysfs;` (Linux), and `lib.rs` gains `pub mod camera;`. Both are registration files, so Camera 2 (`mf_errors`) and Camera 6 add their lines next to it. - `v4l2_sysfs` is Linux-only (`cfg(target_os = "linux")`): the tests build symlink trees with `std::os::unix`. - Beyond the plan's four tests I added `nodes`, `SysfsNode`, `clean_name` and two more tests. A loopback node (OBS virtual camera) counts as a camera, as in browsers. - The decision rule did not ask about panics. Section 1.3 records them because device data must not panic the client. Closes #953 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Refs #953

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
The probe lists cameras from sysfs, enumerates modes and captures for a few
seconds, printing names, modes, rates and timings only. Refuses to run with
FLUXER_CAMERA_FORBID set. v4l 0.14 (feature v4l2) as a Linux dev-dependency.

Refs #953

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Spikes §1: V4L2 through the v4l crate 0.14 (feature v4l2), with the calls
Camera 10 must not use (they panic on some device answers) and the raw
ioctls that replace them; the sysfs listing rule (index 0) and its gaps;
the errno of busy, gone and not allowed from the kernel sources; what
Charles runs with camera_probe. README: the camera module and the probe.

Refs #953

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Author
Owner

Merged into camera by hand (add/add conflicts with Camera 2 in camera/mod.rs, lib.rs and the spikes document resolved: both kept).

Merged into `camera` by hand (add/add conflicts with Camera 2 in camera/mod.rs, lib.rs and the spikes document resolved: both kept).
charles closed this pull request 2026-11-19 22:29:20 +00:00

Pull request closed

Sign in to join this conversation.
No description provided.