Merge remote-tracking branch 'origin/master'

Author: InfantLab

README.md

@@ -100,13 +100,20 @@ curl -X POST "http://localhost:18011/api/v1/jobs/" \
 
 ### 3. Visualize Results
 
-No extra install needed — VideoAnnotator bundles [Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer) and serves it directly:
+No extra install needed — VideoAnnotator bundles [Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer) and serves it directly. `setup-db` (and `generate-token`) print a one-click link that logs the viewer in for you:
 
 ```
-Open http://localhost:18011/viewer
+Connect the viewer with one click: http://localhost:18011/viewer-connect?token=...
 ```
 
-It's pre-configured to talk to this server, so your job results are one click away. Set `VIDEOANNOTATOR_ENABLE_VIEWER=false` if you'd rather not serve it.
+Open that link (not `/viewer` directly) the first time — it stores your API key where the viewer expects it and
+redirects you there. After that, `http://localhost:18011/viewer` remembers you.
+
+Without it, the viewer falls back to a built-in demo token that won't authenticate against your server, and the
+job list will show 401s — if that happens, open the viewer's **Settings** panel and paste in the key printed by
+`setup-db`/`generate-token` by hand instead.
+
+Set `VIDEOANNOTATOR_ENABLE_VIEWER=false` if you'd rather not serve it.
 
 **🎉 That's it!** You now have both automated video processing and interactive visualization.
 

src/videoannotator/api/main.py

@@ -9,6 +9,7 @@
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse
 from fastapi.staticfiles import StaticFiles
 
 from ..utils.logging_config import get_logger
@@ -111,6 +112,15 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
         "Background job processing started", extra={"component": "background_tasks"}
     )
 
+    # Warm up torch/CUDA in the background so the first client request to
+    # /api/v1/system/health (typically the viewer, right after startup)
+    # doesn't pay the one-time import cost itself.
+    import asyncio
+
+    from .startup import warm_up_torch
+
+    asyncio.get_running_loop().run_in_executor(None, warm_up_torch)
+
     # TODO: Initialize pipeline cache
 
     yield
@@ -223,6 +233,29 @@ async def health_check():
             "database": db_status,
         }
 
+    # One-click bridge for onboarding: stores an API token (from `setup-db` /
+    # `generate-token`) into the browser's localStorage under the keys the
+    # bundled viewer reads, then redirects to /viewer/. Avoids asking users to
+    # manually copy the token into the viewer's Settings page.
+    @app.get("/viewer-connect", response_class=HTMLResponse, include_in_schema=False)
+    async def viewer_connect(token: str = "", url: str = ""):
+        import json
+
+        html = f"""<!doctype html>
+<html><head><meta charset="utf-8"><title>Connecting Video Annotation Viewer…</title></head>
+<body style="font-family: system-ui, sans-serif; max-width: 32rem; margin: 4rem auto; text-align: center;">
+<p>Connecting the viewer to your VideoAnnotator server…</p>
+<p><a href="/viewer/">Click here</a> if you are not redirected automatically.</p>
+<script>
+  var token = {json.dumps(token)};
+  var url = {json.dumps(url)};
+  if (token) {{ localStorage.setItem('videoannotator_api_token', token); }}
+  if (url) {{ localStorage.setItem('videoannotator_api_url', url); }}
+  window.location.replace('/viewer/');
+</script>
+</body></html>"""
+        return HTMLResponse(content=html)
+
     _mount_viewer(app)
 
     return app

src/videoannotator/api/startup.py

@@ -4,6 +4,7 @@
 """
 
 import os
+import time
 
 from videoannotator.utils.logging_config import get_logger
 
@@ -12,6 +13,27 @@
 logger = get_logger("api")
 
 
+def warm_up_torch() -> None:
+    """Import torch and probe CUDA once, ahead of the first client request.
+
+    ``/api/v1/system/health`` lazily imports torch to report GPU info. On a
+    fresh process that import (plus CUDA context init) can take tens of
+    seconds, which the health endpoint would otherwise charge to whichever
+    client happens to call it first (typically the viewer, right after
+    startup). Doing it here, in a startup background thread, moves that cost
+    off the request path.
+    """
+    start = time.time()
+    try:
+        import torch
+
+        torch.cuda.is_available()
+    except Exception as e:
+        logger.debug(f"Torch warmup skipped: {e}")
+        return
+    logger.info(f"Torch warmup completed in {time.time() - start:.1f}s")
+
+
 def ensure_api_key_exists() -> tuple[str | None, bool]:
     """Ensure at least one API key exists, generating one if needed.
 

src/videoannotator/cli.py

@@ -6,7 +6,7 @@
 import typer
 import uvicorn
 
-from .config_env import MAX_CONCURRENT_JOBS, WORKER_POLL_INTERVAL
+from .config_env import API_PORT, MAX_CONCURRENT_JOBS, WORKER_POLL_INTERVAL
 from .validation.emotion_validator import validate_emotion_file
 from .version import __version__
 
