feat(snapshot): generate annotated event snapshots with bounding boxes

Wire snapshot generation into the event flow:
- When a new detection track is confirmed, capture the current frame,
  draw all tracked bounding boxes with color-coded labels, and save
  as JPEG alongside the event
- Add SnapshotConsumer that decodes IDR frames from the main (high-res)
  stream and caches the latest full-resolution frame; event snapshots
  use this when available, falling back to detection resolution
- Scale bounding box coordinates from detection to full resolution
- Save snapshots asynchronously to avoid blocking the detection pipeline
- Fix event snapshot endpoint to serve inline for <img> tags (attachment
  only with ?download=1)
- Add snapshot retention cleanup tied to event_retain_days config
- Remove unused internal/event package (dead code)

Author: rvben

cmd/vedetta/main.go

@@ -70,7 +70,7 @@ func main() {
 
 	slog.Info("native Go media pipeline active (no ffmpeg required)")
 
-	recorder := recording.New(cfg.Recording, db, hub)
+	recorder := recording.New(cfg.Recording, db, hub, cfg.Events.SnapshotPath)
 
 	// Register cameras for recording
 	for _, cam := range cfg.Cameras {
@@ -101,7 +101,7 @@ func main() {
 
 	events := make(chan camera.Event, 100)
 
-	manager := camera.NewManager(cfg.Cameras, detector, events, hub)
+	manager := camera.NewManager(cfg.Cameras, detector, events, hub, cfg.Events.SnapshotPath, cfg.Events.SnapshotQuality)
 	manager.Start(ctx)
 
 	// Periodically publish camera online/offline status to MQTT.

internal/api/server.go

@@ -293,8 +293,11 @@ func (s *Server) handleEventSnapshot(w http.ResponseWriter, r *http.Request) {
 		writeJSON(w, http.StatusNotFound, map[string]string{"error": "snapshot not found"})
 		return
 	}
+	// Use inline disposition for <img> tags; download param triggers attachment
 	filename := fmt.Sprintf("%s_%s.jpg", event.ID, event.Label)
-	w.Header().Set("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"`, filename))
+	if r.URL.Query().Get("download") != "" {
+		w.Header().Set("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"`, filename))
+	}
 	http.ServeFile(w, r, event.SnapshotPath)
 }
 
@@ -728,7 +731,7 @@ func (s *Server) handleEventDetailPartial(w http.ResponseWriter, r *http.Request
 			`{{if .ClipPath}}<a href="/api/events/{{.ID}}/clip" download class="download-row">` +
 			`<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>` +
 			` Download Clip</a>{{end}}` +
-			`{{if .SnapshotPath}}<a href="/api/events/{{.ID}}/snapshot" download class="download-row">` +
+			`{{if .SnapshotPath}}<a href="/api/events/{{.ID}}/snapshot?download=1" download class="download-row">` +
 			`<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>` +
 			` Download Snapshot</a>{{end}}` +
 			`{{if not .ClipPath}}{{if not .SnapshotPath}}<div class="download-row disabled">No media available</div>{{end}}{{end}}` +

internal/api/server_test.go

@@ -24,10 +24,10 @@ func newTestServer(t *testing.T) (*Server, *storage.DB) {
 	}
 	t.Cleanup(func() { _ = db.Close() })
 
-	mgr := camera.NewManager(nil, nil, nil, nil)
+	mgr := camera.NewManager(nil, nil, nil, nil, "", 85)
 	rec := recording.New(config.RecordingConfig{
 		Path: t.TempDir(),
-	}, db, nil)
+	}, db, nil, "")
 
 	apiCfg := config.APIConfig{Host: "127.0.0.1", Port: 0}
 	srv := New(apiCfg, db, mgr, rec, nil)

internal/camera/camera.go

@@ -15,6 +15,7 @@ import (
 	"github.com/rvben/vedetta/internal/detect"
 	"github.com/rvben/vedetta/internal/media"
 	"github.com/rvben/vedetta/internal/rtsp"
+	"github.com/rvben/vedetta/internal/snapshot"
 )
 
 // Event represents a detected object event from a camera.
