duck-preview/notes/01-mvp-plan.md

MVP Implementation Plan — Duck Preview

Stack

• Language: Python 3.12
• GUI/Framework: PySide6 6.11 (QtMultimedia + QtWidgets)
• Camera backend: QCamera + QMediaCaptureSession + QVideoSink (native GPU)
• Rendering: QWidget (paintEvent) z QPainter — manual render z QVideoFrame → QImage
• Testing: pytest
• Linting/Formatting: ruff

Architecture

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)

app = QApplication(sys.argv)

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
│   ├── app.py
│   ├── main_window.py
│   ├── camera/
│   │   ├── __init__.py
│   │   └── service.py
│   ├── dispatcher/
│   │   ├── __init__.py
│   │   └── frame_dispatcher.py
│   ├── rendering/
│   │   ├── __init__.py
│   │   ├── video_widget.py
│   │   └── overlay.py
│   └── telemetry/
│       ├── __init__.py
│       └── collector.py
└── tests/
    ├── __init__.py
    ├── test_dispatcher.py
    └── test_collector.py

---

Edge cases / uwagi

• Brak kamer → menu Camera pokazuje "No cameras detected"
• Brak klatek → VideoWidget pokazuje ciemne tło + napis
• Błąd kamery → CameraService emituje error_occurred (na razie tylko log)
• Zamknięcie okna → closeEvent → camera.stop()
• QVideoFrame.toImage() kopiuje dane — akceptowalne dla MVP
• Wszystkie obiekty żyją w main thread — brak problemów z threadingiem