@@ -1002,6 +1002,18 @@ def validate_emotion(
         typer.echo(f"[OK] Emotion file valid: {file}")
 
 
+def _viewer_connect_url(token: str, port: int = API_PORT) -> str:
+    """Build a one-click link that logs the bundled viewer into this server.
+
+    Opening it stores `token` under the localStorage key the viewer reads and
+    redirects to /viewer/, so users don't have to paste the key into the
+    viewer's Settings page by hand. See the `/viewer-connect` route.
+    """
+    from urllib.parse import quote
+
+    return f"http://localhost:{port}/viewer-connect?token={quote(token)}"
+
+
 @app.command("generate-token")
 def generate_token(
     user: str = typer.Option(None, "--user", help="User email address"),
@@ -1122,6 +1134,8 @@ def generate_token(
             '  curl -H "Authorization: Bearer $API_KEY" http://localhost:18011/api/v1/jobs'
         )
         typer.echo("")
+        typer.echo(f"Connect the viewer with one click: {_viewer_connect_url(raw_key)}")
+        typer.echo("")
 
         # Save to file if requested
         if output_file:
@@ -1225,12 +1239,15 @@ def setup_db(
 {key}
 ================================================
 Save this key now; it will not be shown again.
-""".strip().format(key=raw_key)
+
+Connect the viewer with one click: {url}
+""".strip().format(key=raw_key, url=_viewer_connect_url(raw_key))
         )
     else:
         typer.echo(
-            "[INFO] Admin already existed; no new API key generated. "
-            "Use generate-token for additional keys."
+            "[INFO] Admin already existed; no new API key generated (existing keys "
+            "cannot be displayed again). Run `uv run videoannotator generate-token` "
+            "to create a new one — it will also print a one-click viewer-connect link."
         )
 
 

src/videoannotator/pipelines/face_analysis/openface3_pipeline.py

@@ -429,6 +429,18 @@ def process(
         """
         if not self.is_initialized:
             self.initialize()
+        if not self.is_initialized:
+            reason = (
+                self._model_info.get(
+                    "unavailable_reason", "unknown initialization failure"
+                )
+                if self._model_info
+                else "unknown initialization failure"
+            )
+            raise RuntimeError(
+                f"OpenFace 3.0 is not available ({reason}); see "
+                "docs/installation/INSTALLATION.md for manual setup. Skipping this pipeline."
+            )
 
         self.logger.info(f"Processing video: {video_path}")
         start_processing_time = time.time()

src/videoannotator/registry/pipeline_loader.py

@@ -29,25 +29,46 @@ def load_all_pipelines(self) -> dict[str, type]:
         """
         self._registry.load()
         pipeline_classes = {}
+        # (stability_rank, name, class) candidates per family, used to pick which
+        # pipeline the short family alias (e.g. 'face') should resolve to.
+        stability_rank = {"stable": 0, "beta": 1, "experimental": 2}
+        family_candidates: dict[str, list[tuple[int, str, type]]] = {}
 
         for meta in self._registry.list():
             pipeline_class = self._load_pipeline_class(meta)
             if pipeline_class:
                 # Add primary name
                 pipeline_classes[meta.name] = pipeline_class
 
-                # Add common aliases based on pipeline_family
                 if meta.pipeline_family:
-                    # Short family name (e.g., 'face' for 'face_analysis')
-                    if meta.pipeline_family not in pipeline_classes:
-                        pipeline_classes[meta.pipeline_family] = pipeline_class
+                    family_candidates.setdefault(meta.pipeline_family, []).append(
+                        (
+                            stability_rank.get(meta.stability or "", 3),
+                            meta.name,
+                            pipeline_class,
+                        )
+                    )
 
                     # Add variant-based alias if applicable
                     if meta.variant:
                         variant_name = f"{meta.pipeline_family}_{meta.variant}"
                         if variant_name != meta.name:
                             pipeline_classes[variant_name] = pipeline_class
 
+        # Assign each family's short alias (e.g. 'face') to its most-stable
+        # loadable pipeline, rather than whichever happened to load first —
+        # otherwise an experimental variant can silently shadow a stable one
+        # just because metadata files are read in alphabetical order.
+        for family, candidates in family_candidates.items():
+            candidates.sort(key=lambda c: c[0])
+            best_rank, best_name, best_class = candidates[0]
+            pipeline_classes[family] = best_class
+            if len(candidates) > 1:
+                LOGGER.debug(
+                    f"Family alias '{family}' -> '{best_name}' "
+                    f"(candidates: {[c[1] for c in candidates]})"
+                )
+
         LOGGER.info(
             f"Loaded {len(set(pipeline_classes.values()))} unique pipeline classes "
             f"with {len(pipeline_classes)} total names/aliases"