Add macOS/Windows setup scripts and update modules for enhanced funct…

[rehanbgmi]

…ionality

• Add clone_or_update scripts for cross-platform repo management
• Introduce exclude.txt to prevent syncing .git, models, and binary files
• Add install and run scripts for macOS/Windows environments
• Improve error handling and add docstrings in utilities.py
• Enhance robustness in video processing functions
• Update core modules (face_analyser, globals, ui, etc.) for consistency

The changes implement cross-platform setup automation while improving code quality through better error handling, documentation, and synchronization control. Key modules and scripts were updated to ensure stable execution across different operating systems.

Summary by Sourcery

Add cross-platform setup automation and improve core functionality by introducing new setup scripts, virtual camera and preview toggles, and strengthening code quality with enhanced error handling, documentation, and processing robustness across all modules.

New Features:

• Add cross-platform setup and management scripts for macOS and Windows, including clone/update, install, run, and push helpers
• Introduce virtual camera toggle in the UI via pyvirtualcam and add a face swap enable/disable toggle with warning overlay in webcam preview
• Add exclude.txt to prevent syncing .git, model, and binary files during repository updates

Enhancements:

• Improve error handling, logging, and add docstrings and type hints across utilities, processing modules, and UI components
• Refactor face swapping and enhancement modules for thread-safe model loading, color correction, Poisson blending, and optional mouth-region blending
• Revamp FFmpeg-based utilities for stable frame extraction, video creation, temp file management, and synchronized progress updates
• Stabilize camera detection and capture backends on Windows, macOS, and Linux

Chores:

• Update project metadata
• Streamline module imports and simplify global map functions

[sourcery-ai[bot]]

Reviewer's Guide

Implements cross-platform setup automation via new shell and batch scripts (with exclusion control) while enhancing core modules (UI, face processing, utilities, globals) with consistent docstrings, error handling, and robust cross-OS logic for stable execution.

Sequence Diagram for Toggling Virtual Camera

sequenceDiagram
    actor User
    participant UI_Button as "UI Button"
    participant toggle_virtual_cam_func as "toggle_virtual_cam()"
    participant vcm as "virtual_cam_manager (VirtualCamManager)"
    participant StatusUpdate as "update_status()"

    User->>UI_Button: Clicks "Toggle Virtual Cam"
    UI_Button->>toggle_virtual_cam_func: Invoke
    toggle_virtual_cam_func->>toggle_virtual_cam_func: Check PYVIRTUALCAM_AVAILABLE
    alt pyvirtualcam not installed
        toggle_virtual_cam_func->>StatusUpdate: "pyvirtualcam not installed..."
    else pyvirtualcam available
        toggle_virtual_cam_func->>toggle_virtual_cam_func: Get virtual_cam_enabled state
        alt Virtual cam is currently disabled
            toggle_virtual_cam_func->>vcm: start(PREVIEW_DEFAULT_WIDTH, PREVIEW_DEFAULT_HEIGHT, 30)
            vcm-->>toggle_virtual_cam_func: Started successfully
            toggle_virtual_cam_func->>toggle_virtual_cam_func: Set virtual_cam_enabled = True
            toggle_virtual_cam_func->>StatusUpdate: "Virtual camera enabled."
        else Virtual cam is currently enabled
            toggle_virtual_cam_func->>vcm: stop()
            vcm-->>toggle_virtual_cam_func: Stopped successfully
            toggle_virtual_cam_func->>toggle_virtual_cam_func: Set virtual_cam_enabled = False
            toggle_virtual_cam_func->>StatusUpdate: "Virtual camera disabled."
        end
    end

Sequence Diagram for Webcam Frame Processing and Virtual Camera Output

sequenceDiagram
    participant WebcamPreviewLoop as "create_webcam_preview() loop"
    participant VideoCapture as "cap.read()"
    participant FrameProcessors
    participant vcm as "virtual_cam_manager (VirtualCamManager)"
    participant UIDisplay as "UI Image Display"

    loop Each Frame in Webcam Preview
        WebcamPreviewLoop->>VideoCapture: Read new frame
        VideoCapture-->>WebcamPreviewLoop: Frame data
        alt Frame successfully read
            WebcamPreviewLoop->>WebcamPreviewLoop: Copy frame for processing
            WebcamPreviewLoop->>FrameProcessors: Process frame (face swap, enhance, etc.)
            FrameProcessors-->>WebcamPreviewLoop: Processed frame
            alt Virtual camera enabled AND face_swap_enabled
                WebcamPreviewLoop->>vcm: send(processed_frame)
            end
            WebcamPreviewLoop->>UIDisplay: Update preview with processed_frame
        else Frame read failed
            WebcamPreviewLoop->>WebcamPreviewLoop: Break loop
        end
    end

File-Level Changes

Change	Details	Files
Add cross-platform automation scripts and exclude control	New clone_or_update, install and run scripts for macOS/Windows Shell and batch files in project root exclude.txt to prevent syncing .git, models, binaries	clone_or_update_deep_live_cam.sh clone_or_update_deep_live_cam.bat install_macos.sh install_windows.bat push_to_*.sh run-*.sh run-*.bat exclude.txt
Enhance UI with virtual camera and face-swap toggles	Import and detect pyvirtualcam, add VirtualCamManager Add Toggle Virtual Cam button and toggle logic Bind key event for face-swap enable/disable, show status messages	modules/ui.py
Refine face swapper logic and blending	Add improved Poisson (seamlessClone) blending and optional mouth region blending Wrap swap_face in exception handling, add docstrings Add color_transfer utility and integrate into swap_face	modules/processors/frame/face_swapper.py modules/processors/frame/face_enhancer.py modules/utilities.py
Improve error handling and documentation in utilities	Add docstrings to all utility functions Use subprocess.run with exception capture for ffmpeg/ffprobe Robust path resolution, temp file management and download via requests	modules/utilities.py
Standardize models and prediction modules	Thread-safe singleton loaders with docstrings in face_analyser and face_enhancer Exception handling in get_one_face, get_many_faces, NSFW predictor Type hints and improved globals mapping	modules/face_analyser.py modules/processors/frame/face_enhancer.py modules/predicter.py modules/globals.py
Harden video capture and cluster analysis	Wrap cv2.VideoCapture calls in try/finally with error logs Add docstrings and exception handling in capturer and cluster analysis Type annotations and consistent return defaults	modules/capturer.py modules/cluster_analysis.py modules/processors/frame/core.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an issue from a review comment by replying to it. You can also reply to a review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull request title to generate a title at any time. You can also comment @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in the pull request body to generate a PR summary at any time exactly where you want it. You can also comment @sourcery-ai summary on the pull request to (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the pull request to resolve all Sourcery comments. Useful if you've already addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull request to dismiss all existing Sourcery reviews. Especially useful if you want to start fresh with a new review - don't forget to comment @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.