Camera 6: fluxer-capture camera trait, mode selection, decode, fake (#958) #980

Closed
charles wants to merge 0 commits from camera-6-capture-camera-trait-mode into camera
Owner

What this builds

fluxer-capture::camera (Camera spec §5.2, §7.2–7.4), plus one line in xtask:

  • Trait and types: CameraCapturer (list, watch, modes, start, stop), CameraDevice { id, name } (Debug hashes the id with the same FNV-1a as the core's device_hash), CameraChoice::{Default, Device(id)}, CameraTarget, CameraOutput::{Started { width, height, fps }, Frame, Stalled, Resumed, Ended(CameraEnd::DeviceLost), Error}, CameraSink. default_camera() returns Unsupported("camera capture is not built for this system yet") until Camera 10 and 11.
  • The switch: camera::forbidden() / forbidden_by(value) give Unsupported("forbidden by FLUXER_CAMERA_FORBID") when the variable is set to anything but empty or 0 (the same rule as camera_probe). Real back ends must call it first in start. xtask's cargo_command now sets FLUXER_CAMERA_FORBID=1 for every cargo step ci runs, with the test ci_sets_camera_forbid.
  • format (pure): Mode { layout: PixelLayout, width, height, interval: FrameInterval }, PixelLayout::from_fourcc (V4L2 and MF FourCCs: YUYV/YUY2, UYVY, NV12, YU12/I420/IYUV, MJPG, Other), choose(modes, target, prefer_uncompressed) (§7.3), fit (wraps scale::area_downscale: scales down, never crops) and fitted_size.
  • decode::to_i420(layout, w, h, stride, data, ts): YUYV, UYVY, NV12 and I420 with strides, and MJPEG, built on Task 4's conversions. Bad input gives a FrameError, never a panic.
  • names::{clean, display, FALLBACK}: a port of the original's cleanVideoDeviceLabel (fluxer_app/src/features/voice/utils/VoiceDeviceManager.ts:118-198). Fallback string copied: "Camera" (CAMERA_DESCRIPTOR, VoiceMessageDescriptors.ts:283).
  • camera::fake (feature fake): FakeCamera and FakeCameraControl. Two scripted cameras; plug, plug_with_modes, unplug, set_devices, fail_next_start, lose_device, stall/resume, set_stall_after; the counters opened, open_now, listed; and running_device/running_mode/running_target. It draws TestPattern::camera at the chosen mode, fitted to the target. Several FakeCameras on one control share devices, so a second consumer of an open device gets Busy.

Capture cards (owner decision of 2026-11-19)

  • Listing modes: CameraCapturer::modes(&CameraChoice) lists every mode, whatever its size, aspect ratio or rate. Its default answer is Unsupported. On a real back end it opens the device without streaming and closes it before returning, so the docs say a listing must never call it.
  • Selecting a mode: a target equal to an offered mode selects that mode (any_offered_mode_is_selectable_by_its_own_target).
  • Aspect ratio: choose prefers the target's aspect ratio. The spec says 16:9, and for the 16:9 presets the two are the same; this way a 4:3 or 5:4 capture-card mode can be picked exactly.
  • Mirroring: frames are never mirrored in capture (is_mirrored == Some(false) is asserted).
  • The sink: the sink does not know who consumes the frames.
  • Second consumer: a device opened by id that is already open is refused with Busy.

Deviations from the plan / spec

  • CameraError gains AlreadyStarted (appended), needed for second_start_is_already_started.
  • CameraCapturer::modes is an addition to spec §5.2's trait. It has a default body, so Tasks 10 and 11 may leave it out.
  • PixelLayout::Uyvy is an addition (common on capture cards). It is decoded by swapping byte pairs into YUYV.
  • names::clean also blanks a label that starts with / (a Linux device path). The original's DEVICE_PATH_LABEL only covers \\?\ and scheme:/.
  • fit returns the frame as it is when it already fits (the behaviour of area_downscale).
  • The xtask change sets the variable in cargo_command, so it covers every cargo step ci runs (tests, screenshots, livekit), not only the test step.
  • default_camera_is_unsupported_until_the_back_ends_land will need adjusting when Task 10/11 make list succeed.

How it was tested

  • crates/fluxer-capture/tests/camera_format.rs (11 tests: the mode tables, fit, decode of every layout, stride, MJPEG fixture, garbage, the switch) and tests/camera_fake.rs (15 tests: listing_opens_nothing, start_delivers_started_then_frames_at_rate, stop_closes_before_returning, busy_and_not_allowed_start_nothing, loss_reports_ended_once_and_closes, watch_fires_on_plug_and_unplug, second_start_is_already_started, forbidden_env_is_reported, the second-consumer, unplug, stall, modes and Unsupported cases), plus unit tests in format.rs, names.rs and mod.rs.
  • No camera, display or device was opened. All test runs had FLUXER_CAMERA_FORBID=1. No desktop tests were run (none were needed).
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci is green locally.
  • Windows: no cfg(windows) code was added. Everything new is OS-neutral.

Closes #958

🤖 Generated with Claude Code

https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K

## What this builds `fluxer-capture::camera` (Camera spec §5.2, §7.2–7.4), plus one line in `xtask`: - **Trait and types**: `CameraCapturer` (`list`, `watch`, `modes`, `start`, `stop`), `CameraDevice { id, name }` (`Debug` hashes the id with the same FNV-1a as the core's `device_hash`), `CameraChoice::{Default, Device(id)}`, `CameraTarget`, `CameraOutput::{Started { width, height, fps }, Frame, Stalled, Resumed, Ended(CameraEnd::DeviceLost), Error}`, `CameraSink`. `default_camera()` returns `Unsupported("camera capture is not built for this system yet")` until Camera 10 and 11. - **The switch**: `camera::forbidden()` / `forbidden_by(value)` give `Unsupported("forbidden by FLUXER_CAMERA_FORBID")` when the variable is set to anything but empty or `0` (the same rule as `camera_probe`). Real back ends must call it first in `start`. `xtask`'s `cargo_command` now sets `FLUXER_CAMERA_FORBID=1` for every cargo step `ci` runs, with the test `ci_sets_camera_forbid`. - **`format`** (pure): `Mode { layout: PixelLayout, width, height, interval: FrameInterval }`, `PixelLayout::from_fourcc` (V4L2 and MF FourCCs: YUYV/YUY2, UYVY, NV12, YU12/I420/IYUV, MJPG, `Other`), `choose(modes, target, prefer_uncompressed)` (§7.3), `fit` (wraps `scale::area_downscale`: scales down, never crops) and `fitted_size`. - **`decode::to_i420(layout, w, h, stride, data, ts)`**: YUYV, UYVY, NV12 and I420 with strides, and MJPEG, built on Task 4's conversions. Bad input gives a `FrameError`, never a panic. - **`names::{clean, display, FALLBACK}`**: a port of the original's `cleanVideoDeviceLabel` (`fluxer_app/src/features/voice/utils/VoiceDeviceManager.ts:118-198`). Fallback string copied: "Camera" (`CAMERA_DESCRIPTOR`, `VoiceMessageDescriptors.ts:283`). - **`camera::fake`** (feature `fake`): `FakeCamera` and `FakeCameraControl`. Two scripted cameras; `plug`, `plug_with_modes`, `unplug`, `set_devices`, `fail_next_start`, `lose_device`, `stall`/`resume`, `set_stall_after`; the counters `opened`, `open_now`, `listed`; and `running_device`/`running_mode`/`running_target`. It draws `TestPattern::camera` at the chosen mode, fitted to the target. Several `FakeCamera`s on one control share devices, so a second consumer of an open device gets `Busy`. ## Capture cards (owner decision of 2026-11-19) - **Listing modes**: `CameraCapturer::modes(&CameraChoice)` lists every mode, whatever its size, aspect ratio or rate. Its default answer is `Unsupported`. On a real back end it opens the device without streaming and closes it before returning, so the docs say a listing must never call it. - **Selecting a mode**: a target equal to an offered mode selects that mode (`any_offered_mode_is_selectable_by_its_own_target`). - **Aspect ratio**: `choose` prefers the target's aspect ratio. The spec says 16:9, and for the 16:9 presets the two are the same; this way a 4:3 or 5:4 capture-card mode can be picked exactly. - **Mirroring**: frames are never mirrored in capture (`is_mirrored == Some(false)` is asserted). - **The sink**: the sink does not know who consumes the frames. - **Second consumer**: a device opened by id that is already open is refused with `Busy`. ## Deviations from the plan / spec - `CameraError` gains `AlreadyStarted` (appended), needed for `second_start_is_already_started`. - `CameraCapturer::modes` is an addition to spec §5.2's trait. It has a default body, so Tasks 10 and 11 may leave it out. - `PixelLayout::Uyvy` is an addition (common on capture cards). It is decoded by swapping byte pairs into YUYV. - `names::clean` also blanks a label that starts with `/` (a Linux device path). The original's `DEVICE_PATH_LABEL` only covers `\\?\` and `scheme:/`. - `fit` returns the frame as it is when it already fits (the behaviour of `area_downscale`). - The xtask change sets the variable in `cargo_command`, so it covers every cargo step `ci` runs (tests, screenshots, livekit), not only the test step. - `default_camera_is_unsupported_until_the_back_ends_land` will need adjusting when Task 10/11 make `list` succeed. ## How it was tested - `crates/fluxer-capture/tests/camera_format.rs` (11 tests: the mode tables, fit, decode of every layout, stride, MJPEG fixture, garbage, the switch) and `tests/camera_fake.rs` (15 tests: `listing_opens_nothing`, `start_delivers_started_then_frames_at_rate`, `stop_closes_before_returning`, `busy_and_not_allowed_start_nothing`, `loss_reports_ended_once_and_closes`, `watch_fires_on_plug_and_unplug`, `second_start_is_already_started`, `forbidden_env_is_reported`, the second-consumer, unplug, stall, modes and Unsupported cases), plus unit tests in `format.rs`, `names.rs` and `mod.rs`. - No camera, display or device was opened. All test runs had `FLUXER_CAMERA_FORBID=1`. No desktop tests were run (none were needed). - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` is green locally. - Windows: no `cfg(windows)` code was added. Everything new is OS-neutral. Closes #958 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Refs #958

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

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
The CameraCapturer trait and its types (spec §5.2), the FLUXER_CAMERA_FORBID
switch, mode selection and the fit (spec §7.3), decoding of YUYV, UYVY, NV12,
I420 and MJPEG buffers to I420 (spec §7.4), the original's device name
cleaning (row 13, VoiceDeviceManager.ts:118-198) and the fake camera.

Refs #958

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 (the merge API returns 405); the commits are in the branch.

Merged into `camera` by hand (the merge API returns 405); the commits are in the branch.
charles closed this pull request 2026-11-20 00:02:33 +00:00

Pull request closed

Sign in to join this conversation.
No description provided.