detstream 0.1.0__py3-none-any.whl

detstream/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("detstream")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

detstream/__main__.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+import argparse
+import asyncio
+import logging
+import sys
+from .config import load_config
+from .runner import run
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="detstream")
+    parser.add_argument("--config", required=True, help="path to a YAML/JSON feed config")
+    args = parser.parse_args()
+
+    # Force line buffering so log lines appear as they happen
+    sys.stdout.reconfigure(line_buffering=True)
+    sys.stderr.reconfigure(line_buffering=True)
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+
+    app = load_config(args.config)
+    try:
+        asyncio.run(run(app))
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

detstream/annotate.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+import cv2
+import numpy as np
+from .detectors import Detection
+
+BOX_COLOR = (208, 147, 0)  # BGR (a mid blue)
+BOX_THICKNESS = 3
+
+
+# Draw the detection box and a confidence label onto a copy of the frame. Returns the
+# frame unchanged when there is no box, so it is safe to call on every sampled frame
+def annotate(frame: np.ndarray, detection: Detection, label: str = "") -> np.ndarray:
+    if detection.box is None:
+        return frame
+    out = frame.copy()
+    x1, y1, x2, y2 = (int(v) for v in detection.box)
+    cv2.rectangle(out, (x1, y1), (x2, y2), BOX_COLOR, BOX_THICKNESS)
+
+    text = f"{label} {detection.confidence:.0%}".strip()
+    (tw, th), _ = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, 0.6, 2)
+    ty = max(y1, th + 6)
+    cv2.rectangle(out, (x1, ty - th - 6), (x1 + tw + 6, ty), BOX_COLOR, -1)
+    cv2.putText(
+        out, text, (x1 + 3, ty - 4), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 255, 255), 2
+    )
+    return out

