docs: document MIRAGE_PROC_MAX_DIM & MIRAGE_DEBUG_OVERLAY; add swap debug vars; capture active providers

README.md

@@ -147,14 +147,39 @@ Pipeline stats (subset) from swap pipeline:
 | `MIRAGE_TURN_TLS_ONLY` | Filter TURN to TLS/TCP | `1` |
 | `MIRAGE_PREFER_H264` | Prefer H264 codec in SDP munging | `0` |
 | `MIRAGE_VOICE_ENABLE` | Enable voice processor stub | `0` |
-| `MIRAGE_PERSIST_MODELS` | Persist models under /data and symlink /app/models | `1` |
-| `MIRAGE_PERSIST_MODELS` | Persist models in /data (HF Space) via symlink | `1` |
+| `MIRAGE_PERSIST_MODELS` | Persist models in `/data/mirage_models` via symlink `/app/models` | `1` |
+| `MIRAGE_PROVISION_FRESH` | Force re-download of required models (ignores sentinel) | `0` |
+| `MIRAGE_PROC_MAX_DIM` | Max dimension (longest side) for processing downscale | `512` |
+| `MIRAGE_DEBUG_OVERLAY` | Draw green bbox + SWAP label on swapped faces | `0` |
+| `MIRAGE_SWAP_DEBUG` | Verbose per-frame swap decision logging | `0` |
 
 CodeFormer fidelity example:
 ```bash
 MIRAGE_CODEFORMER_FIDELITY=0.6
 ```
 
+### Processing Resolution & Visual Debug Overlay
+
+Two new controls help you verify that swapping is occurring and tune visual quality vs latency:
+
+| Control | Effect | Guidance |
+|---------|--------|----------|
+| `MIRAGE_PROC_MAX_DIM` | Caps the longest side of a frame before inference. Frames larger than this are downscaled for detection/swap, then returned at original size. | Raise (e.g. 640, 720) for crisper facial detail if GPU headroom allows; lower (384–512) to reduce latency on weaker GPUs. Minimum enforced is 64. |
+| `MIRAGE_DEBUG_OVERLAY` | When enabled (`1`), draws a green rectangle and the text `SWAP` over each face region that was swapped in the most recent frame. | Use temporarily to confirm active swapping; disable for production to avoid visual artifacts. |
+
+Example (higher detail + overlay for confirmation):
+```bash
+MIRAGE_PROC_MAX_DIM=640
+MIRAGE_DEBUG_OVERLAY=1
+```
+
+If you still perceive “no change” while counters show swaps:
+1. Ensure your reference image is a clear, well-lit, frontal face (avoid extreme angles / occlusions).
+2. Increase `MIRAGE_PROC_MAX_DIM` to 640 or 720 for sharper results.
+3. Temporarily enable `MIRAGE_DEBUG_OVERLAY=1` to visualize the swapped region.
+4. Check `/debug/pipeline` for `total_faces_swapped` and `swap_faces_last` > 0.
+
+
 ## 📋 Requirements
 
 - **GPU**: NVIDIA (Ampere+ recommended). CPU-only will be extremely slow.

swap_pipeline.py

@@ -80,6 +80,11 @@ class FaceSwapPipeline:
             raise ImportError("insightface (and its deps like onnxruntime) not available. Ensure onnxruntime, onnx, torch installed.")
         self.app = FaceAnalysis(name='buffalo_l', providers=providers)
         self.app.prepare(ctx_id=0, det_size=(640,640))
+        # Capture active providers after prepare (best effort)
+        try:
+            self._active_providers = getattr(self.app, 'providers', providers)
+        except Exception:
+            self._active_providers = providers
         # Load swapper
         model_path = INSWAPPER_ONNX_PATH
         if not os.path.isfile(model_path):
@@ -332,6 +337,15 @@ class FaceSwapPipeline:
             except Exception as e:
                 logger.debug(f"Swap failed for face: {e}")
         self._stats['total_faces_swapped'] += count
+        # Optional debug overlay for visual confirmation
+        if count > 0 and os.getenv('MIRAGE_DEBUG_OVERLAY', '0').lower() in ('1','true','yes','on'):
+            try:
+                for f in faces[:self.max_faces]:
+                    x1,y1,x2,y2 = f.bbox.astype(int)
+                    cv2.rectangle(out, (x1,y1), (x2,y2), (0,255,0), 2)
+                    cv2.putText(out, 'SWAP', (x1, max(0,y1-5)), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0,255,0), 1, cv2.LINE_AA)
+            except Exception:
+                pass
         if self.swap_debug:
             logger.debug(f'process_frame: detected={len(faces)} swapped={count} stride={self.codeformer_frame_stride} apply_cf={count>0 and (self._frame_index % self.codeformer_frame_stride == 0)}')
         # CodeFormer stride / face-region logic
@@ -391,12 +405,13 @@ class FaceSwapPipeline:
             codeformer_face_only=self.codeformer_face_only,
             codeformer_avg_latency_ms=cf_avg,
             max_faces=self.max_faces,
+            debug_overlay=os.getenv('MIRAGE_DEBUG_OVERLAY', '0'),
         )
         # Provider diagnostics (best-effort)
         try:  # pragma: no cover
             import onnxruntime as ort  # type: ignore
             info['available_providers'] = ort.get_available_providers()
-            info['active_providers'] = getattr(self.app, 'providers', None) if self.app else None
+            info['active_providers'] = getattr(self, '_active_providers', None)
         except Exception:
             pass
         return info

webrtc_server.py

@@ -383,13 +383,18 @@ class IncomingVideoTrack(MediaStreamTrack):
         img = frame.to_ndarray(format="bgr24")
         h, w, _ = img.shape
         proc_input = img
-        # Optionally downscale for processing to cap latency
+        # Optionally downscale for processing to cap latency (configurable)
         try:
-            if max(h, w) > 512:
-                scale_w = 512
-                scale_h = int(h * (512 / w)) if w >= h else 512
-                if w < h:
-                    scale_w = int(w * (512 / h))
+            max_dim_cfg = int(os.getenv('MIRAGE_PROC_MAX_DIM', '512') or '512')
+            if max_dim_cfg < 64:
+                max_dim_cfg = 64
+            if max(h, w) > max_dim_cfg:
+                if w >= h:
+                    scale_w = max_dim_cfg
+                    scale_h = int(h * (max_dim_cfg / w))
+                else:
+                    scale_h = max_dim_cfg
+                    scale_w = int(w * (max_dim_cfg / h))
                 proc_input = cv2.resize(img, (max(1, scale_w), max(1, scale_h)))
         except Exception as e:
             logger.debug(f"Video downscale skip: {e}")