feat: implement core functionality for camera preview application

- Add FrameDispatcher for distributing QVideoFrames to subscribers
- Implement TelemetryCollector to measure video pipeline performance metrics
- Create MainWindow as the main application interface with video rendering
- Develop AppMenuBar for camera selection, resolution, and FPS settings
- Establish overlay system for displaying telemetry metrics
- Set up project structure and configuration files
- Add unit tests for FrameDispatcher and TelemetryCollector

app/camera/camera_enumerator.py

@@ -0,0 +1,80 @@
+"""Camera enumeration — discovers available video input devices."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from PySide6.QtMultimedia import QCameraDevice, QMediaDevices
+
+
+@dataclass
+class CameraInfo:
+    """Lightweight descriptor of a detected camera."""
+
+    device: QCameraDevice
+    name: str
+    id: str
+    formats: list[tuple[int, int, float]] = field(default_factory=list)
+    # formats: list of (width, height, max_fps)
+
+    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[tuple[int, int, float]] = []
+            for fmt in device.videoFormats():
+                res = fmt.resolution()
+                fps = fmt.maxFrameRate()
+                formats.append((res.width(), res.height(), fps))
+
+            # deduplicate and sort: largest resolution first, then fps descending
+            seen: set[tuple[int, int, float]] = set()
+            unique_formats: list[tuple[int, int, float]] = []
+            for f in sorted(formats, key=lambda x: (x[0] * x[1], x[2]), reverse=True):
+                if f not in seen:
+                    seen.add(f)
+                    unique_formats.append(f)
+
+            cameras.append(
+                CameraInfo(
+                    device=device,
+                    name=device.description(),
+                    id=device.id().toStdString()
+                    if hasattr(device.id(), "toStdString")
+                    else device.id().data().decode("utf-8", errors="replace"),
+                    formats=unique_formats,
+                )
+            )
+
+        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
+
+        cameras = CameraEnumerator.list_cameras()
+        # find by id match
+        default_id = (
+            device.id().toStdString()
+            if hasattr(device.id(), "toStdString")
+            else device.id().data().decode("utf-8", errors="replace")
+        )
+        for cam in cameras:
+            if cam.id == default_id:
+                return cam
+
+        # fallback: wrap directly
+        return cameras[0] if cameras else None

app/camera/camera_service.py

@@ -0,0 +1,174 @@
+"""Camera Service — manages QCamera lifecycle and frame acquisition."""
+
+from __future__ import annotations
+
+import logging
+
+from PySide6.QtCore import QObject, Signal
+from PySide6.QtMultimedia import (
+    QCamera,
+    QMediaCaptureSession,
+    QVideoFrame,
+    QVideoSink,
+)
+
+from app.camera.camera_enumerator import CameraInfo
+from app.config import DEFAULT_FPS, DEFAULT_HEIGHT, DEFAULT_WIDTH
+
+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
+    """
+
+    frame_ready = Signal(QVideoFrame)
+    camera_started = Signal()
+    camera_stopped = Signal()
+    camera_error = Signal(str)
+
+    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.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()
+
+        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_best_format(camera_info)
+        self._camera.start()
+        logger.info("Camera start requested: %s", camera_info.name)
+
+    def stop(self) -> None:
+        """Stop the current camera."""
+        if self._camera is not None:
+            self._camera.stop()
+            self._camera.errorOccurred.disconnect()
+            self._camera.activeChanged.disconnect()
+            self._camera = None
+            self._current_info = None
+            logger.info("Camera stopped")
+
+    def reconnect(self) -> None:
+        """Restart the current camera 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_resolution(self, width: int, height: int) -> None:
+        """Request a specific resolution. Effective on next start() if camera is active."""
+        if self._camera is None:
+            return
+        self._set_format(width, height, fps=None)
+
+    def set_fps(self, fps: float) -> None:
+        """Request a specific frame rate."""
+        if self._camera is None or self._current_info is None:
+            return
+        # Get current resolution from active format
+        fmt = self._camera.cameraFormat()
+        res = fmt.resolution()
+        self._set_format(res.width(), res.height(), fps=fps)
+
+    @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
+
+    # ------------------------------------------------------------------
+    # Video output accessor for direct QVideoWidget connection
+    # ------------------------------------------------------------------
+
+    def video_sink(self) -> QVideoSink:
+        """Return the internal QVideoSink (used by VideoRenderer)."""
+        return self._sink
+
+    def capture_session(self) -> QMediaCaptureSession:
+        """Return the capture session (can be connected to QVideoWidget directly)."""
+        return self._session
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _apply_best_format(self, info: CameraInfo) -> None:
+        """Pick the best matching format: prefer DEFAULT_WIDTH x DEFAULT_HEIGHT at DEFAULT_FPS."""
+        if not info.formats:
+            return
+        self._set_format(DEFAULT_WIDTH, DEFAULT_HEIGHT, fps=float(DEFAULT_FPS))
+
+    def _set_format(self, width: int, height: int, fps: float | None) -> None:
+        if self._camera is None or self._current_info is None:
+            return
+
+        best = None
+        best_score = -1
+
+        for fmt in self._current_info.device.videoFormats():
+            res = fmt.resolution()
+            w, h = res.width(), res.height()
+            f = fmt.maxFrameRate()
+
+            res_match = int(w == width and h == height) * 1000
+            fps_match = int(fps is not None and abs(f - fps) < 1) * 100
+            area_score = -(abs(w * h - width * height))
+
+            score = res_match + fps_match + area_score
+            if score > best_score:
+                best_score = score
+                best = fmt
+
+        if best is not None:
+            self._camera.setCameraFormat(best)
+            res = best.resolution()
+            logger.info(
+                "Camera format set: %dx%d @ %.1f fps",
+                res.width(),
+                res.height(),
+                best.maxFrameRate(),
+            )
+
+    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:
+            logger.info("Camera active: %s", self._current_info.name if self._current_info else "?")
+            self.camera_started.emit()
+        else:
+            logger.info("Camera inactive")
+            self.camera_stopped.emit()

app/config.py

@@ -0,0 +1,22 @@
+"""Application-wide constants and default settings."""
+
+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

app/main.py

@@ -0,0 +1,35 @@
+"""Application entry point."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QApplication
+
+from app.config import APP_NAME
+from app.ui.main_window import MainWindow
+
+
+def main() -> None:
+    # Basic logging — WARNING by default; Debug menu toggles to DEBUG
+    logging.basicConfig(
+        level=logging.WARNING,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    app = QApplication(sys.argv)
+    app.setApplicationName(APP_NAME)
+    app.setHighDpiScaleFactorRoundingPolicy(
+        Qt.HighDpiScaleFactorRoundingPolicy.PassThrough
+    )
+
+    window = MainWindow()
+    window.show()
+
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()

app/overlay/overlay_widget.py

@@ -0,0 +1,126 @@
+"""Overlay Widget — transparent layer rendered above the video preview."""
+
+from __future__ import annotations
+
+from PySide6.QtCore import QRect, Qt, Slot
+from PySide6.QtGui import QColor, QFont, QPainter, QPen
+from PySide6.QtWidgets import QWidget
+
+from app.config import (
+    OVERLAY_BG_COLOR,
+    OVERLAY_FONT_SIZE,
+    OVERLAY_MARGIN,
+    OVERLAY_PADDING,
+    OVERLAY_TEXT_COLOR,
+)
+from app.telemetry.telemetry_collector import TelemetrySnapshot
+
+
+class OverlayWidget(QWidget):
+    """
+    Semi-transparent performance metrics overlay.
+
+    Sits on top of the video widget (same parent, raised).
+    Does NOT intercept mouse events — clicks pass through to the video widget.
+
+    Usage:
+        overlay = OverlayWidget(parent=main_window)
+        telemetry_collector.metrics_updated.connect(overlay.update_metrics)
+    """
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+
+        # Make widget transparent to mouse and visual background
+        self.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents, True)
+        self.setAttribute(Qt.WidgetAttribute.WA_NoSystemBackground, True)
+        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground, True)
+        self.setWindowFlags(Qt.WindowType.FramelessWindowHint)
+
+        self._snapshot: TelemetrySnapshot | None = None
+        self._visible_overlay: bool = True
+
+        # Font
+        self._font = QFont("Monospace")
+        self._font.setStyleHint(QFont.StyleHint.TypeWriter)
+        self._font.setPointSize(OVERLAY_FONT_SIZE)
+        self._font.setBold(False)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @Slot(object)
+    def update_metrics(self, snapshot: TelemetrySnapshot) -> None:
+        """Receive a new telemetry snapshot and trigger a repaint."""
+        self._snapshot = snapshot
+        if self._visible_overlay:
+            self.update()
+
+    def set_overlay_visible(self, visible: bool) -> None:
+        self._visible_overlay = visible
+        self.update()
+
+    def toggle_overlay(self) -> None:
+        self.set_overlay_visible(not self._visible_overlay)
+
+    # ------------------------------------------------------------------
+    # Qt painting
+    # ------------------------------------------------------------------
+
+    def paintEvent(self, event) -> None:  # noqa: N802
+        if not self._visible_overlay or self._snapshot is None:
+            return
+
+        lines = self._format_lines(self._snapshot)
+        if not lines:
+            return
+
+        painter = QPainter(self)
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing, False)
+        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 = OVERLAY_MARGIN
+        y = OVERLAY_MARGIN
+
+        # Background rectangle
+        bg = QColor(*OVERLAY_BG_COLOR)
+        painter.setBrush(bg)
+        painter.setPen(Qt.PenStyle.NoPen)
+        painter.drawRoundedRect(QRect(x, y, box_w, box_h), 6, 6)
+
+        # Text
+        text_color = QColor(*OVERLAY_TEXT_COLOR)
+        painter.setPen(QPen(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
+
+        painter.end()
+
+    # ------------------------------------------------------------------
+    # Private
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _format_lines(snap: TelemetrySnapshot) -> list[str]:
+        lines = [
+            f"FPS    {snap.fps:>6.1f}",
+            f"Frame  {snap.frame_time_ms:>6.1f} ms",
+            f"Drop   {snap.dropped_frames:>6d}",
+            f"CPU    {snap.cpu_percent:>5.1f} %",
+        ]
+        if snap.memory_mb is not None:
+            lines.append(f"Mem    {snap.memory_mb:>5.0f} MB")
+        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.warning("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/telemetry_collector.py

@@ -0,0 +1,171 @@
+"""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
+    frame_time_ms: float          # average inter-frame time in ms
+    dropped_frames: int           # cumulative dropped frames detected
+    cpu_percent: float            # overall CPU usage (0–100)
+    memory_mb: float | None       # RSS memory usage in MB (optional)
+    timestamp: float              # time.perf_counter() when snapshot was taken
+
+
+class TelemetryCollector(QObject):
+    """
+    Frame subscriber that measures pipeline performance.
+
+    Connect to FrameDispatcher:
+        dispatcher.subscribe(collector.on_frame, drop_if_busy=False)
+
+    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
+
+        # 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()  # timestamps of recent frames
+        self._fps_window_size_s: float = 1.0
+
+        # psutil process reference
+        self._process = psutil.Process()
+
+        # periodic snapshot timer
+        self._timer = QTimer(self)
+        self._timer.setInterval(update_interval_ms)
+        self._timer.timeout.connect(self._emit_snapshot)
+        self._timer.start()
+
+        # latest snapshot (available synchronously)
+        self._latest: TelemetrySnapshot = self._make_empty_snapshot()
+
+    # ------------------------------------------------------------------
+    # Frame subscriber callback
+    # ------------------------------------------------------------------
+
+    def on_frame(self, frame: QVideoFrame) -> None:
+        """Called by FrameDispatcher for every frame. Must be fast."""
+        now = time.perf_counter()
+
+        # inter-frame time
+        if self._last_frame_time > 0:
+            delta = now - self._last_frame_time
+            self._frame_times.append(delta)
+
+            # drop detection: if delta > 2.5× the rolling average, count as drop
+            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
+
+        # FPS window
+        self._fps_window.append(now)
+        # prune old entries
+        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 the most recently computed snapshot."""
+        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))  # frames in the last second
+
+        # average frame time
+        if self._frame_times:
+            avg_frame_time_ms = (sum(self._frame_times) / len(self._frame_times)) * 1000.0
+        else:
+            avg_frame_time_ms = 0.0
+
+        # CPU
+        try:
+            cpu = psutil.cpu_percent(interval=None)
+        except Exception:
+            cpu = 0.0
+
+        # memory
+        try:
+            mem_mb = self._process.memory_info().rss / (1024 * 1024)
+        except Exception:
+            mem_mb = None
+
+        return TelemetrySnapshot(
+            fps=round(fps, 1),
+            frame_time_ms=round(avg_frame_time_ms, 2),
+            dropped_frames=self._dropped_frames,
+            cpu_percent=round(cpu, 1),
+            memory_mb=round(mem_mb, 1) if mem_mb is not None else None,
+            timestamp=now,
+        )
+
+    @staticmethod
+    def _make_empty_snapshot() -> TelemetrySnapshot:
+        return TelemetrySnapshot(
+            fps=0.0,
+            frame_time_ms=0.0,
+            dropped_frames=0,
+            cpu_percent=0.0,
+            memory_mb=None,
+            timestamp=time.perf_counter(),
+        )

app/ui/main_window.py

@@ -0,0 +1,170 @@
+"""Main application window."""
+
+from __future__ import annotations
+
+import logging
+
+from PySide6.QtCore import Qt, QTimer
+from PySide6.QtMultimedia import QVideoWidget
+from PySide6.QtWidgets import QLabel, QMainWindow, QSizePolicy, QStatusBar
+
+from app.camera.camera_enumerator import CameraEnumerator, CameraInfo
+from app.camera.camera_service import CameraService
+from app.config import APP_NAME, APP_VERSION
+from app.overlay.overlay_widget import OverlayWidget
+from app.pipeline.frame_dispatcher import FrameDispatcher
+from app.telemetry.telemetry_collector import TelemetryCollector
+from app.ui.menu_bar import AppMenuBar
+
+logger = logging.getLogger(__name__)
+
+
+class MainWindow(QMainWindow):
+    """
+    Top-level application window.
+
+    Wires together:
+        CameraService → FrameDispatcher → TelemetryCollector
+                                        → OverlayWidget (via metrics_updated)
+        CameraService.capture_session → QVideoWidget (direct, zero-copy path)
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+
+        self.setWindowTitle(f"{APP_NAME} v{APP_VERSION}")
+        self.setMinimumSize(640, 480)
+        self.resize(1280, 720)
+
+        # --- Core components ---
+        self._camera_service = CameraService(self)
+        self._dispatcher = FrameDispatcher(self)
+        self._telemetry = TelemetryCollector(parent=self)
+
+        # --- Video widget (central widget) ---
+        self._video_widget = QVideoWidget(self)
+        self._video_widget.setSizePolicy(
+            QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding
+        )
+        self._video_widget.setAspectRatioMode(Qt.AspectRatioMode.KeepAspectRatio)
+        self.setCentralWidget(self._video_widget)
+
+        # Connect camera session to video widget — this is the zero-copy render path
+        self._camera_service.capture_session().setVideoOutput(self._video_widget)
+
+        # --- Overlay ---
+        self._overlay = OverlayWidget(parent=self._video_widget)
+        self._overlay.raise_()
+        self._overlay.resize(self._video_widget.size())
+
+        # --- Menu bar ---
+        self._menu = AppMenuBar(self)
+        self.setMenuBar(self._menu)
+
+        # --- Status bar ---
+        self._status_bar = QStatusBar(self)
+        self.setStatusBar(self._status_bar)
+        self._status_label = QLabel("Initialising…")
+        self._status_bar.addWidget(self._status_label)
+
+        # --- Wire signals ---
+        self._wire_signals()
+
+        # --- Enumerate cameras and start ---
+        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._telemetry.reset_counters()
+        self._camera_service.start(cam)
+        self._menu.set_active_camera(cam)
+        self._status_label.setText(f"Opening: {cam.name}")
+
+    # ------------------------------------------------------------------
+    # Signal wiring
+    # ------------------------------------------------------------------
+
+    def _wire_signals(self) -> None:
+        # CameraService → FrameDispatcher
+        self._camera_service.frame_ready.connect(self._dispatcher.dispatch)
+
+        # FrameDispatcher → TelemetryCollector (never drop for telemetry)
+        self._dispatcher.subscribe(self._telemetry.on_frame, drop_if_busy=False)
+
+        # TelemetryCollector → OverlayWidget
+        self._telemetry.metrics_updated.connect(self._overlay.update_metrics)
+
+        # CameraService 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)
+
+        # Menu signals
+        self._menu.camera_selected.connect(self._on_camera_selected)
+        self._menu.resolution_selected.connect(self._on_resolution_selected)
+        self._menu.fps_selected.connect(self._on_fps_selected)
+        self._menu.reconnect_requested.connect(self._camera_service.reconnect)
+        self._menu.overlay_toggled.connect(self._overlay.set_overlay_visible)
+
+    # ------------------------------------------------------------------
+    # 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)
+
+    # ------------------------------------------------------------------
+    # Menu action slots
+    # ------------------------------------------------------------------
+
+    def _on_camera_selected(self, cam: CameraInfo) -> None:
+        self._start_camera(cam)
+
+    def _on_resolution_selected(self, width: int, height: int) -> None:
+        self._camera_service.set_resolution(width, height)
+
+    def _on_fps_selected(self, fps: float) -> None:
+        self._camera_service.set_fps(fps)
+
+    # ------------------------------------------------------------------
+    # Qt overrides
+    # ------------------------------------------------------------------
+
+    def resizeEvent(self, event) -> None:  # noqa: N802
+        super().resizeEvent(event)
+        # Keep overlay covering the video widget
+        if hasattr(self, "_overlay") and hasattr(self, "_video_widget"):
+            self._overlay.resize(self._video_widget.size())
+
+    def closeEvent(self, event) -> None:  # noqa: N802
+        self._camera_service.stop()
+        super().closeEvent(event)

app/ui/menu_bar.py

@@ -0,0 +1,198 @@
+"""Menu bar — camera, video format, FPS and debug controls."""
+
+from __future__ import annotations
+
+import logging
+
+from PySide6.QtCore import Signal
+from PySide6.QtGui import QAction, QActionGroup
+from PySide6.QtWidgets import QMenuBar, QWidget
+
+from app.camera.camera_enumerator import CameraInfo
+
+logger = logging.getLogger(__name__)
+
+
+class AppMenuBar(QMenuBar):
+    """
+    Application menu bar.
+
+    Signals:
+        camera_selected(CameraInfo)         — user picked a camera
+        resolution_selected(int, int)       — user picked (width, height)
+        fps_selected(float)                 — user picked a target FPS
+        reconnect_requested()               — user hit Reconnect
+        overlay_toggled(bool)               — overlay show/hide
+        log_toggled(bool)                   — console logging on/off
+    """
+
+    camera_selected = Signal(object)        # CameraInfo
+    resolution_selected = Signal(int, int)
+    fps_selected = Signal(float)
+    reconnect_requested = Signal()
+    overlay_toggled = Signal(bool)
+    log_toggled = Signal(bool)
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+
+        self._camera_group: QActionGroup | None = None
+        self._resolution_group: QActionGroup | None = None
+        self._fps_group: QActionGroup | None = None
+        self._cameras: list[CameraInfo] = []
+
+        self._build_menus()
+
+    # ------------------------------------------------------------------
+    # Public API — called after camera enumeration
+    # ------------------------------------------------------------------
+
+    def populate_cameras(self, cameras: list[CameraInfo]) -> None:
+        """Populate the Camera menu with discovered devices."""
+        self._cameras = cameras
+        menu = self._camera_menu
+
+        # Remove existing camera actions (keep Reconnect + separator)
+        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:
+            first = self._camera_group.actions()[0]
+            first.setChecked(True)
+
+    def populate_formats(self, camera_info: CameraInfo) -> None:
+        """Populate Resolution and FPS menus based on a camera's supported formats."""
+        self._populate_resolutions(camera_info)
+        self._populate_fps(camera_info)
+
+    def set_active_camera(self, camera_info: CameraInfo) -> None:
+        """Check the menu item matching camera_info."""
+        if self._camera_group is None:
+            return
+        for action in self._camera_group.actions():
+            if action.data() is camera_info:
+                action.setChecked(True)
+                return
+
+    # ------------------------------------------------------------------
+    # Menu construction
+    # ------------------------------------------------------------------
+
+    def _build_menus(self) -> None:
+        # --- 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")
+        self._fps_menu = self._video_menu.addMenu("FPS")
+
+        # --- 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)
+
+    def _populate_resolutions(self, camera_info: CameraInfo) -> None:
+        self._res_menu.clear()
+        self._resolution_group = QActionGroup(self)
+        self._resolution_group.setExclusive(True)
+
+        seen: set[tuple[int, int]] = set()
+        for w, h, _ in camera_info.formats:
+            key = (w, h)
+            if key in seen:
+                continue
+            seen.add(key)
+            action = QAction(f"{w} × {h}", self)
+            action.setCheckable(True)
+            action.setData((w, h))
+            self._resolution_group.addAction(action)
+            self._res_menu.addAction(action)
+            action.triggered.connect(self._on_resolution_action)
+
+        actions = self._resolution_group.actions()
+        if actions:
+            actions[0].setChecked(True)
+
+    def _populate_fps(self, camera_info: CameraInfo) -> None:
+        self._fps_menu.clear()
+        self._fps_group = QActionGroup(self)
+        self._fps_group.setExclusive(True)
+
+        seen: set[int] = set()
+        for _, _, fps in camera_info.formats:
+            key = round(fps)
+            if key in seen:
+                continue
+            seen.add(key)
+            action = QAction(f"{key} fps", self)
+            action.setCheckable(True)
+            action.setData(float(fps))
+            self._fps_group.addAction(action)
+            self._fps_menu.addAction(action)
+            action.triggered.connect(self._on_fps_action)
+
+        actions = self._fps_group.actions()
+        if actions:
+            actions[0].setChecked(True)
+
+    # ------------------------------------------------------------------
+    # Slots
+    # ------------------------------------------------------------------
+
+    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_resolutions(cam)
+        self._populate_fps(cam)
+
+    def _on_resolution_action(self) -> None:
+        action = self.sender()
+        if action is None:
+            return
+        w, h = action.data()
+        logger.debug("Resolution selected: %dx%d", w, h)
+        self.resolution_selected.emit(w, h)
+
+    def _on_fps_action(self) -> None:
+        action = self.sender()
+        if action is None:
+            return
+        fps: float = action.data()
+        logger.debug("FPS selected: %.1f", fps)
+        self.fps_selected.emit(fps)
+
+    def _on_log_toggled(self, enabled: bool) -> None:
+        level = logging.DEBUG if enabled else logging.WARNING
+        logging.getLogger().setLevel(level)
+        self.log_toggled.emit(enabled)