Upload 19 files

.gitignore

@@ -0,0 +1,8 @@
+venv/
+__pycache__/
+*.pyc
+*.pyo
+.video_blur_ai_temp/
+blur_output_*/
+.DS_Store
+.ipynb_checkpoints/

DEPLOY_HF.md

@@ -0,0 +1,112 @@
+# Deploying to Hugging Face Spaces (ZeroGPU)
+# النشر على Hugging Face Spaces باستخدام ZeroGPU
+
+---
+
+## English
+
+### 1. Create the Space
+- Go to <https://huggingface.co/new-space>.
+- **SDK:** Gradio. **Hardware:** select **ZeroGPU** (Nvidia A100, on-demand).
+- Give it a name and create it.
+
+> ZeroGPU is free for PRO users and for Spaces owned by orgs with the right plan.
+> If ZeroGPU isn't offered on your account, a paid GPU (e.g. T4/A10G) also works —
+> the code auto-detects a normal CUDA GPU too.
+
+### 2. Add the files
+Upload every file in this folder to the Space repo (drag-and-drop in the
+**Files** tab, or use git):
+
+```bash
+git clone https://huggingface.co/spaces/<user>/<space-name>
+cd <space-name>
+cp -r /path/to/video-blur-ai/* .
+git add .
+git commit -m "Video Blur AI — image + video, ZeroGPU"
+git push
+```
+
+Make sure these are present at the repo root:
+`app.py`, `pipeline.py`, `config.py`, `requirements.txt`, `packages.txt`,
+`README.md`, and the `models/` and `utils/` folders.
+
+### 3. Let it build
+The Space installs `packages.txt` (ffmpeg + libs) then `requirements.txt`
+(this compiles SAM 2 — a few minutes the first time). When it says
+**Running**, open the app.
+
+### 4. First run
+The **first** image/video is slow: Grounding DINO + SAM 2 download and load
+onto the GPU. Subsequent runs are fast. This is normal for ZeroGPU.
+
+### 5. Optional: Variables (Settings → Variables and secrets)
+| Variable             | Default | Meaning                                   |
+| -------------------- | ------- | ----------------------------------------- |
+| `MAX_VIDEO_SECONDS`  | `30`    | Longest video accepted (GPU time budget)  |
+| `MAX_HEIGHT`         | `720`   | Frames downscaled to this height          |
+| `GPU_DURATION_VIDEO` | `120`   | Max seconds a video job may hold the GPU  |
+| `GPU_DURATION_IMAGE` | `60`    | Max seconds an image job may hold the GPU |
+| `SAM2_BUILD_CUDA`    | —       | Set to `0` only if the SAM 2 build fails  |
+
+### Troubleshooting
+- **`libGL.so.1` / cv2 import error** → confirm `packages.txt` has `libgl1`.
+- **`ffmpeg not found`** → confirm `packages.txt` has `ffmpeg`.
+- **Job killed mid-video** → the video exceeded the GPU time budget; shorten it
+  or raise `GPU_DURATION_VIDEO` / lower `MAX_HEIGHT`.
+- **SAM 2 build fails** → add variable `SAM2_BUILD_CUDA=0` and restart the build.
+- **Everything runs on CPU** → hardware isn't ZeroGPU/GPU; check Space settings.
+
+---
+
+## العربية
+
+### 1) إنشاء الـ Space
+- افتح <https://huggingface.co/new-space>.
+- **SDK:** اختر Gradio. **Hardware:** اختر **ZeroGPU** (كرت A100 عند الطلب).
+- سمّي المشروع وأنشئه.
+
+> ZeroGPU متاح مجانًا لمشتركي PRO وللمنظمات ذات الخطة المناسبة. لو مش ظاهر عندك،
+> أي كرت مدفوع (زي T4/A10G) هيشتغل برضه — الكود بيكتشف كرت CUDA العادي تلقائيًا.
+
+### 2) رفع الملفات
+ارفع كل الملفات اللي في الفولدر ده إلى مستودع الـ Space (بالسحب والإفلات من تبويب
+**Files**، أو باستخدام git):
+
+```bash
+git clone https://huggingface.co/spaces/<user>/<space-name>
+cd <space-name>
+cp -r /path/to/video-blur-ai/* .
+git add .
+git commit -m "Video Blur AI — صورة + فيديو، ZeroGPU"
+git push
+```
+
+اتأكد إن الملفات دي موجودة في جذر المستودع:
+`app.py` و`pipeline.py` و`config.py` و`requirements.txt` و`packages.txt`
+و`README.md` وفولدر `models/` وفولدر `utils/`.
+
+### 3) البناء (Build)
+الـ Space هيثبّت `packages.txt` (ffmpeg والمكتبات) وبعدها `requirements.txt`
+(ده بيبني SAM 2 وبياخد كام دقيقة أول مرة). لما تلاقي الحالة **Running** افتح التطبيق.
+
+### 4) أول تشغيل
+أول صورة أو فيديو بيكون بطيء لأن النماذج (Grounding DINO + SAM 2) بتتنزّل وتتحمّل
+على الكرت. التشغيلات اللي بعده بتبقى سريعة — وده طبيعي مع ZeroGPU.
+
+### 5) متغيّرات اختيارية (Settings → Variables and secrets)
+| المتغيّر              | الافتراضي | المعنى                                        |
+| -------------------- | --------- | --------------------------------------------- |
+| `MAX_VIDEO_SECONDS`  | `30`      | أطول فيديو مسموح به (ميزانية وقت الكرت)        |
+| `MAX_HEIGHT`         | `720`     | تصغير الإطارات لهذا الارتفاع                   |
+| `GPU_DURATION_VIDEO` | `120`     | أقصى ثوانٍ يمسك فيها الفيديو الكرت             |
+| `GPU_DURATION_IMAGE` | `60`      | أقصى ثوانٍ تمسك فيها الصورة الكرت              |
+| `SAM2_BUILD_CUDA`    | —         | حطّها `0` فقط لو فشل بناء SAM 2                |
+
+### حل المشاكل
+- **خطأ `libGL.so.1` أو استيراد cv2** → اتأكد إن `packages.txt` فيها `libgl1`.
+- **`ffmpeg not found`** → اتأكد إن `packages.txt` فيها `ffmpeg`.
+- **الفيديو بيتوقف في النص** → الفيديو تعدّى ميزانية وقت الكرت؛ قصّره أو زوّد
+  `GPU_DURATION_VIDEO` أو قلّل `MAX_HEIGHT`.
+- **فشل بناء SAM 2** → ضيف متغيّر `SAM2_BUILD_CUDA=0` وأعد البناء.
+- **كله بيشتغل على CPU** → الهاردوير مش ZeroGPU/GPU؛ راجع إعدادات الـ Space.

README.md

@@ -1,15 +1,117 @@
 ---
-title: Easy Blury
-emoji: 🔥
-colorFrom: indigo
-colorTo: pink
+title: Video Blur AI
+emoji: 🎬
+colorFrom: purple
+colorTo: blue
 sdk: gradio
-sdk_version: 6.20.0
-python_version: '3.12'
+sdk_version: 4.44.1
 app_file: app.py
 pinned: false
 license: apache-2.0
