4.41.0

README.md

@@ -1,4 +1,3 @@
----
 title: 🎬 BackgroundFX Pro - SAM2 + MatAnyone
 emoji: 🎥
 colorFrom: indigo
@@ -7,61 +6,123 @@ sdk: docker
 app_port: 7860
 license: mit
 tags:
-  - video
-  - background-removal
-  - segmentation
-  - matting
-  - SAM2
-  - MatAnyOne
----
 
-# 🎬 BackgroundFX Pro — Professional Video Background Replacement
+video
 
-**BackgroundFX Pro** is an advanced video background replacement app built for **Hugging Face Spaces (GPU)**.  
-It combines cutting-edge AI segmentation and matting models with a simple Gradio UI:
+background-removal
 
-- **[SAM2](https://huggingface.co/facebook/sam2)** → high-quality object segmentation (first frame or image prompts).  
-- **[MatAnyone](https://huggingface.co/PeiqingYang/MatAnyone)** → temporal video matting with consistent alpha masks.  
-- **Rembg fallback** → ensures every video can be processed, even if models fail.  
+segmentation
 
-👉 The result: **fast, stable, professional-grade background replacement** — ideal for content creators, streamers, and marketing.
+matting
 
----
+SAM2
 
-## ✨ Features
+MatAnyone
 
-- 🎥 Upload any video and replace its background with:
-  - Solid colors
-  - AI-generated images
-  - Custom uploaded backgrounds
-- ⚡ GPU-optimized (Tesla T4 / CUDA 12.x)
-- 🧩 Model pre-warm for faster startup
-- 🛡️ Fallback pipeline so you *never lose frames*
-- 📂 Persistent caching in `/data/.cache` for Hugging Face Spaces
+🎬 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
 
-## 🚀 Try it on Hugging Face Spaces
+Built on: CUDA 12.1.1, PyTorch 2.5.1 (cu121), torchvision 0.20.1, Gradio 4.41.0.
 
-[**▶ Open BackgroundFX Pro on Hugging Face**](https://huggingface.co/spaces/MogensR/VideoBackgroundReplacer2)  
+✨ Features
 
-No installation required — runs directly in your browser with GPU acceleration.
+• 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).
+• 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
 
-## 🛠️ Developer Notes
+Open the Space in your browser (GPU required):
+https://huggingface.co/spaces/MogensR/VideoBackgroundReplacer2
 
-### Local Development (with Docker)
+🖱️ How to Use
 
-Clone the repo and build locally:
+Upload a video (.mp4, .avi, .mov, .mkv).
 
-```bash
-git clone https://huggingface.co/spaces/MogensR/VideoBackgroundReplacer2
-cd VideoBackgroundReplacer2
+Choose a Background Type: Upload Image, AI Generate, Gradient, Solid, or Unsplash.
 
-# Build container (CUDA 12.3 base, Python 3.10, Torch 2.3.1+cu121)
-docker build -t backgroundfx-pro .
+If not uploading, enter a prompt and click Generate Background.
 
-# Run locally
-docker run --gpus all -p 7860:7860 backgroundfx-pro
+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:
+• Check data/run.log — heartbeat shows RSS and cgroup memory limit.
+• 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.
+
+“Could not open video” or empty output:
+• Verify the uploaded file codec/container. Re-encode to H.264/AAC in .mp4 if needed.
+
+Weights not found / slow first run:
+• First run downloads model assets into ./.hf and ./.torch. Subsequent runs are faster.
+
+🔐 Privacy
+
+All processing happens inside the Space container. Uploaded files are copied into ./data/uploads within the Space’s sandboxed storage.
+
+📄 License
+
+MIT — see LICENSE or the Space’s license field.
+
+🙌 Credits
+
+• SAM2 by Meta FAIR
+• MatAnyone by Peiqing Yang et al.
+• Built with Gradio and PyTorch

requirements.txt

@@ -36,7 +36,7 @@ kornia>=0.7.0,<0.8.0
 tqdm>=4.60.0,<5.0.0
 
 # ===== UI and API =====
-gradio==4.41.3
+gradio==4.41.0
 
 # ===== Helpers and Utilities =====
 huggingface-hub>=0.20.0,<1.0.0