Initial pipeline upload

Crop-inpaint-composite pipeline with LaMa (fast) and VACE-14B (quality) modes.

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

.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+env/
+.env
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE / tooling
+.idea/
+.vscode/
+.claude/
+*.swp
+*.swo
+
+# HF / model caches
+.cache/
+hub/
+*.ckpt
+*.pt
+*.bin
+*.safetensors
+
+# Local test artifacts
+*.mp4
+*.mov
+*.png
+*.jpg
+*.jpeg
+!**/assets/**
+
+# Logs
+*.log

README.md

@@ -1,12 +1,50 @@
 ---
-title: Watermark Remover
-emoji: 🦀
-colorFrom: gray
-colorTo: green
+title: Video Watermark Remover
+emoji: 🦎
+colorFrom: green
+colorTo: blue
 sdk: gradio
-sdk_version: 6.13.0
+sdk_version: "4.44.0"
 app_file: app.py
 pinned: false
+license: apache-2.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Video Watermark Remover
+
+Self-hosted Hugging Face Space for removing static, opaque watermarks from video footage.
+
+## Modes
+
+| Mode | Model | Speed | Best for |
+|------|-------|-------|----------|
+| **Fast** | LaMa (per-frame) | Seconds | Sky, water, foliage — low-frequency backgrounds |
+| **Quality** | Wan2.1-VACE-14B | ~2 min | Structured or textured backgrounds |
+
+## How it works
+
+1. Upload a video clip (≤15 seconds, 1080p)
+2. On the extracted first frame, **draw around the watermark** using the brush tool
+3. Choose **Fast** or **Quality** mode
+4. Hit **Remove Watermark** — the output is composited back at full 1080p
+
+### Crop-inpaint-composite
+
+The pipeline never runs the model on the full 1920×1080 frame. Instead:
+- Your drawn region determines a tight crop (expanded to a VACE-compatible resolution with surrounding context)
+- Only that crop (~7× fewer pixels) is processed by the model
+- The result is feather-blended back into the original frame
+- All other pixels are **byte-identical** to the source
+
+V-Log color metadata is preserved via FFmpeg flag passthrough.
+
+## Platform
+
+- ZeroGPU PRO (H200 MIG slice, 70 GB VRAM)
+- PyTorch 2.7.1 + diffusers
+
+## License
+
+- Pipeline code: Apache 2.0  
+- LaMa: Apache 2.0  
+- Wan2.1-VACE-14B: [Wan-AI license](https://huggingface.co/Wan-AI/Wan2.1-VACE-14B-diffusers)

app.py

@@ -0,0 +1,611 @@
+"""
+app.py
+------
+Gradio UI for the Video Watermark Remover Space (ZeroGPU PRO).
+
+Flow:
+  1. Upload video → extract first frame → display in ImageEditor for mask drawing
+  2. User brushes over the watermark
+  3. Preview Crop → shows crop region + mask overlay
+  4. Mode: Fast (LaMa) | Quality (VACE-14B)
+  5. Remove Watermark → runs pipeline → output video
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+import gradio as gr
+import numpy as np
+from PIL import Image, ImageDraw
+
+# ---------------------------------------------------------------------------
+# ZeroGPU spaces shim — import succeeds locally too
+# ---------------------------------------------------------------------------
+try:
+    import spaces  # type: ignore
+    HAS_SPACES = True
+except ImportError:
+    HAS_SPACES = False
+    class spaces:  # type: ignore
+        @staticmethod
+        def GPU(duration=60):
+            def decorator(fn):
+                return fn
+            return decorator
+
+# ---------------------------------------------------------------------------
+# Pipeline imports
+# ---------------------------------------------------------------------------
+from pipeline.crop import CropRegion, build_inpaint_mask, compute_crop_region, mask_to_bbox
+from pipeline.video import (
+    VideoMeta, VideoWorkspace,
+    attach_audio, extract_first_frame, extract_frames, frames_to_video, probe,
+)
+
+# ---------------------------------------------------------------------------
+# CSS — dark premium theme
+# ---------------------------------------------------------------------------
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+
+* { box-sizing: border-box; }
+
+body, .gradio-container {
+    font-family: 'Inter', sans-serif !important;
+    background: #0d1117 !important;
+    color: #e6edf3 !important;
+}
+
+.gradio-container {
+    max-width: 1200px !important;
+    margin: 0 auto !important;
+    padding: 24px !important;
+}
+
+/* Header */
+.header-block {
+    text-align: center;
+    padding: 32px 0 24px;
+}
+.header-block h1 {
+    font-size: 2rem;
+    font-weight: 700;
+    background: linear-gradient(135deg, #2dd4bf, #06b6d4);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    margin-bottom: 8px;
+}
+.header-block p {
+    color: #8b949e;
+    font-size: 0.95rem;
+}
+
+/* Cards */
+.card {
+    background: #161b22;
+    border: 1px solid #30363d;
+    border-radius: 12px;
+    padding: 20px;
+    margin-bottom: 16px;
+}
+.card-title {
+    font-size: 0.8rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: #8b949e;
+    margin-bottom: 12px;
+}
+
+/* Buttons */
+.btn-primary {
+    background: linear-gradient(135deg, #0f766e, #0e7490) !important;
+    border: none !important;
+    color: white !important;
+    font-weight: 600 !important;
+    border-radius: 8px !important;
+    padding: 10px 24px !important;
+    transition: opacity 0.2s !important;
+}
+.btn-primary:hover { opacity: 0.85 !important; }
+
+.btn-secondary {
+    background: #21262d !important;
+    border: 1px solid #30363d !important;
+    color: #e6edf3 !important;
+    font-weight: 500 !important;
+    border-radius: 8px !important;
+    transition: border-color 0.2s !important;
+}
+.btn-secondary:hover { border-color: #2dd4bf !important; }
+
+/* Status */
+.status-box textarea {
+    background: #0d1117 !important;
+    border: 1px solid #30363d !important;
+    color: #8b949e !important;
+    font-family: 'JetBrains Mono', monospace !important;
+    font-size: 0.82rem !important;
+    border-radius: 8px !important;
+}
+
+/* Mode radio */
+.mode-radio label { font-weight: 500 !important; }
+
+/* Steps badge */
+.step-badge {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 24px;
+    height: 24px;
+    border-radius: 50%;
+    background: #0f766e;
+    color: white;
+    font-size: 0.75rem;
+    font-weight: 700;
+    margin-right: 8px;
+}
+"""
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _get_mask_from_editor(editor_value: dict | None) -> np.ndarray | None:
+    """Extract a uint8 mask (H×W) from gr.ImageEditor output.
+
+    Unions all layers so drawings across multiple Gradio layers are preserved.
+    The returned array is at *display* resolution (the editor canvas size),
+    not necessarily source frame resolution. Always rescale with
+    _rescale_mask_to_frame() before using mask coordinates against VideoMeta.
+    """
+    if editor_value is None:
+        return None
+    raw_layers = [l for l in (editor_value.get("layers") or []) if l is not None]
+    if not raw_layers:
+        return None
+
+    combined: np.ndarray | None = None
+    for raw in raw_layers:
+        arr = np.array(raw)
+        if arr.ndim == 3 and arr.shape[2] == 4:
+            channel = arr[:, :, 3]          # RGBA → alpha
+        elif arr.ndim == 3:
+            channel = arr.max(axis=2)       # RGB → luminance max
+        else:
+            channel = arr.astype(np.uint8)  # already single-channel
+        combined = channel if combined is None else np.maximum(combined, channel)
+
+    return combined
+
+
+def _rescale_mask_to_frame(
+    raw_mask: np.ndarray,
+    target_w: int,
+    target_h: int,
+) -> np.ndarray:
+    """Rescale a mask from editor/display resolution to full source-frame resolution.
+
+    gr.ImageEditor renders at a fixed CSS height, so the returned layer may be
+    e.g. 854×480 for a 1920×1080 source. Using display-resolution coordinates
+    against full-frame VideoMeta dimensions would place the crop in the wrong
+    position.
+
+    Also enforces uint8 binary (0 / 255) output regardless of the layer dtype
+    returned by Gradio — guards against future API changes where the layer
+    becomes float32 (0–1) rather than uint8 (0–255).
+    """
+    if raw_mask.shape[0] == target_h and raw_mask.shape[1] == target_w:
+        result = raw_mask
+    else:
+        result = np.array(
+            Image.fromarray(raw_mask).resize((target_w, target_h), Image.NEAREST)
+        )
+    # Normalise to binary uint8 regardless of incoming dtype
+    return (result > 0).astype(np.uint8) * 255
+
+
+def _create_crop_preview(
+    first_frame: np.ndarray,
+    crop_region: CropRegion,
+    inpaint_mask: np.ndarray,
+) -> np.ndarray:
+    """Overlay crop rectangle and mask on the first frame for preview."""
+    img = Image.fromarray(first_frame).convert("RGBA")
+    overlay = Image.new("RGBA", img.size, (0, 0, 0, 0))
+    draw = ImageDraw.Draw(overlay)
+
+    cr = crop_region
+
+    # Semi-transparent teal fill for crop region
+    draw.rectangle(
+        [cr.frame_x, cr.frame_y, cr.frame_x + cr.frame_w, cr.frame_y + cr.frame_h],
+        fill=(13, 148, 136, 40),
+        outline=(45, 212, 191, 200),
+        width=2,
+    )
+
+    # Inpaint mask overlay (red)
+    if inpaint_mask is not None:
+        mask_rgba = Image.new("RGBA", img.size, (0, 0, 0, 0))
+        mask_full = np.zeros((img.height, img.width), dtype=np.uint8)
+        y1 = cr.frame_y
+        y2 = cr.frame_y + cr.frame_h
+        x1 = cr.frame_x
+        x2 = cr.frame_x + cr.frame_w
+        mask_full[y1:y2, x1:x2] = inpaint_mask
+        red_channel = np.zeros((*mask_full.shape, 4), dtype=np.uint8)
+        red_channel[mask_full > 0] = [239, 68, 68, 140]
+        mask_rgba = Image.fromarray(red_channel, mode="RGBA")
+        overlay = Image.alpha_composite(overlay, mask_rgba)
+
+    composite = Image.alpha_composite(img, overlay).convert("RGB")
+    return np.array(composite)
+
+
+def _meta_to_dict(meta: VideoMeta) -> dict:
+    return {
+        "width": meta.width,
+        "height": meta.height,
+        "fps": meta.fps,
+        "frame_count": meta.frame_count,
+        "duration_s": meta.duration_s,
+        "color_primaries": meta.color_primaries,
+        "color_trc": meta.color_trc,
+        "colorspace": meta.colorspace,
+        "color_range": meta.color_range,
+        "codec_name": meta.codec_name,
+        "bit_depth": meta.bit_depth,
+    }
+
+
+def _dict_to_meta(d: dict) -> VideoMeta:
+    return VideoMeta(**d)
+
+
+# ---------------------------------------------------------------------------
+# Callbacks
+# ---------------------------------------------------------------------------
+
+def on_video_upload(video_path: str | None):
+    """Extract first frame and populate the ImageEditor."""
+    if not video_path:
+        return gr.update(), gr.update(), None, "Upload a video to begin."
+
+    try:
+        meta = probe(video_path)
+
+        # ── Input validation — guard against disk exhaustion on ZeroGPU ──
+        MAX_DURATION_S = 16.0
+        MAX_PIXELS = 1920 * 1080
+        if meta.duration_s > MAX_DURATION_S:
+            return (
+                gr.update(), gr.update(), None,
+                f"❌ Clip too long ({meta.duration_s:.1f}s). Max {MAX_DURATION_S:.0f} seconds.",
+            )
+        if meta.width * meta.height > MAX_PIXELS:
+            return (
+                gr.update(), gr.update(), None,
+                f"❌ Resolution too high ({meta.width}×{meta.height}). Max 1920×1080.",
+            )
+
+        # Extract first frame — mkstemp so the fd is closed before FFmpeg writes
+        fd, tmp_path = tempfile.mkstemp(suffix=".png", prefix="wm_frame_")
+        os.close(fd)
+        try:
+            extract_first_frame(video_path, tmp_path)
+            first_frame = np.array(Image.open(tmp_path).convert("RGB"))
+        finally:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+
+        meta_str = (
+            f"{meta.width}×{meta.height} · {meta.fps:.3g} fps · "
+            f"{meta.duration_s:.1f}s · {meta.frame_count} frames"
+        )
+        if meta.color_trc:
+            meta_str += f" · {meta.color_trc}"
+
+        editor_val = {
+            "background": first_frame,
+            "layers": [],
+            "composite": None,
+        }
+        return (
+            gr.update(value=editor_val),
+            gr.update(value=None),
+            _meta_to_dict(meta),
+            f"✓ Loaded — {meta_str}\n\nNow draw over the watermark with the brush tool.",
+        )
+    except Exception as e:
+        return gr.update(), gr.update(), None, f"❌ Error: {e}"
+
+
+def on_preview_crop(editor_value: dict | None, meta_state: dict | None, context_px: int):
+    """Compute crop region from mask and render a preview overlay."""
+    if meta_state is None:
+        return gr.update(), "Upload a video first."
+    if editor_value is None:
+        return gr.update(), "Upload a video first."
+
+    raw_mask = _get_mask_from_editor(editor_value)
+    if raw_mask is None or raw_mask.max() == 0:
+        return gr.update(), "⚠️ No drawing detected. Use the brush to paint over the watermark."
+
+    try:
+        meta = _dict_to_meta(meta_state)
+        # Rescale mask from editor/display resolution to full source-frame resolution
+        full_mask = _rescale_mask_to_frame(raw_mask, meta.width, meta.height)
+        bbox = mask_to_bbox(full_mask)
+        crop_region = compute_crop_region(
+            bbox, meta.width, meta.height, context_px=context_px
+        )
+        inpaint_mask = build_inpaint_mask(
+            crop_region, source_mask=full_mask, dilate_px=6
+        )
+
+        bg = editor_value.get("background")
+        if bg is None:
+            first_frame = np.zeros((meta.height, meta.width, 3), dtype=np.uint8)
+        else:
+            first_frame = np.array(Image.fromarray(np.array(bg)).convert("RGB"))
+            # Ensure first_frame is at full source resolution for the overlay
+            if first_frame.shape[1] != meta.width or first_frame.shape[0] != meta.height:
+                first_frame = np.array(
+                    Image.fromarray(first_frame).resize(
+                        (meta.width, meta.height), Image.LANCZOS
+                    )
+                )
+
+        preview = _create_crop_preview(first_frame, crop_region, inpaint_mask)
+
+        status = (
+            f"✓ Crop computed\n"
+            f"  Watermark bbox : {bbox.width}×{bbox.height} px\n"
+            f"  Crop region    : {crop_region.frame_w}×{crop_region.frame_h} "
+            f"@ ({crop_region.frame_x}, {crop_region.frame_y})\n"
+            f"  VACE target    : {crop_region.target_w}×{crop_region.target_h}\n"
+            f"\nLooks good? Hit Remove Watermark."
+        )
+        return gr.update(value=preview), status
+
+    except Exception as e:
+        return gr.update(), f"❌ {e}"
+
+
+@spaces.GPU(duration=180)
+def _inpaint_frames_gpu(
+    frame_paths: list,
+    crop_region: CropRegion,
+    inpaint_mask: np.ndarray,
+    mode: str,
+    total: int,
+    progress,
+) -> list:
+    """
+    GPU-accelerated inpainting step.
+
+    This is the *only* function that holds the ZeroGPU allocation.
+    Frame extraction, compositing, and video encoding are all CPU-only and
+    run outside this function to avoid burning GPU quota on I/O work.
+    """
+    if mode == "Fast (LaMa)":
+        from pipeline.lama import inpaint_frames_lama
+
+        def _lama_progress(i: int) -> None:
+            progress(
+                0.20 + 0.70 * ((i + 1) / total),
+                desc=f"LaMa frame {i + 1}/{total}…",
+            )
+
+        return inpaint_frames_lama(
+            frame_paths, crop_region, inpaint_mask, progress_fn=_lama_progress
+        )
+    else:  # Quality (VACE)
+        from pipeline.vace import inpaint_frames_vace
+        progress(0.5, desc="Running VACE-14B…")
+        return inpaint_frames_vace(frame_paths, crop_region, inpaint_mask)
+
+
+def run_pipeline(
+    video_path: str | None,
+    editor_value: dict | None,
+    mode: str,
+    context_px: int,
+    meta_state: dict | None,
+    progress=gr.Progress(),
+):
+    """
+    Pipeline orchestrator — CPU work only.
+
+    GPU allocation is acquired and released inside _inpaint_frames_gpu; the
+    rest of the pipeline (frame extraction, compositing, encoding) is pure
+    CPU/disk I/O and does not consume GPU quota.
+    """
+    if video_path is None:
+        raise gr.Error("Upload a video first.")
+    if meta_state is None:
+        raise gr.Error("Video metadata missing — re-upload the video.")
+
+    raw_mask = _get_mask_from_editor(editor_value)
+    if raw_mask is None or raw_mask.max() == 0:
+        raise gr.Error("Draw over the watermark before processing.")
+
+    meta = _dict_to_meta(meta_state)
+    full_mask = _rescale_mask_to_frame(raw_mask, meta.width, meta.height)
+
+    # ── Compute crop + mask ─────────────────────────────────────────────
+    progress(0.05, desc="Computing crop region…")
+    bbox = mask_to_bbox(full_mask)
+    crop_region = compute_crop_region(
+        bbox, meta.width, meta.height, context_px=context_px
+    )
+    inpaint_mask = build_inpaint_mask(
+        crop_region, source_mask=full_mask, dilate_px=6
+    )
+
+    with VideoWorkspace() as ws:
+        safe_video = ws.path("source" + Path(video_path).suffix)
+        shutil.copy2(video_path, safe_video)
+
+        # ── Extract frames (CFR-forced for VFR safety) ─────────────────
+        progress(0.10, desc="Extracting frames…")
+        frame_paths = extract_frames(safe_video, ws.frames_dir, fps=meta.fps)
+        total = len(frame_paths)
+
+        # ── GPU: inpainting only ───────────────────────────────────
+        progress(0.15, desc="Starting inpainting…")
+        inpainted_crops = _inpaint_frames_gpu(
+            frame_paths, crop_region, inpaint_mask, mode, total, progress
+        )
+
+        # ── CPU: composite ──────────────────────────────────────────
+        progress(0.90, desc="Compositing frames…")
+        from pipeline.composite import composite_frame
+
+        for i, (fp, crop) in enumerate(zip(frame_paths, inpainted_crops)):
+            original = np.array(Image.open(fp).convert("RGB"))
+            composited = composite_frame(original, crop, crop_region, inpaint_mask)
+            Image.fromarray(composited).save(ws.out_frames_dir / f"{i+1:06d}.png")
+
+        # ── CPU: encode + mux ───────────────────────────────────────
+        progress(0.95, desc="Encoding video…")
+        silent_path = ws.path("silent.mp4")
+        frames_to_video(ws.out_frames_dir, silent_path, meta)
+
+        fd, final_path = tempfile.mkstemp(suffix=".mp4", prefix="wm_out_")
+        os.close(fd)
+        try:
+            attach_audio(safe_video, silent_path, final_path)
+        except Exception:
+            try:
+                os.unlink(final_path)
+            except OSError:
+                pass
+            raise
+        # ws (frames, composited pngs, silent.mp4) cleaned up here
+
+    progress(1.0, desc="Done!")
+    return final_path, f"✓ Done — {total} frames processed ({mode})"
+
+
+# ---------------------------------------------------------------------------
+# UI
+# ---------------------------------------------------------------------------
+
+with gr.Blocks(title="Video Watermark Remover", css=CSS) as demo:
+
+    # State
+    meta_state = gr.State(None)
+
+    # ── Header ──────────────────────────────────────────────────────────────
+    gr.HTML("""
+        <div class="header-block">
+            <h1>🦎 Video Watermark Remover</h1>
+            <p>Draw over the watermark · choose a mode · get clean footage</p>
+        </div>
+    """)
+
+    # ── Step 1 + 2 side by side ─────────────────────────────────────────────
+    with gr.Row(equal_height=False):
+        with gr.Column(scale=1):
+            gr.HTML('<div class="card-title"><span class="step-badge">1</span>Upload Video</div>')
+            video_input = gr.Video(
+                label="Source clip (≤15 s, 1080p)",
+                elem_id="video-input",
+            )
+
+            gr.HTML('<div class="card-title" style="margin-top:16px"><span class="step-badge">2</span>Mode</div>')
+            mode_radio = gr.Radio(
+                choices=["Fast (LaMa)", "Quality (VACE-14B)"],
+                value="Fast (LaMa)",
+                label="",
+                elem_classes=["mode-radio"],
+            )
+
+            gr.HTML('<div class="card-title" style="margin-top:16px">⚙️ Advanced</div>')
+            context_slider = gr.Slider(
+                minimum=32,
+                maximum=192,
+                value=64,
+                step=16,
+                label="Context padding (px)",
+                info="Extra scene context around the watermark given to the model",
+            )
+
+        with gr.Column(scale=2):
+            gr.HTML('<div class="card-title"><span class="step-badge">3</span>Draw Over the Watermark</div>')
+            editor = gr.ImageEditor(
+                label="Paint over the watermark (brush tool)",
+                type="numpy",
+                height=480,
+                brush=gr.Brush(colors=["#ef4444"], default_size=12),
+                eraser=gr.Eraser(default_size=12),
+            )
+
+    # ── Action buttons ───────────────────────────────────────────────────────
+    with gr.Row():
+        preview_btn = gr.Button(
+            "🔍 Preview Crop Region",
+            elem_classes=["btn-secondary"],
+        )
+        process_btn = gr.Button(
+            "✨ Remove Watermark",
+            variant="primary",
+            elem_classes=["btn-primary"],
+        )
+
+    # ── Status ───────────────────────────────────────────────────────────────
+    status_box = gr.Textbox(
+        label="Status",
+        value="Upload a video to begin.",
+        lines=4,
+        interactive=False,
+        elem_classes=["status-box"],
+    )
+
+    # ── Outputs ──────────────────────────────────────────────────────────────
+    with gr.Row():
+        with gr.Column():
+            gr.HTML('<div class="card-title">Crop Preview</div>')
+            crop_preview = gr.Image(
+                label="",
+                type="numpy",
+                show_label=False,
+            )
+        with gr.Column():
+            gr.HTML('<div class="card-title">Output Video</div>')
+            video_output = gr.Video(
+                label="",
+                show_label=False,
+            )
+
+    # ── Wiring ───────────────────────────────────────────────────────────────
+    video_input.upload(
+        fn=on_video_upload,
+        inputs=[video_input],
+        outputs=[editor, crop_preview, meta_state, status_box],
+    )
+
+    preview_btn.click(
+        fn=on_preview_crop,
+        inputs=[editor, meta_state, context_slider],
+        outputs=[crop_preview, status_box],
+    )
+
+    process_btn.click(
+        fn=run_pipeline,
+        inputs=[video_input, editor, mode_radio, context_slider, meta_state],
+        outputs=[video_output, status_box],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

packages.txt

@@ -0,0 +1 @@
+ffmpeg

pipeline/__init__.py

@@ -0,0 +1,3 @@
+"""
+pipeline/__init__.py
+"""

pipeline/composite.py

@@ -0,0 +1,218 @@
+"""
+pipeline/composite.py
+---------------------
+Feathered alpha compositing: paste an inpainted crop back into the
+original full frame.
+
+The feather/blend zone creates a smooth transition along the crop border,
+avoiding hard edge seams. Only pixels inside the inpaint mask are replaced;
+the rest of the crop (the "context" ring) is discarded.
+
+Design
+------
+Two-stage blend:
+  1. Mask feathering: the inpaint mask is Gaussian-blurred to create a
+     soft alpha ramp around the watermark boundary. This blends between
+     the inpainted content and the original frame within the crop.
+  2. Crop-border feathering (optional, default off): a second linear ramp
+     from the crop border inward, so the context ring blends too. Usually
+     not needed because context pixels in the crop are identical to the
+     original frame anyway (LaMa / VACE don't alter them much).
+
+All operations are pure NumPy + PIL — no cv2 required.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image, ImageFilter
+
+from pipeline.crop import CropRegion
+
+
+def composite_frame(
+    original: np.ndarray,
+    inpainted_crop: np.ndarray,
+    crop_region: CropRegion,
+    inpaint_mask: np.ndarray,
+    feather_radius: int = 8,
+) -> np.ndarray:
+    """
+    Blend an inpainted crop back into the original full frame.
+
+    Parameters
+    ----------
+    original : np.ndarray
+        Full-frame image (H x W x 3, uint8 RGB). Modified in-place
+        on a copy — caller's array is not mutated.
+    inpainted_crop : np.ndarray
+        Inpainted crop image (crop_h x crop_w x 3, uint8 RGB).
+        Must match crop_region dimensions exactly.
+    crop_region : CropRegion
+        Defines where the crop sits in the full frame.
+    inpaint_mask : np.ndarray
+        Crop-local binary mask (crop_h x crop_w, uint8). 255=inpaint, 0=keep.
+        Same mask that was passed to the inpainting model.
+    feather_radius : int
+        Gaussian blur radius applied to the mask before blending.
+        Larger values = softer transition.
+        Set to 0 to disable feathering (hard composite).
+
+    Returns
+    -------
+    np.ndarray
+        Full-frame output (H x W x 3, uint8 RGB) with watermark removed.
+    """
+    cr = crop_region
+    result = original.copy()
+
+    # Sanity check dimensions
+    expected_h, expected_w = cr.frame_h, cr.frame_w
+    actual_h, actual_w = inpainted_crop.shape[:2]
+    if (actual_h, actual_w) != (expected_h, expected_w):
+        # Resize inpainted crop to match crop region (handles VACE resize case)
+        inpainted_crop = np.array(
+            Image.fromarray(inpainted_crop).resize(
+                (expected_w, expected_h), Image.LANCZOS
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # Build the blend alpha from the inpaint mask
+    # ------------------------------------------------------------------
+    alpha = _feathered_alpha(inpaint_mask, feather_radius)  # float32, 0..1
+
+    # ------------------------------------------------------------------
+    # Composite: result = alpha * inpainted + (1 - alpha) * original_crop
+    # ------------------------------------------------------------------
+    original_crop = result[
+        cr.frame_y : cr.frame_y + cr.frame_h,
+        cr.frame_x : cr.frame_x + cr.frame_w,
+    ].astype(np.float32)
+
+    inpainted_f = inpainted_crop.astype(np.float32)
+    alpha_3 = alpha[:, :, np.newaxis]   # broadcast over RGB channels
+
+    blended = alpha_3 * inpainted_f + (1.0 - alpha_3) * original_crop
+    blended_uint8 = np.clip(blended, 0, 255).astype(np.uint8)
+
+    result[
+        cr.frame_y : cr.frame_y + cr.frame_h,
+        cr.frame_x : cr.frame_x + cr.frame_w,
+    ] = blended_uint8
+
+    return result
+
+
+def composite_frames(
+    original_frame_paths,
+    inpainted_crops: list[np.ndarray],
+    crop_region: CropRegion,
+    inpaint_mask: np.ndarray,
+    feather_radius: int = 8,
+) -> list[np.ndarray]:
+    """
+    Batch version: composite a list of inpainted crops onto their
+    corresponding original frames.
+
+    Parameters
+    ----------
+    original_frame_paths : List[Path]
+        Full-frame PNG paths (same order as inpainted_crops).
+    inpainted_crops : List[np.ndarray]
+        One inpainted crop per frame.
+    crop_region : CropRegion
+    inpaint_mask : np.ndarray
+        Shared mask (same for all frames — watermark is static).
+    feather_radius : int
+
+    Returns
+    -------
+    List[np.ndarray]
+        Full-frame composited images (uint8 RGB), one per input frame.
+    """
+    # Pre-compute feathered alpha once (shared mask)
+    alpha = _feathered_alpha(inpaint_mask, feather_radius)
+
+    composited: list[np.ndarray] = []
+    for frame_path, crop in zip(original_frame_paths, inpainted_crops):
+        original = np.array(Image.open(frame_path).convert("RGB"))
+        frame_out = _composite_with_alpha(original, crop, crop_region, alpha)
+        composited.append(frame_out)
+
+    return composited
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+def _feathered_alpha(mask: np.ndarray, radius: int) -> np.ndarray:
+    """
+    Convert a uint8 binary mask (0/255) to a float32 alpha map (0..1)
+    with a Gaussian-blurred soft edge.
+
+    Parameters
+    ----------
+    mask : np.ndarray
+        Crop-local binary mask (H x W, uint8).
+    radius : int
+        Gaussian blur radius. 0 = hard composite.
+
+    Returns
+    -------
+    np.ndarray
+        Float32 alpha map (H x W), values in [0.0, 1.0].
+    """
+    alpha_f = mask.astype(np.float32) / 255.0
+
+    if radius > 0:
+        # Use scipy gaussian_filter on float32 directly — avoids uint8 quantisation
+        # that would staircase the feather ramp over 8 discrete levels.
+        # sigma: radius ≈ 3σ is the standard Gaussian convention.
+        from scipy.ndimage import gaussian_filter
+        sigma = max(radius / 3.0, 0.5)
+        alpha_f = gaussian_filter(alpha_f, sigma=sigma)
+        alpha_f = np.clip(alpha_f, 0.0, 1.0)
+
+    return alpha_f
+
+
+def _composite_with_alpha(
+    original: np.ndarray,
+    inpainted_crop: np.ndarray,
+    crop_region: CropRegion,
+    alpha: np.ndarray,
+) -> np.ndarray:
+    """
+    Internal composite given a pre-computed alpha map.
+    Returns a copy of original with the crop region blended in.
+    """
+    cr = crop_region
+    result = original.copy()
+
+    # Resize crop if needed (e.g. VACE returned a different resolution)
+    expected_h, expected_w = cr.frame_h, cr.frame_w
+    actual_h, actual_w = inpainted_crop.shape[:2]
+    if (actual_h, actual_w) != (expected_h, expected_w):
+        inpainted_crop = np.array(
+            Image.fromarray(inpainted_crop).resize(
+                (expected_w, expected_h), Image.LANCZOS
+            )
+        )
+
+    original_crop = result[
+        cr.frame_y : cr.frame_y + cr.frame_h,
+        cr.frame_x : cr.frame_x + cr.frame_w,
+    ].astype(np.float32)
+
+    alpha_3 = alpha[:, :, np.newaxis]
+    blended = alpha_3 * inpainted_crop.astype(np.float32) + (1.0 - alpha_3) * original_crop
+    blended_uint8 = np.clip(blended, 0, 255).astype(np.uint8)
+
+    result[
+        cr.frame_y : cr.frame_y + cr.frame_h,
+        cr.frame_x : cr.frame_x + cr.frame_w,
+    ] = blended_uint8
+
+    return result

pipeline/crop.py

@@ -0,0 +1,447 @@
+"""
+pipeline/crop.py
+----------------
+Crop region computation for the watermark inpainting pipeline.
+
+Given a user-drawn mask on the first frame, this module:
+  1. Computes the bounding box of the drawn region.
+  2. Finds the smallest VACE-compatible resolution that fits the bbox
+     (with a configurable context border added on each side).
+  3. Centers the crop on the watermark centroid and shifts it
+     asymmetrically if it would fall off a frame edge.
+  4. Returns a CropRegion dataclass consumed by the rest of the pipeline.
+
+No model dependencies — pure NumPy / math.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Tuple
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Supported VACE / Wan2.1 resolutions
+# ---------------------------------------------------------------------------
+# These are the canonical (width, height) pairs that Wan2.1-VACE accepts.
+# They must be divisible by 32 (VAE spatial downsampling factor).
+# Ordered by total pixel count ascending so we can pick the smallest fitting one.
+
+VACE_RESOLUTIONS: list[Tuple[int, int]] = sorted(
+    [
+        # Square
+        (512, 512),
+        (576, 576),
+        (640, 640),
+        (704, 704),
+        (768, 768),
+        (832, 832),
+        (896, 896),
+        (960, 960),
+        (1024, 1024),
+        (1280, 1280),
+        # Landscape (width > height)
+        (640, 480),
+        (704, 480),
+        (768, 512),
+        (832, 576),
+        (896, 576),
+        (960, 544),
+        (1024, 576),
+        (1024, 640),
+        (1024, 704),
+        (1024, 768),
+        (1152, 640),
+        (1152, 768),
+        (1280, 720),
+        (1280, 768),
+        (1280, 1024),
+        # Portrait (height > width)
+        (480, 640),
+        (480, 704),
+        (512, 768),
+        (576, 832),
+        (576, 896),
+        (544, 960),
+        (576, 1024),
+        (640, 1024),
+        (704, 1024),
+        (768, 1024),
+        (640, 1152),
+        (768, 1152),
+        (720, 1280),
+        (768, 1280),
+        (1024, 1280),
+    ],
+    key=lambda wh: wh[0] * wh[1],  # ascending by pixel count
+)
+
+
+# ---------------------------------------------------------------------------
+# Data types
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class BBox:
+    """Pixel-space bounding box. All values are inclusive, 0-indexed."""
+    x1: int
+    y1: int
+    x2: int
+    y2: int
+
+    @property
+    def width(self) -> int:
+        # x1 and x2 are both inclusive pixel indices, so pixel count = x2 - x1 + 1
+        return self.x2 - self.x1 + 1
+
+    @property
+    def height(self) -> int:
+        return self.y2 - self.y1 + 1
+
+    @property
+    def cx(self) -> float:
+        return (self.x1 + self.x2) / 2.0
+
+    @property
+    def cy(self) -> float:
+        return (self.y1 + self.y2) / 2.0
+
+    @property
+    def area(self) -> int:
+        return self.width * self.height
+
+    def __repr__(self) -> str:
+        return (
+            f"BBox(x1={self.x1}, y1={self.y1}, x2={self.x2}, y2={self.y2}, "
+            f"w={self.width}, h={self.height})"
+        )
+
+
+@dataclass(frozen=True)
+class CropRegion:
+    """
+    The crop rectangle to cut from each full frame before inpainting.
+
+    - ``frame_x / frame_y``: top-left corner in full-frame pixel space.
+    - ``frame_w / frame_h``: size in full-frame pixel space.
+    - ``target_w / target_h``: VACE-compatible resolution the crop is scaled
+      to (usually equal to frame_w/frame_h when we only expand, no downscale).
+    - ``mask_bbox``: original watermark bbox in crop-local coordinates.
+    """
+    frame_x: int
+    frame_y: int
+    frame_w: int
+    frame_h: int
+    target_w: int
+    target_h: int
+    mask_bbox: BBox          # in crop-local pixel space
+
+    @property
+    def frame_rect(self) -> Tuple[int, int, int, int]:
+        """(x, y, w, h) in full-frame space — handy for cv2.getRectSubPix etc."""
+        return (self.frame_x, self.frame_y, self.frame_w, self.frame_h)
+
+    @property
+    def needs_resize(self) -> bool:
+        return self.frame_w != self.target_w or self.frame_h != self.target_h
+
+    def __repr__(self) -> str:
+        return (
+            f"CropRegion(frame=({self.frame_x},{self.frame_y},"
+            f"{self.frame_w}x{self.frame_h}), "
+            f"target={self.target_w}x{self.target_h}, "
+            f"mask={self.mask_bbox})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def mask_to_bbox(mask: np.ndarray) -> BBox:
+    """
+    Convert a binary mask (H x W uint8, 255=drawn) to a tight BBox.
+
+    Parameters
+    ----------
+    mask : np.ndarray
+        Single-channel mask, dtype uint8. Non-zero pixels = drawn area.
+
+    Returns
+    -------
+    BBox
+        Tight bounding box around all non-zero pixels.
+
+    Raises
+    ------
+    ValueError
+        If the mask contains no drawn pixels.
+    """
+    if mask.ndim == 3:
+        # Accept RGB/RGBA — collapse to single channel
+        mask = mask.max(axis=2)
+
+    ys, xs = np.where(mask > 0)
+    if len(xs) == 0:
+        raise ValueError(
+            "The mask has no drawn pixels. "
+            "Please draw around the watermark before processing."
+        )
+
+    return BBox(
+        x1=int(xs.min()),
+        y1=int(ys.min()),
+        x2=int(xs.max()),
+        y2=int(ys.max()),
+    )
+
+
+def find_target_resolution(
+    required_w: int,
+    required_h: int,
+) -> Tuple[int, int]:
+    """
+    Find the smallest VACE-compatible (width, height) pair such that
+    width >= required_w AND height >= required_h.
+
+    The algorithm iterates the catalogue (sorted by area ascending) and
+    picks the first entry where both width >= required_w AND height >= required_h.
+
+    If no resolution in the catalogue fits, the function rounds up both
+    dimensions to the next multiple of 32 and returns them — effectively
+    a custom resolution that VACE handles via its flexible attention.
+
+    Parameters
+    ----------
+    required_w, required_h : int
+        Minimum pixel dimensions needed (the crop area with context padding).
+
+    Returns
+    -------
+    (target_w, target_h) : Tuple[int, int]
+        VACE resolution to use. Always >= (required_w, required_h).
+    """
+    # VACE_RESOLUTIONS is sorted ascending by area; the first entry that
+    # satisfies both constraints is therefore the minimum-area fit.
+    best = next(
+        ((w, h) for (w, h) in VACE_RESOLUTIONS if w >= required_w and h >= required_h),
+        None,
+    )
+    if best is not None:
+        return best
+
+    # Fallback: round up to nearest multiple of 32
+    fallback_w = _ceil_to_multiple(required_w, 32)
+    fallback_h = _ceil_to_multiple(required_h, 32)
+    return (fallback_w, fallback_h)
+
+
+def compute_crop_region(
+    watermark_bbox: BBox,
+    frame_w: int,
+    frame_h: int,
+    context_px: int = 64,
+    min_crop_dim: int = 320,
+) -> CropRegion:
+    """
+    Compute the fixed crop region for the entire video.
+
+    Steps
+    -----
+    1. Add ``context_px`` padding on all four sides of the watermark bbox
+       to give the model scene context.
+    2. Enforce a minimum crop dimension (``min_crop_dim``).
+    3. Find the smallest VACE-compatible resolution that fits the padded bbox.
+    4. Centre the crop on the watermark centroid.
+    5. Shift the crop (without resizing) if it would overflow the frame edge.
+    6. Express the watermark mask in crop-local coordinates.
+
+    Parameters
+    ----------
+    watermark_bbox : BBox
+        Tight bounding box of the drawn watermark mask, in full-frame pixels.
+    frame_w, frame_h : int
+        Full frame dimensions (e.g. 1920 x 1080).
+    context_px : int
+        How many pixels of context to add around the watermark on each side.
+        Default 64 gives ample scene context for the model.
+    min_crop_dim : int
+        Smallest allowed crop dimension. Prevents tiny crops (e.g. a 10px
+        watermark) from confusing the model.
+
+    Returns
+    -------
+    CropRegion
+        Fully resolved crop spec, ready for use by video.py and composite.py.
+
+    Raises
+    ------
+    ValueError
+        If the watermark bbox is larger than the full frame (sanity check).
+    """
+    if watermark_bbox.width > frame_w or watermark_bbox.height > frame_h:
+        raise ValueError(
+            f"Watermark bbox {watermark_bbox} is larger than the frame "
+            f"({frame_w}x{frame_h}). Check your mask."
+        )
+
+    # ------------------------------------------------------------------
+    # 1. Padded required dimensions
+    # ------------------------------------------------------------------
+    required_w = max(watermark_bbox.width + 2 * context_px, min_crop_dim)
+    required_h = max(watermark_bbox.height + 2 * context_px, min_crop_dim)
+
+    # Clamp: the crop can never exceed the frame itself
+    required_w = min(required_w, frame_w)
+    required_h = min(required_h, frame_h)
+
+    # ------------------------------------------------------------------
+    # 2. VACE target resolution
+    # ------------------------------------------------------------------
+    target_w, target_h = find_target_resolution(required_w, required_h)
+
+    # Again clamp target to frame size (no point upscaling beyond source)
+    target_w = min(target_w, frame_w)
+    target_h = min(target_h, frame_h)
+
+    # Round down to multiple of 32 after clamping
+    target_w = _floor_to_multiple(target_w, 32)
+    target_h = _floor_to_multiple(target_h, 32)
+
+    # ------------------------------------------------------------------
+    # 3. Centre on watermark centroid, then clamp to frame bounds
+    # ------------------------------------------------------------------
+    crop_x, crop_y = _centre_crop(
+        cx=watermark_bbox.cx,
+        cy=watermark_bbox.cy,
+        crop_w=target_w,
+        crop_h=target_h,
+        frame_w=frame_w,
+        frame_h=frame_h,
+    )
+
+    # ------------------------------------------------------------------
+    # 4. Mask in crop-local coordinates
+    # ------------------------------------------------------------------
+    local_bbox = BBox(
+        x1=watermark_bbox.x1 - crop_x,
+        y1=watermark_bbox.y1 - crop_y,
+        x2=watermark_bbox.x2 - crop_x,
+        y2=watermark_bbox.y2 - crop_y,
+    )
+
+    return CropRegion(
+        frame_x=crop_x,
+        frame_y=crop_y,
+        frame_w=target_w,
+        frame_h=target_h,
+        target_w=target_w,
+        target_h=target_h,
+        mask_bbox=local_bbox,
+    )
+
+
+def build_inpaint_mask(
+    crop_region: CropRegion,
+    source_mask: np.ndarray | None = None,
+    dilate_px: int = 6,
+) -> np.ndarray:
+    """
+    Build the binary inpainting mask in crop-local coordinates.
+
+    If ``source_mask`` is provided (a full-frame mask from the user's drawing),
+    it is cropped to the crop region. Otherwise, the mask is synthesised from
+    ``crop_region.mask_bbox`` (i.e. a filled rectangle).
+
+    The mask is then dilated by ``dilate_px`` pixels to prevent edge artefacts.
+
+    Parameters
+    ----------
+    crop_region : CropRegion
+    source_mask : np.ndarray, optional
+        Full-frame binary mask (H x W uint8), 255=inpaint. If None, uses bbox.
+    dilate_px : int
+        Dilation radius in pixels. Default 6.
+
+    Returns
+    -------
+    np.ndarray
+        Crop-local mask (target_h x target_w, uint8). 255=inpaint, 0=keep.
+    """
+    h, w = crop_region.frame_h, crop_region.frame_w
+    mask = np.zeros((h, w), dtype=np.uint8)
+
+    if source_mask is not None:
+        # Collapse to single channel if needed
+        if source_mask.ndim == 3:
+            source_mask = source_mask.max(axis=2)
+        # Crop to the crop region
+        y1 = crop_region.frame_y
+        y2 = crop_region.frame_y + crop_region.frame_h
+        x1 = crop_region.frame_x
+        x2 = crop_region.frame_x + crop_region.frame_w
+        mask = source_mask[y1:y2, x1:x2].copy()
+    else:
+        # Fill the watermark bbox rectangle
+        b = crop_region.mask_bbox
+        mask[b.y1 : b.y2 + 1, b.x1 : b.x2 + 1] = 255
+
+    # Dilate
+    if dilate_px > 0:
+        mask = _dilate_mask(mask, dilate_px)
+
+    return mask
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+def _centre_crop(
+    cx: float,
+    cy: float,
+    crop_w: int,
+    crop_h: int,
+    frame_w: int,
+    frame_h: int,
+) -> Tuple[int, int]:
+    """
+    Compute top-left (x, y) of a crop_w x crop_h rectangle centred at
+    (cx, cy), then clamp so the rectangle stays within the frame.
+
+    Clamping shifts asymmetrically — the crop size never changes.
+    """
+    x = int(round(cx - crop_w / 2.0))
+    y = int(round(cy - crop_h / 2.0))
+
+    # Clamp: do not go off any edge
+    x = max(0, min(x, frame_w - crop_w))
+    y = max(0, min(y, frame_h - crop_h))
+
+    return x, y
+
+
+def _ceil_to_multiple(value: int, multiple: int) -> int:
+    return math.ceil(value / multiple) * multiple
+
+
+def _floor_to_multiple(value: int, multiple: int) -> int:
+    return (value // multiple) * multiple
+
+
+def _dilate_mask(mask: np.ndarray, radius: int) -> np.ndarray:
+    """
+    Dilate a binary mask using a square structuring element of side
+    (2*radius + 1). Uses scipy.ndimage for correctness without requiring cv2.
+
+    For the typical 4-8 px dilation used here this is fast enough.
+    """
+    from scipy.ndimage import binary_dilation  # lazy import
+
+    struct = np.ones((2 * radius + 1, 2 * radius + 1), dtype=bool)
+    binary = mask > 0
+    dilated = binary_dilation(binary, structure=struct)
+    return (dilated * 255).astype(np.uint8)

pipeline/lama.py

@@ -0,0 +1,150 @@
+"""
+pipeline/lama.py
+----------------
+Fast mode: per-frame LaMa inpainting.
+
+Uses the `simple-lama-inpainting` PyPI package, which wraps the
+Resolution-robust Large Mask inpainting (LaMa) model. Runs on CPU
+or GPU without requiring a @spaces.GPU call — negligible quota burn.
+
+Pipeline for each frame:
+  1. Crop to the CropRegion.
+  2. Run LaMa on the crop with the dilated inpaint mask.
+  3. Return the inpainted crop; compositing is handled by composite.py.
+
+License: LaMa is Apache 2.0.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+import numpy as np
+from PIL import Image
+
+from pipeline.crop import CropRegion
+
+
+# ---------------------------------------------------------------------------
+# Model singleton
+# ---------------------------------------------------------------------------
+# Loaded lazily on first call; shared across all frames in a run.
+# Tracks the device it was loaded on — reloads if GPU becomes available
+# after a cold CPU-only initialisation (ZeroGPU warm/cold start handling).
+_lama_model = None
+_lama_device: str | None = None
+
+
+def _get_model():
+    global _lama_model, _lama_device
+    import torch
+    current_device = "cuda" if torch.cuda.is_available() else "cpu"
+    # One-way latch: only reload when *upgrading* from CPU to GPU.
+    # After the @spaces.GPU call ends the process returns to CPU, but we keep
+    # the model reference — it will be valid again on the next GPU allocation.
+    # Reloading on every cpu→cuda transition (once per cold start) is correct;
+    # reloading on cuda→cpu would double the startup cost for no benefit.
+    if _lama_model is None or (current_device == "cuda" and _lama_device != "cuda"):
+        from simple_lama_inpainting import SimpleLama  # type: ignore
+        _lama_model = SimpleLama()
+        _lama_device = current_device
+    return _lama_model
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def inpaint_frames_lama(
+    frame_paths: List[Path],
+    crop_region: CropRegion,
+    inpaint_mask: np.ndarray,
+    progress_fn=None,
+) -> List[np.ndarray]:
+    """
+    Run LaMa inpainting on the crop region of each frame.
+
+    Parameters
+    ----------
+    frame_paths : List[Path]
+        Ordered list of full-frame PNG paths.
+    crop_region : CropRegion
+        Defines the rectangle to extract from each frame.
+    inpaint_mask : np.ndarray
+        Crop-local binary mask (H x W, uint8). 255=inpaint, 0=keep.
+        Must match crop_region dimensions.
+    progress_fn : callable, optional
+        Called as ``progress_fn(i)`` after each frame where i is the
+        0-based frame index. Use for Gradio progress reporting.
+
+    Returns
+    -------
+    List[np.ndarray]
+        List of inpainted crop images (H x W x 3, uint8 RGB),
+        one per input frame. Full-frame compositing is done in composite.py.
+    """
+    model = _get_model()
+    # Create mask PIL image once — it is identical for every frame
+    mask_pil = _mask_to_pil(inpaint_mask)
+    results: List[np.ndarray] = []
+
+    for i, frame_path in enumerate(frame_paths):
+        crop_np = _load_crop(frame_path, crop_region)
+        crop_pil = Image.fromarray(crop_np)
+
+        # simple-lama-inpainting expects (image: PIL.Image, mask: PIL.Image)
+        # mask must be mode "L": 255=inpaint, 0=keep
+        inpainted_pil: Image.Image = model(crop_pil, mask_pil)
+        results.append(np.array(inpainted_pil.convert("RGB")))
+
+        if progress_fn is not None:
+            progress_fn(i)
+
+    return results
+
+
+def inpaint_image_lama(
+    image: np.ndarray,
+    crop_region: CropRegion,
+    inpaint_mask: np.ndarray,
+) -> np.ndarray:
+    """
+    Run LaMa on a single already-loaded image array (H x W x 3 uint8 RGB).
+    Convenience wrapper used by the preview step in app.py.
+
+    Returns the inpainted crop (crop_region dimensions, RGB uint8).
+    """
+    model = _get_model()
+    mask_pil = _mask_to_pil(inpaint_mask)
+
+    cr = crop_region
+    crop_np = image[
+        cr.frame_y : cr.frame_y + cr.frame_h,
+        cr.frame_x : cr.frame_x + cr.frame_w,
+    ]
+    inpainted_pil: Image.Image = model(Image.fromarray(crop_np), mask_pil)
+    return np.array(inpainted_pil.convert("RGB"))
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+def _load_crop(frame_path: Path, crop_region: CropRegion) -> np.ndarray:
+    """Load a frame and return only the crop region (RGB uint8)."""
+    img = Image.open(frame_path).convert("RGB")
+    cr = crop_region
+    # PIL box is (left, upper, right, lower)
+    box = (
+        cr.frame_x,
+        cr.frame_y,
+        cr.frame_x + cr.frame_w,
+        cr.frame_y + cr.frame_h,
+    )
+    return np.array(img.crop(box))
+
+
+def _mask_to_pil(mask: np.ndarray) -> Image.Image:
+    """Convert a uint8 numpy mask to a PIL L-mode image for LaMa."""
+    return Image.fromarray(mask, mode="L")

pipeline/vace.py

@@ -0,0 +1,59 @@
+"""
+pipeline/vace.py
+----------------
+Quality mode: VACE-14B video inpainting via Wan2.1-VACE-14B-diffusers.
+
+STUB — implemented in the next iteration after pipeline validation with LaMa.
+
+Planned implementation:
+  - WanVACEPipeline from diffusers
+  - FP8 quantization via torchao
+  - AoT compilation for speed
+  - 8-step inference (step-distilled schedule)
+  - Temporal chunking: split frame list into ~33-frame windows, run each
+    chunk with overlapping context frames to avoid seam artefacts
+  - Memory: model.enable_model_cpu_offload() + torch.cuda.empty_cache()
+    between chunks
+  - @spaces.GPU(duration=200) decorator on the main entry function
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+import numpy as np
+
+from pipeline.crop import CropRegion
+
+
+def inpaint_frames_vace(
+    frame_paths: List[Path],
+    crop_region: CropRegion,
+    inpaint_mask: np.ndarray,
+    num_inference_steps: int = 8,
+    guidance_scale: float = 5.0,
+) -> List[np.ndarray]:
+    """
+    Run VACE-14B inpainting on the crop region of each frame.
+
+    Parameters
+    ----------
+    frame_paths : List[Path]
+        Ordered full-frame PNG paths.
+    crop_region : CropRegion
+    inpaint_mask : np.ndarray
+        Crop-local binary mask (H x W, uint8). 255=inpaint.
+    num_inference_steps : int
+        Default 8 for step-distilled fast inference.
+    guidance_scale : float
+
+    Returns
+    -------
+    List[np.ndarray]
+        Inpainted crop arrays (H x W x 3, uint8 RGB), one per frame.
+    """
+    raise NotImplementedError(
+        "VACE-14B pipeline is not yet implemented. "
+        "Use Fast (LaMa) mode for now."
+    )

pipeline/video.py

@@ -0,0 +1,445 @@
+"""
+pipeline/video.py
+-----------------
+FFmpeg I/O wrappers for the watermark removal pipeline.
+
+Responsibilities:
+  - Extract frames from input video to a temp directory (PNG, lossless).
+  - Probe frame rate, resolution, and color metadata from source.
+  - Reassemble inpainted frames into a no-audio video.
+  - Reattach the original audio stream (simple copy remux).
+  - Passthrough V-Log / HLG / HDR color metadata flags.
+
+All FFmpeg calls raise RuntimeError on non-zero exit so callers can surface
+clean error messages to the Gradio UI.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Video metadata
+# ---------------------------------------------------------------------------
+
+@dataclass
+class VideoMeta:
+    """Probed properties of the input video."""
+    width: int
+    height: int
+    fps: float
+    frame_count: int
+    duration_s: float
+    # FFmpeg color metadata strings (may be None if not present)
+    color_primaries: Optional[str]
+    color_trc: Optional[str]       # transfer characteristics (e.g. "arib-std-b67" for HLG, "bt709")
+    colorspace: Optional[str]      # YCbCr matrix (e.g. "bt2020nc")
+    color_range: Optional[str]     # "tv" or "pc"
+    # Raw codec name, e.g. "h264"
+    codec_name: str
+    # Bit depth per channel. 8 = standard SDR; 10 = V-Log / HLG / HDR10.
+    # Default 8 so existing callers that omit this field keep working.
+    bit_depth: int = 8
+
+
+def probe(video_path: str | Path) -> VideoMeta:
+    """
+    Run ffprobe on *video_path* and return a VideoMeta.
+
+    Parameters
+    ----------
+    video_path : str | Path
+
+    Returns
+    -------
+    VideoMeta
+
+    Raises
+    ------
+    RuntimeError
+        If ffprobe fails or the file has no video stream.
+    """
+    cmd = [
+        "ffprobe",
+        "-v", "quiet",
+        "-print_format", "json",
+        "-show_streams",
+        "-show_format",
+        str(video_path),
+    ]
+    result = _run(cmd)
+    data = json.loads(result.stdout)
+
+    # Find the first video stream
+    video_stream = next(
+        (s for s in data.get("streams", []) if s.get("codec_type") == "video"),
+        None,
+    )
+    if video_stream is None:
+        raise RuntimeError(f"No video stream found in {video_path}")
+
+    # Parse frame rate (stored as "num/den" string)
+    fps = _parse_rational(video_stream.get("r_frame_rate", "30/1"))
+
+    # Duration: prefer stream-level, fall back to format-level
+    dur_str = video_stream.get("duration") or data.get("format", {}).get("duration", "0")
+    duration_s = float(dur_str)
+
+    # Frame count
+    nb_frames = video_stream.get("nb_frames")
+    if nb_frames and nb_frames != "N/A":
+        frame_count = int(nb_frames)
+    else:
+        frame_count = max(1, round(duration_s * fps))
+
+    # Bit depth: prefer bits_per_raw_sample; fall back to pixel format name.
+    # bits_per_raw_sample is "0" or missing for most H.264 sources.
+    bits_raw = video_stream.get("bits_per_raw_sample") or "0"
+    pix_fmt_val = video_stream.get("pix_fmt", "")
+
+    def _bd_from_pix_fmt() -> int:
+        return 10 if any(d in pix_fmt_val for d in ("10le", "10be", "12le", "12be")) else 8
+
+    try:
+        bd = int(bits_raw)
+        bit_depth = bd if bd > 0 else _bd_from_pix_fmt()
+    except (ValueError, TypeError):
+        bit_depth = _bd_from_pix_fmt()
+
+    return VideoMeta(
+        width=int(video_stream["width"]),
+        height=int(video_stream["height"]),
+        fps=fps,
+        frame_count=frame_count,
+        duration_s=duration_s,
+        color_primaries=video_stream.get("color_primaries"),
+        color_trc=video_stream.get("color_transfer"),
+        colorspace=video_stream.get("color_space"),
+        color_range=video_stream.get("color_range"),
+        codec_name=video_stream.get("codec_name", "unknown"),
+        bit_depth=bit_depth,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Frame extraction
+# ---------------------------------------------------------------------------
+
+def extract_frames(
+    video_path: str | Path,
+    out_dir: str | Path,
+    pattern: str = "%06d.png",
+    fps: float | None = None,
+) -> List[Path]:
+    """
+    Extract every frame from *video_path* as PNG images into *out_dir*.
+
+    Uses lossless PNG so that frame quality is preserved for inpainting.
+    When *fps* is provided, a ``-vf fps=<n>`` filter forces constant frame rate
+    output, which is required for correct audio sync on VFR sources.
+
+    Parameters
+    ----------
+    video_path : str | Path
+        Source video file.
+    out_dir : str | Path
+        Directory to write frames into. Created if it does not exist.
+    pattern : str
+        Output filename pattern, e.g. "%06d.png".
+    fps : float, optional
+        If given, force constant-rate output at this rate. Pass
+        ``VideoMeta.fps`` to guarantee A/V sync on reassembly.
+
+    Returns
+    -------
+    List[Path]
+        Sorted list of extracted frame paths.
+    """
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    cmd = [
+        "ffmpeg",
+        "-y",
+        "-i", str(video_path),
+    ]
+    if fps is not None:
+        # Force constant frame rate; handles VFR sources without re-encoding
+        # by inserting duplicate frames where the source skips.
+        cmd += ["-vf", f"fps={_fps_str(fps)}"]
+    else:
+        cmd += ["-vsync", "0"]   # passthrough for CFR sources (no dup/drop)
+
+    cmd.append(str(out_dir / pattern))
+    _run(cmd)
+
+    frames = sorted(out_dir.glob("*.png"), key=lambda p: int(p.stem))
+    if not frames:
+        raise RuntimeError(f"No frames extracted from {video_path} into {out_dir}")
+    return frames
+
+
+def extract_first_frame(video_path: str | Path, out_path: str | Path) -> Path:
+    """
+    Extract only the first frame, e.g. for mask drawing in the UI.
+
+    Parameters
+    ----------
+    video_path : str | Path
+    out_path : str | Path
+        Path to write the PNG (parent directory must exist).
+
+    Returns
+    -------
+    Path
+        Same as out_path, now guaranteed to exist.
+    """
+    out_path = Path(out_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    cmd = [
+        "ffmpeg",
+        "-y",
+        "-i", str(video_path),
+        "-frames:v", "1",
+        "-update", "1",
+        str(out_path),
+    ]
+    _run(cmd)
+
+    if not out_path.exists():
+        raise RuntimeError(f"First frame extraction failed for {video_path}")
+    return out_path
+
+
+# ---------------------------------------------------------------------------
+# Frame reassembly
+# ---------------------------------------------------------------------------
+
+def frames_to_video(
+    frames_dir: str | Path,
+    out_path: str | Path,
+    meta: VideoMeta,
+    pattern: str = "%06d.png",
+    crf: int = 16,
+) -> Path:
+    """
+    Reassemble a directory of inpainted PNG frames into an H.264 (8-bit) or
+    H.265 (10-bit) video, passing through V-Log / HDR colour metadata.
+
+    No audio is embedded here — use :func:`attach_audio` afterwards.
+
+    Parameters
+    ----------
+    frames_dir : str | Path
+        Directory containing sequentially named PNG frames.
+    out_path : str | Path
+        Output .mp4 path.
+    meta : VideoMeta
+        Source video metadata (for fps and color flags).
+    pattern : str
+        Input filename pattern matching the PNGs.
+    crf : int
+        H.264 CRF quality level. 16 = near-lossless; increase for smaller files.
+
+    Returns
+    -------
+    Path
+        Path to the written output video.
+    """
+    out_path = Path(out_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Build color metadata flags — pass through whatever the source had
+    color_flags: list[str] = []
+    if meta.color_primaries and meta.color_primaries != "unknown":
+        color_flags += ["-color_primaries", meta.color_primaries]
+    if meta.color_trc and meta.color_trc != "unknown":
+        color_flags += ["-color_trc", meta.color_trc]
+    if meta.colorspace and meta.colorspace != "unknown":
+        color_flags += ["-colorspace", meta.colorspace]
+    if meta.color_range and meta.color_range != "unknown":
+        color_flags += ["-color_range", meta.color_range]
+
+    # Choose codec + pixel format based on source bit depth.
+    # libx264 is 8-bit only — using it on 10-bit V-Log footage silently
+    # quantises every pixel value, destroying the HDR tonal range.
+    if meta.bit_depth >= 10:
+        vid_codec, pix_fmt = "libx265", "yuv420p10le"
+        # hvc1 tag makes HEVC readable by QuickTime / Safari / iOS.
+        # Only valid for MP4/MOV containers — skip for MKV etc.
+        mp4_like = Path(str(out_path)).suffix.lower() in (".mp4", ".mov")
+        extra_codec_flags: list[str] = ["-tag:v", "hvc1"] if mp4_like else []
+    else:
+        vid_codec, pix_fmt = "libx264", "yuv420p"
+        extra_codec_flags = []
+
+    cmd = [
+        "ffmpeg",
+        "-y",
+        "-framerate", _fps_str(meta.fps),
+        "-i", str(Path(frames_dir) / pattern),
+        "-c:v", vid_codec,
+        "-preset", "slow",
+        "-crf", str(crf),
+        "-pix_fmt", pix_fmt,
+        *extra_codec_flags,
+        *color_flags,
+        str(out_path),
+    ]
+    _run(cmd)
+    return out_path
+
+
+def attach_audio(
+    source_video: str | Path,
+    silent_video: str | Path,
+    out_path: str | Path,
+) -> Path:
+    """
+    Remux audio from *source_video* into *silent_video* (copy both streams,
+    no re-encode).
+
+    If the source has no audio stream the silent video is simply copied
+    to *out_path* unchanged.
+
+    Parameters
+    ----------
+    source_video : str | Path
+        Original video (audio source).
+    silent_video : str | Path
+        Inpainted video without audio.
+    out_path : str | Path
+        Final output path.
+
+    Returns
+    -------
+    Path
+    """
+    out_path = Path(out_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if not _has_audio(source_video):
+        shutil.copy2(str(silent_video), str(out_path))
+        return out_path
+
+    cmd = [
+        "ffmpeg",
+        "-y",
+        "-i", str(silent_video),   # stream 0: video
+        "-i", str(source_video),   # stream 1: audio donor
+        "-c", "copy",
+        "-map", "0:v:0",
+        "-map", "1:a:0",
+        "-shortest",               # trim to shorter stream (video)
+        str(out_path),
+    ]
+    _run(cmd)
+    return out_path
+
+
+# ---------------------------------------------------------------------------
+# Convenience: managed temp workspace
+# ---------------------------------------------------------------------------
+
+class VideoWorkspace:
+    """
+    Context manager that creates a temporary working directory and cleans it up.
+
+    Usage::
+
+        with VideoWorkspace() as ws:
+            frames = extract_frames(video_path, ws.frames_dir)
+            ...
+            out = ws.path("output_silent.mp4")
+    """
+
+    def __init__(self, prefix: str = "wm_remove_") -> None:
+        self._prefix = prefix
+        self._tmpdir: Optional[tempfile.TemporaryDirectory] = None
+
+    def __enter__(self) -> "VideoWorkspace":
+        self._tmpdir = tempfile.TemporaryDirectory(prefix=self._prefix)
+        self.root = Path(self._tmpdir.name)
+        self.frames_dir = self.root / "frames"
+        self.out_frames_dir = self.root / "out_frames"
+        self.frames_dir.mkdir()
+        self.out_frames_dir.mkdir()
+        return self
+
+    def __exit__(self, *args) -> None:
+        if self._tmpdir:
+            self._tmpdir.cleanup()
+
+    def path(self, name: str) -> Path:
+        """Return a path inside the workspace root."""
+        return self.root / name
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess:
+    """Run a subprocess, raising RuntimeError on failure."""
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"FFmpeg/ffprobe command failed (exit {result.returncode}):\n"
+            f"cmd: {' '.join(cmd)}\n"
+            f"stderr: {result.stderr[-2000:]}"  # last 2k chars
+        )
+    return result
+
+
+def _parse_rational(rat: str) -> float:
+    """Parse a 'num/den' rational string to float."""
+    parts = rat.split("/")
+    if len(parts) == 2:
+        num, den = int(parts[0]), int(parts[1])
+        return num / den if den else 0.0
+    return float(rat)
+
+
+def _fps_str(fps: float) -> str:
+    """Convert fps float to a clean string for FFmpeg -framerate."""
+    # Keep common exact fractions (24000/1001, 30000/1001, etc.)
+    common = {
+        23.976: "24000/1001",
+        29.97: "30000/1001",
+        59.94: "60000/1001",
+    }
+    for approx, s in common.items():
+        if abs(fps - approx) < 0.01:
+            return s
+    return f"{fps:.6g}"
+
+
+def _has_audio(video_path: str | Path) -> bool:
+    """Return True if the video contains at least one audio stream."""
+    cmd = [
+        "ffprobe",
+        "-v", "quiet",
+        "-print_format", "json",
+        "-show_streams",
+        "-select_streams", "a",
+        str(video_path),
+    ]
+    try:
+        result = _run(cmd)
+        data = json.loads(result.stdout)
+        return bool(data.get("streams"))
+    except RuntimeError:
+        return False

requirements.txt

@@ -0,0 +1,23 @@
+# Runtime dependencies for the Hugging Face Space
+# Pinned ranges are intentionally loose so HF's resolver can pick compatible versions.
+
+# ── Core ──────────────────────────────────────────────────────────────────
+gradio>=4.44.0,<5.0.0
+numpy>=1.24.0
+Pillow>=10.0.0
+scipy>=1.11.0        # mask dilation in pipeline/crop.py
+
+# ── Fast mode (LaMa) ──────────────────────────────────────────────────────
+simple-lama-inpainting>=0.1.2
+
+# ── Quality mode (VACE-14B) ───────────────────────────────────────────────
+# torch / torchvision are pre-installed on ZeroGPU; do not pin here.
+diffusers>=0.32.0
+transformers>=4.44.0
+accelerate>=0.33.0
+sentencepiece>=0.1.99
+# torchao — FP8 quantization (uncomment when implementing vace.py)
+# torchao>=0.6.0
+
+# ── Video I/O ─────────────────────────────────────────────────────────────
+# ffmpeg binary is provided via packages.txt; no Python wrapper needed.