Wanyard

Website: https://wanyard.com

RTSP camera capture with an SEI frame clock stamped onto every frame, YOLO object detection, live HLS, and a LAN web viewer.

Quick start

git clone https://github.com/blowhacker/wanyard.git
cd wanyard
docker compose up --build -d

Open http://localhost:8091/settings to add cameras. YOLO model downloads automatically on first run. Docker installs the exact Python package set in requirements.lock; dependency updates should change that file deliberately and pass the full test suite.

For GPU acceleration, copy the override file:

cp docker-compose.gpu.yml docker-compose.override.yml
docker compose up --build -d

What it does

• Stamps Unix time onto each frame as an H.264 SEI clock before recording and detection (codec copy — zero generation loss, archive = camera bits)
• Records stamped camera streams through a persistent RTSP subscription, rotating MP4 storage files without reconnecting at file boundaries
• Serves rolling live HLS streams for browser playback
• Runs live YOLO detection plus MP4 backfill, with detections keyed by clock time
• Live wall (god view) — all cameras at once on the landing page, instant load with near-zero-latency WebRTC; click a camera to open its full viewer
• Web UI: live view, timeline filmstrip, event feed with class filtering, clip export
• Spatial views (experimental) — reconstruct synchronized frames from two or more overlapping cameras as an interactive point cloud, with live colour and PLY export
• Auto-cleanup of old footage by age or disk usage

Spatial views (experimental)

Spatial views require the GPU Compose override, an NVIDIA CUDA GPU, and a VGGT checkpoint. Wanyard does not download that checkpoint automatically because VGGT checkpoints have their own licence terms:

1. Choose a checkpoint from the official VGGT project. The original VGGT-1B checkpoint is non-commercial; use a checkpoint licensed for your intended use.
2. Save the downloaded checkpoint as models/vggt/model.pt.
3. Start Wanyard with docker-compose.gpu.yml, then open http://localhost:8091/spatial.

Select two or more cameras with overlapping coverage, check the connection, and create a view. Geometry is reconstructed on demand; current camera colour can then be projected onto the result. Density presets trade filtering and browser load for more points, up to a two-million-point safety cap at Full density.

VGGT geometry has relative scale. Camera calibration is required before lengths or distances can be interpreted as metric measurements. Sky, reflections, moving subjects, low-texture surfaces, and weak overlap can produce noise or missing geometry.

Architecture

Ingest: camera → go2rtc → mediamtx → stamper → recorder/yolo. go2rtc is the single camera puller; it serves the live wall over WebRTC directly (instant, low latency) while MediaMTX sources from it for stamping and detection — no extra pull from the physical camera.

For each enabled source, the app keeps one archive FFmpeg subscribed to the stamped relay for the lifetime of that relay epoch. FFmpeg's segment muxer rotates crash-tolerant fragmented MP4 files without closing RTSP; sealed files are remuxed to fast-start MP4 and indexed from their decoded SEI frame clocks. A second, isolated FFmpeg produces the clock-aware rolling HLS fallback. An HLS failure therefore cannot block or restart the archive subscriber. Both processes have continuously drained diagnostics and video-progress watchdogs; an archive reconnect happens only after upstream EOF/failure or a real progress stall, never because a storage boundary was reached.

Live detection is a separate subscriber. When an MP4 is sealed, detections are reconciled against its exact stamped-frame clock, so a live detection without corresponding archived pixels is not exposed as retained footage.

Main services in docker-compose.yml:

• app (wanyard) — web server, APIs, persistent archive recording, and clock-aware HLS/MP4 serving
• go2rtc — camera ingest; serves the live wall over WebRTC (WHEP)
• mediamtx — RTSP relay (sources from go2rtc) and native low-latency HLS
• stamper — attaches the SEI frame clock and republishes stamped streams
• yolo (wanyard-yolo) — live detector, thumbnail crops, MP4 backfill

Commands

wanyard serve        # web server, APIs, recording
wanyard stamp        # SEI frame-clock stamper
wanyard yolo-serve   # YOLO live detection + MP4 backfill
wanyard stereo-inspect tapo-front garden-old  # geometry + moving-vehicle timing report

stereo-inspect reads recorded frames and detections only. Its default three-hour timing window looks for up to 30 shared moving vehicles, estimates the right-camera clock offset at 10 ms resolution, and writes a confidence gate, offset plot, paired-vehicle montage, and uncalibrated rectification alongside the geometry report. The rectification validates the shared view but remains projective: lens calibration and a measured baseline are required for metric depth.

Tests

Run the fast unit suite:

python3 -m unittest discover -s tests -v

Run the isolated recorder fault suite with real FFmpeg and MediaMTX processes:

./scripts/test-recorder-faults.sh

The fault suite uses a separate Compose project, synthetic RTSP publishers, temporary databases, and temporary video directories. It does not read camera configuration or production footage.

Web UI

• http://localhost:8091 — live wall (all cameras); click one for its viewer
• http://localhost:8091/detections — object-tag filters and detection thumbnails grouped by camera
• http://localhost:8091/spatial — multi-camera Spatial views, on-demand reconstruction, live colour, and PLY export
• http://localhost:8091/?source=<id>&live=1 — single-camera timeline viewer + event feed
• http://localhost:8091/settings — cameras, detection classes, media health history, notifications, and storage