detstream/config.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+import os
+import re
+from pathlib import Path
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+_ENV_REF = re.compile(r"\$\{(\w+)\}")
+
+
+class ComponentConfig(BaseModel):
+    type: str
+    # Everything else is the component's own config sub-block, passed through to its
+    # factory. Sources/detectors vary by type, so the schema is intentionally open
+    model_config = {"extra": "allow"}
+
+    def options(self) -> dict:
+        return self.model_dump(exclude={"type"})
+
+
+class DebounceConfig(BaseModel):
+    sample_interval_s: float = 2.0
+    enter_frames: int = 3
+    exit_frames: int = 5
+    cooldown_s: float = 120.0
+
+
+class FeedConfig(BaseModel):
+    id: str
+    name: str
+    source: ComponentConfig
+    detector: ComponentConfig
+    debounce: DebounceConfig = Field(default_factory=DebounceConfig)
+    sinks: list[str] = Field(default_factory=lambda: ["console"])
+
+
+class AppConfig(BaseModel):
+    feeds: list[FeedConfig]
+    # Shared sink settings keyed by sink name, e.g. {"supabase": {...}, "discord": {...}}.
+    # A feed enables a sink by listing its name, the settings come from here
+    sinks: dict[str, dict] = Field(default_factory=dict)
+
+    # A `sinks:` block with everything commented out parses as None
+    @field_validator("sinks", mode="before")
+    @classmethod
+    def _none_sinks_to_empty(cls, v):
+        return v or {}
+
+
+def _expand_env(value):
+    if isinstance(value, str):
+        return _ENV_REF.sub(lambda m: os.environ.get(m.group(1), ""), value)
+    if isinstance(value, dict):
+        return {k: _expand_env(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_expand_env(v) for v in value]
+    return value
+
+
+def _load_dotenv(path: Path) -> None:
+    env_file = path.parent / ".env"
+    if not env_file.exists():
+        return
+    for line in env_file.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.removeprefix("export ").strip()
+        value = value.strip()
+        if value and value[0] in "'\"":
+            # Quoted value: everything up to the matching quote is literal
+            quote = value[0]
+            end = value.find(quote, 1)
+            value = value[1:end] if end != -1 else value[1:]
+        else:
+            # Unquoted: an inline ` # comment` is not part of the value
+            value = value.split(" #", 1)[0].strip()
+        os.environ.setdefault(key, value)
+
+
+def load_config(path: str | Path) -> AppConfig:
+    path = Path(path)
+    _load_dotenv(path)
+    data = _expand_env(yaml.safe_load(path.read_text()))
+    return AppConfig(**data)

detstream/detectors/__init__.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Protocol
+import numpy as np
+from ..registry import Registry
+
+
+@dataclass
+class Detection:
+    present: bool
+    confidence: float
+    box: tuple[float, float, float, float] | None = None
+
+
+class Detector(Protocol):
+    def detect(self, frame: np.ndarray) -> Detection: ...
+
+
+detectors: Registry[Detector] = Registry("detstream.detectors")
+
+# Import built-ins so they self-register
+# A deployment that did not install the yolo extra can still use a plugin detector without importing ultralytics
+try:
+    from . import yolo_world  # noqa: F401
+except ImportError:
+    pass

detstream/detectors/yolo_world.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+import numpy as np
+from . import Detection, detectors
+
+
+# Open-vocabulary detector prompted with a class name
+class YoloWorldDetector:
+    def __init__(self, prompt: str, confidence_threshold: float, weights: str = ""):
+        from ultralytics import YOLO
+
+        self.prompt = prompt
+        self.threshold = confidence_threshold
+        self.model = YOLO(weights or "yolov8s-world.pt")
+        self.model.set_classes([prompt])
+
+    def detect(self, frame: np.ndarray) -> Detection:
+        results = self.model.predict(frame, conf=0.01, verbose=False)
+        best = 0.0
+        box = None
+        for r in results:
+            if r.boxes is None or len(r.boxes) == 0:
+                continue
+            top = int(r.boxes.conf.argmax())
+            conf = float(r.boxes.conf[top])
+            if conf > best:
+                best = conf
+                box = tuple(r.boxes.xyxy[top].cpu().tolist())
+        return Detection(present=best >= self.threshold, confidence=best, box=box)
+
+
+@detectors.register("yolo-world")
+def _build(config: dict) -> YoloWorldDetector:
+    return YoloWorldDetector(
+        prompt=config.get("prompt", "object"),
+        confidence_threshold=config.get("confidence_threshold", 0.4),
+        weights=config.get("weights", ""),
+    )

detstream/events.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+from dataclasses import dataclass
+import numpy as np
+
+
+@dataclass
+class SightingStarted:
+    feed_id: str
+    confidence: float
+
+
+@dataclass
+class SightingEnded:
+    feed_id: str
+    peak_confidence: float
+    # The peak-confidence frame, annotated, captured over the sighting's life. The
+    # thumbnail is uploaded from this so it matches the stored peak confidence
+    peak_frame: np.ndarray | None = None

detstream/registry.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+import logging
+from importlib.metadata import entry_points
+from typing import Callable, Generic, TypeVar
+
+log = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+# A factory takes the component's config sub-block (a plain dict) and returns an
+# instance. Built-ins register a factory under a name, config selects by that name
+Factory = Callable[[dict], T]
+
+
+class Registry(Generic[T]):
+    def __init__(self, entry_point_group: str):
+        self._factories: dict[str, Factory[T]] = {}
+        self._group = entry_point_group
+        self._loaded_entry_points = False
+
+    def register(self, name: str) -> Callable[[Factory[T]], Factory[T]]:
+        def decorator(factory: Factory[T]) -> Factory[T]:
+            if name in self._factories:
+                raise ValueError(f"{name!r} is already registered in {self._group}")
+            self._factories[name] = factory
+            return factory
+
+        return decorator
+
+    def create(self, name: str, config: dict) -> T:
+        if name not in self._factories:
+            self._load_entry_points()
+        try:
+            factory = self._factories[name]
+        except KeyError:
+            known = ", ".join(sorted(self._factories)) or "(none)"
+            raise ValueError(f"unknown {self._group} {name!r}; known: {known}") from None
+        return factory(config)
+
+    # Discover plugins declared by installed packages under this group. A plugin's
+    # entry point points at a callable that registers its factories on import, so
+    # loading the module is enough. The value is called if it is callable
+    def _load_entry_points(self) -> None:
+        if self._loaded_entry_points:
+            return
+        self._loaded_entry_points = True
+        for ep in entry_points(group=self._group):
+            try:
+                obj = ep.load()
+                if callable(obj):
+                    obj()
+            except Exception as e:
+                log.warning("failed to load plugin %r in %s: %s", ep.name, self._group, e)

detstream/runner.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+import asyncio
+import logging
+import os
+from .annotate import annotate
+from .config import AppConfig, FeedConfig
+from .detectors import Detector, detectors
+from .events import SightingStarted
+from .sinks import Sink, sinks as sink_registry
+from .sources import sources as source_registry
+from .state import SightingTracker
+
+log = logging.getLogger(__name__)
+
+
+def build_sinks(feed: FeedConfig, app: AppConfig) -> list[Sink]:
+    built: list[Sink] = []
+    for name in feed.sinks:
+        config = app.sinks.get(name, {})
+        built.append(sink_registry.create(name, config))
+    return built
+
+
+# Restart backoff for a feed whose watch loop crashed
+FEED_RESTART_BACKOFF_S = (5.0, 15.0, 30.0, 60.0)
+
+
+async def _dispatch(sinks: list[Sink], call) -> None:
+    # One sink failing (a network blip on the supabase POST) must not stop the others or
+    # kill the feed, so each call is awaited independently and its error logged
+    results = await asyncio.gather(*(call(s) for s in sinks), return_exceptions=True)
+    for sink, result in zip(sinks, results):
+        if isinstance(result, Exception):
+            log.warning("sink %s failed: %s", type(sink).__name__, result)
+
+
+async def watch_feed(feed: FeedConfig, detector: Detector, sinks: list[Sink]) -> None:
+    tracker = SightingTracker(
+        feed_id=feed.id,
+        enter_frames=feed.debounce.enter_frames,
+        exit_frames=feed.debounce.exit_frames,
+        cooldown_s=feed.debounce.cooldown_s,
+    )
+    loop = asyncio.get_running_loop()
+    source = source_registry.create(
+        feed.source.type,
+        {**feed.source.options(), "interval_s": feed.debounce.sample_interval_s},
+    )
+    async for _ts, frame in source.frames():
+        det = await asyncio.to_thread(detector.detect, frame)
+        # Annotate before the tracker captures the frame, so the saved thumbnail shows
+        # the detection box
+        annotated = annotate(frame, det, feed.name) if det.present else frame
+        event = tracker.update(det.present, det.confidence, annotated, loop.time())
+        if event is None:
+            continue
+        if isinstance(event, SightingStarted):
+            await _dispatch(sinks, lambda s: s.on_sighting_start(event, feed.name))
+        else:
+            await _dispatch(sinks, lambda s: s.on_sighting_end(event))
+
+
+async def supervise_feed(feed: FeedConfig, detector: Detector, sinks: list[Sink]) -> None:
+    attempt = 0
+    while True:
+        try:
+            await watch_feed(feed, detector, sinks)
+            return
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            backoff = FEED_RESTART_BACKOFF_S[min(attempt, len(FEED_RESTART_BACKOFF_S) - 1)]
+            log.exception("feed %s crashed: %s; restarting in %ss", feed.id, e, backoff)
+            attempt += 1
+            await asyncio.sleep(backoff)
+
+
+CLEANUP_INTERVAL_S = float(os.environ.get("DETSTREAM_CLEANUP_INTERVAL_S", str(60 * 60)))
+
+
+# Run each sink's cleanup() on an interval (hourly by default)
+async def cleanup_loop(sinks: list[Sink]) -> None:
+    targets = [s for s in sinks if hasattr(s, "cleanup")]
+    if not targets:
+        return
+    while True:
+        await asyncio.sleep(CLEANUP_INTERVAL_S)
+        for sink in targets:
+            try:
+                await asyncio.to_thread(sink.cleanup)
+            except Exception as e:
+                log.warning("cleanup failed for %s: %s", type(sink).__name__, e)
+
+
+async def run(app: AppConfig) -> None:
+    if not app.feeds:
+        log.error("no feeds configured")
+        return
+
+    tasks = []
+    all_sinks: list[Sink] = []
+    for feed in app.feeds:
+        detector = detectors.create(feed.detector.type, feed.detector.options())
+        sinks = build_sinks(feed, app)
+        all_sinks.extend(sinks)
+        log.info("watching %s with %d sink(s)", feed.id, len(sinks))
+        tasks.append(asyncio.create_task(supervise_feed(feed, detector, sinks)))
+
+    # Dedupe sinks of the same type so cleanup runs once
+    unique_sinks = list({type(s): s for s in all_sinks}.values())
+    tasks.append(asyncio.create_task(cleanup_loop(unique_sinks)))
+
+    try:
+        await asyncio.gather(*tasks)
+    except asyncio.CancelledError:
+        for t in tasks:
+            t.cancel()
+        raise

detstream/sinks/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+from typing import Protocol
+from ..events import SightingEnded, SightingStarted
+from ..registry import Registry
+
+
+class Sink(Protocol):
+    async def on_sighting_start(self, event: SightingStarted, feed_name: str) -> None: ...
+    async def on_sighting_end(self, event: SightingEnded) -> None: ...
+
+
+sinks: Registry[Sink] = Registry("detstream.sinks")
+
+# console has no optional deps. The others self-register but their factories import their
+# client libraries lazily, so a deployment only pays for the sinks it enables
+from . import console  # noqa: E402,F401
+
+try:
+    from . import supabase  # noqa: F401
+except ImportError:
+    pass
+try:
+    from . import discord  # noqa: F401
+except ImportError:
+    pass

detstream/sinks/console.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+import logging
+from ..events import SightingEnded, SightingStarted
+from . import sinks
+
+log = logging.getLogger(__name__)
+
+
+class ConsoleSink:
+    async def on_sighting_start(self, event: SightingStarted, feed_name: str) -> None:
+        log.info("sighting on %s (%.2f)", feed_name, event.confidence)
+
+    async def on_sighting_end(self, event: SightingEnded) -> None:
+        log.info("ended on %s (peak %.2f)", event.feed_id, event.peak_confidence)
+
+
+@sinks.register("console")
+def _build(config: dict) -> ConsoleSink:
+    return ConsoleSink()

detstream/sinks/discord.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+import os
+import httpx
+from ..events import SightingEnded, SightingStarted
+from . import sinks
+
+DEFAULT_COLOR = 0x6EC9A9
+
+
+# Posts a rich embed on each new sighting with feed name and peak confidence. 
+# Honors the per-feed cooldown upstream in SightingTracker
+# A watch live link is per-feed, so it is passed via config.watch_urls
+class DiscordSink:
+    def __init__(self, config: dict):
+        self.webhook_url = os.environ.get("DETSTREAM_DISCORD_WEBHOOK_URL", "")
+        if not self.webhook_url:
+            raise ValueError("discord sink needs DETSTREAM_DISCORD_WEBHOOK_URL")
+        self.color = config.get("color", DEFAULT_COLOR)
+        self.watch_urls: dict[str, str] = config.get("watch_urls", {})
+
+    async def on_sighting_start(self, event: SightingStarted, feed_name: str) -> None:
+        embed = {
+            "title": f"spotted on {feed_name}",
+            "color": self.color,
+            "fields": [{"name": "confidence", "value": f"{event.confidence:.0%}", "inline": True}],
+        }
+        watch_url = self.watch_urls.get(event.feed_id)
+        if watch_url:
+            embed["url"] = watch_url
+            embed["description"] = f"[watch live]({watch_url})"
+        async with httpx.AsyncClient(timeout=10) as client:
+            await client.post(self.webhook_url, json={"embeds": [embed]})
+
+    async def on_sighting_end(self, event: SightingEnded) -> None:
+        return
+
+
+@sinks.register("discord")
+def _build(config: dict) -> DiscordSink:
+    return DiscordSink(config)

detstream/sinks/supabase.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+import logging
+import os
+import uuid
+import cv2
+from ..events import SightingEnded, SightingStarted
+from . import sinks
+
+log = logging.getLogger(__name__)
+
+
+# Writes a sightings row on start and patches ended_at on end. The peak confidence frame is
+# downscaled, uploaded to Supabase Storage, and its URL is stored on the row. The website
+# subscribes to the table via Realtime
+class SupabaseSink:
+    def __init__(self, config: dict):
+        from supabase import create_client
+
+        url = os.environ.get("DETSTREAM_SUPABASE_URL", "")
+        key = os.environ.get("DETSTREAM_SUPABASE_KEY", "")
+        if not url or not key:
+            raise ValueError(
+                "supabase sink needs DETSTREAM_SUPABASE_URL and DETSTREAM_SUPABASE_KEY"
+            )
+        self.client = create_client(url, key)
+        self.bucket = config.get("bucket", "thumbnails")
+        self.detector_label = config.get("detector_label", "")
+        self.thumbnail_width = int(config.get("thumbnail_width", 960))
+        self.thumbnail_quality = int(config.get("thumbnail_quality", 70))
+        self.retention_hours = float(config.get("retention_hours", 3))
+        self._open_rows: dict[str, str] = {}  # feed_id -> sighting row id
+
+    async def on_sighting_start(self, event: SightingStarted, feed_name: str) -> None:
+        # No thumbnail yet, it is uploaded on end from the peak-confidence frame
+        row = (
+            self.client.table("sightings")
+            .insert(
+                {
+                    "cam_id": event.feed_id,
+                    "confidence": event.confidence,
+                    "detector": self.detector_label,
+                }
+            )
+            .execute()
+        )
+        self._open_rows[event.feed_id] = row.data[0]["id"]
+
+    async def on_sighting_end(self, event: SightingEnded) -> None:
+        row_id = self._open_rows.pop(event.feed_id, None)
+        if row_id is None:
+            return
+        thumb_url = self._upload_thumbnail(event.feed_id, event.peak_frame)
+        self.client.table("sightings").update(
+            {
+                "ended_at": "now()",
+                "confidence": event.peak_confidence,
+                "thumbnail": thumb_url,
+            }
+        ).eq("id", row_id).execute()
+
+    def _upload_thumbnail(self, feed_id: str, frame) -> str | None:
+        if frame is None:
+            return None
+        frame = self._downscale(frame)
+        ok, buf = cv2.imencode(
+            ".jpg", frame, [cv2.IMWRITE_JPEG_QUALITY, self.thumbnail_quality]
+        )
+        if not ok:
+            return None
+        path = f"{feed_id}/{uuid.uuid4().hex}.jpg"
+        # A storage failure (bucket full/missing) must not lose the row's ended_at patch,
+        # so the upload is isolated and the row keeps a null thumbnail
+        try:
+            self.client.storage.from_(self.bucket).upload(
+                path, buf.tobytes(), {"content-type": "image/jpeg"}
+            )
+            return self.client.storage.from_(self.bucket).get_public_url(path)
+        except Exception as e:
+            log.warning("thumbnail upload failed for %s: %s", feed_id, e)
+            return None
+
+    def _downscale(self, frame):
+        h, w = frame.shape[:2]
+        if w <= self.thumbnail_width:
+            return frame
+        new_h = round(h * self.thumbnail_width / w)
+        return cv2.resize(frame, (self.thumbnail_width, new_h), interpolation=cv2.INTER_AREA)
+
+    # Delete sightings and their thumbnail objects older than retention_hours
+    def cleanup(self) -> None:
+        if self.retention_hours <= 0:
+            return
+        from datetime import datetime, timedelta, timezone
+
+        cutoff = (datetime.now(timezone.utc) - timedelta(hours=self.retention_hours)).isoformat()
+        old = (
+            self.client.table("sightings")
+            .select("id, thumbnail")
+            .lt("started_at", cutoff)
+            .execute()
+            .data
+        )
+        if not old:
+            return
+
+        paths = []
+        for r in old:
+            url = r.get("thumbnail") or ""
+            marker = f"/{self.bucket}/"
+            i = url.find(marker)
+            if i != -1:
+                paths.append(url[i + len(marker) :])
+        for i in range(0, len(paths), 100):
+            self.client.storage.from_(self.bucket).remove(paths[i : i + 100])
+
+        ids = [r["id"] for r in old]
+        for i in range(0, len(ids), 100):
+            self.client.table("sightings").delete().in_("id", ids[i : i + 100]).execute()
+        log.info("cleanup: removed %d sighting(s) older than %gh", len(ids), self.retention_hours)
+
+
+@sinks.register("supabase")
+def _build(config: dict) -> SupabaseSink:
+    return SupabaseSink(config)

detstream/sources/__init__.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+import asyncio
+import logging
+import time
+from collections.abc import AsyncIterator
+from typing import Callable, Protocol
+import cv2
+import numpy as np
+from ..registry import Registry
+
+log = logging.getLogger(__name__)
+
+
+class Source(Protocol):
+    def frames(self) -> AsyncIterator[tuple[float, np.ndarray]]: ...
+
+
+# How long VideoCapture reads can keep failing before the stream is treated as down,
+# rather than emitting the last decoded frame
+STREAM_DOWN_AFTER_S = 15.0
+RECONNECT_BACKOFF_S = (2.0, 5.0, 15.0, 30.0, 60.0)
+
+
+async def capture_frames(
+    open_capture: Callable[[], "cv2.VideoCapture"],
+    interval_s: float,
+    *,
+    label: str,
+    reconnect: bool = True,
+) -> AsyncIterator[tuple[float, np.ndarray]]:
+    """Read frames from an OpenCV VideoCapture with reconnect + frozen-frame handling.
+
+    open_capture is called to (re)open the capture. Sources that need to re-resolve a
+    URL (YouTube) pass a closure that re-resolves. Sources reading a finite file pass
+    reconnect=False so EOF ends the stream instead of looping forever.
+    """
+    attempt = 0
+    while True:
+        try:
+            cap = await asyncio.to_thread(open_capture)
+        except Exception as e:
+            if not reconnect:
+                raise
+            backoff = RECONNECT_BACKOFF_S[min(attempt, len(RECONNECT_BACKOFF_S) - 1)]
+            log.warning("%s: open failed: %s; retrying in %ss", label, e, backoff)
+            attempt += 1
+            await asyncio.sleep(backoff)
+            continue
+
+        attempt = 0
+        last_ok = time.monotonic()
+        try:
+            while True:
+                ok, frame = await asyncio.to_thread(cap.read)
+                now = time.monotonic()
+                if ok and frame is not None:
+                    last_ok = now
+                    yield time.time(), frame
+                    await asyncio.sleep(interval_s)
+                    continue
+                if not reconnect:
+                    return
+                if now - last_ok > STREAM_DOWN_AFTER_S:
+                    log.warning("%s: stream down; reconnecting", label)
+                    break
+                await asyncio.sleep(1.0)
+        finally:
+            await asyncio.to_thread(cap.release)
+
+
+sources: Registry[Source] = Registry("detstream.sources")
+
+from . import file_device, stream, youtube  # noqa: E402,F401

detstream/sources/file_device.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+from collections.abc import AsyncIterator
+import cv2
+import numpy as np
+from . import capture_frames, sources
+
+
+# A local video file or a webcam/capture device (integer index)
+# By default a file stops at EOF, set loop: true to replay it (handy for
+# demos). A device index always reconnects, like a live stream
+class FileDeviceSource:
+    def __init__(self, path: str | int, interval_s: float, loop: bool):
+        self.path = path
+        self.interval_s = interval_s
+        self.loop = loop
+
+    def frames(self) -> AsyncIterator[tuple[float, np.ndarray]]:
+        is_device = isinstance(self.path, int)
+        reconnect = self.loop or is_device
+        return capture_frames(
+            lambda: cv2.VideoCapture(self.path),
+            self.interval_s,
+            label=f"file {self.path}",
+            reconnect=reconnect,
+        )
+
+
+@sources.register("file")
+def _build(config: dict) -> FileDeviceSource:
+    path = config["path"]
+    # An all-digit path is a capture device index, not a filename
+    if isinstance(path, str) and path.isdigit():
+        path = int(path)
+    return FileDeviceSource(
+        path=path,
+        interval_s=config.get("interval_s", 2.0),
+        loop=config.get("loop", False),
+    )

detstream/sources/stream.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from collections.abc import AsyncIterator
+import cv2
+import numpy as np
+from . import capture_frames, sources
+
+
+# A direct stream URL (RTSP, HLS, or HTTP) read straight by OpenCV, no resolve step.
+# Covers IP cameras and raw stream endpoints
+class StreamSource:
+    def __init__(self, url: str, interval_s: float):
+        self.url = url
+        self.interval_s = interval_s
+
+    def frames(self) -> AsyncIterator[tuple[float, np.ndarray]]:
+        return capture_frames(
+            lambda: cv2.VideoCapture(self.url), self.interval_s, label=f"stream {self.url}"
+        )
+
+
+@sources.register("stream")
+def _build(config: dict) -> StreamSource:
+    return StreamSource(url=config["url"], interval_s=config.get("interval_s", 2.0))

detstream/sources/youtube.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+from collections.abc import AsyncIterator
+import cv2
+import numpy as np
+from . import capture_frames, sources
+
+
+def resolve_stream(youtube_url: str) -> str:
+    import yt_dlp
+
+    # remote_components lets yt-dlp fetch and run its JS challenge solver
+    opts = {
+        "quiet": True,
+        "format": "best[protocol^=m3u8]/best",
+        "noplaylist": True,
+        "remote_components": ["ejs:github"],
+    }
+    with yt_dlp.YoutubeDL(opts) as ydl:
+        info = ydl.extract_info(youtube_url, download=False)
+    return info["url"]
+
+
+# A YouTube live stream. yt-dlp resolves the page to an HLS manifest, which OpenCV reads
+# The manifest URL expires, so each reconnect re-resolves rather than reusing the old one
+class YouTubeSource:
+    def __init__(self, url: str, interval_s: float):
+        self.url = url
+        self.interval_s = interval_s
+
+    def frames(self) -> AsyncIterator[tuple[float, np.ndarray]]:
+        def open_capture() -> cv2.VideoCapture:
+            hls = resolve_stream(self.url)
+            return cv2.VideoCapture(hls)
+
+        return capture_frames(open_capture, self.interval_s, label=f"youtube {self.url}")
+
+
+@sources.register("youtube")
+def _build(config: dict) -> YouTubeSource:
+    return YouTubeSource(url=config["url"], interval_s=config.get("interval_s", 2.0))

detstream/state.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+import numpy as np
+from .events import SightingEnded, SightingStarted
+
+
+# State tracking and cooldown over a stream of per-frame detections per feed
+# Fires SightingStarted when a sighting begins, tracks peak confidence for the
+# duration of the sighting, and doesn't fire again until the cooldown has elapsed
+@dataclass
+class SightingTracker:
+    feed_id: str
+    enter_frames: int
+    exit_frames: int
+    cooldown_s: float
+
+    present: bool = False
+    _over: int = 0
+    _under: int = 0
+    _peak: float = 0.0
+    _peak_frame: np.ndarray | None = None
+    _last_alert_at: float | None = field(default=None)
+
+    def update(
+        self, detected: bool, confidence: float, frame: np.ndarray, now: float
+    ) -> SightingStarted | SightingEnded | None:
+        if detected:
+            self._over += 1
+            self._under = 0
+        else:
+            self._under += 1
+            self._over = 0
+
+        if self.present:
+            # Keep the frame from the highest-confidence moment for the thumbnail
+            if confidence > self._peak:
+                self._peak = confidence
+                self._peak_frame = frame
+            if self._under >= self.exit_frames:
+                self.present = False
+                ended = SightingEnded(self.feed_id, self._peak, self._peak_frame)
+                self._peak = 0.0
+                self._peak_frame = None
+                return ended
+            return None
+
+        if self._over >= self.enter_frames and not self._in_cooldown(now):
+            self.present = True
+            self._last_alert_at = now
+            self._peak = confidence
+            self._peak_frame = frame
+            return SightingStarted(self.feed_id, confidence)
+
+        return None
+
+    def _in_cooldown(self, now: float) -> bool:
+        if self._last_alert_at is None:
+            return False
+        return (now - self._last_alert_at) < self.cooldown_s

detstream-0.1.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: detstream
+Version: 0.1.0
+Summary: Modular object detection for live video feeds
+Author: catherinepereira
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/catherinepereira/detstream
+Project-URL: Repository, https://github.com/catherinepereira/detstream
+Keywords: object-detection,video,streaming,yolo,computer-vision
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: opencv-python-headless>=4.9.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: yolo
+Requires-Dist: ultralytics>=8.3.0; extra == "yolo"
+Requires-Dist: torch>=2.2.0; extra == "yolo"
+Provides-Extra: youtube
+Requires-Dist: yt-dlp>=2026.03.17; extra == "youtube"
+Requires-Dist: deno>=2.8.0; extra == "youtube"
+Provides-Extra: supabase
+Requires-Dist: supabase>=2.4.0; extra == "supabase"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+# detstream
+
+Modular object detection framework for live video feeds.
+
+## Pipeline
+
+1. **Source**: Where frames come from. `youtube`, `stream` (RTSP/HLS/HTTP), `file` (a video
+  file or webcam device)
+2. **Detector**: What to look for. `yolo-world`, an open-vocabulary model prompted with a
+  word or phrase (`person`, `forklift`, `bird`). Bring your own by registering one (see Plugins).
+3. **Tracker**: When a detection counts as a sighting. Hysteresis and cooldown give you one
+  alert per sighting instead of one per frame, which is what keeps alerts from becoming spam.
+4. **Sinks**: Where alerts go. `console`, `supabase` (rows + thumbnails for a website),
+  `discord` (rich embeds).
+
+## Install
+
+```bash
+pip install detstream                          # core only
+pip install "detstream[yolo,youtube,supabase]" # for example, everything otterwatch uses
+```
+
+The core install pulls what every feed needs: `numpy`, `opencv-python-headless`
+(decoding and annotation), `pydantic` (config), `pyyaml`, and `httpx`.
+
+| Extra | Enables | Pulls in |
+| --- | --- | --- |
+| `yolo` | the `yolo-world` detector | `ultralytics>=8.3.0`, `torch>=2.2.0`. ultralytics fetches CLIP on first use of the detector |
+| `youtube` | the `youtube` source | `yt-dlp>=2026.03.17` and `deno>=2.8.0`, which ships the deno binary yt-dlp runs to solve YouTube's stream challenge |
+| `supabase` | the `supabase` sink | `supabase>=2.4.0` |
+
+## Run
+
+```bash
+detstream --config examples/otters.yaml
+```
+
+A config lists feeds and shared sink settings:
+
+```yaml
+feeds:
+  - id: monterey-otters
+    name: Monterey Sea Otters
+    source:   { type: youtube, url: "https://www.youtube.com/watch?v=abbR-Ttd-cA" }
+    detector: { type: yolo-world, prompt: otter swimming, confidence_threshold: 0.4 }
+    debounce: { enter_frames: 3, exit_frames: 5, cooldown_s: 120, sample_interval_s: 2 }
+    sinks: [console, supabase]
+sinks:
+  supabase: { bucket: thumbnails, detector_label: yolo-world, retention_hours: 3, thumbnail_width: 960 }
+```
+
+Credentials and webhook URLs are configured in `.env`: `DETSTREAM_SUPABASE_URL`, `DETSTREAM_SUPABASE_KEY`, and `DETSTREAM_DISCORD_WEBHOOK_URL`.
+
+## Plugins
+
+Built-in components register themselves on import. To add your own detector (an HF model, a
+cloud API, a fine-tuned ONNX, etc.), register a factory and declare an entry point:
+
+```python
+# mypkg/detector.py
+from detstream.detectors import detectors, Detection
+
+class MyDetector:
+    def detect(self, frame) -> Detection: ...
+
+@detectors.register("my-model")
+def _build(config: dict) -> MyDetector:
+    return MyDetector(**config)
+```
+
+```toml
+# mypkg/pyproject.toml
+[project.entry-points."detstream.detectors"]
+my-model = "mypkg.detector"
+```
+
+After `pip install`, reference it in config as `detector: { type: my-model, ... }`. detstream
+discovers it through the entry point with no change to detstream itself. The same pattern works
+for `detstream.sources` and `detstream.sinks`.
+
+## Layout
+
+```
+detstream/
+  registry.py     register + create + entry-point discovery
+  config.py       FeedConfig / AppConfig, loads YAML
+  runner.py       per-feed asyncio loop
+  state.py        SightingTracker: hysteresis + cooldown, no I/O
+  events.py       SightingStarted / SightingEnded
+  sources/        youtube, stream, file_device (+ shared reconnect base)
+  detectors/      yolo_world
+  sinks/          console, supabase, discord
+examples/         otters.yaml, eagles.yaml
+tests/            config, registry, sources, state, sinks, detectors
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

detstream-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+detstream/__init__.py,sha256=L7lddFxMl5oUZrs8ct43YyG3PY80tZMGkk-lxegUJmA,161
+detstream/__main__.py,sha256=KcB6klF-sSOExKLC8m9tYrnzgD97ZzBMUa115nuQwOU,788
+detstream/annotate.py,sha256=md5_gFA3bRYv1G6zqJrlD3jXPP-qa0n1-vrhjvgfdnM,976
+detstream/config.py,sha256=gIdRcrGMhVO4F4Lr2ElXicbEsaj1z9n4QTgpoe06GIM,2736
+detstream/events.py,sha256=BOFJHvgo7_cAeMORJWH1VQDjA8SYNWrhykXVkO2wDh8,444
+detstream/registry.py,sha256=wEB_iWyIHEGNtmsTwCi-U3N8_7H-dwjEdsxjCugTzb0,2021
+detstream/runner.py,sha256=Ds8CBjRR0y_2lLL5bmvv3mGeu8OOomr6WBcbaMLx3co,4288
+detstream/state.py,sha256=BqrTtSBXwtZYcnG6hhBrm1V-NkOUX-BqqRUGck6s6ac,1978
+detstream/detectors/__init__.py,sha256=tXs7QzebKo-ubMWSbGSmkeM_yBhjz0aiR5j6NH8gWdY,659
+detstream/detectors/yolo_world.py,sha256=ZH1imGTdB6FiieBD89ldQhHIsaHYOJJH4n_72EjTBd8,1302
+detstream/sinks/__init__.py,sha256=LQjbK6dbNPrJ9nkHIOKTPYnqptLUPb6vb69E-7T5FOk,747
+detstream/sinks/console.py,sha256=9diJfRGJWOgVBnzpCxzKTXDk1nm9GBuUbyVfFuS5Xzg,581
+detstream/sinks/discord.py,sha256=Wu3Hqg_w5EA71VMAWEj2wt_gt1kcablqj-KqGEps80w,1537
+detstream/sinks/supabase.py,sha256=ysQYhB52V2sIxGm7i3lKCfY6f28ZcSPxDSHCDHcfo3w,4732
+detstream/sources/__init__.py,sha256=yvFtB7k-5p85GPx1DJlCNFBf2psHwiG6KerP3ad3Ub0,2383
+detstream/sources/file_device.py,sha256=HsSI2dr5hvQHvF04HyOE5nVcqQLXz7ysEND3cajAboM,1261
+detstream/sources/stream.py,sha256=2Gwky7R3CuBIBaPH3_hnwtlNeHN_sw6Om6vuY8Owclw,766
+detstream/sources/youtube.py,sha256=ON0FUJpNO7BhtXmAHgBmA3PUDEWcg_8NaZJhfhyJFz4,1335
+detstream-0.1.0.dist-info/licenses/LICENSE,sha256=t6OtDm9utbKg4SC6nd9ojOssuacbnzHsPZCb6du-Nkg,1073
+detstream-0.1.0.dist-info/METADATA,sha256=QLZAU37eFqB4atB71vQUNZ6EwigbHZraSwwQRoBxW7Y,4925
+detstream-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+detstream-0.1.0.dist-info/entry_points.txt,sha256=DIJ756--PMRovx_pIVYV3fUoT0CXDs3bmqM0yOAeB3A,54
+detstream-0.1.0.dist-info/top_level.txt,sha256=HV04D3nelp-oKiYr5w5322rnwuKcOYxGoWjhSO9enKs,10
+detstream-0.1.0.dist-info/RECORD,,

detstream-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

detstream-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+detstream = detstream.__main__:main

detstream-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 catherinepereira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

detstream-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+detstream