matebot 0.2.2__tar.gz → 0.3.1__tar.gz

{matebot-0.2.2 → matebot-0.3.1}/AGENTS.md

@@ -43,7 +43,12 @@ The decision tree:
 6. **Optional extras**, in ascending effort: journal repo + GitHub Pages
    (README "Publishing your journal"), dial-in hints (on by default), bean
    bag tracking (`/newbag`, multiple bags, `/tossbag`), smart plug hooks for cold-start `/wake`
-   (README "Smart plug cold start").
+   (README "Smart plug cold start"), shot-video camera module (README
+   "Camera module" — MATEBOT_CAMERA=1, needs ffmpeg + HTTPS in front of the
+   camera page; getUserMedia refuses plain HTTP). Camera shots auto-calibrate
+   their chart-sync offset from the pump's audio onset (calibrate.py) and get
+   a rendered clip+chart "shot reel" sent to the chat (render.py,
+   MATEBOT_REEL=0 to disable; needs matplotlib).
 
 Common failure modes: token/chat id swapped or quoted wrong; bot and machine
 on different networks/VLANs; machine powered off at a dumb power strip;

{matebot-0.2.2 → matebot-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matebot
-Version: 0.2.2
+Version: 0.3.1
 Summary: The proactive companion for GaggiMate espresso machines: post-shot logging bot, .slog decoder, shot-journal site generator
 Project-URL: Homepage, https://github.com/AlexNly/matebot
 Project-URL: Issues, https://github.com/AlexNly/matebot/issues
@@ -159,6 +159,36 @@ MATEBOT_WAKE_HOOK='curl -sf "http://192.168.1.60/relay/0?turn=on"'
 ```
 
 Any shell command works (Home Assistant webhook, `tinytuya`, zigbee2mqtt…).
+NixOS module users: write `%` as `%%` in the hook options — the values pass
+through a systemd unit, which treats single `%` as a specifier.
+
+## Camera module (optional): shot videos synced with the charts
+
+Opt in with `MATEBOT_CAMERA=1` and MATEbot serves a phone-camera page on
+`MATEBOT_CAMERA_PORT` (default 8877). Open it on a phone near the machine,
+allow camera access, and leave the page open — recording starts and stops
+automatically with each shot. Clips are transcoded (720p, with audio),
+committed to the journal repo, and the shot page plays them in sync with the
+curves (scrub the chart, the video follows).
+
+**HTTPS is required** — browsers only grant camera access on secure pages.
+MATEbot itself serves plain HTTP; put it behind whatever TLS you have:
+
+- a reverse proxy with certificates (nginx/caddy/traefik), e.g.
+  `matebot.example.com` → `127.0.0.1:8877` (WebSocket support needed)
+- or zero-config on a tailnet: `tailscale serve https / http://127.0.0.1:8877`
+
+Sync is calibrated automatically: the pump is loud, so MATEbot aligns its
+audio onset in the clip with the pump command in the shot data and writes the
+exact per-shot offset. If a clip has no usable audio the fallback is
+`MATEBOT_CAMERA_OFFSET` (default `-1.0`), and `/vsync +0.5` still nudges any
+shot manually. Videos rotate out after `MATEBOT_VIDEO_KEEP` shots (git
+history keeps every clip recoverable).
+
+After each recorded shot MATEbot also renders a **shot reel** — a portrait
+video with the clip on top and the chart animating below it, playhead
+tracking the x axis — and sends it to the chat (ready for sharing). Disable
+with `MATEBOT_REEL=0`; it needs ffmpeg and the `plots` extra (matplotlib).
 
 ## Configuration
 

{matebot-0.2.2 → matebot-0.3.1}/README.md

@@ -125,6 +125,36 @@ MATEBOT_WAKE_HOOK='curl -sf "http://192.168.1.60/relay/0?turn=on"'
 ```
 
 Any shell command works (Home Assistant webhook, `tinytuya`, zigbee2mqtt…).
+NixOS module users: write `%` as `%%` in the hook options — the values pass
+through a systemd unit, which treats single `%` as a specifier.
+
+## Camera module (optional): shot videos synced with the charts
+
+Opt in with `MATEBOT_CAMERA=1` and MATEbot serves a phone-camera page on
+`MATEBOT_CAMERA_PORT` (default 8877). Open it on a phone near the machine,
+allow camera access, and leave the page open — recording starts and stops
+automatically with each shot. Clips are transcoded (720p, with audio),
+committed to the journal repo, and the shot page plays them in sync with the
+curves (scrub the chart, the video follows).
+
+**HTTPS is required** — browsers only grant camera access on secure pages.
+MATEbot itself serves plain HTTP; put it behind whatever TLS you have:
+
+- a reverse proxy with certificates (nginx/caddy/traefik), e.g.
+  `matebot.example.com` → `127.0.0.1:8877` (WebSocket support needed)
+- or zero-config on a tailnet: `tailscale serve https / http://127.0.0.1:8877`
+
+Sync is calibrated automatically: the pump is loud, so MATEbot aligns its
+audio onset in the clip with the pump command in the shot data and writes the
+exact per-shot offset. If a clip has no usable audio the fallback is
+`MATEBOT_CAMERA_OFFSET` (default `-1.0`), and `/vsync +0.5` still nudges any
+shot manually. Videos rotate out after `MATEBOT_VIDEO_KEEP` shots (git
+history keeps every clip recoverable).
+
+After each recorded shot MATEbot also renders a **shot reel** — a portrait
+video with the clip on top and the chart animating below it, playhead
+tracking the x axis — and sends it to the chat (ready for sharing). Disable
+with `MATEBOT_REEL=0`; it needs ffmpeg and the `plots` extra (matplotlib).
 
 ## Configuration
 

{matebot-0.2.2 → matebot-0.3.1}/flake.nix

@@ -13,7 +13,7 @@
           default = matebot;
           matebot = pkgs.python3Packages.buildPythonApplication {
             pname = "matebot";
-            version = "0.2.2";
+            version = "0.3.1";
             pyproject = true;
             src = self;
             build-system = [ pkgs.python3Packages.hatchling ];
@@ -90,7 +90,7 @@
               wantedBy = [ "multi-user.target" ];
               after = [ "network-online.target" ];
               wants = [ "network-online.target" ];
-              path = [ pkgs.git pkgs.openssh ];
+              path = [ pkgs.git pkgs.openssh pkgs.ffmpeg-headless ];
               environment = {
                 MATEBOT_MACHINE_HOST = cfg.machineHost;
                 MATEBOT_MESSENGER = cfg.messenger;

{matebot-0.2.2 → matebot-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matebot"
-version = "0.2.2"
+version = "0.3.1"
 description = "The proactive companion for GaggiMate espresso machines: post-shot logging bot, .slog decoder, shot-journal site generator"
 readme = "README.md"
 license = "MIT"

matebot-0.3.1/scripts/discord_cmd_smoke.py

@@ -0,0 +1,62 @@
+"""Command-routing smoke test for Discord: /help, /status, /bag as plain text."""
+import asyncio
+import logging
+import os
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent / "src"))
+
+from matebot.commands import CommandRouter, make_frame_cache  # noqa: E402
+from matebot.config import Config  # noqa: E402
+from matebot.messengers.base import TextReply  # noqa: E402
+from matebot.messengers.discord import DiscordMessenger  # noqa: E402
+from matebot.state import State  # noqa: E402
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s: %(message)s")
+log = logging.getLogger("cmdsmoke")
+
+
+class FakeMachine:
+    async def request(self, tp, **f):
+        return {"msg": "Ok"}
+
+    async def send_event(self, tp, **f):
+        log.info("MACHINE would receive: %s %s", tp, f)
+
+
+async def main():
+    messenger = DiscordMessenger(
+        os.environ["DISCORD_BOT_TOKEN"], os.environ["DISCORD_CHANNEL_ID"]
+    )
+    state = State("/tmp/discord-cmd-state.json")
+    state.set("last_shot", {"shot_id": 73, "profile": "Direct Lever v3",
+                            "duration_ms": 42600, "volume_g": 36.4})
+    cache, latest = make_frame_cache()
+    cache({"tp": "evt:status", "m": 0, "ct": 91.2, "tt": 0, "wl": 55})
+    router = CommandRouter(FakeMachine(), state, None, messenger,
+                           Config(journal_url="https://alexnly.github.io/GAGGIMATE-0614/"), latest)
+    await messenger.start()
+    await messenger.send("Command smoke test ready — send /help, /status, /last, /wake as messages.")
+
+    async def pump():
+        handled = 0
+        async for event in messenger.events():
+            log.info("EVENT: %r", event)
+            if isinstance(event, TextReply) and event.text.strip().startswith("/"):
+                consumed = await router.handle(event.text.strip())
+                log.info("router consumed=%s", consumed)
+                handled += 1
+                if handled >= 4:
+                    log.info("✅ command routing works on Discord")
+                    return
+
+    try:
+        await asyncio.wait_for(pump(), timeout=600)
+    except TimeoutError:
+        log.error("timed out")
+    finally:
+        await messenger.stop()
+
+
+asyncio.run(main())

matebot-0.3.1/scripts/discord_smoke.py

@@ -0,0 +1,75 @@
+"""Live smoke test for the Discord messenger backend.
+
+Drives a complete fake-shot questionnaire through real Discord — buttons,
+free-text answers, photo, commands — without needing the machine. Saved
+notes land in a recorder and are printed instead of hitting hardware.
+
+Usage:
+    DISCORD_BOT_TOKEN=... DISCORD_CHANNEL_ID=... python scripts/discord_smoke.py
+"""
+
+import asyncio
+import logging
+import os
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent / "src"))
+
+from matebot.conversation import Conversation  # noqa: E402
+from matebot.messengers.discord import DiscordMessenger  # noqa: E402
+from matebot.state import State  # noqa: E402
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+log = logging.getLogger("smoke")
+
+GOLDEN = pathlib.Path(__file__).parent.parent / "tests" / "fixtures" / "000004.slog"
+
+
+async def main() -> None:
+    messenger = DiscordMessenger(
+        os.environ["DISCORD_BOT_TOKEN"], os.environ["DISCORD_CHANNEL_ID"]
+    )
+    state = State("/tmp/discord-smoke-state.json")
+    saved = {}
+
+    async def save_notes(shot_id, notes):
+        saved[shot_id] = notes
+        log.info("NOTES SAVED for #%s: %s", shot_id, notes)
+        return True
+
+    convo = Conversation(messenger, state, save_notes)
+    await messenger.start()
+    log.info("connected — starting fake questionnaire")
+
+    photo = None
+    try:
+        from matebot.plot import render_shot_png
+        from matebot.slog import parse_slog
+
+        photo = render_shot_png(parse_slog(GOLDEN.read_bytes()), title="Shot #999 — Smoke Test")
+        log.info("photo rendered (%d bytes)", len(photo))
+    except Exception as exc:  # noqa: BLE001
+        log.warning("photo skipped: %s", exc)
+
+    await convo.start_shot(999, "Discord Smoke Test", 31000, 36.2, photo=photo)
+    log.info("questionnaire sent — play it through in Discord (buttons AND typed answers)")
+
+    async def pump():
+        async for event in messenger.events():
+            log.info("EVENT: %r", event)
+            await convo.handle_event(event)
+            if saved:
+                log.info("✅ questionnaire complete — smoke test PASSED")
+                return
+
+    try:
+        await asyncio.wait_for(pump(), timeout=600)
+    except TimeoutError:
+        log.error("timed out waiting for interactions")
+    finally:
+        await messenger.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{matebot-0.2.2 → matebot-0.3.1}/src/matebot/__init__.py

