Update README.md

README.md

@@ -1,33 +1,288 @@
----
-title: Video Background Replacement
-emoji: 🎬
-colorFrom: blue
-colorTo: green
-sdk: gradio
-sdk_version: 4.44.1
-app_file: app.py
-pinned: false
-license: mit
----
+# Video Background Replacement
+
+Professional-quality video background replacement using SAM2 + MatAnyone for precise segmentation and cinema-grade compositing.
+
+## Features
+
+### Core Capabilities
+- **High-Quality Segmentation**: SAM2-powered person detection with sub-pixel accuracy
+- **Advanced Matting**: MatAnyone integration for professional edge refinement
+- **Dual Processing Modes**:
+  - **Single-Stage**: Direct background replacement (fast)
+  - **Two-Stage**: Green screen intermediate for broadcast-quality results
+- **Multiple Background Options**: Custom uploads, professional presets, procedural generation
+- **GPU Accelerated**: CUDA optimization for NVIDIA GPUs with CPU fallback
+
+### Technical Highlights
+- Keyframe-based processing with temporal consistency
+- Automatic memory management and error recovery
+- Real-time progress tracking with ETA estimation
+- Audio preservation throughout processing
+- Robust codec fallback system
+
+## Quick Start
+
+### Option 1: Docker (Recommended)
+
+```bash
+# Clone repository
+git clone <your-repo-url>
+cd video-background-replacement
+
+# Build and run with GPU support
+docker build -t video-bg-replacement .
+docker run --gpus all -p 7860:7860 video-bg-replacement
+```
+
+### Option 2: Local Installation
+
+```bash
+# Clone repository
+git clone <your-repo-url>
+cd video-background-replacement
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run application
+python app.py
+```
+
+## System Requirements
+
+### Minimum Requirements
+- Python 3.10+
+- 8GB RAM
+- 4GB storage space
+- FFmpeg installed
+
+### Recommended for Best Performance
+- NVIDIA GPU with 6GB+ VRAM
+- 16GB+ RAM
+- CUDA 12.1+ support
+- Fast SSD storage
 
