Screen share 3: fluxer-capture crate — traits, model types, fake backend (#150) #190

Manually merged
charles merged 0 commits from screenshare-3-capture-crate into screenshare 2026-11-12 05:17:16 +00:00
Owner

Stacked on: screenshare-1-video-frames

What this builds

New crate crates/fluxer-capture (Screen share plan Task 3, spec §4, §7.1, §9):

  • source: SourceKind::{Screen, Window, SystemPicker}, CaptureSource { id, kind, title, app_name, pid, thumbnail }, SourceChoice::{Source(String), SystemPicker}, CaptureTarget { max_width, max_height, fps }, 480x270 thumbnail constants.
  • screen: trait ScreenCapturer: Send (capabilities, list_sources, start, switch, update, stop), CaptureCapabilities { in_app_picker, window_audio }, CaptureOutput::{Frame, Started, Stalled, Resumed, Ended(EndReason), Error}, STALL_AFTER = 3 s, plus StallDetector and Pacer (shared stall detection and absolute-deadline pacing for the real backends of Tasks 4/5).
  • audio: trait StreamAudioCapturer: Send (start(&AudioRule, exclude_pid_tree, sink), set_rule, stop), StreamAudioFrame { samples, channels: 2 } (10 ms, 48 kHz), AudioRule with the original's defaults (VoiceSettings.ts: System, only_speakers, only_default_speakers, ignore_devices, ignore_input_media all true, ignore_virtual false), AudioMode::{System, Applications(Vec<AppMatch>)}, AppMatch::{Pid, Name, Binary}.
  • error: CaptureError::{Unsupported, SourceNotFound, AlreadyStarted, Cancelled, Backend}.
  • fake (feature fake): FakeScreenCapturer (test pattern at the target size and rate, thumbnails, switch/update on the fly), FakeAudioCapturer (440 Hz stereo tone, clock-driven 10 ms frames), FakeCaptureControl (sources, capabilities, picker cancel, stall/resume, scripted end; inspection of current source, target, audio rule, excluded pid).
  • default_backends() returns Unsupported stubs on every OS until Tasks 4/5/14/15.

Depends only on fluxer-video and thiserror (no fluxer-core, no livekit).

How it was tested

  • tests/fake.rs (10 tests): the plan's seven (fake_delivers_frames_at_target_rate_and_size, fake_switch_changes_source_without_ended, scripted_end_is_reported_once, stall_and_resume_after_3s_without_frames, stop_is_idempotent, fake_audio_delivers_10ms_stereo_frames, unsupported_backends_return_errors) plus fake_lists_screens_and_windows_with_optional_thumbnails, start_with_unknown_source_is_an_error, audio_rule_defaults_match_the_original. Unit tests for StallDetector and Pacer.
  • Tests written first and seen failing (compile failure: crate absent), then green; the integration tests were run 15+ times locally to check for timing flakiness (one test-side race in stop_is_idempotent was found and fixed).
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally (Linux). No real-device tests belong to this task.

Deviations / decisions for the reviewer

  • The plan names EndReason but not its variants: chose SourceClosed, SessionEnded, Cancelled. AppMatch variants beyond Pid (Task 15) are Name and Binary for the PipeWire matcher (Task 14). CaptureError variants are my choice.
  • StreamAudioCapturer::start/set_rule and ScreenCapturer::start take &AudioRule/&SourceChoice by reference.
  • channels is u16 (always 2).
  • Workspace Cargo.toml needed no edit: members = ["crates/*"] already covers the new crate.
  • The fake audio delivers frames by the clock (catching up after a late wake-up, up to 100 ms) so coarse Windows timers do not drop frames.

Closes #150

🤖 Generated with Claude Code

Stacked on: screenshare-1-video-frames ## What this builds New crate `crates/fluxer-capture` (Screen share plan Task 3, spec §4, §7.1, §9): - `source`: `SourceKind::{Screen, Window, SystemPicker}`, `CaptureSource { id, kind, title, app_name, pid, thumbnail }`, `SourceChoice::{Source(String), SystemPicker}`, `CaptureTarget { max_width, max_height, fps }`, 480x270 thumbnail constants. - `screen`: `trait ScreenCapturer: Send` (`capabilities`, `list_sources`, `start`, `switch`, `update`, `stop`), `CaptureCapabilities { in_app_picker, window_audio }`, `CaptureOutput::{Frame, Started, Stalled, Resumed, Ended(EndReason), Error}`, `STALL_AFTER` = 3 s, plus `StallDetector` and `Pacer` (shared stall detection and absolute-deadline pacing for the real backends of Tasks 4/5). - `audio`: `trait StreamAudioCapturer: Send` (`start(&AudioRule, exclude_pid_tree, sink)`, `set_rule`, `stop`), `StreamAudioFrame { samples, channels: 2 }` (10 ms, 48 kHz), `AudioRule` with the original's defaults (`VoiceSettings.ts`: System, only_speakers, only_default_speakers, ignore_devices, ignore_input_media all true, ignore_virtual false), `AudioMode::{System, Applications(Vec<AppMatch>)}`, `AppMatch::{Pid, Name, Binary}`. - `error`: `CaptureError::{Unsupported, SourceNotFound, AlreadyStarted, Cancelled, Backend}`. - `fake` (feature `fake`): `FakeScreenCapturer` (test pattern at the target size and rate, thumbnails, switch/update on the fly), `FakeAudioCapturer` (440 Hz stereo tone, clock-driven 10 ms frames), `FakeCaptureControl` (sources, capabilities, picker cancel, stall/resume, scripted end; inspection of current source, target, audio rule, excluded pid). - `default_backends()` returns `Unsupported` stubs on every OS until Tasks 4/5/14/15. Depends only on `fluxer-video` and `thiserror` (no `fluxer-core`, no `livekit`). ## How it was tested - `tests/fake.rs` (10 tests): the plan's seven (`fake_delivers_frames_at_target_rate_and_size`, `fake_switch_changes_source_without_ended`, `scripted_end_is_reported_once`, `stall_and_resume_after_3s_without_frames`, `stop_is_idempotent`, `fake_audio_delivers_10ms_stereo_frames`, `unsupported_backends_return_errors`) plus `fake_lists_screens_and_windows_with_optional_thumbnails`, `start_with_unknown_source_is_an_error`, `audio_rule_defaults_match_the_original`. Unit tests for `StallDetector` and `Pacer`. - Tests written first and seen failing (compile failure: crate absent), then green; the integration tests were run 15+ times locally to check for timing flakiness (one test-side race in `stop_is_idempotent` was found and fixed). - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally (Linux). No real-device tests belong to this task. ## Deviations / decisions for the reviewer - The plan names `EndReason` but not its variants: chose `SourceClosed`, `SessionEnded`, `Cancelled`. `AppMatch` variants beyond `Pid` (Task 15) are `Name` and `Binary` for the PipeWire matcher (Task 14). `CaptureError` variants are my choice. - `StreamAudioCapturer::start`/`set_rule` and `ScreenCapturer::start` take `&AudioRule`/`&SourceChoice` by reference. - `channels` is `u16` (always 2). - Workspace `Cargo.toml` needed no edit: `members = ["crates/*"]` already covers the new crate. - The fake audio delivers frames by the clock (catching up after a late wake-up, up to 100 ms) so coarse Windows timers do not drop frames. Closes #150 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(video): frames, conversions, frame bus, test pattern and preview JPEG
All checks were successful
ci / Linux (x86_64) (push) Successful in 15m16s
ci / Windows (x64) (push) Successful in 16m21s
8b8a359082
Refs #148

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feat(capture): capture traits and fake backends
All checks were successful
ci / Windows (x64) (push) Successful in 16m9s
ci / Linux (x86_64) (push) Successful in 35m35s
d821f19097
Refs #150

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Author
Owner

Independent review: Screen share 3 (capture crate), d821f19

Scope: git diff 8b8a359..origin/screenshare-3-capture-crate (the crate, its tests, README and Cargo.lock).

Checks

  1. Plan tests: all 7 named tests are in tests/fake.rs and assert what the plan says. Rate and size are checked at 640x360@30 (25 to 35 frames) and after update at 320x180@10. A switch produces no Ended or Error. A scripted end is reported once and nothing follows it. STALL_AFTER == 3 s: Stalled comes in the 2.9 to 4 s window, then Resumed before the next frame. stop can be called twice, the sink is dropped (the channel disconnects), and dropping the capturer stops it. Fake audio is 480x2 samples per frame at 48 kHz with a 440 Hz tone that is identical on both channels. The Unsupported stubs return errors and never panic. There are 3 more tests (thumbnails are 480x270, an unknown source returns SourceNotFound, and AudioRule defaults), plus unit tests for StallDetector and Pacer.
  2. Interfaces: every name and signature in the Task 3 block exists as written. This covers SourceKind, CaptureSource, CaptureTarget, ScreenCapturer (all 6 methods), SourceChoice, CaptureOutput, AudioRule, StreamAudioFrame, StreamAudioCapturer::start(rule, exclude_pid_tree: u32, sink)/set_rule/stop, FakeScreenCapturer/FakeAudioCapturer/FakeCaptureControl behind feature fake, and default_backends(). AppMatch::Pid exists for Task 15. I checked the AudioRule defaults against the fork's VoiceSettings.ts:491-497. They match: System, true, true, true, true, ignore_virtual=false.
  3. Invariants: the only dependencies are fluxer-video (path) and thiserror. There is no fluxer-core, livekit or libwebrtc, and no OS library. The fake feature is not on by default and is only enabled for dev-dependencies. There are no secrets in the code or the fixtures, and no server data flows through this crate.
  4. Review Focus: no item belongs to Task 3.
  5. cargo xtask ci in the review worktree is green ("all steps passed"). All 10 tests in tests/fake.rs pass in 3.5 s.

Findings

  • [minor] src/fake.rs / README: when update changes the size, the fake does not send a new Started. The README contract says "Started { width, height } comes first, then frames of that size". Consumers (Task 16 VideoFrameInfo, Task 21) therefore have to take the size from each frame. Suggestion: say in the README that the size can change after update, and that Frame.width/height is the authority.
  • [minor] src/fake.rs stop(): this joins the capture thread. If someone calls stop from inside the sink (on the capture thread), the thread would try to join itself. The trait docs say the sink must not block, but they do not explicitly forbid calling stop or switch from the sink. A single doc line on CaptureSink would close this off for Tasks 4, 5 and 21.
  • [minor] tests/fake.rs: the rate assertions depend on wall-clock timing (25 to 35 fps, 40 to 60 audio frames in 500 ms). They passed here. If the shared Windows runner turns out to be flaky, widen the windows rather than retrying.

No blocking findings.

Verdict: APPROVE. The interfaces match the plan, the invariants hold and local CI is green. The remote runners were not checked by this review.

🤖 Generated with Claude Code

## Independent review: Screen share 3 (capture crate), d821f19 Scope: `git diff 8b8a359..origin/screenshare-3-capture-crate` (the crate, its tests, README and Cargo.lock). **Checks** 1. Plan tests: all 7 named tests are in `tests/fake.rs` and assert what the plan says. Rate and size are checked at 640x360@30 (25 to 35 frames) and after `update` at 320x180@10. A switch produces no `Ended` or `Error`. A scripted end is reported once and nothing follows it. `STALL_AFTER == 3 s`: `Stalled` comes in the 2.9 to 4 s window, then `Resumed` before the next frame. `stop` can be called twice, the sink is dropped (the channel disconnects), and dropping the capturer stops it. Fake audio is 480x2 samples per frame at 48 kHz with a 440 Hz tone that is identical on both channels. The `Unsupported` stubs return errors and never panic. There are 3 more tests (thumbnails are 480x270, an unknown source returns `SourceNotFound`, and `AudioRule` defaults), plus unit tests for `StallDetector` and `Pacer`. 2. Interfaces: every name and signature in the Task 3 block exists as written. This covers `SourceKind`, `CaptureSource`, `CaptureTarget`, `ScreenCapturer` (all 6 methods), `SourceChoice`, `CaptureOutput`, `AudioRule`, `StreamAudioFrame`, `StreamAudioCapturer::start(rule, exclude_pid_tree: u32, sink)`/`set_rule`/`stop`, `FakeScreenCapturer`/`FakeAudioCapturer`/`FakeCaptureControl` behind feature `fake`, and `default_backends()`. `AppMatch::Pid` exists for Task 15. I checked the `AudioRule` defaults against the fork's `VoiceSettings.ts:491-497`. They match: System, true, true, true, true, ignore_virtual=false. 3. Invariants: the only dependencies are `fluxer-video` (path) and `thiserror`. There is no `fluxer-core`, `livekit` or `libwebrtc`, and no OS library. The `fake` feature is not on by default and is only enabled for dev-dependencies. There are no secrets in the code or the fixtures, and no server data flows through this crate. 4. Review Focus: no item belongs to Task 3. 5. `cargo xtask ci` in the review worktree is **green** ("all steps passed"). All 10 tests in `tests/fake.rs` pass in 3.5 s. **Findings** - [minor] `src/fake.rs` / README: when `update` changes the size, the fake does not send a new `Started`. The README contract says "`Started { width, height }` comes first, then frames of that size". Consumers (Task 16 `VideoFrameInfo`, Task 21) therefore have to take the size from each frame. Suggestion: say in the README that the size can change after `update`, and that `Frame.width/height` is the authority. - [minor] `src/fake.rs` `stop()`: this joins the capture thread. If someone calls `stop` from inside the sink (on the capture thread), the thread would try to join itself. The trait docs say the sink must not block, but they do not explicitly forbid calling `stop` or `switch` from the sink. A single doc line on `CaptureSink` would close this off for Tasks 4, 5 and 21. - [minor] `tests/fake.rs`: the rate assertions depend on wall-clock timing (25 to 35 fps, 40 to 60 audio frames in 500 ms). They passed here. If the shared Windows runner turns out to be flaky, widen the windows rather than retrying. No blocking findings. **Verdict: APPROVE.** The interfaces match the plan, the invariants hold and local CI is green. The remote runners were not checked by this review. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
charles manually merged commit 69edce3d34 into screenshare 2026-11-12 05:17:16 +00:00
Sign in to join this conversation.
No description provided.