@@ -36,7 +37,10 @@ type Camera struct {
 	tracker        *detect.Tracker
 	motionDetector *detect.MotionDetector
 	events         chan<- Event
-	hub            *rtsp.Hub
+	hub             *rtsp.Hub
+	eventSnapDir    string
+	eventSnapQuality int
+	snapConsumer    *media.SnapshotConsumer
 
 	mu               sync.RWMutex
 	rawFrame         []byte // RGB24 frame data, guarded by mu
@@ -55,14 +59,19 @@ type CameraStatus struct {
 	LastFrame time.Time `json:"last_frame"`
 }
 
-func NewCamera(cfg config.CameraConfig, detector *detect.Detector, events chan<- Event, hub *rtsp.Hub) *Camera {
+func NewCamera(cfg config.CameraConfig, detector *detect.Detector, events chan<- Event, hub *rtsp.Hub, snapshotPath string, snapshotQuality int) *Camera {
+	if snapshotQuality <= 0 {
+		snapshotQuality = 85
+	}
 	return &Camera{
 		config:          cfg,
 		detector:        detector,
 		tracker:         detect.NewTracker(30, 3),
 		motionDetector:  detect.NewMotionDetector(25, 200, 0.05),
 		events:          events,
 		hub:             hub,
+		eventSnapDir:     snapshotPath,
+		eventSnapQuality: snapshotQuality,
 		confirmedTracks: make(map[int]bool),
 	}
 }
@@ -200,6 +209,9 @@ func (c *Camera) readFrames(ctx context.Context) {
 	source.AddConsumer(consumer)
 	defer source.RemoveConsumer(consumer)
 
+	// Attach snapshot consumer to the main (high-res) stream for event snapshots
+	c.startSnapshotConsumer(ctx)
+
 	for {
 		select {
 		case <-ctx.Done():
@@ -210,6 +222,50 @@ func (c *Camera) readFrames(ctx context.Context) {
 	}
 }
 
+// startSnapshotConsumer attaches a decoder to the main stream that caches
+// the latest full-resolution frame for use in event snapshots.
+func (c *Camera) startSnapshotConsumer(ctx context.Context) {
+	recordURL := c.RecordURL()
+	if recordURL == c.config.URL {
+		// Same stream for detect and record — no benefit from a separate consumer
+		return
+	}
+
+	mainSource := c.hub.GetOrCreate(recordURL)
+
+	// Wait briefly for track info (main stream may already be connected for recording)
+	var videoTrack *rtsp.TrackInfo
+	for i := 0; i < 10; i++ {
+		videoTrack = mainSource.VideoTrack()
+		if videoTrack != nil {
+			break
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-time.After(500 * time.Millisecond):
+		}
+	}
+	if videoTrack == nil {
+		slog.Warn("snapshot consumer: main stream not available", "camera", c.config.Name)
+		return
+	}
+
+	sc := media.NewSnapshotConsumer(c.config.Name, videoTrack)
+	if sc == nil {
+		return
+	}
+
+	c.snapConsumer = sc
+	mainSource.AddConsumer(sc)
+
+	go func() {
+		<-ctx.Done()
+		mainSource.RemoveConsumer(sc)
+		sc.Close()
+	}()
+}
+
 // processFrame handles a decoded RGB24 frame — motion detection + YOLO.
 func (c *Camera) processFrame(buf []byte, w, h int) {
 	frameSize := w * h * 3
@@ -238,18 +294,87 @@ func (c *Camera) processFrame(buf []byte, w, h int) {
 		detections := c.detector.DetectRGB24(buf, w, h)
 		tracked := c.tracker.Update(detections)
 
+		// Collect all current detections for annotation
+		allDetections := make([]detect.Detection, len(tracked))
+		for i, obj := range tracked {
+			allDetections[i] = detect.Detection{
+				Label: obj.Label,
+				Score: obj.Score,
+				Box:   obj.Box,
+			}
+		}
+
+		// Generate one annotated frame with ALL bounding boxes (reused for all new events).
+		// Prefer the full-resolution main stream frame; fall back to the detection frame.
+		var annotatedFrame *image.RGBA
+		if c.eventSnapDir != "" {
+			hasNewTrack := false
+			for _, obj := range tracked {
+				if !c.confirmedTracks[obj.TrackID] {
+					hasNewTrack = true
+					break
+				}
+			}
+			if hasNewTrack {
+				var fullRes *image.RGBA
+				if sc := c.snapConsumer; sc != nil {
+					fullRes = sc.LastFrame()
+				}
+				if fullRes != nil {
+					// Copy so we don't mutate the snapshot consumer's cached frame
+					annotatedFrame = image.NewRGBA(fullRes.Bounds())
+					copy(annotatedFrame.Pix, fullRes.Pix)
+					// Scale detection boxes from detect resolution to full resolution
+					frameW := annotatedFrame.Bounds().Dx()
+					frameH := annotatedFrame.Bounds().Dy()
+					scaled := make([]detect.Detection, len(allDetections))
+					for i, d := range allDetections {
+						scaled[i] = detect.Detection{
+							Label: d.Label,
+							Score: d.Score,
+							Box: [4]int{
+								d.Box[0] * frameW / w,
+								d.Box[1] * frameH / h,
+								d.Box[2] * frameW / w,
+								d.Box[3] * frameH / h,
+							},
+						}
+					}
+					snapshot.DrawDetectionsInPlace(annotatedFrame, scaled)
+				} else {
+					// No full-res frame available, use detection frame
+					annotatedFrame = rawToRGBA(buf, w, h)
+					snapshot.DrawDetectionsInPlace(annotatedFrame, allDetections)
+				}
+			}
+		}
+
 		// Emit events for newly confirmed tracks
 		for _, obj := range tracked {
 			if !c.confirmedTracks[obj.TrackID] {
 				c.confirmedTracks[obj.TrackID] = true
-				c.events <- Event{
-					ID:         fmt.Sprintf("%s-t%d-%d", c.config.Name, obj.TrackID, time.Now().UnixMilli()),
+				eventID := fmt.Sprintf("%s-t%d-%d", c.config.Name, obj.TrackID, time.Now().UnixMilli())
+				ev := Event{
+					ID:         eventID,
 					CameraName: c.config.Name,
 					Label:      obj.Label,
 					Score:      obj.Score,
 					Box:        obj.Box,
 					Timestamp:  time.Now(),
 				}
+
+				if annotatedFrame != nil {
+					snapFile := filepath.Join(c.eventSnapDir, c.config.Name, eventID+".jpg")
+					ev.SnapshotPath = snapFile
+					quality := c.eventSnapQuality
+					go func() {
+						if err := snapshot.SaveSnapshot(annotatedFrame, snapFile, quality); err != nil {
+							slog.Error("failed to save event snapshot", "event", eventID, "error", err)
+						}
+					}()
+				}
+
+				c.events <- ev
 			}
 		}
 

internal/camera/camera_test.go

@@ -12,7 +12,7 @@ func TestSnapshotRGB24_NoFrame(t *testing.T) {
 	cam := NewCamera(config.CameraConfig{
 		Name: "test",
 		Detect: config.StreamConfig{Width: 64, Height: 64, FPS: 5},
-	}, nil, make(chan<- Event, 1), nil)
+	}, nil, make(chan<- Event, 1), nil, "", 85)
 
 	dst := make([]byte, 64*64*3)
 	_, _, ok := cam.SnapshotRGB24(dst)
@@ -25,7 +25,7 @@ func TestSnapshotRGB24_CopiesFrame(t *testing.T) {
 	cam := NewCamera(config.CameraConfig{
 		Name: "test",
 		Detect: config.StreamConfig{Width: 4, Height: 4, FPS: 5},
-	}, nil, make(chan<- Event, 1), nil)
+	}, nil, make(chan<- Event, 1), nil, "", 85)
 
 	frameSize := 4 * 4 * 3
 	frame := make([]byte, frameSize)
@@ -59,7 +59,7 @@ func TestSnapshotRGB24_DstTooSmall(t *testing.T) {
 	cam := NewCamera(config.CameraConfig{
 		Name: "test",
 		Detect: config.StreamConfig{Width: 4, Height: 4, FPS: 5},
-	}, nil, make(chan<- Event, 1), nil)
+	}, nil, make(chan<- Event, 1), nil, "", 85)
 
 	frameSize := 4 * 4 * 3
 	cam.mu.Lock()
@@ -79,7 +79,7 @@ func TestFrameSize(t *testing.T) {
 	cam := NewCamera(config.CameraConfig{
 		Name: "test",
 		Detect: config.StreamConfig{Width: 320, Height: 240, FPS: 5},
-	}, nil, make(chan<- Event, 1), nil)
+	}, nil, make(chan<- Event, 1), nil, "", 85)
 
 	expected := 320 * 240 * 3
 	if got := cam.FrameSize(); got != expected {
@@ -91,7 +91,7 @@ func TestIsOnline_NoHub(t *testing.T) {
 	cam := NewCamera(config.CameraConfig{
 		Name: "test",
 		URL:  "rtsp://localhost/test",
-	}, nil, make(chan<- Event, 1), nil)
+	}, nil, make(chan<- Event, 1), nil, "", 85)
 
 	if cam.IsOnline() {
 		t.Error("expected IsOnline=false with nil hub")
@@ -107,7 +107,7 @@ func TestIsOnline_NoSource(t *testing.T) {
 	cam := NewCamera(config.CameraConfig{
 		Name: "test",
 		URL:  "rtsp://localhost/test",
-	}, nil, make(chan<- Event, 1), hub)
+	}, nil, make(chan<- Event, 1), hub, "", 85)
 
 	// No source created for this URL yet
 	if cam.IsOnline() {
@@ -119,7 +119,7 @@ func TestStatus_NoHub(t *testing.T) {
 	cam := NewCamera(config.CameraConfig{
 		Name: "test",
 		URL:  "rtsp://localhost/test",
-	}, nil, make(chan<- Event, 1), nil)
+	}, nil, make(chan<- Event, 1), nil, "", 85)
 
 	st := cam.Status()
 	if st.Online {

internal/camera/manager.go

@@ -20,7 +20,7 @@ type Manager struct {
 	mu       sync.RWMutex
 }
 
-func NewManager(configs []config.CameraConfig, detector *detect.Detector, events chan<- Event, hub *rtsp.Hub) *Manager {
+func NewManager(configs []config.CameraConfig, detector *detect.Detector, events chan<- Event, hub *rtsp.Hub, snapshotPath string, snapshotQuality int) *Manager {
 	m := &Manager{
 		cameras:  make(map[string]*Camera),
 		detector: detector,
@@ -30,7 +30,7 @@ func NewManager(configs []config.CameraConfig, detector *detect.Detector, events
 
 	for _, cfg := range configs {
 		if cfg.Enabled {
-			cam := NewCamera(cfg, detector, events, hub)
+			cam := NewCamera(cfg, detector, events, hub, snapshotPath, snapshotQuality)
 			m.cameras[cfg.Name] = cam
 		}
 	}