WW

README.md

@@ -1,6 +1,4 @@
-Here’s a cleaned, single README.md you can paste in as-is.
-(It includes the required YAML metadata at the very top and fixes your tags/list formatting.)
-
+---
 title: 🎬 BackgroundFX Pro - SAM2 + MatAnyone
 emoji: 🎥
 colorFrom: indigo
@@ -9,154 +7,88 @@ sdk: docker
 app_port: 7860
 license: mit
 tags:
+  - video
+  - background-removal
+  - segmentation
+  - matting
+  - SAM2
+  - MatAnyone
+---
 
-video
-
-background-removal
-
-segmentation
-
-matting
-
-SAM2
-
-MatAnyone
-
-🎬 BackgroundFX Pro — Professional Video Background Replacement
+# 🎬 BackgroundFX Pro — Professional Video Background Replacement
 
 BackgroundFX Pro is a GPU-accelerated app for Hugging Face Spaces (Docker) that replaces video backgrounds using:
+- **SAM2** — high-quality object segmentation  
+- **MatAnyone** — temporal video matting for stable alpha over time
 
-SAM2 — high-quality object segmentation
+Built on: **CUDA 12.1.1**, **PyTorch 2.5.1 (cu121)**, **torchvision 0.20.1**, **Gradio 4.41.0**.
 
-MatAnyone — temporal video matting for stable alpha over time
+---
 
-Built on: CUDA 12.1.1, PyTorch 2.5.1 (cu121), torchvision 0.20.1, Gradio 4.41.0.
+## ✨ Features
 
-✨ Features
+- Replace backgrounds with: **solid color**, **AI-generated** image (procedural), **custom uploaded image**, or **Unsplash** search  
+- Optimized for **T4 GPUs** on Hugging Face  
+- Caching & logs stored in the repo volume:
+  - HF cache → `./.hf`  
+  - Torch cache → `./.torch`  
+  - App data & logs → `./data` (see `data/run.log`)
 
-Upload a video and replace its background with: solid color, AI-generated image, your own uploaded image, or an Unsplash search
+---
 
-Optimized for T4 GPUs (HF Spaces)
+## 🚀 Try It
 
-Caching & logs stored in the repository volume for reliability:
-
-HF cache: ./.hf
-
-Torch cache: ./.torch
-
-App data & logs: ./data (see data/run.log)
-
-🚀 Try It
-
-Open the Space in your browser (GPU required):
+Open the Space in your browser (GPU required):  
 https://huggingface.co/spaces/MogensR/VideoBackgroundReplacer2
 
-🖱️ How to Use
-
-Upload a video (.mp4, .avi, .mov, .mkv).
-
-Choose a Background Type: Upload Image, AI Generate, Gradient, Solid, or Unsplash.
-
-If not uploading, enter a prompt and click Generate Background.
-
-Click Process Video.
-
-Preview and download the result.
-
-Tip: Start with 720p/1080p on T4; 4K can exceed memory.
-
-🗂️ Project Structure (key files)
-
-Dockerfile
-
-requirements.txt
-
-ui.py
-
-ui_core_interface.py
-
-ui_core_functionality.py
-
-two_stage_pipeline.py
-
-models/sam2_loader.py
-
-models/matanyone_loader.py
-
-utils/init.py
-
-data/ (created at runtime for logs and outputs)
-
-tmp/ (created at runtime for jobs and temp files)
-
-⚙️ Runtime Notes
-
-The app binds to the port from PORT or GRADIO_SERVER_PORT (defaults to 7860).
-
-A heartbeat writes every ~2s to logs with memory and disk stats.
-
-If the process dies without a final “PROCESS EXITING” line, it was likely an OOM or hard kill.
-
-🧪 Local Development (Docker)
-
-Requires an NVIDIA GPU with CUDA drivers installed.
-
-Steps:
-
-Clone the Space repo.
-
-Build the image (base: Ubuntu 22.04, CUDA 12.1.1; installs Torch 2.5.1+cu121).
-
-Run the container and map port 7860.
-
-🔧 Space Settings
-
-SDK: docker
-
-App port: 7860
-
-Hardware: T4 GPU (or better)
-
-📦 Key Versions
-
-Gradio: 4.41.0
-
-PyTorch: 2.5.1 (cu121)
-
-torchvision: 0.20.1
-
-SAM2: installed from source at build time in third_party/sam2
-
-MatAnyone: installed from GitHub
-
-🧯 Troubleshooting
+---
 
-Container exits after ~20s:
+## 🖱️ How to Use
 
-Check data/run.log — heartbeat shows RSS and cgroup memory limit.
+1. **Upload a video** (`.mp4`, `.avi`, `.mov`, `.mkv`).  
+2. Choose a **Background Type**: Upload Image, AI Generate, Gradient, Solid, or Unsplash.  
+3. If not uploading, enter a prompt and click **Generate Background**.  
+4. Click **Process Video**.  
+5. Preview and **Download Result**.
 
-If OOM is suspected: use lower-resolution videos, keep concurrency low (already set to max_threads=1 and queue(max_size=2)), and ensure GPU hardware is selected.
+> Tip: Start with 720p/1080p on T4; 4K can exceed memory.
 
-“Could not open video” or empty output:
+---
 
-Verify the uploaded file codec/container. Re-encode to H.264/AAC in .mp4 if needed.
+## 🗂️ Project Structure (key files)
 
-Weights not found / slow first run:
+- `Dockerfile`  
+- `requirements.txt`  
+- `ui.py`  
+- `ui_core_interface.py`  
+- `ui_core_functionality.py`  
+- `two_stage_pipeline.py`  
+- `models/sam2_loader.py`  
+- `models/matanyone_loader.py`  
+- `utils/__init__.py`  
+- `data/`  (created at runtime for logs/outputs)  
+- `tmp/`   (created at runtime for jobs/temp files)
 
-First run downloads model assets into ./.hf and ./.torch. Subsequent runs are faster.
+---
 
-🔐 Privacy
+## ⚙️ Runtime Notes
 
-All processing happens inside the Space container. Uploaded files are copied into ./data/uploads within the Space’s sandboxed storage.
+- Binds to `PORT` / `GRADIO_SERVER_PORT` (defaults to **7860**).  
+- Heartbeat logs every ~2s with memory & disk stats.  
+- If there’s no final “PROCESS EXITING” line, it was likely an **OOM** or hard kill.
 
-📄 License
+---
 
-MIT — see LICENSE or the Space’s license field.
+## 🧪 Local Development (Docker)
 
-🙌 Credits
+Requires an NVIDIA GPU with CUDA drivers.
 
-SAM2 by Meta FAIR
+```bash
+git clone https://huggingface.co/spaces/MogensR/VideoBackgroundReplacer2
+cd VideoBackgroundReplacer2
 
-MatAnyone by Peiqing Yang et al.
+# Build (Ubuntu 22.04, CUDA 12.1.1; installs Torch 2.5.1+cu121)
+docker build -t backgroundfx-pro .
 
-Built with Gradio and PyTorch
+# Run
+docker run --gpus all -p 7860:7860 backgroundfx-pro