Generalize webcam proxy to a live-image proxy supporting all-sky cameras

Refactors the native CLI proxy from webcam-only to a source-agnostic
live-image proxy. USB webcams keep working unchanged; all-sky cameras
that write JPEGs to disk (Thomas Jacquin's allsky, indi-allsky, ...) are
now supported through the same WebSocket transport, addressed by source
ids like webcam:0 or allsky:roof.

- New arcsecond/imagesources/ package replaces arcsecond/webcam/, with a
  FrameSource ABC and two implementations: OpenCV (webcams) and a file-
  watcher (all-sky JPEGs, mtime-based, file or glob).
- All-sky paths auto-discovered at well-known locations; custom paths
  can be registered with --allsky id=path on `webcam start` or `allsky start`.
- New `arcsecond allsky` CLI group (detect, start). `arcsecond webcam`
  remains as backward-compatible alias.
- Wire protocol unchanged: {type, format: "jpeg/base64", data}. Numeric
  /stream/{N} ids still resolve to webcam:N.
- Backend env var renamed WEBCAM_PROXY_URL → LIVE_IMAGE_PROXY_URL.
- pip install arcsecond[webcam] still works (extra name preserved).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: onekiloparsec

arcsecond/cli.py

@@ -10,7 +10,7 @@
     upload_data,
 )
 from arcsecond.hosting import setup
-from arcsecond.webcam import commands as webcam
+from arcsecond.imagesources import commands as imagesources
 
 from . import __version__
 from .options import State
@@ -61,5 +61,7 @@ def version():
 # Allow to try arcsecond by installing a local version
 main.add_command(setup)
 
-# Native webcam proxy — lets Docker containers reach USB webcams on the host.
-main.add_command(webcam.webcam)
+# Native live-image proxy — exposes USB webcams and all-sky cameras to
+# Arcsecond.local Docker containers via host.docker.internal.
+main.add_command(imagesources.webcam)
+main.add_command(imagesources.allsky)

arcsecond/webcam/__init__.py arcsecond/imagesources/__init__.pyarcsecond/webcam/__init__.py renamed to arcsecond/imagesources/__init__.py

