feat: live camera preview on the diagnostics page

Streams webcam frames into a preview panel while the Diagnostics page
is open, driven by a Start/Stop command channel so the device is only
held open when needed. The preview requests a 640x480 mode (falling
back to whatever the camera offers) since decoding a full-resolution
frame every tick was taking ~450ms and made the feed crawl; the
donation snapshot path is untouched and still captures at the
camera's highest resolution.

Author: eupn

src/camera.rs

@@ -1,10 +1,13 @@
 use log::{error, info};
 use nokhwa::Camera;
 use nokhwa::pixel_format::RgbFormat;
-use nokhwa::utils::{CameraIndex, RequestedFormat, RequestedFormatType};
+use nokhwa::utils::{
+    CameraFormat, CameraIndex, FrameFormat, RequestedFormat, RequestedFormatType, Resolution,
+};
 use std::path::PathBuf;
+use std::sync::mpsc::{Receiver, SyncSender, TryRecvError};
 use std::thread;
-use std::time::{SystemTime, UNIX_EPOCH};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 /// Captures a single frame from the default webcam and saves it as a JPEG
 /// under `photos_dir`, running on a dedicated thread so it never blocks the UI.
@@ -19,7 +22,7 @@ pub fn capture_donation_photo(photos_dir: &str, username: &str) {
     });
 }
 
