swap-cli 0.1.1__tar.gz → 0.1.2__tar.gz

{swap_cli-0.1.1 → swap_cli-0.1.2}/.gitignore

@@ -57,3 +57,6 @@ swap-config.toml
 # Recordings
 recordings/
 *.mp4
+
+# Watermark capture source (throwaway; cropped template lives in assets/)
+wm_source.*

{swap_cli-0.1.1 → swap_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swap-cli
-Version: 0.1.1
+Version: 0.1.2
 Summary: Real-time deepfake on your desktop. Bring your own Decart API key.
 Project-URL: Homepage, https://github.com/BlAcQW/swap-cli
 Project-URL: Repository, https://github.com/BlAcQW/swap-cli

{swap_cli-0.1.1 → swap_cli-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "swap-cli"
-version = "0.1.1"
+version = "0.1.2"
 description = "Real-time deepfake on your desktop. Bring your own Decart API key."
 authors = [{ name = "BlAcQW", email = "enochhenyo@gmail.com" }]
 readme = "README.md"
@@ -106,6 +106,9 @@ allow-direct-references = true
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/swap_cli"]
+# Ship the bundled watermark template (and any future data assets) even
+# though *.png would otherwise be excluded by VCS-based file selection.
+artifacts = ["src/swap_cli/assets/*.png"]
 
 [tool.ruff]
 line-length = 100

{swap_cli-0.1.1 → swap_cli-0.1.2}/src/swap_cli/cli.py

@@ -194,6 +194,36 @@ def run(
             ),
         ),
     ] = True,
+    remove_watermark: Annotated[
+        bool | None,
+        typer.Option(
+            "--remove-watermark/--no-remove-watermark",
+            help=(
+                "Remove the Decart 'AI Generated' watermark from each frame "
+                "via template-match + inpaint. A default template ships with "
+                "the app; capture your own with `swap capture-watermark` or "
+                "the W key. Omit to use your saved preference."
+            ),
+        ),
+    ] = None,
+    watermark_template: Annotated[
+        Path | None,
+        typer.Option(
+            "--watermark-template",
+            help="Path to the watermark template PNG (overrides saved config).",
+        ),
+    ] = None,
+    watermark_removal: Annotated[
+        str | None,
+        typer.Option(
+            "--watermark-removal",
+            help=(
+                "How to hide the badge: 'reconstruct' (rebuild the background, "
+                "invisible) or 'blur' (smear it into a soft patch — always works). "
+                "Omit to use your saved preference."
+            ),
+        ),
+    ] = None,
 ) -> None:
     """Open a realtime Decart session and stream until you press Q."""
     cfg = config.load()