@@ -0,0 +1,175 @@
+"""
+Click command groups: ``arcsecond webcam`` and ``arcsecond allsky``.
+
+Both groups talk to the same proxy. ``webcam`` is kept for backward
+compatibility; ``allsky`` is the new entry point for fisheye / all-sky
+cameras whose driver software writes JPEGs to disk.
+"""
+
+import logging
+
+import click
+
+from .registry import AllskyOverride
+from .sources.filewatch import detect_allsky
+from .sources.opencv import detect_webcams
+
+logger = logging.getLogger(__name__)
+
+
+def _check_aiohttp():
+    try:
+        import aiohttp  # noqa: F401
+    except ImportError:
+        click.echo(
+            click.style("Error: ", fg='red') +
+            "aiohttp is not installed.\n"
+            "Run:  pip install 'arcsecond[webcam]'"
+        )
+        raise SystemExit(1)
+
+
+def _check_cv2():
+    try:
+        import cv2  # noqa: F401
+    except ImportError:
+        click.echo(
+            click.style("Error: ", fg='red') +
+            "opencv-python-headless is not installed.\n"
+            "Run:  pip install 'arcsecond[webcam]'"
+        )
+        raise SystemExit(1)
+
+
+def _parse_allsky_overrides(values: tuple[str, ...]) -> list[AllskyOverride]:
+    overrides: list[AllskyOverride] = []
+    for v in values:
+        if '=' not in v:
+            raise click.BadParameter(f"--allsky must be id=path, got {v!r}")
+        sid, _, path = v.partition('=')
+        sid, path = sid.strip(), path.strip()
+        if not sid or not path:
+            raise click.BadParameter(f"--allsky must be id=path, got {v!r}")
+        overrides.append(AllskyOverride(id=sid, path=path))
+    return overrides
+
+
+def _run_proxy(host: str, port: int, log_level: str, allsky_overrides):
+    _check_aiohttp()
+
+    logging.basicConfig(
+        level=getattr(logging, log_level.upper()),
+        format='%(asctime)s  %(levelname)-8s  %(name)s  %(message)s',
+    )
+
+    click.echo(
+        click.style("Arcsecond live-image proxy", bold=True) +
+        f" listening on {host}:{port}\n"
+        f"  Detection  →  http://{host}:{port}/detect\n"
+        f"  Streaming  →  ws://{host}:{port}/stream/{{id}}\n\n"
+        "Set in your .env file:\n"
+        f"  LIVE_IMAGE_PROXY_URL=http://host.docker.internal:{port}\n\n"
+        "Press Ctrl-C to stop."
+    )
+
+    from .proxy import run
+    run(host=host, port=port, allsky_overrides=allsky_overrides)
+
+
+# ---------------------------------------------------------------------------
+# Shared options
+# ---------------------------------------------------------------------------
+
+_start_options = [
+    click.option('--port', default=8765, show_default=True, help="TCP port to listen on."),
+    click.option('--host', default='0.0.0.0', show_default=True, help="Interface to bind."),
+    click.option('--log-level', default='INFO', show_default=True,
+                 type=click.Choice(['DEBUG', 'INFO', 'WARNING', 'ERROR'], case_sensitive=False),
+                 help="Logging verbosity."),
+    click.option('--allsky', 'allsky', multiple=True, metavar='ID=PATH',
+                 help="Register an all-sky source. PATH may be a file or a glob. "
+                      "Repeat for multiple cameras. If omitted, well-known paths "
+                      "are auto-discovered."),
+]
+
+
+def _add_options(options):
+    def _wrap(fn):
+        for opt in reversed(options):
+            fn = opt(fn)
+        return fn
+    return _wrap
+
+
+# ---------------------------------------------------------------------------
+# `arcsecond webcam` group  (kept for backward compatibility)
+# ---------------------------------------------------------------------------
+
+@click.group(help="Manage the native live-image proxy (USB webcams + all-sky).")
+def webcam():
+    pass
+
+
+@webcam.command(name='detect', help="Scan for locally attached webcams and print their details.")
+def webcam_detect_cmd():
+    _check_cv2()
+    cams = detect_webcams()
+    if not cams:
+        click.echo("No webcams detected.")
+        return
+    click.echo(f"Found {len(cams)} webcam(s):\n")
+    for c in cams:
+        e = c.extra or {}
+        click.echo(f"  {c.id}  {e.get('width')}×{e.get('height')}  {e.get('fps', 0):.1f} fps")
+
+
+@webcam.command(name='start', help=(
+    "Start the live-image proxy server.\n\n"
+    "Exposes:\n\n"
+    "  GET  /detect              — list available sources (JSON)\n\n"
+    "  WS   /stream/{id}         — JPEG frame stream\n\n"
+    "Source ids are e.g. webcam:0, allsky:roof. Bare numeric ids "
+    "(/stream/0) are accepted for backward compatibility.\n\n"
+    "Set LIVE_IMAGE_PROXY_URL=http://host.docker.internal:<PORT> in your "
+    ".env so the backend can reach the proxy."
+))
+@_add_options(_start_options)
+def webcam_start_cmd(port, host, log_level, allsky):
+    overrides = _parse_allsky_overrides(allsky)
+    _run_proxy(host, port, log_level, overrides)
+
+
+# ---------------------------------------------------------------------------
+# `arcsecond allsky` group  (new)
+# ---------------------------------------------------------------------------
+
+@click.group(help="Manage all-sky camera image sources.")
+def allsky():
+    pass
+
+
+@allsky.command(name='detect', help=(
+    "Auto-discover all-sky sources at well-known paths "
+    "(Thomas Jacquin's allsky, indi-allsky)."
+))
+def allsky_detect_cmd():
+    found = detect_allsky()
+    if not found:
+        click.echo("No all-sky sources discovered at well-known paths.")
+        click.echo("\nIf your software writes images elsewhere, register a custom path with:\n")
+        click.echo("  arcsecond allsky start --allsky <id>=<path-to-jpeg-or-glob>")
+        return
+    click.echo(f"Found {len(found)} all-sky source(s):\n")
+    for s in found:
+        click.echo(f"  {s.id}  →  {(s.extra or {}).get('path')}")
+
+
+@allsky.command(name='start', help=(
+    "Start the live-image proxy server (same proxy as `arcsecond webcam start`).\n\n"
+    "Use --allsky id=path to register custom all-sky paths in addition to "
+    "auto-discovered ones."
+))
+@_add_options(_start_options)
+def allsky_start_cmd(port, host, log_level, allsky):
+    overrides = _parse_allsky_overrides(allsky)
+    _run_proxy(host, port, log_level, overrides)

arcsecond/imagesources/commands.py