-fn capture_and_save(photos_dir: &str, username: &str) -> Result<(), String> {
+fn open_camera() -> Result<Camera, String> {
     let index = CameraIndex::Index(0);
     let requested =
         RequestedFormat::new::<RgbFormat>(RequestedFormatType::AbsoluteHighestFrameRate);
@@ -31,6 +34,31 @@ fn capture_and_save(photos_dir: &str, username: &str) -> Result<(), String> {
         .open_stream()
         .map_err(|e| format!("failed to open webcam stream: {e}"))?;
 
+    Ok(camera)
+}
+
+/// Opens the camera for the live diagnostics preview. Decoding a full-resolution
+/// frame (e.g. 1920x1080, which many webcams default to) takes ~450ms — far too
+/// slow for a live view — so this asks for a modest 640x480 mode first, which
+/// virtually every UVC/AVFoundation webcam supports and decodes in under 100ms.
+/// Falls back to whatever the camera actually offers if that request is rejected.
+fn open_preview_camera() -> Result<Camera, String> {
+    let small = RequestedFormat::new::<RgbFormat>(RequestedFormatType::Exact(CameraFormat::new(
+        Resolution::new(640, 480),
+        FrameFormat::MJPEG,
+        30,
+    )));
+    if let Ok(mut camera) = Camera::new(CameraIndex::Index(0), small)
+        && camera.open_stream().is_ok()
+    {
+        return Ok(camera);
+    }
+    open_camera()
+}
+
+fn capture_and_save(photos_dir: &str, username: &str) -> Result<(), String> {
+    let mut camera = open_camera()?;
+
     // Discard the first couple of frames to let auto-exposure/white-balance settle.
     for _ in 0..2 {
         let _ = camera.frame();
@@ -69,3 +97,73 @@ fn capture_and_save(photos_dir: &str, username: &str) -> Result<(), String> {
     info!("📷 Saved donation photo to {path:?}");
     Ok(())
 }
+
+/// Commands accepted by the [`spawn_preview`] thread.
+pub enum PreviewCommand {
+    Start,
+    Stop,
+}
+
+/// A single decoded RGB8 frame, ready to hand to `slint::SharedPixelBuffer`.
+pub struct PreviewFrame {
+    pub rgb: Vec<u8>,
+    pub width: u32,
+    pub height: u32,
+}
+
+const PREVIEW_FRAME_INTERVAL: Duration = Duration::from_millis(100);
+
+/// Spawns a thread that owns the webcam for as long as the diagnostics page's
+/// live preview is active. `Start`/`Stop` on `cmd_rx` open/close the device;
+/// while open, frames are pushed to `frame_tx` on a best-effort basis (a full
+/// channel just means the consumer hasn't caught up, so the frame is dropped).
+pub fn spawn_preview(cmd_rx: Receiver<PreviewCommand>, frame_tx: SyncSender<PreviewFrame>) {
+    thread::spawn(move || {
+        let mut camera: Option<Camera> = None;
+
+        loop {
+            let cmd = if camera.is_some() {
+                match cmd_rx.try_recv() {
+                    Ok(cmd) => Some(cmd),
+                    Err(TryRecvError::Empty) => None,
+                    Err(TryRecvError::Disconnected) => break,
+                }
+            } else {
+                match cmd_rx.recv() {
+                    Ok(cmd) => Some(cmd),
+                    Err(_) => break,
+                }
+            };
+
+            match cmd {
+                Some(PreviewCommand::Start) if camera.is_none() => match open_preview_camera() {
+                    Ok(cam) => camera = Some(cam),
+                    Err(e) => error!("📷 Failed to start preview: {}", e),
+                },
+                Some(PreviewCommand::Stop) => camera = None,
+                _ => {}
+            }
+
+            let Some(cam) = camera.as_mut() else {
+                continue;
+            };
+
+            let frame_start = Instant::now();
+            match cam.frame().and_then(|f| f.decode_image::<RgbFormat>()) {
+                Ok(image) => {
+                    let _ = frame_tx.try_send(PreviewFrame {
+                        width: image.width(),
+                        height: image.height(),
+                        rgb: image.into_raw(),
+                    });
+                }
+                Err(e) => error!("📷 Preview frame capture failed: {}", e),
+            }
+            // Capture+decode already ate into the budget; only sleep the remainder
+            // so the preview holds close to its target cadence instead of drifting.
+            if let Some(remaining) = PREVIEW_FRAME_INTERVAL.checked_sub(frame_start.elapsed()) {
+                thread::sleep(remaining);
+            }
+        }
+    });
+}

src/main.rs

@@ -944,6 +944,51 @@ mod diagnostics_handler {
         );
         std::mem::forget(timer);
 
+        // Live camera preview — only streams while the Diagnostics page is open.
+        let (preview_cmd_tx, preview_cmd_rx) = std::sync::mpsc::channel::<camera::PreviewCommand>();
+        let (preview_frame_tx, preview_frame_rx) =
+            std::sync::mpsc::sync_channel::<camera::PreviewFrame>(1);
+        camera::spawn_preview(preview_cmd_rx, preview_frame_tx);
+
+        let weak_preview = app.as_weak();
+        let was_on_diagnostics = Rc::new(RefCell::new(false));
+        let preview_timer = Timer::default();
+        preview_timer.start(
+            TimerMode::Repeated,
+            std::time::Duration::from_millis(100),
+            move || {
+                let Some(window) = weak_preview.upgrade() else {
+                    return;
+                };
+                let on_page = window.get_on_diagnostics_page();
+                if on_page != *was_on_diagnostics.borrow() {
+                    *was_on_diagnostics.borrow_mut() = on_page;
+                    if on_page {
+                        let _ = preview_cmd_tx.send(camera::PreviewCommand::Start);
+                    } else {
+                        let _ = preview_cmd_tx.send(camera::PreviewCommand::Stop);
+                        window.set_diag_camera_available(false);
+                    }
+                }
+                // Drain to the most recent frame only — older ones are stale.
+                let mut latest = None;
+                while let Ok(frame) = preview_frame_rx.try_recv() {
+                    latest = Some(frame);
+                }
+                if let Some(frame) = latest {
+                    let pixel_buffer =
+                        slint::SharedPixelBuffer::<slint::Rgb8Pixel>::clone_from_slice(
+                            &frame.rgb,
+                            frame.width,
+                            frame.height,
+                        );
+                    window.set_diag_camera_frame(slint::Image::from_rgb8(pixel_buffer));
+                    window.set_diag_camera_available(true);
+                }
+            },
+        );
+        std::mem::forget(preview_timer);
+
         let cashcode_tx_reset = cashcode_tx;
         app.on_diag_reset_bills(move || {
             info!("🔄 Diagnostics: resetting bill acceptor");

ui/main_window.slint

@@ -50,6 +50,10 @@ export component MainWindow inherits Window {
     in-out property <LogEntry> diag-bill-status: { level: 0, text: "Initializing..." };
     in-out property <LogEntry> diag-coin-status: { level: 0, text: "Initializing..." };
     in-out property <LogEntry> diag-backend-status: { level: 0, text: "Not checked" };
+    // read by Rust to know when to start/stop the camera preview
+    out property <bool> on-diagnostics-page: current-page == Page.Diagnostics;
+    in-out property <image> diag-camera-frame: @image-url("");
+    in-out property <bool> diag-camera-available: false;
     callback diag-reset-bills();
     callback diag-reenumerate-coins();
     callback diag-play-sound();
@@ -225,11 +229,23 @@ export component MainWindow inherits Window {
             bill-status: root.diag-bill-status;
             coin-status: root.diag-coin-status;
             backend-status: root.diag-backend-status;
-            back-clicked => { root.current-page = Page.Main; }
-            reset-bills => { root.diag-reset-bills(); }
-            reenumerate-coins => { root.diag-reenumerate-coins(); }
-            play-sound => { root.diag-play-sound(); }
-            check-backend => { root.diag-check-backend(); }
+            camera-frame: root.diag-camera-frame;
+            camera-available: root.diag-camera-available;
+            back-clicked => {
+                root.current-page = Page.Main;
+            }
+            reset-bills => {
+                root.diag-reset-bills();
+            }
+            reenumerate-coins => {
+                root.diag-reenumerate-coins();
+            }
+            play-sound => {
+                root.diag-play-sound();
+            }
+            check-backend => {
+                root.diag-check-backend();
+            }
         }
 
         // Confetti overlay — rendered on top of all pages