-# 🎬 Video Background Replacement
-Advanced video background replacement using **SAM2 + MatAnyone** for professional-quality results.
-
-## ✨ Features
-- **High-Quality Segmentation**: Precise foreground/background separation
-- **Two Processing Modes**:
-  - **Single-Stage**: Fast, direct background replacement
-  - **Two-Stage**: Green screen intermediate for **cinema-quality edges**
-- **Multiple Background Options**:
-  - Upload custom images
-  - Use professional presets (gradients, solid colors)
-  - Generate AI backgrounds (experimental)
-- **GPU Optimized**: Efficient processing with **CUDA support** (NVIDIA GPUs)
-- **User-Friendly Interface**: Simple Gradio UI with real-time progress tracking
-
-## 🚀 How to Use
-
-### **Option 1: Run with Docker (Recommended)**
-1. **Build the Docker image**:
+### Supported Platforms
+- Linux (Ubuntu 20.04+, tested)
+- Windows 10/11 with WSL2
+- macOS (CPU-only, limited testing)
+
+## Usage Guide
+
+### Basic Workflow
+
+1. **Launch Application**
    ```bash
-   docker build -t video-bg-replacement .
+   python app.py
+   ```
+   Access web interface at `http://localhost:7860`
+
+2. **Load Models** (first-time setup)
+   - Click "Load Models" button
+   - Wait for SAM2 and MatAnyone to download and initialize
+   - Status will show "Models loaded and validated"
+
+3. **Process Video**
+   - Upload your video file (MP4, AVI, MOV supported)
+   - Choose background method:
+     - **Professional Presets**: Studio-quality backgrounds
+     - **Custom Upload**: Your own background image
+   - Select processing options:
+     - **Two-Stage Mode**: Better quality, slower processing
+     - **Quality Preset**: Fast/Balanced/High
+   - Click "Process Video"
+
+### Processing Modes
+
+#### Single-Stage Mode (Default)
+- Direct background replacement
+- Faster processing (2-5x speed)
+- Good quality for most use cases
+- Recommended for: Social media, quick edits, testing
+
+#### Two-Stage Mode (Premium)
+- Green screen intermediate step
+- Cinema-quality edge compositing
+- Advanced chroma key algorithms
+- Recommended for: Professional content, broadcast, film
+
+### Background Options
+
+#### Professional Presets
+- `office_modern`: Clean contemporary office
+- `studio_blue`: Broadcast-quality blue background
+- `studio_green`: Professional green screen replacement
+- `minimalist`: Clean white gradient
+- `warm_gradient`: Warm sunset atmosphere
+- `tech_dark`: Modern tech/gaming setup
+
+#### Custom Backgrounds
+- Upload any image (JPG, PNG supported)
+- Automatically resized to match video resolution
+- Best results with high-resolution images (1920x1080+)
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Model settings
+export MODEL_CACHE_DIR="/path/to/model/cache"
+export FORCE_CPU="false"
+export DISABLE_MATANYONE="false"
+
+# Processing settings
+export KEYFRAME_INTERVAL="5"
+export FRAME_SKIP="1"
+export QUALITY_PRESET="balanced"
+
+# Video encoding
+export OUTPUT_CODEC="mp4v"
+export CRF="18"
+```
+
+### Quality Presets
+
+| Preset | Speed | Quality | Use Case |
+|--------|-------|---------|----------|
+| `fast` | 3x faster | Good | Social media, previews |
+| `balanced` | Normal | High | General use |
+| `high` | 2x slower | Excellent | Professional content |
+
+## API Reference
+
+### Core Functions
+
+```python
+from app import process_video_fixed, load_models_with_validation
+
+# Load models
+status = load_models_with_validation()
+
+# Process video
+result_path, message = process_video_fixed(
+    video_path="input.mp4",
+    background_choice="studio_blue",
+    custom_background_path=None,
+    use_two_stage=False,
+    chroma_preset="standard"
+)
+```
+
+### Two-Stage Processing
+
+```python
+from two_stage_processor import TwoStageProcessor
+
+processor = TwoStageProcessor(sam2_predictor, matanyone_model)
+
+# Full pipeline
+result_path, message = processor.process_full_pipeline(
+    video_path="input.mp4",
+    background=background_image,
+    final_output="output.mp4",
+    chroma_settings={"tolerance": 40, "edge_softness": 2}
+)
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**CUDA Out of Memory**
+```bash
+# Reduce processing quality
+export QUALITY_PRESET="fast"
+export KEYFRAME_INTERVAL="8"
+```
+
+**Models Not Loading**
+```bash
+# Clear cache and retry
+rm -rf /tmp/model_cache
+python app.py
+```
+
+**Video Processing Fails**
+- Check video format (MP4 recommended)
+- Ensure video is not corrupted
+- Try shorter clips first (under 30 seconds)
+
+**Audio Missing**
+- FFmpeg must be installed and in PATH
+- Check input video has audio track
+- Try different output format
+
+### Performance Optimization
+
+**For Large Videos**
+- Use "fast" quality preset
+- Increase `KEYFRAME_INTERVAL` to 8-10
+- Process in shorter segments
+
+**For High Resolution**
+- Ensure sufficient VRAM (6GB+ recommended)
+- Use two-stage mode for best quality
+- Consider downscaling input video
+
+## Development
+
+### Project Structure
+```
+├── app.py                    # Main application entry point
+├── utilities.py              # Core CV functions (segmentation, compositing)
+├── two_stage_processor.py    # Green screen pipeline
+├── ui_components.py          # Gradio interface
+├── requirements.txt          # Python dependencies
+├── Dockerfile               # Container configuration
+└── README.md               # This file
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing-feature`)
+5. Open Pull Request
+
+### Testing
+
+```bash
+# Run with test video
+python app.py --test-mode
+
+# Process sample
+python -c "
+from app import process_video_fixed, load_models_with_validation
+load_models_with_validation()
+result = process_video_fixed('test_video.mp4', 'office_modern', None)
+print(f'Result: {result}')
+"
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Acknowledgments
+
+- **SAM2**: Meta's Segment Anything 2 for segmentation
+- **MatAnyone**: High-quality image matting
+- **Gradio**: Web interface framework
+- **OpenCV**: Computer vision processing
+- **FFmpeg**: Video encoding/decoding
+
+## Support
+
+- **Issues**: Report bugs via GitHub Issues
+- **Discussions**: Feature requests and questions
+- **Documentation**: Check troubleshooting section first
+
+---
+
+*For deployment on Hugging Face Spaces, see the space configuration in the app header.*