feat: stop the picamera2 capture loop when no consumers

Building on the previous LazyEncoder commit, this commit ref-counts the
Picamera2 instance itself: the camera only runs while at least one
encoder is active. When the last encoder is released, picam2.stop() is
called; on the next consumer, picam2.start() runs again.

Adds a small CameraSession wrapper next to LazyEncoder; each LazyEncoder
takes an optional session and acquires/releases it together with the
underlying encoder, so the camera is the union of the encoders' refs.

Measured CPU impact, applied on top of the previous commit (Raspberry
Pi 4B, Camera Module 3, hardware encoders, sampled with `top`):

  Default config (640x480 @ 15 FPS):
    Idle (no clients):                ~5%  ->  ~0%
    Live MJPEG / WebRTC client:       unchanged

  Heavier config (1920x1080 @ 30 FPS):
    Idle (no clients):               ~15%  ->  ~0%
    Live WebRTC client:              ~60%  (unchanged)

Cumulative effect of both commits at 1080p30:
  Idle:           ~95-100%   ->   ~0%
  Live WebRTC:   ~120-135%   ->  ~60%

Cold-start latency on first connect (camera off -> on -> first JPEG):
~150-500 ms for /snapshot at 1080p30, dominated by libcamera sensor
init and AE/AWB warm-up. The first cold start after process boot is
typically slowest (~500 ms); subsequent cold starts are faster
(~150-200 ms) since some libcamera state appears to be retained.
There is no warm path while no consumers are active: every snapshot
released triggers a full camera stop.

Implementation notes:
- CameraSession.acquire/release are protected by a threading.Lock and
  roll back the refcount if picam2.start() raises, mirroring the
  LazyEncoder pattern.
- LazyEncoder.acquire takes the session ref before calling start_encoder
  so the camera is always running when the encoder starts. release does
  the inverse: stop_encoder first, then drop the session ref. If
  start_encoder fails, the session ref is rolled back too.
- Lock acquisition order is consistent (encoder lock then session lock),
  so two encoders sharing one session cannot deadlock.
- CSI.stop() now defensively calls picam2.stop_encoder() and
  picam2.stop() under try/except, since at systemd shutdown the camera
  may already be stopped (no consumers) and stop_encoder/stop would
  otherwise raise.
- USB camera path is unaffected; only csi.py wires the session in.

All 129 existing unit tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: antoinecellerier

spyglass/camera/csi.py

@@ -5,7 +5,7 @@
 from picamera2.outputs import FileOutput
 
 from spyglass import WEBRTC_ENABLED, camera
-from spyglass.camera.lazy_encoder import LazyEncoder
+from spyglass.camera.lazy_encoder import CameraSession, LazyEncoder
 from spyglass.server.http_server import StreamingHandler
 
 
@@ -42,18 +42,21 @@ def get_frame(inner_self):
                 output.condition.wait()
                 return output.frame
 
+        session = CameraSession(self.picam2)
         StreamingHandler.mjpeg_encoder = LazyEncoder(
-            self.picam2, MJPEGEncoder, FileOutput(output)
+            self.picam2, MJPEGEncoder, FileOutput(output), session=session
         )
         if WEBRTC_ENABLED:
             from picamera2.encoders import H264Encoder
 
             StreamingHandler.h264_encoder = LazyEncoder(
-                self.picam2, H264Encoder, self.media_track
+                self.picam2,
+                H264Encoder,
+                self.media_track,
+                session=session,
             )
         else:
             StreamingHandler.h264_encoder = None
-        self.picam2.start()
 
         self._run_server(
             bind_address,
@@ -67,4 +70,13 @@ def get_frame(inner_self):
         )
 
     def stop(self):
-        self.picam2.stop_recording()
+        # Encoders / camera may already be stopped (no consumers); guard the
+        # systemd shutdown path so we don't error out on that case.
+        try:
+            self.picam2.stop_encoder()
+        except Exception:
+            pass
+        try:
+            self.picam2.stop()
+        except Exception:
+            pass

spyglass/camera/lazy_encoder.py

@@ -1,22 +1,57 @@
-"""Reference-counted lazy start/stop wrapper for picamera2 encoders.
+"""Reference-counted lazy start/stop wrappers for picamera2.
 
-The encoder is only running while at least one consumer holds a reference.
-This avoids burning CPU on encoders that have no clients.
+CameraSession wraps Picamera2.start()/stop(): the camera only runs while
+at least one consumer (encoder) holds a reference.
+
+LazyEncoder wraps Picamera2.start_encoder()/stop_encoder(): the encoder
+only runs while at least one consumer (HTTP stream / snapshot / WebRTC
+peer connection) holds a reference. Each LazyEncoder also holds a
+reference on the CameraSession while running, so the camera itself
+turns off when no encoders are active.
 """
 
 import threading
 
 
+class CameraSession:
+    def __init__(self, picam2):
+        self._picam2 = picam2
+        self._refs = 0
+        self._lock = threading.Lock()
+
+    def acquire(self):
+        with self._lock:
+            self._refs += 1
+            if self._refs == 1:
+                try:
+                    self._picam2.start()
+                except Exception:
+                    self._refs -= 1
+                    raise
+
+    def release(self):
+        with self._lock:
+            if self._refs == 0:
+                return
+            self._refs -= 1
+            if self._refs == 0:
+                self._picam2.stop()
+
+
 class LazyEncoder:
-    def __init__(self, picam2, encoder_factory, output):
+    def __init__(self, picam2, encoder_factory, output, session=None):
         """
         :param picam2: the Picamera2 instance to start/stop the encoder on.
         :param encoder_factory: zero-arg callable returning a fresh Encoder.
         :param output: the picamera2 Output to attach to the encoder.
+        :param session: optional CameraSession. If provided, the camera is
+            started/stopped together with the encoder so the camera only runs
+            when at least one encoder is active.
         """
         self._picam2 = picam2
         self._encoder_factory = encoder_factory
         self._output = output
+        self._session = session
         self._encoder = None
         self._refs = 0
         self._lock = threading.Lock()
@@ -25,13 +60,17 @@ def acquire(self):
         with self._lock:
             self._refs += 1
             if self._refs == 1:
+                if self._session is not None:
+                    self._session.acquire()
                 try:
                     self._encoder = self._encoder_factory()
                     self._picam2.start_encoder(self._encoder, self._output)
                 except Exception:
                     # Roll back so a future caller can retry.
                     self._refs -= 1
                     self._encoder = None
+                    if self._session is not None:
+                        self._session.release()
                     raise
 
     def release(self):
@@ -42,6 +81,8 @@ def release(self):
             if self._refs == 0 and self._encoder is not None:
                 self._picam2.stop_encoder(self._encoder)
                 self._encoder = None
+                if self._session is not None:
+                    self._session.release()
 
     def __enter__(self):
         self.acquire()