-short_description: it can blur any image or videos by prompting the model
+short_description: Blur anything in images & video by text prompt (ZeroGPU)
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎬 Video Blur AI
+
+**Text-prompted image & video object blurring.** Type what you want to blur —
+`face`, `hand`, `license plate`, `text`, `logo` — and the AI segments and blurs it.
+
+Built with **Grounding DINO** (text → boxes) + **SAM 2** (boxes → masks + tracking),
+and adapted to run on **Hugging Face Spaces with ZeroGPU**.
+
+---
+
+## ✨ Features
+
+- **Image *and* video** input — upload either.
+- **Text-Prompted Blur** — describe what to blur in plain words.
+- **Precise Segmentation** — pixel-level masks via SAM 2, not just boxes.
+- **Video Tracking** — SAM 2 tracks objects across frames automatically.
+- **Blur Types** — Gaussian blur, pixelation (mosaic), or solid black.
+- **Audio Preserved** — the original audio track is kept for videos.
+- **Detection Preview** — test your prompt on a frame before processing.
+
+## 🚀 Using it
+
+1. Open the **🖼️ Image** or **🎬 Video** tab and upload a file.
+2. Type what to blur, e.g. `face. license plate. text.`
+3. (Video) hit **Preview Detection** to sanity-check, then **Process**.
+4. Download the result.
+
+### Prompt cheatsheet
+
+| Want to blur   | Prompt                        |
+| -------------- | ----------------------------- |
+| Faces          | `face.`                       |
+| Hands          | `hand.`                       |
+| License plates | `license plate.`              |
+| Text / signs   | `text. writing.`              |
+| People         | `person.`                     |
+| Logos / brands | `logo. brand.`                |
+| Multiple       | `face. license plate. text.`  |
+
+### Settings
+
+- **Blur Strength** (11–151): higher = more blur. 51 is a good default.
+- **Edge Feathering** (3–51): smooths blur edges. 11 looks natural.
+- **Detection Threshold** (0.1–0.9): lower = more detections. 0.3 is balanced.
+- **Model Quality**: *Tiny* is faster, *Base* is more accurate.
+
+---
+
+## ⚡ ZeroGPU notes
+
+On ZeroGPU the GPU is attached only while a job runs. So:
+
+- The **first run is slower** (models download + load); later runs are fast.
+- Demo limits keep each job inside the GPU time budget:
+  **video ≤ 30 s**, processed at **≤ 720p**.
+- Raise `MAX_VIDEO_SECONDS`, `MAX_HEIGHT`, `GPU_DURATION_VIDEO` in the Space
+  **Variables** if you have a longer budget or paid hardware.
+
+See **DEPLOY_HF.md** for full deployment steps (English + العربية).
+
+---
+
+## 🖥️ Run locally
+
+```bash
+# 1. install torch for your CUDA (or CPU)
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+# 2. install the rest
+pip install -r requirements.txt
+# 3. run
+python app.py            # http://localhost:7860
+```
+
+The same `app.py` runs locally (the `spaces` decorator becomes a no-op off-Spaces).
+
+You can also process from the command line:
+
+```bash
+python cli.py input.mp4 --prompt "face. license plate." --blur-type pixelate
+```
+
+---
+
+## 📁 Structure
+
+```
+video-blur-ai/
+├── app.py               # Gradio app (Image + Video tabs, @spaces.GPU)
+├── pipeline.py          # Orchestrates detect → segment/track → blur → assemble
+├── config.py            # Settings + ZeroGPU-aware device detection
+├── cli.py               # Command-line interface (video)
+├── models/model_manager.py   # Grounding DINO + SAM 2 loading & inference
+├── utils/video_processor.py  # FFmpeg-based video I/O
+├── utils/blur_engine.py      # Blur application & mask compositing
+├── requirements.txt     # Python deps (torch provided by ZeroGPU)
+├── packages.txt         # apt deps (ffmpeg, libgl1, libglib2.0-0)
+└── DEPLOY_HF.md         # Deployment guide (EN + AR)
+```
+
+## 📝 License & Credits
+
+Apache 2.0. Built on [SAM 2](https://github.com/facebookresearch/sam2) (Meta AI),
+[Grounding DINO](https://github.com/IDEA-Research/GroundingDINO) (IDEA Research),
+and [Gradio](https://gradio.app/) (Hugging Face).

activate.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+source "/home/abdo96/.venvs/video-blur-ai/bin/activate"
+cd "/media/abdo96/ABODSALOMHA/LLMs_apps_github/video-blur-ai"
+echo "✅ Activated. venv: /home/abdo96/.venvs/video-blur-ai"

app.py

@@ -0,0 +1,540 @@
+"""
+Video Blur AI — Hugging Face Spaces (ZeroGPU) edition
+Text-prompted image & video object blurring using Grounded SAM 2.
+
+Type what you want to blur ("face. license plate. text.") and the AI
+segments and blurs it — on an uploaded image or video.
+
+Run locally:
+    python app.py            # CPU or local CUDA
+On Hugging Face Spaces:
+    Set hardware to "ZeroGPU"; this file is the app entrypoint.
+"""
+import os
+
+# ── Import `spaces` BEFORE torch so ZeroGPU can hook CUDA correctly. ──
+# When running locally (no `spaces` package) we fall back to a no-op shim
+# so the exact same file runs on CPU / local GPU unchanged.
+try:
+    import spaces  # type: ignore
+    _HAS_SPACES = True
+except Exception:  # pragma: no cover - only hit off-Spaces
+    _HAS_SPACES = False
+
+    class _SpacesShim:
+        @staticmethod
+        def GPU(*dargs, **dkwargs):
+            # Supports both @spaces.GPU and @spaces.GPU(duration=...)
+            if len(dargs) == 1 and callable(dargs[0]) and not dkwargs:
+                return dargs[0]
+
+            def _decorator(fn):
+                return fn
+
+            return _decorator
+
+    spaces = _SpacesShim()  # type: ignore
+
+import tempfile
+import gradio as gr
+import numpy as np
+from pathlib import Path
+
+from config import get_config
+from pipeline import VideoBlurPipeline
+
+# ─── Spaces / ZeroGPU tunables (override via Space "Variables") ─────
+ON_ZERO_GPU = os.environ.get("SPACES_ZERO_GPU", "").lower() in ("1", "true", "yes", "on")
+MAX_VIDEO_SECONDS = int(os.environ.get("MAX_VIDEO_SECONDS", "30"))
+MAX_HEIGHT = int(os.environ.get("MAX_HEIGHT", "720"))
+GPU_DURATION_VIDEO = int(os.environ.get("GPU_DURATION_VIDEO", "120"))
+GPU_DURATION_IMAGE = int(os.environ.get("GPU_DURATION_IMAGE", "60"))
+
+# ─── Global State ──────────────────────────────────────────────
+config = get_config()
+config.video.max_resolution = MAX_HEIGHT
+pipeline = VideoBlurPipeline(config)
+
+
+# ─── Custom CSS ────────────────────────────────────────────────
+CUSTOM_CSS = """
+.gradio-container {
+    max-width: 1200px !important;
+    margin: auto !important;
+    font-family: 'Segoe UI', system-ui, -apple-system, sans-serif !important;
+}
+.app-header {
+    text-align: center;
+    padding: 20px 0;
+    margin-bottom: 10px;
+    background: linear-gradient(135deg, #0f0c29, #302b63, #24243e);
+    border-radius: 16px;
+    color: white;
+}
+.app-header h1 {
+    font-size: 2.2em !important;
+    font-weight: 700 !important;
+    margin: 0 !important;
+    background: linear-gradient(90deg, #00d2ff, #7b2ff7, #ff6b6b);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+.app-header p { color: #a0a0c0; font-size: 1.05em; margin: 8px 0 0 0; }
+.prompt-input textarea {
+    font-size: 1.15em !important;
+    border: 2px solid #7b2ff7 !important;
+    border-radius: 12px !important;
+    padding: 14px !important;
+    transition: all 0.3s ease !important;
+}
+.prompt-input textarea:focus {
+    border-color: #00d2ff !important;
+    box-shadow: 0 0 0 3px rgba(0, 210, 255, 0.15) !important;
+}
+.process-btn {
+    background: linear-gradient(135deg, #7b2ff7, #00d2ff) !important;
+    border: none !important;
+    font-size: 1.15em !important;
+    font-weight: 600 !important;
+    padding: 14px 32px !important;
+    border-radius: 12px !important;
+    transition: all 0.3s ease !important;
+}
+.process-btn:hover {
+    transform: translateY(-2px) !important;
+    box-shadow: 0 6px 20px rgba(123, 47, 247, 0.35) !important;
+}
+.preview-btn {
+    background: linear-gradient(135deg, #ff6b6b, #ffa07a) !important;
+    border: none !important;
+    border-radius: 12px !important;
+    font-weight: 600 !important;
+}
+.status-text { font-size: 1.05em; padding: 10px; border-radius: 8px; text-align: center; }
+"""
+
+
+EXAMPLE_PROMPTS = [
+    ["face."],
+    ["face. hand."],
+    ["license plate."],
+    ["text. writing."],
+    ["person."],
+    ["logo. brand."],
+    ["phone. screen."],
+    ["face. license plate. text."],
+]
+
+
+# ─── Helpers ───────────────────────────────────────────────────
+
+def _apply_model_quality(model_quality: str):
+    """Switch the Grounding DINO checkpoint based on the quality toggle."""
+    if model_quality == "base":
+        config.model.gdino_model_id = "IDEA-Research/grounding-dino-base"
+    else:
+        config.model.gdino_model_id = "IDEA-Research/grounding-dino-tiny"
+
+
+def _resolve_path(file_obj):
+    """Gradio can hand back a path string or a file-like object."""
+    if isinstance(file_obj, str):
+        return file_obj
+    return file_obj.name if hasattr(file_obj, "name") else str(file_obj)
+
+
+# ─── Processing Functions (GPU-decorated for ZeroGPU) ──────────
+
+@spaces.GPU(duration=GPU_DURATION_IMAGE)
+def process_image(
+    image,
+    text_prompt,
+    blur_type,
+    blur_strength,
+    edge_feather,
+    detection_threshold,
+    model_quality,
+    progress=gr.Progress(),
+):
+    """Blur objects in a single uploaded image."""
+    if image is None:
+        gr.Warning("⚠️ Please upload an image first!")
+        return None, "❌ No image uploaded"
+
+    if not text_prompt or not text_prompt.strip():
+        gr.Warning("⚠️ Please enter a text prompt describing what to blur!")
+        return None, "❌ No prompt entered"
+
+    text_prompt = text_prompt.strip()
+    _apply_model_quality(model_quality)
+
+    def gradio_progress(value, text):
+        progress(value, desc=text)
+
+    try:
+        # gr.Image(type="numpy") gives RGB; the pipeline works in BGR.
+        image_bgr = np.ascontiguousarray(image[..., ::-1])
+
+        result_bgr = pipeline.process_image(
+            image_bgr=image_bgr,
+            text_prompt=text_prompt,
+            blur_type=blur_type,
+            blur_strength=int(blur_strength),
+            edge_feather=int(edge_feather),
+            detection_threshold=float(detection_threshold),
+            progress_callback=gradio_progress,
+        )
+
+        result_rgb = np.ascontiguousarray(result_bgr[..., ::-1])
+        return result_rgb, "✅ Done!"
+
+    except Exception as e:
+        error_msg = f"❌ Error: {str(e)}"
+        gr.Warning(error_msg)
+        return None, error_msg
+
+
+@spaces.GPU(duration=GPU_DURATION_VIDEO)
+def process_video(
+    video_file,
+    text_prompt,
+    blur_type,
+    blur_strength,
+    edge_feather,
+    processing_mode,
+    keyframe_interval,
+    detection_threshold,
+    model_quality,
+    progress=gr.Progress(),
+):
+    """Blur objects across an uploaded video."""
+    if video_file is None:
+        gr.Warning("⚠️ Please upload a video first!")
+        return None, "❌ No video uploaded"
+
+    if not text_prompt or not text_prompt.strip():
+        gr.Warning("⚠️ Please enter a text prompt describing what to blur!")
+        return None, "❌ No prompt entered"
+
+    text_prompt = text_prompt.strip()
+    _apply_model_quality(model_quality)
+
+    def gradio_progress(value, text):
+        progress(value, desc=text)
+
+    try:
+        video_path = _resolve_path(video_file)
+
+        # Keep each request within the ZeroGPU time budget.
+        try:
+            info = pipeline.video_processor.get_video_info(video_path)
+            if info.duration > MAX_VIDEO_SECONDS:
+                msg = (
+                    f"❌ Video is {info.duration:.0f}s long. On this demo the limit "
+                    f"is {MAX_VIDEO_SECONDS}s so it fits the ZeroGPU time budget. "
+                    f"Please trim it, or raise MAX_VIDEO_SECONDS / GPU_DURATION_VIDEO "
+                    f"in the Space variables."
+                )
+                gr.Warning(msg)
+                return None, msg
+        except Exception:
+            # If probing fails, let the pipeline surface the real error below.
+            pass
+
+        output_dir = tempfile.mkdtemp(prefix="blur_output_")
+        output_name = f"blurred_{Path(video_path).stem}.mp4"
+        output_path = os.path.join(output_dir, output_name)
+
+        result_path = pipeline.process_video(
+            video_path=video_path,
+            text_prompt=text_prompt,
+            output_path=output_path,
+            blur_type=blur_type,
+            blur_strength=int(blur_strength),
+            edge_feather=int(edge_feather),
+            processing_mode=processing_mode,
+            keyframe_interval=int(keyframe_interval),
+            detection_threshold=float(detection_threshold),
+            progress_callback=gradio_progress,
+        )
+
+        return result_path, "✅ Done! Video saved successfully."
+
+    except Exception as e:
+        error_msg = f"❌ Error: {str(e)}"
+        gr.Warning(error_msg)
+        return None, error_msg
+
+
+@spaces.GPU(duration=GPU_DURATION_IMAGE)
+def preview_detection(video_file, text_prompt, frame_slider):
+    """Preview detection on a single video frame."""
+    if video_file is None:
+        gr.Warning("⚠️ Please upload a video first!")
+        return None
+
+    if not text_prompt or not text_prompt.strip():
+        gr.Warning("⚠️ Please enter a prompt!")
+        return None
+
+    try:
+        video_path = _resolve_path(video_file)
+        vis = pipeline.preview_detection(
+            video_path,
+            text_prompt.strip(),
+            frame_number=int(frame_slider),
+        )
+        return np.ascontiguousarray(vis[..., ::-1])  # BGR -> RGB
+    except Exception as e:
+        gr.Warning(f"Preview error: {str(e)}")
+        return None
+
+
+def get_video_info_text(video_file):
+    """Show basic metadata when a video is uploaded."""
+    if video_file is None:
+        return "No video uploaded", gr.Slider(maximum=0, value=0)
+
+    try:
+        video_path = _resolve_path(video_file)
+        info = pipeline.video_processor.get_video_info(video_path)
+
+        warn = ""
+        if info.duration > MAX_VIDEO_SECONDS:
+            warn = f"  ⚠️ Longer than the {MAX_VIDEO_SECONDS}s demo limit — please trim."
+
+        text = (
+            f"📹 **{Path(video_path).name}**\n"
+            f"Resolution: {info.width}×{info.height} | "
+            f"FPS: {info.fps:.1f} | "
+            f"Frames: {info.total_frames} | "
+            f"Duration: {info.duration:.1f}s | "
+            f"Audio: {'Yes ✅' if info.has_audio else 'No ❌'}{warn}"
+        )
+        max_frame = max(0, info.total_frames - 1)
+        return text, gr.Slider(maximum=max_frame, value=0)
+
+    except Exception as e:
+        return f"❌ Error reading video: {e}", gr.Slider(maximum=0, value=0)
+
+
+# ─── UI builders ───────────────────────────────────────────────
+
+def _build_common_settings(include_video_controls: bool):
+    """Create the shared advanced-settings controls.
+
+    Returns a dict of components. New instances are created per call
+    because a Gradio component can't be reused across two layouts.
+    """
+    c = {}
+    c["model_quality"] = gr.Radio(
+        choices=[
+            ("⚡ Fast (Tiny model ~350MB, good accuracy)", "tiny"),
+            ("🎯 Accurate (Base model ~999MB, best accuracy)", "base"),
+        ],
+        value="base",
+        label="Model Quality",
+        info="Tiny downloads faster and runs faster. Base is more accurate.",
+    )
+    c["blur_type"] = gr.Radio(
+        choices=["gaussian", "pixelate", "black"],
+        value="gaussian",
+        label="Blur Type",
+        info="Gaussian = smooth blur, Pixelate = mosaic, Black = solid cover",
+    )
+    c["blur_strength"] = gr.Slider(
+        minimum=11, maximum=151, value=51, step=2,
+        label="Blur Strength", info="Higher = more blur (odd number)",
+    )
+    c["edge_feather"] = gr.Slider(
+        minimum=3, maximum=51, value=11, step=2,
+        label="Edge Feathering", info="Smooth transition at blur edges",
+    )
+    if include_video_controls:
+        c["processing_mode"] = gr.Radio(
+            choices=[
+                ("🎯 SAM 2 Video Tracking (recommended)", "video_tracking"),
+                ("⚡ Frame-by-Frame (faster, less consistent)", "frame_by_frame"),
+            ],
+            value="video_tracking",
+            label="Processing Mode",
+        )
+        c["keyframe_interval"] = gr.Slider(
+            minimum=1, maximum=30, value=5, step=1,
+            label="Keyframe Interval (frame-by-frame mode)",
+            info="Re-detect every N frames",
+        )
+    c["detection_threshold"] = gr.Slider(
+        minimum=0.1, maximum=0.9, value=0.3, step=0.05,
+        label="Detection Confidence Threshold",
+        info="Lower = more detections, higher = more precise",
+    )
+    return c
+
+
+def create_app():
+    """Build the Gradio interface."""
+    theme = gr.themes.Soft(primary_hue="violet", secondary_hue="cyan")
+
+    with gr.Blocks(title="Video Blur AI", theme=theme, css=CUSTOM_CSS) as app:
+
+        gr.HTML("""
+        <div class="app-header">
+            <h1>🎬 Video Blur AI</h1>
+            <p>Type what you want to blur — faces, hands, text, logos, anything.</p>
+            <p style="font-size: 0.85em; color: #7a7a9a;">
+                Image &amp; Video · Grounding DINO + SAM 2 · ZeroGPU
+            </p>
+        </div>
+        """)
+
+        with gr.Tabs():
+
+            # ══════════════ IMAGE TAB ══════════════
+            with gr.Tab("🖼️ Image"):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        img_input = gr.Image(label="📤 Upload Image", type="numpy")
+                        img_prompt = gr.Textbox(
+                            label="✏️ What to blur? (Text Prompt)",
+                            placeholder="e.g., face, license plate, text, logo...",
+                            info="Separate multiple objects with periods: 'face. text.'",
+                            lines=2,
+                            elem_classes=["prompt-input"],
+                        )
+                        gr.Examples(
+                            examples=EXAMPLE_PROMPTS,
+                            inputs=[img_prompt],
+                            label="💡 Example Prompts (click to use)",
+                        )
+                        with gr.Accordion("⚙️ Advanced Settings", open=False):
+                            img_s = _build_common_settings(include_video_controls=False)
+                        img_process_btn = gr.Button(
+                            "🚀 Blur Image", variant="primary", size="lg",
+                            elem_classes=["process-btn"],
+                        )
+                    with gr.Column(scale=1):
+                        img_output = gr.Image(label="Blurred Image", type="numpy")
+                        img_status = gr.Markdown("Ready to process", elem_classes=["status-text"])
+
+                img_process_btn.click(
+                    fn=process_image,
+                    inputs=[
+                        img_input, img_prompt, img_s["blur_type"], img_s["blur_strength"],
+                        img_s["edge_feather"], img_s["detection_threshold"], img_s["model_quality"],
+                    ],
+                    outputs=[img_output, img_status],
+                )
+
+            # ══════════════ VIDEO TAB ══════════════
+            with gr.Tab("🎬 Video"):
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        video_input = gr.Video(label="📤 Upload Video")
+                        video_info_text = gr.Markdown("No video uploaded")
+                        vid_prompt = gr.Textbox(
+                            label="✏️ What to blur? (Text Prompt)",
+                            placeholder="e.g., face, hand, license plate, person, text, logo...",
+                            info="Separate multiple objects with periods: 'face. hand. text.'",
+                            lines=2,
+                            elem_classes=["prompt-input"],
+                        )
+                        gr.Examples(
+                            examples=EXAMPLE_PROMPTS,
+                            inputs=[vid_prompt],
+                            label="💡 Example Prompts (click to use)",
+                        )
+                        with gr.Accordion("⚙️ Advanced Settings", open=False):
+                            vid_s = _build_common_settings(include_video_controls=True)
+
+                    with gr.Column(scale=1):
+                        with gr.Tab("🔍 Preview Detection"):
+                            preview_image = gr.Image(label="Detection Preview", type="numpy")
+                            frame_slider = gr.Slider(
+                                minimum=0, maximum=100, value=0, step=1, label="Frame Number",
+                            )
+                            preview_btn = gr.Button(
+                                "🔍 Preview Detection", variant="secondary",
+                                elem_classes=["preview-btn"],
+                            )
+                        with gr.Tab("🎬 Result"):
+                            video_output = gr.Video(label="Blurred Video")
+                            vid_status = gr.Markdown("Ready to process", elem_classes=["status-text"])
+
+                        vid_process_btn = gr.Button(
+                            "🚀 Process Video", variant="primary", size="lg",
+                            elem_classes=["process-btn"],
+                        )
+
+                video_input.change(
+                    fn=get_video_info_text,
+                    inputs=[video_input],
+                    outputs=[video_info_text, frame_slider],
+                )
+                preview_btn.click(
+                    fn=preview_detection,
+                    inputs=[video_input, vid_prompt, frame_slider],
+                    outputs=[preview_image],
+                )
+                vid_process_btn.click(
+                    fn=process_video,
+                    inputs=[
+                        video_input, vid_prompt, vid_s["blur_type"], vid_s["blur_strength"],
+                        vid_s["edge_feather"], vid_s["processing_mode"], vid_s["keyframe_interval"],
+                        vid_s["detection_threshold"], vid_s["model_quality"],
+                    ],
+                    outputs=[video_output, vid_status],
+                )
+
+        # ── Usage Guide ──
+        with gr.Accordion("📖 How to Use", open=False):
+            gr.Markdown(f"""
+            ### Quick Start
+            1. **Upload** an image or a video (image: PNG/JPG · video: MP4/AVI/MOV/MKV)
+            2. **Type** what you want to blur in the text prompt
+            3. (Video) **Preview Detection** to check the AI found the right objects
+            4. **Click** the process button to apply the blur
+            5. **Download** your result
+
+            ### Tips for Better Results
+            - Use **specific** descriptions: `face` works better than `person's head`
+            - Separate multiple objects with **periods**: `face. license plate. text.`
+            - Lower the **detection threshold** if objects aren't being found
+            - **SAM 2 Video Tracking** gives smooth, consistent blur across frames
+            - **Frame-by-Frame** is better when objects appear/disappear frequently
+
+            ### ZeroGPU Notes
+            - The GPU is attached only while a job runs, so the **first run is slower**
+              (models download + load). Later runs are fast.
+            - Demo limits: video ≤ **{MAX_VIDEO_SECONDS}s**, processed at ≤ **{MAX_HEIGHT}p**.
+              Raise `MAX_VIDEO_SECONDS`, `MAX_HEIGHT`, and `GPU_DURATION_VIDEO`
+              in the Space **Variables** if you have a longer GPU budget.
+            """)
+
+    return app
+
+
+# ─── Entry Point ───────────────────────────────────────────────
+
+if __name__ == "__main__":
+    print("\n" + "=" * 60)
+    print("  🎬 Video Blur AI - Starting...")
+    print("=" * 60)
+
+    demo = create_app()
+    demo.queue()  # serialize GPU access + enable progress
+
+    if ON_ZERO_GPU or os.environ.get("SPACE_ID"):
+        # On Spaces, let the platform manage host/port.
+        demo.launch()
+    else:
+        import argparse
+
+        parser = argparse.ArgumentParser(description="Video Blur AI")
+        parser.add_argument("--port", type=int, default=7860, help="Server port")
+        parser.add_argument("--share", action="store_true", help="Create public link")
+        parser.add_argument("--host", type=str, default="0.0.0.0", help="Server host")
+        args = parser.parse_args()
+
+        demo.launch(server_name=args.host, server_port=args.port, share=args.share)

cli.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+Video Blur AI - Command Line Interface
+
+Usage:
+    python cli.py input.mp4 --prompt "face. license plate." --output blurred.mp4
+    python cli.py input.mp4 --prompt "hand." --blur-type pixelate --strength 15
+"""
+import argparse
+import sys
+from pathlib import Path
+
+from config import get_config
+from pipeline import VideoBlurPipeline
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="🎬 Video Blur AI - Text-prompted video object blurring",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s video.mp4 --prompt "face."
+  %(prog)s video.mp4 --prompt "face. license plate." --blur-type pixelate
+  %(prog)s video.mp4 --prompt "hand." --strength 99 --mode frame_by_frame
+  %(prog)s video.mp4 --prompt "person." --blur-type black --output censored.mp4
+        """
+    )
+    
+    parser.add_argument("video", help="Input video file path")
+    parser.add_argument("-p", "--prompt", required=True, 
+                       help="Text prompt describing what to blur (e.g., 'face. hand.')")
+    parser.add_argument("-o", "--output", default=None,
+                       help="Output video path (default: input_blurred.mp4)")
+    
+    # Blur settings
+    parser.add_argument("--blur-type", choices=["gaussian", "pixelate", "black"],
+                       default="gaussian", help="Type of blur effect")
+    parser.add_argument("--strength", type=int, default=51,
+                       help="Blur strength (odd number, default: 51)")
+    parser.add_argument("--feather", type=int, default=11,
+                       help="Edge feathering (odd number, default: 11)")
+    
+    # Processing settings
+    parser.add_argument("--mode", choices=["video_tracking", "frame_by_frame"],
+                       default="video_tracking", help="Processing mode")
+    parser.add_argument("--keyframe-interval", type=int, default=5,
+                       help="Keyframe detection interval (frame_by_frame mode)")
+    parser.add_argument("--threshold", type=float, default=0.3,
+                       help="Detection confidence threshold (0.1-0.9)")
+    
+    args = parser.parse_args()
+    
+    # Validate input
+    if not Path(args.video).exists():
+        print(f"❌ Video not found: {args.video}")
+        sys.exit(1)
+    
+    # Generate output path if not specified
+    if args.output is None:
+        p = Path(args.video)
+        args.output = str(p.parent / f"{p.stem}_blurred{p.suffix}")
+    
+    # Run pipeline
+    print("\n" + "="*60)
+    print("  🎬 Video Blur AI - CLI Mode")
+    print("="*60)
+    print(f"  Input:   {args.video}")
+    print(f"  Prompt:  {args.prompt}")
+    print(f"  Blur:    {args.blur_type} (strength={args.strength})")
+    print(f"  Mode:    {args.mode}")
+    print(f"  Output:  {args.output}")
+    print("="*60 + "\n")
+    
+    config = get_config()
+    pipeline = VideoBlurPipeline(config)
+    
+    def cli_progress(value, text):
+        bar_length = 30
+        filled = int(bar_length * value)
+        bar = "█" * filled + "░" * (bar_length - filled)
+        print(f"\r  [{bar}] {value*100:5.1f}% | {text}", end="", flush=True)
+        if value >= 1.0:
+            print()
+    
+    try:
+        output = pipeline.process_video(
+            video_path=args.video,
+            text_prompt=args.prompt,
+            output_path=args.output,
+            blur_type=args.blur_type,
+            blur_strength=args.strength,
+            edge_feather=args.feather,
+            processing_mode=args.mode,
+            keyframe_interval=args.keyframe_interval,
+            detection_threshold=args.threshold,
+            progress_callback=cli_progress,
+        )
+        
+        print(f"\n✅ Output saved to: {output}")
+        
+    except KeyboardInterrupt:
+        print("\n\n⚠️ Processing cancelled by user")
+        sys.exit(1)
+    except Exception as e:
+        print(f"\n\n❌ Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

config.py

@@ -0,0 +1,109 @@
+"""
+Configuration settings for Video Blur AI
+Adapted for Hugging Face Spaces (ZeroGPU) + local use.
+"""
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class ModelConfig:
+    """Model configuration"""
+    # SAM 2 settings
+    sam2_checkpoint: str = "facebook/sam2.1-hiera-base-plus"
+    sam2_model_cfg: str = "configs/sam2.1/sam2.1_hiera_b+.yaml"
+
+    # Grounding DINO settings
+    gdino_model_id: str = "IDEA-Research/grounding-dino-base"
+    gdino_box_threshold: float = 0.3
+    gdino_text_threshold: float = 0.25
+
+    # Device
+    device: str = "cuda"
+    use_fp16: bool = True
+
+
+@dataclass
+class VideoConfig:
+    """Video processing configuration"""
+    # Frame extraction
+    max_resolution: int = 1080       # Max height for processing
+    keyframe_interval: int = 5       # Run detection every N frames
+
+    # Output
+    output_codec: str = "libx264"
+    output_crf: int = 18             # Quality (lower = better, 18-23 recommended)
+    output_preset: str = "medium"    # Encoding speed preset
+    pixel_format: str = "yuv420p"
+
+    # Temp directory
+    temp_dir: str = os.path.join(os.path.expanduser("~"), ".video_blur_ai_temp")
+
+
+@dataclass
+class BlurConfig:
+    """Blur settings"""
+    blur_strength: int = 51          # Gaussian kernel size (must be odd)
+    edge_feather: int = 11           # Edge softening kernel (must be odd)
+    blur_type: str = "gaussian"      # gaussian, pixelate, black
+    pixelate_size: int = 15          # Block size for pixelation
+
+
+@dataclass
+class AppConfig:
+    """Main application config"""
+    model: ModelConfig = field(default_factory=ModelConfig)
+    video: VideoConfig = field(default_factory=VideoConfig)
+    blur: BlurConfig = field(default_factory=BlurConfig)
+
+    # App settings
+    max_video_duration: int = 600    # Max 10 minutes
+    max_file_size_mb: int = 500
+    server_port: int = 7860
+    share: bool = False
+
+
+def _is_zero_gpu() -> bool:
+    """Detect a Hugging Face ZeroGPU Space.
+
+    On ZeroGPU the physical GPU is attached only inside functions wrapped
+    with @spaces.GPU, so torch.cuda.is_available() is typically False at
+    import time. We therefore rely on the env var HF sets instead.
+    """
+    return os.environ.get("SPACES_ZERO_GPU", "").lower() in ("1", "true", "yes", "on")
+
+
+def get_config() -> AppConfig:
+    """Get application configuration with device auto-detection."""
+    config = AppConfig()
+
+    import torch
+
+    if _is_zero_gpu():
+        # Target CUDA: the GPU becomes available inside @spaces.GPU calls,
+        # even though it is not attached to this (import-time) process.
+        config.model.device = "cuda"
+        config.model.use_fp16 = True
+        print("✅ Hugging Face ZeroGPU detected — targeting CUDA inside @spaces.GPU")
+    elif torch.cuda.is_available():
+        config.model.device = "cuda"
+        config.model.use_fp16 = True
+        gpu_name = torch.cuda.get_device_name(0)
+        vram_gb = torch.cuda.get_device_properties(0).total_memory / (1024 ** 3)
+        print(f"✅ GPU: {gpu_name} ({vram_gb:.1f} GB VRAM)")
+
+        # Use smaller model for low VRAM
+        if vram_gb < 8:
+            config.model.sam2_checkpoint = "facebook/sam2.1-hiera-small"
+            config.model.sam2_model_cfg = "configs/sam2.1/sam2.1_hiera_s.yaml"
+            print("📉 Low VRAM detected, using SAM 2 Small model")
+    else:
+        config.model.device = "cpu"
+        config.model.use_fp16 = False
+        print("⚠️  CUDA not available, using CPU (will be slow)")
+
+    # Create temp directory
+    os.makedirs(config.video.temp_dir, exist_ok=True)
+
+    return config

docs/README_full.md

@@ -0,0 +1,212 @@
+# 🎬 Video Blur AI
+
+**Text-prompted video object blurring** — type what you want to blur, and AI does the rest.
+
+Built with **Grounding DINO + SAM 2** for precise, prompt-driven segmentation and tracking.
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Python-3.10+-blue?logo=python" alt="Python">
+  <img src="https://img.shields.io/badge/PyTorch-2.1+-red?logo=pytorch" alt="PyTorch">
+  <img src="https://img.shields.io/badge/License-Apache%202.0-green" alt="License">
+  <img src="https://img.shields.io/badge/GPU-NVIDIA%208GB+-76b900?logo=nvidia" alt="GPU">
+</p>
+
+---
+
+## ✨ Features
+
+- **Text-Prompted Blur**: Type "face", "hand", "license plate" — blur anything describable
+- **Precise Segmentation**: Pixel-level masks via SAM 2, not just bounding boxes
+- **Video Tracking**: SAM 2's memory mechanism tracks objects across frames automatically
+- **Multiple Blur Types**: Gaussian blur, pixelation (mosaic), or solid black overlay
+- **Audio Preservation**: Original audio track is preserved in the output
+- **Web Interface**: Beautiful Gradio UI with live preview and progress tracking
+- **Detection Preview**: Test your prompt on any frame before processing
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Video Blur AI                          │
+├─────────────┬──────────────┬──────────────┬────────────────┤
+│  Gradio UI  │  Grounding   │   SAM 2.1    │  FFmpeg +      │
+│  (Web App)  │  DINO        │  (Segment &  │  OpenCV        │
+│             │  (Text →     │   Track)     │  (Video I/O    │
+│             │   Boxes)     │              │   & Blur)      │
+├─────────────┴──────────────┴──────────────┴────────────────┤
+│                    Processing Pipeline                      │
+│                                                             │
+│  Video → Extract Frames → Detect (keyframe) → Track →      │
+│  → Generate Masks → Apply Blur → Reassemble → Output       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Processing Modes
+
+| Mode | How it works | Best for |
+|------|-------------|----------|
+| **SAM 2 Video Tracking** | Detect on frame 1, track through entire video | Consistent blur, moving objects |
+| **Frame-by-Frame** | Re-detect every N frames, reuse masks between | Objects appearing/disappearing |
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.10+
+- NVIDIA GPU with 8+ GB VRAM (12+ GB recommended)
+- CUDA 11.8+ / CUDA 12.x
+- FFmpeg
+
+### Automated Setup (Recommended)
+```bash
+git clone <this-repo>
+cd video-blur-ai
+chmod +x setup.sh
+./setup.sh
+```
+
+### Manual Setup
+```bash
+# 1. Create virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# 2. Install PyTorch (CUDA 12.1)
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+
+# 3. Install SAM 2
+pip install git+https://github.com/facebookresearch/sam2.git
+
+# 4. Install Grounding DINO
+pip install git+https://github.com/IDEA-Research/GroundingDINO.git
+
+# 5. Install other dependencies
+pip install -r requirements.txt
+```
+
+### Run the App
+```bash
+source venv/bin/activate
+python app.py
+# Open http://localhost:7860
+```
+
+For a public shareable link:
+```bash
+python app.py --share
+```
+
+---
+
+## 💡 Usage Tips
+
+### Effective Prompts
+
+| Want to blur | Prompt | Notes |
+|-------------|--------|-------|
+| Faces | `face.` | Works great for front & side views |
+| Hands | `hand.` | Both palms and fists |
+| License plates | `license plate.` | Vehicles in motion too |
+| Text/Writing | `text. writing.` | Signs, documents, screens |
+| People (full body) | `person.` | Entire silhouette |
+| Logos/Brands | `logo. brand.` | On clothing, products |
+| Multiple things | `face. license plate. text.` | Separate with periods |
+| Phone screens | `phone screen.` | Mobile devices |
+
+### Settings Guide
+
+- **Blur Strength** (11-151): Higher = more blur. 51 is good default.
+- **Edge Feathering** (3-51): Smooths blur edges. 11 for natural look.
+- **Detection Threshold** (0.1-0.9): Lower = more detections. 0.3 is balanced.
+- **Keyframe Interval** (1-30): Frame-by-frame mode only. 5 = detect every 5 frames.
+
+---
+
+## 📁 Project Structure
+
+```
+video-blur-ai/
+├── app.py                  # Main Gradio web application
+├── pipeline.py             # Processing pipeline orchestrator
+├── config.py               # All configuration settings
+├── setup.sh                # Automated setup script
+├── requirements.txt        # Python dependencies
+├── models/
+│   ├── __init__.py
+│   └── model_manager.py    # Grounding DINO + SAM 2 loading & inference
+├── utils/
+│   ├── __init__.py
+│   ├── video_processor.py  # FFmpeg-based video I/O
+│   └── blur_engine.py      # Blur application & mask compositing
+└── README.md
+```
+
+---
+
+## 🔧 Technical Details
+
+### Models Used
+
+| Model | Purpose | Size | Source |
+|-------|---------|------|--------|
+| Grounding DINO (SwinB) | Text → Bounding Boxes | ~700 MB | [IDEA Research](https://github.com/IDEA-Research/GroundingDINO) |
+| SAM 2.1 Hiera B+ | Boxes → Masks + Video Tracking | ~350 MB | [Meta](https://github.com/facebookresearch/sam2) |
+
+### Performance (approximate)
+
+| GPU | Video Tracking Mode | Frame-by-Frame Mode |
+|-----|-------------------|---------------------|
+| RTX 4090 | ~8-15 FPS | ~5-10 FPS |
+| RTX 3080 | ~5-10 FPS | ~3-7 FPS |
+| RTX 3070 | ~3-7 FPS | ~2-5 FPS |
+| CPU only | ~0.1-0.3 FPS | ~0.1-0.2 FPS |
+
+### Memory Usage
+
+| Component | VRAM | RAM |
+|-----------|------|-----|
+| Grounding DINO | ~3-4 GB | ~2 GB |
+| SAM 2.1 B+ | ~4-6 GB | ~2 GB |
+| Video frames | ~1-3 GB | ~2-8 GB |
+| **Total** | **~8-13 GB** | **~6-12 GB** |
+
+---
+
+## 🔄 API / CLI Usage
+
+You can also use the pipeline programmatically:
+
+```python
+from config import get_config
+from pipeline import VideoBlurPipeline
+
+config = get_config()
+pipeline = VideoBlurPipeline(config)
+
+# Process a video
+output = pipeline.process_video(
+    video_path="input.mp4",
+    text_prompt="face. license plate.",
+    blur_type="gaussian",
+    blur_strength=51,
+)
+print(f"Output: {output}")
+```
+
+---
+
+## 📝 License
+
+Apache 2.0 — Both Grounding DINO and SAM 2 use Apache 2.0 compatible licenses.
+
+---
+
+## 🙏 Credits
+
+- [SAM 2](https://github.com/facebookresearch/sam2) by Meta AI
+- [Grounding DINO](https://github.com/IDEA-Research/GroundingDINO) by IDEA Research
+- [Grounded SAM 2](https://github.com/IDEA-Research/Grounded-SAM-2) by IDEA Research
+- [Gradio](https://gradio.app/) by Hugging Face

models/__init__.py

@@ -0,0 +1 @@
+# Video Blur AI - Models

models/model_manager.py

@@ -0,0 +1,419 @@
+"""
+Model Manager - Handles loading and inference for Grounding DINO + SAM 2
+"""
+import os
+import torch
+import numpy as np
+from PIL import Image
+from typing import List, Dict, Tuple, Optional
+from dataclasses import dataclass
+
+@dataclass
+class DetectionResult:
+    """Single detection result"""
+    label: str
+    confidence: float
+    bbox: np.ndarray        # [x1, y1, x2, y2]
+    mask: Optional[np.ndarray] = None  # H x W binary mask
+
+
+class ModelManager:
+    """Manages Grounding DINO + SAM 2 pipeline"""
+    
+    def __init__(self, config):
+        self.config = config
+        self.device = config.model.device
+        self.gdino_model = None
+        self.gdino_processor = None
+        self.sam2_predictor = None
+        self.sam2_video_predictor = None
+        self._loaded = False
+    
+    def load_models(self, progress_callback=None):
+        """Load all models into memory"""
+        if self._loaded:
+            return
+        
+        if progress_callback:
+            progress_callback(0.1, "Loading Grounding DINO...")
+        self._load_grounding_dino()
+        
+        if progress_callback:
+            progress_callback(0.5, "Loading SAM 2...")
+        self._load_sam2()
+        
+        self._loaded = True
+        if progress_callback:
+            progress_callback(1.0, "Models loaded ✅")
+    
+    def _load_grounding_dino(self):
+        """Load Grounding DINO model"""
+        try:
+            # Try HuggingFace Transformers first (easier setup)
+            from transformers import AutoProcessor, AutoModelForZeroShotObjectDetection
+            
+            model_id = self.config.model.gdino_model_id
+            print(f"📥 Loading {model_id} (cached in ~/.cache/huggingface after first download)")
+            self.gdino_processor = AutoProcessor.from_pretrained(model_id)
+            self.gdino_model = AutoModelForZeroShotObjectDetection.from_pretrained(
+                model_id
+            ).to(self.device)
+            
+            if self.config.model.use_fp16 and self.device == "cuda":
+                self.gdino_model = self.gdino_model.half()
+            
+            self.gdino_model.eval()
+            print(f"✅ Grounding DINO loaded from {model_id}")
+            self._gdino_backend = "transformers"
+            
+        except Exception as e:
+            print(f"⚠️  Transformers loading failed ({e}), trying GroundingDINO package...")
+            self._load_grounding_dino_native()
+    
+    def _load_grounding_dino_native(self):
+        """Fallback: Load Grounding DINO from official package"""
+        try:
+            from groundingdino.util.inference import load_model, predict
+            from huggingface_hub import hf_hub_download
+            
+            # Download checkpoint
+            ckpt_path = hf_hub_download(
+                repo_id="ShilongLiu/GroundingDINO",
+                filename="groundingdino_swinb_cogcoor.pth"
+            )
+            config_path = hf_hub_download(
+                repo_id="ShilongLiu/GroundingDINO",
+                filename="GroundingDINO_SwinB.cfg.py"
+            )
+            
+            self.gdino_model = load_model(config_path, ckpt_path, device=self.device)
+            self._gdino_backend = "native"
+            print("✅ Grounding DINO loaded (native)")
+        except ImportError:
+            raise RuntimeError(
+                "❌ Grounding DINO failed to load!\n"
+                "The HuggingFace Transformers backend failed, and the native package is not installed.\n"
+                "Fix: pip install git+https://github.com/IDEA-Research/GroundingDINO.git\n"
+                "Or check that 'transformers' is up to date: pip install -U transformers"
+            )
+    
+    def _load_sam2(self):
+        """Load SAM 2 model"""
+        try:
+            # Try importing from sam2 (PyPI: pip install sam-2)
+            try:
+                from sam2.build_sam import build_sam2, build_sam2_video_predictor
+                from sam2.sam2_image_predictor import SAM2ImagePredictor
+            except ImportError:
+                # Older versions may have different import paths
+                from sam2.build_sam import build_sam2
+                from sam2.automatic_mask_generator import SAM2ImagePredictor
+                build_sam2_video_predictor = None
+            
+            from huggingface_hub import hf_hub_download
+            
+            checkpoint = self.config.model.sam2_checkpoint
+            model_cfg = self.config.model.sam2_model_cfg
+            
+            # Download checkpoint from HuggingFace
+            ckpt_map = {
+                "facebook/sam2.1-hiera-base-plus": "sam2.1_hiera_base_plus.pt",
+                "facebook/sam2.1-hiera-small": "sam2.1_hiera_small.pt",
+                "facebook/sam2.1-hiera-large": "sam2.1_hiera_large.pt",
+                "facebook/sam2.1-hiera-tiny": "sam2.1_hiera_tiny.pt",
+            }
+            ckpt_file = ckpt_map.get(checkpoint, "sam2.1_hiera_base_plus.pt")
+            
+            try:
+                ckpt_path = hf_hub_download(
+                    repo_id=checkpoint,
+                    filename=ckpt_file
+                )
+            except Exception:
+                # Try without version suffix
+                alt_file = ckpt_file.replace("sam2.1_", "sam2_")
+                ckpt_path = hf_hub_download(
+                    repo_id=checkpoint,
+                    filename=alt_file
+                )
+            
+            # Build image predictor
+            sam2_model = build_sam2(model_cfg, ckpt_path, device=self.device)
+            self.sam2_predictor = SAM2ImagePredictor(sam2_model)
+            
+            # Build video predictor (may not be available in all versions)
+            if build_sam2_video_predictor is not None:
+                try:
+                    self.sam2_video_predictor = build_sam2_video_predictor(
+                        model_cfg, ckpt_path, device=self.device
+                    )
+                except Exception as e:
+                    print(f"⚠️  Video predictor not available: {e}")
+                    print("   Will use frame-by-frame mode only.")
+                    self.sam2_video_predictor = None
+            else:
+                self.sam2_video_predictor = None
+            
+            print(f"✅ SAM 2 loaded from {checkpoint}")
+            
+        except Exception as e:
+            print(f"❌ SAM 2 loading failed: {e}")
+            print("   Make sure sam-2 is installed: pip install sam-2>=1.1.0")
+            raise
+    
+    def detect_objects(self, image: np.ndarray, text_prompt: str) -> List[DetectionResult]:
+        """
+        Detect objects in image using text prompt via Grounding DINO
+        
+        Args:
+            image: BGR numpy array (H, W, 3)
+            text_prompt: Text description of objects to detect (e.g., "face. hand. text.")
+        
+        Returns:
+            List of DetectionResult with bounding boxes
+        """
+        # Normalize prompt - ensure it ends with period for GDINO
+        prompt = text_prompt.strip()
+        if not prompt.endswith("."):
+            prompt += "."
+        
+        pil_image = Image.fromarray(image[..., ::-1])  # BGR -> RGB -> PIL
+        
+        if self._gdino_backend == "transformers":
+            return self._detect_transformers(pil_image, prompt)
+        else:
+            return self._detect_native(image, prompt)
+    
+    def _detect_transformers(self, pil_image: Image.Image, prompt: str) -> List[DetectionResult]:
+        """Detection using HuggingFace Transformers (auto-detects API version)"""
+        import inspect
+        
+        inputs = self.gdino_processor(
+            images=pil_image, 
+            text=prompt, 
+            return_tensors="pt"
+        ).to(self.device)
+        
+        with torch.no_grad():
+            if self.config.model.use_fp16 and self.device == "cuda":
+                with torch.autocast("cuda"):
+                    outputs = self.gdino_model(**inputs)
+            else:
+                outputs = self.gdino_model(**inputs)
+        
+        target_sizes = [pil_image.size[::-1]]  # (H, W)
+        threshold = self.config.model.gdino_box_threshold
+        
+        # Inspect the actual function signature to know which params it accepts
+        post_fn = self.gdino_processor.post_process_grounded_object_detection
+        sig = inspect.signature(post_fn)
+        param_names = list(sig.parameters.keys())
+        
+        kwargs = {"target_sizes": target_sizes}
+        args = [outputs]
+        
+        # Add threshold with correct name
+        if "threshold" in param_names:
+            kwargs["threshold"] = threshold
+        elif "box_threshold" in param_names:
+            kwargs["box_threshold"] = threshold
+            kwargs["text_threshold"] = self.config.model.gdino_text_threshold
+        
+        # Add input_ids if accepted
+        if "input_ids" in param_names:
+            args.append(inputs.get("input_ids", None))
+        
+        results = post_fn(*args, **kwargs)[0]
+        
+        detections = []
+        
+        # Handle both 'text_labels' (new) and 'labels' (old) keys
+        labels = results.get("text_labels", results.get("labels", []))
+        
+        for bbox, score, label in zip(
+            results["boxes"].cpu().numpy(),
+            results["scores"].cpu().numpy(),
+            labels
+        ):
+            label_str = str(label) if not isinstance(label, str) else label
+            detections.append(DetectionResult(
+                label=label_str,
+                confidence=float(score),
+                bbox=bbox
+            ))
+        
+        return detections
+    
+    def _detect_native(self, image: np.ndarray, prompt: str) -> List[DetectionResult]:
+        """Detection using native GroundingDINO"""
+        from groundingdino.util.inference import predict
+        from groundingdino.util.utils import get_phrases_from_posmap
+        import groundingdino.datasets.transforms as T
+        
+        transform = T.Compose([
+            T.RandomResize([800], max_size=1333),
+            T.ToTensor(),
+            T.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
+        ])
+        
+        pil_image = Image.fromarray(image[..., ::-1])
+        transformed, _ = transform(pil_image, None)
+        
+        boxes, logits, phrases = predict(
+            model=self.gdino_model,
+            image=transformed,
+            caption=prompt,
+            box_threshold=self.config.model.gdino_box_threshold,
+            text_threshold=self.config.model.gdino_text_threshold,
+            device=self.device
+        )
+        
+        h, w = image.shape[:2]
+        detections = []
+        for box, score, label in zip(boxes, logits, phrases):
+            # Convert from [cx, cy, w, h] normalized to [x1, y1, x2, y2] pixels
+            cx, cy, bw, bh = box.cpu().numpy()
+            x1 = (cx - bw/2) * w
+            y1 = (cy - bh/2) * h
+            x2 = (cx + bw/2) * w
+            y2 = (cy + bh/2) * h
+            
+            detections.append(DetectionResult(
+                label=label,
+                confidence=float(score),
+                bbox=np.array([x1, y1, x2, y2])
+            ))
+        
+        return detections
+    
+    def segment_with_boxes(self, image: np.ndarray, boxes: np.ndarray) -> np.ndarray:
+        """
+        Generate segmentation masks from bounding boxes using SAM 2
+        
+        Args:
+            image: BGR numpy array (H, W, 3)
+            boxes: Array of boxes [N, 4] in [x1, y1, x2, y2] format
+        
+        Returns:
+            Combined binary mask (H, W) uint8
+        """
+        rgb_image = image[..., ::-1]  # BGR -> RGB
+        self.sam2_predictor.set_image(rgb_image)
+        
+        if len(boxes) == 0:
+            return np.zeros(image.shape[:2], dtype=np.uint8)
+        
+        input_boxes = torch.tensor(boxes, dtype=torch.float32, device=self.device)
+        
+        with torch.no_grad():
+            if self.config.model.use_fp16 and self.device == "cuda":
+                with torch.autocast("cuda"):
+                    masks, scores, _ = self.sam2_predictor.predict(
+                        box=input_boxes,
+                        multimask_output=False,
+                    )
+            else:
+                masks, scores, _ = self.sam2_predictor.predict(
+                    box=input_boxes,
+                    multimask_output=False,
+                )
+        
+        # Combine all masks into single mask
+        if isinstance(masks, torch.Tensor):
+            masks = masks.cpu().numpy()
+        
+        combined_mask = np.zeros(image.shape[:2], dtype=np.uint8)
+        for mask in masks:
+            if mask.ndim == 3:
+                mask = mask[0]  # Take first mask if multimask
+            combined_mask = np.maximum(combined_mask, (mask > 0.5).astype(np.uint8) * 255)
+        
+        return combined_mask
+    
+    def init_video_tracking(self, frames_dir: str, detections: List[DetectionResult]) -> dict:
+        """
+        Initialize SAM 2 video tracking from first-frame detections
+        
+        Args:
+            frames_dir: Directory containing numbered JPEG frames
+            detections: Detection results from first frame
+        
+        Returns:
+            SAM 2 inference state
+        """
+        state = self.sam2_video_predictor.init_state(video_path=frames_dir)
+        
+        # Add each detection as a tracking target
+        for idx, det in enumerate(detections):
+            box = det.bbox
+            _, _, mask_logits = self.sam2_video_predictor.add_new_points_or_box(
+                inference_state=state,
+                frame_idx=0,
+                obj_id=idx + 1,
+                box=box,
+            )
+        
+        return state
+    
+    def propagate_video(self, state, num_frames: int, progress_callback=None):
+        """
+        Propagate masks through all video frames
+        
+        Args:
+            state: SAM 2 inference state
+            num_frames: Total number of frames
+            progress_callback: Optional callback(frame_idx, total_frames)
+        
+        Returns:
+            Dict mapping frame_idx -> combined binary mask (H, W)
+        """
+        frame_masks = {}
+        
+        for frame_idx, obj_ids, mask_logits in self.sam2_video_predictor.propagate_in_video(state):
+            # Combine all object masks
+            masks = (mask_logits > 0.0).cpu().numpy()  # [N, 1, H, W]
+            combined = np.zeros(masks.shape[2:], dtype=np.uint8)
+            
+            for mask in masks:
+                combined = np.maximum(combined, (mask[0] > 0).astype(np.uint8) * 255)
+            
+            frame_masks[frame_idx] = combined
+            
+            if progress_callback:
+                progress_callback(frame_idx, num_frames)
+        
+        return frame_masks
+    
+    def detect_and_segment_frame(self, frame: np.ndarray, text_prompt: str) -> np.ndarray:
+        """
+        Full pipeline: detect + segment on a single frame
+        
+        Args:
+            frame: BGR numpy array
+            text_prompt: What to detect
+        
+        Returns:
+            Binary mask (H, W) uint8, 0 or 255
+        """
+        detections = self.detect_objects(frame, text_prompt)
+        
+        if not detections:
+            return np.zeros(frame.shape[:2], dtype=np.uint8)
+        
+        boxes = np.array([d.bbox for d in detections])
+        mask = self.segment_with_boxes(frame, boxes)
+        
+        return mask
+    
+    def unload_models(self):
+        """Free GPU memory"""
+        self.gdino_model = None
+        self.gdino_processor = None
+        self.sam2_predictor = None
+        self.sam2_video_predictor = None
+        self._loaded = False
+        
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+        
+        print("🗑️  Models unloaded")

packages.txt

@@ -0,0 +1,3 @@
+ffmpeg
+libgl1
+libglib2.0-0

pipeline.py

@@ -0,0 +1,386 @@
+"""
+Processing Pipeline - Orchestrates the complete video blur workflow
+
+Two processing modes:
+1. SAM 2 Video Mode: Extract frames → detect on keyframe → track with SAM 2 → blur → assemble
+   Best for: consistent tracking, objects that move continuously
+   
+2. Frame-by-Frame Mode: Read frame → detect + segment → blur → write
+   Best for: simplicity, objects appearing/disappearing frequently, lower VRAM
+"""
+import os
+import cv2
+import time
+import shutil
+import numpy as np
+from pathlib import Path
+from typing import Optional, Callable
+
+from config import AppConfig
+from models.model_manager import ModelManager
+from utils.video_processor import VideoProcessor
+from utils.blur_engine import BlurEngine
+
+
+class VideoBlurPipeline:
+    """Complete video blur processing pipeline"""
+    
+    def __init__(self, config: AppConfig):
+        self.config = config
+        self.model_manager = ModelManager(config)
+        self.video_processor = VideoProcessor(config)
+        self.blur_engine = BlurEngine(config)
+        self._models_loaded = False
+        self._last_gdino_id = None
+    
+    def ensure_models_loaded(self, progress_callback=None):
+        """Load models if not already loaded or if config changed"""
+        if not self._models_loaded or self._last_gdino_id != self.config.model.gdino_model_id:
+            # Unload old models if switching
+            if self._models_loaded:
+                self.model_manager.unload_models()
+                self._models_loaded = False
+            
+            self.model_manager = ModelManager(self.config)
+            self.model_manager.load_models(progress_callback)
+            self._models_loaded = True
+            self._last_gdino_id = self.config.model.gdino_model_id
+    
+    def process_video(
+        self,
+        video_path: str,
+        text_prompt: str,
+        output_path: Optional[str] = None,
+        blur_type: str = "gaussian",
+        blur_strength: int = 51,
+        edge_feather: int = 11,
+        processing_mode: str = "video_tracking",
+        keyframe_interval: int = 5,
+        detection_threshold: float = 0.3,
+        progress_callback: Optional[Callable] = None,
+    ) -> str:
+        """
+        Main entry point: Process video with text-prompted blur
+        
+        Args:
+            video_path: Path to input video
+            text_prompt: What to blur (e.g., "face", "hand", "license plate")
+            output_path: Where to save result (auto-generated if None)
+            blur_type: "gaussian", "pixelate", or "black"
+            blur_strength: Blur kernel size
+            edge_feather: Edge softening amount
+            processing_mode: "video_tracking" or "frame_by_frame"
+            keyframe_interval: How often to re-detect (frame_by_frame mode)
+            detection_threshold: Confidence threshold for detection
+            progress_callback: Callback(progress_float, status_text)
+        
+        Returns:
+            Path to output video
+        """
+        start_time = time.time()
+        
+        # Setup
+        if output_path is None:
+            base = Path(video_path)
+            output_path = str(base.parent / f"{base.stem}_blurred{base.suffix}")
+        
+        # Update config
+        self.config.model.gdino_box_threshold = detection_threshold
+        self.config.blur.blur_type = blur_type
+        self.config.blur.blur_strength = blur_strength
+        self.config.blur.edge_feather = edge_feather
+        
+        # Load models
+        self._progress(progress_callback, 0.05, "🔄 Loading AI models...")
+        self.ensure_models_loaded()
+        
+        # Get video info
+        self._progress(progress_callback, 0.1, "📹 Analyzing video...")
+        video_info = self.video_processor.get_video_info(video_path)
+        print(f"📹 Input: {video_info.width}x{video_info.height}, "
+              f"{video_info.fps:.1f} FPS, {video_info.total_frames} frames, "
+              f"{video_info.duration:.1f}s")
+        
+        # Choose processing mode
+        if processing_mode == "video_tracking":
+            # Check if video predictor is available
+            if self.model_manager.sam2_video_predictor is None:
+                print("⚠️  SAM 2 video predictor not available, falling back to frame-by-frame mode")
+                processing_mode = "frame_by_frame"
+        
+        if processing_mode == "video_tracking":
+            result = self._process_video_tracking(
+                video_path, text_prompt, output_path, 
+                video_info, progress_callback
+            )
+        else:
+            result = self._process_frame_by_frame(
+                video_path, text_prompt, output_path,
+                video_info, keyframe_interval, progress_callback
+            )
+        
+        elapsed = time.time() - start_time
+        fps_processed = video_info.total_frames / elapsed
+        self._progress(
+            progress_callback, 1.0, 
+            f"✅ Done! {elapsed:.1f}s ({fps_processed:.1f} FPS)"
+        )
+        
+        return result
+    
+    def _process_video_tracking(
+        self, video_path, text_prompt, output_path, 
+        video_info, progress_callback
+    ) -> str:
+        """
+        Mode 1: SAM 2 Video Tracking
+        
+        1. Extract all frames to disk
+        2. Detect objects on first frame
+        3. Initialize SAM 2 video tracker
+        4. Propagate masks through video
+        5. Apply blur to each frame
+        6. Reassemble video with audio
+        """
+        temp_dir = os.path.join(self.config.video.temp_dir, "processing")
+        frames_dir = os.path.join(temp_dir, "frames")
+        blurred_dir = os.path.join(temp_dir, "blurred")
+        os.makedirs(blurred_dir, exist_ok=True)
+        
+        try:
+            # Step 1: Extract frames
+            self._progress(progress_callback, 0.15, "🎞️ Extracting frames...")
+            self.video_processor.extract_frames_to_dir(
+                video_path, frames_dir,
+                max_height=self.config.video.max_resolution
+            )
+            
+            # Load first frame for detection
+            frame_files = sorted(os.listdir(frames_dir))
+            first_frame_path = os.path.join(frames_dir, frame_files[0])
+            first_frame = cv2.imread(first_frame_path)
+            
+            # Step 2: Detect objects
+            self._progress(progress_callback, 0.25, f"🔍 Detecting: '{text_prompt}'...")
+            detections = self.model_manager.detect_objects(first_frame, text_prompt)
+            
+            if not detections:
+                self._progress(progress_callback, 1.0, 
+                    f"⚠️ No '{text_prompt}' detected in video. Returning original.")
+                shutil.copy2(video_path, output_path)
+                return output_path
+            
+            print(f"🎯 Detected {len(detections)} objects: "
+                  f"{[f'{d.label} ({d.confidence:.2f})' for d in detections]}")
+            
+            # Step 3: Initialize video tracking
+            self._progress(progress_callback, 0.3, "🎯 Initializing tracking...")
+            state = self.model_manager.init_video_tracking(frames_dir, detections)
+            
+            # Step 4: Propagate masks
+            self._progress(progress_callback, 0.35, "🔄 Tracking objects through video...")
+            total_frames = len(frame_files)
+            
+            def track_progress(frame_idx, total):
+                p = 0.35 + (frame_idx / total) * 0.3  # 0.35 -> 0.65
+                self._progress(progress_callback, p, 
+                    f"🔄 Tracking: frame {frame_idx+1}/{total}")
+            
+            frame_masks = self.model_manager.propagate_video(
+                state, total_frames, track_progress
+            )
+            
+            # Step 5: Apply blur
+            self._progress(progress_callback, 0.65, "🌫️ Applying blur...")
+            for i, fname in enumerate(frame_files):
+                frame_path = os.path.join(frames_dir, fname)
+                frame = cv2.imread(frame_path)
+                
+                mask = frame_masks.get(i, np.zeros(frame.shape[:2], dtype=np.uint8))
+                
+                # Resize mask if needed
+                if mask.shape[:2] != frame.shape[:2]:
+                    mask = cv2.resize(mask, (frame.shape[1], frame.shape[0]))
+                    mask = (mask > 127).astype(np.uint8) * 255
+                
+                blurred = self.blur_engine.apply_blur(frame, mask)
+                
+                output_frame_path = os.path.join(blurred_dir, fname)
+                cv2.imwrite(output_frame_path, blurred, [cv2.IMWRITE_JPEG_QUALITY, 95])
+                
+                p = 0.65 + (i / total_frames) * 0.25  # 0.65 -> 0.9
+                if i % 10 == 0:
+                    self._progress(progress_callback, p, 
+                        f"🌫️ Blurring: frame {i+1}/{total_frames}")
+            
+            # Step 6: Assemble video
+            self._progress(progress_callback, 0.9, "🎬 Assembling video...")
+            self.video_processor.assemble_video(
+                blurred_dir, output_path, 
+                video_info.fps, original_video=video_path
+            )
+            
+            return output_path
+            
+        finally:
+            # Cleanup
+            self.video_processor.cleanup_temp(temp_dir)
+    
+    def _process_frame_by_frame(
+        self, video_path, text_prompt, output_path,
+        video_info, keyframe_interval, progress_callback
+    ) -> str:
+        """
+        Mode 2: Frame-by-Frame Processing
+        
+        Process each frame independently with periodic re-detection.
+        Uses OpenCV for reading and a temp directory for output frames.
+        """
+        temp_dir = os.path.join(self.config.video.temp_dir, "processing")
+        output_frames_dir = os.path.join(temp_dir, "output_frames")
+        os.makedirs(output_frames_dir, exist_ok=True)
+        
+        try:
+            total_frames = video_info.total_frames
+            last_mask = None
+            frame_idx = 0
+            
+            for idx, frame in self.video_processor.read_frames_generator(
+                video_path, max_height=self.config.video.max_resolution
+            ):
+                # Detect + segment on keyframes
+                if idx % keyframe_interval == 0 or last_mask is None:
+                    mask = self.model_manager.detect_and_segment_frame(
+                        frame, text_prompt
+                    )
+                    if mask.max() > 0:
+                        last_mask = mask
+                else:
+                    # Reuse last mask (approximate between keyframes)
+                    mask = last_mask if last_mask is not None else \
+                           np.zeros(frame.shape[:2], dtype=np.uint8)
+                
+                # Apply blur
+                blurred = self.blur_engine.apply_blur(frame, mask)
+                
+                # Save frame
+                fname = f"{idx+1:06d}.jpg"
+                cv2.imwrite(
+                    os.path.join(output_frames_dir, fname), 
+                    blurred, [cv2.IMWRITE_JPEG_QUALITY, 95]
+                )
+                
+                # Progress
+                if idx % 5 == 0:
+                    p = 0.15 + (idx / max(total_frames, 1)) * 0.75
+                    self._progress(progress_callback, p, 
+                        f"⚡ Processing: frame {idx+1}/{total_frames}")
+                
+                frame_idx = idx
+            
+            # Assemble video
+            self._progress(progress_callback, 0.9, "🎬 Assembling video...")
+            self.video_processor.assemble_video(
+                output_frames_dir, output_path,
+                video_info.fps, original_video=video_path
+            )
+            
+            return output_path
+            
+        finally:
+            self.video_processor.cleanup_temp(temp_dir)
+    
+    def process_image(
+        self,
+        image_bgr: np.ndarray,
+        text_prompt: str,
+        blur_type: str = "gaussian",
+        blur_strength: int = 51,
+        edge_feather: int = 11,
+        detection_threshold: float = 0.3,
+        progress_callback: Optional[Callable] = None,
+    ) -> np.ndarray:
+        """
+        Process a single image with text-prompted blur.
+
+        Args:
+            image_bgr: Input image as a BGR numpy array (H, W, 3)
+            text_prompt: What to blur (e.g., "face. license plate.")
+            blur_type: "gaussian", "pixelate", or "black"
+            blur_strength: Blur kernel size (odd number)
+            edge_feather: Edge softening amount (odd number)
+            detection_threshold: Confidence threshold for detection
+
+        Returns:
+            Blurred image as a BGR numpy array (H, W, 3)
+        """
+        # Update config
+        self.config.model.gdino_box_threshold = detection_threshold
+        self.config.blur.blur_type = blur_type
+        self.config.blur.blur_strength = blur_strength
+        self.config.blur.edge_feather = edge_feather
+
+        # Load models (inside the GPU context on ZeroGPU)
+        self._progress(progress_callback, 0.1, "🔄 Loading AI models...")
+        self.ensure_models_loaded()
+
+        # Detect + segment
+        self._progress(progress_callback, 0.4, f"🔍 Detecting: '{text_prompt}'...")
+        mask = self.model_manager.detect_and_segment_frame(image_bgr, text_prompt)
+
+        if mask is None or mask.max() == 0:
+            self._progress(
+                progress_callback, 1.0,
+                f"⚠️ No '{text_prompt}' detected. Returning original image."
+            )
+            return image_bgr.copy()
+
+        # Apply blur
+        self._progress(progress_callback, 0.8, "🌫️ Applying blur...")
+        result = self.blur_engine.apply_blur(image_bgr, mask)
+
+        self._progress(progress_callback, 1.0, "✅ Done!")
+        return result
+
+    def preview_detection(
+        self, 
+        video_path: str, 
+        text_prompt: str,
+        frame_number: int = 0
+    ) -> np.ndarray:
+        """
+        Preview detection on a single frame (for UI)
+        
+        Returns:
+            BGR image with detection overlay
+        """
+        self.ensure_models_loaded()
+        
+        cap = cv2.VideoCapture(video_path)
+        cap.set(cv2.CAP_PROP_POS_FRAMES, frame_number)
+        ret, frame = cap.read()
+        cap.release()
+        
+        if not ret:
+            raise ValueError(f"Cannot read frame {frame_number}")
+        
+        # Resize if needed
+        max_h = self.config.video.max_resolution
+        if frame.shape[0] > max_h:
+            scale = max_h / frame.shape[0]
+            frame = cv2.resize(frame, (int(frame.shape[1] * scale), max_h))
+        
+        # Detect and segment
+        mask = self.model_manager.detect_and_segment_frame(frame, text_prompt)
+        
+        # Create visualization
+        vis = self.blur_engine.visualize_mask(frame, mask, color=(0, 200, 255))
+        
+        return vis
+    
+    @staticmethod
+    def _progress(callback, value, text):
+        """Safe progress callback"""
+        if callback:
+            callback(value, text)
+        print(f"[{value*100:.0f}%] {text}")

requirements.txt

@@ -0,0 +1,33 @@
+# ── Video Blur AI — Hugging Face Spaces (ZeroGPU) ──
+#
+# NOTE ON torch: on ZeroGPU, torch/torchvision are provided by the
+# runtime and are already CUDA-matched. Do NOT pin them here — listing
+# them can trigger a reinstall of an incompatible build. For LOCAL runs,
+# install torch first, e.g.:
+#   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+
+# ZeroGPU: provides the @spaces.GPU decorator
+spaces
+
+# Segment Anything Model 2 (installed from source).
+# ZeroGPU build images ship the CUDA toolkit, so the CUDA extension
+# compiles at build time. If the build ever fails, add a Space variable
+# SAM2_BUILD_CUDA=0 to fall back to the pure-PyTorch path.
+git+https://github.com/facebookresearch/sam2.git
+
+# Grounding DINO is loaded through transformers (no separate package)
+transformers>=4.35.0
+
+# Video & image processing
+opencv-python>=4.8.0
+numpy>=1.24.0
+Pillow>=10.0.0
+ffmpeg-python>=0.2.0
+
+# Web UI
+gradio>=4.20.0
+
+# Utilities
+tqdm>=4.65.0
+supervision>=0.18.0
+huggingface-hub>=0.20.0

run.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+source "/home/abdo96/.venvs/video-blur-ai/bin/activate"
+cd "/media/abdo96/ABODSALOMHA/LLMs_apps_github/video-blur-ai"
+python app.py "$@"

run_cli.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+source "/home/abdo96/.venvs/video-blur-ai/bin/activate"
+cd "/media/abdo96/ABODSALOMHA/LLMs_apps_github/video-blur-ai"
+python cli.py "$@"

setup.sh

@@ -0,0 +1,259 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════
+#  Video Blur AI - Automated Setup Script
+#  Handles NTFS/exFAT drives (no symlink support)
+# ═══════════════════════════════════════════════════════════
+set -e
+
+echo "╔══════════════════════════════════════════════════╗"
+echo "║       🎬 Video Blur AI - Setup                   ║"
+echo "╚══════════════════════════════════════════════════╝"
+echo ""
+
+PROJECT_DIR="$(cd "$(dirname "$0")" && pwd)"
+echo "📂 Project: $PROJECT_DIR"
+
+# ── Check Python ──
+echo "🐍 Checking Python..."
+if ! command -v python3 &> /dev/null; then
+    echo "❌ Python 3 not found! Install Python 3.10+"
+    exit 1
+fi
+PYTHON_VERSION=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
+echo "   Python $PYTHON_VERSION ✅"
+
+# ── Check FFmpeg ──
+echo "📹 Checking FFmpeg..."
+if ! command -v ffmpeg &> /dev/null; then
+    echo "⚠️  FFmpeg not found. Installing..."
+    if command -v apt &> /dev/null; then
+        sudo apt update && sudo apt install -y ffmpeg
+    elif command -v brew &> /dev/null; then
+        brew install ffmpeg
+    else
+        echo "❌ Install FFmpeg manually: https://ffmpeg.org/download.html"
+        exit 1
+    fi
+fi
+echo "   FFmpeg ✅"
+
+# ── Check Git ──
+echo "📦 Checking Git..."
+if ! command -v git &> /dev/null; then
+    echo "⚠️  Git not found. Installing..."
+    if command -v apt &> /dev/null; then
+        sudo apt install -y git
+    else
+        echo "❌ Install Git: https://git-scm.com"
+        exit 1
+    fi
+fi
+echo "   Git ✅"
+
+# ── Check CUDA ──
+echo "🎮 Checking GPU..."
+if command -v nvidia-smi &> /dev/null; then
+    GPU_NAME=$(nvidia-smi --query-gpu=name --format=csv,noheader | head -1)
+    GPU_MEM=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader | head -1)
+    echo "   GPU: $GPU_NAME ($GPU_MEM) ✅"
+else
+    echo "   ⚠️  No NVIDIA GPU. Will use CPU (slow)."
+fi
+
+# ══════════════════════════════════════════════════════════
+#  Detect filesystem — NTFS/exFAT can't create symlinks
+# ══════════════════════════════════════════════════════════
+CAN_SYMLINK=true
+TEST_LINK="$PROJECT_DIR/.symtest_link_$$"
+TEST_FILE="$PROJECT_DIR/.symtest_file_$$"
+touch "$TEST_FILE" 2>/dev/null || true
+if ! ln -s "$TEST_FILE" "$TEST_LINK" 2>/dev/null; then
+    CAN_SYMLINK=false
+fi
+rm -f "$TEST_LINK" "$TEST_FILE" 2>/dev/null
+
+VENV_DIR="$PROJECT_DIR/venv"
+
+if [ "$CAN_SYMLINK" = false ]; then
+    echo ""
+    echo "════════════════════════════════════════════════════"
+    echo "⚠️  NTFS/exFAT drive detected (no symlink support)"
+    echo "   venv will be created in your home directory"
+    echo "════════════════════════════════════════════════════"
+    
+    VENV_DIR="$HOME/.venvs/video-blur-ai"
+    mkdir -p "$(dirname "$VENV_DIR")"
+    
+    # Create helper scripts
+    cat > "$PROJECT_DIR/run.sh" << EOF
+#!/bin/bash
+source "$VENV_DIR/bin/activate"
+cd "$PROJECT_DIR"
+python app.py "\$@"
+EOF
+    chmod +x "$PROJECT_DIR/run.sh"
+
+    cat > "$PROJECT_DIR/run_cli.sh" << EOF
+#!/bin/bash
+source "$VENV_DIR/bin/activate"
+cd "$PROJECT_DIR"
+python cli.py "\$@"
+EOF
+    chmod +x "$PROJECT_DIR/run_cli.sh"
+
+    cat > "$PROJECT_DIR/activate.sh" << EOF
+#!/bin/bash
+source "$VENV_DIR/bin/activate"
+cd "$PROJECT_DIR"
+echo "✅ Activated. venv: $VENV_DIR"
+EOF
+    chmod +x "$PROJECT_DIR/activate.sh"
+    
+    echo "   Created run.sh, run_cli.sh, activate.sh ✅"
+fi
+
+echo "   venv location: $VENV_DIR"
+
+# ── Create Virtual Environment ──
+echo ""
+echo "📦 Creating virtual environment..."
+if [ ! -d "$VENV_DIR" ]; then
+    python3 -m venv "$VENV_DIR"
+    echo "   Created ✅"
+else
+    echo "   Already exists ✅"
+fi
+source "$VENV_DIR/bin/activate"
+pip install --upgrade pip -q
+echo "   Activated ✅"
+
+# ── Install PyTorch ──
+echo ""
+echo "🔥 Installing PyTorch (this may take a while)..."
+if command -v nvidia-smi &> /dev/null; then
+    pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 -q
+else
+    pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu -q
+fi
+echo "   PyTorch ✅"
+
+# ── Install Dependencies ──
+echo ""
+echo "📚 Installing dependencies..."
+pip install -q \
+    "opencv-python>=4.8.0" \
+    "numpy>=1.24.0" \
+    "Pillow>=10.0.0" \
+    "ffmpeg-python>=0.2.0" \
+    "gradio>=4.20.0" \
+    "tqdm>=4.65.0" \
+    "supervision>=0.18.0" \
+    "huggingface-hub>=0.20.0" \
+    "transformers>=4.35.0"
+echo "   Dependencies ✅"
+
+# ── Install SAM 2 ──
+echo ""
+echo "🎯 Installing SAM 2 from source (official method)..."
+
+SAM2_DIR="$HOME/.sam2_source"
+if [ -d "$SAM2_DIR" ] && python3 -c "import sam2" 2>/dev/null; then
+    echo "   SAM 2 already installed ✅"
+else
+    rm -rf "$SAM2_DIR"
+    git clone --depth 1 https://github.com/facebookresearch/sam2.git "$SAM2_DIR"
+    cd "$SAM2_DIR"
+    
+    # Skip CUDA extension build (works fine without it)
+    SAM2_BUILD_CUDA=0 pip install -e "." -q
+    
+    cd "$PROJECT_DIR"
+    echo "   SAM 2 installed ✅"
+fi
+
+# ── Install Grounding DINO ──
+# Grounding DINO is used via HuggingFace Transformers (AutoModelForZeroShotObjectDetection)
+# No separate package needed! transformers handles it.
+# If you need the native package as fallback, uncomment below:
+echo ""
+echo "🔍 Grounding DINO will load via HuggingFace Transformers ✅"
+# pip install -q "groundingdino @ git+https://github.com/IDEA-Research/GroundingDINO.git"
+
+# ── Download Models ──
+echo ""
+echo "⬇️  Downloading model weights (first time only, cached after)..."
+python3 << 'PYEOF'
+from huggingface_hub import hf_hub_download
+import os
+
+cache_dir = os.path.expanduser("~/.cache/huggingface")
+print(f"   Cache dir: {cache_dir}")
+
+print("   Downloading Grounding DINO Base (~999MB)...")
+try:
+    from transformers import AutoProcessor, AutoModelForZeroShotObjectDetection
+    AutoProcessor.from_pretrained("IDEA-Research/grounding-dino-base")
+    AutoModelForZeroShotObjectDetection.from_pretrained("IDEA-Research/grounding-dino-base")
+    print("   Grounding DINO Base ✅")
+except Exception as e:
+    print(f"   ⚠️  Will download on first run: {e}")
+
+print("   Downloading SAM 2.1 Base+ (~350MB)...")
+try:
+    hf_hub_download(repo_id="facebook/sam2.1-hiera-base-plus", filename="sam2.1_hiera_base_plus.pt")
+    print("   SAM 2.1 ✅")
+except Exception as e:
+    print(f"   ⚠️  Will download on first run: {e}")
+
+print("   Models are cached in ~/.cache/huggingface — next launch will be instant.")
+PYEOF
+
+# ── Verify ──
+echo ""
+echo "🔧 Verifying..."
+python3 -c "
+import torch, cv2, gradio, numpy
+print(f'   PyTorch {torch.__version__}', '(CUDA)' if torch.cuda.is_available() else '(CPU)')
+print(f'   OpenCV {cv2.__version__} | Gradio {gradio.__version__} | NumPy {numpy.__version__}')
+try:
+    import sam2
+    print(f'   SAM 2 ✅')
+except ImportError:
+    print('   ⚠️  SAM 2 import failed - check installation')
+try:
+    from transformers import AutoModelForZeroShotObjectDetection
+    print(f'   Grounding DINO (via transformers) ✅')
+except ImportError:
+    print('   ⚠️  Transformers import failed')
+print('   All OK ✅')
+"
+
+# ── Done ──
+echo ""
+echo "╔══════════════════════════════════════════════════╗"
+echo "║            ✅ Setup Complete!                     ║"
+echo "╠══════════════════════════════════════════════════╣"
+
+if [ "$CAN_SYMLINK" = false ]; then
+echo "║                                                  ║"
+echo "║  🚀 Start the app:                               ║"
+echo "║     ./run.sh                                     ║"
+echo "║                                                  ║"
+echo "║  🖥️  CLI mode:                                    ║"
+echo "║     ./run_cli.sh video.mp4 -p \"face.\"            ║"
+echo "║                                                  ║"
+echo "║  Or manually:                                    ║"
+echo "║     source activate.sh                           ║"
+echo "║     python app.py                                ║"
+else
+echo "║                                                  ║"
+echo "║  🚀 Start the app:                               ║"
+echo "║     source venv/bin/activate                     ║"
+echo "║     python app.py                                ║"
+fi
+
+echo "║                                                  ║"
+echo "║  🌐 Open: http://localhost:7860                  ║"
+echo "║  📡 Public: python app.py --share                ║"
+echo "║                                                  ║"
+echo "╚══════════════════════════════════════════════════╝"

utils/__init__.py

@@ -0,0 +1 @@
+# Video Blur AI - Utilities

utils/blur_engine.py

@@ -0,0 +1,173 @@
+"""
+Blur Engine - Applies various blur effects using segmentation masks
+Supports Gaussian blur, pixelation, and solid color overlay
+"""
+import cv2
+import numpy as np
+from typing import Optional
+
+
+class BlurEngine:
+    """Applies blur effects to images using segmentation masks"""
+    
+    def __init__(self, config):
+        self.config = config
+    
+    def apply_blur(
+        self,
+        frame: np.ndarray,
+        mask: np.ndarray,
+        blur_type: Optional[str] = None,
+        blur_strength: Optional[int] = None,
+        edge_feather: Optional[int] = None,
+    ) -> np.ndarray:
+        """
+        Apply blur to masked region of frame
+        
+        Args:
+            frame: BGR image (H, W, 3) uint8
+            mask: Binary mask (H, W) uint8, 255 = blur region
+            blur_type: "gaussian", "pixelate", or "black"
+            blur_strength: Kernel size for Gaussian (must be odd)
+            edge_feather: Edge softening kernel (must be odd)
+        
+        Returns:
+            Blurred frame (H, W, 3) uint8
+        """
+        blur_type = blur_type or self.config.blur.blur_type
+        blur_strength = blur_strength or self.config.blur.blur_strength
+        edge_feather = edge_feather or self.config.blur.edge_feather
+        
+        # Ensure odd kernel sizes
+        blur_strength = blur_strength | 1
+        edge_feather = edge_feather | 1
+        
+        # Skip if no mask
+        if mask is None or mask.max() == 0:
+            return frame.copy()
+        
+        # Resize mask to match frame if needed
+        if mask.shape[:2] != frame.shape[:2]:
+            mask = cv2.resize(mask, (frame.shape[1], frame.shape[0]), 
+                            interpolation=cv2.INTER_LINEAR)
+            mask = (mask > 127).astype(np.uint8) * 255
+        
+        # Generate the blurred/modified version
+        if blur_type == "gaussian":
+            modified = self._gaussian_blur(frame, blur_strength)
+        elif blur_type == "pixelate":
+            modified = self._pixelate(frame, self.config.blur.pixelate_size)
+        elif blur_type == "black":
+            modified = np.zeros_like(frame)
+        else:
+            modified = self._gaussian_blur(frame, blur_strength)
+        
+        # Apply edge feathering for smooth transitions
+        mask_soft = self._feather_mask(mask, edge_feather)
+        
+        # Composite: blend original and modified using soft mask
+        result = self._composite(frame, modified, mask_soft)
+        
+        return result
+    
+    def _gaussian_blur(self, frame: np.ndarray, kernel_size: int) -> np.ndarray:
+        """Apply Gaussian blur to entire frame"""
+        return cv2.GaussianBlur(frame, (kernel_size, kernel_size), 0)
+    
+    def _pixelate(self, frame: np.ndarray, block_size: int) -> np.ndarray:
+        """Apply pixelation effect"""
+        h, w = frame.shape[:2]
+        small = cv2.resize(frame, (w // block_size, h // block_size), 
+                          interpolation=cv2.INTER_LINEAR)
+        pixelated = cv2.resize(small, (w, h), interpolation=cv2.INTER_NEAREST)
+        return pixelated
+    
+    def _feather_mask(self, mask: np.ndarray, kernel_size: int) -> np.ndarray:
+        """
+        Create soft-edged mask for smooth blur transitions
+        
+        Returns:
+            Float mask (H, W) in range [0, 1]
+        """
+        # Optional: dilate slightly to ensure full coverage
+        dilate_kernel = np.ones((3, 3), np.uint8)
+        mask_dilated = cv2.dilate(mask, dilate_kernel, iterations=1)
+        
+        # Apply Gaussian blur to create soft edges
+        mask_soft = cv2.GaussianBlur(
+            mask_dilated.astype(np.float32), 
+            (kernel_size, kernel_size), 
+            0
+        )
+        
+        # Normalize to [0, 1]
+        mask_max = mask_soft.max()
+        if mask_max > 0:
+            mask_soft = mask_soft / mask_max
+        
+        return mask_soft
+    
+    def _composite(
+        self, 
+        original: np.ndarray, 
+        modified: np.ndarray, 
+        mask_soft: np.ndarray
+    ) -> np.ndarray:
+        """
+        Alpha-blend original and modified frames using soft mask
+        
+        result = original * (1 - mask) + modified * mask
+        """
+        # Expand mask to 3 channels
+        mask_3ch = np.stack([mask_soft] * 3, axis=-1)
+        
+        # Blend
+        result = (
+            original.astype(np.float32) * (1.0 - mask_3ch) + 
+            modified.astype(np.float32) * mask_3ch
+        )
+        
+        return np.clip(result, 0, 255).astype(np.uint8)
+    
+    def visualize_mask(
+        self, 
+        frame: np.ndarray, 
+        mask: np.ndarray, 
+        color: tuple = (0, 255, 0),
+        alpha: float = 0.4
+    ) -> np.ndarray:
+        """
+        Overlay colored mask on frame for visualization
+        
+        Args:
+            frame: BGR image
+            mask: Binary mask (H, W) uint8
+            color: BGR color tuple
+            alpha: Overlay transparency
+        
+        Returns:
+            Visualization image
+        """
+        vis = frame.copy()
+        
+        if mask is None or mask.max() == 0:
+            return vis
+        
+        # Resize mask if needed
+        if mask.shape[:2] != frame.shape[:2]:
+            mask = cv2.resize(mask, (frame.shape[1], frame.shape[0]))
+        
+        # Create colored overlay
+        overlay = np.zeros_like(frame)
+        overlay[mask > 127] = color
+        
+        # Blend
+        vis = cv2.addWeighted(vis, 1.0, overlay, alpha, 0)
+        
+        # Draw contours
+        contours, _ = cv2.findContours(
+            mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
+        )
+        cv2.drawContours(vis, contours, -1, color, 2)
+        
+        return vis

utils/video_processor.py

@@ -0,0 +1,281 @@
+"""
+Video Processor - Handles video I/O using FFmpeg
+Supports frame extraction, video assembly, and audio preservation
+"""
+import os
+import cv2
+import json
+import shutil
+import subprocess
+import numpy as np
+from pathlib import Path
+from typing import Generator, Tuple, Optional, Dict
+from dataclasses import dataclass
+
+
+@dataclass
+class VideoInfo:
+    """Video metadata"""
+    width: int
+    height: int
+    fps: float
+    total_frames: int
+    duration: float
+    has_audio: bool
+    codec: str
+    filepath: str
+
+
+class VideoProcessor:
+    """Handles all video I/O operations"""
+    
+    def __init__(self, config):
+        self.config = config
+        self._verify_ffmpeg()
+    
+    def _verify_ffmpeg(self):
+        """Verify FFmpeg is installed"""
+        try:
+            result = subprocess.run(
+                ["ffmpeg", "-version"], 
+                capture_output=True, text=True, timeout=5
+            )
+            if result.returncode != 0:
+                raise RuntimeError("FFmpeg not working properly")
+        except FileNotFoundError:
+            raise RuntimeError(
+                "FFmpeg not found! Install it:\n"
+                "  Ubuntu: sudo apt install ffmpeg\n"
+                "  Mac: brew install ffmpeg\n"
+                "  Windows: choco install ffmpeg"
+            )
+    
+    def get_video_info(self, video_path: str) -> VideoInfo:
+        """Extract video metadata using ffprobe"""
+        cmd = [
+            "ffprobe", "-v", "quiet",
+            "-print_format", "json",
+            "-show_format", "-show_streams",
+            video_path
+        ]
+        
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise ValueError(f"Cannot read video: {video_path}")
+        
+        probe = json.loads(result.stdout)
+        
+        # Find video stream
+        video_stream = None
+        has_audio = False
+        for stream in probe.get("streams", []):
+            if stream["codec_type"] == "video" and video_stream is None:
+                video_stream = stream
+            elif stream["codec_type"] == "audio":
+                has_audio = True
+        
+        if not video_stream:
+            raise ValueError("No video stream found")
+        
+        # Parse FPS
+        fps_parts = video_stream.get("r_frame_rate", "30/1").split("/")
+        fps = float(fps_parts[0]) / float(fps_parts[1]) if len(fps_parts) == 2 else 30.0
+        
+        # Parse frame count
+        nb_frames = int(video_stream.get("nb_frames", 0))
+        duration = float(probe.get("format", {}).get("duration", 0))
+        
+        if nb_frames == 0 and duration > 0:
+            nb_frames = int(duration * fps)
+        
+        return VideoInfo(
+            width=int(video_stream["width"]),
+            height=int(video_stream["height"]),
+            fps=fps,
+            total_frames=nb_frames,
+            duration=duration,
+            has_audio=has_audio,
+            codec=video_stream.get("codec_name", "unknown"),
+            filepath=video_path
+        )
+    
+    def extract_frames_to_dir(
+        self, 
+        video_path: str, 
+        output_dir: str,
+        max_height: Optional[int] = None,
+        progress_callback=None
+    ) -> Tuple[str, VideoInfo]:
+        """
+        Extract all frames as numbered JPEGs (required by SAM 2)
+        
+        Args:
+            video_path: Path to input video
+            output_dir: Directory to save frames
+            max_height: Optional max height for resizing
+            progress_callback: Optional callback(current, total)
+        
+        Returns:
+            (frames_dir, video_info)
+        """
+        os.makedirs(output_dir, exist_ok=True)
+        info = self.get_video_info(video_path)
+        
+        # Build FFmpeg command
+        cmd = ["ffmpeg", "-y", "-i", video_path]
+        
+        # Add scaling if needed
+        if max_height and info.height > max_height:
+            cmd.extend(["-vf", f"scale=-2:{max_height}"])
+        
+        # Output as numbered JPEGs
+        cmd.extend([
+            "-qscale:v", "2",  # High quality JPEG
+            os.path.join(output_dir, "%06d.jpg")
+        ])
+        
+        process = subprocess.Popen(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+        )
+        _, stderr = process.communicate()
+        
+        if process.returncode != 0:
+            raise RuntimeError(f"Frame extraction failed: {stderr.decode()}")
+        
+        # Count extracted frames
+        frame_files = sorted([
+            f for f in os.listdir(output_dir) 
+            if f.endswith('.jpg')
+        ])
+        info.total_frames = len(frame_files)
+        
+        # Update dimensions if resized
+        if frame_files:
+            sample = cv2.imread(os.path.join(output_dir, frame_files[0]))
+            if sample is not None:
+                info.height, info.width = sample.shape[:2]
+        
+        print(f"📹 Extracted {info.total_frames} frames ({info.width}x{info.height} @ {info.fps:.1f} FPS)")
+        return output_dir, info
+    
+    def read_frames_generator(
+        self, 
+        video_path: str,
+        max_height: Optional[int] = None
+    ) -> Generator[Tuple[int, np.ndarray], None, None]:
+        """
+        Stream frames from video using OpenCV (memory efficient)
+        
+        Yields:
+            (frame_index, frame_bgr)
+        """
+        cap = cv2.VideoCapture(video_path)
+        if not cap.isOpened():
+            raise ValueError(f"Cannot open video: {video_path}")
+        
+        frame_idx = 0
+        while True:
+            ret, frame = cap.read()
+            if not ret:
+                break
+            
+            # Resize if needed
+            if max_height and frame.shape[0] > max_height:
+                scale = max_height / frame.shape[0]
+                new_w = int(frame.shape[1] * scale)
+                frame = cv2.resize(frame, (new_w, max_height))
+            
+            yield frame_idx, frame
+            frame_idx += 1
+        
+        cap.release()
+    
+    def assemble_video(
+        self, 
+        frames_dir: str,
+        output_path: str,
+        fps: float,
+        original_video: Optional[str] = None,
+        progress_callback=None
+    ) -> str:
+        """
+        Assemble processed frames back into video with optional audio
+        
+        Args:
+            frames_dir: Directory with numbered JPEG frames
+            output_path: Output video path
+            fps: Frame rate
+            original_video: Original video to copy audio from
+            progress_callback: Optional callback
+        
+        Returns:
+            Path to output video
+        """
+        temp_video = output_path + ".temp.mp4"
+        
+        # Step 1: Encode frames to video
+        cmd = [
+            "ffmpeg", "-y",
+            "-framerate", str(fps),
+            "-i", os.path.join(frames_dir, "%06d.jpg"),
+            "-c:v", self.config.video.output_codec,
+            "-crf", str(self.config.video.output_crf),
+            "-preset", self.config.video.output_preset,
+            "-pix_fmt", self.config.video.pixel_format,
+            "-movflags", "+faststart",
+        ]
+        
+        if original_video:
+            cmd.append(temp_video)
+        else:
+            cmd.append(output_path)
+        
+        process = subprocess.Popen(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+        )
+        _, stderr = process.communicate()
+        
+        if process.returncode != 0:
+            raise RuntimeError(f"Video encoding failed: {stderr.decode()}")
+        
+        # Step 2: Mux audio from original video
+        if original_video:
+            info = self.get_video_info(original_video)
+            
+            if info.has_audio:
+                mux_cmd = [
+                    "ffmpeg", "-y",
+                    "-i", temp_video,
+                    "-i", original_video,
+                    "-c:v", "copy",
+                    "-c:a", "aac",
+                    "-map", "0:v:0",
+                    "-map", "1:a:0?",
+                    "-shortest",
+                    output_path
+                ]
+                
+                process = subprocess.Popen(
+                    mux_cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+                )
+                _, stderr = process.communicate()
+                
+                if process.returncode != 0:
+                    # Fallback: just use video without audio
+                    shutil.move(temp_video, output_path)
+                    print("⚠️  Audio muxing failed, output has no audio")
+                else:
+                    os.remove(temp_video)
+                    print("🔊 Audio preserved from original video")
+            else:
+                shutil.move(temp_video, output_path)
+        
+        file_size_mb = os.path.getsize(output_path) / (1024 * 1024)
+        print(f"✅ Output video: {output_path} ({file_size_mb:.1f} MB)")
+        
+        return output_path
+    
+    def cleanup_temp(self, temp_dir: str):
+        """Remove temporary files"""
+        if os.path.exists(temp_dir):
+            shutil.rmtree(temp_dir, ignore_errors=True)