@@ -219,6 +249,17 @@ def run(
         if status.cached:
             console.print(f"[dim]license: cached ({status.reason})[/dim]")
 
+    # Tri-state precedence: an explicit --remove-watermark / --no-remove-
+    # watermark wins; when omitted (None) fall back to saved config. This
+    # keeps --no-remove-watermark working even when config defaults it on.
+    wm_enabled = (
+        remove_watermark if remove_watermark is not None else cfg.remove_watermark
+    )
+    wm_template = (
+        str(watermark_template) if watermark_template else cfg.watermark_template
+    )
+    wm_removal = watermark_removal if watermark_removal is not None else cfg.watermark_removal
+
     opts = RunOptions(
         decart_api_key=cfg.decart_api_key,
         reference=reference,
@@ -227,15 +268,24 @@ def run(
         camera_device=device,
         record=record,
         virtual_camera=vcam,
+        remove_watermark=wm_enabled,
+        watermark_template=wm_template,
+        watermark_method=cfg.watermark_method,
+        watermark_removal=wm_removal,
+        watermark_threshold=cfg.watermark_threshold,
+        watermark_inpaint_radius=cfg.watermark_inpaint_radius,
+        watermark_template_width=cfg.watermark_template_width,
     )
 
+    _wm_status = "[green]on[/green]" if opts.remove_watermark else "[dim]off[/dim]"
     console.print(
         Panel.fit(
             f"model: [bold]{opts.model_name}[/bold]\n"
             f"reference: {opts.reference or '[dim]none[/dim]'}\n"
             f"camera device: {opts.camera_device}\n"
-            f"record: {opts.record or '[dim]off[/dim]'}\n\n"
-            "[dim]Press [bold]Q[/bold] in the preview window to quit.[/dim]",
+            f"record: {opts.record or '[dim]off[/dim]'}\n"
+            f"watermark removal: {_wm_status}\n\n"
+            "[dim]Press [bold]Q[/bold] to quit · [bold]W[/bold] to capture the watermark.[/dim]",
             title="▶ swap · live",
             border_style="cyan",
         )
@@ -250,6 +300,78 @@ def run(
         raise typer.Exit(1) from err
 
 
+@app.command(name="capture-watermark")
+def capture_watermark(
+    snapshot: Annotated[
+        Path,
+        typer.Argument(
+            help="Snapshot PNG/JPG containing the watermark to crop out.",
+        ),
+    ],
+    roi: Annotated[
+        str | None,
+        typer.Option(
+            "--roi",
+            help="Crop region as x,y,w,h in pixels. Omit to crop interactively.",
+        ),
+    ] = None,
+) -> None:
+    """Crop a watermark template from a snapshot for `--remove-watermark`.
+
+    Take a normal snapshot of a live frame that shows the badge, then run
+    this to save the watermark template. Pass --roi x,y,w,h for a headless
+    crop, or omit it to drag-select in a window.
+    """
+    import cv2  # local import: cv2 isn't needed for `swap version` etc.
+
+    from .display import default_watermark_template_path
+
+    if not snapshot.exists():
+        err_console.print(f"[red]snapshot not found: {snapshot}[/red]")
+        raise typer.Exit(2)
+    img = cv2.imread(str(snapshot))
+    if img is None:
+        err_console.print(f"[red]could not read image: {snapshot}[/red]")
+        raise typer.Exit(2)
+
+    if roi:
+        try:
+            x, y, w, h = (int(v.strip()) for v in roi.split(","))
+        except ValueError as err:
+            err_console.print("[red]--roi must be 'x,y,w,h' integers[/red]")
+            raise typer.Exit(2) from err
+    else:
+        try:
+            x, y, w, h = (int(v) for v in cv2.selectROI("select watermark", img))
+            cv2.destroyAllWindows()
+        except Exception as err:  # noqa: BLE001 — headless without a display
+            err_console.print(
+                f"[red]interactive crop unavailable ({err}). Pass --roi x,y,w,h.[/red]"
+            )
+            raise typer.Exit(2) from err
+
+    if w <= 0 or h <= 0:
+        err_console.print("[red]empty selection — nothing saved.[/red]")
+        raise typer.Exit(2)
+
+    crop = img[y : y + h, x : x + w]
+    dest = default_watermark_template_path()
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if not cv2.imwrite(str(dest), crop):
+        err_console.print(f"[red]failed to write template → {dest}[/red]")
+        raise typer.Exit(1)
+    config.update(watermark_template=str(dest))
+    console.print(
+        Panel.fit(
+            f"saved: [bold]{dest}[/bold]\n"
+            f"region: {x},{y} {w}×{h}\n\n"
+            "[dim]Run [bold]swap run --remove-watermark[/bold] to use it.[/dim]",
+            title="✂ watermark template",
+            border_style="green",
+        )
+    )
+
+
 @app.command()
 def voice(
     voice: Annotated[
@@ -1088,6 +1210,11 @@ async def _doctor() -> None:
             f"[yellow]⚠ {vcam_check.label} — {vcam_check.hint}[/yellow]",
         )
 
+    # Watermark removal template (Sprint 15) — show whether a captured
+    # template exists and is loadable, so users know if --remove-watermark
+    # will actually do anything.
+    table.add_row("watermark template", _watermark_template_label())
+
     # macOS-only: customtkinter needs Tcl/Tk >= 8.6.9. The system Python
     # ships 8.5.9 which fails silently or renders broken windows. Surface
     # this here so users know to switch to python.org Python or
@@ -1106,6 +1233,37 @@ async def _doctor() -> None:
         sys.exit(1)
 
 
+def _watermark_template_label() -> str:
+    cfg = config.load()
+    source = "custom"
+    template = cfg.watermark_template
+    if not template:
+        from .watermark import bundled_template_path
+
+        bundled = bundled_template_path()
+        if bundled is None:
+            return "[dim]none — run `swap capture-watermark`[/dim]"
+        template = str(bundled)
+        source = "bundled default"
+    path = Path(template)
+    if not path.exists():
+        return f"[yellow]⚠ missing: {path}[/yellow]"
+    try:
+        import cv2
+
+        img = cv2.imread(str(path))
+        if img is None or img.size == 0:
+            return f"[yellow]⚠ unreadable: {path}[/yellow]"
+        h, w = img.shape[:2]
+        ref = cfg.watermark_template_width or 1280
+        return (
+            f"[green]✓ {w}×{h} {path.name} ({source})[/green] "
+            f"[dim]· multi-scale match (ref {ref}px)[/dim]"
+        )
+    except Exception:  # noqa: BLE001 — doctor must never crash
+        return f"[green]✓ {path.name} ({source})[/green]"
+
+
 def _camera_probe_label() -> str:
     try:
         import cv2

{swap_cli-0.1.1 → swap_cli-0.1.2}/src/swap_cli/config.py

@@ -38,6 +38,22 @@ class Config:
     # (skip Faiss retrieval). Trades timbre quality for big speedup —
     # essential on weak GPUs or when using voices with huge .index files.
     voice_fast: bool = False
+    # Sprint 15: per-frame watermark removal. The Decart "AI Generated"
+    # badge roams the frame, so removal runs template-match + inpaint on
+    # every frame. All optional — older config files load fine. Off by
+    # default so existing users aren't surprised by the latency cost.
+    remove_watermark: bool = False
+    watermark_template: str | None = None  # path to captured watermark PNG
+    watermark_method: str = "template"  # "template" | "threshold"
+    # How a located badge is hidden: "reconstruct" (invisible rebuild) or
+    # "blur" (smear into an unreadable soft patch). Detection is separate.
+    watermark_removal: str = "reconstruct"  # "reconstruct" | "blur"
+    watermark_threshold: float = 0.50  # matchTemplate confidence gate (0..1)
+    watermark_inpaint_radius: int = 3
+    # Frame width the captured template was grabbed at. Decart's output
+    # resolution varies, so this centers the multi-scale match exactly for a
+    # user-captured template. None → the 1280px bundled-default assumption.
+    watermark_template_width: int | None = None
 
     @property
     def is_complete(self) -> bool:
@@ -69,6 +85,13 @@ def load() -> Config:
         last_voice_output=_int_or_none(data.get("last_voice_output")),
         voice_engine=_clean(data.get("voice_engine")) or "rvc",
         voice_fast=bool(data.get("voice_fast", False)),
+        remove_watermark=bool(data.get("remove_watermark", False)),
+        watermark_template=_clean(data.get("watermark_template")),
+        watermark_method=_clean(data.get("watermark_method")) or "template",
+        watermark_removal=_clean(data.get("watermark_removal")) or "reconstruct",
+        watermark_threshold=_float_or_none(data.get("watermark_threshold")) or 0.50,
+        watermark_inpaint_radius=_int_or_none(data.get("watermark_inpaint_radius")) or 3,
+        watermark_template_width=_int_or_none(data.get("watermark_template_width")),
     )
 
 
@@ -98,6 +121,20 @@ def save(cfg: Config) -> Path:
         body.append(f'voice_engine = "{_escape(cfg.voice_engine)}"')
     if cfg.voice_fast:
         body.append("voice_fast = true")
+    if cfg.remove_watermark:
+        body.append("remove_watermark = true")
+    if cfg.watermark_template:
+        body.append(f'watermark_template = "{_escape(cfg.watermark_template)}"')
+    if cfg.watermark_method and cfg.watermark_method != "template":
+        body.append(f'watermark_method = "{_escape(cfg.watermark_method)}"')
+    if cfg.watermark_removal and cfg.watermark_removal != "reconstruct":
+        body.append(f'watermark_removal = "{_escape(cfg.watermark_removal)}"')
+    if cfg.watermark_threshold != 0.50:
+        body.append(f"watermark_threshold = {cfg.watermark_threshold}")
+    if cfg.watermark_inpaint_radius != 3:
+        body.append(f"watermark_inpaint_radius = {cfg.watermark_inpaint_radius}")
+    if cfg.watermark_template_width is not None:
+        body.append(f"watermark_template_width = {cfg.watermark_template_width}")
 
     text = "\n".join(body) + "\n"
     tmp = path.with_suffix(path.suffix + ".tmp")
@@ -124,6 +161,17 @@ def update(**kwargs: Any) -> Config:
         last_voice_output=kwargs.get("last_voice_output", current.last_voice_output),
         voice_engine=kwargs.get("voice_engine", current.voice_engine),
         voice_fast=kwargs.get("voice_fast", current.voice_fast),
+        remove_watermark=kwargs.get("remove_watermark", current.remove_watermark),
+        watermark_template=kwargs.get("watermark_template", current.watermark_template),
+        watermark_method=kwargs.get("watermark_method", current.watermark_method),
+        watermark_removal=kwargs.get("watermark_removal", current.watermark_removal),
+        watermark_threshold=kwargs.get("watermark_threshold", current.watermark_threshold),
+        watermark_inpaint_radius=kwargs.get(
+            "watermark_inpaint_radius", current.watermark_inpaint_radius
+        ),
+        watermark_template_width=kwargs.get(
+            "watermark_template_width", current.watermark_template_width
+        ),
     )
     save(merged)
     return merged
@@ -148,5 +196,11 @@ def _int_or_none(value: Any) -> int | None:
     return None
 
 
+def _float_or_none(value: Any) -> float | None:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    return None
+
+
 def _escape(value: str) -> str:
     return value.replace("\\", "\\\\").replace('"', '\\"')

swap_cli-0.1.2/src/swap_cli/display.py

@@ -0,0 +1,350 @@
+"""Render an aiortc remote video track in a cv2.imshow window.
+
+Also handles snapshot-on-keypress, optional MP4 recording, and
+(Sprint 14k) optional output to a virtual camera device so apps like
+Zoom/Meet/Discord see the deepfake stream directly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from contextlib import suppress
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import cv2
+import numpy as np
+
+if TYPE_CHECKING:
+    from aiortc.mediastreams import MediaStreamTrack
+
+    from .watermark import WatermarkRemover
+
+
+WINDOW_TITLE = "swap — Lucy 2 live"
+
+
+class Display:
+    """Pulls frames from a remote MediaStreamTrack and renders them.
+
+    Press Q in the window or call `stop()` to terminate the loop.
+    """
+
+    def __init__(
+        self,
+        track: MediaStreamTrack,
+        *,
+        record_path: Path | None = None,
+        on_quit: callable = lambda: None,  # type: ignore[assignment]
+        virtual_camera: bool = False,
+        watermark: WatermarkRemover | None = None,
+        show_window: bool = True,
+    ) -> None:
+        self._track = track
+        self._record_path = record_path
+        self._on_quit = on_quit
+        self._virtual_camera = virtual_camera
+        # Show the cv2 preview window. False in GUI mode: the session runs on a
+        # worker thread, and macOS forbids OpenCV HighGUI off the main thread, so
+        # the GUI renders frames itself (tkinter, main thread) via latest_frame().
+        self._show_window = show_window
+        # Sprint 15: optional per-frame watermark remover. None = no-op.
+        # Injected as a configured instance so _loop stays thin and the
+        # remover is unit-testable in isolation.
+        self._watermark = watermark
+        self._writer: cv2.VideoWriter | None = None
+        # pyvirtualcam.Camera — lazy-init on first frame so we know the
+        # actual width/height from Decart's stream rather than guessing.
+        self._vcam: Any = None
+        self._task: asyncio.Task[None] | None = None
+        self._stopped = asyncio.Event()
+        self._latest_bgr: np.ndarray | None = None
+        # Raw (pre-removal) frame, kept so the W-key capture grabs the badge
+        # even while watermark removal is on.
+        self._latest_raw_bgr: np.ndarray | None = None
+
+    def start(self) -> None:
+        self._task = asyncio.create_task(self._loop())
+
+    async def stop(self) -> None:
+        self._stopped.set()
+        if self._task:
+            self._task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._task
+        if self._writer is not None:
+            self._writer.release()
+        if self._vcam is not None:
+            with suppress(Exception):
+                self._vcam.close()
+            self._vcam = None
+        if self._show_window:
+            cv2.destroyAllWindows()
+
+    def snapshot(self, dest: Path) -> bool:
+        """Save the most recent rendered frame as JPEG. Returns success."""
+        if self._latest_bgr is None:
+            return False
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        return cv2.imwrite(str(dest), self._latest_bgr)
+
+    def latest_frame(self) -> np.ndarray | None:
+        """Most recent processed (cleaned) frame — for the in-app GUI preview.
+        The render loop rebinds this each frame, so the read is atomic."""
+        return self._latest_bgr
+
+    def latest_raw_frame(self) -> np.ndarray | None:
+        """Most recent RAW (pre-removal) frame — for GUI watermark capture."""
+        return self._latest_raw_bgr
+
+    async def _loop(self) -> None:
+        if self._show_window:
+            cv2.namedWindow(WINDOW_TITLE, cv2.WINDOW_NORMAL)
+            cv2.resizeWindow(WINDOW_TITLE, 960, 540)
+        first_frame = True
+        try:
+            while not self._stopped.is_set():
+                frame = await self._track.recv()
+                bgr = frame.to_ndarray(format="bgr24")
+                self._latest_raw_bgr = bgr  # keep the un-cleaned frame for W capture
+                # Sprint 15: strip the Decart watermark before anything
+                # downstream sees the frame. process() never raises — it
+                # returns the frame unchanged on any failure.
+                if self._watermark is not None:
+                    bgr = self._watermark.process(bgr)
+                self._latest_bgr = bgr
+                self._maybe_init_writer(bgr.shape, fps_guess=20)
+                if self._writer is not None:
+                    self._writer.write(bgr)
+                # Sprint 14k: also push the frame to the OBS Virtual Camera
+                # driver so Zoom/Meet/Discord pick it up as a real camera.
+                # pyvirtualcam expects RGB.
+                if self._virtual_camera:
+                    self._maybe_init_vcam(bgr.shape, fps_guess=20)
+                    if self._vcam is not None:
+                        try:
+                            rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)
+                            self._vcam.send(rgb)
+                            self._vcam.sleep_until_next_frame()
+                        except Exception as err:  # noqa: BLE001
+                            print(f"[display] vcam send error: {err}", flush=True)
+                            # Don't tear the driver down on a single bad frame.
+                if not self._show_window:
+                    # GUI renders the preview itself (tkinter, main thread) and
+                    # drives capture/stop — no cv2 window/keys here. Yield so a
+                    # non-vcam session doesn't spin the loop hot.
+                    if not self._virtual_camera:
+                        await asyncio.sleep(0)
+                    first_frame = False
+                    continue
+                cv2.imshow(WINDOW_TITLE, bgr)
+                if first_frame:
+                    # Flash topmost so the cv2 window pops above the tk GUI on
+                    # Windows. We don't want it pinned forever — just one beat.
+                    with suppress(Exception):
+                        cv2.setWindowProperty(WINDOW_TITLE, cv2.WND_PROP_TOPMOST, 1)
+                        cv2.waitKey(1)
+                        cv2.setWindowProperty(WINDOW_TITLE, cv2.WND_PROP_TOPMOST, 0)
+                    first_frame = False
+                key = cv2.waitKey(1) & 0xFF
+                if key in (ord("q"), ord("Q"), 27):  # q or ESC
+                    self._on_quit()
+                    self._stopped.set()
+                    break
+                if key in (ord("w"), ord("W")):  # Sprint 15: capture watermark
+                    self._capture_watermark_template()
+        except asyncio.CancelledError:
+            raise
+        except Exception as err:  # noqa: BLE001 — show + exit cleanly
+            # The Decart remote track raises (often with an empty message) when
+            # the connection drops. End the session cleanly so it doesn't hang
+            # in "reconnecting" — the user can click Live again.
+            detail = str(err) or err.__class__.__name__
+            print(f"[display] stream ended: {detail} — stopping session.", flush=True)
+            with suppress(Exception):
+                self._on_quit()
+            self._stopped.set()
+        finally:
+            if self._show_window:
+                cv2.destroyAllWindows()
+
+    def capture_watermark(self, roi: tuple[int, int, int, int]) -> None:
+        """Public entry for the GUI: capture the badge template from a caller-
+        supplied ROI (the GUI's tk drag-selector), instead of cv2.selectROI."""
+        self._capture_watermark_template(roi=roi)
+
+    def _capture_watermark_template(
+        self, roi: tuple[int, int, int, int] | None = None
+    ) -> None:
+        """Select the watermark on the current frame and save it as the template
+        PNG (Sprint 15). `roi` is supplied by the GUI's tk selector; when None
+        (CLI / cv2-window mode) we fall back to cv2.selectROI on the W key.
+
+        Captures from the RAW (pre-removal) frame so it works even while
+        removal is on but not matching. Persists the path AND the frame width
+        so the multi-scale match centers exactly, then HOT-RELOADS the live
+        remover so removal starts immediately — no restart needed.
+        """
+        # Prefer the raw frame; fall back to the displayed one.
+        source = self._latest_raw_bgr
+        if source is None:
+            source = self._latest_bgr
+        if source is None:
+            print("[display] no frame yet — can't capture watermark.", flush=True)
+            return
+        try:
+            from . import config as _config
+
+            if roi is None:
+                roi = cv2.selectROI(
+                    "select watermark — ENTER to save, C to cancel",
+                    source,
+                    showCrosshair=False,
+                )
+                cv2.destroyWindow("select watermark — ENTER to save, C to cancel")
+            x, y, w, h = (int(v) for v in roi)
+            if w <= 0 or h <= 0:
+                print("[display] watermark capture cancelled.", flush=True)
+                return
+            # Guard against a stray click saving a junk template that then
+            # matches nothing — the badge is ~150–260px wide.
+            if w < 20 or h < 10:
+                print(
+                    f"[display] selection too small ({w}x{h}) — press W again "
+                    "and drag a box around the whole badge.",
+                    flush=True,
+                )
+                return
+            crop = source[y : y + h, x : x + w]
+            crop = _tighten_to_badge(crop)  # shrink a loose box to the strokes
+            frame_width = int(source.shape[1])
+            dest = default_watermark_template_path()
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            if not cv2.imwrite(str(dest), crop):
+                print(f"[display] failed to write template → {dest}", flush=True)
+                return
+            _config.update(
+                watermark_template=str(dest),
+                watermark_template_width=frame_width,
+            )
+            print(
+                f"[display] watermark template saved → {dest} "
+                f"(from {frame_width}px-wide frame)",
+                flush=True,
+            )
+            # Hot-reload: rebuild the live remover from the just-saved config so
+            # removal starts THIS frame — no restart. Pressing W is a clear
+            # intent to remove, so we enable even if the toggle was off.
+            from .watermark import WatermarkRemover
+
+            new = WatermarkRemover.from_config(_config.load(), enabled=True)
+            if new is not None:
+                self._watermark = new
+                print(
+                    "[display] watermark removal now using the captured template "
+                    "(live) — if the badge is still visible, press W again and "
+                    "box it tighter.",
+                    flush=True,
+                )
+        except Exception as err:  # noqa: BLE001 — capture is best-effort
+            print(f"[display] watermark capture error: {err}", flush=True)
+
+    def _maybe_init_writer(self, shape: tuple[int, ...], fps_guess: int) -> None:
+        if self._record_path is None or self._writer is not None:
+            return
+        h, w = shape[:2]
+        fourcc = cv2.VideoWriter_fourcc(*"mp4v")  # type: ignore[attr-defined]
+        self._record_path.parent.mkdir(parents=True, exist_ok=True)
+        self._writer = cv2.VideoWriter(str(self._record_path), fourcc, fps_guess, (w, h))
+
+    def _maybe_init_vcam(self, shape: tuple[int, ...], fps_guess: int) -> None:
+        """Open pyvirtualcam.Camera on the first frame so we use the
+        actual stream resolution. Silently no-ops if pyvirtualcam isn't
+        installed or no virtual camera driver is registered — preview
+        window keeps working in that case."""
+        if self._vcam is not None:
+            return
+        try:
+            import pyvirtualcam  # type: ignore[import-not-found]
+        except ImportError:
+            # Pure-Python wrapper missing; ship hint via the doctor row.
+            self._virtual_camera = False
+            print(
+                "[display] vcam: pyvirtualcam not installed — `pip install pyvirtualcam`",
+                flush=True,
+            )
+            return
+        h, w = shape[:2]
+        try:
+            # backend=None lets pyvirtualcam pick the right one per OS:
+            # Windows → OBS Virtual Camera, macOS → OBS, Linux → v4l2loopback.
+            self._vcam = pyvirtualcam.Camera(width=w, height=h, fps=fps_guess)
+            print(
+                f"[display] vcam ready: '{self._vcam.device}' "
+                f"{w}x{h}@{fps_guess}fps — Zoom/Meet/Discord can pick it now.",
+                flush=True,
+            )
+        except Exception as err:  # noqa: BLE001
+            # Driver not installed, busy, or fps unsupported. Disable vcam
+            # for this session and keep the preview window healthy.
+            self._virtual_camera = False
+            self._vcam = None
+            print(
+                f"[display] vcam unavailable: {err}\n"
+                "[display] Install OBS Studio for the OBS Virtual Camera driver: "
+                "https://obsproject.com/download",
+                flush=True,
+            )
+
+
+def _tighten_to_badge(crop: np.ndarray) -> np.ndarray:
+    """Shrink a (possibly loose) selection to the badge's bright strokes, so a
+    sloppy drag still yields a tight, background-free template that matches
+    with high confidence. Uses the same white top-hat as the matcher; returns
+    the original crop if no clear strokes are found."""
+    try:
+        if crop.size == 0 or crop.shape[0] < 8 or crop.shape[1] < 8:
+            return crop
+        gray = cv2.cvtColor(crop, cv2.COLOR_BGR2GRAY)
+        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (21, 21))
+        top = cv2.morphologyEx(gray, cv2.MORPH_TOPHAT, kernel)
+        _ret, strokes = cv2.threshold(top, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+        ys, xs = np.where(strokes > 0)
+        if xs.size < 20:  # not enough signal — keep the user's box
+            return crop
+        m = 6  # small margin around the strokes
+        x0 = max(0, int(xs.min()) - m)
+        y0 = max(0, int(ys.min()) - m)
+        x1 = min(crop.shape[1], int(xs.max()) + m + 1)
+        y1 = min(crop.shape[0], int(ys.max()) + m + 1)
+        tight = crop[y0:y1, x0:x1]
+        if tight.shape[0] < 8 or tight.shape[1] < 20:
+            return crop
+        print(
+            f"[display] tightened selection {crop.shape[1]}x{crop.shape[0]} "
+            f"-> {tight.shape[1]}x{tight.shape[0]} (badge strokes)",
+            flush=True,
+        )
+        return tight
+    except Exception:  # noqa: BLE001 — tightening is best-effort
+        return crop
+
+
+def default_watermark_template_path() -> Path:
+    """Canonical location for the captured watermark template PNG."""
+    from platformdirs import user_config_dir
+
+    from .config import APP_NAME
+
+    return Path(user_config_dir(APP_NAME)) / "watermarks" / "watermark.png"
+
+
+def default_snapshot_path() -> Path:
+    ts = time.strftime("%Y%m%d-%H%M%S")
+    return Path.cwd() / "snapshots" / f"swap-{ts}.jpg"
+
+
+def default_recording_path() -> Path:
+    ts = time.strftime("%Y%m%d-%H%M%S")
+    return Path.cwd() / "recordings" / f"swap-{ts}.mp4"