@@ -0,0 +1,121 @@
+"""
+Live-image proxy server for the Arcsecond CLI.
+
+Why this exists
+---------------
+The Arcsecond backend runs inside Docker Desktop (Windows / macOS), which does
+not forward USB devices — and may not have access to host filesystem paths
+where all-sky software writes images. This small aiohttp server runs
+**natively** on the host and exposes:
+
+    GET  /detect             → JSON list of available sources
+    WS   /stream/{id}        → continuous JPEG-frame stream (base64-in-JSON)
+
+Source ids look like ``webcam:0`` or ``allsky:roof``. For backward
+compatibility, a bare numeric id (``/stream/0``) is treated as ``webcam:0``.
+
+The backend reads the ``LIVE_IMAGE_PROXY_URL`` environment variable
+(``WEBCAM_PROXY_URL`` is accepted as a deprecated fallback). When set, it
+delegates detection and streaming to this proxy.
+
+Start with:
+    arcsecond webcam start          # webcams only (legacy)
+    arcsecond imagesources start    # webcams + all-sky
+"""
+
+import asyncio
+import base64
+import json
+import logging
+from dataclasses import asdict
+from typing import Optional
+
+from .registry import AllskyOverride, Registry
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# aiohttp request handlers
+# ---------------------------------------------------------------------------
+
+async def handle_health(request):
+    from aiohttp import web
+    return web.json_response({'status': 'ok'})
+
+
+async def handle_detect(request):
+    from aiohttp import web
+    registry: Registry = request.app['registry']
+    loop = asyncio.get_running_loop()
+    infos = await loop.run_in_executor(None, registry.detect)
+    return web.json_response([asdict(i) for i in infos])
+
+
+async def handle_stream(request):
+    from aiohttp import web
+
+    registry: Registry = request.app['registry']
+    source_id = request.match_info['id']
+
+    ws = web.WebSocketResponse()
+    await ws.prepare(request)
+    logger.info("Live-image proxy: client connected to stream %s", source_id)
+
+    try:
+        source = registry.open_source(source_id)
+    except KeyError as e:
+        logger.error("Live-image proxy: %s", e)
+        await ws.send_str(json.dumps({'type': 'error', 'message': str(e)}))
+        await ws.close()
+        return ws
+
+    try:
+        await source.open()
+    except Exception as e:
+        logger.error("Live-image proxy: cannot open %s: %s", source_id, e)
+        await ws.send_str(json.dumps({'type': 'error', 'message': str(e)}))
+        await ws.close()
+        return ws
+
+    try:
+        while not ws.closed:
+            jpeg: Optional[bytes] = await source.read()
+            if jpeg is not None:
+                b64 = base64.b64encode(jpeg).decode('ascii')
+                await ws.send_str(json.dumps({
+                    'type': 'frame',
+                    'format': 'jpeg/base64',
+                    'data': b64,
+                }))
+            await asyncio.sleep(source.poll_interval)
+    except (ConnectionResetError, ConnectionError):
+        logger.info("Live-image proxy: client disconnected from %s.", source_id)
+    finally:
+        await source.close()
+        logger.info("Live-image proxy: %s released.", source_id)
+
+    return ws
+
+
+# ---------------------------------------------------------------------------
+# Server entry-point
+# ---------------------------------------------------------------------------
+
+def run(
+    host: str = '0.0.0.0',
+    port: int = 8765,
+    allsky_overrides: Optional[list[AllskyOverride]] = None,
+):
+    """Build and run the aiohttp application (blocking)."""
+    from aiohttp import web
+
+    app = web.Application()
+    app['registry'] = Registry(allsky_overrides=allsky_overrides)
+
+    app.router.add_get('/health', handle_health)
+    app.router.add_get('/detect', handle_detect)
+    app.router.add_get('/stream/{id}', handle_stream)
+
+    logger.info("Live-image proxy starting on %s:%d", host, port)
+    web.run_app(app, host=host, port=port, print=lambda msg: logger.info(msg))

arcsecond/imagesources/proxy.py

@@ -0,0 +1,71 @@
+"""
+Source resolution and discovery for the proxy.
+
+Webcams are auto-detected by probing OpenCV device indices.
+All-sky sources are either auto-discovered at well-known paths or registered
+explicitly by the user (``arcsecond allsky add``-style overrides passed at
+``run()`` time).
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Optional
+
+from .sources.base import FrameSource, SourceInfo
+from .sources.filewatch import FileWatchSource, detect_allsky
+from .sources.opencv import OpenCVWebcamSource, detect_webcams
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AllskyOverride:
+    id: str          # bare id, will be prefixed with "allsky:"
+    path: str        # file path or glob
+    label: Optional[str] = None
+
+
+class Registry:
+    """Discover and instantiate sources on demand."""
+
+    def __init__(self, allsky_overrides: Optional[list[AllskyOverride]] = None):
+        self.allsky_overrides = allsky_overrides or []
+
+    def detect(self) -> list[SourceInfo]:
+        infos: list[SourceInfo] = []
+        try:
+            infos.extend(detect_webcams())
+        except Exception as e:
+            logger.warning("Webcam detection failed: %s", e)
+
+        if self.allsky_overrides:
+            for o in self.allsky_overrides:
+                src = FileWatchSource(f"allsky:{o.id}", o.path, o.label)
+                infos.append(src.info())
+        else:
+            infos.extend(detect_allsky())
+
+        return infos
+
+    def open_source(self, source_id: str) -> FrameSource:
+        # Backward-compat: bare numeric ids → webcam.
+        if source_id.isdigit():
+            return OpenCVWebcamSource(int(source_id))
+
+        kind, _, name = source_id.partition(":")
+        if not name:
+            raise KeyError(f"Unknown source id: {source_id!r}")
+
+        if kind == "webcam":
+            return OpenCVWebcamSource(int(name))
+
+        if kind == "allsky":
+            for o in self.allsky_overrides:
+                if o.id == name:
+                    return FileWatchSource(source_id, o.path, o.label)
+            for info in detect_allsky():
+                if info.id == source_id:
+                    return FileWatchSource(source_id, info.extra["path"], info.label)
+            raise KeyError(f"No all-sky source registered as {source_id!r}")
+
+        raise KeyError(f"Unknown source kind: {kind!r}")