feat: Enhance inference management with device tracking and telemetry updates

- Introduced VideoPlayer class to handle local video playback, emitting frames via frame_ready signal.
- Updated MainWindow to switch between camera and video sources, integrating video playback controls.
- Enhanced AppMenuBar with options to open video files and manage inference models.
- Implemented BboxOverlay for displaying detection results on video frames.
- Added InferenceManager to manage YOLO inference in a separate process, with error handling and restart logic.
- Created tests for BboxOverlay and InferenceManager to ensure functionality and robustness.
- Updated pyproject.toml to include optional dependencies for inference support.

.gitignore

@@ -12,6 +12,9 @@ __pycache__/
 venv/
 env/
 
+# Log files
+logs/
+
 # Local/runtime data
 captures/photos/*
 captures/videos/*

app/camera/camera_enumerator.py

@@ -0,0 +1,132 @@
+"""Camera enumeration — discovers available video input devices."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+
+from PySide6.QtMultimedia import QCameraDevice, QMediaDevices, QVideoFrameFormat
+
+logger = logging.getLogger(__name__)
+
+# Map Qt pixel format enum → human-readable string
+_PIXEL_FORMAT_NAMES: dict[QVideoFrameFormat.PixelFormat, str] = {
+    QVideoFrameFormat.PixelFormat.Format_BGRA8888:  "BGRA",
+    QVideoFrameFormat.PixelFormat.Format_BGRX8888:  "BGRX",
+    QVideoFrameFormat.PixelFormat.Format_ABGR8888:  "ABGR",
+    QVideoFrameFormat.PixelFormat.Format_ARGB8888:  "ARGB",
+    QVideoFrameFormat.PixelFormat.Format_RGBA8888:  "RGBA",
+    QVideoFrameFormat.PixelFormat.Format_RGBX8888:  "RGBX",
+    QVideoFrameFormat.PixelFormat.Format_YUV420P:   "YUV420P",
+    QVideoFrameFormat.PixelFormat.Format_YUV422P:   "YUV422P",
+    QVideoFrameFormat.PixelFormat.Format_NV12:      "NV12",
+    QVideoFrameFormat.PixelFormat.Format_NV21:      "NV21",
+    QVideoFrameFormat.PixelFormat.Format_UYVY:      "UYVY",
+    QVideoFrameFormat.PixelFormat.Format_YUYV:      "YUY2",
+    QVideoFrameFormat.PixelFormat.Format_Jpeg:      "MJPG",
+    QVideoFrameFormat.PixelFormat.Format_Y8:        "GRAY8",
+    QVideoFrameFormat.PixelFormat.Format_Y16:       "GRAY16",
+}
+
+
+def pixel_format_name(fmt: QVideoFrameFormat.PixelFormat) -> str:
+    """Return a short human-readable name for a Qt pixel format."""
+    return _PIXEL_FORMAT_NAMES.get(fmt, f"fmt_{fmt.value if hasattr(fmt, 'value') else fmt}")
+
+
+@dataclass
+class CameraFormat:
+    """One supported video format entry for a camera device."""
+
+    width: int
+    height: int
+    max_fps: float
+    pixel_format: str       # e.g. "MJPG", "YUY2", "NV12", "BGRA"
+
+    def __str__(self) -> str:
+        return f"{self.pixel_format:6s} {self.width}x{self.height} @ {self.max_fps:.1f} fps"
+
+
+@dataclass
+class CameraInfo:
+    """Lightweight descriptor of a detected camera."""
+
+    device: QCameraDevice
+    name: str
+    id: str
+    formats: list[CameraFormat] = field(default_factory=list)
+
+    def __str__(self) -> str:
+        return f"{self.name} [{self.id}]"
+
+
+class CameraEnumerator:
+    """Discovers available video input devices via QMediaDevices."""
+
+    @staticmethod
+    def list_cameras() -> list[CameraInfo]:
+        """Return all available camera devices with their supported formats."""
+        devices = QMediaDevices.videoInputs()
+        cameras: list[CameraInfo] = []
+
+        for device in devices:
+            formats: list[CameraFormat] = []
+            for qfmt in device.videoFormats():
+                res = qfmt.resolution()
+                formats.append(CameraFormat(
+                    width=res.width(),
+                    height=res.height(),
+                    max_fps=qfmt.maxFrameRate(),
+                    pixel_format=pixel_format_name(qfmt.pixelFormat()),
+                ))
+
+            # deduplicate; sort: largest area first, then fps descending
+            seen: set[tuple[int, int, float, str]] = set()
+            unique: list[CameraFormat] = []
+            for f in sorted(
+                formats,
+                key=lambda x: (x.width * x.height, x.max_fps),
+                reverse=True,
+            ):
+                key = (f.width, f.height, f.max_fps, f.pixel_format)
+                if key not in seen:
+                    seen.add(key)
+                    unique.append(f)
+
+            cam_id = CameraEnumerator._device_id(device)
+            cameras.append(CameraInfo(
+                device=device,
+                name=device.description(),
+                id=cam_id,
+                formats=unique,
+            ))
+
+        logger.info("Cameras found: %d", len(cameras))
+        for idx, cam in enumerate(cameras):
+            logger.info("  [%d] %s (id: %s)", idx, cam.name, cam.id)
+            for fmt in cam.formats:
+                logger.info("        %s", fmt)
+
+        return cameras
+
+    @staticmethod
+    def default_camera() -> CameraInfo | None:
+        """Return the system default camera, or None if no camera is available."""
+        device = QMediaDevices.defaultVideoInput()
+        if device.isNull():
+            return None
+
+        default_id = CameraEnumerator._device_id(device)
+        for cam in CameraEnumerator.list_cameras():
+            if cam.id == default_id:
+                return cam
+
+        cameras = CameraEnumerator.list_cameras()
+        return cameras[0] if cameras else None
+
+    @staticmethod
+    def _device_id(device: QCameraDevice) -> str:
+        raw = device.id()
+        if hasattr(raw, "toStdString"):
+            return raw.toStdString()
+        return raw.data().decode("utf-8", errors="replace")

app/camera/camera_service.py

@@ -0,0 +1,228 @@
+"""Camera Service — manages QCamera lifecycle and frame acquisition."""
+
+from __future__ import annotations
+
+import logging
+import platform
+
+from PySide6.QtCore import QObject, Signal
+from PySide6.QtMultimedia import (
+    QCamera,
+    QMediaCaptureSession,
+    QVideoFrame,
+    QVideoSink,
+)
+
+from app.camera.camera_enumerator import CameraFormat, CameraInfo, pixel_format_name
+
+logger = logging.getLogger(__name__)
+
+
+class CameraService(QObject):
+    """
+    Manages camera initialisation, configuration and frame delivery.
+
+    Emits:
+        frame_ready(QVideoFrame)  — new frame available from the camera
+        camera_started()          — camera successfully opened and streaming
+        camera_stopped()          — camera stopped (clean shutdown)
+        camera_error(str)         — camera error description
+        format_changed(float)     — actual FPS after format was applied
+    """
+
+    frame_ready = Signal(QVideoFrame)
+    camera_started = Signal()
+    camera_stopped = Signal()
+    camera_error = Signal(str)
+    format_changed = Signal(float)
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+
+        self._camera: QCamera | None = None
+        self._session = QMediaCaptureSession(self)
+        self._sink = QVideoSink(self)
+        self._current_info: CameraInfo | None = None
+        self._session_logged: bool = False
+
+        # Desired format — applied on every (re)start
+        self._desired_fmt: CameraFormat | None = None
+
+        self._session.setVideoSink(self._sink)
+        self._sink.videoFrameChanged.connect(self._on_frame)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def start(self, camera_info: CameraInfo) -> None:
+        """Start streaming from the given camera device."""
+        self._stop_camera()
+
+        self._current_info = camera_info
+        self._camera = QCamera(camera_info.device, self)
+        self._camera.errorOccurred.connect(self._on_error)
+        self._camera.activeChanged.connect(self._on_active_changed)
+
+        self._session.setCamera(self._camera)
+        self._apply_format()
+        self._camera.start()
+        logger.info("Camera start requested: %s", camera_info.name)
+
+    def stop(self) -> None:
+        """Stop the current camera and forget the device."""
+        self._stop_camera()
+        self._current_info = None
+
+    def reconnect(self) -> None:
+        """Restart the current camera (e.g. after an error or disconnect)."""
+        if self._current_info is not None:
+            logger.info("Reconnecting camera: %s", self._current_info.name)
+            self.start(self._current_info)
+        else:
+            logger.warning("Reconnect requested but no camera was previously started")
+
+    def set_format(self, fmt: CameraFormat) -> None:
+        """
+        Request a specific video format (resolution + fps + pixel format).
+        Restarts the camera to apply the change reliably.
+        """
+        self._desired_fmt = fmt
+        if self._current_info is not None:
+            logger.info(
+                "Format change: %dx%d @ %.4g fps (%s) — restarting camera",
+                fmt.width, fmt.height, fmt.max_fps, fmt.pixel_format,
+            )
+            self.start(self._current_info)
+
+    @property
+    def is_active(self) -> bool:
+        return self._camera is not None and self._camera.isActive()
+
+    @property
+    def current_camera(self) -> CameraInfo | None:
+        return self._current_info
+
+    @property
+    def qt_camera(self) -> QCamera | None:
+        """Expose underlying QCamera for settings dialog."""
+        return self._camera
+
+    def video_sink(self) -> QVideoSink:
+        return self._sink
+
+    def capture_session(self) -> QMediaCaptureSession:
+        return self._session
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _stop_camera(self) -> None:
+        if self._camera is not None:
+            self._camera.stop()
+            self._camera.errorOccurred.disconnect()
+            self._camera.activeChanged.disconnect()
+            self._camera = None
+            logger.debug("Camera stopped (internal)")
+
+    def _apply_format(self) -> None:
+        """Select and apply the best matching QCameraFormat before start()."""
+        if self._camera is None or self._current_info is None:
+            return
+
+        best = None
+        best_score = -1
+
+        desired = self._desired_fmt
+
+        for qfmt in self._current_info.device.videoFormats():
+            res = qfmt.resolution()
+            w, h = res.width(), res.height()
+            f = qfmt.maxFrameRate()
+            pf = pixel_format_name(qfmt.pixelFormat())
+
+            if desired is not None:
+                # Exact match preferred
+                exact_res = int(w == desired.width and h == desired.height) * 1000
+                exact_fps = int(abs(f - desired.max_fps) < 0.5) * 100
+                exact_pf  = int(pf == desired.pixel_format) * 500
+                area_diff = abs(w * h - desired.width * desired.height)
+                score = exact_res + exact_fps + exact_pf - area_diff
+            else:
+                # No preference — pick largest area, then highest fps
+                score = w * h + int(f)
+
+            if score > best_score:
+                best_score = score
+                best = qfmt
+
+        if best is not None:
+            self._camera.setCameraFormat(best)
+            res = best.resolution()
+            pf = pixel_format_name(best.pixelFormat())
+            logger.info(
+                "Camera format requested: %s %dx%d @ %.4g fps",
+                pf, res.width(), res.height(), best.maxFrameRate(),
+            )
+
+    def _log_actual_format(self) -> None:
+        """Log the format the camera actually started with and emit format_changed."""
+        if self._camera is None:
+            return
+        fmt = self._camera.cameraFormat()
+        res = fmt.resolution()
+        actual_fps = fmt.maxFrameRate()
+        pf = pixel_format_name(fmt.pixelFormat())
+
+        logger.info(
+            "Camera format ACTUAL: %s %dx%d @ %.4g fps",
+            pf, res.width(), res.height(), actual_fps,
+        )
+        if self._desired_fmt is not None:
+            d = self._desired_fmt
+            if abs(actual_fps - d.max_fps) > 0.5:
+                logger.warning(
+                    "Requested %.4g fps but camera delivering %.4g fps",
+                    d.max_fps, actual_fps,
+                )
+            if res.width() != d.width or res.height() != d.height:
+                logger.warning(
+                    "Requested %dx%d but camera delivering %dx%d",
+                    d.width, d.height, res.width(), res.height(),
+                )
+        self.format_changed.emit(actual_fps)
+
+    def _log_qt_backend(self) -> None:
+        """Log the Qt multimedia backend in use (once per session)."""
+        try:
+            system = platform.system()
+            backend = {
+                "Darwin":  "AVFoundation",
+                "Windows": "Media Foundation / DirectShow",
+                "Linux":   "GStreamer / V4L2",
+            }.get(system, system)
+            logger.info("Qt multimedia backend: %s", backend)
+        except Exception:
+            pass
+
+    def _on_frame(self, frame: QVideoFrame) -> None:
+        if frame.isValid():
+            self.frame_ready.emit(frame)
+
+    def _on_error(self, error: QCamera.Error, error_string: str) -> None:
+        logger.error("Camera error %s: %s", error, error_string)
+        self.camera_error.emit(error_string)
+
+    def _on_active_changed(self, active: bool) -> None:
+        if active:
+            name = self._current_info.name if self._current_info else "?"
+            if not self._session_logged:
+                self._log_qt_backend()
+                self._session_logged = True
+            logger.info("Camera active: %s", name)
+            self._log_actual_format()
+            self.camera_started.emit()
+        else:
+            logger.info("Camera inactive")
+            self.camera_stopped.emit()

app/camera/uvc/__init__.py

@@ -0,0 +1,48 @@
+"""UVC camera controls — platform-aware factory."""
+
+from __future__ import annotations
+
+import logging
+import platform
+
+from app.camera.uvc.base import UvcControllerBase, UvcParam, UvcParamInfo
+
+logger = logging.getLogger(__name__)
+
+
+def make_uvc_controller(device_name: str) -> UvcControllerBase:
+    """
+    Return the best available UVC controller for the current platform.
+
+    Falls back to NullUvcController if the required native library is absent.
+    """
+    system = platform.system()
+
+    if system == "Windows":
+        try:
+            from app.camera.uvc.windows import WindowsUvcController  # noqa: PLC0415
+            ctrl = WindowsUvcController(device_name)
+            logger.info("UVC: Windows controller (duvc-ctl) loaded for '%s'", device_name)
+            return ctrl
+        except ImportError:
+            logger.warning(
+                "UVC: duvc-ctl not installed — install with: pip install duvc-ctl"
+            )
+    elif system == "Darwin":
+        try:
+            from app.camera.uvc.macos import MacUvcController  # noqa: PLC0415
+            ctrl = MacUvcController(device_name)
+            logger.info("UVC: macOS controller loaded for '%s'", device_name)
+            return ctrl
+        except ImportError:
+            logger.warning(
+                "UVC: pyuvc not installed — UVC controls unavailable on macOS"
+            )
+    else:
+        logger.warning("UVC: platform '%s' not supported — controls unavailable", system)
+
+    from app.camera.uvc.stub import NullUvcController  # noqa: PLC0415
+    return NullUvcController()
+
+
+__all__ = ["make_uvc_controller", "UvcControllerBase", "UvcParam", "UvcParamInfo"]

app/camera/uvc/base.py

@@ -0,0 +1,77 @@
+"""UVC controller abstract base class."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class UvcParam(Enum):
+    """UVC video proc amp controls supported by the ELP camera."""
+    BRIGHTNESS = auto()
+    CONTRAST = auto()
+    SATURATION = auto()
+    HUE = auto()
+    SHARPNESS = auto()
+    GAMMA = auto()
+    WHITE_BALANCE = auto()
+    BACKLIGHT_COMPENSATION = auto()
+    EXPOSURE = auto()
+
+
+@dataclass
+class UvcParamInfo:
+    """Range and current value of a single UVC control."""
+    param: UvcParam
+    supported: bool
+    minimum: int = 0
+    maximum: int = 100
+    default: int = 50
+    current: int = 50
+    step: int = 1
+    auto_supported: bool = False
+    auto_enabled: bool = False
+
+
+class UvcControllerBase(ABC):
+    """
+    Abstract interface for platform-specific UVC camera controls.
+
+    All set_* methods are best-effort: if a control is unsupported the
+    call should silently do nothing (log at DEBUG level).
+    """
+
+    @abstractmethod
+    def open(self, device_name: str) -> bool:
+        """Open connection to the named camera device. Returns True on success."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release the camera device handle."""
+
+    @abstractmethod
+    def is_open(self) -> bool:
+        """Return True if the device is currently open."""
+
+    @abstractmethod
+    def get_param_info(self, param: UvcParam) -> UvcParamInfo:
+        """Return range + current value for the given control."""
+
+    @abstractmethod
+    def get_all_params(self) -> list[UvcParamInfo]:
+        """Return info for all known UVC controls."""
+
+    @abstractmethod
+    def set_value(self, param: UvcParam, value: int) -> bool:
+        """
+        Set a control to an integer value.
+        Returns True if the call succeeded.
+        """
+
+    @abstractmethod
+    def set_auto(self, param: UvcParam, enabled: bool) -> bool:
+        """
+        Enable/disable auto mode for a control (e.g. auto white balance).
+        Returns True if supported and the call succeeded.
+        """

app/camera/uvc/macos.py

@@ -0,0 +1,172 @@
+"""macOS UVC controller — backed by pyuvc (libuvc bindings)."""
+
+from __future__ import annotations
+
+import logging
+
+from app.camera.uvc.base import UvcControllerBase, UvcParam, UvcParamInfo
+from app.camera.uvc.stub import NullUvcController
+
+logger = logging.getLogger(__name__)
+
+# pyuvc provides access to UVC controls via libuvc.
+# Install: pip install pyuvc  (requires libusb + libjpeg-turbo via brew)
+#
+# If pyuvc is not installed, fall back silently to NullUvcController.
+try:
+    import uvc  # type: ignore[import-untyped]
+    _PYUVC_AVAILABLE = True
+except ImportError:
+    _PYUVC_AVAILABLE = False
+    logger.debug("pyuvc not available — macOS UVC controls disabled")
+
+
+# Map UvcParam → pyuvc control name string
+_CONTROL_NAME: dict[UvcParam, str] = {
+    UvcParam.BRIGHTNESS:             "Brightness",
+    UvcParam.CONTRAST:               "Contrast",
+    UvcParam.SATURATION:             "Saturation",
+    UvcParam.HUE:                    "Hue",
+    UvcParam.SHARPNESS:              "Sharpness",
+    UvcParam.GAMMA:                  "Gamma",
+    UvcParam.WHITE_BALANCE:          "White Balance temperature",
+    UvcParam.BACKLIGHT_COMPENSATION: "Backlight Compensation",
+    UvcParam.EXPOSURE:               "Absolute Exposure Time",
+}
+
+
+class MacUvcController(UvcControllerBase):
+    """
+    UVC camera controls on macOS via pyuvc / libuvc.
+
+    pyuvc: https://github.com/pupil-labs/pyuvc
+    Install: pip install pyuvc  (requires: brew install libusb jpeg-turbo)
+    """
+
+    def __init__(self, device_name: str) -> None:
+        if not _PYUVC_AVAILABLE:
+            raise ImportError("pyuvc not installed")
+        self._device_name = device_name
+        self._cap: object | None = None
+        self._controls: dict[str, object] = {}
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def open(self, device_name: str) -> bool:
+        self.close()
+        if not _PYUVC_AVAILABLE:
+            return False
+        try:
+            device_list = uvc.device_list()
+            target = None
+            for d in device_list:
+                if device_name.lower() in d.get("name", "").lower():
+                    target = d
+                    break
+            if target is None and device_list:
+                target = device_list[0]
+                logger.warning(
+                    "UVC: camera '%s' not found by name, using '%s'",
+                    device_name, target.get("name"),
+                )
+            if target is None:
+                logger.warning("UVC: no UVC devices found on macOS")
+                return False
+
+            self._cap = uvc.Capture(target["uid"])
+            # Index controls by name for fast lookup
+            self._controls = {c.display_name: c for c in self._cap.controls}
+            logger.info(
+                "UVC: opened '%s', controls: %s",
+                target.get("name"), list(self._controls.keys()),
+            )
+            return True
+        except Exception as exc:
+            logger.warning("UVC macOS open failed: %s", exc)
+            self._cap = None
+            return False
+
+    def close(self) -> None:
+        if self._cap is not None:
+            try:
+                self._cap.close()
+            except Exception:
+                pass
+            self._cap = None
+            self._controls.clear()
+
+    def is_open(self) -> bool:
+        return self._cap is not None
+
+    # ------------------------------------------------------------------
+    # Query
+    # ------------------------------------------------------------------
+
+    def get_param_info(self, param: UvcParam) -> UvcParamInfo:
+        ctrl_name = _CONTROL_NAME.get(param)
+        if ctrl_name is None or ctrl_name not in self._controls:
+            return UvcParamInfo(param=param, supported=False)
+        try:
+            ctrl = self._controls[ctrl_name]
+            auto_supported = hasattr(ctrl, "auto_mode")
+            auto_enabled = bool(ctrl.auto_mode) if auto_supported else False
+            return UvcParamInfo(
+                param=param,
+                supported=True,
+                minimum=int(ctrl.min_val),
+                maximum=int(ctrl.max_val),
+                default=int(ctrl.def_val),
+                current=int(ctrl.value),
+                step=int(getattr(ctrl, "step", 1)),
+                auto_supported=auto_supported,
+                auto_enabled=auto_enabled,
+            )
+        except Exception as exc:
+            logger.debug("UVC get_param_info(%s): %s", param.name, exc)
+            return UvcParamInfo(param=param, supported=False)
+
+    def get_all_params(self) -> list[UvcParamInfo]:
+        return [self.get_param_info(p) for p in UvcParam]
+
+    # ------------------------------------------------------------------
+    # Set
+    # ------------------------------------------------------------------
+
+    def set_value(self, param: UvcParam, value: int) -> bool:
+        ctrl_name = _CONTROL_NAME.get(param)
+        if ctrl_name is None or ctrl_name not in self._controls:
+            return False
+        try:
+            self._controls[ctrl_name].value = value
+            logger.debug("UVC set %s = %d", param.name, value)
+            return True
+        except Exception as exc:
+            logger.warning("UVC set_value(%s, %d): %s", param.name, value, exc)
+            return False
+
+    def set_auto(self, param: UvcParam, enabled: bool) -> bool:
+        ctrl_name = _CONTROL_NAME.get(param)
+        if ctrl_name is None or ctrl_name not in self._controls:
+            return False
+        try:
+            ctrl = self._controls[ctrl_name]
+            if hasattr(ctrl, "auto_mode"):
+                ctrl.auto_mode = enabled
+                logger.debug("UVC auto %s = %s", param.name, enabled)
+                return True
+            return False
+        except Exception as exc:
+            logger.warning("UVC set_auto(%s, %s): %s", param.name, enabled, exc)
+            return False
+
+
+def make_mac_uvc_controller(device_name: str) -> UvcControllerBase:
+    """Factory: returns MacUvcController or NullUvcController if pyuvc absent."""
+    if not _PYUVC_AVAILABLE:
+        return NullUvcController()
+    ctrl = MacUvcController(device_name)
+    if ctrl.open(device_name):
+        return ctrl
+    return NullUvcController()

app/camera/uvc/stub.py

@@ -0,0 +1,43 @@
+"""Null (no-op) UVC controller — used when no native library is available."""
+
+from __future__ import annotations
+
+import logging
+
+from app.camera.uvc.base import UvcControllerBase, UvcParam, UvcParamInfo
+
+logger = logging.getLogger(__name__)
+
+
+class NullUvcController(UvcControllerBase):
+    """
+    Fallback controller that reports all controls as unsupported.
+
+    Used on platforms where no UVC library is installed or when device
+    enumeration fails.
+    """
+
+    def open(self, device_name: str) -> bool:  # noqa: ARG002
+        return False
+
+    def close(self) -> None:
+        pass
+
+    def is_open(self) -> bool:
+        return False
+
+    def get_param_info(self, param: UvcParam) -> UvcParamInfo:
+        return UvcParamInfo(param=param, supported=False)
+
+    def get_all_params(self) -> list[UvcParamInfo]:
+        return [UvcParamInfo(param=p, supported=False) for p in UvcParam]
+
+    def set_value(self, param: UvcParam, value: int) -> bool:  # noqa: ARG002
+        logger.debug("NullUvcController: set_value ignored (%s=%d)", param.name, value)
+        return False
+
+    def set_auto(self, param: UvcParam, enabled: bool) -> bool:  # noqa: ARG002
+        logger.debug(
+            "NullUvcController: set_auto ignored (%s, auto=%s)", param.name, enabled
+        )
+        return False

app/camera/uvc/windows.py

@@ -0,0 +1,175 @@
+"""Windows UVC controller — backed by duvc-ctl (DirectShow)."""
+
+from __future__ import annotations
+
+import logging
+
+import duvc_ctl as duvc  # type: ignore[import-untyped]  # noqa: PLC0415 (lazy import)
+
+from app.camera.uvc.base import UvcControllerBase, UvcParam, UvcParamInfo
+
+logger = logging.getLogger(__name__)
+
+# Map our UvcParam → duvc_ctl VidProp string name
+_VIDPROP: dict[UvcParam, str] = {
+    UvcParam.BRIGHTNESS:             "brightness",
+    UvcParam.CONTRAST:               "contrast",
+    UvcParam.SATURATION:             "saturation",
+    UvcParam.HUE:                    "hue",
+    UvcParam.SHARPNESS:              "sharpness",
+    UvcParam.GAMMA:                  "gamma",
+    UvcParam.WHITE_BALANCE:          "white_balance",
+    UvcParam.BACKLIGHT_COMPENSATION: "backlight_compensation",
+}
+
+# Map UvcParam → duvc_ctl CamProp string for camera-side controls
+_CAMPROP: dict[UvcParam, str] = {
+    UvcParam.EXPOSURE: "exposure",
+}
+
+
+class WindowsUvcController(UvcControllerBase):
+    """
+    UVC camera controls on Windows via duvc-ctl (DirectShow).
+
+    duvc-ctl docs: https://allanhanan.github.io/duvc-ctl/
+    """
+
+    def __init__(self, device_name: str) -> None:
+        self._device_name = device_name
+        self._cam: duvc.CameraController | None = None
+        self._supported: dict[UvcParam, bool] = {}
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def open(self, device_name: str) -> bool:
+        self.close()
+        try:
+            devices = duvc.list_devices()
+            target = None
+            for d in devices:
+                if device_name.lower() in d.name.lower() or d.name.lower() in device_name.lower():
+                    target = d
+                    break
+            if target is None and devices:
+                target = devices[0]  # fallback to first device
+                logger.warning(
+                    "UVC: camera '%s' not found by name, using '%s'",
+                    device_name, target.name,
+                )
+
+            if target is None:
+                logger.warning("UVC: no devices found on Windows")
+                return False
+
+            self._cam = duvc.CameraController(target)
+            self._cam.__enter__()
+            self._refresh_supported()
+            logger.info("UVC: opened device '%s'", target.name)
+            return True
+        except Exception as exc:
+            logger.warning("UVC: failed to open device: %s", exc)
+            self._cam = None
+            return False
+
+    def close(self) -> None:
+        if self._cam is not None:
+            try:
+                self._cam.__exit__(None, None, None)
+            except Exception:
+                pass
+            self._cam = None
+            self._supported.clear()
+
+    def is_open(self) -> bool:
+        return self._cam is not None
+
+    # ------------------------------------------------------------------
+    # Query
+    # ------------------------------------------------------------------
+
+    def get_param_info(self, param: UvcParam) -> UvcParamInfo:
+        if not self.is_open() or not self._supported.get(param, False):
+            return UvcParamInfo(param=param, supported=False)
+
+        try:
+            prop_name = _VIDPROP.get(param) or _CAMPROP.get(param)
+            if prop_name is None:
+                return UvcParamInfo(param=param, supported=False)
+
+            rng = self._cam.get_property_range(prop_name)
+            current = getattr(self._cam, prop_name, rng.get("default", 0))
+            auto_supported = param in (UvcParam.WHITE_BALANCE, UvcParam.EXPOSURE)
+            return UvcParamInfo(
+                param=param,
+                supported=True,
+                minimum=int(rng.get("min", 0)),
+                maximum=int(rng.get("max", 100)),
+                default=int(rng.get("default", 50)),
+                current=int(current),
+                step=int(rng.get("step", 1)),
+                auto_supported=auto_supported,
+            )
+        except Exception as exc:
+            logger.debug("UVC get_param_info(%s): %s", param.name, exc)
+            return UvcParamInfo(param=param, supported=False)
+
+    def get_all_params(self) -> list[UvcParamInfo]:
+        return [self.get_param_info(p) for p in UvcParam]
+
+    # ------------------------------------------------------------------
+    # Set
+    # ------------------------------------------------------------------
+
+    def set_value(self, param: UvcParam, value: int) -> bool:
+        if not self.is_open():
+            return False
+        try:
+            prop_name = _VIDPROP.get(param) or _CAMPROP.get(param)
+            if prop_name is None:
+                return False
+            setattr(self._cam, prop_name, value)
+            logger.debug("UVC set %s = %d", param.name, value)
+            return True
+        except Exception as exc:
+            logger.warning("UVC set_value(%s, %d): %s", param.name, value, exc)
+            return False
+
+    def set_auto(self, param: UvcParam, enabled: bool) -> bool:
+        if not self.is_open():
+            return False
+        try:
+            if param == UvcParam.WHITE_BALANCE:
+                prop = "white_balance"
+            elif param == UvcParam.EXPOSURE:
+                prop = "exposure"
+            else:
+                return False
+            mode = duvc.CamMode.AUTO if enabled else duvc.CamMode.MANUAL
+            self._cam.set_camera_property(prop, mode=mode)
+            logger.debug("UVC auto %s = %s", param.name, enabled)
+            return True
+        except Exception as exc:
+            logger.warning("UVC set_auto(%s, %s): %s", param.name, enabled, exc)
+            return False
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _refresh_supported(self) -> None:
+        if self._cam is None:
+            return
+        try:
+            info = self._cam.get_supported_properties()
+            vid = set(info.get("video", []))
+            cam = set(info.get("camera", []))
+            for param in UvcParam:
+                prop = _VIDPROP.get(param) or _CAMPROP.get(param, "")
+                self._supported[param] = prop in vid or prop in cam
+        except Exception as exc:
+            logger.debug("UVC _refresh_supported: %s", exc)
+            for param in UvcParam:
+                self._supported[param] = False

app/config.py

@@ -0,0 +1,46 @@
+"""Application-wide constants and default settings."""
+
+from pathlib import Path
+
+APP_NAME = "Duck Preview"
+APP_VERSION = "0.1.0"
+
+# Default camera settings
+DEFAULT_FPS = 30
+DEFAULT_WIDTH = 1280
+DEFAULT_HEIGHT = 720
+
+# Telemetry
+TELEMETRY_UPDATE_INTERVAL_MS = 500  # how often the metrics snapshot is refreshed
+
+# Overlay
+OVERLAY_BG_COLOR = (0, 0, 0, 160)   # RGBA
+OVERLAY_TEXT_COLOR = (255, 255, 255, 255)
+OVERLAY_FONT_SIZE = 13
+OVERLAY_PADDING = 10
+OVERLAY_MARGIN = 10
+
+# Frame dispatcher
+DISPATCHER_MAX_QUEUE_SIZE = 2  # max pending frames per slow subscriber before drop
+
+# Logging
+LOG_DIR = Path("logs")              # relative to CWD (project root)
+MAX_LOG_FILES = 20                  # oldest sessions are deleted when exceeded
+TELEMETRY_CSV_INTERVAL_S = 5.0     # how often a CSV row is written (seconds)
+
+# Inference worker
+INFERENCE_WORKER_TIMEOUT_S = 10.0  # seconds without response before watchdog fires
+INFERENCE_MAX_RESTARTS = 3         # max auto-restart attempts before giving up
+INFERENCE_POLL_INTERVAL_MS = 50    # how often GUI thread polls output queue (ms)
+INFERENCE_WATCHDOG_INTERVAL_MS = 2000  # how often watchdog checks process health (ms)
+
+# BBox overlay
+BBOX_COLOR = (0, 220, 60, 255)          # RGBA — vivid green
+BBOX_LABEL_BG_COLOR = (0, 220, 60, 200) # RGBA — semi-transparent green for label bg
+BBOX_LABEL_TEXT_COLOR = (0, 0, 0, 255)  # RGBA — black text on green bg
+BBOX_LINE_WIDTH = 2
+BBOX_FONT_SIZE = 11
+
+# Video file source
+VIDEO_FILE_EXTENSIONS = "Video Files (*.mp4 *.avi *.mov *.mkv *.m4v *.webm)"
+MODEL_FILE_EXTENSIONS = "YOLO Model (*.pt *.pth)"

app/inference/bbox_overlay.py

@@ -0,0 +1,154 @@
+"""BboxOverlay — draws YOLO detection bounding boxes on the camera view."""
+
+from __future__ import annotations
+
+import logging
+from typing import NamedTuple
+
+from PySide6.QtCore import QRect, QSize, Qt, Slot
+from PySide6.QtGui import QColor, QFont, QPainter, QPen
+
+from app.config import (
+    BBOX_COLOR,
+    BBOX_FONT_SIZE,
+    BBOX_LABEL_BG_COLOR,
+    BBOX_LABEL_TEXT_COLOR,
+    BBOX_LINE_WIDTH,
+)
+from app.overlay.overlay_layer import IOverlayLayer
+
+logger = logging.getLogger(__name__)
+
+
+class Detection(NamedTuple):
+    """
+    A single object detection result.
+
+    Coordinates (x1, y1, x2, y2) are in pixels of the *source frame*
+    (i.e. the frame that was submitted to inference).  BboxOverlay maps
+    them to the letterboxed video_rect before drawing.
+    """
+
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+    conf: float
+    label: str
+
+
+class BboxOverlay(IOverlayLayer):
+    """
+    Overlay layer that renders detection bounding boxes.
+
+    Usage:
+        overlay = BboxOverlay()
+        camera_view.add_overlay_layer(overlay)
+        inference_manager.detections_ready.connect(overlay.on_detections)
+
+    Thread safety:
+        on_detections() is called from the GUI thread (via Qt signal).
+        paint() is also called from the GUI thread (paintEvent).
+        No locks required.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._detections: list[Detection] = []
+        self._source_size: QSize = QSize(0, 0)
+
+        self._pen = QPen(QColor(*BBOX_COLOR))
+        self._pen.setWidth(BBOX_LINE_WIDTH)
+        self._pen.setJoinStyle(Qt.PenJoinStyle.MiterJoin)
+
+        self._font = QFont("Monospace")
+        self._font.setStyleHint(QFont.StyleHint.TypeWriter)
+        self._font.setPointSize(BBOX_FONT_SIZE)
+        self._font.setBold(True)
+
+        self._box_color = QColor(*BBOX_COLOR)
+        self._bg_color = QColor(*BBOX_LABEL_BG_COLOR)
+        self._text_color = QColor(*BBOX_LABEL_TEXT_COLOR)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @Slot(object, object)
+    def on_detections(
+        self,
+        detections: list[Detection],
+        source_size: tuple[int, int],
+    ) -> None:
+        """
+        Receive detection results from InferenceManager.
+
+        Args:
+            detections:  List of Detection namedtuples (pixel coords).
+            source_size: (width, height) of the frame that was inferred.
+        """
+        self._detections = detections
+        self._source_size = QSize(*source_size)
+
+    def clear(self) -> None:
+        """Remove all currently displayed detections."""
+        self._detections = []
+
+    # ------------------------------------------------------------------
+    # IOverlayLayer implementation
+    # ------------------------------------------------------------------
+
+    def paint(self, painter: QPainter, video_rect: QRect) -> None:
+        if not self._detections:
+            return
+        if self._source_size.isEmpty():
+            return
+
+        src_w = self._source_size.width()
+        src_h = self._source_size.height()
+        vr = video_rect
+
+        # Scale factors: source-pixel → video_rect-pixel
+        scale_x = vr.width() / src_w
+        scale_y = vr.height() / src_h
+
+        painter.setFont(self._font)
+        fm = painter.fontMetrics()
+
+        for det in self._detections:
+            # Map to widget coordinates
+            wx1 = vr.x() + int(det.x1 * scale_x)
+            wy1 = vr.y() + int(det.y1 * scale_y)
+            wx2 = vr.x() + int(det.x2 * scale_x)
+            wy2 = vr.y() + int(det.y2 * scale_y)
+
+            box_rect = QRect(wx1, wy1, wx2 - wx1, wy2 - wy1)
+
+            # Draw bounding box
+            painter.setPen(self._pen)
+            painter.setBrush(Qt.BrushStyle.NoBrush)
+            painter.drawRect(box_rect)
+
+            # Label text: "label 0.87"
+            label_text = f"{det.label} {det.conf:.2f}"
+            text_w = fm.horizontalAdvance(label_text) + 6
+            text_h = fm.height() + 2
+
+            # Position label above box, clamped to video_rect
+            lx = wx1
+            ly = wy1 - text_h
+            if ly < vr.top():
+                ly = wy1  # draw inside box if no room above
+
+            label_bg = QRect(lx, ly, text_w, text_h)
+
+            painter.setPen(Qt.PenStyle.NoPen)
+            painter.setBrush(self._bg_color)
+            painter.drawRect(label_bg)
+
+            painter.setPen(QPen(self._text_color))
+            painter.drawText(
+                lx + 3,
+                ly + fm.ascent() + 1,
+                label_text,
+            )

app/inference/worker.py

@@ -0,0 +1,219 @@
+"""YOLO inference worker — runs in a separate process.
+
+This module contains only plain functions (no Qt, no PySide6) so it can
+safely be imported and executed in a child process via multiprocessing.
+
+IPC protocol
+------------
+input_queue  receives : FramePacket       (frame_id, raw_bytes, width, height, channels)
+output_queue sends    : WorkerReadyPacket (device)  — once after model load
+                      : ResultPacket      (frame_id, detections, width, height, elapsed_ms)
+                      : None              — on fatal load failure
+stop_event           : multiprocessing.Event — set by parent to request clean exit
+
+Detection format (namedtuple-compatible plain tuple):
+    (x1, y1, x2, y2, conf, label)  — all floats/str, x/y in source-frame pixels
+"""
+
+from __future__ import annotations
+
+import logging
+import platform
+import sys
+from multiprocessing import Event, Queue
+from queue import Empty
+from typing import NamedTuple
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Data structures shared between worker and manager
+# ---------------------------------------------------------------------------
+
+class FramePacket(NamedTuple):
+    frame_id: int
+    raw_bytes: bytes       # RGB bytes, row-major, shape = (height, width, channels)
+    width: int
+    height: int
+    channels: int          # always 3 (RGB)
+
+
+class WorkerReadyPacket(NamedTuple):
+    """
+    Sent once by the worker right after the model is loaded.
+    Carries the device string so the GUI can display it.
+    """
+    device: str            # e.g. "cpu", "mps"
+
+
+class ResultPacket(NamedTuple):
+    frame_id: int
+    detections: list       # list of (x1, y1, x2, y2, conf, label) tuples
+    width: int             # source frame width (for overlay scaling)
+    height: int            # source frame height
+    elapsed_ms: float = 0.0  # inference wall-clock time in milliseconds
+
+
+# ---------------------------------------------------------------------------
+# Worker entry point
+# ---------------------------------------------------------------------------
+
+def run_worker(
+    model_path: str,
+    input_queue: Queue,
+    output_queue: Queue,
+    stop_event: Event,
+    log_level: int = logging.WARNING,
+) -> None:
+    """
+    Main loop of the inference worker process.
+
+    Loads the YOLO model once, sends WorkerReadyPacket, then processes
+    frames from input_queue until stop_event is set.
+    Results are posted to output_queue.
+
+    This function is designed to be the target of multiprocessing.Process.
+    It must NOT import PySide6 or any Qt module.
+    """
+    _configure_worker_logging(log_level)
+    logger.info("Inference worker starting (pid=%d)", _getpid())
+
+    # Select device once — never changes during the lifetime of this process
+    device = _select_device()
+
+    try:
+        model = _load_model(model_path, device)
+    except Exception as exc:
+        logger.error("Failed to load model '%s': %s", model_path, exc)
+        # Signal failure by putting None — manager treats it as error
+        output_queue.put(None)
+        return
+
+    logger.info("Model loaded: %s  device=%s", model_path, device)
+
+    # Notify GUI thread of the device being used
+    output_queue.put(WorkerReadyPacket(device=device))
+
+    while not stop_event.is_set():
+        try:
+            packet: FramePacket = input_queue.get(timeout=0.1)
+        except Empty:
+            continue
+        except Exception as exc:
+            logger.error("Error reading input queue: %s", exc)
+            break
+
+        try:
+            result = _infer(model, packet, device)
+            output_queue.put(result)
+        except Exception as exc:
+            logger.error("Inference error (frame %d): %s", packet.frame_id, exc)
+            # Put empty result so manager knows we're still alive
+            output_queue.put(ResultPacket(
+                frame_id=packet.frame_id,
+                detections=[],
+                width=packet.width,
+                height=packet.height,
+            ))
+
+    logger.info("Inference worker stopping")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _load_model(model_path: str, device: str):
+    """Load YOLO model and warm up on the selected device."""
+    from ultralytics import YOLO  # noqa: PLC0415
+
+    logger.info("Loading YOLO model on device='%s'", device)
+    model = YOLO(model_path)
+    # Warm up — run on a tiny dummy to JIT-compile kernels
+    try:
+        import numpy as np  # noqa: PLC0415
+        dummy = np.zeros((64, 64, 3), dtype=np.uint8)
+        model(dummy, device=device, verbose=False)
+    except Exception as exc:
+        logger.warning("Warm-up failed (non-fatal): %s", exc)
+    return model
+
+
+def _select_device() -> str:
+    """
+    Choose the best available inference device.
+
+    Priority:
+      - macOS  → "mps" if torch.backends.mps.is_available(), else "cpu"
+      - others → "cpu"
+
+    Called once at worker startup — not per frame.
+    """
+    system = platform.system()
+    if system == "Darwin":
+        try:
+            import torch  # noqa: PLC0415
+            if torch.backends.mps.is_available():
+                logger.info("MPS (Metal) available — using GPU")
+                return "mps"
+        except Exception:
+            pass
+        logger.info("MPS not available — using CPU")
+    return "cpu"
+
+
+def _infer(model, packet: FramePacket, device: str) -> ResultPacket:
+    """Run model on one frame, return ResultPacket with elapsed_ms."""
+    import time  # noqa: PLC0415
+
+    import numpy as np  # noqa: PLC0415
+
+    frame_np = np.frombuffer(packet.raw_bytes, dtype=np.uint8).reshape(
+        (packet.height, packet.width, packet.channels)
+    )
+
+    t0 = time.perf_counter()
+    results = model(frame_np, device=device, verbose=False)
+    elapsed_ms = (time.perf_counter() - t0) * 1000.0
+
+    detections = []
+    for r in results:
+        if r.boxes is None:
+            continue
+        boxes = r.boxes
+        for i in range(len(boxes)):
+            xyxy = boxes.xyxy[i].tolist()   # [x1, y1, x2, y2] in source pixels
+            conf = float(boxes.conf[i])
+            cls_idx = int(boxes.cls[i])
+            label = (
+                r.names[cls_idx]
+                if r.names and cls_idx in r.names
+                else str(cls_idx)
+            )
+            detections.append((
+                float(xyxy[0]), float(xyxy[1]),
+                float(xyxy[2]), float(xyxy[3]),
+                conf, label,
+            ))
+
+    return ResultPacket(
+        frame_id=packet.frame_id,
+        detections=detections,
+        width=packet.width,
+        height=packet.height,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def _configure_worker_logging(level: int) -> None:
+    logging.basicConfig(
+        level=level,
+        format="[worker %(process)d] %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+def _getpid() -> int:
+    import os  # noqa: PLC0415
+    return os.getpid()

app/inference/worker_manager.py

@@ -0,0 +1,401 @@
+"""InferenceManager — orchestrates the YOLO worker process from the GUI thread.
+
+Responsibilities:
+  - Start / stop the worker process
+  - Submit frames (with drop-if-busy logic)
+  - Poll result queue via QTimer (never blocks the GUI thread)
+  - Watch process health via QTimer (auto-restart on crash)
+  - Emit Qt signals with results for BboxOverlay and TelemetryCollector
+"""
+
+from __future__ import annotations
+
+import collections
+import logging
+import multiprocessing
+import time
+from pathlib import Path
+
+from PySide6.QtCore import QObject, QTimer, Signal, Slot
+from PySide6.QtMultimedia import QVideoFrame
+
+from app.config import (
+    INFERENCE_MAX_RESTARTS,
+    INFERENCE_POLL_INTERVAL_MS,
+    INFERENCE_WATCHDOG_INTERVAL_MS,
+    INFERENCE_WORKER_TIMEOUT_S,
+)
+from app.inference.bbox_overlay import Detection
+from app.inference.worker import FramePacket, ResultPacket, WorkerReadyPacket, run_worker
+
+logger = logging.getLogger(__name__)
+
+# Number of recent inference times to average for the overlay display
+_ELAPSED_WINDOW = 10
+
+
+class InferenceManager(QObject):
+    """
+    Manages the YOLO worker subprocess.
+
+    Signals:
+        detections_ready(detections, source_size)
+            Emitted in the GUI thread when a result arrives.
+            detections   : list[Detection]
+            source_size  : tuple[int, int] — (width, height) of inferred frame
+
+        detection_count_updated(int)
+            Total number of frames on which at least one detection occurred.
+
+        inference_stats_updated(device, avg_ms)
+            Emitted after every result packet.
+            device  : str   — e.g. "cpu", "mps"
+            avg_ms  : float — rolling average of inference time (last 10 frames)
+
+        inference_device_changed(str)
+            Emitted once when the worker reports its device after model load.
+
+        inference_started()   — worker is up and model is loaded
+        inference_stopped()   — worker has exited cleanly
+        inference_error(str)  — fatal error (max restarts exceeded)
+    """
+
+    detections_ready = Signal(object, object)   # list[Detection], tuple[int,int]
+    detection_count_updated = Signal(int)       # total frames with detections so far
+    inference_stats_updated = Signal(str, float)  # device, avg_elapsed_ms
+    inference_device_changed = Signal(str)      # emitted once on WorkerReadyPacket
+    inference_started = Signal()
+    inference_stopped = Signal()
+    inference_error = Signal(str)
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+
+        self._model_path: str | None = None
+        self._process: multiprocessing.Process | None = None
+        self._input_queue: multiprocessing.Queue | None = None
+        self._output_queue: multiprocessing.Queue | None = None
+        self._stop_event: multiprocessing.Event | None = None
+
+        # Drop-if-busy flag — True while worker is processing a frame
+        self._busy: bool = False
+        self._frame_id: int = 0
+
+        # Restart tracking
+        self._restart_count: int = 0
+        self._last_result_time: float = 0.0
+
+        # Paused flag — inference can be suspended without stopping the process
+        self._paused: bool = False
+
+        # Detection counter — frames on which at least one detection occurred
+        self._detection_frame_count: int = 0
+
+        # Device reported by the worker after model load
+        self._current_device: str = "cpu"
+
+        # Rolling window of recent elapsed_ms values for averaging
+        self._elapsed_window: collections.deque[float] = collections.deque(
+            maxlen=_ELAPSED_WINDOW
+        )
+
+        # QTimers (GUI thread)
+        self._poll_timer = QTimer(self)
+        self._poll_timer.setInterval(INFERENCE_POLL_INTERVAL_MS)
+        self._poll_timer.timeout.connect(self._poll_output)
+
+        self._watchdog_timer = QTimer(self)
+        self._watchdog_timer.setInterval(INFERENCE_WATCHDOG_INTERVAL_MS)
+        self._watchdog_timer.timeout.connect(self._watchdog_check)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def start(self, model_path: str) -> None:
+        """Load model and start the worker process."""
+        if not Path(model_path).exists():
+            msg = f"Model file not found: {model_path}"
+            logger.error(msg)
+            self.inference_error.emit(msg)
+            return
+
+        self._stop_worker()
+        self._model_path = model_path
+        self._restart_count = 0
+        self._paused = False
+        self._detection_frame_count = 0
+        self._elapsed_window.clear()
+        self._current_device = "cpu"
+        self._start_worker()
+
+    def stop(self) -> None:
+        """Stop the worker process and reset state."""
+        self._stop_worker()
+        self._model_path = None
+        self._restart_count = 0
+        self._paused = False
+
+    def pause(self) -> None:
+        """Suspend frame submission without stopping the process."""
+        self._paused = True
+        logger.debug("InferenceManager: paused")
+
+    def resume(self) -> None:
+        """Resume frame submission."""
+        self._paused = False
+        logger.debug("InferenceManager: resumed")
+
+    @property
+    def is_running(self) -> bool:
+        return self._process is not None and self._process.is_alive()
+
+    @property
+    def is_paused(self) -> bool:
+        return self._paused
+
+    @property
+    def model_path(self) -> str | None:
+        return self._model_path
+
+    @property
+    def current_device(self) -> str:
+        return self._current_device
+
+    @Slot(QVideoFrame)
+    def submit_frame(self, frame: QVideoFrame) -> None:
+        """
+        Attempt to submit a frame for inference.
+
+        Drops the frame silently if:
+          - manager is not running
+          - manager is paused
+          - worker is still busy with previous frame (drop_if_busy)
+
+        Frame conversion strategy:
+          Use QVideoFrame.toImage() → QImage.Format_RGB32 → bits().
+          This handles all pixel formats (NV12, YUV420P, BGRA, MJPG, etc.)
+          because Qt decodes them internally.  The cost is a CPU colour-space
+          conversion, but it only happens when the worker is idle (drop_if_busy).
+        """
+        if not self.is_running or self._paused or self._busy:
+            return
+
+        if not frame.isValid():
+            return
+
+        # Convert frame to RGB via Qt's built-in decoder.
+        # toImage() handles NV12, YUV420P, MJPG, BGRA — any pixel format.
+        image = frame.toImage()
+        if image.isNull():
+            logger.warning("InferenceManager: toImage() returned null")
+            return
+
+        width = image.width()
+        height = image.height()
+
+        # Ensure we have packed RGB32 (BGRX on little-endian, 4 bytes/pixel)
+        from PySide6.QtGui import QImage  # noqa: PLC0415
+        if image.format() != QImage.Format.Format_RGB32:
+            image = image.convertToFormat(QImage.Format.Format_RGB32)
+
+        # Extract RGB bytes (drop alpha/padding channel)
+        try:
+            import numpy as np  # noqa: PLC0415
+            # bits() returns BGRX (B G R 0xFF) for Format_RGB32
+            ptr = image.bits()
+            arr = np.frombuffer(ptr, dtype=np.uint8).reshape((height, width, 4))
+            # Swap B↔R and drop X → RGB
+            rgb = arr[:, :, [2, 1, 0]].copy()
+            raw = rgb.tobytes()
+        except Exception as exc:
+            logger.warning("InferenceManager: frame conversion failed: %s", exc)
+            return
+
+        channels = 3
+
+        self._frame_id += 1
+        packet = FramePacket(
+            frame_id=self._frame_id,
+            raw_bytes=raw,
+            width=width,
+            height=height,
+            channels=channels,
+        )
+
+        try:
+            self._input_queue.put_nowait(packet)
+            self._busy = True
+        except Exception as exc:
+            logger.warning("InferenceManager: could not enqueue frame: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Private — worker lifecycle
+    # ------------------------------------------------------------------
+
+    def _start_worker(self) -> None:
+        ctx = multiprocessing.get_context("spawn")
+        self._input_queue = ctx.Queue(maxsize=1)
+        self._output_queue = ctx.Queue(maxsize=4)
+        self._stop_event = ctx.Event()
+
+        self._process = ctx.Process(
+            target=run_worker,
+            args=(
+                self._model_path,
+                self._input_queue,
+                self._output_queue,
+                self._stop_event,
+                logging.WARNING,
+            ),
+            daemon=True,
+            name="inference-worker",
+        )
+        self._process.start()
+        self._busy = False
+        self._last_result_time = time.monotonic()
+
+        self._poll_timer.start()
+        self._watchdog_timer.start()
+        logger.info(
+            "Inference worker started (pid=%d, model=%s)",
+            self._process.pid, self._model_path,
+        )
+        self.inference_started.emit()
+
+    def _stop_worker(self) -> None:
+        self._poll_timer.stop()
+        self._watchdog_timer.stop()
+
+        if self._stop_event is not None:
+            self._stop_event.set()
+
+        if self._process is not None:
+            self._process.join(timeout=3.0)
+            if self._process.is_alive():
+                logger.warning("Worker did not stop cleanly — terminating")
+                self._process.terminate()
+                self._process.join(timeout=2.0)
+            self._process = None
+
+        self._input_queue = None
+        self._output_queue = None
+        self._stop_event = None
+        self._busy = False
+
+        logger.info("Inference worker stopped")
+        self.inference_stopped.emit()
+
+    # ------------------------------------------------------------------
+    # Private — timers
+    # ------------------------------------------------------------------
+
+    @Slot()
+    def _poll_output(self) -> None:
+        """Drain the output queue (called every INFERENCE_POLL_INTERVAL_MS ms)."""
+        if self._output_queue is None:
+            return
+
+        try:
+            while True:
+                item = self._output_queue.get_nowait()
+
+                if item is None:
+                    # Worker signalled a fatal load error
+                    logger.error("Worker reported model load failure")
+                    self._handle_crash("Model failed to load in worker process")
+                    return
+
+                # ----------------------------------------------------------
+                # WorkerReadyPacket — sent once after model load
+                # ----------------------------------------------------------
+                if isinstance(item, WorkerReadyPacket):
+                    self._current_device = item.device
+                    logger.info("Inference device: %s", item.device)
+                    self.inference_device_changed.emit(item.device)
+                    continue
+
+                # ----------------------------------------------------------
+                # ResultPacket — regular inference result
+                # ----------------------------------------------------------
+                packet: ResultPacket = item
+                self._busy = False
+                self._last_result_time = time.monotonic()
+
+                # Update rolling average of elapsed time
+                self._elapsed_window.append(packet.elapsed_ms)
+                avg_ms = sum(self._elapsed_window) / len(self._elapsed_window)
+
+                detections = [
+                    Detection(x1, y1, x2, y2, conf, label)
+                    for x1, y1, x2, y2, conf, label in packet.detections
+                ]
+                source_size = (packet.width, packet.height)
+
+                if detections:
+                    self._detection_frame_count += 1
+                    conf_summary = ", ".join(
+                        f"{d.label} {d.conf:.2f}" for d in detections
+                    )
+                    logger.info(
+                        "frame %d: %d detection(s) in %.1f ms — %s",
+                        packet.frame_id,
+                        len(detections),
+                        packet.elapsed_ms,
+                        conf_summary,
+                    )
+                    self.detection_count_updated.emit(self._detection_frame_count)
+
+                # Always emit stats so overlay stays current
+                self.inference_stats_updated.emit(self._current_device, avg_ms)
+                self.detections_ready.emit(detections, source_size)
+
+        except Exception:
+            # Empty queue — normal
+            pass
+
+    @Slot()
+    def _watchdog_check(self) -> None:
+        """Detect crashed or hung worker process."""
+        if self._process is None:
+            return
+
+        # Process died unexpectedly
+        if not self._process.is_alive():
+            exit_code = self._process.exitcode
+            logger.error("Worker process died (exitcode=%s)", exit_code)
+            self._handle_crash(f"Worker process exited with code {exit_code}")
+            return
+
+        # Worker alive but hasn't responded for too long (hung during inference)
+        if self._busy:
+            elapsed = time.monotonic() - self._last_result_time
+            if elapsed > INFERENCE_WORKER_TIMEOUT_S:
+                logger.error(
+                    "Worker timeout: no response for %.1f s — restarting", elapsed
+                )
+                self._process.terminate()
+                self._process.join(timeout=2.0)
+                self._handle_crash("Worker timed out (hung during inference)")
+
+    def _handle_crash(self, reason: str) -> None:
+        """Decide whether to auto-restart or give up."""
+        self._poll_timer.stop()
+        self._watchdog_timer.stop()
+        self._process = None
+        self._busy = False
+
+        if self._restart_count < INFERENCE_MAX_RESTARTS:
+            self._restart_count += 1
+            logger.warning(
+                "Auto-restarting worker (attempt %d/%d): %s",
+                self._restart_count, INFERENCE_MAX_RESTARTS, reason,
+            )
+            self._start_worker()
+        else:
+            msg = (
+                f"Inference worker failed after {INFERENCE_MAX_RESTARTS} restarts. "
+                f"Last error: {reason}"
+            )
+            logger.error(msg)
+            self.inference_error.emit(msg)

app/logging_setup.py

@@ -0,0 +1,118 @@
+"""Logging initialisation — file + console handlers with session isolation."""
+
+from __future__ import annotations
+
+import logging
+import platform
+import sys
+from pathlib import Path
+
+from app.config import APP_NAME, APP_VERSION, MAX_LOG_FILES
+
+_LOG_FORMAT = "%(asctime)s.%(msecs)03d [%(levelname)-7s] %(name)s: %(message)s"
+_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+_console_handler: logging.StreamHandler | None = None
+
+
+def setup_logging(log_dir: Path, session_id: str) -> Path:
+    """
+    Configure the root logger for a new session.
+
+    Creates:
+        <log_dir>/duck-preview_<session_id>.log  — DEBUG level, all messages
+        console StreamHandler                     — WARNING by default
+
+    Prunes oldest log files when count exceeds MAX_LOG_FILES.
+
+    Args:
+        log_dir:    Directory where log files are stored.
+        session_id: Timestamp string used as filename suffix (e.g. "2026-05-12_14-30-00").
+
+    Returns:
+        Path to the created log file.
+    """
+    global _console_handler
+
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_path = log_dir / f"duck-preview_{session_id}.log"
+
+    root = logging.getLogger()
+    root.setLevel(logging.DEBUG)  # handlers filter individually
+
+    formatter = logging.Formatter(_LOG_FORMAT, datefmt=_DATE_FORMAT)
+
+    # --- File handler — always DEBUG ---
+    file_handler = logging.FileHandler(log_path, encoding="utf-8")
+    file_handler.setLevel(logging.DEBUG)
+    file_handler.setFormatter(formatter)
+    root.addHandler(file_handler)
+
+    # --- Console handler — WARNING by default, toggled by Debug menu ---
+    _console_handler = logging.StreamHandler(sys.stdout)
+    _console_handler.setLevel(logging.WARNING)
+    _console_handler.setFormatter(formatter)
+    root.addHandler(_console_handler)
+
+    # Write session header to file
+    _write_session_header(log_path, session_id)
+
+    # Prune old log files
+    _prune_old_logs(log_dir, log_path)
+
+    return log_path
+
+
+def set_console_level(debug: bool) -> None:
+    """Toggle console handler between DEBUG and WARNING (called from Debug menu)."""
+    if _console_handler is not None:
+        _console_handler.setLevel(logging.DEBUG if debug else logging.WARNING)
+
+
+def _write_session_header(log_path: Path, session_id: str) -> None:
+    """Write a human-readable header block at the top of the log file."""
+    try:
+        import PySide6
+        pyside_version = PySide6.__version__
+    except Exception:
+        pyside_version = "unknown"
+
+    try:
+        import psutil
+        mem = psutil.virtual_memory()
+        cpu_count = psutil.cpu_count(logical=True)
+        mem_total_gb = mem.total / (1024 ** 3)
+        hw_info = f"{cpu_count} logical CPUs, {mem_total_gb:.1f} GB RAM"
+    except Exception:
+        hw_info = "unknown"
+
+    lines = [
+        "=" * 72,
+        f"  {APP_NAME} {APP_VERSION}",
+        f"  Session: {session_id}",
+        "=" * 72,
+        f"  Platform : {platform.platform()}",
+        f"  Python   : {sys.version.split()[0]}",
+        f"  PySide6  : {pyside_version}",
+        f"  Hardware : {hw_info}",
+        f"  Log file : {log_path.resolve()}",
+        "=" * 72,
+        "",
+    ]
+    with log_path.open("w", encoding="utf-8") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+def _prune_old_logs(log_dir: Path, current: Path) -> None:
+    """Delete oldest .log files if total count exceeds MAX_LOG_FILES."""
+    log_files = sorted(
+        [p for p in log_dir.glob("duck-preview_*.log") if p != current],
+        key=lambda p: p.stat().st_mtime,
+    )
+    excess = len(log_files) - (MAX_LOG_FILES - 1)
+    for path in log_files[:excess]:
+        try:
+            path.unlink()
+            logging.getLogger(__name__).debug("Pruned old log: %s", path.name)
+        except OSError:
+            pass

app/main.py

@@ -0,0 +1,41 @@
+"""Application entry point."""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QApplication
+
+from app.config import APP_NAME, LOG_DIR
+from app.logging_setup import setup_logging
+
+
+def main() -> None:
+    session_id = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    log_path = setup_logging(LOG_DIR, session_id)
+
+    # Import after logging is ready so module-level loggers work correctly
+    import logging  # noqa: PLC0415
+
+    from app.ui.main_window import MainWindow  # noqa: PLC0415
+
+    logger = logging.getLogger(__name__)
+    logger.info("Application starting (session: %s)", session_id)
+
+    app = QApplication(sys.argv)
+    app.setApplicationName(APP_NAME)
+    app.setHighDpiScaleFactorRoundingPolicy(
+        Qt.HighDpiScaleFactorRoundingPolicy.PassThrough
+    )
+
+    window = MainWindow(log_path=log_path)
+    window.show()
+
+    logger.info("Application shutting down")
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()

app/overlay/overlay_layer.py

@@ -0,0 +1,54 @@
+"""IOverlayLayer — interface for pluggable overlay layers drawn on CameraView."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from PySide6.QtCore import QRect
+from PySide6.QtGui import QPainter
+
+
+class IOverlayLayer(ABC):
+    """
+    Interface for a single overlay layer drawn over the camera frame.
+
+    Each layer receives the active QPainter and the video rect (the letterboxed
+    area where the camera image was drawn) so it can position elements relative
+    to the actual video content if needed.
+
+    To add a new overlay (e.g. YOLO bboxes):
+        1. Subclass IOverlayLayer.
+        2. Implement paint().
+        3. Register with CameraView.add_overlay_layer().
+
+    No Qt subclassing is required — layers are plain Python objects.
+    """
+
+    @property
+    def name(self) -> str:
+        """Human-readable identifier used in menus / debug output."""
+        return type(self).__name__
+
+    @property
+    def visible(self) -> bool:
+        """Whether this layer should be drawn."""
+        return self._visible
+
+    @visible.setter
+    def visible(self, value: bool) -> None:
+        self._visible = value
+
+    def __init__(self) -> None:
+        self._visible: bool = True
+
+    @abstractmethod
+    def paint(self, painter: QPainter, video_rect: QRect) -> None:
+        """
+        Draw this layer.
+
+        Args:
+            painter:    Active QPainter on the CameraView widget.
+                        Caller saves/restores painter state around each layer.
+            video_rect: The QRect where the camera image was drawn (letterboxed).
+                        Use this to position overlays relative to the video image.
+        """

app/overlay/telemetry_overlay.py

@@ -0,0 +1,117 @@
+"""TelemetryOverlay — draws the performance metrics box on the camera view."""
+
+from __future__ import annotations
+
+from PySide6.QtCore import QRect, Qt, Slot
+from PySide6.QtGui import QColor, QFont, QPainter, QPen
+
+from app.config import (
+    OVERLAY_BG_COLOR,
+    OVERLAY_FONT_SIZE,
+    OVERLAY_MARGIN,
+    OVERLAY_PADDING,
+    OVERLAY_TEXT_COLOR,
+)
+from app.overlay.overlay_layer import IOverlayLayer
+from app.telemetry.telemetry_collector import TelemetrySnapshot
+
+
+class TelemetryOverlay(IOverlayLayer):
+    """
+    Renders a semi-transparent metrics box in the top-left corner.
+
+    Usage:
+        overlay = TelemetryOverlay()
+        camera_view.add_overlay_layer(overlay)
+        telemetry_collector.metrics_updated.connect(overlay.on_metrics_updated)
+
+    Display format:
+        FPS req   60.0          ← what was requested from camera
+        FPS got   30.2          ← what camera actually delivered
+        Frame     33.1 ms
+        Drop         0
+        CPU sys   14.8 %        ← normalised by cpu_count (matches Task Manager)
+        CPU core 118.4 %        ← per single core (can exceed 100%)
+        Mem        68 MB
+        Inf.dev  mps            ← inference device (only when model loaded)
+        Inf.time  87 ms         ← rolling average of model() call time
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._snapshot: TelemetrySnapshot | None = None
+
+        self._font = QFont("Monospace")
+        self._font.setStyleHint(QFont.StyleHint.TypeWriter)
+        self._font.setPointSize(OVERLAY_FONT_SIZE)
+        self._font.setBold(False)
+
+    @Slot(object)
+    def on_metrics_updated(self, snapshot: TelemetrySnapshot) -> None:
+        """Receive a new snapshot from TelemetryCollector."""
+        self._snapshot = snapshot
+
+    # ------------------------------------------------------------------
+    # IOverlayLayer
+    # ------------------------------------------------------------------
+
+    def paint(self, painter: QPainter, video_rect: QRect) -> None:
+        if self._snapshot is None:
+            return
+
+        lines = self._format_lines(self._snapshot)
+        if not lines:
+            return
+
+        painter.setFont(self._font)
+        fm = painter.fontMetrics()
+        line_height = fm.height()
+        max_width = max(fm.horizontalAdvance(line) for line in lines)
+
+        box_w = max_width + OVERLAY_PADDING * 2
+        box_h = line_height * len(lines) + OVERLAY_PADDING * 2
+
+        x = video_rect.left() + OVERLAY_MARGIN
+        y = video_rect.top() + OVERLAY_MARGIN
+
+        # Background
+        painter.setBrush(QColor(*OVERLAY_BG_COLOR))
+        painter.setPen(Qt.PenStyle.NoPen)
+        painter.drawRoundedRect(QRect(x, y, box_w, box_h), 6, 6)
+
+        # Text
+        painter.setPen(QPen(QColor(*OVERLAY_TEXT_COLOR)))
+        text_x = x + OVERLAY_PADDING
+        text_y = y + OVERLAY_PADDING + fm.ascent()
+        for line in lines:
+            painter.drawText(text_x, text_y, line)
+            text_y += line_height
+
+    # ------------------------------------------------------------------
+    # Private
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _format_lines(snap: TelemetrySnapshot) -> list[str]:
+        lines: list[str] = []
+
+        # FPS — show target if known, then actual
+        if snap.target_fps is not None:
+            lines.append(f"FPS req  {snap.target_fps:>6.1f}")
+        lines.append(f"FPS got  {snap.fps:>6.1f}")
+
+        lines.append(f"Frame    {snap.frame_time_ms:>6.1f} ms")
+        lines.append(f"Drop     {snap.dropped_frames:>6d}")
+        lines.append(f"CPU sys  {snap.cpu_percent_sys:>5.1f} %")
+        lines.append(f"CPU core {snap.cpu_percent_core:>5.1f} %")
+
+        if snap.memory_mb is not None:
+            lines.append(f"Mem      {snap.memory_mb:>5.0f} MB")
+
+        if snap.inference_device is not None:
+            lines.append(f"Inf.dev  {snap.inference_device:>6s}")
+
+        if snap.inference_time_ms is not None:
+            lines.append(f"Inf.time {snap.inference_time_ms:>5.0f} ms")
+
+        return lines

app/pipeline/frame_dispatcher.py

@@ -0,0 +1,111 @@
+"""Frame Dispatcher — distributes QVideoFrames to registered subscribers."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from PySide6.QtCore import QObject, Slot
+from PySide6.QtMultimedia import QVideoFrame
+
+logger = logging.getLogger(__name__)
+
+FrameCallback = Callable[[QVideoFrame], None]
+
+
+@dataclass
+class _Subscriber:
+    callback: FrameCallback
+    drop_if_busy: bool = True
+    _busy: bool = field(default=False, init=False, repr=False)
+
+
+class FrameDispatcher(QObject):
+    """
+    Receives frames from CameraService and fans them out to all subscribers.
+
+    Each subscriber is a callable (QVideoFrame) -> None.
+
+    Subscribers that set drop_if_busy=True will skip a frame if they are still
+    processing the previous one (non-blocking). Subscribers with drop_if_busy=False
+    always receive every frame.
+
+    All dispatch happens in the GUI thread (Qt signal/slot), so subscribers
+    must NOT perform heavy work directly — they should queue to a worker thread
+    if processing is needed.
+    """
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._subscribers: list[_Subscriber] = []
+        self._frame_count: int = 0
+        self._last_dispatch_time: float = 0.0
+
+    # ------------------------------------------------------------------
+    # Subscription API
+    # ------------------------------------------------------------------
+
+    def subscribe(self, callback: FrameCallback, *, drop_if_busy: bool = True) -> None:
+        """Register a frame callback.
+
+        Args:
+            callback:      Callable that receives QVideoFrame.
+            drop_if_busy:  When True, frame is skipped if subscriber is still
+                           marked busy from last call (default True).
+        """
+        for sub in self._subscribers:
+            if sub.callback is callback:
+                logger.warning("Subscriber %r already registered", callback)
+                return
+        self._subscribers.append(_Subscriber(callback=callback, drop_if_busy=drop_if_busy))
+        logger.debug("Subscriber added: %r (drop_if_busy=%s)", callback, drop_if_busy)
+
+    def unsubscribe(self, callback: FrameCallback) -> None:
+        """Remove a previously registered callback."""
+        before = len(self._subscribers)
+        self._subscribers = [s for s in self._subscribers if s.callback is not callback]
+        if len(self._subscribers) < before:
+            logger.debug("Subscriber removed: %r", callback)
+        else:
+            logger.debug("Subscriber not found for removal: %r", callback)
+
+    def subscriber_count(self) -> int:
+        return len(self._subscribers)
+
+    # ------------------------------------------------------------------
+    # Frame intake — connect CameraService.frame_ready to this slot
+    # ------------------------------------------------------------------
+
+    @Slot(QVideoFrame)
+    def dispatch(self, frame: QVideoFrame) -> None:
+        """Distribute the frame to all registered subscribers."""
+        self._frame_count += 1
+        now = time.perf_counter()
+        self._last_dispatch_time = now
+
+        for sub in self._subscribers:
+            if sub.drop_if_busy and sub._busy:
+                logger.debug("Dropping frame for busy subscriber %r", sub.callback)
+                continue
+            sub._busy = True
+            try:
+                sub.callback(frame)
+            except Exception:
+                logger.exception("Error in frame subscriber %r", sub.callback)
+            finally:
+                sub._busy = False
+
+    # ------------------------------------------------------------------
+    # Stats
+    # ------------------------------------------------------------------
+
+    @property
+    def frame_count(self) -> int:
+        return self._frame_count
+
+    @property
+    def last_dispatch_time(self) -> float:
+        """perf_counter timestamp of the last dispatched frame."""
+        return self._last_dispatch_time

app/telemetry/csv_logger.py

@@ -0,0 +1,104 @@
+"""CsvTelemetryLogger — writes telemetry snapshots to a CSV file with throttling.
+
+Design decisions:
+- Does NOT use the logging module — writes directly via csv.writer so the file
+  is readable independently of the text log level.
+- Flushes after every row so the file is intact even on crash or force-quit.
+- Throttle: only one row per TELEMETRY_CSV_INTERVAL_S seconds, even if
+  metrics_updated fires every 500 ms.  This keeps the file manageable for
+  long sessions (8 h @ 5 s interval = 5 760 rows).
+"""
+
+from __future__ import annotations
+
+import csv
+import time
+from datetime import datetime
+from pathlib import Path
+
+from app.config import TELEMETRY_CSV_INTERVAL_S
+from app.telemetry.telemetry_collector import TelemetrySnapshot
+
+_CSV_HEADER = [
+    "timestamp",
+    "fps_got",
+    "fps_req",
+    "frame_time_ms",
+    "dropped_frames",
+    "cpu_sys_pct",
+    "cpu_core_pct",
+    "mem_mb",
+]
+
+
+class CsvTelemetryLogger:
+    """
+    Receives TelemetrySnapshot objects and writes throttled rows to a CSV file.
+
+    Usage:
+        logger = CsvTelemetryLogger(path)
+        telemetry_collector.metrics_updated.connect(logger.on_metrics_updated)
+        # call logger.close() on application exit
+    """
+
+    def __init__(
+        self,
+        path: Path,
+        interval_s: float = TELEMETRY_CSV_INTERVAL_S,
+    ) -> None:
+        self._interval_s = interval_s
+        self._last_write_time: float = 0.0
+        self._rows_written: int = 0
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._file = path.open("w", newline="", encoding="utf-8")
+        self._writer = csv.writer(self._file)
+        self._writer.writerow(_CSV_HEADER)
+        self._file.flush()
+
+    # ------------------------------------------------------------------
+    # Slot — connect to TelemetryCollector.metrics_updated
+    # ------------------------------------------------------------------
+
+    def on_metrics_updated(self, snapshot: TelemetrySnapshot) -> None:
+        """Write a row if the throttle interval has elapsed."""
+        now = time.monotonic()
+        if now - self._last_write_time < self._interval_s:
+            return
+        self._last_write_time = now
+        self._write_row(snapshot)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Flush and close the CSV file. Call on application shutdown."""
+        try:
+            self._file.flush()
+            self._file.close()
+        except OSError:
+            pass
+
+    @property
+    def rows_written(self) -> int:
+        return self._rows_written
+
+    # ------------------------------------------------------------------
+    # Private
+    # ------------------------------------------------------------------
+
+    def _write_row(self, snap: TelemetrySnapshot) -> None:
+        ts = datetime.now().strftime("%H:%M:%S.%f")[:-3]  # HH:MM:SS.mmm
+        self._writer.writerow([
+            ts,
+            f"{snap.fps:.1f}",
+            f"{snap.target_fps:.1f}" if snap.target_fps is not None else "",
+            f"{snap.frame_time_ms:.2f}",
+            snap.dropped_frames,
+            f"{snap.cpu_percent_sys:.1f}",
+            f"{snap.cpu_percent_core:.1f}",
+            f"{snap.memory_mb:.1f}" if snap.memory_mb is not None else "",
+        ])
+        self._file.flush()
+        self._rows_written += 1

app/telemetry/telemetry_collector.py

@@ -0,0 +1,215 @@
+"""Telemetry Collector — measures video pipeline performance metrics."""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+from dataclasses import dataclass
+
+import psutil
+from PySide6.QtCore import QObject, QTimer, Signal
+from PySide6.QtMultimedia import QVideoFrame
+
+from app.config import TELEMETRY_UPDATE_INTERVAL_MS
+
+
+@dataclass
+class TelemetrySnapshot:
+    """Immutable snapshot of current performance metrics."""
+
+    fps: float                    # actual frames received in the last second
+    target_fps: float | None      # FPS requested from the camera (None = unknown)
+    frame_time_ms: float          # average inter-frame time in ms
+    dropped_frames: int           # cumulative dropped frames detected
+    cpu_percent_sys: float        # process CPU as % of total system capacity
+                                  # (divided by cpu_count) — matches Task Manager
+    cpu_percent_core: float       # process CPU per single core — can exceed 100%
+    memory_mb: float | None       # process private working set in MB
+    timestamp: float              # time.perf_counter() when snapshot was taken
+    # Inference fields — None when inference is disabled / model not loaded
+    inference_device: str | None = None   # e.g. "cpu", "mps"
+    inference_time_ms: float | None = None  # rolling average of model() call time
+
+
+class TelemetryCollector(QObject):
+    """
+    Frame subscriber that measures pipeline performance.
+
+    Connect to FrameDispatcher:
+        dispatcher.subscribe(collector.on_frame, drop_if_busy=False)
+
+    Receive target FPS updates from CameraService:
+        camera_service.format_changed.connect(collector.set_target_fps)
+
+    Listen to metrics updates:
+        collector.metrics_updated.connect(my_slot)
+    """
+
+    metrics_updated = Signal(object)  # emits TelemetrySnapshot
+
+    def __init__(
+        self,
+        update_interval_ms: int = TELEMETRY_UPDATE_INTERVAL_MS,
+        parent: QObject | None = None,
+    ) -> None:
+        super().__init__(parent)
+
+        self._update_interval_ms = update_interval_ms
+        self._target_fps: float | None = None
+
+        # frame timing ring-buffer (last 120 samples)
+        self._frame_times: deque[float] = deque(maxlen=120)
+        self._last_frame_time: float = 0.0
+        self._total_frames: int = 0
+        self._dropped_frames: int = 0
+
+        # FPS window — count frames in the last second
+        self._fps_window: deque[float] = deque()
+        self._fps_window_size_s: float = 1.0
+
+        # psutil — initialise baseline so first real reading is non-zero
+        self._process = psutil.Process()
+        self._process.cpu_percent()  # first call always returns 0.0; discard
+        self._cpu_count: int = max(psutil.cpu_count(logical=True) or 1, 1)
+
+        # Inference stats (updated externally via set_inference_stats)
+        self._inference_device: str | None = None
+        self._inference_time_ms: float | None = None
+
+        # periodic snapshot timer
+        self._timer = QTimer(self)
+        self._timer.setInterval(update_interval_ms)
+        self._timer.timeout.connect(self._emit_snapshot)
+        self._timer.start()
+
+        self._latest: TelemetrySnapshot = self._make_empty_snapshot()
+
+    # ------------------------------------------------------------------
+    # Configuration
+    # ------------------------------------------------------------------
+
+    def set_target_fps(self, fps: float | None) -> None:
+        """Record the FPS that was requested from the camera."""
+        self._target_fps = fps
+
+    def set_inference_stats(self, device: str, avg_ms: float) -> None:
+        """Update inference device and average inference time (called from MainWindow)."""
+        self._inference_device: str | None = device
+        self._inference_time_ms: float | None = avg_ms
+
+    def clear_inference_stats(self) -> None:
+        """Clear inference stats when inference is disabled."""
+        self._inference_device = None
+        self._inference_time_ms = None
+
+    # ------------------------------------------------------------------
+    # Frame subscriber callback
+    # ------------------------------------------------------------------
+
+    def on_frame(self, frame: QVideoFrame) -> None:
+        """Called by FrameDispatcher for every frame. Must be fast."""
+        now = time.perf_counter()
+
+        if self._last_frame_time > 0:
+            delta = now - self._last_frame_time
+            self._frame_times.append(delta)
+
+            # drop detection: gap > 2.5× rolling average
+            if len(self._frame_times) >= 5:
+                avg = sum(self._frame_times) / len(self._frame_times)
+                if delta > avg * 2.5:
+                    self._dropped_frames += 1
+
+        self._last_frame_time = now
+        self._total_frames += 1
+
+        self._fps_window.append(now)
+        cutoff = now - self._fps_window_size_s
+        while self._fps_window and self._fps_window[0] < cutoff:
+            self._fps_window.popleft()
+
+    # ------------------------------------------------------------------
+    # Snapshot
+    # ------------------------------------------------------------------
+
+    def latest_snapshot(self) -> TelemetrySnapshot:
+        return self._latest
+
+    def reset_counters(self) -> None:
+        """Reset cumulative counters (e.g. after camera switch)."""
+        self._frame_times.clear()
+        self._fps_window.clear()
+        self._last_frame_time = 0.0
+        self._total_frames = 0
+        self._dropped_frames = 0
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _emit_snapshot(self) -> None:
+        snapshot = self._compute_snapshot()
+        self._latest = snapshot
+        self.metrics_updated.emit(snapshot)
+
+    def _compute_snapshot(self) -> TelemetrySnapshot:
+        now = time.perf_counter()
+
+        # FPS — prune stale entries before counting
+        cutoff = now - self._fps_window_size_s
+        while self._fps_window and self._fps_window[0] < cutoff:
+            self._fps_window.popleft()
+        fps = float(len(self._fps_window))
+
+        # average frame time
+        avg_frame_time_ms = (
+            (sum(self._frame_times) / len(self._frame_times)) * 1000.0
+            if self._frame_times
+            else 0.0
+        )
+
+        # CPU — per-core reading, then derive system-normalised value
+        try:
+            cpu_core = self._process.cpu_percent()
+        except Exception:
+            cpu_core = 0.0
+        cpu_sys = cpu_core / self._cpu_count
+
+        # Memory — private working set (Windows) or RSS (macOS/Linux)
+        try:
+            mem_info = self._process.memory_info()
+            mem_bytes = getattr(mem_info, "wset", None) or mem_info.rss
+            mem_mb: float | None = mem_bytes / (1024 * 1024)
+        except Exception:
+            mem_mb = None
+
+        return TelemetrySnapshot(
+            fps=round(fps, 1),
+            target_fps=self._target_fps,
+            frame_time_ms=round(avg_frame_time_ms, 2),
+            dropped_frames=self._dropped_frames,
+            cpu_percent_sys=round(cpu_sys, 1),
+            cpu_percent_core=round(cpu_core, 1),
+            memory_mb=round(mem_mb, 1) if mem_mb is not None else None,
+            timestamp=now,
+            inference_device=self._inference_device,
+            inference_time_ms=(
+                round(self._inference_time_ms, 1)
+                if self._inference_time_ms is not None
+                else None
+            ),
+        )
+
+    def _make_empty_snapshot(self) -> TelemetrySnapshot:
+        return TelemetrySnapshot(
+            fps=0.0,
+            target_fps=self._target_fps,
+            frame_time_ms=0.0,
+            dropped_frames=0,
+            cpu_percent_sys=0.0,
+            cpu_percent_core=0.0,
+            memory_mb=None,
+            timestamp=time.perf_counter(),
+            inference_device=None,
+            inference_time_ms=None,
+        )

app/ui/camera_settings_dialog.py

@@ -0,0 +1,310 @@
+"""Camera Settings dialog — sliders for UVC controls + Qt WhiteBalance/Exposure."""
+
+from __future__ import annotations
+
+import logging
+
+from PySide6.QtCore import Qt
+from PySide6.QtMultimedia import QCamera
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QComboBox,
+    QDialog,
+    QDialogButtonBox,
+    QDoubleSpinBox,
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QScrollArea,
+    QSlider,
+    QSpinBox,
+    QVBoxLayout,
+    QWidget,
+)
+
+from app.camera.uvc.base import UvcControllerBase, UvcParam
+
+logger = logging.getLogger(__name__)
+
+# Human-readable labels for each UVC parameter
+_PARAM_LABELS: dict[UvcParam, str] = {
+    UvcParam.BRIGHTNESS:             "Brightness",
+    UvcParam.CONTRAST:               "Contrast",
+    UvcParam.SATURATION:             "Saturation",
+    UvcParam.HUE:                    "Hue",
+    UvcParam.SHARPNESS:              "Sharpness",
+    UvcParam.GAMMA:                  "Gamma",
+    UvcParam.WHITE_BALANCE:          "White Balance (K)",
+    UvcParam.BACKLIGHT_COMPENSATION: "Backlight Compensation",
+    UvcParam.EXPOSURE:               "Exposure Time",
+}
+
+# Qt WhiteBalance modes shown in the combo
+_WB_MODES: list[tuple[str, QCamera.WhiteBalanceMode]] = [
+    ("Auto",        QCamera.WhiteBalanceMode.WhiteBalanceAuto),
+    ("Sunlight",    QCamera.WhiteBalanceMode.WhiteBalanceSunlight),
+    ("Cloudy",      QCamera.WhiteBalanceMode.WhiteBalanceCloudy),
+    ("Shade",       QCamera.WhiteBalanceMode.WhiteBalanceShade),
+    ("Tungsten",    QCamera.WhiteBalanceMode.WhiteBalanceTungsten),
+    ("Fluorescent", QCamera.WhiteBalanceMode.WhiteBalanceFluorescent),
+    ("Flash",       QCamera.WhiteBalanceMode.WhiteBalanceFlash),
+    ("Sunset",      QCamera.WhiteBalanceMode.WhiteBalanceSunset),
+    ("Manual (K)",  QCamera.WhiteBalanceMode.WhiteBalanceManual),
+]
+
+_EXPOSURE_MODES: list[tuple[str, QCamera.ExposureMode]] = [
+    ("Auto",   QCamera.ExposureMode.ExposureAuto),
+    ("Manual", QCamera.ExposureMode.ExposureManual),
+]
+
+
+class CameraSettingsDialog(QDialog):
+    """
+    Modal dialog for camera image controls.
+
+    Sections:
+      • Qt controls — WhiteBalance mode + colour temperature, Exposure mode + time
+      • UVC controls — sliders for Brightness, Contrast, Saturation, Hue,
+                       Sharpness, Gamma, White Balance (manual K), Backlight,
+                       Exposure (if UVC controller is open)
+
+    Changes are applied live to the camera.
+    """
+
+    def __init__(
+        self,
+        camera: QCamera,
+        uvc: UvcControllerBase,
+        parent: QWidget | None = None,
+    ) -> None:
+        super().__init__(parent)
+        self.setWindowTitle("Camera Settings")
+        self.setMinimumWidth(440)
+
+        self._camera = camera
+        self._uvc = uvc
+
+        outer = QVBoxLayout(self)
+
+        scroll = QScrollArea()
+        scroll.setWidgetResizable(True)
+        outer.addWidget(scroll)
+
+        content = QWidget()
+        scroll.setWidget(content)
+        layout = QVBoxLayout(content)
+        layout.setAlignment(Qt.AlignmentFlag.AlignTop)
+
+        layout.addWidget(self._build_qt_group())
+
+        uvc_group = self._build_uvc_group()
+        if uvc_group is not None:
+            layout.addWidget(uvc_group)
+
+        buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Close)
+        buttons.rejected.connect(self.accept)
+        outer.addWidget(buttons)
+
+    # ------------------------------------------------------------------
+    # Qt controls section
+    # ------------------------------------------------------------------
+
+    def _build_qt_group(self) -> QGroupBox:
+        group = QGroupBox("Qt Camera Controls")
+        form = QFormLayout(group)
+
+        # White Balance mode
+        self._wb_combo = QComboBox()
+        for label, mode in _WB_MODES:
+            self._wb_combo.addItem(label, mode)
+
+        current_wb = self._camera.whiteBalanceMode()
+        for i, (_, mode) in enumerate(_WB_MODES):
+            if mode == current_wb:
+                self._wb_combo.setCurrentIndex(i)
+                break
+
+        self._wb_combo.currentIndexChanged.connect(self._on_wb_mode_changed)
+        form.addRow("White Balance:", self._wb_combo)
+
+        # Colour temperature (manual only)
+        self._temp_label = QLabel("Colour Temp (K):")
+        self._temp_spin = QSpinBox()
+        self._temp_spin.setRange(2000, 10000)
+        self._temp_spin.setSingleStep(100)
+        current_temp = self._camera.colorTemperature()
+        self._temp_spin.setValue(current_temp if current_temp >= 2000 else 5500)
+        self._temp_spin.valueChanged.connect(self._on_color_temp_changed)
+        form.addRow(self._temp_label, self._temp_spin)
+        self._update_temp_visibility()
+
+        form.addRow(QLabel(""))  # spacer
+
+        # Exposure mode
+        self._exp_combo = QComboBox()
+        for label, mode in _EXPOSURE_MODES:
+            self._exp_combo.addItem(label, mode)
+
+        current_exp = self._camera.exposureMode()
+        for i, (_, mode) in enumerate(_EXPOSURE_MODES):
+            if mode == current_exp:
+                self._exp_combo.setCurrentIndex(i)
+                break
+
+        self._exp_combo.currentIndexChanged.connect(self._on_exp_mode_changed)
+        form.addRow("Exposure Mode:", self._exp_combo)
+
+        # Manual exposure time
+        self._exp_label = QLabel("Exposure Time (s):")
+        self._exp_spin = QDoubleSpinBox()
+        exp_min = self._camera.minimumExposureTime()
+        exp_max = self._camera.maximumExposureTime()
+        self._exp_spin.setRange(
+            exp_min if exp_min > 0 else 1e-6,
+            exp_max if exp_max > 0 else 1.0,
+        )
+        self._exp_spin.setDecimals(6)
+        self._exp_spin.setSingleStep(0.001)
+        manual_t = self._camera.manualExposureTime()
+        self._exp_spin.setValue(manual_t if manual_t > 0 else 0.033)
+        self._exp_spin.valueChanged.connect(self._on_exp_time_changed)
+        form.addRow(self._exp_label, self._exp_spin)
+        self._update_exp_visibility()
+
+        return group
+
+    # ------------------------------------------------------------------
+    # UVC controls section
+    # ------------------------------------------------------------------
+
+    def _build_uvc_group(self) -> QGroupBox | None:
+        params = self._uvc.get_all_params()
+        supported = [p for p in params if p.supported]
+
+        group = QGroupBox("UVC Camera Controls")
+        form = QFormLayout(group)
+
+        if not supported:
+            note = QLabel(
+                "UVC controls not available.\n"
+                "Install duvc-ctl (Windows) or pyuvc (macOS) to enable."
+            )
+            note.setEnabled(False)
+            form.addRow(note)
+            return group
+
+        self._uvc_sliders: dict[UvcParam, QSlider] = {}
+        self._uvc_spins: dict[UvcParam, QSpinBox] = {}
+        self._uvc_auto_boxes: dict[UvcParam, QCheckBox] = {}
+
+        for info in params:
+            label = _PARAM_LABELS.get(info.param, info.param.name.title())
+
+            if not info.supported:
+                lbl = QLabel("Not supported")
+                lbl.setEnabled(False)
+                form.addRow(f"{label}:", lbl)
+                continue
+
+            row_widget = QWidget()
+            row_layout = QHBoxLayout(row_widget)
+            row_layout.setContentsMargins(0, 0, 0, 0)
+
+            slider = QSlider(Qt.Orientation.Horizontal)
+            slider.setRange(info.minimum, info.maximum)
+            slider.setValue(info.current)
+            slider.setSingleStep(max(1, info.step))
+
+            spin = QSpinBox()
+            spin.setRange(info.minimum, info.maximum)
+            spin.setValue(info.current)
+            spin.setFixedWidth(75)
+
+            # Keep slider ↔ spin in sync
+            slider.valueChanged.connect(spin.setValue)
+            spin.valueChanged.connect(slider.setValue)
+            slider.valueChanged.connect(
+                lambda v, p=info.param: self._on_uvc_value(p, v)
+            )
+
+            row_layout.addWidget(slider)
+            row_layout.addWidget(spin)
+
+            if info.auto_supported:
+                auto_box = QCheckBox("Auto")
+                auto_box.setChecked(info.auto_enabled)
+                auto_box.toggled.connect(
+                    lambda checked, p=info.param: self._on_uvc_auto(p, checked)
+                )
+                row_layout.addWidget(auto_box)
+                self._uvc_auto_boxes[info.param] = auto_box
+                # Init enabled state
+                slider.setEnabled(not info.auto_enabled)
+                spin.setEnabled(not info.auto_enabled)
+
+            self._uvc_sliders[info.param] = slider
+            self._uvc_spins[info.param] = spin
+            form.addRow(f"{label}:", row_widget)
+
+        return group
+
+    # ------------------------------------------------------------------
+    # Qt control slots
+    # ------------------------------------------------------------------
+
+    def _on_wb_mode_changed(self, index: int) -> None:
+        mode: QCamera.WhiteBalanceMode = self._wb_combo.itemData(index)
+        if self._camera.isWhiteBalanceModeSupported(mode):
+            self._camera.setWhiteBalanceMode(mode)
+            logger.debug("WB mode: %s", mode)
+        else:
+            logger.debug("WB mode %s not supported by this camera", mode)
+        self._update_temp_visibility()
+
+    def _on_color_temp_changed(self, value: int) -> None:
+        self._camera.setColorTemperature(value)
+        logger.debug("Colour temp: %d K", value)
+
+    def _on_exp_mode_changed(self, index: int) -> None:
+        mode: QCamera.ExposureMode = self._exp_combo.itemData(index)
+        if self._camera.isExposureModeSupported(mode):
+            self._camera.setExposureMode(mode)
+            logger.debug("Exposure mode: %s", mode)
+        self._update_exp_visibility()
+
+    def _on_exp_time_changed(self, value: float) -> None:
+        self._camera.setManualExposureTime(value)
+        logger.debug("Exposure time: %.6f s", value)
+
+    def _update_temp_visibility(self) -> None:
+        manual = (
+            self._wb_combo.currentData()
+            == QCamera.WhiteBalanceMode.WhiteBalanceManual
+        )
+        self._temp_label.setVisible(manual)
+        self._temp_spin.setVisible(manual)
+
+    def _update_exp_visibility(self) -> None:
+        manual = (
+            self._exp_combo.currentData()
+            == QCamera.ExposureMode.ExposureManual
+        )
+        self._exp_label.setVisible(manual)
+        self._exp_spin.setVisible(manual)
+
+    # ------------------------------------------------------------------
+    # UVC control slots
+    # ------------------------------------------------------------------
+
+    def _on_uvc_value(self, param: UvcParam, value: int) -> None:
+        self._uvc.set_value(param, value)
+
+    def _on_uvc_auto(self, param: UvcParam, enabled: bool) -> None:
+        self._uvc.set_auto(param, enabled)
+        slider = self._uvc_sliders.get(param)
+        spin = self._uvc_spins.get(param)
+        if slider:
+            slider.setEnabled(not enabled)
+        if spin:
+            spin.setEnabled(not enabled)

app/ui/camera_view.py

@@ -0,0 +1,144 @@
+"""CameraView — QWidget that renders camera frames and composites overlay layers.
+
+Responsibilities:
+    - Receive QVideoFrame, convert to QImage, schedule repaint.
+    - In paintEvent: draw the frame (letterboxed) then call paint() on each
+      registered IOverlayLayer in order.
+    - Know nothing about what specific overlays draw — that is entirely up to
+      each IOverlayLayer implementation.
+
+Adding a new overlay (e.g. YOLO bboxes):
+    layer = YoloBboxOverlay()
+    camera_view.add_overlay_layer(layer)
+    yolo_processor.results_ready.connect(layer.on_results)
+
+No modification to CameraView is needed.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from PySide6.QtCore import QRect, Qt, Slot
+from PySide6.QtGui import QImage, QPainter
+from PySide6.QtMultimedia import QVideoFrame
+from PySide6.QtWidgets import QWidget
+
+from app.overlay.overlay_layer import IOverlayLayer
+
+logger = logging.getLogger(__name__)
+
+
+class CameraView(QWidget):
+    """
+    Camera preview widget.
+
+    Frame pipeline:
+        CameraService.frame_ready(QVideoFrame)
+            → CameraView.on_frame()     — convert to QImage, schedule update()
+            → paintEvent()              — draw image + all overlay layers
+    """
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        self.setStyleSheet("background: black;")
+
+        self._current_image: QImage | None = None
+        self._video_rect: QRect = QRect()
+        self._overlay_layers: list[IOverlayLayer] = []
+
+    # ------------------------------------------------------------------
+    # Overlay layer registry
+    # ------------------------------------------------------------------
+
+    def add_overlay_layer(self, layer: IOverlayLayer) -> None:
+        """Register an overlay layer. Layers are painted in registration order."""
+        if layer not in self._overlay_layers:
+            self._overlay_layers.append(layer)
+            logger.debug("Overlay layer added: %s", layer.name)
+
+    def remove_overlay_layer(self, layer: IOverlayLayer) -> None:
+        """Unregister an overlay layer."""
+        try:
+            self._overlay_layers.remove(layer)
+            logger.debug("Overlay layer removed: %s", layer.name)
+        except ValueError:
+            pass
+
+    def set_all_overlays_visible(self, visible: bool) -> None:
+        """Show or hide all registered overlay layers at once."""
+        for layer in self._overlay_layers:
+            layer.visible = visible
+        self.update()
+
+    # ------------------------------------------------------------------
+    # Frame input
+    # ------------------------------------------------------------------
+
+    @Slot(QVideoFrame)
+    def on_frame(self, frame: QVideoFrame) -> None:
+        """Receive a camera frame, convert to QImage, schedule repaint."""
+        if not frame.isValid():
+            return
+
+        image = frame.toImage()
+        if image.isNull():
+            return
+
+        # Convert to Format_RGB32 — QPainter's fastest path on all platforms
+        if image.format() != QImage.Format.Format_RGB32:
+            image = image.convertToFormat(QImage.Format.Format_RGB32)
+
+        self._current_image = image
+        self.update()
+
+    # ------------------------------------------------------------------
+    # Qt paint
+    # ------------------------------------------------------------------
+
+    def paintEvent(self, event) -> None:  # noqa: N802
+        painter = QPainter(self)
+
+        # 1. Background
+        painter.fillRect(self.rect(), Qt.GlobalColor.black)
+
+        # 2. Camera frame — letterboxed
+        if self._current_image is not None:
+            img = self._current_image
+            self._video_rect = _letterbox_rect(
+                img.width(), img.height(), self.width(), self.height()
+            )
+            painter.drawImage(self._video_rect, img)
+        else:
+            self._video_rect = self.rect()
+
+        # 3. Overlay layers — each gets a clean painter state
+        for layer in self._overlay_layers:
+            if not layer.visible:
+                continue
+            painter.save()
+            try:
+                layer.paint(painter, self._video_rect)
+            except Exception:
+                logger.exception("Error painting overlay layer %s", layer.name)
+            finally:
+                painter.restore()
+
+        painter.end()
+
+
+# ------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------
+
+def _letterbox_rect(img_w: int, img_h: int, widget_w: int, widget_h: int) -> QRect:
+    """Return the largest rect that fits the image while preserving aspect ratio."""
+    if img_w <= 0 or img_h <= 0:
+        return QRect(0, 0, widget_w, widget_h)
+
+    scale = min(widget_w / img_w, widget_h / img_h)
+    draw_w = int(img_w * scale)
+    draw_h = int(img_h * scale)
+    x = (widget_w - draw_w) // 2
+    y = (widget_h - draw_h) // 2
+    return QRect(x, y, draw_w, draw_h)

app/ui/main_window.py

@@ -0,0 +1,377 @@
+"""Main application window."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from PySide6.QtCore import QTimer
+from PySide6.QtWidgets import QLabel, QMainWindow, QMessageBox, QSizePolicy, QStatusBar
+
+from app.camera.camera_enumerator import CameraEnumerator, CameraFormat, CameraInfo
+from app.camera.camera_service import CameraService
+from app.camera.uvc import make_uvc_controller
+from app.camera.uvc.base import UvcControllerBase
+from app.camera.uvc.stub import NullUvcController
+from app.config import APP_NAME, APP_VERSION
+from app.inference.bbox_overlay import BboxOverlay
+from app.inference.worker_manager import InferenceManager
+from app.overlay.telemetry_overlay import TelemetryOverlay
+from app.pipeline.frame_dispatcher import FrameDispatcher
+from app.telemetry.csv_logger import CsvTelemetryLogger
+from app.telemetry.telemetry_collector import TelemetryCollector
+from app.ui.camera_settings_dialog import CameraSettingsDialog
+from app.ui.camera_view import CameraView
+from app.ui.menu_bar import AppMenuBar
+from app.video.video_player import VideoPlayer
+
+logger = logging.getLogger(__name__)
+
+
+class MainWindow(QMainWindow):
+    """
+    Top-level application window.
+
+    Frame source (exclusive):
+        • CameraService  — live camera (default)
+        • VideoPlayer    — local video file
+
+    Inference pipeline (optional):
+        InferenceManager runs YOLO in a separate process.
+        Frames submitted via FrameDispatcher subscriber (drop_if_busy).
+        Results displayed by BboxOverlay.
+
+    Signal flow:
+        [CameraService | VideoPlayer].frame_ready(QVideoFrame)
+            → FrameDispatcher.dispatch
+                → CameraView.on_frame             (render)
+                → TelemetryCollector.on_frame     (metrics)
+                    → TelemetryOverlay            (HUD)
+                    → CsvTelemetryLogger          (CSV)
+                → InferenceManager.submit_frame   (drop_if_busy, optional)
+                    → [worker process] YOLO
+                    → BboxOverlay.on_detections   (draw boxes)
+    """
+
+    def __init__(self, log_path: Path | None = None) -> None:
+        super().__init__()
+
+        self.setWindowTitle(f"{APP_NAME} v{APP_VERSION}")
+        self.setMinimumSize(640, 480)
+        self.resize(1280, 720)
+
+        # --- Core pipeline ---
+        self._camera_service = CameraService(self)
+        self._video_player = VideoPlayer(self)
+        self._dispatcher = FrameDispatcher(self)
+        self._telemetry = TelemetryCollector(parent=self)
+        self._inference = InferenceManager(self)
+
+        # Track which source is active
+        self._video_source_active: bool = False
+        self._current_camera: CameraInfo | None = None
+
+        # --- UVC ---
+        self._uvc: UvcControllerBase = NullUvcController()
+
+        # --- CSV logger ---
+        self._csv_logger: CsvTelemetryLogger | None = None
+        if log_path is not None:
+            csv_path = log_path.with_suffix(".csv")
+            self._csv_logger = CsvTelemetryLogger(csv_path)
+            logger.info("Telemetry CSV: %s", csv_path.resolve())
+
+        # --- Camera view ---
+        self._camera_view = CameraView(self)
+        self._camera_view.setSizePolicy(
+            QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding
+        )
+        self.setCentralWidget(self._camera_view)
+
+        # --- Overlay layers ---
+        self._telemetry_overlay = TelemetryOverlay()
+        self._bbox_overlay = BboxOverlay()
+        self._camera_view.add_overlay_layer(self._telemetry_overlay)
+        self._camera_view.add_overlay_layer(self._bbox_overlay)
+        self._bbox_overlay.visible = False   # hidden until inference enabled
+
+        # --- Menu bar ---
+        self._menu = AppMenuBar(self)
+        self.setMenuBar(self._menu)
+        if log_path is not None:
+            self._menu.set_log_file_path(str(log_path.resolve()))
+
+        # --- Status bar ---
+        self._status_bar = QStatusBar(self)
+        self.setStatusBar(self._status_bar)
+        self._status_label = QLabel("Initialising\u2026")
+        self._status_bar.addWidget(self._status_label, stretch=1)
+        # Detection counter — right-aligned permanent widget
+        self._detection_label = QLabel("")
+        self._detection_label.setVisible(False)
+        self._status_bar.addPermanentWidget(self._detection_label)
+
+        # --- Wire signals ---
+        self._wire_signals()
+
+        QTimer.singleShot(0, self._initialise_cameras)
+
+    # ------------------------------------------------------------------
+    # Initialisation
+    # ------------------------------------------------------------------
+
+    def _initialise_cameras(self) -> None:
+        cameras = CameraEnumerator.list_cameras()
+        if not cameras:
+            self._status_label.setText("No cameras found")
+            logger.warning("No cameras detected")
+            return
+
+        self._menu.populate_cameras(cameras)
+        default = CameraEnumerator.default_camera()
+        start_cam = default if default is not None else cameras[0]
+        self._menu.populate_formats(start_cam)
+        self._start_camera(start_cam)
+
+    def _start_camera(self, cam: CameraInfo) -> None:
+        self._current_camera = cam
+        self._telemetry.reset_counters()
+        self._camera_service.start(cam)
+        self._menu.set_active_camera(cam)
+        self._status_label.setText(f"Opening: {cam.name}")
+        self._open_uvc(cam)
+
+    def _open_uvc(self, cam: CameraInfo) -> None:
+        if self._uvc.is_open():
+            self._uvc.close()
+        ctrl = make_uvc_controller(cam.name)
+        if not ctrl.is_open():
+            ctrl.open(cam.name)
+        self._uvc = ctrl
+
+    # ------------------------------------------------------------------
+    # Signal wiring
+    # ------------------------------------------------------------------
+
+    def _wire_signals(self) -> None:
+        # ---- Active source → dispatcher ----
+        # (connected dynamically in _switch_to_camera / _switch_to_video)
+        self._camera_service.frame_ready.connect(self._dispatcher.dispatch)
+
+        # ---- Dispatcher fans out to all consumers ----
+        self._dispatcher.subscribe(self._camera_view.on_frame, drop_if_busy=True)
+        self._dispatcher.subscribe(self._telemetry.on_frame, drop_if_busy=False)
+        # InferenceManager subscriber added/removed dynamically on toggle
+
+        # ---- Telemetry ----
+        self._telemetry.metrics_updated.connect(
+            self._telemetry_overlay.on_metrics_updated
+        )
+        if self._csv_logger is not None:
+            self._telemetry.metrics_updated.connect(self._csv_logger.on_metrics_updated)
+        self._camera_service.format_changed.connect(self._telemetry.set_target_fps)
+
+        # ---- Camera service status ----
+        self._camera_service.camera_started.connect(self._on_camera_started)
+        self._camera_service.camera_stopped.connect(self._on_camera_stopped)
+        self._camera_service.camera_error.connect(self._on_camera_error)
+
+        # ---- Video player status ----
+        self._video_player.playback_started.connect(self._on_playback_started)
+        self._video_player.playback_stopped.connect(self._on_playback_stopped)
+        self._video_player.playback_error.connect(self._on_playback_error)
+
+        # ---- InferenceManager ----
+        self._inference.detections_ready.connect(self._bbox_overlay.on_detections)
+        self._inference.detection_count_updated.connect(self._on_detection_count_updated)
+        self._inference.inference_stats_updated.connect(self._on_inference_stats_updated)
+        self._inference.inference_started.connect(self._on_inference_started)
+        self._inference.inference_stopped.connect(self._on_inference_stopped)
+        self._inference.inference_error.connect(self._on_inference_error)
+
+        # ---- Menu ----
+        self._menu.camera_selected.connect(self._on_camera_selected)
+        self._menu.format_selected.connect(self._on_format_selected)
+        self._menu.reconnect_requested.connect(self._camera_service.reconnect)
+        self._menu.overlay_toggled.connect(self._camera_view.set_all_overlays_visible)
+        self._menu.camera_settings_requested.connect(self._on_settings_requested)
+        self._menu.video_file_selected.connect(self._on_video_selected)
+        self._menu.video_closed.connect(self._on_video_closed)
+        self._menu.model_file_selected.connect(self._on_model_selected)
+        self._menu.inference_toggled.connect(self._on_inference_toggled)
+
+    # ------------------------------------------------------------------
+    # Source switching
+    # ------------------------------------------------------------------
+
+    def _switch_to_camera(self) -> None:
+        """Disconnect VideoPlayer, connect CameraService to dispatcher."""
+        try:
+            self._video_player.frame_ready.disconnect(self._dispatcher.dispatch)
+        except RuntimeError:
+            pass
+        self._camera_service.frame_ready.connect(self._dispatcher.dispatch)
+        self._video_source_active = False
+        self._menu.set_video_source_active(False)
+
+    def _switch_to_video(self) -> None:
+        """Disconnect CameraService, connect VideoPlayer to dispatcher."""
+        try:
+            self._camera_service.frame_ready.disconnect(self._dispatcher.dispatch)
+        except RuntimeError:
+            pass
+        self._video_player.frame_ready.connect(self._dispatcher.dispatch)
+        self._video_source_active = True
+        self._menu.set_video_source_active(True)
+
+    # ------------------------------------------------------------------
+    # Camera status slots
+    # ------------------------------------------------------------------
+
+    def _on_camera_started(self) -> None:
+        cam = self._camera_service.current_camera
+        name = cam.name if cam else "Unknown"
+        self._status_label.setText(f"Streaming: {name}")
+        logger.info("Camera streaming: %s", name)
+
+    def _on_camera_stopped(self) -> None:
+        self._status_label.setText("Camera stopped")
+
+    def _on_camera_error(self, message: str) -> None:
+        self._status_label.setText(f"Error: {message}")
+        logger.error("Camera error: %s", message)
+
+    # ------------------------------------------------------------------
+    # Video player slots
+    # ------------------------------------------------------------------
+
+    def _on_playback_started(self) -> None:
+        path = self._video_player.current_path or ""
+        name = Path(path).name if path else "video"
+        self._status_label.setText(f"Playing: {name}")
+
+    def _on_playback_stopped(self) -> None:
+        self._status_label.setText("Playback finished")
+
+    def _on_playback_error(self, message: str) -> None:
+        self._status_label.setText(f"Video error: {message}")
+        logger.error(message)
+
+    # ------------------------------------------------------------------
+    # Inference slots
+    # ------------------------------------------------------------------
+
+    def _on_inference_started(self) -> None:
+        self._status_label.setText("Inference running")
+        self._menu.set_inference_checked(True)
+
+    def _on_detection_count_updated(self, count: int) -> None:
+        self._detection_label.setText(f"Detections: {count} frames")
+
+    def _on_inference_stats_updated(self, device: str, avg_ms: float) -> None:
+        self._telemetry.set_inference_stats(device, avg_ms)
+
+    def _on_inference_stopped(self) -> None:
+        self._bbox_overlay.clear()
+
+    def _on_inference_error(self, message: str) -> None:
+        logger.error("Inference: %s", message)
+        self._menu.set_inference_available(False)
+        self._menu.set_inference_checked(False)
+        self._bbox_overlay.visible = False
+        self._detection_label.setVisible(False)
+        self._telemetry.clear_inference_stats()
+        QMessageBox.critical(self, "Inference Error", message)
+
+    # ------------------------------------------------------------------
+    # Menu action slots
+    # ------------------------------------------------------------------
+
+    def _on_camera_selected(self, cam: CameraInfo) -> None:
+        if self._video_source_active:
+            self._video_player.stop()
+            self._switch_to_camera()
+        self._start_camera(cam)
+
+    def _on_format_selected(self, fmt: CameraFormat) -> None:
+        logger.info(
+            "Format selected via menu: %dx%d @ %.4g fps (%s)",
+            fmt.width, fmt.height, fmt.max_fps, fmt.pixel_format,
+        )
+        self._camera_service.set_format(fmt)
+
+    def _on_settings_requested(self) -> None:
+        qt_cam = self._camera_service.qt_camera
+        if qt_cam is None:
+            logger.warning("Settings requested but no camera is active")
+            return
+        dlg = CameraSettingsDialog(qt_cam, self._uvc, parent=self)
+        dlg.exec()
+
+    def _on_video_selected(self, path: str) -> None:
+        """Switch source to video file."""
+        self._camera_service.stop()
+        self._switch_to_video()
+        self._video_player.play(path)
+        logger.info("Video source: %s", path)
+
+    def _on_video_closed(self) -> None:
+        """Return to camera source."""
+        self._video_player.stop()
+        self._switch_to_camera()
+        if self._current_camera is not None:
+            self._start_camera(self._current_camera)
+        logger.info("Returned to camera source")
+
+    def _on_model_selected(self, path: str) -> None:
+        """Load YOLO model into inference manager."""
+        name = Path(path).name
+        logger.info("Loading model: %s", path)
+        self._status_label.setText(f"Loading model: {name}\u2026")
+        self._inference.start(path)
+        self._menu.set_model_label(name)
+        self._menu.set_inference_available(True)
+        self._menu.set_inference_checked(False)   # user must explicitly enable
+
+    def _on_inference_toggled(self, enabled: bool) -> None:
+        if enabled:
+            if not self._inference.is_running:
+                # shouldn't happen but be safe
+                logger.warning("Inference toggle on but manager not running")
+                self._menu.set_inference_checked(False)
+                return
+            self._inference.resume()
+            self._dispatcher.subscribe(
+                self._inference.submit_frame, drop_if_busy=True
+            )
+            self._bbox_overlay.visible = True
+            self._detection_label.setText("Detections: 0 frames")
+            self._detection_label.setVisible(True)
+            self._status_label.setText("Inference enabled")
+            logger.info("Inference enabled")
+        else:
+            self._inference.pause()
+            self._dispatcher.unsubscribe(self._inference.submit_frame)
+            self._bbox_overlay.clear()
+            self._bbox_overlay.visible = False
+            self._detection_label.setVisible(False)
+            self._telemetry.clear_inference_stats()
+            self._status_label.setText("Inference disabled")
+            logger.info("Inference disabled")
+
+    # ------------------------------------------------------------------
+    # Qt overrides
+    # ------------------------------------------------------------------
+
+    def closeEvent(self, event) -> None:  # noqa: N802
+        self._inference.stop()
+        self._camera_service.stop()
+        self._video_player.stop()
+        if self._uvc.is_open():
+            self._uvc.close()
+        if self._csv_logger is not None:
+            logger.info(
+                "CSV telemetry: %d rows written", self._csv_logger.rows_written
+            )
+            self._csv_logger.close()
+        super().closeEvent(event)

app/ui/menu_bar.py

@@ -0,0 +1,278 @@
+"""Menu bar — File, Camera, Video format, Image, Model and Debug controls."""
+
+from __future__ import annotations
+
+import logging
+
+from PySide6.QtCore import Signal
+from PySide6.QtGui import QAction, QActionGroup
+from PySide6.QtWidgets import QFileDialog, QMenuBar, QWidget
+
+from app.camera.camera_enumerator import CameraFormat, CameraInfo
+from app.config import MODEL_FILE_EXTENSIONS, VIDEO_FILE_EXTENSIONS
+from app.logging_setup import set_console_level
+
+logger = logging.getLogger(__name__)
+
+
+class AppMenuBar(QMenuBar):
+    """
+    Application menu bar.
+
+    Signals:
+        video_file_selected(str)    — user picked a video file path
+        video_closed()              — user chose to close video and return to camera
+        model_file_selected(str)    — user picked a .pt model file path
+        inference_toggled(bool)     — user toggled inference on/off
+        camera_selected(CameraInfo)
+        format_selected(CameraFormat)
+        reconnect_requested()
+        overlay_toggled(bool)
+        log_toggled(bool)
+        camera_settings_requested()
+    """
+
+    # File / video
+    video_file_selected = Signal(str)
+    video_closed = Signal()
+
+    # Model / inference
+    model_file_selected = Signal(str)
+    inference_toggled = Signal(bool)
+
+    # Camera
+    camera_selected = Signal(object)        # CameraInfo
+    format_selected = Signal(object)        # CameraFormat
+    reconnect_requested = Signal()
+
+    # View / debug
+    overlay_toggled = Signal(bool)
+    log_toggled = Signal(bool)
+    camera_settings_requested = Signal()
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+
+        self._camera_group: QActionGroup | None = None
+        self._format_group: QActionGroup | None = None
+        self._cameras: list[CameraInfo] = []
+
+        self._build_menus()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def populate_cameras(self, cameras: list[CameraInfo]) -> None:
+        self._cameras = cameras
+        menu = self._camera_menu
+
+        for action in list(menu.actions()):
+            if action not in (self._reconnect_action, self._cam_separator):
+                menu.removeAction(action)
+
+        self._camera_group = QActionGroup(self)
+        self._camera_group.setExclusive(True)
+
+        for cam in cameras:
+            action = QAction(cam.name, self)
+            action.setCheckable(True)
+            action.setData(cam)
+            self._camera_group.addAction(action)
+            menu.insertAction(self._cam_separator, action)
+            action.triggered.connect(self._on_camera_action)
+
+        if cameras:
+            self._camera_group.actions()[0].setChecked(True)
+
+    def populate_formats(self, camera_info: CameraInfo) -> None:
+        self._populate_format_menu(camera_info)
+
+    def set_active_camera(self, camera_info: CameraInfo) -> None:
+        if self._camera_group is None:
+            return
+        for action in self._camera_group.actions():
+            if action.data() is camera_info:
+                action.setChecked(True)
+                return
+
+    def set_active_format(self, fmt: CameraFormat) -> None:
+        if self._format_group is None:
+            return
+        for action in self._format_group.actions():
+            f: CameraFormat = action.data()
+            if (
+                f.width == fmt.width
+                and f.height == fmt.height
+                and abs(f.max_fps - fmt.max_fps) < 0.5
+                and f.pixel_format == fmt.pixel_format
+            ):
+                action.setChecked(True)
+                return
+
+    def set_log_file_path(self, path: str) -> None:
+        display = path if len(path) <= 60 else "\u2026" + path[-57:]
+        self._log_file_action.setText(f"Log: {display}")
+        self._log_file_action.setToolTip(path)
+
+    def set_video_source_active(self, is_video: bool) -> None:
+        """Update File menu state when source switches between camera and video."""
+        self._close_video_action.setEnabled(is_video)
+
+    def set_inference_available(self, available: bool) -> None:
+        """Enable/disable the inference toggle (requires model to be loaded)."""
+        self._inference_toggle_action.setEnabled(available)
+
+    def set_inference_checked(self, checked: bool) -> None:
+        self._inference_toggle_action.setChecked(checked)
+
+    def set_model_label(self, name: str) -> None:
+        """Show loaded model name as disabled info item."""
+        self._model_info_action.setText(f"Model: {name}")
+
+    # ------------------------------------------------------------------
+    # Menu construction
+    # ------------------------------------------------------------------
+
+    def _build_menus(self) -> None:
+        # --- File menu ---
+        file_menu = self.addMenu("File")
+
+        open_video_action = QAction("Open Video\u2026", self)
+        open_video_action.triggered.connect(self._on_open_video)
+        file_menu.addAction(open_video_action)
+
+        self._close_video_action = QAction("Close Video", self)
+        self._close_video_action.setEnabled(False)
+        self._close_video_action.triggered.connect(self.video_closed)
+        file_menu.addAction(self._close_video_action)
+
+        # --- Camera menu ---
+        self._camera_menu = self.addMenu("Camera")
+        self._cam_separator = self._camera_menu.addSeparator()
+        self._reconnect_action = QAction("Reconnect", self)
+        self._reconnect_action.triggered.connect(self.reconnect_requested)
+        self._camera_menu.addAction(self._reconnect_action)
+
+        # --- Video menu ---
+        self._video_menu = self.addMenu("Video")
+        self._res_menu = self._video_menu.addMenu("Resolution")
+
+        # --- Image menu ---
+        self._image_menu = self.addMenu("Image")
+        self._settings_action = QAction("Camera Settings\u2026", self)
+        self._settings_action.triggered.connect(self.camera_settings_requested)
+        self._image_menu.addAction(self._settings_action)
+
+        # --- Model menu ---
+        model_menu = self.addMenu("Model")
+
+        load_model_action = QAction("Load Model\u2026", self)
+        load_model_action.triggered.connect(self._on_load_model)
+        model_menu.addAction(load_model_action)
+
+        self._inference_toggle_action = QAction("Enable Inference", self)
+        self._inference_toggle_action.setCheckable(True)
+        self._inference_toggle_action.setChecked(False)
+        self._inference_toggle_action.setEnabled(False)   # enabled after model loaded
+        self._inference_toggle_action.toggled.connect(self.inference_toggled)
+        model_menu.addAction(self._inference_toggle_action)
+
+        model_menu.addSeparator()
+
+        self._model_info_action = QAction("Model: (none)", self)
+        self._model_info_action.setEnabled(False)
+        model_menu.addAction(self._model_info_action)
+
+        # --- Debug menu ---
+        debug_menu = self.addMenu("Debug")
+
+        self._overlay_action = QAction("Show Overlay", self)
+        self._overlay_action.setCheckable(True)
+        self._overlay_action.setChecked(True)
+        self._overlay_action.toggled.connect(self.overlay_toggled)
+        debug_menu.addAction(self._overlay_action)
+
+        self._log_action = QAction("Console Logging", self)
+        self._log_action.setCheckable(True)
+        self._log_action.setChecked(False)
+        self._log_action.toggled.connect(self._on_log_toggled)
+        debug_menu.addAction(self._log_action)
+
+        debug_menu.addSeparator()
+
+        self._log_file_action = QAction("Log: (not started)", self)
+        self._log_file_action.setEnabled(False)
+        debug_menu.addAction(self._log_file_action)
+
+    def _populate_format_menu(self, camera_info: CameraInfo) -> None:
+        self._res_menu.clear()
+        self._format_group = QActionGroup(self)
+        self._format_group.setExclusive(True)
+
+        for fmt in camera_info.formats:
+            label = (
+                f"{fmt.width}\u00d7{fmt.height}"
+                f" @ {fmt.max_fps:.4g}fps"
+                f" ({fmt.pixel_format})"
+            )
+            action = QAction(label, self)
+            action.setCheckable(True)
+            action.setData(fmt)
+            self._format_group.addAction(action)
+            self._res_menu.addAction(action)
+            action.triggered.connect(self._on_format_action)
+
+        actions = self._format_group.actions()
+        if actions:
+            actions[0].setChecked(True)
+
+    # ------------------------------------------------------------------
+    # Slots
+    # ------------------------------------------------------------------
+
+    def _on_open_video(self) -> None:
+        path, _ = QFileDialog.getOpenFileName(
+            self.parentWidget(),
+            "Open Video File",
+            "",
+            VIDEO_FILE_EXTENSIONS,
+        )
+        if path:
+            logger.debug("Video file selected: %s", path)
+            self.video_file_selected.emit(path)
+
+    def _on_load_model(self) -> None:
+        path, _ = QFileDialog.getOpenFileName(
+            self.parentWidget(),
+            "Load YOLO Model",
+            "",
+            MODEL_FILE_EXTENSIONS,
+        )
+        if path:
+            logger.debug("Model file selected: %s", path)
+            self.model_file_selected.emit(path)
+
+    def _on_camera_action(self) -> None:
+        action = self.sender()
+        if action is None:
+            return
+        cam: CameraInfo = action.data()
+        logger.debug("Camera selected: %s", cam.name)
+        self.camera_selected.emit(cam)
+        self._populate_format_menu(cam)
+
+    def _on_format_action(self) -> None:
+        action = self.sender()
+        if action is None:
+            return
+        fmt: CameraFormat = action.data()
+        logger.debug(
+            "Format selected: %dx%d @ %.4g fps (%s)",
+            fmt.width, fmt.height, fmt.max_fps, fmt.pixel_format,
+        )
+        self.format_selected.emit(fmt)
+
+    def _on_log_toggled(self, enabled: bool) -> None:
+        set_console_level(enabled)
+        self.log_toggled.emit(enabled)

app/video/video_player.py

@@ -0,0 +1,117 @@
+"""VideoPlayer — plays a local video file and delivers frames via frame_ready signal.
+
+The public interface mirrors CameraService so MainWindow can treat both
+interchangeably: both emit frame_ready(QVideoFrame).
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from PySide6.QtCore import QObject, QUrl, Signal, Slot
+from PySide6.QtMultimedia import (
+    QMediaPlayer,
+    QVideoFrame,
+    QVideoSink,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class VideoPlayer(QObject):
+    """
+    Wraps QMediaPlayer + QVideoSink to replay a local video file.
+
+    Signal flow (identical interface to CameraService):
+        VideoPlayer.frame_ready(QVideoFrame) → FrameDispatcher
+
+    Notes:
+        - Playback is real-time (1×) — no seek/pause in this version.
+        - At end-of-file: emits playback_stopped() and stops.
+        - On any error: emits playback_error(str) then playback_stopped().
+    """
+
+    frame_ready = Signal(QVideoFrame)
+    playback_started = Signal()
+    playback_stopped = Signal()
+    playback_error = Signal(str)
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+
+        self._player = QMediaPlayer(self)
+        self._sink = QVideoSink(self)
+
+        self._player.setVideoSink(self._sink)
+
+        self._sink.videoFrameChanged.connect(self._on_frame)
+        self._player.playbackStateChanged.connect(self._on_playback_state_changed)
+        self._player.errorOccurred.connect(self._on_error)
+
+        self._current_path: str | None = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def play(self, path: str) -> None:
+        """Open and start playing a video file."""
+        self.stop()
+        p = Path(path)
+        if not p.exists():
+            msg = f"Video file not found: {path}"
+            logger.error(msg)
+            self.playback_error.emit(msg)
+            return
+
+        self._current_path = path
+        url = QUrl.fromLocalFile(str(p.resolve()))
+        self._player.setSource(url)
+        self._player.play()
+        logger.info("VideoPlayer: starting playback of '%s'", p.name)
+
+    def stop(self) -> None:
+        """Stop playback and clear source."""
+        if self._player.playbackState() != QMediaPlayer.PlaybackState.StoppedState:
+            self._player.stop()
+        self._player.setSource(QUrl())
+        self._current_path = None
+
+    @property
+    def is_playing(self) -> bool:
+        return (
+            self._player.playbackState()
+            == QMediaPlayer.PlaybackState.PlayingState
+        )
+
+    @property
+    def current_path(self) -> str | None:
+        return self._current_path
+
+    # ------------------------------------------------------------------
+    # Private slots
+    # ------------------------------------------------------------------
+
+    @Slot(QVideoFrame)
+    def _on_frame(self, frame: QVideoFrame) -> None:
+        if frame.isValid():
+            self.frame_ready.emit(frame)
+
+    @Slot(QMediaPlayer.PlaybackState)
+    def _on_playback_state_changed(self, state: QMediaPlayer.PlaybackState) -> None:
+        if state == QMediaPlayer.PlaybackState.PlayingState:
+            logger.info("VideoPlayer: playing")
+            self.playback_started.emit()
+        elif state == QMediaPlayer.PlaybackState.StoppedState:
+            logger.info("VideoPlayer: stopped")
+            self.playback_stopped.emit()
+
+    @Slot(QMediaPlayer.Error, str)
+    def _on_error(self, error: QMediaPlayer.Error, error_string: str) -> None:
+        if error == QMediaPlayer.Error.NoError:
+            return
+        msg = f"VideoPlayer error: {error_string}"
+        logger.error(msg)
+        self.playback_error.emit(msg)
+        self.playback_stopped.emit()

duck_preview/__main__.py

@@ -1,3 +0,0 @@
-from duck_preview.app import main
-
-main()

duck_preview/app.py

@@ -1,47 +0,0 @@
-from __future__ import annotations
-
-import sys
-
-from PySide6.QtCore import QTimer
-from PySide6.QtMultimedia import QVideoSink
-from PySide6.QtWidgets import QApplication
-
-from duck_preview.camera.service import CameraService
-from duck_preview.dispatcher.frame_dispatcher import FrameDispatcher
-from duck_preview.main_window import MainWindow
-from duck_preview.rendering.overlay import OverlayWidget
-from duck_preview.rendering.video_widget import VideoWidget
-from duck_preview.telemetry.collector import TelemetryCollector
-
-
-def main() -> None:
-    app = QApplication(sys.argv)
-    app.setApplicationName("Duck Preview")
-
-    camera = CameraService()
-    video_sink = QVideoSink()
-    dispatcher = FrameDispatcher()
-    telemetry = TelemetryCollector()
-    video_widget = VideoWidget()
-    overlay = OverlayWidget()
-
-    camera.set_video_widget(video_widget)
-    camera.set_video_sink(video_sink)
-
-    video_sink.videoFrameChanged.connect(dispatcher.on_frame)
-    dispatcher.subscribe(telemetry.on_frame)
-
-    window = MainWindow(camera, video_widget, overlay)
-
-    camera.error_occurred.connect(lambda msg: overlay.set_metrics({"error": msg}))
-
-    metrics_timer = QTimer()
-    metrics_timer.timeout.connect(lambda: overlay.set_metrics(telemetry.metrics()))
-    metrics_timer.start(200)
-
-    window.show()
-    sys.exit(app.exec())
-
-
-if __name__ == "__main__":
-    main()

duck_preview/camera/service.py

@@ -1,59 +0,0 @@
-from __future__ import annotations
-
-from PySide6.QtCore import QObject, Signal
-from PySide6.QtMultimedia import (
-    QCamera,
-    QCameraDevice,
-    QCameraFormat,
-    QMediaCaptureSession,
-    QMediaDevices,
-    QVideoSink,
-)
-from PySide6.QtMultimediaWidgets import QVideoWidget
-
-
-class CameraService(QObject):
-    error_occurred = Signal(str)
-
-    def __init__(self, parent: QObject | None = None) -> None:
-        super().__init__(parent)
-        self._session = QMediaCaptureSession()
-        self._camera: QCamera | None = None
-
-    @property
-    def session(self) -> QMediaCaptureSession:
-        return self._session
-
-    def set_video_widget(self, widget: QVideoWidget) -> None:
-        self._session.setVideoOutput(widget)
-
-    def set_video_sink(self, sink: QVideoSink) -> None:
-        self._session.setVideoSink(sink)
-
-    @staticmethod
-    def available_cameras() -> list[QCameraDevice]:
-        return QMediaDevices.videoInputs()
-
-    def is_active(self) -> bool:
-        return self._camera is not None and self._camera.isActive()
-
-    def start(self, device: QCameraDevice) -> None:
-        self.stop()
-        self._camera = QCamera(device, self)
-        self._camera.errorOccurred.connect(self._on_error)
-        self._session.setCamera(self._camera)
-        self._camera.start()
-
-    def stop(self) -> None:
-        if self._camera is not None:
-            self._camera.stop()
-            self._session.setCamera(None)
-            self._camera.deleteLater()
-            self._camera = None
-
-    def set_camera_format(self, fmt: QCameraFormat) -> None:
-        if self._camera is not None:
-            self._camera.setCameraFormat(fmt)
-
-    def _on_error(self, error: QCamera.Error, error_string: str) -> None:
-        self.error_occurred.emit(error_string)

duck_preview/dispatcher/frame_dispatcher.py

@@ -1,22 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Callable
-
-from PySide6.QtCore import QObject
-from PySide6.QtMultimedia import QVideoFrame
-
-
-class FrameDispatcher(QObject):
-    def __init__(self, parent: QObject | None = None) -> None:
-        super().__init__(parent)
-        self._subscribers: list[Callable[[QVideoFrame], None]] = []
-
-    def subscribe(self, callback: Callable[[QVideoFrame], None]) -> None:
-        self._subscribers.append(callback)
-
-    def unsubscribe(self, callback: Callable[[QVideoFrame], None]) -> None:
-        self._subscribers.remove(callback)
-
-    def on_frame(self, frame: QVideoFrame) -> None:
-        for cb in self._subscribers:
-            cb(frame)

duck_preview/main_window.py

@@ -1,139 +0,0 @@
-from __future__ import annotations
-
-from PySide6.QtCore import QCameraPermission, Qt
-from PySide6.QtGui import QAction, QCloseEvent
-from PySide6.QtMultimedia import QCameraDevice, QMediaDevices
-from PySide6.QtWidgets import QApplication, QGridLayout, QMainWindow, QWidget
-
-from duck_preview.camera.service import CameraService
-from duck_preview.rendering.overlay import OverlayWidget
-from duck_preview.rendering.video_widget import VideoWidget
-
-
-class MainWindow(QMainWindow):
-    def __init__(
-        self,
-        camera_service: CameraService,
-        video_widget: VideoWidget,
-        overlay_widget: OverlayWidget,
-        parent: QWidget | None = None,
-    ) -> None:
-        super().__init__(parent)
-        self._camera = camera_service
-        self._video_widget = video_widget
-        self._overlay = overlay_widget
-        self._media_devices = QMediaDevices()
-
-        self.setWindowTitle("Duck Preview")
-        self.resize(1280, 720)
-
-        central = QWidget()
-        self.setCentralWidget(central)
-        layout = QGridLayout(central)
-        layout.setContentsMargins(0, 0, 0, 0)
-        layout.setSpacing(0)
-        layout.addWidget(video_widget, 0, 0)
-        layout.addWidget(overlay_widget, 0, 0)
-
-        self._setup_menus()
-
-        self._media_devices.videoInputsChanged.connect(self._rebuild_camera_menu)
-
-    def _setup_menus(self) -> None:
-        menu_bar = self.menuBar()
-
-        self._camera_menu = menu_bar.addMenu("Camera")
-        self._rebuild_camera_menu()
-
-        self._resolution_menu = menu_bar.addMenu("Resolution")
-        self._resolution_menu.setEnabled(False)
-
-        self._fps_menu = menu_bar.addMenu("FPS")
-        self._fps_menu.setEnabled(False)
-
-        debug_menu = menu_bar.addMenu("Debug")
-        toggle_overlay = QAction("Show Metrics", self)
-        toggle_overlay.setCheckable(True)
-        toggle_overlay.setChecked(True)
-        toggle_overlay.triggered.connect(self._overlay.set_visible)
-        debug_menu.addAction(toggle_overlay)
-
-    def _rebuild_camera_menu(self) -> None:
-        self._camera_menu.clear()
-        cameras = CameraService.available_cameras()
-        for device in cameras:
-            action = QAction(device.description(), self)
-            action.triggered.connect(lambda checked, d=device: self._on_camera_selected(d))
-            self._camera_menu.addAction(action)
-        if not cameras:
-            action = QAction("No cameras detected", self)
-            action.setEnabled(False)
-            self._camera_menu.addAction(action)
-
-    def _on_camera_selected(self, device: QCameraDevice) -> None:
-        self._request_camera_permission(device)
-
-    def _request_camera_permission(self, device: QCameraDevice) -> None:
-        perm = QCameraPermission()
-        match QApplication.checkPermission(perm):
-            case Qt.PermissionStatus.Undetermined:
-                QApplication.requestPermission(
-                    perm, self, lambda: self._request_camera_permission(device)
-                )
-            case Qt.PermissionStatus.Denied:
-                self._overlay.set_metrics(
-                    {
-                        "error": (
-                            "Camera permission denied.\n"
-                            "Grant access in System Settings > "
-                            "Privacy & Security > Camera"
-                        )
-                    }
-                )
-            case Qt.PermissionStatus.Granted:
-                self._camera.start(device)
-                self._rebuild_resolution_menu(device)
-
-    def _rebuild_resolution_menu(self, device: QCameraDevice) -> None:
-        self._resolution_menu.clear()
-        self._resolution_menu.setEnabled(True)
-        formats = device.videoFormats()
-        seen: set[tuple[int, int]] = set()
-        for fmt in formats:
-            res = fmt.resolution()
-            key = (res.width(), res.height())
-            if key not in seen:
-                seen.add(key)
-                action = QAction(f"{res.width()}x{res.height()}", self)
-                action.triggered.connect(
-                    lambda checked, d=device, w=res.width(), h=res.height(): (
-                        self._on_resolution_selected(d, w, h)
-                    )
-                )
-                self._resolution_menu.addAction(action)
-
-    def _on_resolution_selected(self, device: QCameraDevice, width: int, height: int) -> None:
-        self._rebuild_fps_menu(device, width, height)
-
-    def _rebuild_fps_menu(self, device: QCameraDevice, width: int, height: int) -> None:
-        self._fps_menu.clear()
-        self._fps_menu.setEnabled(True)
-        formats = device.videoFormats()
-        seen_labels: set[str] = set()
-        for fmt in formats:
-            res = fmt.resolution()
-            if res.width() == width and res.height() == height:
-                min_fps = round(fmt.minFrameRate())
-                max_fps = round(fmt.maxFrameRate())
-                label = f"{max_fps} FPS" if min_fps == max_fps else f"{min_fps}-{max_fps} FPS"
-                if label not in seen_labels:
-                    seen_labels.add(label)
-                    action = QAction(label, self)
-                    action.triggered.connect(
-                        lambda checked, f=fmt: self._camera.set_camera_format(f)
-                    )
-                    self._fps_menu.addAction(action)
-
-    def closeEvent(self, event: QCloseEvent) -> None:  # noqa: N802
-        self._camera.stop()
-        super().closeEvent(event)

duck_preview/rendering/overlay.py

@@ -1,73 +0,0 @@
-from __future__ import annotations
-
-from PySide6.QtCore import Qt
-from PySide6.QtGui import QColor, QFont, QFontMetrics, QPainter
-from PySide6.QtWidgets import QWidget
-
-
-class OverlayWidget(QWidget):
-    def __init__(self, parent: QWidget | None = None) -> None:
-        super().__init__(parent)
-        self.setAttribute(Qt.WA_TransparentForMouseEvents)
-        self.setAttribute(Qt.WA_NoSystemBackground)
-        self._visible = True
-        self._metrics: dict[str, float | int | str] = {}
-
-    def set_visible(self, visible: bool) -> None:
-        self._visible = visible
-        self.update()
-
-    def set_metrics(self, metrics: dict[str, float | int | str]) -> None:
-        self._metrics = metrics
-        self.update()
-
-    def paintEvent(self, event) -> None:  # noqa: N802
-        if not self._visible or not self._metrics:
-            return
-
-        painter = QPainter(self)
-        painter.setRenderHint(QPainter.TextAntialiasing)
-
-        if "error" in self._metrics:
-            self._paint_error(painter)
-        else:
-            self._paint_metrics(painter)
-
-    def _paint_metrics(self, painter: QPainter) -> None:
-        lines = [
-            f"FPS:     {self._metrics.get('fps', 0):>7}",
-            f"Frame:   {self._metrics.get('frame_time_ms', 0):>7.1f} ms",
-            f"Frames:  {self._metrics.get('frame_count', 0):>7}",
-        ]
-
-        font = QFont("monospace", 11)
-        painter.setFont(font)
-        fm = QFontMetrics(font)
-
-        text_width = max(fm.horizontalAdvance(line) for line in lines) + 24
-        text_height = len(lines) * (fm.height() + 6) + 12
-
-        painter.fillRect(8, 8, text_width, text_height, QColor(0, 0, 0, 160))
-        painter.setPen(QColor(0, 255, 0))
-
-        for i, line in enumerate(lines):
-            y = 22 + i * (fm.height() + 6)
-            painter.drawText(16, y, line)
-
-    def _paint_error(self, painter: QPainter) -> None:
-        msg = str(self._metrics.get("error", "Unknown error"))
-        lines = msg.split("\n")
-
-        font = QFont("monospace", 12)
-        painter.setFont(font)
-        fm = QFontMetrics(font)
-
-        text_width = max(fm.horizontalAdvance(line) for line in lines) + 24
-        text_height = len(lines) * (fm.height() + 6) + 12
-
-        painter.fillRect(8, 8, text_width, text_height, QColor(0, 0, 0, 200))
-        painter.setPen(QColor(200, 50, 50))
-
-        for i, line in enumerate(lines):
-            y = 22 + i * (fm.height() + 6)
-            painter.drawText(16, y, line)

duck_preview/rendering/video_widget.py

@@ -1,10 +0,0 @@
-from __future__ import annotations
-
-from PySide6.QtMultimediaWidgets import QVideoWidget
-from PySide6.QtWidgets import QWidget
-
-
-class VideoWidget(QVideoWidget):
-    def __init__(self, parent: QWidget | None = None) -> None:
-        super().__init__(parent)
-        self.setMinimumSize(320, 240)

duck_preview/telemetry/collector.py

@@ -1,39 +0,0 @@
-from __future__ import annotations
-
-import time
-from collections import deque
-
-from PySide6.QtCore import QObject
-from PySide6.QtMultimedia import QVideoFrame
-
-
-class TelemetryCollector(QObject):
-    def __init__(self, parent: QObject | None = None) -> None:
-        super().__init__(parent)
-        self._timestamps: deque[float] = deque(maxlen=500)
-
-    def on_frame(self, frame: QVideoFrame) -> None:
-        self._timestamps.append(time.perf_counter())
-
-    def metrics(self) -> dict[str, float | int]:
-        if not self._timestamps:
-            return {"fps": 0, "frame_time_ms": 0.0, "frame_count": 0}
-
-        now = time.perf_counter()
-        cutoff = now - 1.0
-        recent = [t for t in self._timestamps if t >= cutoff]
-        fps = len(recent)
-
-        frame_time_ms = 0.0
-        if len(self._timestamps) >= 2:
-            diffs = [
-                self._timestamps[i] - self._timestamps[i - 1]
-                for i in range(1, len(self._timestamps))
-            ]
-            frame_time_ms = (sum(diffs) / len(diffs)) * 1000 if diffs else 0.0
-
-        return {
-            "fps": fps,
-            "frame_time_ms": round(frame_time_ms, 2),
-            "frame_count": len(self._timestamps),
-        }

models/.gitkeep

@@ -0,0 +1 @@
+

notes/01-mvp-plan.md

@@ -1,150 +1,324 @@
-# MVP Implementation Plan — Duck Preview
+# Plan działania — MVP Camera Preview (PySide6)
 
-## Stack
+## Środowisko
 
-- **Language:** Python 3.12
+| Element | Wartość |
-- **GUI/Framework:** PySide6 6.11 (QtMultimedia + QtWidgets)
+|---|---|
-- **Camera backend:** QCamera + QMediaCaptureSession + QVideoSink (native GPU)
+| Python | 3.12.10 (venv: `.venv-win`) |
-- **Rendering:** QWidget (paintEvent) z QPainter — manual render z QVideoFrame → QImage
+| Framework GUI | PySide6 6.11.0 |
-- **Testing:** pytest
+| Dev platform | Windows 11 |
-- **Linting/Formatting:** ruff
+| Target platform | Mac Mini (Intel i7, macOS Ventura) |
-
+| Kamera docelowa | ELP USB Camera |
-## Architecture
+| Narzędzia | pytest, ruff, colorama |
-
-```
-CameraService
-  └─ QVideoSink.videoFrame ──→ FrameDispatcher.on_frame
-                                   ├─ VideoWidget.on_frame  (render klatki)
-                                   ├─ TelemetryCollector.on_frame  (timestamp)
-                                   └─ [Future AI subscribers]
-
-TelemetryCollector.metrics() ──→ OverlayWidget.set_metrics()
-                                  (polled co 200ms przez QTimer w app.py)
-```
-
-## Kolejność implementacji
-
-### 0. Project scaffolding
-`pyproject.toml` — projekt, zależność PySide6, entry point, ruff config, pytest
-`duck_preview/__init__.py`, `__main__.py` — entry point `python -m duck_preview`
-Podkatalogi: `camera/`, `dispatcher/`, `rendering/`, `telemetry/`
-
-### 1. CameraService (`camera/service.py`)
-- Wrapper na `QCamera` + `QMediaCaptureSession` + `QVideoSink`
-- `available_cameras()` — static, zwraca listę `QCameraDevice` z `QMediaDevices`
-- `start(device)` / `stop()` — zarządzanie cyklem życia kamery
-- `set_camera_format(fmt)` — zmiana rozdzielczości/FPS
-- `sink` property — QVideoSink do podpięcia dispatchera
-- `error_occurred` Signal — propagacja błędów kamery
-
-### 2. FrameDispatcher (`dispatcher/frame_dispatcher.py`)
-- Prosty pub/sub: `subscribe(cb)` / `unsubscribe(cb)`
-- `on_frame(frame)` — wołany z sygnału QVideoSink, iteruje wszystkich subskrybentów
-- Frame dropping: na razie brak (wszystkie callbacki szybkie)
-
-### 3. TelemetryCollector (`telemetry/collector.py`)
-- Subskrybent dispatchera
-- Zbiera timestampy (`deque`, maxlen=500)
-- `metrics()` → dict: fps (klatki z ostatniej sekundy), frame_time_ms (średnia delta między klatkami), frame_count
-- Brak CPU usage (out of scope na MVP)
-
-### 4. VideoWidget (`rendering/video_widget.py`)
-- `QWidget` z `WA_OpaquePaintEvent`
-- `on_frame(frame)` — `frame.toImage()` → zapis QImage → `update()`
-- `paintEvent` — skalowanie z zachowaniem proporcji, centrowanie, letterboxing
-- Brak klatek → wyświetla "No camera feed"
-
-### 5. OverlayWidget (`rendering/overlay.py`)
-- Przezroczysty QWidget (`WA_TransparentForMouseEvents`)
-- Nakładka na video, rysuje tekst metryk (FPS, frame time, frame count)
-- Semi-transparentne tło, zielona czcionka Consolas
-- Toggle widoczności przez menu Debug
-
-### 6. MainWindow (`main_window.py`)
-- `QMainWindow` z menu barem:
-  - **Camera** — lista dostępnych kamer (dynamiczna, reaguje na `videoInputsChanged`)
-  - **Resolution** — dostępne rozdzielczości dla wybranej kamery
-  - **FPS** — dostępne FPS dla wybranej rozdzielczości
-  - **Debug** — toggle nakładki
-- Central widget: GridLayout z VideoWidget + OverlayWidget (stacked)
-
-### 7. App (`app.py`)
-- `main()` — tworzy QApplication, instancjonuje i łączy zależności (ręczne DI)
-- Wire: camera.sink → dispatcher.on_frame
-- Wire: dispatcher → telemetry.on_frame, video_widget.on_frame
-- QTimer 200ms: telemetry.metrics() → overlay.set_metrics()
-- `__main__.py` → `from duck_preview.app import main; main()`
 
 ---
 
-## DI Wiring (ręczne, w app.py)
+## Fazy realizacji
+
+### Faza 0 — Projekt i scaffolding
+
+Cel: ustalenie struktury katalogów i modułów przed napisaniem pierwszej linii logiki.
+
+#### 0.1 Struktura projektu
 
 ```
-app = QApplication(sys.argv)
+duck-preview2/
-
+├── app/
-camera = CameraService()
-dispatcher = FrameDispatcher()
-telemetry = TelemetryCollector()
-video_widget = VideoWidget()
-overlay = OverlayWidget()
-
-camera.sink.videoFrame.connect(dispatcher.on_frame)
-
-dispatcher.subscribe(telemetry.on_frame)
-dispatcher.subscribe(video_widget.on_frame)
-
-window = MainWindow(camera, video_widget, overlay)
-
-# Poll telemetry co 200ms → overlay
-metrics_timer = QTimer()
-metrics_timer.timeout.connect(lambda: overlay.set_metrics(telemetry.metrics()))
-metrics_timer.start(200)
-
-window.show()
-app.exec()
-```
-
----
-
-## Struktura plików
-
-```
-duck-preview/
-├── pyproject.toml
-├── notes/
-│   ├── 01-mvp-preview.md
-│   └── 01-mvp-plan.md
-├── duck_preview/
 │   ├── __init__.py
-│   ├── __main__.py
+│   ├── main.py                  # entry point
-│   ├── app.py
+│   ├── config.py                # stałe, domyślne ustawienia
-│   ├── main_window.py
 │   ├── camera/
 │   │   ├── __init__.py
-│   │   └── service.py
+│   │   ├── camera_service.py    # QCamera + QMediaCaptureSession
-│   ├── dispatcher/
+│   │   └── camera_enumerator.py # wykrywanie dostępnych kamer
+│   ├── pipeline/
 │   │   ├── __init__.py
-│   │   └── frame_dispatcher.py
+│   │   └── frame_dispatcher.py  # dystrybucja klatek do subskrybentów
-│   ├── rendering/
+│   ├── telemetry/
 │   │   ├── __init__.py
-│   │   ├── video_widget.py
+│   │   └── telemetry_collector.py # zbieranie metryk FPS/frame time/CPU
-│   │   └── overlay.py
+│   ├── overlay/
-│   └── telemetry/
+│   │   ├── __init__.py
+│   │   └── overlay_widget.py    # przezroczysta warstwa QWidget
+│   └── ui/
 │       ├── __init__.py
-│       └── collector.py
+│       ├── main_window.py       # główne okno aplikacji
-└── tests/
+│       └── menu_bar.py          # menu: kamera, rozdzielczość, FPS, debug
-    ├── __init__.py
+├── tests/
-    ├── test_dispatcher.py
+│   ├── __init__.py
-    └── test_collector.py
+│   ├── test_camera_enumerator.py
+│   └── test_telemetry_collector.py
+├── notes/
+├── requirements.txt
+├── requirements-dev.txt
+└── pyproject.toml               # konfiguracja ruff + pytest
+```
+
+#### 0.2 Pliki konfiguracyjne
+
+- `pyproject.toml` — konfiguracja ruff (linter/formatter) i pytest
+- `requirements.txt` — zależności produkcyjne (PySide6)
+- `requirements-dev.txt` — zależności deweloperskie (pytest, ruff)
+- `.gitignore` — aktualizacja o artefakty Pythona
+
+---
+
+### Faza 1 — Camera Service
+
+Cel: stabilne pobranie obrazu z kamery przez QtMultimedia.
+
+#### 1.1 Camera Enumerator
+
+- `QMediaDevices.videoInputs()` — lista dostępnych kamer
+- Zwraca listę `QCameraDevice` z nazwą, id i obsługiwanymi formatami
+- Obsługa braku kamer (komunikat, nie crash)
+- Test jednostkowy: mockowanie `QMediaDevices`
+
+#### 1.2 Camera Service
+
+- Opakowuje `QCamera` + `QMediaCaptureSession`
+- API:
+  - `start(device: QCameraDevice)` — uruchamia kamerę
+  - `stop()` — zatrzymuje kamerę
+  - `set_resolution(width, height)` — ustawia format
+  - `set_fps(fps)` — ustawia docelowy FPS
+  - `reconnect()` — restart po błędzie
+- `QVideoSink` jako punkt odbioru klatek
+- Sygnał `frame_ready(QVideoFrame)` do Frame Dispatcher
+- Obsługa błędów kamery (`QCamera.errorOccurred`)
+
+#### 1.3 Uwagi platformowe
+
+| Aspekt | Windows 11 (dev) | macOS Ventura (target) |
+|---|---|---|
+| Backend | DirectShow / Media Foundation | AVFoundation |
+| Kamera ELP | USB, standardowy UVC driver | USB, UVC |
+| Format klatek | YUYV / MJPEG | YUYV / MJPEG |
+| GPU rendering | ANGLE (OpenGL ES) | Metal |
+
+---
+
+### Faza 2 — Frame Dispatcher
+
+Cel: dystrybucja klatek do wielu odbiorców bez blokowania akwizycji.
+
+#### 2.1 Frame Dispatcher
+
+- Wzorzec: publish-subscribe (lista callbacków)
+- `subscribe(callback: Callable[[QVideoFrame], None])`
+- `unsubscribe(callback)`
+- `dispatch(frame: QVideoFrame)` — wywołuje wszystkich subskrybentów
+- Klatki NIE są kopiowane — subskrybenci działają na referencji
+- Subskrybenci mogą **pominąć klatkę** (tryb drop-if-busy)
+- Wywołanie `dispatch` następuje w wątku GUI (slot połączony z `frame_ready`)
+
+#### 2.2 Subskrybenci w Fazie 1
+
+| Subskrybent | Działanie |
+|---|---|
+| Video Renderer | przekazuje klatkę do `QVideoSink` / `QVideoWidget` |
+| Telemetry Collector | mierzy czas, zlicza klatki |
+
+---
+
+### Faza 3 — Video Renderer
+
+Cel: renderowanie klatki w GUI bez zbędnych kopii.
+
+#### 3.1 Podejście
+
+- `QVideoWidget` jako główny widget podglądu
+- `QMediaCaptureSession.setVideoOutput(QVideoWidget)` — ścieżka bezpośrednia, zero kopii
+- Alternatywnie: `QVideoSink` → `QGraphicsVideoItem` dla przyszłych overlayów
+- Domyślnie: `QVideoWidget` (prosta, niska latencja)
+
+#### 3.2 Wymagania
+
+- Preview nie blokuje wątku GUI
+- Obsługa aspect ratio (letter/pillarbox)
+- Resize okna bez migotania
+
+---
+
+### Faza 4 — Telemetry Collector
+
+Cel: dokładne metryki pipeline'u wideo.
+
+#### 4.1 Zbierane metryki
+
+| Metryka | Metoda pomiaru |
+|---|---|
+| Realtime FPS | licznik klatek / okno 1 s |
+| Frame time | `time.perf_counter()` między klatkami |
+| Frame acquisition time | timestamp wejście frame_ready → dispatch |
+| Rendering time | czas `QVideoWidget.update()` (opcjonalnie) |
+| Dropped frames | detekcja przez numerację lub timestamp gap |
+| CPU usage | `psutil.cpu_percent()` (dodać do requirements) |
+| Memory usage | `psutil.virtual_memory()` (opcjonalnie) |
+
+#### 4.2 API
+
+- `TelemetryCollector` — subskrybent Frame Dispatcher
+- `on_frame(frame: QVideoFrame)` — rejestruje timestamp klatki
+- `get_snapshot() -> TelemetrySnapshot` — aktualny stan metryk (dataclass)
+- `update_interval_ms: int` — jak często odświeżać snapshot (domyślnie 500 ms)
+- Sygnał `metrics_updated(TelemetrySnapshot)` — emitowany co `update_interval_ms`
+
+#### 4.3 TelemetrySnapshot (dataclass)
+
+```python
+@dataclass
+class TelemetrySnapshot:
+    fps: float
+    frame_time_ms: float
+    dropped_frames: int
+    cpu_percent: float
+    memory_mb: float | None
+    timestamp: float
 ```
 
 ---
 
-## Edge cases / uwagi
+### Faza 5 — Overlay System
 
-- Brak kamer → menu Camera pokazuje "No cameras detected"
+Cel: wyświetlanie metryk na przezroczystej warstwie nad podglądem.
-- Brak klatek → VideoWidget pokazuje ciemne tło + napis
+
-- Błąd kamery → CameraService emituje `error_occurred` (na razie tylko log)
+#### 5.1 Architektura
-- Zamknięcie okna → `closeEvent` → `camera.stop()`
+
-- QVideoFrame.toImage() kopiuje dane — akceptowalne dla MVP
+- `OverlayWidget(QWidget)` — przezroczysty widget (`WA_TransparentForMouseEvents`)
-- Wszystkie obiekty żyją w main thread — brak problemów z threadingiem
+- Pozycjonowany absolutnie nad `QVideoWidget` (ten sam parent, wyższy z-index)
+- `paintEvent` rysuje semi-przezroczysty prostokąt + tekst z metrykami
+- Połączony z sygnałem `metrics_updated` — odświeża tylko gdy dane się zmienią
+
+#### 5.2 Zawartość overlaya (MVP)
+
+```
+FPS:    60.0
+Frame:  16.7 ms
+Drop:   0
+CPU:    12.3 %
+```
+
+#### 5.3 Sterowalność
+
+- Widoczność overlaya: toggle przez menu Debug
+- Pozycja: lewy górny róg (stała w MVP)
+- Kolor tła: `rgba(0, 0, 0, 160)`
+
+---
+
+### Faza 6 — GUI / Main Window
+
+Cel: minimalne, funkcjonalne okno aplikacji.
+
+#### 6.1 MainWindow
+
+- `QMainWindow` z `QVideoWidget` jako central widget
+- `OverlayWidget` nałożony na video
+- Obsługa resize → reposition overlay
+- Tytuł okna: `Duck Preview`
+
+#### 6.2 MenuBar
+
+Menu **Camera**:
+- Lista wykrytych kamer (radio-style)
+- Separator
+- Reconnect
+
+Menu **Video**:
+- Resolution submenu (pobierane dynamicznie z `QCameraDevice.videoFormats()`)
+- FPS submenu
+
+Menu **Debug**:
+- Toggle overlay metryk
+- Logowanie do konsoli (toggle)
+
+#### 6.3 Startup flow
+
+```
+main.py
+  → QApplication
+  → CameraEnumerator.list_cameras()
+  → MainWindow(cameras)
+  → CameraService.start(cameras[0])  # pierwsza kamera lub ELP
+  → FrameDispatcher.subscribe(telemetry, renderer)
+  → app.exec()
+```
+
+---
+
+### Faza 7 — Testy i walidacja
+
+#### 7.1 Testy jednostkowe
+
+| Moduł | Co testować |
+|---|---|
+| `CameraEnumerator` | lista kamer, brak kamer, format danych |
+| `TelemetryCollector` | obliczenia FPS, wykrywanie dropów |
+| `FrameDispatcher` | subskrypcja, odsubskrypcja, dispatch |
+| `TelemetrySnapshot` | poprawność dataclass |
+
+#### 7.2 Testy manualne (Windows dev)
+
+- [ ] Uruchomienie z kamerą laptopa / USB webcam
+- [ ] Przełączanie kamer
+- [ ] Zmiana rozdzielczości
+- [ ] Zmiana FPS
+- [ ] Toggle overlay
+- [ ] Reconnect po odłączeniu kamery
+
+#### 7.3 Testy na Mac Mini (target)
+
+- [ ] Wykrycie kamery ELP
+- [ ] Poprawny format YUYV/MJPEG
+- [ ] Wydajność AVFoundation vs DirectShow
+- [ ] GPU rendering przez Metal
+
+#### 7.4 Kryteria sukcesu (z PRD)
+
+- Preview stabilny i płynny
+- Latencja renderowania niska
+- Dane telemetrii dokładne
+- GUI responsywne
+- Overlay działa poprawnie
+- Architektura gotowa na subskrybentów AI
+
+---
+
+## Kolejność implementacji (sprint order)
+
+```
+Sprint 1:  Faza 0  — scaffolding, pyproject.toml, requirements
+Sprint 2:  Faza 1  — CameraEnumerator + CameraService (bez GUI)
+Sprint 3:  Faza 3  — VideoRenderer + MainWindow (preview działa)
+Sprint 4:  Faza 2  — FrameDispatcher (refactor pipeline)
+Sprint 5:  Faza 4  — TelemetryCollector
+Sprint 6:  Faza 5  — OverlayWidget
+Sprint 7:  Faza 6  — MenuBar (camera/resolution/fps switch)
+Sprint 8:  Faza 7  — Testy, poprawki, walidacja na Mac Mini
+```
+
+---
+
+## Zależności do dodania
+
+```
+# requirements.txt
+PySide6>=6.7
+psutil>=6.0
+
+# requirements-dev.txt
+pytest>=8.0
+ruff>=0.4
+```
+
+---
+
+## Uwagi cross-platform
+
+1. **ELP camera** — kamera UVC, powinna działać bez dodatkowych sterowników na obu platformach. Sprawdzić obsługiwane rozdzielczości i FPS przez `QCameraDevice.videoFormats()`.
+2. **Ścieżki absolutne** — unikać `os.path` na korzyść `pathlib.Path`.
+3. **Threading** — wszystkie operacje Qt muszą odbywać się w wątku GUI. `TelemetryCollector` może używać `QTimer` zamiast osobnego wątku.
+4. **Format klatek** — na macOS AVFoundation preferuje `BGRA` lub `NV12`. Konwersja powinna być leniwa i tylko gdy potrzebna (nie w hot path renderowania).
+5. **High DPI** — włączyć `QApplication.setHighDpiScaleFactorRoundingPolicy` dla konsistencji Windows/Mac.
+6. **Testowanie bez kamery** — `CameraEnumerator` powinien umożliwiać dependency injection / mock dla środowisk CI.

notes/01-mvp-preview.md

@@ -253,6 +253,7 @@ Architecture must support future additions:
 * snapshots,
 * streaming,
 * remote sinks.
+* play video files
 
 Without major redesign.
 

notes/02-mvp-app.md

@@ -0,0 +1,194 @@
+# Stan aplikacji — MVP Camera Preview
+
+Data: 2026-05-12
+Środowisko dev: Windows 11, Python 3.12.10, PySide6 6.11.0
+Środowisko docelowe: Mac Mini (Intel i7, macOS Ventura), kamera ELP USB
+
+---
+
+## Zaimplementowane moduły
+
+### Struktura projektu
+
+```
+duck-preview2/
+├── app/
+│   ├── config.py                        # stałe i domyślne ustawienia
+│   ├── main.py                          # entry point (python -m app.main)
+│   ├── camera/
+│   │   ├── camera_enumerator.py         # wykrywanie kamer przez QMediaDevices
+│   │   └── camera_service.py            # zarządzanie QCamera + QMediaCaptureSession
+│   ├── pipeline/
+│   │   └── frame_dispatcher.py          # pub/sub dystrybucja QVideoFrame
+│   ├── telemetry/
+│   │   └── telemetry_collector.py       # pomiar FPS, frame time, CPU, pamięci
+│   ├── overlay/
+│   │   ├── overlay_layer.py             # interfejs IOverlayLayer (ABC)
+│   │   └── telemetry_overlay.py         # implementacja — box z metrykami
+│   └── ui/
+│       ├── camera_view.py               # CameraView — render + kompozycja overlayów
+│       ├── main_window.py               # główne okno, wiring komponentów
+│       └── menu_bar.py                  # menu: Camera / Video / Debug
+├── tests/
+│   ├── test_frame_dispatcher.py         # 8 testów jednostkowych
+│   └── test_telemetry_collector.py      # 7 testów jednostkowych
+├── pyproject.toml                       # konfiguracja pytest + ruff
+├── requirements.txt                     # PySide6, psutil
+└── requirements-dev.txt                 # + pytest, ruff
+```
+
+### Opis komponentów
+
+#### CameraEnumerator (`app/camera/camera_enumerator.py`)
+- Wykrywa dostępne kamery przez `QMediaDevices.videoInputs()`
+- Zwraca listę `CameraInfo` z nazwą, id i listą obsługiwanych formatów (rozdzielczość × FPS)
+- Formaty deduplikowane i posortowane (największa rozdzielczość pierwsza)
+- Obsługa braku kamer bez crasha
+
+#### CameraService (`app/camera/camera_service.py`)
+- Opakowuje `QCamera` + `QMediaCaptureSession` + `QVideoSink`
+- API: `start(CameraInfo)`, `stop()`, `reconnect()`, `set_resolution()`, `set_fps()`
+- Algorytm doboru formatu: score-based (priorytet: dopasowanie rozdzielczości, potem FPS)
+- Sygnały: `frame_ready(QVideoFrame)`, `camera_started`, `camera_stopped`, `camera_error`
+
+#### FrameDispatcher (`app/pipeline/frame_dispatcher.py`)
+- Pub/sub: `subscribe(callback, drop_if_busy=True)` / `unsubscribe(callback)`
+- `drop_if_busy=True` — klatka pomijana jeśli subskrybent jest zajęty (render)
+- `drop_if_busy=False` — każda klatka dociera (telemetria)
+- Odporny na wyjątki w subskrybentach (jeden nie blokuje pozostałych)
+
+#### TelemetryCollector (`app/telemetry/telemetry_collector.py`)
+- Subskrybuje każdą klatkę (`drop_if_busy=False`)
+- Mierzy: FPS (okno 1 s), średni frame time (ring-buffer 120 próbek), dropped frames (heurystyka 2.5× avg)
+- CPU: `psutil.Process.cpu_percent()` — tylko nasz proces, inicjalizowany w `__init__` (warmup)
+- RAM: `memory_info().wset` (Windows private working set) lub `rss` (macOS/Linux)
+- Emituje `metrics_updated(TelemetrySnapshot)` co 500 ms przez `QTimer`
+
+#### IOverlayLayer (`app/overlay/overlay_layer.py`)
+- Abstrakcja (ABC) dla pluggable overlayów
+- Interface: `paint(painter: QPainter, video_rect: QRect)`, `visible: bool`, `name: str`
+- Nowe overlaye nie wymagają modyfikacji żadnego istniejącego kodu
+
+#### TelemetryOverlay (`app/overlay/telemetry_overlay.py`)
+- Implementacja `IOverlayLayer`
+- Rysuje semi-przezroczysty box z metrykami w lewym górnym rogu video
+- Slot `on_metrics_updated(TelemetrySnapshot)` — odbiera dane z TelemetryCollector
+- Format: FPS, Frame time, Drop count, CPU %, Mem MB
+
+#### CameraView (`app/ui/camera_view.py`)
+- Zwykły `QWidget` (nie `QVideoWidget`) — render przez `QPainter` w `paintEvent`
+- Odbiera `QVideoFrame` przez slot `on_frame()`, konwertuje do `QImage.Format_RGB32`
+- Letterboxing z zachowaniem aspect ratio
+- Rejestr overlayów: `add_overlay_layer()`, `remove_overlay_layer()`, `set_all_overlays_visible()`
+- W `paintEvent`: rysuje klatkę → iteruje po warstwach, każda dostaje `painter.save()/restore()`
+
+#### MainWindow (`app/ui/main_window.py`)
+- Wires together wszystkie komponenty
+- Minimalny status bar (nazwa kamery, błędy)
+- `closeEvent` → `CameraService.stop()`
+
+#### AppMenuBar (`app/ui/menu_bar.py`)
+- Menu **Camera**: lista wykrytych kamer (radio), Reconnect
+- Menu **Video**: Resolution submenu, FPS submenu (pobierane z `QCameraDevice.videoFormats()`)
+- Menu **Debug**: Show Overlay (toggle), Console Logging (toggle poziom logowania)
+
+---
+
+## Co działało na Windows 11 (dev)
+
+- Wykrycie wbudowanej kamery laptopa
+- Podgląd w czasie rzeczywistym
+- Przełączanie rozdzielczości i FPS z menu
+- Overlay z metrykami widoczny i aktualizowany
+- Toggle overlay przez Debug menu
+- Logowanie do konsoli przez Debug menu
+- Reconnect po zmianie kamery
+- Letterboxing przy resize okna
+
+---
+
+## Co próbowaliśmy i nie wyszło
+
+### QVideoWidget jako renderer (porzucone)
+
+**Podejście:** Użycie `QVideoWidget` jako centralnego widgetu + nałożenie `OverlayWidget` (child lub sibling).
+
+**Problem:** Na Windows `QVideoWidget` tworzy natywne okno HWND z powierzchnią D3D (Media Foundation backend). Natywna powierzchnia jest rysowana poza hierarchią Qt i zawsze przykrywa wszystkie `QWidget` — niezależnie od:
+- kolejności z-order (`raise_()`)
+- rodzica (child/sibling)
+- flag okna
+- `WA_TranslucentBackground` / `WA_NoSystemBackground`
+
+Żaden `QWidget` nie może się wyświetlić nad `QVideoWidget` na Windows.
+
+**Próby ratowania:**
+1. `OverlayWidget` jako child `QVideoWidget` — zasłonięty przez natywną powierzchnię
+2. Kontener `QWidget` z `QVideoWidget` i `OverlayWidget` jako rodzeństwo — nadal zasłonięty
+3. `setWindowFlags(FramelessWindowHint)` na child widget — odrywa widget od rodzica, tworzy osobne (niewidoczne) okno top-level
+
+**Rozwiązanie:** Porzucenie `QVideoWidget`. Własny `CameraView(QWidget)` odbiera klatki przez `QVideoSink`, konwertuje do `QImage` i rysuje przez `QPainter`. Overlay w tym samym `paintEvent` — brak konfliktu z natywnym renderowaniem.
+
+### OverlayWidget jako osobny QWidget (porzucone)
+
+**Podejście:** `OverlayWidget` z `WA_TransparentForMouseEvents` i `WA_TranslucentBackground` nałożony na video.
+
+**Problem:** Poza konfliktem z `QVideoWidget`, `WA_TranslucentBackground` na child widget działa tylko gdy rodzic też jest transparentny — Qt nie komponuje dziecka z tłem rodzica innym niż własne. W praktyce overlay był niewidoczny lub zasłaniał video czarnym prostokątem.
+
+---
+
+## Znane ograniczenia i uwagi
+
+### Pomiar CPU
+
+`psutil.Process.cpu_percent()` zwraca procent **względem jednego rdzenia** (np. 50% = pół rdzenia). Na wielordzeniowym procesorze 15% w Task Managerze (uśrednione po rdzeniach) może odpowiadać 50% na jednym rdzeniu. To nie jest błąd — to różna metodologia. Task Manager pokazuje `total_cpu / num_cores`, psutil pokazuje `cpu_time / wall_time`.
+
+Jeśli potrzebny jest widok "jak Task Manager": `process.cpu_percent() / psutil.cpu_count()`.
+
+### Pomiar RAM
+
+`memory_info().wset` (Windows) = Private Working Set = to co Task Manager pokazuje w kolumnie "Pamięć". RSS zawiera też współdzielone biblioteki (Qt DLLs ~40 MB) i dlatego było zawyżone. Na macOS używane jest `rss` (tam `wset` nie istnieje).
+
+### Wydajność konwersji klatek
+
+`QVideoFrame.toImage()` + `convertToFormat(RGB32)` wykonuje się na CPU. Przy 1080p60 to koszt ~1-3 ms/klatkę. Dla MVP akceptowalny. Przy przyszłej integracji YOLO warto rozważyć bezpośredni dostęp do danych przez `QVideoFrame.map()` i przekazywanie raw bufora do GPU.
+
+### Brak testów integracyjnych
+
+Testy jednostkowe pokrywają `FrameDispatcher` i `TelemetryCollector` w izolacji (bez Qt event loop). Brak testów `CameraView`, `CameraService` i `MainWindow` — wymagałyby `QApplication` i mockowania urządzeń.
+
+---
+
+## Stan zgodności z PRD (01-mvp-preview.md)
+
+| Wymaganie | Status |
+|---|---|
+| Realtime camera preview | Zaimplementowane |
+| Camera switching | Zaimplementowane |
+| Resolution selection | Zaimplementowane |
+| FPS selection | Zaimplementowane |
+| Reconnect/restart | Zaimplementowane |
+| Realtime FPS metric | Zaimplementowane |
+| Frame time metric | Zaimplementowane |
+| Dropped frames detection | Zaimplementowane (heurystyka) |
+| CPU usage metric | Zaimplementowane |
+| Memory usage metric | Zaimplementowane |
+| Overlay system | Zaimplementowane (IOverlayLayer) |
+| Performance metrics display | Zaimplementowane (TelemetryOverlay) |
+| Minimal GUI | Zaimplementowane |
+| Camera menu | Zaimplementowane |
+| Resolution/FPS menu | Zaimplementowane |
+| Debug/telemetry options | Zaimplementowane |
+| Architecture ready for AI subscribers | Zaimplementowane (IOverlayLayer + FrameDispatcher) |
+| Low latency preview | Zaimplementowane (drop-if-busy w dispatcher) |
+| Non-blocking GUI thread | Zaimplementowane |
+
+---
+
+## Następne kroki (poza MVP)
+
+- Walidacja na Mac Mini z kamerą ELP (AVFoundation backend, macOS Ventura)
+- Snapshot / recording
+- Integracja YOLO: `YoloBboxOverlay(IOverlayLayer)` + worker w osobnym procesie
+- Integracja OCR
+- Optymalizacja konwersji klatek (QVideoFrame.map() → numpy → GPU)
+- Testy integracyjne z QApplication + mock camera

notes/02-mvp-mac-plan.md

@@ -1,212 +0,0 @@
-# Plan — macOS fix + QVideoWidget + QVideoSink dual output
-
-## Cel
-
-Przywrócić działanie kamery na macOS (Elgato) przez:
-1. Przejście z manualnego `QPainter` renderowania na natywny `QVideoWidget`
-2. Dodanie `QVideoSink` jako drugiego wyjścia (frame access dla telemetrii)
-3. Obsługa `QCameraPermission` (Qt 6.5+)
-4. Dokumentacja packagingu przez `pyside6-deploy` na macOS
-
-## Kolejność implementacji
-
-### 1. camera/service.py
-
-```python
-class CameraService(QObject):
-    error_occurred = Signal(str)
-
-    def __init__(self, parent=None):
-        super().__init__(parent)
-        self._session = QMediaCaptureSession()
-        self._camera: QCamera | None = None
-
-    def set_video_widget(self, widget: QVideoWidget) -> None:
-        self._session.setVideoOutput(widget)
-
-    def set_video_sink(self, sink: QVideoSink) -> None:
-        self._session.setVideoSink(sink)
-
-    @property
-    def session(self) -> QMediaCaptureSession:
-        return self._session
-
-    @staticmethod
-    def available_cameras() -> list[QCameraDevice]:
-        return QMediaDevices.videoInputs()
-
-    def is_active(self) -> bool:
-        return self._camera is not None and self._camera.isActive()
-
-    def start(self, device: QCameraDevice) -> None:
-        self.stop()
-        self._camera = QCamera(device, self)
-        self._camera.errorOccurred.connect(self._on_error)
-        self._session.setCamera(self._camera)
-        self._camera.start()
-
-    def stop(self) -> None:
-        if self._camera is not None:
-            self._camera.stop()
-            self._session.setCamera(None)
-            self._camera.deleteLater()
-            self._camera = None
-
-    def set_camera_format(self, fmt: QCameraFormat) -> None:
-        if self._camera is not None:
-            self._camera.setCameraFormat(fmt)
-
-    def _on_error(self, error, error_string):
-        self.error_occurred.emit(error_string)
-```
-
-Zmiany:
-- Usunięto `self._sink` z `__init__`
-- Usunięto `self._session.setVideoOutput(self._sink)`
-- Dodano `set_video_widget(widget)` → `session.setVideoOutput(widget)`
-- Dodano `set_video_sink(sink)` → `session.setVideoSink(sink)`
-
-### 2. rendering/video_widget.py
-
-```python
-from __future__ import annotations
-
-from PySide6.QtMultimediaWidgets import QVideoWidget
-
-
-class VideoWidget(QVideoWidget):
-    def __init__(self, parent=None):
-        super().__init__(parent)
-        self.setMinimumSize(320, 240)
-```
-
-Zmiany:
-- Dziedziczy po `QVideoWidget` zamiast `QWidget`
-- Usunięto `on_frame(frame)` — nie potrzeba, renderowanie natywne
-- Usunięto `paintEvent` — nie potrzeba, robi to Qt
-- Usunięto `QImage`, `QPainter`, `SmoothPixmapTransform`
-
-### 3. rendering/overlay.py
-
-```python
-font = QFont("monospace", 11)  # zamiast "Consolas"
-```
-
-Dodatkowo: obsługa błędu w `paintEvent`:
-- Jeśli `self._metrics` ma klucz `"error"` → pomiń normalne metryki, narysuj czerwony komunikat błędu
-- Użyj `QColor(180, 40, 40)` zamiast zielonego
-
-### 4. app.py — nowe DI wiring
-
-```python
-def main():
-    app = QApplication(sys.argv)
-    app.setApplicationName("Duck Preview")
-
-    camera = CameraService()
-    video_sink = QVideoSink()
-    dispatcher = FrameDispatcher()
-    telemetry = TelemetryCollector()
-    video_widget = VideoWidget()
-    overlay = OverlayWidget()
-
-    camera.set_video_widget(video_widget)
-    camera.set_video_sink(video_sink)
-
-    video_sink.videoFrameChanged.connect(dispatcher.on_frame)
-    dispatcher.subscribe(telemetry.on_frame)
-
-    window = MainWindow(camera, video_widget, overlay)
-
-    # Wire error → overlay
-    camera.error_occurred.connect(
-        lambda msg: overlay.set_metrics({"error": msg})
-    )
-
-    # Poll telemetry → overlay
-    metrics_timer = QTimer()
-    metrics_timer.timeout.connect(
-        lambda: overlay.set_metrics(telemetry.metrics())
-    )
-    metrics_timer.start(200)
-
-    window.show()
-    sys.exit(app.exec())
-```
-
-Zmiany:
-- Tworzy `QVideoSink` jawnie
-- `camera.set_video_widget(video_widget)` + `camera.set_video_sink(video_sink)`
-- `video_sink.videoFrameChanged → dispatcher.on_frame`
-- Usunięto `camera.sink` (property nie istnieje)
-- `camera.error_occurred → overlay.set_metrics({"error": msg})`
-
-### 5. main_window.py — permission flow
-
-```python
-# Importy
-from PySide6.QtCore import QCameraPermission, Qt
-from PySide6.QtWidgets import QApplication
-
-# W _on_camera_selected:
-def _on_camera_selected(self, device: QCameraDevice) -> None:
-    self._request_camera_permission(device)
-
-def _request_camera_permission(self, device: QCameraDevice) -> None:
-    perm = QCameraPermission()
-    match QApplication.checkPermission(perm):
-        case Qt.PermissionStatus.Undetermined:
-            QApplication.requestPermission(perm, self,
-                lambda: self._request_camera_permission(device))
-        case Qt.PermissionStatus.Denied:
-            self._overlay.set_metrics({
-                "error": "Camera permission denied.\n"
-                         "Grant access in System Settings > "
-                         "Privacy & Security > Camera"
-            })
-        case Qt.PermissionStatus.Granted:
-            self._camera.start(device)
-            self._rebuild_resolution_menu(device)
-```
-
-### 6. pyside6-deploy.toml
-
-```toml
-[app]
-script = "duck_preview/__main__.py"
-name = "Duck Preview"
-bundle_identifier = "com.bartool.duck-preview"
-categories = "public.app-category.photography"
-platforms = ["macos"]
-```
-
-### 7. Po zmianach
-
-- `ruff check .` — czysty
-- `ruff format .` — sformatowany
-- `pytest -q` — 5 passed
-
----
-
-## Podsumowanie architektury końcowej
-
-```
-CameraService
-  ├─ session.setVideoOutput(VideoWidget)   → natywne GPU rendering
-  └─ session.setVideoSink(VideoSink)       → frame access
-                                              └─ videoFrameChanged
-                                                   → FrameDispatcher
-                                                        ├─ TelemetryCollector
-                                                        └─ [future AI]
-
-MainWindow
-  ├─ _on_camera_selected
-  │    → QCameraPermission check (Undetermined/Denied/Granted)
-  │    → CameraService.start(device)
-  ├─ error_occurred → OverlayWidget.set_metrics({"error": ...})
-  └─ QTimer 200ms → TelemetryCollector.metrics() → OverlayWidget
-
-OverlayWidget
-  ├─ normal: zielone metryki (FPS, frame time, frame count)
-  └─ error: czerwony komunikat (np. brak permisji)
-```

notes/02-mvp-mac.md

@@ -1,126 +0,0 @@
-# macOS — Camera on macOS with PySide6
-
-## Problem
-
-Aplikacja uruchomiona w interpreted mode (`python -m duck_preview`) na macOS z kamerą Elgato nie wyświetla obrazu.
-
-## Przyczyna
-
-Oficjalny przykład PySide6 (`camera.qml` / examples/multimedia) zawiera kod:
-
-```python
-if sys.platform == "darwin":
-    is_nuitka = "__compiled__" in globals()
-    if not is_nuitka and sys.platform == "darwin":
-        print("This example does not work on macOS when Python is run "
-              "in interpreted mode. For this example to work on macOS, "
-              "package the example using pyside6-deploy")
-        sys.exit(0)
-```
-
-**macOS → AVFoundation → wymaga spakowania przez Nuitka/pyside6-deploy.**
-
-`QCamera` na macOS potrzebuje properly bundled app structure (Info.plist, entitlements, code signing). W interpreted mode Python nie ma tego contextu.
-
-## Rozwiązanie
-
-Pakować aplikację przez `pyside6-deploy` (Nuitka) na macOS. Na Windows działa bez pakowania.
-
----
-
-## Qt Permission API (`QCameraPermission`)
-
-Od Qt 6.5+ dostępne jest `QCameraPermission` — nowoczesne API do proszenia o zgodę kamery.
-
-### API
-
-```python
-from PySide6.QtCore import QCameraPermission, Qt
-from PySide6.QtWidgets import QApplication
-
-perm = QCameraPermission()
-match QApplication.checkPermission(perm):
-    case Qt.PermissionStatus.Undetermined:
-        # Prosimy o zgodę → callback wywoła init ponownie
-        QApplication.requestPermission(perm, parent, callback)
-        return
-    case Qt.PermissionStatus.Denied:
-        # overlay: "Camera permission denied"
-    case Qt.PermissionStatus.Granted:
-        # uruchom kamerę
-```
-
-### Permission flow
-
-```
-User → wybiera kamerę w menu
-  → MainWindow._on_camera_selected(device)
-    → checkPermission(QCameraPermission)
-      ├─ Undetermined → requestPermission(camera, parent, callback)
-      │                   └─ callback → _on_camera_selected ponownie
-      ├─ Denied → overlay: "Camera permission denied. Grant access in System Settings > Privacy & Security > Camera"
-      └─ Granted → CameraService.start(device)
-```
-
----
-
-## QVideoWidget + QVideoSink — dual output
-
-PySide6 6.11 ma osobne metody w `QMediaCaptureSession`:
-
-| Metoda | Przeznaczenie |
-|--------|---------------|
-| `setVideoOutput(QVideoWidget*)` | Natywne renderowanie (GPU) |
-| `setVideoSink(QVideoSink*)` | Dostęp do klatek (telemetria, AI) |
-
-Oba działają **równolegle** — nie ma konfliktu.
-
-```
-QMediaCaptureSession
-  ├─ setVideoOutput(QVideoWidget)  → natywne renderowanie
-  └─ setVideoSink(QVideoSink)      → frame access
-                                       └─ videoFrameChanged → FrameDispatcher
-```
-
-QVideoSink dostarcza sygnał `videoFrameChanged(QVideoFrame)` — na to podpina się FrameDispatcher, a ten rozsyła do TelemetryCollector i przyszłych AI subscriberów.
-
----
-
-## macOS — packaging
-
-### pyside6-deploy
-
-```bash
-pip install nuitka
-pyside6-deploy duck_preview/__main__.py --name "Duck Preview"
-```
-
-### pyside6-deploy.toml
-
-```toml
-[app]
-script = "duck_preview/__main__.py"
-name = "Duck Preview"
-bundle_identifier = "com.bartool.duck-preview"
-categories = "public.app-category.photography"
-platforms = ["macos"]
-```
-
-Po spakowaniu powstaje `Duck Preview.app` — standalone bundle z dostępem do AVFoundation.
-
-### Windows
-
-Na Windows działa bez pakowania — `python -m duck_preview` w venv.
-
----
-
-## Font fallback
-
-`Consolas` nie istnieje na macOS. Używać `"monospace"` (generic font family — Qt mapuje na Menlo na macOS, Consolas na Windows).
-
-## Error state w Overlay
-
-Overlay wspiera wyświetlanie błędów (np. brak permisji):
-- Normalny stan → zielone metryki (FPS, frame times)
-- Error state → czerwony komunikat
-- Przełączanie przez `overlay.set_metrics({"error": "message"})`

notes/03-mvp-summary.md

@@ -0,0 +1,480 @@
+# Goal
+
+Zbudować aplikację do podglądu kamery w czasie rzeczywistym (PySide6) z telemetrią, overlayami i systemem logowania do pliku — docelowo na Mac Mini z kamerą ELP.
+
+---
+
+# Constraints & Preferences
+
+- Python 3.12.10, venv w `.venv-win`
+- Dev: Windows 11
+- Target: Mac Mini Intel i7, macOS Ventura, kamera ELP USB
+- `PySide6 6.11.0`, `psutil`, `pytest`, `ruff`
+- `QVideoWidget` porzucony — na Windows zasłania wszystkie child/sibling widgets przez natywny HWND D3D
+- Logi:
+  - `logs/` w katalogu projektu
+  - nowy plik z timestamp per sesja
+  - max 20 plików
+- CSV telemetrii:
+  - co 5 sekund
+  - `flush` po każdym wierszu
+- CPU:
+  - pokazywać oba:
+    - sys %
+    - per-core % (jak Task Manager)
+- Zmiana formatu kamery przez `stop+start`
+  - nie `setCameraFormat` na żywej kamerze
+
+---
+
+# Progress
+
+## Done
+
+### Faza 0–7 MVP
+
+- scaffolding
+- `CameraService`
+- `FrameDispatcher`
+- `TelemetryCollector`
+- `CameraView`
+- `TelemetryOverlay`
+- `IOverlayLayer`
+- `AppMenuBar`
+- `MainWindow`
+
+### Rendering
+
+- Usunięto `QVideoWidget`
+- `CameraView(QWidget)` z `paintEvent`
+  - render + overlay w jednym przejściu
+
+### Telemetria
+
+`TelemetrySnapshot` — pola:
+
+- `fps`
+- `target_fps`
+- `frame_time_ms`
+- `dropped_frames`
+- `cpu_percent_sys`
+- `cpu_percent_core`
+- `memory_mb`
+
+### Kamera
+
+- `CameraService.format_changed(float)` sygnał
+- `stop+start` przy:
+  - `set_resolution`
+  - `set_fps`
+
+### Logowanie
+
+- `_log_actual_format()`
+  - loguje rzeczywisty format po starcie kamery
+  - warning jeśli FPS się nie zgadza
+
+### CameraFormat
+
+`CameraFormat` dataclass z:
+
+```python
+pixel_format: str
+```
+
+Przykłady:
+
+- `MJPG`
+- `YUY2`
+- `NV12`
+
+w `camera_enumerator.py`
+
+### Logging
+
+`logging_setup.py`
+
+- `FileHandler`
+  - `DEBUG`
+  - zawsze aktywny
+- `StreamHandler`
+  - `WARNING`
+  - przełączalny
+- nagłówek sesji:
+  - wersja
+  - platforma
+  - Python
+  - PySide6
+  - CPU
+  - RAM
+- pruning starych logów
+
+### CSV
+
+`csv_logger.py`
+
+- `CsvTelemetryLogger`
+- throttling:
+  - 5 s
+- `flush` po każdym wierszu
+
+### Menu
+
+`menu_bar.py`
+
+- dostosowany do `CameraFormat`
+- `set_log_file_path()`
+- `set_console_level()`
+
+### Config
+
+`config.py`
+
+- `LOG_DIR`
+- `MAX_LOG_FILES`
+- `TELEMETRY_CSV_INTERVAL_S`
+
+### Main
+
+`main.py`
+
+- wywołuje `setup_logging()`
+- przekazuje `log_path` do `MainWindow`
+
+### Main Window
+
+`main_window.py`
+
+- przyjmuje:
+
+```python
+log_path: Path | None
+```
+
+- tworzy:
+
+```python
+CsvTelemetryLogger(log_path.with_suffix(".csv"))
+```
+
+- podpina do:
+  - `telemetry.metrics_updated`
+- wywołuje:
+  - `menu.set_log_file_path()`
+- `csv_logger.close()` w `closeEvent`
+
+### Repo
+
+`.gitignore`
+
+- dodano `logs/`
+
+### Testy i jakość
+
+- 20 testów jednostkowych
+  - wszystkie zielone
+- `ruff`
+  - czysty
+  - wszystkie błędy naprawione
+
+### Artefakty sesji
+
+Para plików per sesja:
+
+```text
+logs/duck-preview_<timestamp>.log
+logs/duck-preview_<timestamp>.csv
+```
+
+---
+
+## In Progress
+
+- (none)
+
+---
+
+## Blocked
+
+- (none)
+
+---
+
+# Key Decisions
+
+## Rendering
+
+### `QVideoWidget` → własny `CameraView(QWidget)`
+
+Jedyny skuteczny sposób obejścia problemu z natywnym HWND na Windows.
+
+## Overlay Architecture
+
+### `IOverlayLayer` ABC
+
+Pluggable overlaye bez modyfikacji `CameraView`.
+
+Gotowe pod:
+
+- YOLO
+- OCR
+- inne overlaye
+
+## Pipeline
+
+### `FrameDispatcher`
+
+Pub/sub z `drop_if_busy`:
+
+- render może gubić klatki
+- telemetria nigdy
+
+## CPU Metrics
+
+- CPU per-core (`psutil`)
+- dzielone przez `cpu_count`
+- wynik zgodny z Task Manager
+
+## Memory Metrics
+
+- `memory_info().wset` (Windows)
+- zamiast `rss`
+- odpowiada `Private Working Set`
+
+## Logging Strategy
+
+Dwa osobne pliki per sesja:
+
+- `.log` — diagnostyka
+- `.csv` — metryki szeregów czasowych
+
+## CameraFormat
+
+`CameraFormat` dataclass zamiast krotki:
+
+- niesie `pixel_format`
+- potrzebny w logach
+
+---
+
+# Next Steps
+
+1. Przetestować na Windows:
+   - czy logi powstają w `logs/`
+   - czy CSV zapisuje dane co ~5 s
+
+2. Przenieść na Mac Mini i przetestować z kamerą ELP:
+   - sprawdzić `pixel_format` w logu
+   - sprawdzić wykrycie backendu AVFoundation
+
+3. Zweryfikować overlay telemetrii na żywym obrazie
+
+4. (Opcjonalnie) dodać kolejne `IOverlayLayer`
+   - YOLO
+   - OCR
+
+---
+
+# Critical Context
+
+## Camera Enumerator
+
+`CameraEnumerator.list_cameras()` zwraca:
+
+```python
+list[CameraInfo]
+```
+
+gdzie:
+
+```python
+formats: list[CameraFormat]
+```
+
+`menu_bar.py` i `camera_service.py` iterują po:
+
+- `fmt.width`
+- `fmt.height`
+- `fmt.max_fps`
+
+---
+
+## CSV Logger
+
+Ścieżka CSV:
+
+```python
+log_path.with_suffix(".csv")
+```
+
+Powstaje para:
+
+- `.log`
+- `.csv`
+
+z tym samym timestamp.
+
+---
+
+## Console Logging
+
+```python
+logging_setup.set_console_level(debug: bool)
+```
+
+wywoływane z:
+
+```python
+menu_bar._on_log_toggled
+```
+
+---
+
+## Pixel Format
+
+```python
+pixel_format_name()
+```
+
+eksportowane z:
+
+```python
+camera_enumerator.py
+```
+
+używane również w:
+
+```python
+camera_service.py
+```
+
+---
+
+## Log Header
+
+Nagłówek logu zawiera:
+
+- wersję aplikacji
+- platformę
+- Python
+- PySide6
+- liczbę CPU
+- RAM
+
+---
+
+## Uruchamianie
+
+```bash
+.venv-win\Scripts\python.exe -m app.main
+```
+
+---
+
+## Ruff Fixes
+
+Naprawiono:
+
+- `E501`
+  - długa linia w `camera_enumerator.py`
+- `F401`
+- `I001`
+  - w `camera_service.py`
+  - w `main.py`
+
+---
+
+# Relevant Files
+
+## Entry Point
+
+- `app/main.py`
+  - wywołuje `setup_logging()`
+  - przekazuje `log_path`
+
+## Config
+
+- `app/config.py`
+  - `LOG_DIR`
+  - `MAX_LOG_FILES`
+  - `TELEMETRY_CSV_INTERVAL_S`
+
+## Logging
+
+- `app/logging_setup.py`
+  - konfiguracja logowania
+  - nagłówek sesji
+  - pruning
+
+## Telemetry
+
+- `app/telemetry/csv_logger.py`
+  - zapis CSV z throttlingiem
+
+- `app/telemetry/telemetry_collector.py`
+  - `TelemetrySnapshot`
+  - `TelemetryCollector`
+
+## Camera
+
+- `app/camera/camera_enumerator.py`
+  - `CameraFormat`
+  - `CameraInfo`
+  - `pixel_format_name()`
+
+- `app/camera/camera_service.py`
+  - `CameraService`
+  - `format_changed`
+  - `_log_actual_format()`
+
+## UI
+
+- `app/ui/main_window.py`
+  - kompletny
+  - podpięty `CsvTelemetryLogger`
+
+- `app/ui/menu_bar.py`
+  - `set_log_file_path()`
+  - `set_console_level()`
+
+- `app/ui/camera_view.py`
+  - `CameraView`
+  - rejestr `IOverlayLayer`
+
+## Overlay
+
+- `app/overlay/overlay_layer.py`
+  - `IOverlayLayer` ABC
+
+- `app/overlay/telemetry_overlay.py`
+  - `TelemetryOverlay(IOverlayLayer)`
+
+## Pipeline
+
+- `app/pipeline/frame_dispatcher.py`
+  - pub/sub
+  - `drop_if_busy`
+
+## Tests
+
+- `tests/test_telemetry_collector.py`
+  - 12 testów
+  - mockuje `cpu_count`
+
+- `tests/test_frame_dispatcher.py`
+  - 8 testów
+
+## Repo / Docs
+
+- `.gitignore`
+  - zawiera `logs/`
+
+- `notes/01-mvp-preview.md`
+  - PRD
+
+- `notes/01-mvp-plan.md`
+  - plan implementacji
+
+- `notes/02-mvp-app.md`
+  - stan aplikacji
+  - historia prób i decyzji architektonicznych

notes/04-mvp-uvc.md

@@ -0,0 +1,368 @@
+# Stan projektu po sesji: UVC controls + przebudowa menu formatu
+
+## Kontekst
+
+Aplikacja uruchomiona na docelowym Mac Mini. Kamera ELP dostarcza klatki w formacie NV12 (przez backend AVFoundation). Stare menu z osobnymi podmenu `Resolution` i `FPS` nie nadawało się do użycia — kamera eksponuje formaty jako kombinacje (rozdzielczość + fps + pixel format), a ich niezależne ustawianie dawało nieskoordynowane wyniki.
+
+Dodano też interfejs do kontroli parametrów obrazu kamery.
+
+---
+
+## Zmiany w tej sesji
+
+### 1. Menu formatu — przebudowane (`app/ui/menu_bar.py`)
+
+**Przed:** dwa osobne podmenu — `Video → Resolution` i `Video → FPS`.
+
+**Po:** jedno podmenu `Video → Resolution` z pozycjami reprezentującymi pełny format:
+
+```
+1920×1080 @ 30fps (NV12)
+1920×1080 @ 30fps (MJPG)
+1280×720 @ 30fps (NV12)
+1280×720 @ 5fps (YUY2)
+640×480 @ 30fps (MJPG)
+...
+```
+
+Każda pozycja odpowiada dokładnie jednemu `CameraFormat` z `CameraInfo.formats`. Kolejność odzwierciedla sortowanie z `CameraEnumerator` (największa powierzchnia → najwyższe fps).
+
+**Sygnały:**
+
+- Usunięto: `resolution_selected(int, int)`, `fps_selected(float)`
+- Dodano: `format_selected(CameraFormat)` — emituje pełny obiekt formatu
+- Dodano: `camera_settings_requested()` — otwiera dialog ustawień
+
+**Metody publiczne:**
+
+- `populate_formats(camera_info)` — zamiast `populate_resolutions` + `populate_fps`
+- `set_active_format(fmt)` — zaznacza aktywny format po zmianie (matching po w/h/fps/pixel_format)
+- Usunięto: `set_console_level()` (przeniesione do wewnętrznego `_on_log_toggled`)
+
+**Nowe menu `Image`:**
+
+```
+Image
+  └── Camera Settings…   → otwiera CameraSettingsDialog
+```
+
+---
+
+### 2. CameraService — `set_format()` (`app/camera/camera_service.py`)
+
+**Przed:** dwie metody `set_resolution(w, h)` i `set_fps(fps)` przechowujące `_desired_width`, `_desired_height`, `_desired_fps` osobno.
+
+**Po:** jedna metoda `set_format(fmt: CameraFormat)` przechowująca `_desired_fmt: CameraFormat | None`.
+
+```python
+def set_format(self, fmt: CameraFormat) -> None:
+    self._desired_fmt = fmt
+    if self._current_info is not None:
+        self.start(self._current_info)   # stop+start jak poprzednio
+```
+
+**Scoring przy wyborze formatu Qt (`_apply_format`):**
+
+Poprzednio scoringował tylko rozdzielczość i fps. Teraz uwzględnia też pixel format:
+
+```python
+exact_res  = int(w == desired.width and h == desired.height) * 1000
+exact_pf   = int(pf == desired.pixel_format) * 500
+exact_fps  = int(abs(f - desired.max_fps) < 0.5) * 100
+area_diff  = abs(w * h - desired.width * desired.height)
+score      = exact_res + exact_pf + exact_fps - area_diff
+```
+
+Pixel format jest drugim co do ważności kryterium (po rozdzielczości, przed fps).
+
+**Nowa właściwość:**
+
+```python
+@property
+def qt_camera(self) -> QCamera | None:
+    ...
+```
+
+Udostępnia wewnętrzny `QCamera` dla `CameraSettingsDialog` (potrzebny do ustawiania WB i exposure przez Qt API).
+
+**Poprawione logowanie:**
+
+`_log_actual_format()` loguje teraz ostrzeżenia zarówno dla FPS jak i rozdzielczości jeśli kamera nie dostarczyła tego co było żądane.
+
+---
+
+### 3. Warstwa UVC (`app/camera/uvc/`)
+
+Nowy pakiet z abstrakcją dla sterowania parametrami obrazu przez UVC (USB Video Class).
+
+#### Dlaczego osobna warstwa, nie Qt?
+
+`QCamera.Feature` w Qt6 obejmuje: `ColorTemperature`, `ExposureCompensation`, `IsoSensitivity`, `ManualExposureTime`, `CustomFocusPoint`, `FocusDistance`. **Nie obejmuje** brightness, contrast, saturation, hue, sharpness, gamma, backlight compensation — są to niskopoziomowe UVC/V4L2 controls poza zakresem Qt Multimedia.
+
+Sterowanie nimi wymaga osobnych bibliotek natywnych, innych na każdej platformie.
+
+#### Dostępne biblioteki
+
+| Biblioteka | Platforma | Instalacja | Uwagi |
+|---|---|---|---|
+| `duvc-ctl` | Windows only | `pip install duvc-ctl` | DirectShow, stabilna, PyPI, MIT |
+| `pyuvc` | macOS + Linux | `brew install libusb jpeg-turbo && pip install pyuvc` | libuvc bindings, wymaga kompilacji |
+| `uvc-py` | macOS + Linux (Win w planie) | `pip install uvc-py` | dev/alpha, brak UVC controls |
+
+#### Struktura
+
+```
+app/camera/uvc/
+├── __init__.py      # make_uvc_controller(name) — factory z detekcją platformy
+├── base.py          # UvcControllerBase ABC, UvcParam enum, UvcParamInfo dataclass
+├── stub.py          # NullUvcController — no-op fallback
+├── windows.py       # WindowsUvcController — duvc-ctl (DirectShow)
+└── macos.py         # MacUvcController — pyuvc (libuvc)
+```
+
+#### `UvcParam` enum
+
+```python
+class UvcParam(Enum):
+    BRIGHTNESS
+    CONTRAST
+    SATURATION
+    HUE
+    SHARPNESS
+    GAMMA
+    WHITE_BALANCE
+    BACKLIGHT_COMPENSATION
+    EXPOSURE
+```
+
+#### `UvcParamInfo` dataclass
+
+```python
+@dataclass
+class UvcParamInfo:
+    param: UvcParam
+    supported: bool
+    minimum: int = 0
+    maximum: int = 100
+    default: int = 50
+    current: int = 50
+    step: int = 1
+    auto_supported: bool = False
+    auto_enabled: bool = False
+```
+
+#### `UvcControllerBase` ABC — interfejs
+
+```python
+def open(self, device_name: str) -> bool     # otwiera uchwyt do urządzenia
+def close(self) -> None
+def is_open(self) -> bool
+def get_param_info(self, param: UvcParam) -> UvcParamInfo
+def get_all_params(self) -> list[UvcParamInfo]
+def set_value(self, param: UvcParam, value: int) -> bool
+def set_auto(self, param: UvcParam, enabled: bool) -> bool
+```
+
+#### `make_uvc_controller(device_name)` — factory
+
+Detekcja platformy w runtime:
+
+```python
+if system == "Windows":
+    → WindowsUvcController (duvc-ctl)
+elif system == "Darwin":
+    → MacUvcController (pyuvc)
+else:
+    → NullUvcController
+```
+
+Jeśli biblioteka nie jest zainstalowana — `ImportError` przechwycony, fallback na `NullUvcController`. Loguje `WARNING` z instrukcją instalacji.
+
+#### `WindowsUvcController` — szczegóły
+
+- Łączy się z pierwszym urządzeniem którego nazwa zawiera `device_name` (case-insensitive)
+- Mapowanie `UvcParam → duvc-ctl VidProp/CamProp` string:
+  - `BRIGHTNESS → "brightness"`, `CONTRAST → "contrast"`, ..., `EXPOSURE → "exposure"`
+- `set_auto()` używa `duvc.CamMode.AUTO/MANUAL`
+- `_refresh_supported()` odpytuje `cam.get_supported_properties()` po otwarciu
+
+#### `MacUvcController` — szczegóły
+
+- Używa `uvc.device_list()` do wyszukania urządzenia po nazwie
+- Otwiera przez `uvc.Capture(uid)`
+- Mapowanie `UvcParam → pyuvc display_name` string:
+  - `WHITE_BALANCE → "White Balance temperature"`, `EXPOSURE → "Absolute Exposure Time"`, itd.
+- `auto_mode` via `ctrl.auto_mode` (atrybut pyuvc control)
+
+---
+
+### 4. CameraSettingsDialog (`app/ui/camera_settings_dialog.py`)
+
+`QDialog` ze scrollowaną zawartością, dwoma sekcjami. Zmiany aplikowane **na żywo** (brak OK/Apply — tylko Close).
+
+#### Sekcja Qt Camera Controls
+
+| Kontrolka | Widget | Akcja |
+|---|---|---|
+| White Balance | `QComboBox` (8 trybów + Manual) | `camera.setWhiteBalanceMode()` |
+| Colour Temp (K) | `QSpinBox` 2000–10000, krok 100 | `camera.setColorTemperature()` — widoczny tylko w trybie Manual |
+| Exposure Mode | `QComboBox` (Auto / Manual) | `camera.setExposureMode()` |
+| Exposure Time (s) | `QDoubleSpinBox`, 6 miejsc po przecinku | `camera.setManualExposureTime()` — widoczny tylko w trybie Manual |
+
+Dynamiczna widoczność: pola `Colour Temp` i `Exposure Time` pojawiają się tylko gdy wybrano tryb Manual.
+
+Tryby WB sprawdzane przez `camera.isWhiteBalanceModeSupported()` przed aplikacją — jeśli kamera nie obsługuje trybu, zmiana jest ignorowana (logowane DEBUG).
+
+#### Sekcja UVC Camera Controls
+
+Dla każdego `UvcParam`:
+
+- Jeśli `supported=False`: wyświetla "Not supported" (disabled)
+- Jeśli `supported=True`: `QSlider` + `QSpinBox` zsynchronizowane dwukierunkowo
+- Jeśli `auto_supported=True`: dodatkowy `QCheckBox "Auto"` — po zaznaczeniu blokuje slider i spinbox
+
+Jeśli `NullUvcController` (żadne kontrolki nieobsługiwane): sekcja wyświetla notatkę:
+
+```
+UVC controls not available.
+Install duvc-ctl (Windows) or pyuvc (macOS) to enable.
+```
+
+---
+
+### 5. MainWindow — aktualizacje (`app/ui/main_window.py`)
+
+**Nowe pola:**
+
+```python
+self._uvc: UvcControllerBase = NullUvcController()
+```
+
+**Nowe metody:**
+
+- `_open_uvc(cam)` — zamyka poprzedni UVC controller i otwiera nowy dla wybranej kamery
+- `_on_format_selected(fmt)` → `camera_service.set_format(fmt)`
+- `_on_settings_requested()` → tworzy `CameraSettingsDialog(qt_camera, uvc)` i wywołuje `.exec()`
+
+**Zmiany w `_wire_signals()`:**
+
+- Usunięto: `menu.resolution_selected`, `menu.fps_selected`
+- Dodano: `menu.format_selected → _on_format_selected`
+- Dodano: `menu.camera_settings_requested → _on_settings_requested`
+
+**`closeEvent`:**
+
+- Dodano: `self._uvc.close()` jeśli `is_open()`
+
+---
+
+### 6. Testy (`tests/test_uvc.py`) — nowy plik, 15 testów
+
+| Klasa testowa | Co testuje |
+|---|---|
+| `TestNullUvcController` | `open` → False, `is_open` → False, `close` bez wyjątku, `get_param_info` → unsupported, `get_all_params` zwraca wszystkie `UvcParam`, `set_value`/`set_auto` → False bez wyjątku |
+| `TestUvcParamInfo` | wartości domyślne dataclass, flaga `supported=False`, custom range |
+| `TestMakeUvcControllerFallback` | zwraca instancję `UvcControllerBase`, fallback na stub gdy `ImportError` |
+
+Łącznie testów: **35** (20 poprzednich + 15 nowych), wszystkie zielone.
+
+---
+
+## Decyzje architektoniczne
+
+### Dlaczego `set_format()` zamiast osobnych `set_resolution`/`set_fps`?
+
+Kamera ELP przez AVFoundation eksponuje formaty jako niepodzielne kombinacje `(W × H, fps, pixel_format)`. Próba niezależnej zmiany rozdzielczości bez zmiany fps (i odwrotnie) prowadziła do niespójnych stanów — kamera ignorowała jedną z wartości albo wybierała domyślny format. Jeden `CameraFormat` jako atomowa jednostka wyboru eliminuje problem.
+
+### Dlaczego warstwowa architektura UVC a nie jedna biblioteka?
+
+Brak cross-platform biblioteki Python dla UVC controls. `duvc-ctl` — Windows only (DirectShow), `pyuvc` — macOS/Linux (libuvc). Warstwa abstrakcji z platformową detekcją w runtime pozwala:
+- Działać bez żadnej biblioteki (NullUvcController — grayed-out w UI)
+- Dodać obsługę nowej platformy bez zmiany warstwy wyżej
+- Testować logikę UI niezależnie od dostępności sprzętu
+
+### Dlaczego Qt controls i UVC controls w jednym dialogu?
+
+WB i exposure są dostępne przez oba API (Qt i UVC). Qt API jest wyżej poziomowe (tryby, EV), UVC daje surowe wartości rejestrów. Użytkownik widzi jedno spójne miejsce — nie musi wiedzieć przez które API co działa.
+
+---
+
+## Pliki zmienione / dodane
+
+### Zmienione
+
+| Plik | Co zmieniono |
+|---|---|
+| `app/ui/menu_bar.py` | Przebudowa menu: `format_selected` zamiast `resolution_selected`+`fps_selected`, nowe menu Image |
+| `app/camera/camera_service.py` | `set_format()` zamiast `set_resolution`/`set_fps`, `qt_camera` property, lepsza walidacja w `_log_actual_format` |
+| `app/ui/main_window.py` | UVC lifecycle, nowe sygnały menu, `_on_settings_requested` |
+
+### Dodane
+
+| Plik | Co zawiera |
+|---|---|
+| `app/camera/uvc/__init__.py` | `make_uvc_controller()` factory |
+| `app/camera/uvc/base.py` | `UvcControllerBase`, `UvcParam`, `UvcParamInfo` |
+| `app/camera/uvc/stub.py` | `NullUvcController` |
+| `app/camera/uvc/windows.py` | `WindowsUvcController` (duvc-ctl) |
+| `app/camera/uvc/macos.py` | `MacUvcController` (pyuvc) |
+| `app/ui/camera_settings_dialog.py` | `CameraSettingsDialog` |
+| `tests/test_uvc.py` | 15 testów UVC layer |
+
+---
+
+## Instalacja bibliotek UVC
+
+### Mac Mini (cel docelowy)
+
+```bash
+brew install libusb jpeg-turbo
+pip install pyuvc
+```
+
+### Windows (dev)
+
+```bash
+pip install duvc-ctl
+```
+
+### Bez bibliotek
+
+Aplikacja działa normalnie — sekcja UVC w `CameraSettingsDialog` wyświetla komunikat o braku biblioteki. Qt controls (WB, Exposure) działają niezależnie od UVC.
+
+---
+
+## Next Steps
+
+1. Przetestować na Mac Mini z kamerą ELP:
+   - czy `MacUvcController` otwiera urządzenie po `pip install pyuvc`
+   - czy slidery zmieniają rzeczywiste parametry kamery
+   - czy `Camera Settings…` poprawnie pokazuje zakresy dla ELP (np. brightness 0–255)
+
+2. Sprawdzić czy AVFoundation na macOS honoruje `setCameraFormat` bez stop+start (Qt docs mówią że na macOS inny proces może nadpisać format — `_log_actual_format` oznaczy to jako warning)
+
+3. Dodać `set_active_format()` call po `_log_actual_format()` żeby menu zaznaczało faktycznie działający format (nie żądany)
+
+4. Rozważyć `QSlider` z etykietą wartości min/max/default w dialogu — aktualnie są tylko slider + spinbox
+
+5. (Opcjonalnie) Preset systemu: zapisz/wczytaj ustawienia do JSON per kamera
+
+---
+
+## Critical Context
+
+- `CameraService.qt_camera` → `QCamera | None` — potrzebny do `CameraSettingsDialog`, jest `None` gdy kamera zatrzymana
+- `make_uvc_controller(name)` zwraca **już otwarty lub próbujący otworzyć** kontroler; `MainWindow._open_uvc()` nie wywołuje `.open()` ponownie jeśli `is_open()` zwróci True
+- `MacUvcController` używa `uvc.device_list()` (pyuvc API) — wymaga że kamera **nie jest** aktywnie używana przez inny proces (ograniczenie libusb na macOS)
+- `WindowsUvcController` działa **równolegle** z Qt — DirectShow pozwala na jednoczesny dostęp do controls i streamu
+- Testy UVC nie wymagają sprzętu ani bibliotek natywnych — `NullUvcController` jest czystym Pythonem
+
+## Uruchamianie
+
+```bash
+# Windows dev
+.venv-win\Scripts\python.exe -m app.main
+
+# Mac Mini (po instalacji pyuvc)
+.venv/bin/python -m app.main
+```

notes/05-mvp-yolo.md

@@ -0,0 +1,505 @@
+# Stan projektu po sesji: YOLO inference + odtwarzanie wideo
+
+Poprzedni stan: `04-mvp-uvc.md`
+
+---
+
+## Kontekst
+
+Po uruchomieniu aplikacji na Mac Mini z kamerą ELP, kolejny krok to weryfikacja
+wytrenowanego modelu YOLO. Wymagania:
+
+- Model działa w **osobnym procesie** — crash workera nie wywala GUI
+- Inference **nie blokuje** i **nie spowalnia** podglądu kamery
+- Worker **ignoruje klatki** dopóki analizuje poprzednią (drop-if-busy)
+- Możliwość wczytania **pliku wideo** zamiast kamery do oceny modelu
+- Bbox narysowany na nowej **warstwie overlay**
+- W przyszłości OCR będzie działał w tym samym procesie co YOLO
+
+---
+
+## Nowe pakiety
+
+### `app/video/`
+
+```
+app/video/
+├── __init__.py
+└── video_player.py
+```
+
+### `app/inference/`
+
+```
+app/inference/
+├── __init__.py
+├── worker.py           # funkcja uruchamiana w subprocess
+├── worker_manager.py   # InferenceManager (QObject) — IPC, polling, auto-restart
+└── bbox_overlay.py     # BboxOverlay(IOverlayLayer) — rysuje bbox+label+conf
+```
+
+---
+
+## Szczegółowy opis zmian
+
+### 1. `app/video/video_player.py` — `VideoPlayer`
+
+Nowa klasa `VideoPlayer(QObject)` — identyczny interfejs sygnałowy jak `CameraService`:
+
+```python
+frame_ready     = Signal(QVideoFrame)
+playback_started = Signal()
+playback_stopped = Signal()
+playback_error   = Signal(str)
+```
+
+Wewnętrznie: `QMediaPlayer` + `QVideoSink`. Obsługuje formaty: `.mp4`, `.avi`,
+`.mov`, `.mkv`, `.m4v`, `.webm` (cokolwiek obsługuje FFmpeg backend Qt).
+
+Odtwarzanie w czasie rzeczywistym (1×). Brak seek/pauzy — tylko Open + Stop.
+
+`MainWindow` podłącza do `FrameDispatcher` albo `CameraService.frame_ready`,
+albo `VideoPlayer.frame_ready` — nigdy obu naraz. Przełączanie przez
+`_switch_to_camera()` / `_switch_to_video()`.
+
+---
+
+### 2. `app/inference/worker.py` — worker process
+
+#### Struktury IPC (NamedTuple — pickle-safe)
+
+```python
+class FramePacket(NamedTuple):
+    frame_id: int
+    raw_bytes: bytes    # RGB, (H×W×3)
+    width: int
+    height: int
+    channels: int       # zawsze 3
+
+class WorkerReadyPacket(NamedTuple):
+    device: str         # "cpu" | "mps" — wysyłany raz po załadowaniu modelu
+
+class ResultPacket(NamedTuple):
+    frame_id: int
+    detections: list    # list of (x1, y1, x2, y2, conf, label)
+    width: int
+    height: int
+    elapsed_ms: float   # czas wywołania model() w ms
+```
+
+#### Protokół IPC
+
+```
+input_queue  ← FramePacket
+output_queue → WorkerReadyPacket  (raz, zaraz po załadowaniu modelu)
+             → ResultPacket       (po każdej analizowanej klatce)
+             → None               (tylko przy błędzie ładowania modelu)
+```
+
+#### `_select_device()` — wybór urządzenia
+
+Wywoływany **raz przy starcie workera** (nie per-frame jak wcześniej):
+
+```python
+def _select_device() -> str:
+    if platform.system() == "Darwin":
+        if torch.backends.mps.is_available():
+            return "mps"   # Metal GPU na macOS
+    return "cpu"
+```
+
+`device` jest przekazywany do `_load_model()` i do każdego wywołania `_infer()`.
+Eliminuje redundantne wykrywanie urządzenia przy każdej klatce.
+
+#### `_infer()` — pomiar czasu
+
+```python
+t0 = time.perf_counter()
+results = model(frame_np, device=device, verbose=False)
+elapsed_ms = (time.perf_counter() - t0) * 1000.0
+```
+
+`elapsed_ms` trafia do `ResultPacket` i jest logowany w managerze przy detekcjach.
+
+---
+
+### 3. `app/inference/worker_manager.py` — `InferenceManager`
+
+#### Sygnały
+
+```python
+detections_ready      = Signal(object, object)  # list[Detection], tuple[int,int]
+detection_count_updated = Signal(int)           # łączna liczba klatek z detekcją
+inference_stats_updated = Signal(str, float)    # device, avg_elapsed_ms
+inference_device_changed = Signal(str)          # emitowany raz po WorkerReadyPacket
+inference_started     = Signal()
+inference_stopped     = Signal()
+inference_error       = Signal(str)
+```
+
+#### Mechanizm drop-if-busy
+
+```python
+def submit_frame(self, frame: QVideoFrame) -> None:
+    if not self.is_running or self._paused or self._busy:
+        return   # klatka odrzucona cicho
+    # konwersja + put_nowait → self._busy = True
+```
+
+`self._busy` wraca do `False` dopiero gdy `_poll_output()` odbierze `ResultPacket`.
+Gwarantuje że nigdy nie ma więcej niż jedna klatka w locie.
+
+#### Konwersja klatki w GUI thread
+
+Zamiast `frame.bits(0)` (dawało tylko płaszczyznę Y dla NV12):
+
+```python
+image = frame.toImage()                           # Qt dekoduje NV12/YUV/MJPG → RGB
+image = image.convertToFormat(Format_RGB32)       # packed BGRX
+arr = np.frombuffer(image.bits(), dtype=np.uint8).reshape((H, W, 4))
+rgb = arr[:, :, [2, 1, 0]].copy()                # BGRX → RGB, drop X
+```
+
+Obsługuje każdy pixel format jaki kamera może dostarczyć.
+
+#### Rolling average elapsed_ms
+
+```python
+_elapsed_window: deque[float]  # maxlen=10
+avg_ms = sum(_elapsed_window) / len(_elapsed_window)
+```
+
+Emitowany przez `inference_stats_updated(device, avg_ms)` po każdym `ResultPacket`.
+
+#### `_poll_output()` — obsługa `WorkerReadyPacket`
+
+```python
+if isinstance(item, WorkerReadyPacket):
+    self._current_device = item.device
+    self.inference_device_changed.emit(item.device)
+    continue
+```
+
+Odróżnienie od `ResultPacket` przez `isinstance` — nie wymaga sentinel wartości.
+
+#### Auto-restart
+
+- Watchdog co 2s sprawdza `process.is_alive()`
+- Timeout 10s bez odpowiedzi → terminate + restart
+- Max 3 restartów (konfigurowalny przez `INFERENCE_MAX_RESTARTS`)
+- Po przekroczeniu: `QMessageBox.critical` + overlay wyłączony
+
+#### Logowanie — tylko detekcje
+
+```python
+if detections:
+    logger.info(
+        "frame %d: %d detection(s) in %.1f ms — %s",
+        packet.frame_id, len(detections), packet.elapsed_ms, conf_summary,
+    )
+```
+
+Klatki bez detekcji: brak logu. `conf_summary = "label 0.94, label 0.81"`.
+
+---
+
+### 4. `app/inference/bbox_overlay.py` — `BboxOverlay`
+
+```python
+class Detection(NamedTuple):
+    x1: float; y1: float; x2: float; y2: float
+    conf: float
+    label: str
+```
+
+Współrzędne w pikselach **oryginalnej klatki**. `paint()` skaluje do `video_rect`:
+
+```python
+scale_x = video_rect.width() / src_w
+scale_y = video_rect.height() / src_h
+wx1 = video_rect.x() + int(det.x1 * scale_x)
+# ...
+```
+
+Każdy bbox: prostokąt w kolorze `BBOX_COLOR` + label `"label 0.87"` na tle
+`BBOX_LABEL_BG_COLOR` nad lewym górnym rogiem boxa (lub wewnątrz gdy brakuje miejsca).
+
+`BboxOverlay.visible = False` domyślnie — pojawia się dopiero po włączeniu inference toggle.
+
+---
+
+### 5. Menu — zmiany w `app/ui/menu_bar.py`
+
+Dodano dwa nowe menu przed istniejącymi:
+
+```
+File
+  ├── Open Video…         QFileDialog (.mp4 .avi .mov .mkv .m4v .webm)
+  └── Close Video         disabled gdy źródło = kamera
+
+Model
+  ├── Load Model…         QFileDialog (.pt .pth)
+  ├── Enable Inference    QAction checkable, disabled do momentu załadowania modelu
+  └── Model: (none)       disabled — info o załadowanym pliku
+```
+
+Nowe sygnały:
+- `video_file_selected(str)` — ścieżka pliku wideo
+- `video_closed()` — powrót do kamery
+- `model_file_selected(str)` — ścieżka modelu
+- `inference_toggled(bool)` — włącz/wyłącz inference
+
+---
+
+### 6. `app/ui/main_window.py` — integracja
+
+#### Przełączanie źródła klatek
+
+```python
+def _switch_to_camera(self):
+    video_player.frame_ready.disconnect(dispatcher.dispatch)
+    camera_service.frame_ready.connect(dispatcher.dispatch)
+
+def _switch_to_video(self):
+    camera_service.frame_ready.disconnect(dispatcher.dispatch)
+    video_player.frame_ready.connect(dispatcher.dispatch)
+```
+
+Dispatcher i wszyscy subskrybenci (CameraView, TelemetryCollector,
+InferenceManager) są podłączeni do dispatchera — źródło klatek jest dla nich
+transparentne.
+
+#### Inference toggle
+
+```python
+def _on_inference_toggled(self, enabled: bool):
+    if enabled:
+        inference.resume()
+        dispatcher.subscribe(inference.submit_frame, drop_if_busy=True)
+        bbox_overlay.visible = True
+        detection_label.setVisible(True)
+    else:
+        inference.pause()
+        dispatcher.unsubscribe(inference.submit_frame)
+        bbox_overlay.clear()
+        bbox_overlay.visible = False
+        detection_label.setVisible(False)
+        telemetry.clear_inference_stats()
+```
+
+`pause()` nie zatrzymuje procesu — tylko blokuje `submit_frame`. Proces
+pozostaje załadowany w pamięci.
+
+#### Status bar — counter detekcji
+
+```python
+self._detection_label = QLabel("")   # addPermanentWidget (prawa strona)
+```
+
+Pokazywany tylko gdy inference włączone. Aktualizowany przez
+`inference.detection_count_updated(int)` → `"Detections: 17 frames"`.
+
+---
+
+### 7. Telemetria + overlay — nowe pola inference
+
+#### `TelemetrySnapshot` — nowe pola
+
+```python
+@dataclass
+class TelemetrySnapshot:
+    # ... istniejące pola ...
+    inference_device: str | None = None    # "cpu" | "mps" | None
+    inference_time_ms: float | None = None  # rolling avg, None gdy wyłączone
+```
+
+#### `TelemetryCollector` — nowe metody
+
+```python
+def set_inference_stats(self, device: str, avg_ms: float) -> None: ...
+def clear_inference_stats(self) -> None: ...
+```
+
+Wywoływane z `MainWindow` przy każdym `inference_stats_updated` i przy
+wyłączeniu inference.
+
+#### `TelemetryOverlay` — nowe wiersze
+
+```
+FPS req   30.0
+FPS got   29.8
+Frame     33.5 ms
+Drop         0
+CPU sys    8.2 %
+CPU core  65.7 %
+Mem        71 MB
+Inf.dev    mps        ← widoczny tylko gdy model załadowany
+Inf.time   87 ms      ← rolling avg ostatnich 10 klatek
+```
+
+Wiersze `Inf.dev` i `Inf.time` znikają gdy inference jest wyłączone
+(`clear_inference_stats()` → pola `None` → `_format_lines` ich nie emituje).
+
+---
+
+### 8. Bugfixes (zidentyfikowane po uruchomieniu)
+
+#### `Unexpected frame size: 921600 bytes for 1280×720`
+
+**Przyczyna:** `frame.bits(0)` zwraca tylko płaszczyznę 0 (luma Y) dla formatów
+planarnych NV12/YUV420P — `1280 × 720 × 1 = 921600` zamiast `1280 × 720 × 3`.
+
+**Naprawa:** zamiana na `frame.toImage() → Format_RGB32 → bits()`. Qt dekoduje
+każdy format wewnętrznie. Identyczna ścieżka jak `CameraView.on_frame()`.
+
+#### `Subscriber not found for removal` (WARNING w logu)
+
+**Przyczyna:** `_on_inference_toggled(False)` wywoływał `dispatcher.unsubscribe()`
+zanim subscriber był dodany (pierwsze wyłączenie przed włączeniem).
+
+**Naprawa:** zmiana poziomu logu z `WARNING` na `DEBUG` w
+`FrameDispatcher.unsubscribe()` — brak subscribera nie jest błędem.
+
+---
+
+## Decyzje architektoniczne
+
+### Osobny proces zamiast wątku
+
+`multiprocessing.Process(context="spawn")` zamiast `QThread` lub `threading.Thread`:
+- Osobny GIL — inference nie blokuje Python event loop GUI
+- Crash workera (segfault, OOM) nie wywala aplikacji
+- `spawn` zamiast `fork` — wymagane na macOS od Python 3.12 (Apple deprecuje `fork`)
+
+### `toImage()` zamiast `bits(0)`
+
+`QVideoFrame.bits(plane)` daje surowe bajty jednej płaszczyzny. W formatach
+planarnych (NV12: Y w plane 0, UV w plane 1) to tylko część obrazu. `toImage()`
+wywołuje wewnętrzny dekoder Qt i zawsze zwraca kompletny obraz niezależnie od
+pixel formatu.
+
+### `WorkerReadyPacket` zamiast osobnego IPC kanału
+
+Worker wysyła `WorkerReadyPacket(device)` do tej samej `output_queue` zaraz
+po załadowaniu modelu. Manager odróżnia go przez `isinstance`. Eliminuje
+potrzebę dodatkowej kolejki lub pipe tylko dla metadanych startu.
+
+### Inference stats przez `TelemetryCollector`, nie bezpośrednio do overlay
+
+`InferenceManager.inference_stats_updated` → `MainWindow._on_inference_stats_updated`
+→ `TelemetryCollector.set_inference_stats()` → `TelemetrySnapshot.inference_*`
+→ `TelemetryOverlay.paint()`.
+
+Alternatywa: bezpośrednie połączenie `InferenceManager → TelemetryOverlay`.
+Wybrano pośrednie przez `TelemetryCollector` bo:
+- `TelemetrySnapshot` jest jedyną strukturą danych opisującą stan systemu
+- CSV logger automatycznie dostaje inference stats bez dodatkowego kodu
+- Overlay ma jeden spójny model danych
+
+---
+
+## Pliki dodane
+
+| Plik | Zawartość |
+|---|---|
+| `app/video/__init__.py` | pusty |
+| `app/video/video_player.py` | `VideoPlayer(QObject)` |
+| `app/inference/__init__.py` | pusty |
+| `app/inference/worker.py` | `run_worker()`, `FramePacket`, `WorkerReadyPacket`, `ResultPacket`, `_select_device()`, `_infer()` |
+| `app/inference/worker_manager.py` | `InferenceManager(QObject)` |
+| `app/inference/bbox_overlay.py` | `Detection(NamedTuple)`, `BboxOverlay(IOverlayLayer)` |
+| `tests/test_bbox_overlay.py` | 16 testów — `Detection`, stan overlay, mapowanie współrzędnych bbox |
+| `tests/test_inference_manager.py` | 13 testów — drop-if-busy, pause/resume, restart counter, is_running |
+
+## Pliki zmienione
+
+| Plik | Co zmieniono |
+|---|---|
+| `app/config.py` | `INFERENCE_WORKER_TIMEOUT_S`, `INFERENCE_MAX_RESTARTS`, `INFERENCE_POLL_INTERVAL_MS`, `INFERENCE_WATCHDOG_INTERVAL_MS`, `BBOX_COLOR`, `BBOX_LABEL_BG_COLOR`, `BBOX_LABEL_TEXT_COLOR`, `BBOX_LINE_WIDTH`, `BBOX_FONT_SIZE`, `VIDEO_FILE_EXTENSIONS`, `MODEL_FILE_EXTENSIONS` |
+| `app/ui/menu_bar.py` | Menu `File` (Open Video…, Close Video), menu `Model` (Load Model…, Enable Inference, Model info) |
+| `app/ui/main_window.py` | `VideoPlayer` lifecycle, `InferenceManager` lifecycle, source switching, detection counter w statusbar, `_on_inference_stats_updated` |
+| `app/telemetry/telemetry_collector.py` | `TelemetrySnapshot.inference_device`, `TelemetrySnapshot.inference_time_ms`, `set_inference_stats()`, `clear_inference_stats()` |
+| `app/overlay/telemetry_overlay.py` | Wiersze `Inf.dev` i `Inf.time` w `_format_lines()` |
+| `app/pipeline/frame_dispatcher.py` | `unsubscribe()` brak subscribera: WARNING → DEBUG |
+| `pyproject.toml` | `[project.optional-dependencies] inference = ["ultralytics>=8.0", "numpy>=1.24"]` |
+| `tests/test_telemetry_collector.py` | `_make_collector()` uzupełniony o `_inference_device=None`, `_inference_time_ms=None` |
+
+---
+
+## Łączna liczba testów
+
+**69 testów, wszystkie zielone.**
+
+| Plik | Liczba testów |
+|---|---|
+| `test_frame_dispatcher.py` | 8 |
+| `test_telemetry_collector.py` | 12 |
+| `test_uvc.py` | 15 |
+| `test_bbox_overlay.py` | 16 |
+| `test_inference_manager.py` | 18 |
+
+---
+
+## Instalacja
+
+```bash
+# Wymagane do inference:
+pip install ultralytics numpy
+# lub:
+pip install -e ".[inference]"
+```
+
+Aplikacja startuje bez tych pakietów — `Load Model…` zostaje aktywne, ale
+`InferenceManager.start()` zgłosi błąd jeśli `ultralytics` nie jest zainstalowany
+(obsłużony przez `try/except ImportError` w workerze → `output_queue.put(None)`
+→ manager emituje `inference_error`).
+
+---
+
+## Uruchamianie
+
+```bash
+# Windows dev
+.venv-win\Scripts\python.exe -m app.main
+
+# Mac Mini
+.venv/bin/python -m app.main
+
+# Mac Mini z plikiem wideo od razu (CLI nie zaimplementowany — użyj File → Open Video…)
+.venv/bin/python -m app.main
+```
+
+---
+
+## Next Steps
+
+1. Przetestować na Mac Mini z kamerą ELP:
+   - czy `_select_device()` wykrywa MPS i loguje `"MPS (Metal) available"`
+   - czy `Inf.dev mps` pojawia się w overlayzie
+   - czy `Inf.time` jest znacząco niższy niż na CPU
+
+2. OCR w tym samym procesie co YOLO:
+   - Worker process może obsługiwać wiele zadań — dodać `OcrTask` do `FramePacket`
+   - lub uruchomić OCR jako osobny subscriber `FrameDispatcher` w osobnym procesie
+
+3. Dodać możliwość regulacji progu confidence (`conf_threshold`) przez menu/dialog
+   — przekazać jako parametr do `run_worker()` w `FramePacket` lub przy starcie
+
+4. `set_active_format()` call po `_log_actual_format()` żeby menu zaznaczało
+   faktycznie działający format (nie żądany) — z poprzedniej sesji
+
+---
+
+## Critical Context
+
+- `WorkerReadyPacket` jest rozróżniany od `ResultPacket` przez `isinstance` —
+  nie używaj `None` jako sentinela dla obu typów
+- `_select_device()` wywołany raz przy starcie — jeśli zmienisz device w trakcie
+  działania, trzeba zrestartować workera
+- `BboxOverlay.on_detections(detections, source_size)` — `source_size` to
+  `tuple[int, int]` (width, height) klatki która była inferowana, nie aktualnego
+  widgetu; potrzebne do poprawnego skalowania przy zmianie rozdzielczości
+- `InferenceManager.pause()` nie zatrzymuje procesu — `submit_frame` tylko
+  sprawdza flagę; model pozostaje załadowany, można szybko wznowić
+- `multiprocessing.get_context("spawn")` — wymagane na macOS/Windows;
+  `fork` jest domyślny na Linux ale niebezpieczny z Qt

notes/camera_elp.md

@@ -0,0 +1,182 @@
+# Camera Specification
+
+## Model
+
+**ELP-USB4KHDR01-MFV(5-50)**  
+(10X zoom manual lens)
+
+### Optional
+
+**ELP-USB4KHDR01-MFV(2.8-12)**  
+(2.8-12mm manual zoom lens)
+
+---
+
+## Sensor
+
+- SONY IMX317 (1/2.5”)
+
+## Max Resolution
+
+- 3840(H) × 2160(V)
+
+## Sensitivity
+
+- 1000mV/Lux-sec
+
+## Image Area
+
+- 6100μm × 4524μm
+
+## Picture Format
+
+- MJPEG
+- YUY2 (YUYV)
+
+---
+
+# Resolution & FPS
+
+## MJPEG Modes
+
+| Resolution | FPS |
+|---|---|
+| 3840×2160 | 30 fps |
+| 2592×1944 | 30 fps |
+| 2048×1536 | 30 fps |
+| 1600×1200 | 30 fps |
+| 1920×1080 | 30 fps |
+| 1280×1024 | 30 fps |
+| 1280×960 | 30 fps |
+| 1280×720 | 30 fps |
+| 1024×768 | 30 fps |
+| 800×600 | 30 fps |
+| 640×480 | 30 fps |
+| 320×240 | 30 fps |
+
+## YUY2 Modes
+
+| Resolution | FPS |
+|---|---|
+| 3840×2160 | 1 fps |
+| 2592×1944 | 1 fps |
+| 2048×1536 | 3 fps |
+| 1600×1200 | 3 fps |
+| 1920×1080 | 3 fps |
+| 1280×1024 | 3 fps |
+| 1280×960 | 5 fps |
+| 1280×720 | 5 fps |
+| 1024×768 | 5 fps |
+| 800×600 | 20 fps |
+| 640×480 | 30 fps |
+| 320×240 | 30 fps |
+
+---
+
+## Optical / Image Parameters
+
+| Parameter | Value |
+|---|---|
+| Center Definition | 1000LW/PH (Center) |
+| S/N Ratio | 26dB |
+| Sensitivity | 0.65V/lux-sec@550nm |
+| Low Illumination | 0.2lux |
+| Shutter | Electronic rolling shutter / Frame exposure |
+
+---
+
+## Interface
+
+- USB2.0 High Speed
+
+---
+
+## Supported Features
+
+| Feature | Support |
+|---|---|
+| AEC | Yes |
+| AEB | Yes |
+| AGC | Yes |
+
+---
+
+## Adjustable Parameters
+
+- Brightness
+- Contrast
+- Saturation
+- Hue
+- Sharpness
+- Gamma
+- White Balance
+- Backlight Contrast
+- Exposure
+
+---
+
+## Lens
+
+- 2.8-12mm / 5-50mm varifocal manual lens optional
+
+---
+
+## Audio
+
+- Built-in microphone
+- Supports audio recording
+
+---
+
+## Power
+
+| Parameter | Value |
+|---|---|
+| Power Supply | USB BUS POWER 4P-2.0mm socket |
+| Voltage | DC5V |
+| Current | 200mA |
+
+---
+
+## Physical Dimensions
+
+- 45mm × 45mm × 50mm
+
+---
+
+## Temperature
+
+| Parameter | Value |
+|---|---|
+| Storage Temperature | -20°C to 70°C |
+| Working Temperature | 0°C to 60°C |
+
+---
+
+## USB Cable
+
+- 3M standard
+- Optional: 1M / 2M / 5M
+
+---
+
+# Supported Operating Systems
+
+## Windows
+
+- Windows XP
+- Windows Vista
+- Windows 7
+- Windows 8
+- Windows 10
+- Windows 11
+
+## Linux
+
+- Linux with UVC support
+- Kernel above linux-2.6.26
+
+## macOS / Android
+
+- macOS X 10.4.8 or later
+- Android 4.0 or above with UVC

pyproject.toml

@@ -1,21 +1,51 @@
 [project]
 name = "duck-preview"
 version = "0.1.0"
-description = "Realtime camera preview application with performance monitoring"
+description = "Realtime camera preview application with telemetry"
 requires-python = ">=3.12"
 dependencies = [
-    "PySide6>=6.11",
+    "PySide6>=6.7",
+    "psutil>=6.0",
+]
+
+[project.optional-dependencies]
+# Install inference support: pip install -e ".[inference]"
+# or: pip install ultralytics numpy
+inference = [
+    "ultralytics>=8.0",
+    "numpy>=1.24",
 ]
 
 [project.scripts]
-duck-preview = "duck_preview.app:main"
+duck-preview = "app.main:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v"
 
 [tool.ruff]
 target-version = "py312"
 line-length = 100
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "N", "W"]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "N",   # pep8-naming
+]
+ignore = [
+    "B008",  # do not perform function calls in default arguments
+]
 
-[tool.pytest.ini_options]
+[tool.ruff.lint.isort]
-testpaths = ["tests"]
+known-first-party = ["app"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

pyside6-deploy.toml

@@ -1,6 +0,0 @@
-[app]
-script = "duck_preview/__main__.py"
-name = "Duck Preview"
-bundle_identifier = "com.bartool.duck-preview"
-categories = "public.app-category.photography"
-platforms = ["macos"]

requirements-dev.txt

@@ -0,0 +1,3 @@
+-r requirements.txt
+pytest>=8.0
+ruff>=0.4

requirements.txt

@@ -0,0 +1,2 @@
+PySide6>=6.7
+psutil>=6.0

tests/test_bbox_overlay.py

@@ -0,0 +1,180 @@
+"""Tests for BboxOverlay — coordinate mapping and state management."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+from PySide6.QtCore import QRect, QSize
+
+from app.inference.bbox_overlay import BboxOverlay, Detection
+
+
+class TestDetection:
+    def test_namedtuple_fields(self) -> None:
+        d = Detection(x1=10.0, y1=20.0, x2=100.0, y2=200.0, conf=0.87, label="label")
+        assert d.x1 == 10.0
+        assert d.label == "label"
+        assert d.conf == pytest.approx(0.87)
+
+    def test_immutable(self) -> None:
+        d = Detection(0, 0, 1, 1, 0.5, "x")
+        with pytest.raises(AttributeError):
+            d.conf = 0.9  # type: ignore[misc]
+
+
+class TestBboxOverlayState:
+    def setup_method(self) -> None:
+        self.overlay = BboxOverlay()
+
+    def test_initially_no_detections(self) -> None:
+        assert self.overlay._detections == []
+
+    def test_initially_source_size_empty(self) -> None:
+        assert self.overlay._source_size.isEmpty()
+
+    def test_on_detections_stores_data(self) -> None:
+        dets = [Detection(0, 0, 100, 100, 0.9, "label")]
+        self.overlay.on_detections(dets, (640, 480))
+        assert self.overlay._detections == dets
+        assert self.overlay._source_size == QSize(640, 480)
+
+    def test_clear_removes_detections(self) -> None:
+        self.overlay.on_detections([Detection(0, 0, 10, 10, 0.5, "x")], (100, 100))
+        self.overlay.clear()
+        assert self.overlay._detections == []
+
+    def test_visible_by_default(self) -> None:
+        assert self.overlay.visible is True
+
+    def test_multiple_detections_stored(self) -> None:
+        dets = [
+            Detection(0, 0, 50, 50, 0.9, "label"),
+            Detection(100, 100, 200, 200, 0.75, "label"),
+        ]
+        self.overlay.on_detections(dets, (640, 480))
+        assert len(self.overlay._detections) == 2
+
+    def test_replace_detections_on_new_call(self) -> None:
+        self.overlay.on_detections([Detection(0, 0, 10, 10, 0.5, "x")], (100, 100))
+        self.overlay.on_detections([], (100, 100))
+        assert self.overlay._detections == []
+
+
+class TestBboxOverlayCoordinateMapping:
+    """
+    Verify that BboxOverlay correctly maps source-frame pixel coordinates
+    onto the letterboxed video_rect when painting.
+
+    We don't test actual QPainter output — instead we verify that the
+    QRect values passed to painter.drawRect() correspond to the expected
+    scaled coordinates.
+    """
+
+    def setup_method(self) -> None:
+        self.overlay = BboxOverlay()
+
+    def _make_painter_mock(self):
+        painter = MagicMock()
+        fm = MagicMock()
+        fm.height.return_value = 14
+        fm.ascent.return_value = 11
+        fm.horizontalAdvance.return_value = 60
+        painter.fontMetrics.return_value = fm
+        return painter
+
+    def test_paint_skips_when_no_detections(self) -> None:
+        painter = self._make_painter_mock()
+        self.overlay.paint(painter, QRect(0, 0, 640, 480))
+        painter.drawRect.assert_not_called()
+
+    def test_paint_skips_when_source_size_empty(self) -> None:
+        # detections present but source_size not set
+        self.overlay._detections = [Detection(0, 0, 100, 100, 0.9, "label")]
+        painter = self._make_painter_mock()
+        self.overlay.paint(painter, QRect(0, 0, 640, 480))
+        painter.drawRect.assert_not_called()
+
+    def test_bbox_scaled_to_full_video_rect(self) -> None:
+        """
+        Source: 640×480, covers full frame.
+        video_rect: 640×480 at origin.
+        Detection: full-frame box → should map 1:1.
+        """
+        self.overlay.on_detections(
+            [Detection(0.0, 0.0, 640.0, 480.0, 0.99, "label")],
+            (640, 480),
+        )
+        painter = self._make_painter_mock()
+        video_rect = QRect(0, 0, 640, 480)
+        self.overlay.paint(painter, video_rect)
+
+        # First drawRect call = the bounding box
+        first_call_rect: QRect = painter.drawRect.call_args_list[0][0][0]
+        assert first_call_rect.x() == 0
+        assert first_call_rect.y() == 0
+        assert first_call_rect.width() == 640
+        assert first_call_rect.height() == 480
+
+    def test_bbox_scaled_with_half_size_video_rect(self) -> None:
+        """
+        Source: 640×480, video_rect: 320×240 at origin (0.5× scale).
+        Detection at (64, 48)→(128, 96) should map to (32, 24)→(64, 48).
+        """
+        self.overlay.on_detections(
+            [Detection(64.0, 48.0, 128.0, 96.0, 0.8, "label")],
+            (640, 480),
+        )
+        painter = self._make_painter_mock()
+        video_rect = QRect(0, 0, 320, 240)
+        self.overlay.paint(painter, video_rect)
+
+        first_call_rect: QRect = painter.drawRect.call_args_list[0][0][0]
+        assert first_call_rect.x() == 32
+        assert first_call_rect.y() == 24
+        assert first_call_rect.width() == 32   # (128-64) * 0.5
+        assert first_call_rect.height() == 24  # (96-48) * 0.5
+
+    def test_bbox_offset_by_video_rect_origin(self) -> None:
+        """
+        video_rect at (100, 50) — letterboxed with margins.
+        Detection at origin of source should map to (100, 50).
+        """
+        self.overlay.on_detections(
+            [Detection(0.0, 0.0, 100.0, 100.0, 0.9, "label")],
+            (640, 480),
+        )
+        painter = self._make_painter_mock()
+        # video_rect 320×240 starting at (100, 50)
+        video_rect = QRect(100, 50, 320, 240)
+        self.overlay.paint(painter, video_rect)
+
+        first_call_rect: QRect = painter.drawRect.call_args_list[0][0][0]
+        # x: 100 + int(0 * 320/640) = 100
+        # y:  50 + int(0 * 240/480) =  50
+        assert first_call_rect.x() == 100
+        assert first_call_rect.y() == 50
+
+
+class TestBboxOverlayWorkerPacket:
+    """Test FramePacket and ResultPacket data structures."""
+
+    def test_frame_packet_fields(self) -> None:
+        from app.inference.worker import FramePacket
+        pkt = FramePacket(
+            frame_id=1,
+            raw_bytes=b"\x00" * 12,
+            width=2,
+            height=2,
+            channels=3,
+        )
+        assert pkt.frame_id == 1
+        assert pkt.width == 2
+        assert pkt.channels == 3
+
+    def test_result_packet_fields(self) -> None:
+        from app.inference.worker import ResultPacket
+        pkt = ResultPacket(frame_id=5, detections=[], width=640, height=480)
+        assert pkt.frame_id == 5
+        assert pkt.detections == []
+        assert pkt.width == 640

tests/test_collector.py

@@ -1,22 +0,0 @@
-import time
-from unittest.mock import MagicMock
-
-from duck_preview.telemetry.collector import TelemetryCollector
-
-
-def test_metrics_empty():
-    collector = TelemetryCollector()
-    metrics = collector.metrics()
-    assert metrics == {"fps": 0, "frame_time_ms": 0.0, "frame_count": 0}
-
-
-def test_metrics_after_frames():
-    collector = TelemetryCollector()
-    mock = MagicMock()
-    for _ in range(30):
-        collector.on_frame(mock)
-        time.sleep(0.002)
-
-    metrics = collector.metrics()
-    assert metrics["frame_count"] >= 30
-    assert metrics["frame_time_ms"] > 0

tests/test_dispatcher.py

@@ -1,47 +0,0 @@
-from duck_preview.dispatcher.frame_dispatcher import FrameDispatcher
-
-
-def test_subscribe_notified():
-    dispatcher = FrameDispatcher()
-    received = []
-
-    def cb(frame):
-        received.append(frame)
-
-    dispatcher.subscribe(cb)
-    dispatcher.on_frame("test")
-
-    assert received == ["test"]
-
-
-def test_unsubscribe_not_notified():
-    dispatcher = FrameDispatcher()
-    received = []
-
-    def cb(frame):
-        received.append(frame)
-
-    dispatcher.subscribe(cb)
-    dispatcher.unsubscribe(cb)
-    dispatcher.on_frame("test")
-
-    assert received == []
-
-
-def test_multiple_subscribers():
-    dispatcher = FrameDispatcher()
-    received_1 = []
-    received_2 = []
-
-    def cb1(frame):
-        received_1.append(frame)
-
-    def cb2(frame):
-        received_2.append(frame)
-
-    dispatcher.subscribe(cb1)
-    dispatcher.subscribe(cb2)
-    dispatcher.on_frame("test")
-
-    assert received_1 == ["test"]
-    assert received_2 == ["test"]

tests/test_frame_dispatcher.py

@@ -0,0 +1,76 @@
+"""Tests for FrameDispatcher."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from app.pipeline.frame_dispatcher import FrameDispatcher
+
+
+def _make_frame():
+    frame = MagicMock()
+    frame.isValid.return_value = True
+    return frame
+
+
+class TestFrameDispatcher:
+    def setup_method(self):
+        # FrameDispatcher is a QObject — needs QApplication
+        # Use minimal mock to avoid Qt dependency in unit tests
+        with patch("app.pipeline.frame_dispatcher.QObject.__init__", return_value=None):
+            self.dispatcher = FrameDispatcher.__new__(FrameDispatcher)
+            self.dispatcher._subscribers = []
+            self.dispatcher._frame_count = 0
+            self.dispatcher._last_dispatch_time = 0.0
+
+    def test_subscribe_adds_subscriber(self):
+        cb = MagicMock()
+        self.dispatcher.subscribe(cb)
+        assert self.dispatcher.subscriber_count() == 1
+
+    def test_subscribe_same_callback_twice_is_noop(self):
+        cb = MagicMock()
+        self.dispatcher.subscribe(cb)
+        self.dispatcher.subscribe(cb)
+        assert self.dispatcher.subscriber_count() == 1
+
+    def test_unsubscribe_removes_subscriber(self):
+        cb = MagicMock()
+        self.dispatcher.subscribe(cb)
+        self.dispatcher.unsubscribe(cb)
+        assert self.dispatcher.subscriber_count() == 0
+
+    def test_unsubscribe_nonexistent_does_not_raise(self):
+        cb = MagicMock()
+        self.dispatcher.unsubscribe(cb)  # should not raise
+
+    def test_dispatch_calls_all_subscribers(self):
+        cb1 = MagicMock()
+        cb2 = MagicMock()
+        self.dispatcher.subscribe(cb1)
+        self.dispatcher.subscribe(cb2)
+        frame = _make_frame()
+        self.dispatcher.dispatch(frame)
+        cb1.assert_called_once_with(frame)
+        cb2.assert_called_once_with(frame)
+
+    def test_dispatch_increments_frame_count(self):
+        frame = _make_frame()
+        self.dispatcher.dispatch(frame)
+        self.dispatcher.dispatch(frame)
+        assert self.dispatcher.frame_count == 2
+
+    def test_dispatch_with_no_subscribers_does_not_raise(self):
+        frame = _make_frame()
+        self.dispatcher.dispatch(frame)  # should not raise
+
+    def test_subscriber_exception_does_not_stop_others(self):
+        def bad_cb(f):
+            raise RuntimeError("boom")
+
+        good_cb = MagicMock()
+        self.dispatcher.subscribe(bad_cb)
+        self.dispatcher.subscribe(good_cb)
+        frame = _make_frame()
+        self.dispatcher.dispatch(frame)  # should not raise
+        good_cb.assert_called_once_with(frame)

tests/test_inference_manager.py

@@ -0,0 +1,238 @@
+"""Tests for InferenceManager — drop-if-busy, restart counter, model validation."""
+
+from __future__ import annotations
+
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+from PySide6.QtWidgets import QApplication
+
+from app.inference.worker_manager import InferenceManager
+
+# Ensure a QApplication exists for tests that create Qt objects
+_app = QApplication.instance() or QApplication(sys.argv)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_manager() -> InferenceManager:
+    """Return an InferenceManager without starting any process."""
+    mgr = InferenceManager.__new__(InferenceManager)
+    mgr._model_path = None
+    mgr._process = None
+    mgr._input_queue = None
+    mgr._output_queue = None
+    mgr._stop_event = None
+    mgr._busy = False
+    mgr._frame_id = 0
+    mgr._restart_count = 0
+    mgr._last_result_time = 0.0
+    mgr._paused = False
+    return mgr
+
+
+# ---------------------------------------------------------------------------
+# Model path validation
+# ---------------------------------------------------------------------------
+
+class TestModelPathValidation:
+    def test_start_emits_error_for_missing_file(self, tmp_path) -> None:
+        """start() with non-existent path must NOT spawn a process."""
+        mgr = InferenceManager()
+        errors: list[str] = []
+        mgr.inference_error.connect(errors.append)
+
+        mgr.start(str(tmp_path / "nonexistent.pt"))
+
+        assert errors, "Expected inference_error signal"
+        assert mgr._process is None
+
+    def test_start_does_not_raise_for_existing_file(self, tmp_path) -> None:
+        """start() with existing file should attempt to start (we mock _start_worker)."""
+        model_file = tmp_path / "model.pt"
+        model_file.write_bytes(b"fake")
+
+        mgr = InferenceManager()
+        with patch.object(mgr, "_start_worker") as mock_start:
+            mgr.start(str(model_file))
+            mock_start.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Drop-if-busy logic
+# ---------------------------------------------------------------------------
+
+class TestDropIfBusy:
+    def test_submit_frame_drops_when_busy(self) -> None:
+        """submit_frame must not enqueue when _busy is True."""
+        mgr = _make_manager()
+        mgr._busy = True
+        mgr._process = MagicMock()
+        mgr._process.is_alive.return_value = True
+        mgr._input_queue = MagicMock()
+
+        frame = MagicMock()
+        frame.isValid.return_value = True
+        mgr.submit_frame(frame)
+
+        mgr._input_queue.put_nowait.assert_not_called()
+
+    def test_submit_frame_drops_when_paused(self) -> None:
+        mgr = _make_manager()
+        mgr._paused = True
+        mgr._process = MagicMock()
+        mgr._process.is_alive.return_value = True
+        mgr._input_queue = MagicMock()
+
+        frame = MagicMock()
+        frame.isValid.return_value = True
+        mgr.submit_frame(frame)
+
+        mgr._input_queue.put_nowait.assert_not_called()
+
+    def test_submit_frame_drops_when_not_running(self) -> None:
+        mgr = _make_manager()
+        mgr._process = None
+        mgr._input_queue = MagicMock()
+
+        frame = MagicMock()
+        frame.isValid.return_value = True
+        mgr.submit_frame(frame)
+
+        mgr._input_queue.put_nowait.assert_not_called()
+
+    def test_submit_frame_drops_invalid_frame(self) -> None:
+        mgr = _make_manager()
+        mgr._process = MagicMock()
+        mgr._process.is_alive.return_value = True
+        mgr._input_queue = MagicMock()
+
+        frame = MagicMock()
+        frame.isValid.return_value = False
+        mgr.submit_frame(frame)
+
+        mgr._input_queue.put_nowait.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# Pause / resume
+# ---------------------------------------------------------------------------
+
+class TestPauseResume:
+    def test_pause_sets_flag(self) -> None:
+        mgr = _make_manager()
+        assert mgr._paused is False
+        mgr.pause()
+        assert mgr._paused is True
+
+    def test_resume_clears_flag(self) -> None:
+        mgr = _make_manager()
+        mgr.pause()
+        mgr.resume()
+        assert mgr._paused is False
+
+    def test_is_paused_property(self) -> None:
+        mgr = _make_manager()
+        assert mgr.is_paused is False
+        mgr.pause()
+        assert mgr.is_paused is True
+
+
+# ---------------------------------------------------------------------------
+# Restart counter
+# ---------------------------------------------------------------------------
+
+class TestRestartCounter:
+    def test_handle_crash_increments_counter(self) -> None:
+        mgr = InferenceManager()
+        mgr._model_path = "fake.pt"
+        mgr._restart_count = 0
+
+        with (
+            patch.object(mgr, "_start_worker"),
+            patch.object(mgr._poll_timer, "stop"),
+            patch.object(mgr._watchdog_timer, "stop"),
+        ):
+            mgr._handle_crash("test crash")
+
+        assert mgr._restart_count == 1
+
+    def test_handle_crash_emits_error_after_max_restarts(self) -> None:
+        from app.config import INFERENCE_MAX_RESTARTS
+
+        mgr = InferenceManager()
+        mgr._model_path = "fake.pt"
+        mgr._restart_count = INFERENCE_MAX_RESTARTS
+
+        errors: list[str] = []
+        mgr.inference_error.connect(errors.append)
+
+        with (
+            patch.object(mgr, "_start_worker") as mock_start,
+            patch.object(mgr._poll_timer, "stop"),
+            patch.object(mgr._watchdog_timer, "stop"),
+        ):
+            mgr._handle_crash("final crash")
+
+        assert errors, "Expected inference_error signal after max restarts"
+        mock_start.assert_not_called()
+
+    def test_stop_resets_restart_count(self) -> None:
+        mgr = InferenceManager()
+        mgr._restart_count = 2
+
+        with patch.object(mgr, "_stop_worker"):
+            mgr.stop()
+
+        assert mgr._restart_count == 0
+
+
+# ---------------------------------------------------------------------------
+# is_running property
+# ---------------------------------------------------------------------------
+
+class TestIsRunning:
+    def test_not_running_when_process_is_none(self) -> None:
+        mgr = _make_manager()
+        assert mgr.is_running is False
+
+    def test_not_running_when_process_dead(self) -> None:
+        mgr = _make_manager()
+        proc = MagicMock()
+        proc.is_alive.return_value = False
+        mgr._process = proc
+        assert mgr.is_running is False
+
+    def test_running_when_process_alive(self) -> None:
+        mgr = _make_manager()
+        proc = MagicMock()
+        proc.is_alive.return_value = True
+        mgr._process = proc
+        assert mgr.is_running is True
+
+
+# ---------------------------------------------------------------------------
+# Worker data structures
+# ---------------------------------------------------------------------------
+
+class TestWorkerDataStructures:
+    def test_frame_packet_is_immutable(self) -> None:
+        from app.inference.worker import FramePacket
+        pkt = FramePacket(1, b"", 640, 480, 3)
+        with pytest.raises(AttributeError):
+            pkt.frame_id = 2  # type: ignore[misc]
+
+    def test_result_packet_is_immutable(self) -> None:
+        from app.inference.worker import ResultPacket
+        pkt = ResultPacket(1, [], 640, 480)
+        with pytest.raises(AttributeError):
+            pkt.frame_id = 2  # type: ignore[misc]
+
+    def test_select_device_returns_string(self) -> None:
+        from app.inference.worker import _select_device
+        device = _select_device()
+        assert isinstance(device, str)
+        assert device in ("cpu", "mps", "cuda")

tests/test_telemetry_collector.py

@@ -0,0 +1,142 @@
+"""Tests for TelemetryCollector."""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+from unittest.mock import MagicMock, patch
+
+
+class TestTelemetryCollector:
+    """Test telemetry calculations in isolation (no Qt event loop required)."""
+
+    def _make_collector(self, cpu_count: int = 8):
+        """Construct a TelemetryCollector bypassing Qt machinery."""
+        from app.telemetry.telemetry_collector import TelemetryCollector
+
+        with patch.object(TelemetryCollector, "__init__", return_value=None):
+            col = TelemetryCollector.__new__(TelemetryCollector)
+
+        col._frame_times = deque(maxlen=120)
+        col._last_frame_time = 0.0
+        col._total_frames = 0
+        col._dropped_frames = 0
+        col._fps_window = deque()
+        col._fps_window_size_s = 1.0
+        col._target_fps = None
+        col._cpu_count = cpu_count
+
+        col._process = MagicMock()
+        # Simulate Windows: wset takes priority over rss
+        mem_info = MagicMock()
+        mem_info.wset = 50 * 1024 * 1024   # 50 MB private working set
+        mem_info.rss = 70 * 1024 * 1024    # RSS (larger, includes shared)
+        col._process.memory_info.return_value = mem_info
+        col._process.cpu_percent.return_value = 0.0
+        # Inference stats — None by default (inference disabled)
+        col._inference_device = None
+        col._inference_time_ms = None
+        return col
+
+    def test_initial_snapshot_has_zero_fps(self):
+        col = self._make_collector()
+        snap = col._compute_snapshot()
+        assert snap.fps == 0.0
+
+    def test_fps_counts_frames_in_window(self):
+        col = self._make_collector()
+        now = time.perf_counter()
+        for i in range(30):
+            col._fps_window.append(now - 0.9 + i * 0.03)
+        snap = col._compute_snapshot()
+        assert snap.fps == 30.0
+
+    def test_fps_excludes_old_frames(self):
+        col = self._make_collector()
+        now = time.perf_counter()
+        # 10 frames older than 1 second — should not count
+        for i in range(10):
+            col._fps_window.append(now - 2.0 + i * 0.05)
+        # 5 frames within the last second
+        for i in range(5):
+            col._fps_window.append(now - 0.4 + i * 0.05)
+        snap = col._compute_snapshot()
+        assert snap.fps == 5.0
+
+    def test_frame_time_average(self):
+        col = self._make_collector()
+        interval = 0.0333
+        for _ in range(10):
+            col._frame_times.append(interval)
+        snap = col._compute_snapshot()
+        assert abs(snap.frame_time_ms - interval * 1000) < 0.1
+
+    def test_drop_detection(self):
+        col = self._make_collector()
+        normal_interval = 0.016
+        now = time.perf_counter()
+        col._last_frame_time = now - normal_interval * 10
+        for _ in range(9):
+            col._last_frame_time += normal_interval
+            col._frame_times.append(normal_interval)
+
+        col._last_frame_time = now
+        with patch("app.telemetry.telemetry_collector.time") as mock_time:
+            col._last_frame_time = now
+            big_delta = normal_interval * 5  # 5× average → drop
+            mock_time.perf_counter.return_value = now + big_delta
+            delta = big_delta
+            col._frame_times.append(delta)
+            avg = sum(col._frame_times) / len(col._frame_times)
+            if delta > avg * 2.5:
+                col._dropped_frames += 1
+
+        assert col._dropped_frames == 1
+
+    def test_reset_counters(self):
+        col = self._make_collector()
+        col._total_frames = 100
+        col._dropped_frames = 5
+        col._frame_times.append(0.016)
+        col._fps_window.append(time.perf_counter())
+        col.reset_counters()
+        assert col._total_frames == 0
+        assert col._dropped_frames == 0
+        assert len(col._frame_times) == 0
+        assert len(col._fps_window) == 0
+
+    def test_snapshot_memory_mb(self):
+        col = self._make_collector()
+        snap = col._compute_snapshot()
+        assert snap.memory_mb == 50.0
+
+    def test_cpu_sys_is_core_divided_by_cpu_count(self):
+        col = self._make_collector(cpu_count=8)
+        col._process.cpu_percent.return_value = 80.0  # 80% of one core
+        snap = col._compute_snapshot()
+        assert snap.cpu_percent_core == 80.0
+        assert snap.cpu_percent_sys == round(80.0 / 8, 1)
+
+    def test_cpu_sys_never_exceeds_100_on_single_core_machine(self):
+        col = self._make_collector(cpu_count=1)
+        col._process.cpu_percent.return_value = 95.0
+        snap = col._compute_snapshot()
+        assert snap.cpu_percent_sys == snap.cpu_percent_core == 95.0
+
+    def test_cpu_sys_le_cpu_core(self):
+        """cpu_percent_sys must always be <= cpu_percent_core."""
+        col = self._make_collector(cpu_count=4)
+        col._process.cpu_percent.return_value = 150.0
+        snap = col._compute_snapshot()
+        assert snap.cpu_percent_sys <= snap.cpu_percent_core
+
+    def test_target_fps_none_by_default(self):
+        col = self._make_collector()
+        snap = col._compute_snapshot()
+        assert snap.target_fps is None
+
+    def test_set_target_fps_reflected_in_snapshot(self):
+        col = self._make_collector()
+        col.set_target_fps(60.0)
+        snap = col._compute_snapshot()
+        assert snap.target_fps == 60.0

tests/test_uvc.py

@@ -0,0 +1,117 @@
+"""Tests for the UVC controller abstraction layer."""
+
+from __future__ import annotations
+
+from app.camera.uvc.base import UvcParam, UvcParamInfo
+from app.camera.uvc.stub import NullUvcController
+
+
+class TestNullUvcController:
+    """NullUvcController must implement the full interface, all as no-ops."""
+
+    def setup_method(self) -> None:
+        self.ctrl = NullUvcController()
+
+    def test_is_not_open(self) -> None:
+        assert not self.ctrl.is_open()
+
+    def test_open_returns_false(self) -> None:
+        assert self.ctrl.open("any device") is False
+
+    def test_close_does_not_raise(self) -> None:
+        self.ctrl.close()  # must not raise
+
+    def test_get_param_info_returns_unsupported(self) -> None:
+        info = self.ctrl.get_param_info(UvcParam.BRIGHTNESS)
+        assert isinstance(info, UvcParamInfo)
+        assert info.supported is False
+        assert info.param is UvcParam.BRIGHTNESS
+
+    def test_get_all_params_covers_all_uvc_params(self) -> None:
+        infos = self.ctrl.get_all_params()
+        returned_params = {i.param for i in infos}
+        all_params = set(UvcParam)
+        assert returned_params == all_params
+
+    def test_get_all_params_all_unsupported(self) -> None:
+        for info in self.ctrl.get_all_params():
+            assert info.supported is False
+
+    def test_set_value_returns_false(self) -> None:
+        assert self.ctrl.set_value(UvcParam.CONTRAST, 50) is False
+
+    def test_set_auto_returns_false(self) -> None:
+        assert self.ctrl.set_auto(UvcParam.WHITE_BALANCE, True) is False
+
+    def test_set_value_does_not_raise(self) -> None:
+        for param in UvcParam:
+            self.ctrl.set_value(param, 0)  # must not raise
+
+    def test_set_auto_does_not_raise(self) -> None:
+        for param in UvcParam:
+            self.ctrl.set_auto(param, True)   # must not raise
+            self.ctrl.set_auto(param, False)
+
+
+class TestUvcParamInfo:
+    """UvcParamInfo dataclass sanity checks."""
+
+    def test_defaults(self) -> None:
+        info = UvcParamInfo(param=UvcParam.BRIGHTNESS, supported=True)
+        assert info.minimum == 0
+        assert info.maximum == 100
+        assert info.default == 50
+        assert info.current == 50
+        assert info.step == 1
+        assert info.auto_supported is False
+        assert info.auto_enabled is False
+
+    def test_unsupported_flag(self) -> None:
+        info = UvcParamInfo(param=UvcParam.GAMMA, supported=False)
+        assert info.supported is False
+
+    def test_custom_range(self) -> None:
+        info = UvcParamInfo(
+            param=UvcParam.HUE,
+            supported=True,
+            minimum=-180,
+            maximum=180,
+            default=0,
+            current=-45,
+        )
+        assert info.minimum == -180
+        assert info.maximum == 180
+        assert info.current == -45
+
+
+class TestMakeUvcControllerFallback:
+    """make_uvc_controller falls back to NullUvcController when no lib available."""
+
+    def test_returns_controller_instance(self) -> None:
+        from app.camera.uvc import make_uvc_controller
+        from app.camera.uvc.base import UvcControllerBase
+        ctrl = make_uvc_controller("Test Camera")
+        assert isinstance(ctrl, UvcControllerBase)
+
+    def test_stub_used_when_native_lib_absent(self, monkeypatch) -> None:
+        """If the native import fails, should return NullUvcController."""
+        import builtins
+        real_import = builtins.__import__
+
+        def patched_import(name, *args, **kwargs):
+            if name in ("duvc_ctl", "uvc"):
+                raise ImportError(f"Mocked missing: {name}")
+            return real_import(name, *args, **kwargs)
+
+        monkeypatch.setattr(builtins, "__import__", patched_import)
+        # Re-import to exercise factory with patched import
+        import importlib
+
+        import app.camera.uvc as uvc_pkg
+        importlib.reload(uvc_pkg)
+        ctrl = uvc_pkg.make_uvc_controller("Test Camera")
+        # Should be functional (not raise), may be Null or platform controller
+        from app.camera.uvc.base import UvcControllerBase
+        assert isinstance(ctrl, UvcControllerBase)
+        # Reload back to normal
+        importlib.reload(uvc_pkg)