Watchtower is a cross-platform desktop application built with PySide6 / Qt6 QML for discovering, previewing, and continuously recording from locally attached USB cameras. It enumerates available video capture devices, lets users preview any camera in real time, and records H.264/MPEG-4 video in rolling 15-minute segments. Watchtower automatically purges older recordings based on configurable retention and free-space policies.
- PySide6 >= 6.12.0 — Qt for Python bindings (GUI, multimedia, settings).
- Qt Multimedia —
QMediaDevices,QCamera,QMediaCaptureSession,QMediaRecorder. - QML — Declarative UI (
ui/). - Pydantic >= 2.0.0 — Data models for camera devices and video formats.
- PyInstaller — Windows executable packaging.
- pytest + pytest-qt — Unit and Qt integration tests.
The application is split into three layers:
- QML UI Layer (
ui/*.qml) — The user interface. - QML Bridge (
backend/qml_bridge.py) — Adapts backend objects/signals/slots so they are accessible from QML. - Backend Layer (
backend/*.py) — Managers, workers, and data models that interact with Qt Multimedia and the filesystem.
graph TB
subgraph UI ["QML UI Layer"]
home["ui/home.qml<br/>Main ApplicationWindow"]
device_list["ui/device_list.qml<br/>Reusable camera list"]
camera_device_item["ui/camera_device_item.qml<br/>List item card"]
camera_capture["ui/camera_capture.qml<br/>Preview + record controls"]
recording_popup["ui/recording_popup.qml<br/>Folder picker dialog"]
storage_settings_popup["ui/storage_settings_popup.qml<br/>Purge policy dialog"]
qmldir["ui/qmldir<br/>Module registration"]
end
subgraph Bridge ["QML Bridge"]
qml_bridge["backend/qml_bridge.py<br/>Exposes backend to QML"]
end
subgraph Backend ["Backend Managers"]
device_manager["backend/device_manager.py<br/>Owns device worker thread"]
capture_session_manager["backend/capture_session_manager.py<br/>Owns per-camera capture threads"]
storage_manager["backend/storage_manager.py<br/>Owns storage policy + purge thread"]
end
subgraph Workers ["Backend Workers"]
device_worker["backend/device_worker.py<br/>Enumerate QMediaDevices"]
capture_session_worker["backend/capture_session_worker.py<br/>Run QMediaCaptureSession per camera"]
storage_purge_worker["backend/storage_purge_worker.py<br/>Delete old .mp4 segments"]
end
subgraph Data ["Models"]
models["backend/models.py<br/>MediaDevice, VideoFormat"]
end
main["main.py<br/>Bootstrap + shutdown"]
main --> device_manager
main --> storage_manager
main --> capture_session_manager
main --> qml_bridge
main --> home
device_manager --> device_worker
capture_session_manager --> capture_session_worker
storage_manager --> storage_purge_worker
qml_bridge --> device_manager
qml_bridge --> capture_session_manager
qml_bridge --> storage_manager
home --> device_list
home --> camera_capture
home --> storage_settings_popup
device_list --> camera_device_item
camera_capture --> recording_popup
camera_capture -->|"VideoOutput.videoSink"| capture_session_manager
device_worker -->|"converts to"| models
main.py- Bootstraps the Qt application (
QGuiApplication+QQmlApplicationEngine). - Instantiates
DeviceManager,StorageManager, andCaptureSessionManager. - Creates
QmlBridgeand exposes it to QML as the context propertybridge. - Loads the
ui/homeQML module and connects shutdown cleanup for all background threads.
- Bootstraps the Qt application (
backend/qml_bridge.py- A single
QObjectthat adapts the three backend managers for QML consumption. - Forwards signals such as
videoInputsChanged,errorOccurred,storagePolicyChanged, andstorageCritical. - Exposes properties including
videoInputs,lastRefreshTime,captureManager,storageManager, storage policy values, and disk-usage status. - Provides QML-callable slots:
refreshDevices,saveStoragePolicy,loadStoragePolicy,triggerPurgeNow,setPurgeActiveOnly, and managed-folder edits.
- A single
-
backend/device_manager.py- Owns a dedicated
QThreadrunning aDeviceWorker. - Caches the list of
MediaDevicemodels and the last successful refresh timestamp. - Emits
videoInputsChanged,lastRefreshTimeChanged, anderrorOccurred. - Provides
find_camera_device()so the main thread can resolve adevice_idback to aQCameraDevice. - Wires graceful worker shutdown on app exit.
- Owns a dedicated
-
backend/capture_session_manager.py- Spawns and owns one
CaptureSessionWorkerper detected camera, each on its ownQThread. - Receives
QVideoSinkobjects from QMLVideoOutputand routes them to the correct worker. - Tracks the currently selected camera (
currentDeviceId,cameraActive). - Handles start/stop recording commands, normalizes folder paths, checks free space via
StorageManager, and registers recording folders withStorageManager. - Stops all recording if
StorageManageremitsstorageCritical. - Emits
sessionStarted,sessionStopped,deviceRecordingStateChanged, andsegmentFinalized.
- Spawns and owns one
-
backend/storage_manager.py- Owns the storage purge policy and persists it through
QSettings. - Runs
StoragePurgeWorkeron a backgroundQThreadwith a configurable timer. - Refreshes disk-usage status every 5 seconds and exposes
storageStatusText,storageUsageRatio, andfreeSpaceGb. - Tracks active recording folders and protected (currently writing) files from
CaptureSessionManager. - Emits
policyChanged,storageStatusChanged, andstorageCritical.
- Owns the storage purge policy and persists it through
-
backend/device_worker.py- Lives on the device-manager thread.
- Instantiates
QMediaDeviceson that thread to avoid blocking the GUI during USB enumeration. - Converts native
QCameraDevice/QCameraFormatobjects into PydanticMediaDevice/VideoFormatmodels. - Emits
devicesChangedwith the model list and a UTC timestamp, orerrorOccurredon failure.
-
backend/capture_session_worker.py- One instance per camera, running on its own
QThread. - Builds a
QMediaCaptureSession,QCamera, andQMediaRecorderon the worker thread. - Attaches the
QVideoSinksupplied by QML so the live preview is rendered. - Configures the recorder for H.264/MPEG4 at the camera's best resolution/frame rate.
- Records 15-minute segments, auto-rotating when each segment ends.
- Emits
sessionReady,recordingStateChanged,segmentStarted, andsegmentFinalized.
- One instance per camera, running on its own
-
backend/storage_purge_worker.py- Lives on the storage-manager thread.
- Runs a
QTimerbased on the configured purge interval. - Scans active and/or managed folders for finalized
.mp4files. - Deletes files older than the retention age, then deletes oldest files until the minimum free-space threshold is met.
- Skips files listed as protected (currently being written by an active recording).
- Emits
purgedFilesorpurgeFailed.
Note on multi-volume setups: The storage purge worker currently measures free space against a single root path. If active recording folders and managed folders reside on different volumes, the purge may check free space on one volume while deleting files from another. For now, keep all purged recordings on the same volume, or trigger manual purges with care.
backend/models.py- Defines Pydantic models for the camera data flowing from the backend to the UI.
VideoFormat— resolution, dimensions, frame-rate range, and pixel format.MediaDevice— device ID, description, default flag, photo resolutions, and supported video formats.
-
ui/home.qml- Main
ApplicationWindowcontaining the toolbar, device list, capture preview stack, and error/status area. - Binds to
bridge.videoInputs,bridge.lastRefreshTime, andbridge.captureManager.currentDeviceId. - Displays errors from both the device bridge and the capture manager.
- Main
-
ui/device_list.qml- Reusable scrollable list component.
- Accepts a
devicesarray and aselectedDeviceId. - Emits
deviceSelected(deviceId)when the user clicks a camera.
-
ui/camera_device_item.qml- Visual card rendered for each camera in the list.
- Shows description, default indicator, device ID, photo resolution, and available video formats.
- Highlights when selected.
-
ui/camera_capture.qml- Right-hand preview panel for the selected camera.
- Uses
VideoOutputto display the live feed and registers itsvideoSinkwithCaptureSessionManager. - Shows Record / Stop Recording controls and a red recording indicator.
- Opens
RecordingPopupto choose the output folder.
-
ui/recording_popup.qml- Modal popup that lets the user pick an output folder via a native
FolderDialog. - Emits
startRecording(folderPath)to the parentCameraCapture.
- Modal popup that lets the user pick an output folder via a native
-
ui/storage_settings_popup.qml- Modal popup for configuring minimum free space, maximum retention age, purge interval, and managed folders.
- Reads from and writes to
bridgestorage properties/slots. - Shows a disk-usage progress bar and status text.
-
ui/qmldir- Registers the
uiQML module and maps public component names (DeviceList,CameraCapture, etc.) to their source files.
- Registers the
Run from the project root with uv or your preferred Python environment:
uv run python main.pyRun tests:
uv run pytestBuild a standalone executable with PyInstaller:
uv run pyinstaller watchtower.specThe spec file (watchtower.spec) and pyproject.toml configure the PyInstaller bundle.