@@ -1,3 +1,3 @@
 """matebot — the proactive companion for GaggiMate espresso machines."""
 
-__version__ = "0.2.2"
+__version__ = "0.3.1"

matebot-0.3.1/src/matebot/calibrate.py

@@ -0,0 +1,90 @@
+"""Auto-calibrate the video/chart sync offset from the pump's audio onset.
+
+A vibratory pump is loud. The moment it kicks in is visible in the shot data
+(``tp`` — target pressure — leaves zero) and audible in the clip, so aligning
+the two gives the exact offset with no manual ``/vsync`` needed:
+
+    offset = t_pump_in_video - t_pump_in_chart
+
+Pure python on 8 kHz mono PCM — no numpy. Returns ``None`` whenever the
+signal is unclear; callers then keep the configured default.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import struct
+from pathlib import Path
+
+from .slog import parse_slog
+
+log = logging.getLogger(__name__)
+
+SAMPLE_RATE = 8000
+WINDOW_S = 0.05
+SUSTAIN_WINDOWS = 6  # onset must stay loud for 0.3 s (a clink won't)
+
+
+async def audio_onset(clip: Path) -> float | None:
+    """Time (s) at which the clip's audio gets loud and stays loud."""
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "ffmpeg", "-hide_banner", "-loglevel", "error", "-i", str(clip),
+            "-vn", "-ac", "1", "-ar", str(SAMPLE_RATE), "-f", "s16le", "pipe:1",
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.DEVNULL,
+        )
+    except FileNotFoundError:
+        return None
+    pcm, _ = await proc.communicate()
+    if proc.returncode != 0 or len(pcm) < SAMPLE_RATE:  # needs ≥0.5 s of audio
+        return None
+    n = len(pcm) // 2
+    samples = struct.unpack(f"<{n}h", pcm[: n * 2])
+    win = int(WINDOW_S * SAMPLE_RATE)
+    rms = [
+        (sum(x * x for x in samples[i : i + win]) / win) ** 0.5
+        for i in range(0, n - win, win)
+    ]
+    if len(rms) < 30:
+        return None
+    head = sorted(rms[:20])
+    base = head[len(head) // 2]  # median of the first second
+    peak = max(rms)
+    if peak < max(base, 1.0) * 4:  # no clear loud event (or mic muted)
+        return None
+    thresh = max(base * 5, peak * 0.25)
+    for i in range(len(rms) - SUSTAIN_WINDOWS):
+        if all(r > thresh for r in rms[i : i + SUSTAIN_WINDOWS]):
+            return round(i * WINDOW_S, 2)
+    return None
+
+
+def pump_start(slog_bytes: bytes) -> float | None:
+    """Time (s) at which the shot data first commands the pump."""
+    shot = parse_slog(slog_bytes)
+    step = shot.sample_interval_ms / 1000
+    for key, thresh in (("tp", 0.1), ("fl", 0.3)):
+        for i, v in enumerate(shot.series.get(key, [])):
+            if v > thresh:
+                return round(i * step, 2)
+    return None
+
+
+async def calibrate_offset(repo: str | Path, shot_id: int) -> float | None:
+    """Offset for the shot's sidecar (video t = chart t + offset), or None."""
+    repo = Path(repo)
+    sid = f"{shot_id:06d}"
+    clip = repo / "shots" / f"{sid}.mp4"
+    slog = repo / "shots" / f"{sid}.slog"
+    if not clip.exists() or not slog.exists():
+        return None
+    t_video = await audio_onset(clip)
+    t_chart = pump_start(slog.read_bytes())
+    if t_video is None or t_chart is None:
+        return None
+    offset = round(t_video - t_chart, 2)
+    if not -5.0 <= offset <= 5.0:  # implausible match, don't trust it
+        log.info("calibration rejected (offset %+.2fs out of range)", offset)
+        return None
+    return offset

matebot-0.3.1/src/matebot/camera.py

@@ -0,0 +1,141 @@
+"""Optional camera module: MATEbot serves a phone-camera page and records shots.
+
+Strictly opt-in (``MATEBOT_CAMERA=1``). The phone opens the page (HTTPS via
+the user's reverse proxy — getUserMedia requires a secure context), grants
+camera access and keeps the page open near the machine. When a shot starts,
+the server tells the page to record; MediaRecorder chunks stream back over
+the WebSocket. When the shot ends (+ a short tail), the clip is transcoded
+and attached to the shot via the video pipeline.
+
+Best-effort by design: no page connected → no recording, no errors.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.resources
+import json
+import logging
+import tempfile
+from pathlib import Path
+
+from aiohttp import WSMsgType, web
+
+log = logging.getLogger(__name__)
+
+TAIL_SECONDS = 5.0
+MAX_RECORD_SECONDS = 240
+
+
+class CameraServer:
+    def __init__(self, port: int, on_clip) -> None:
+        """*on_clip* is ``async (webm_path: Path) -> None`` — called per finished clip."""
+        self.port = port
+        self.on_clip = on_clip
+        self._ws: web.WebSocketResponse | None = None
+        self._chunks: list[bytes] = []
+        self._recording = False
+        self._runner: web.AppRunner | None = None
+        self._stop_task: asyncio.Task | None = None
+
+    # ------------------------------------------------------------ lifecycle
+
+    async def start(self) -> None:
+        app = web.Application()
+        app.router.add_get("/", self._page)
+        app.router.add_get("/ws", self._websocket)
+        self._runner = web.AppRunner(app)
+        await self._runner.setup()
+        site = web.TCPSite(self._runner, "0.0.0.0", self.port)
+        await site.start()
+        log.info("camera server listening on :%d", self.port)
+
+    async def stop(self) -> None:
+        if self._runner:
+            await self._runner.cleanup()
+
+    @property
+    def page_connected(self) -> bool:
+        return self._ws is not None and not self._ws.closed
+
+    # ------------------------------------------------------------ recording
+
+    async def shot_started(self) -> None:
+        if not self.page_connected or self._recording:
+            return
+        self._chunks = []
+        self._recording = True
+        await self._send({"cmd": "start"})
+        log.info("camera: recording started")
+        self._stop_task = asyncio.create_task(self._safety_stop())
+
+    async def shot_ended(self) -> None:
+        if not self._recording:
+            return
+        await asyncio.sleep(TAIL_SECONDS)
+        await self._finish()
+
+    async def _safety_stop(self) -> None:
+        await asyncio.sleep(MAX_RECORD_SECONDS)
+        if self._recording:
+            log.warning("camera: safety stop after %ds", MAX_RECORD_SECONDS)
+            await self._finish()
+
+    async def _finish(self) -> None:
+        if not self._recording:
+            return
+        self._recording = False
+        if self._stop_task and not self._stop_task.done():
+            self._stop_task.cancel()
+        await self._send({"cmd": "stop"})
+        # give the page a moment to flush its final chunks
+        for _ in range(20):
+            await asyncio.sleep(0.25)
+            if not self.page_connected:
+                break
+        chunks, self._chunks = self._chunks, []
+        if not chunks:
+            log.info("camera: no video data received")
+            return
+        with tempfile.NamedTemporaryFile(suffix=".webm", delete=False) as tmp:
+            for chunk in chunks:
+                tmp.write(chunk)
+            path = Path(tmp.name)
+        log.info("camera: clip complete (%.1f MB)", path.stat().st_size / 1e6)
+        try:
+            await self.on_clip(path)
+        finally:
+            path.unlink(missing_ok=True)
+
+    # ------------------------------------------------------------ http
+
+    async def _page(self, request: web.Request) -> web.Response:
+        html = (importlib.resources.files("matebot") / "web_cam" / "index.html").read_text()
+        return web.Response(text=html, content_type="text/html")
+
+    async def _websocket(self, request: web.Request) -> web.WebSocketResponse:
+        ws = web.WebSocketResponse(max_msg_size=8 * 2**20)
+        await ws.prepare(request)
+        if self._ws and not self._ws.closed:
+            await self._ws.close()  # newest page wins
+        self._ws = ws
+        log.info("camera page connected from %s", request.remote)
+        try:
+            async for msg in ws:
+                if msg.type == WSMsgType.BINARY:
+                    if self._recording or self._chunks is not None:
+                        self._chunks.append(msg.data)
+                elif msg.type == WSMsgType.TEXT:
+                    log.debug("camera page: %s", msg.data[:100])
+        finally:
+            if self._ws is ws:
+                self._ws = None
+            log.info("camera page disconnected")
+        return ws
+
+    async def _send(self, payload: dict) -> None:
+        if self.page_connected:
+            try:
+                await self._ws.send_str(json.dumps(payload))
+            except Exception as exc:  # noqa: BLE001
+                log.warning("camera send failed: %s", exc)

{matebot-0.2.2 → matebot-0.3.1}/src/matebot/cli.py

@@ -76,7 +76,10 @@ async def _sync(config: Config) -> int:
         return 1
     async with GaggiMateClient(config.machine_host) as client:
         # WS connection (for profiles) is optional here; HTTP does the rest.
-        pushed = await sync(client, config.data_repo, site_title=config.site_title)
+        pushed = await sync(
+            client, config.data_repo,
+            site_title=config.site_title, video_keep=config.video_keep,
+        )
     print("synced" if pushed else "nothing new")
     return 0
 
@@ -117,7 +120,8 @@ async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
                 asyncio.create_task(
                     sync_soon(
                         client, config.data_repo, messenger.send,
-                        site_title=config.site_title, state=state, quiet=quiet,
+                        site_title=config.site_title, video_keep=config.video_keep,
+                        state=state, quiet=quiet,
                     )
                 )
 
@@ -146,6 +150,81 @@ async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
         convo = Conversation(messenger, state, save_notes)
         cache_frame, latest_frame = make_frame_cache()
         router = CommandRouter(client, state, convo, messenger, config, latest_frame)
+
+        camera = None
+        pending_clip: dict = {"path": None, "ts": 0.0}
+        attach_lock = asyncio.Lock()
+
+        async def try_attach_clip(shot_id: int | None = None) -> None:
+            """Rendezvous: a finished clip and a resolved shot id arrive in
+            either order; whichever side is second completes the attach."""
+            import time as _time
+
+            from .video import VideoError, attach_video, get_offset
+
+            async with attach_lock:
+                clip = pending_clip["path"]
+                if clip is None or _time.monotonic() - pending_clip["ts"] > 300:
+                    return
+                sid = shot_id if shot_id is not None else state.get("last_shot_id")
+                if not sid or get_offset(config.data_repo, sid) is not None:
+                    return  # no shot yet, or it already has a video
+                pending_clip["path"] = None
+                try:
+                    await attach_video(config.data_repo, sid, clip,
+                                       offset=config.camera_offset)
+                    log.info("camera clip attached to shot %06d", sid)
+                    asyncio.create_task(post_video(sid))
+                except VideoError as exc:
+                    log.warning("clip attach failed: %s", exc)
+                    await messenger.send(f"🎬 Couldn't process the shot video: {exc}")
+                finally:
+                    pathlib.Path(clip).unlink(missing_ok=True)
+
+        async def post_video(sid: int) -> None:
+            """After a clip attaches: auto-calibrate its sync offset from the
+            pump's audio onset, then render + send the shot reel."""
+            try:
+                from .calibrate import calibrate_offset
+                from .video import set_offset
+
+                offset = await calibrate_offset(config.data_repo, sid)
+                if offset is not None:
+                    set_offset(config.data_repo, sid, offset)
+                    log.info("shot %06d video offset auto-calibrated to %+.2fs", sid, offset)
+            except Exception as exc:  # noqa: BLE001 - calibration is best-effort
+                log.warning("offset calibration failed: %s", exc)
+            schedule_sync(quiet=True)
+            if not config.reel_enabled:
+                return
+            try:
+                from .render import RenderError, render_reel
+
+                reel = await render_reel(config.data_repo, sid, title=f"Shot #{sid}")
+                try:
+                    await messenger.send_video(reel.read_bytes(), f"🎬 Shot #{sid}")
+                finally:
+                    reel.unlink(missing_ok=True)
+            except RenderError as exc:
+                log.info("no reel for shot %06d: %s", sid, exc)
+            except Exception as exc:  # noqa: BLE001 - never let the reel kill the bot
+                log.warning("reel for shot %06d failed: %s", sid, exc)
+
+        if config.camera_enabled and config.data_repo:
+            import shutil as _shutil
+            import time as _time
+
+            from .camera import CameraServer
+
+            async def on_clip(webm_path):
+                keep = pathlib.Path(config.state_dir) / "pending_clip.webm"
+                _shutil.copy(webm_path, keep)
+                pending_clip["path"] = str(keep)
+                pending_clip["ts"] = _time.monotonic()
+                await try_attach_clip()
+
+            camera = CameraServer(config.camera_port, on_clip)
+            await camera.start()
         # messenger APIs can be flaky at boot; retry instead of crash-looping
         for attempt in range(8):
             try:
@@ -175,16 +254,31 @@ async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
 
                 last_frame_at = 0.0
 
+                shot_active = False
+
                 async def tee(source):
-                    nonlocal last_frame_at
+                    nonlocal last_frame_at, shot_active
                     async for frame in source:
                         now = _time.monotonic()
                         gap = now - last_frame_at if last_frame_at else None
                         last_frame_at = now
-                        if state.get("sync_pending") and (gap is None or gap > 60):
-                            log.info("machine is back; retrying pending journal sync")
-                            state.set("sync_pending", False)  # avoid re-trigger storms
-                            schedule_sync(quiet=True)
+                        if camera is not None and frame.get("tp") == "evt:status":
+                            active = (
+                                frame.get("m") == 1
+                                and (frame.get("process") or {}).get("a") == 1
+                                and not _re.search(config.ignore_profiles, frame.get("p") or "")
+                            )
+                            if active and not shot_active:
+                                await camera.shot_started()
+                            elif shot_active and not active:
+                                asyncio.create_task(camera.shot_ended())
+                            shot_active = active
+                        if gap is None or gap > 60:
+                            await router.on_machine_online(frame)
+                            if state.get("sync_pending"):
+                                log.info("machine is back; retrying pending journal sync")
+                                state.set("sync_pending", False)  # avoid re-trigger storms
+                                schedule_sync(quiet=True)
                         cache_frame(frame)
                         await router.on_frame(frame)
                         yield frame
@@ -247,6 +341,7 @@ async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
                         )
                     except Exception:  # noqa: BLE001 - keep watching even if messaging fails
                         log.exception("questionnaire start failed (state kept for resume)")
+                    await try_attach_clip(shot.entry.id)
                     schedule_sync()  # archive the .slog right away
 
             async def weekly_digest():
@@ -279,6 +374,8 @@ async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
                 if exc:
                     raise exc
         finally:
+            if camera is not None:
+                await camera.stop()
             await messenger.stop()
     return 0