Camera 10: fluxer-capture camera on Linux (V4L2) (#962) #985

Closed
charles wants to merge 0 commits from camera-10-capture-camera-on-linux into camera
Owner

What

The Linux camera back end, fluxer_capture::camera::v4l2::V4l2Camera: CameraCapturer (V4L2 through v4l 0.14, Camera 1's choice), and camera::v4l2_errors (pure errno → CameraError table, every OS). default_camera() is now V4l2Camera on Linux (still Unsupported elsewhere until Camera 11).

  • list: sysfs only (v4l2_sysfs::list); id = the /dev/v4l/by-id link, else the node; names through names::display.
  • watch: no inotify crate in the tree, so a 2 s re-list of sysfs on a thread (WATCH_INTERVAL); opens nothing; a second watch replaces the callback; it stops on drop.
  • modes: opens, enumerates every format/size/rate (stepwise ranges sampled at common sizes and rates and the target, never expanded), closes. Refused under FLUXER_CAMERA_FORBID too, since it opens the device.
  • start: forbidden() first, then on the session thread open → VIDIOC_QUERYCAP (capture + streaming, else Backend("not a video capture device"), spec Q4) → modes → format::choose → VIDIOC_S_FMT / VIDIOC_S_PARM (what the driver gave is what Started reports) → mmap buffers → VIDIOC_STREAMON, all before start returns. Any failure is mapped (EBUSY → Busy, EACCES/EPERM → NotAllowed, ENOENT/ENODEV/ENXIO → NotFound, else Backend("<ioctl>: <ERRNO>")) and the thread is joined, so the descriptor is closed and the sink dropped before start returns.
  • Capture thread: drops V4L2_BUF_FLAG_ERROR frames, paces frames faster than the target (Pacer with half a device interval of slack, so jitter does not drop frames at the target rate), decodes to I420 (decode::to_i420, bytesused respected for MJPEG), fits (format::fit), Stalled/Resumed from StallDetector; an undecodable frame is dropped and counted (dropped_frames()) with one Error per session; ENODEV → Ended(DeviceLost) after closing; another DQBUF error → Error + Ended. A start right after Ended works without stop.
  • stop/Drop: sets the flag and joins the thread (100 ms poll slice); stream off and descriptor closed before return.
  • Spike §1.3 rules kept: raw ioctls for QUERYCAP, ENUM_FMT, G_FMT/S_FMT; no to_discrete; stream stopped before drop; the session body under catch_unwind (a panic in the crate's Drop becomes Error + Ended, never reported after stop). The crate's next() re-queues its last buffer before waiting, so a timed-out next would queue a buffer twice: the back end polls the descriptor itself and calls next only when a buffer is ready, and queues buffers 1..n itself before STREAMON so that STREAMON's answer is start's (the first next queues buffer 0). Reviewer: please read RealDevice::stream_on / dequeue with v4l 0.14.0's io/mmap/stream.rs open.
  • Capture cards (owner decision): every enumerated mode is listed and selectable, nothing is mirrored, the sink does not know its consumer, devices are opened by id and a second consumer gets the kernel's EBUSY → Busy.
  • Logs: device name, id_hash, layout/size/fps, setup time, frame and drop counts. No frame bytes, no path, no std::fs writes.

How it was tested

tests/camera_v4l2.rs (26 tests) over camera::v4l2::memory::MemoryIo (feature fake: recorded mode lists and buffers, scripted failures per step, counters opened/open_now/streaming_now/stream_ons) and a temporary sysfs tree: errno_table, chooses_mode_and_reports_what_driver_gave, yuyv_and_mjpeg_buffers_become_i420 (the MJPEG case uses fixtures/media/camera_frame_420.jpg), bad_mjpeg_frame_is_dropped_and_counted, enodev_mid_stream_is_device_lost (closed before Ended is delivered, and restartable), stop_closes_descriptor_before_returning, busy_at_streamon_closes_descriptor, forbidden_env_refuses_before_open, list_reads_sysfs_only (open counter 0), plus watch (plug/unplug, metadata node ignored, replaced callback, nothing after drop), modes, pacing, stall/resume, driver-adjusted size, missing S_PARM, non-capture node, unusable formats, already-started, choice by id, and real_back_end_refuses_under_the_switch (runs only when FLUXER_CAMERA_FORBID is set). Unit tests in v4l2.rs: capability bits equal the header's, stepwise sampling (step 0 safe), interval ranges, the frame gate; in v4l2_errors.rs: names and the kernel's own texts for the numbers.

FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci is green locally (screenshot step included). It had to run with TMPDIR on disk: /tmp (tmpfs) was full of leaked /tmp/appimage_extracted_* directories from earlier gate runs, which made xtask/tests/package.rs fail; reported as #983, nothing deleted.

No camera was opened: no agent ran camera_probe, camera_real or anything with FLUXER_CAMERA_TESTS; every manual cargo test ran with FLUXER_CAMERA_FORBID=1; the tests read only temporary sysfs trees, never the real one. No FLUXER_DESKTOP_TESTS test was run (none is needed here).

What Charles checks (real camera, by hand)

FLUXER_CAMERA_TESTS=1 cargo test -p fluxer-capture --test camera_real -- --ignored --nocapture

Expected: the camera listed by name, a mode count, started: WxH at N fps, the first frame within a second or two, at least 20 frames in 5 s, mean brightness well above 16 in a lit room, stop took well under a second, and the second open succeeding. Then:

  1. The light goes off as soon as the test prints its summary line (and the test process ends with it off).
  2. Busy: cargo run -p fluxer-capture --example camera_probe -- capture 0 20 in one terminal and the test in another: the test's start fails with "the camera is in use by another program".
  3. Unplug the camera during the 5 s capture: the output shows Ended(DeviceLost); plug it back in and camera_probe list shows it again.

Deviations from the plan

  • Hot-plug is a 2 s sysfs re-list, not inotify (no inotify crate in the tree; the plan allows it).
  • modes also honours FLUXER_CAMERA_FORBID (it opens the device); the trait only required it of start.
  • V4l2Io has a forbidden() method (the kernel's reads the environment; the in-memory one is scripted), so the in-memory tests run under CI's FLUXER_CAMERA_FORBID=1 while forbidden_env_refuses_before_open still proves the refusal comes before any open.
  • tests/camera_fake.rs's default_camera_is_unsupported_until_the_back_ends_land is now cfg(not(target_os = "linux")) (on Linux the default is the real back end, which no test may start; Camera 11 will narrow it further). Otherwise only the task's files, plus a comment in src/lib.rs.
  • v4l moved from [dev-dependencies] to the Linux [dependencies] (already in Cargo.lock; cargo deny green).
  • Strings: none copied (no user-facing text in this task).

Closes #962

🤖 Generated with Claude Code

https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K

## What The Linux camera back end, `fluxer_capture::camera::v4l2::V4l2Camera: CameraCapturer` (V4L2 through `v4l` 0.14, Camera 1's choice), and `camera::v4l2_errors` (pure `errno` → `CameraError` table, every OS). `default_camera()` is now `V4l2Camera` on Linux (still `Unsupported` elsewhere until Camera 11). - `list`: sysfs only (`v4l2_sysfs::list`); id = the `/dev/v4l/by-id` link, else the node; names through `names::display`. - `watch`: no inotify crate in the tree, so **a 2 s re-list** of sysfs on a thread (`WATCH_INTERVAL`); opens nothing; a second `watch` replaces the callback; it stops on drop. - `modes`: opens, enumerates every format/size/rate (stepwise ranges sampled at common sizes and rates and the target, never expanded), closes. Refused under `FLUXER_CAMERA_FORBID` too, since it opens the device. - `start`: `forbidden()` first, then on the session thread `open` → `VIDIOC_QUERYCAP` (capture + streaming, else `Backend("not a video capture device")`, spec Q4) → modes → `format::choose` → `VIDIOC_S_FMT` / `VIDIOC_S_PARM` (what the driver gave is what `Started` reports) → mmap buffers → `VIDIOC_STREAMON`, **all before `start` returns**. Any failure is mapped (`EBUSY` → `Busy`, `EACCES`/`EPERM` → `NotAllowed`, `ENOENT`/`ENODEV`/`ENXIO` → `NotFound`, else `Backend("<ioctl>: <ERRNO>")`) and the thread is joined, so the descriptor is closed and the sink dropped before `start` returns. - Capture thread: drops `V4L2_BUF_FLAG_ERROR` frames, paces frames faster than the target (`Pacer` with half a device interval of slack, so jitter does not drop frames at the target rate), decodes to I420 (`decode::to_i420`, `bytesused` respected for MJPEG), fits (`format::fit`), `Stalled`/`Resumed` from `StallDetector`; an undecodable frame is dropped and counted (`dropped_frames()`) with one `Error` per session; `ENODEV` → `Ended(DeviceLost)` after closing; another `DQBUF` error → `Error` + `Ended`. A `start` right after `Ended` works without `stop`. - `stop`/`Drop`: sets the flag and joins the thread (100 ms poll slice); stream off and descriptor closed before return. - Spike §1.3 rules kept: raw ioctls for `QUERYCAP`, `ENUM_FMT`, `G_FMT`/`S_FMT`; no `to_discrete`; stream stopped before drop; the session body under `catch_unwind` (a panic in the crate's `Drop` becomes `Error` + `Ended`, never reported after `stop`). The crate's `next()` re-queues its last buffer before waiting, so a timed-out `next` would queue a buffer twice: the back end polls the descriptor itself and calls `next` only when a buffer is ready, and queues buffers 1..n itself before `STREAMON` so that `STREAMON`'s answer is `start`'s (the first `next` queues buffer 0). Reviewer: please read `RealDevice::stream_on` / `dequeue` with `v4l` 0.14.0's `io/mmap/stream.rs` open. - Capture cards (owner decision): every enumerated mode is listed and selectable, nothing is mirrored, the sink does not know its consumer, devices are opened by id and a second consumer gets the kernel's `EBUSY` → `Busy`. - Logs: device name, `id_hash`, layout/size/fps, setup time, frame and drop counts. No frame bytes, no path, no `std::fs` writes. ## How it was tested `tests/camera_v4l2.rs` (26 tests) over `camera::v4l2::memory::MemoryIo` (feature `fake`: recorded mode lists and buffers, scripted failures per step, counters `opened`/`open_now`/`streaming_now`/`stream_ons`) and a temporary sysfs tree: `errno_table`, `chooses_mode_and_reports_what_driver_gave`, `yuyv_and_mjpeg_buffers_become_i420` (the MJPEG case uses `fixtures/media/camera_frame_420.jpg`), `bad_mjpeg_frame_is_dropped_and_counted`, `enodev_mid_stream_is_device_lost` (closed before `Ended` is delivered, and restartable), `stop_closes_descriptor_before_returning`, `busy_at_streamon_closes_descriptor`, `forbidden_env_refuses_before_open`, `list_reads_sysfs_only` (open counter 0), plus watch (plug/unplug, metadata node ignored, replaced callback, nothing after drop), modes, pacing, stall/resume, driver-adjusted size, missing `S_PARM`, non-capture node, unusable formats, already-started, choice by id, and `real_back_end_refuses_under_the_switch` (runs only when `FLUXER_CAMERA_FORBID` is set). Unit tests in `v4l2.rs`: capability bits equal the header's, stepwise sampling (step 0 safe), interval ranges, the frame gate; in `v4l2_errors.rs`: names and the kernel's own texts for the numbers. `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` is green locally (screenshot step included). It had to run with `TMPDIR` on disk: `/tmp` (tmpfs) was full of leaked `/tmp/appimage_extracted_*` directories from earlier gate runs, which made `xtask/tests/package.rs` fail; reported as #983, nothing deleted. **No camera was opened**: no agent ran `camera_probe`, `camera_real` or anything with `FLUXER_CAMERA_TESTS`; every manual `cargo test` ran with `FLUXER_CAMERA_FORBID=1`; the tests read only temporary sysfs trees, never the real one. No `FLUXER_DESKTOP_TESTS` test was run (none is needed here). ## What Charles checks (real camera, by hand) ```text FLUXER_CAMERA_TESTS=1 cargo test -p fluxer-capture --test camera_real -- --ignored --nocapture ``` Expected: the camera listed by name, a mode count, `started: WxH at N fps`, the first frame within a second or two, at least 20 frames in 5 s, mean brightness well above 16 in a lit room, `stop took` well under a second, and the second open succeeding. Then: 1. The light goes off as soon as the test prints its summary line (and the test process ends with it off). 2. `Busy`: `cargo run -p fluxer-capture --example camera_probe -- capture 0 20` in one terminal and the test in another: the test's `start` fails with "the camera is in use by another program". 3. Unplug the camera during the 5 s capture: the output shows `Ended(DeviceLost)`; plug it back in and `camera_probe list` shows it again. ## Deviations from the plan - Hot-plug is a 2 s sysfs re-list, not inotify (no inotify crate in the tree; the plan allows it). - `modes` also honours `FLUXER_CAMERA_FORBID` (it opens the device); the trait only required it of `start`. - `V4l2Io` has a `forbidden()` method (the kernel's reads the environment; the in-memory one is scripted), so the in-memory tests run under CI's `FLUXER_CAMERA_FORBID=1` while `forbidden_env_refuses_before_open` still proves the refusal comes before any open. - `tests/camera_fake.rs`'s `default_camera_is_unsupported_until_the_back_ends_land` is now `cfg(not(target_os = "linux"))` (on Linux the default is the real back end, which no test may start; Camera 11 will narrow it further). Otherwise only the task's files, plus a comment in `src/lib.rs`. - `v4l` moved from `[dev-dependencies]` to the Linux `[dependencies]` (already in `Cargo.lock`; `cargo deny` green). - Strings: none copied (no user-facing text in this task). Closes #962 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
The V4L2 back end of CameraCapturer (camera::v4l2::V4l2Camera) over the
v4l crate chosen by Camera 1: sysfs-only listing, a 2 s re-list watcher,
modes, start up to STREAMON before returning (errno mapped by
camera::v4l2_errors, descriptor closed on every failure), a capture
thread that drops flagged frames, paces, decodes to I420, fits, reports
stalls and ENODEV as DeviceLost, and stop/Drop that close the device
before returning. Tested over an in-memory V4l2Io (feature fake);
tests/camera_real.rs is ignored and for Charles only.

Refs #962

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
The V4L2 session marks itself ended (device closed) before it hands
Ended to the sink, and start joins such a session instead of racing
the thread's exit. The pacing test's bounds are loosened for loaded
CI machines (it checks that 100 fps is not passed through).

Refs #962

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. Conflict with Camera 11 resolved: default_camera() dispatches to V4L2 on Linux and Media Foundation on Windows; the Unsupported default test now runs only where there is no back end. Workspace clippy and the capture and voice tests pass on the merged tree.

Merged into `camera` by hand. Conflict with Camera 11 resolved: `default_camera()` dispatches to V4L2 on Linux and Media Foundation on Windows; the `Unsupported` default test now runs only where there is no back end. Workspace clippy and the capture and voice tests pass on the merged tree.
charles closed this pull request 2026-11-20 03:14:12 +00:00

Pull request closed

Sign in to join this conversation.
No description provided.