### Windows Development Setup

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Clones the repository, sets up a Python virtual environment, and installs dependencies for Windows development.

```powershell
# Windows development setup
git clone https://github.com/djebaz/Deep-Live-Cam-Remote.git
Set-Location .\Deep-Live-Cam-Remote
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

--------------------------------

### Python Environment Setup

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/AGENTS.md

Set up a Python 3.11 virtual environment and install project dependencies using pip.

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
```

--------------------------------

### Setup Deep Live Cam Remote on Windows

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Commands to clone the repository, set up a Python virtual environment, install dependencies, and run the Windows remote app. Ensure Python 3.11 is installed.

```powershell
git clone https://github.com/djebaz/Deep-Live-Cam-Remote.git
Set-Location .\Deep-Live-Cam-Remote
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\run_windows_remote_app.ps1
```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

This script clones the specified GitHub repository, installs required Python packages, and sets up local directories for input and output. It checks for existing installations and handles both public and private repositories. It also installs nvtop for GPU monitoring.

```python
# @title Clone and install (resumable - safe to re-run after session restart)
import os
import subprocess
import sys
from pathlib import Path
import shutil

REPO_OWNER = "djebaz"
REPO_NAME = "Deep-Live-Cam-Remote"
REPO_BRANCH = "live-webcam-stability"
WORK_DIR = Path("/content/Deep-Live-Cam-Remote")
CRITICAL_FILES = ["colab_api.py", "colab_batch.py", "modules/__init__.py"]

# Clean up Colab sample data (one-time)
if Path("/content/sample_data").exists():
    shutil.rmtree("/content/sample_data")
    print("✓ Removed /content/sample_data")

# Install nvtop if not present
if shutil.which("nvtop") is None:
    subprocess.run(["apt-get", "install", "-qq", "-y", "nvtop"], check=False)
    print("✓ Installed nvtop")
else:
    print("✓ nvtop already installed")

# Create local input/output directories
LOCAL_DIRS = [
    Path("/content/inputs/source"),
    Path("/content/inputs/photos"),
    Path("/content/inputs/videos"),
    Path("/content/outputs/photos"),
    Path("/content/outputs/videos"),
]
for d in LOCAL_DIRS:
    d.mkdir(parents=True, exist_ok=True)
print("✓ Local input/output directories ready")

# Check if repo is already cloned with all critical files
def repo_ready() -> bool:
    if not WORK_DIR.exists():
        return False
    for f in CRITICAL_FILES:
        if not (WORK_DIR / f).exists():
            return False
    return True

if repo_ready():
    print(f"✓ Repository already present: {WORK_DIR}")
    # Pull latest changes
    os.chdir(WORK_DIR)
    result = subprocess.run(["git", "pull", "--ff-only"], capture_output=True, text=True)
    if result.returncode == 0:
        if "Already up to date" in result.stdout:
            print("✓ Already up to date")
        else:
            print("✓ Pulled latest changes")
            print(result.stdout.strip())
    else:
        print(f"⚠️ git pull failed: {result.stderr.strip()}")
else:
    # Need to clone
    import urllib.request
    import json

    # Check if repo is public
    try:
        api_url = f"https://api.github.com/repos/{REPO_OWNER}/{REPO_NAME}"
        req = urllib.request.Request(api_url)
        with urllib.request.urlopen(req, timeout=5) as response:
            repo_info = json.loads(response.read().decode())
            is_private = repo_info.get("private", True)
    except Exception:
        is_private = True

    # Build clone URL
    if is_private:
        try:
            from google.colab import userdata
            GH_PAT = userdata.get('GH_PAT')
            REPO_URL = f"https://{GH_PAT}@github.com/{REPO_OWNER}/{REPO_NAME}.git"
            print("Using authenticated clone (private repo)")
        except Exception as e:
            print(f"Warning: Repository appears private but no GH_PAT available: {e}")
            REPO_URL = f"https://github.com/{REPO_OWNER}/{REPO_NAME}.git"
    else:
        REPO_URL = f"https://github.com/{REPO_OWNER}/{REPO_NAME}.git"
        print("Using public clone (repo is public)")

    os.chdir("/content")

    # Clean up any existing incomplete directories
    if WORK_DIR.exists():
        shutil.rmtree(WORK_DIR)
    TEMP_CLONE = Path("/content/Deep_Live_Cam_Remote_temp")
    if TEMP_CLONE.exists():
        shutil.rmtree(TEMP_CLONE)

    print(f"Cloning {REPO_OWNER}/{REPO_NAME} (branch: {REPO_BRANCH})...")
    result = subprocess.run(
        ["git", "clone", "--depth=1", "--branch", REPO_BRANCH, REPO_URL, str(TEMP_CLONE)],
        capture_output=True, text=True, cwd="/content"
    )
    if result.returncode != 0:
        error_msg = result.stderr.replace(REPO_URL, f"https://github.com/{REPO_OWNER}/{REPO_NAME}.git")
        raise RuntimeError(f"Clone failed:\n{error_msg}")

    # Move cloned repository into the stable work directory
    shutil.move(str(TEMP_CLONE), str(WORK_DIR))
    print(f"✓ Repository cloned to: {WORK_DIR}")

# Check if key packages are already installed
def packages_ready() -> bool:
    try:
        import insightface
        import onnxruntime
        import fastapi
        import uvicorn
        return True
    except ImportError:
        return False

if packages_ready():
    print("✓ Python packages already installed")
else:
    print("Installing Python dependencies...")
    subprocess.run([
        sys.executable, "-m", "pip", "install", "-q",
        "numpy<2",
        "opencv-python==4.10.0.84",
        "insightface==0.7.3",
        "onnx==1.18.0",
        "onnxruntime-gpu==1.23.2",
        "scikit-learn",
        "tqdm",
        "pillow",
        "psutil",
        "protobuf==4.25.1",
        "PySide6>=6.7,<7",
        "cv2_enumerate_cameras==1.1.15",
        "fastapi>=0.115,<1",
        "uvicorn[standard]>=0.30,<1",
        "websockets>=12,<16"
    ], check=True)
    print("✓ Python packages installed")

```

--------------------------------

### Install Tailscale

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Installs Tailscale if it's not already present. It downloads the official installer script and executes it. This cell also ensures the Tailscale daemon is running in the background.

```python
# @title Install Tailscale (resumable - safe to re-run)
import subprocess
import shutil
import time

def tailscale_installed() -> bool:
    return shutil.which("tailscale") is not None

def daemon_running() -> bool:
    result = subprocess.run(["tailscale", "status"], capture_output=True, text=True)
    # Daemon is running if we get any response (even "Logged out")
    return result.returncode == 0 or "Logged out" in result.stderr or "Logged out" in result.stdout

# Install if needed
if tailscale_installed():
    print("✓ Tailscale already installed")
else:
    print("Installing Tailscale...")
    result = subprocess.run(["curl", "-fsSL", "https://tailscale.com/install.sh"], capture_output=True, text=True)
    if result.returncode != 0:
        raise RuntimeError(f"Failed to download Tailscale installer: {result.stderr}")
    install_result = subprocess.run(["sh", "-c", result.stdout], capture_output=True, text=True)
    if install_result.returncode != 0:
        raise RuntimeError(f"Tailscale installation failed: {install_result.stderr}")
    print("✓ Tailscale installed")

# Start daemon if needed
if daemon_running():
    print("✓ Tailscale daemon already running")
else:
    print("Starting Tailscale daemon...")
    daemon_cmd = "sudo tailscaled --tun=userspace-networking --socks5-server=localhost:1055 > /dev/null 2>&1 &"
    subprocess.Popen(daemon_cmd, shell=True)
    time.sleep(2)
    if daemon_running():
        print("✓ Tailscale daemon started")
    else:
        print("⚠️  Daemon may not have started correctly - check next cell")

```

--------------------------------

### Run Colab Batch Processing

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Example command to start Colab batch processing from the command line.

```powershell
# Colab batch from command line (example)
python colab_batch.py process --source-face source.png --input-dir ./videos --output-dir ./output
```

--------------------------------

### Clone Repository and Setup Python Environment (Windows PowerShell)

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CONTRIBUTING.md

Steps to clone the repository and set up a Python virtual environment using PowerShell on Windows. Ensure Python 3.11 is installed.

```powershell
git clone https://github.com/djebaz/Deep-Live-Cam-Remote.git
Set-Location .\Deep-Live-Cam-Remote
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

--------------------------------

### Start Private API Server

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Run this cell after Tailscale is configured and you have your IP address. It starts a private API server in a background thread. Ensure the setup cell has been run first.

```python
# @title Start private API server
import sys
import threading
from pathlib import Path

# Verify setup was run first
WORK_DIR = Path("/content/Deep-Live-Cam-Remote")
if not WORK_DIR.exists() or str(WORK_DIR) not in sys.path:
    raise RuntimeError(
        "Setup cell not completed successfully! Please run the 'Clone and install' cell first.\n"
        f"Expected directory: {WORK_DIR}\n"
        f"Current sys.path: {sys.path[:3]}"
    )

from colab_api import ensure_drive_layout, app

ensure_drive_layout()

# Run uvicorn in a background thread to avoid asyncio event loop conflicts
def run_server():
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=7860)

server_thread = threading.Thread(target=run_server, daemon=True)
server_thread.start()

print("✓ API server starting on http://0.0.0.0:7860")
print("✓ The server is running in the background")
print("✓ Connect your Tailscale network and use the Tailscale IP with the Windows app")
print("\nPress Ctrl+C or stop the cell to terminate the server.")

```

--------------------------------

### Skip Installation and Reuse Environment

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Use the -SkipInstall switch to reuse an existing, prepared .venv_build environment. This can speed up builds if the environment is already set up correctly.

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -SkipInstall
```

--------------------------------

### Install Dependencies for Desktop App

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/AGENTS.md

Install project dependencies using pip within the project's virtual environment for the desktop application.

```batch
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

--------------------------------

### Start Tailscale and Authenticate

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Connects to Tailscale using either a pre-configured authentication key or an interactive login URL. It displays the assigned Tailscale IP address upon successful connection.

```python
# @title Start Tailscale and authenticate (resumable)
import subprocess

def get_tailscale_ip() -> str | None:
    result = subprocess.run(["tailscale", "ip", "-4"], capture_output=True, text=True)
    if result.returncode == 0 and result.stdout.strip():
        return result.stdout.strip()
    return None

def is_connected() -> bool:
    result = subprocess.run(["tailscale", "status"], capture_output=True, text=True)
    output = result.stdout + result.stderr
    # Connected if we have an IP and status doesn't show logged out
    return get_tailscale_ip() is not None and "Logged out" not in output

# Check if already connected
if is_connected():
    ip = get_tailscale_ip()
    print("="*70)
    print(f"✓ Tailscale already connected! IP: {ip}")
    print("="*70)
    print(f"\nUse this in your Windows app: http://{ip}:7860")
    print("\nRun the 'Start private API server' cell below.")
else:
    # Need to authenticate
    authkey = None
    try:
        from google.colab import userdata
        authkey = userdata.get('TAILSCALE_AUTHKEY')
        print("✓ Found TAILSCALE_AUTHKEY in secrets - using automatic auth")
    except Exception:
        print("⚠️  No TAILSCALE_AUTHKEY found - using interactive auth")

    print("\nConnecting to Tailscale...")
    cmd = ["sudo", "tailscale", "up", "--hostname=colab-dlc-remote"]
    if authkey:
        cmd.append(f"--authkey={authkey}")

    result = subprocess.run(cmd, capture_output=True, text=True)
    output = result.stdout + result.stderr
    print(output)

    if result.returncode == 0:
        ip = get_tailscale_ip()
        print("\n" + "="*70)
        print(f"✓ Tailscale connected! IP: {ip}")
        print("="*70)
        print(f"\nUse this in your Windows app: http://{ip}:7860")
        print("\nRun the 'Start private API server' cell below.")
    elif "https://login.tailscale.com" in output:
        print("\n" + "="*70)
        print("IMPORTANT: Click the authentication URL above")
        print("="*70)
        print("\nAfter authorizing, re-run this cell to get your IP.")
    else:
        print("\n⚠️  Authentication may have failed. Check output above.")

```

--------------------------------

### Colab Notebook Round-Trip Setup

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Converts Python scripts to Colab notebooks and vice-versa, ensuring correct line endings.

```powershell
# Colab notebook round-trip setup (same venv)
python scripts/py_to_ipynb.py .\google-colab\Deep_Live_Cam_Remote_Batch.py .\google-colab\Deep_Live_Cam_Remote_Batch.ipynb --eol lf
```

--------------------------------

### Run Colab API Server

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Starts the Colab API server using uvicorn within a Colab environment.

```python
from colab_api import app
import uvicorn
uvicorn.run(app, host='0.0.0.0', port=7860)
```

--------------------------------

### Build Standalone Desktop App

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Use this command to create an isolated build virtual environment, install build requirements, and run the PowerShell script to build the desktop application.

```powershell
py -3.11 -m venv .venv_build
.\.venv_build\Scripts\python.exe -m pip install -r requirements-build.txt
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1
```

--------------------------------

### Colab API Server

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/AGENTS.md

Start the FastAPI/WebSocket server for remote control on a specified host and port.

```python
python colab_api.py --host 0.0.0.0 --port 7860
```

--------------------------------

### Display Runtime Status

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Prints the current working directory, the Python path, and confirms that the runtime environment is ready. This serves as a final check after setup.

```python
print(f"✓ Runtime ready: {WORK_DIR}")
print(f"✓ Python path: {sys.path[0]}")
print(f"✓ Working directory: {os.getcwd()}")
```

--------------------------------

### Clean Build and Reinstall Requirements

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Use the -Clean switch to reinstall requirements and clear the PyInstaller cache and build output. This is useful for resolving build issues or starting fresh.

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -Clean
```

--------------------------------

### Full vs. Lite Onefile Build Commands

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/devdocs/features/live-streaming-without-opencv.md

These PowerShell commands demonstrate how to build the desktop application in either a full version including Live webcam support or a lite version excluding it.

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -OneFile
```

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -OneFile -Lite
```

--------------------------------

### Display Batch CLI Help

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Run these commands to view the help documentation for the batch CLI and its process subcommand. This is useful for understanding available options.

```bash
python colab_batch.py --help
```

```bash
python colab_batch.py process --help
```

--------------------------------

### Build Standalone Desktop Executable (Full)

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Builds a full standalone desktop executable, including live webcam dependencies.

```powershell
# Full build (includes live webcam dependencies: cv2, numpy, pyvirtualcam)
py -3.11 -m venv .venv_build
.\.venv_build\Scripts\python.exe -m pip install -r requirements-build.txt
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1
```

--------------------------------

### Recommended Live Preset Configuration

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/devdocs/live-webcam-perf-correlation-2026-06-25.md

This configuration is recommended based on performance analysis of live webcam feeds. It optimizes for latency and throughput by balancing capture FPS, pipeline settings, detection frequency, and source caching.

```text
Capture FPS: 15 or 20
Pipeline frames: same as capture FPS, or at most 2x capture FPS
Detector size: 256
Detect every N: 3
Swapper precision: fp16
InsightFace pack: buffalo_l
Cache source face: ON
Opacity: 1.0 while testing
```

--------------------------------

### Build Lite Single-File Executable

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Build a smaller, single-file executable that excludes Live webcam dependencies like cv2, numpy, and pyvirtualcam. This is suitable for controllers not requiring live webcam functionality.

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -OneFile -Lite
```

--------------------------------

### Local GUI Entry Point

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/AGENTS.md

Run the local graphical user interface for the Deep-Live-Cam-Remote application.

```python
python run.py
```

--------------------------------

### Recursive Search with Select-String

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/AGENTS.md

When performing large recursive searches, use Get-ChildItem -Recurse -File to get files and then pipe to Select-String. This avoids issues with Select-String -Recurse.

```powershell
Get-ChildItem -Recurse -File | Select-String
```

--------------------------------

### Mount Google Drive and Set Up Folders

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

This snippet mounts your Google Drive, checks for accessibility, and creates the necessary folder structure for the Deep-Live-Cam Remote project. It's essential for batch processing directly in Colab and for persistent storage.

```python
# @title Mount Google Drive
from google.colab import drive
from pathlib import Path
import os

# Check if already mounted
already_mounted = os.path.ismount('/content/drive')

if not already_mounted:
    try:
        drive.mount('/content/drive')
        print("✓ Google Drive mounted successfully")
    except Exception as e:
        print(f"Drive mount error: {e}")
        print("If Drive is already mounted, you can continue.")
else:
    print("✓ Google Drive already mounted")

# Verify Drive is accessible
DRIVE_ROOT = Path("/content/drive/MyDrive/DeepLiveCamRemote")
if not Path("/content/drive/MyDrive").exists():
    print("⚠️  WARNING: Google Drive not accessible!")
    print("If you're using the Windows app, you can skip this cell.")
    print("If you need Drive, run: from google.colab import drive; drive.mount('/content/drive', force_remount=True)")
    import sys
    sys.exit(0)  # Exit gracefully instead of crashing

# Create folder structure automatically
folders = [
    DRIVE_ROOT / "source",
    DRIVE_ROOT / "photos",
    DRIVE_ROOT / "videos",
    DRIVE_ROOT / "outputs" / "photos",
    DRIVE_ROOT / "outputs" / "videos",
]

print("\nCreating folder structure...")
for folder in folders:
    folder.mkdir(parents=True, exist_ok=True)
    print(f"  ✓ {folder.relative_to(Path('/content/drive/MyDrive'))}")

print("\n" + "="*70)
print("✓ Folder structure ready!")
print("="*70)
print("\nNext steps:")
print("1. Upload your source face image to:")
print("   MyDrive/DeepLiveCamRemote/source/source.png")
print("2. Upload videos to process to:")
print("   MyDrive/DeepLiveCamRemote/videos/")
print("3. Or upload photos to:")
print("   MyDrive/DeepLiveCamRemote/photos/")
print("\nThen run the next cell to install dependencies.")

```

--------------------------------

### Get Tailscale IP Address

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Optionally retrieves and displays the Colab instance's Tailscale IP address. This is useful for verifying the connection and configuring the remote Windows application.

```python
# @title Get Tailscale IP address (optional - shown above if connected)
import subprocess

result = subprocess.run(["tailscale", "ip", "-4"], capture_output=True, text=True)

if result.returncode == 0 and result.stdout.strip():
    tailscale_ip = result.stdout.strip()
    print("="*70)
    print(f"✓ Your Colab Tailscale IP: {tailscale_ip}")
    print("="*70)
    print(f"\nUse this in your Windows app: http://{tailscale_ip}:7860")
    print("\nNow run the 'Start private API server' cell below.")
else:
    print("Error getting Tailscale IP. Make sure you:")
    print("1. Ran the 'Install Tailscale' cell")
    print("2. Clicked the auth URL in the 'Authenticate Tailscale' cell")
    print("3. Authorized the Colab instance in your Tailscale admin panel")

```

--------------------------------

### Build Standalone Desktop Executable (With Version)

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Builds a standalone desktop executable with a specified version number.

```powershell
# With explicit version
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -Version 0.1.0
```

--------------------------------

### Build Standalone Desktop Executable (Lite)

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Builds a lite version of the standalone desktop executable, excluding live webcam support.

```powershell
# Lite build (smaller, no live webcam)
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -Lite
```

--------------------------------

### Configure Batch Processing Options

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Set up directory paths and processing parameters for batch operations. Adjust variables like input/output directories, frame rates, resolutions, and image enhancement options.

```python
# @title Batch configuration
DRIVE_ROOT = "/content/drive/MyDrive/DeepLiveCamRemote"
SOURCE_FACE = DRIVE_ROOT + "/source/source.png"
INPUT_DIR = DRIVE_ROOT + "/videos"
PHOTO_INPUT_DIR = DRIVE_ROOT + "/photos"
OUTPUT_DIR = DRIVE_ROOT + "/outputs/videos"
PHOTO_OUTPUT_DIR = DRIVE_ROOT + "/outputs/photos"
ZIP_PATH = DRIVE_ROOT + "/outputs/face_swapped_outputs.zip"
SS = 0.0
DURATION = None  # None processes the remainder
MAX_FPS = 30.0
MAX_WIDTH = 420
MANY_FACES = False
OPACITY = 1.0
SHARPNESS = 0.0
MOUTH_MASK_SIZE = 0.0
POISSON_BLEND = False
COLOR_CORRECTION = False
INTERPOLATION_WEIGHT = 0.0
ENHANCER = "none"  # none, gfpgan, gpen256, gpen512
MAPPING_JSON = None  # e.g. "/content/mapping/face_mapping.json"

```

--------------------------------

### Build Standalone Desktop Executable (Single-File)

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Builds a single-file standalone desktop executable.

```powershell
# Single-file executable
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -OneFile
```

--------------------------------

### Build Single-File Executable

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Attempt to create a single-file executable for the desktop application. Note that this may have implications for startup performance and debugging.

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -OneFile
```

--------------------------------

### Build Desktop App with Explicit Version

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Build the desktop application specifying an explicit release version. This ensures consistent versioning for your builds.

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -Version 0.1.0
```

--------------------------------

### Recreate Build Environment

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Use the -RecreateVenv switch to rebuild the virtual environment if a previous build failed or the environment is stale. This ensures a clean environment for the build process.

```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_remote_app.ps1 -RecreateVenv
```

--------------------------------

### Run Desktop Launcher (Windows PowerShell)

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CONTRIBUTING.md

Command to execute the desktop remote controller application on Windows using PowerShell.

```powershell
.\run_windows_remote_app.ps1
```

--------------------------------

### Face Mapping Workflow with Batch CLI

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

This workflow involves scanning input directories and then processing them using a face mapping configuration. Ensure the mapping configuration file is correctly specified.

```bash
python colab_batch.py scan --input-dir /content/in --mapping-dir /content/mapping
```

```bash
python colab_batch.py process \
  --input-dir /content/in \
  --output-dir /content/out \
  --map-config /content/mapping/face_mapping.json
```

--------------------------------

### Desktop App Launchers

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/AGENTS.md

Launch the desktop remote controller application using different script types.

```python
run_windows_remote_app.py
```

```powershell
run_windows_remote_app.ps1
```

```batch
run-windows-remote-app.bat
```

--------------------------------

### Run Batch Processor

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Execute the main batch processing function with configured parameters. This processes videos from `INPUT_DIR` and saves results to `OUTPUT_DIR`, optionally creating a ZIP archive.

```python
# @title Run batch processor
from colab_batch import main
args = ["process", "--input-dir", INPUT_DIR, "--output-dir", OUTPUT_DIR, "--zip-output", ZIP_PATH, "--ss", str(SS), "--max-fps", str(MAX_FPS), "--max-width", str(MAX_WIDTH), "--opacity", str(OPACITY), "--sharpness", str(SHARPNESS), "--mouth-mask-size", str(MOUTH_MASK_SIZE), "--interpolation-weight", str(INTERPOLATION_WEIGHT), "--enhancer", ENHANCER]
if SOURCE_FACE: args += ["--source-face", SOURCE_FACE]
if DURATION is not None: args += ["--duration", str(DURATION)]
if MAPPING_JSON: args += ["--map-config", MAPPING_JSON]
if MANY_FACES: args += ["--many-faces"]
if POISSON_BLEND: args += ["--poisson-blend"]
if COLOR_CORRECTION: args += ["--color-correction"]
exit_code = main(args)
print("Batch exit code:", exit_code)

```

--------------------------------

### Show GPU Information

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Displays information about the available GPUs using the nvidia-smi command. This is helpful for verifying GPU availability and status.

```bash
subprocess.run(["nvidia-smi"], check=False)
```

--------------------------------

### Process Videos with Batch CLI

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Use this command to process video files. Specify source face, input directory, and output directory.

```bash
python colab_batch.py process \
  --source-face /content/drive/MyDrive/DeepLiveCamRemote/source/source.png \
  --input-dir /content/drive/MyDrive/DeepLiveCamRemote/videos \
  --output-dir /content/drive/MyDrive/DeepLiveCamRemote/outputs/videos
```

--------------------------------

### Process Photos with Batch CLI

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/README.md

Use this command to process photo files. Specify source face, input directory, and output directory.

```bash
python colab_batch.py photos \
  --source-face /content/drive/MyDrive/DeepLiveCamRemote/source/source.png \
  --input-dir /content/drive/MyDrive/DeepLiveCamRemote/photos \
  --output-dir /content/drive/MyDrive/DeepLiveCamRemote/outputs/photos
```

--------------------------------

### Set Working Directory and Path

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Configures the script's working directory and adds it to the Python system path. This ensures that local modules can be imported correctly.

```python
# Set working directory and path
os.chdir(WORK_DIR)
if str(WORK_DIR) not in sys.path:
    sys.path.insert(0, str(WORK_DIR))
```

--------------------------------

### Run Batch Face Swap Processing

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/devdocs/features/modern-colab-batch-face-swap.md

Use this command to process a batch of videos. Specify the source face image, input directory, output directory, and an optional ZIP output file.

```bash
python colab_batch.py process \
  --source-face /content/source.png \
  --input-dir /content/in \
  --output-dir /content/out \
  --zip-output /content/face-swapped.zip
```

--------------------------------

### Scan Identities for Mapping

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Optional step to scan identities from input videos and create a mapping JSON file. Use this when different target identities require distinct source faces. Ensure `MAPPING_JSON` is set in the configuration above after running this.

```python
# @title Scan identity gallery (optional)
from colab_batch import main
MAPPING_DIR = "/content/mapping"
main(["scan", "--input-dir", INPUT_DIR, "--mapping-dir", MAPPING_DIR])

```

--------------------------------

### Run Desktop Remote App (Windows)

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Launches the Windows desktop remote application.

```powershell
# Desktop remote app (Windows)
.\run_windows_remote_app.ps1
```

--------------------------------

### Download Face Swapper Model

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Downloads the 'inswapper_128.onnx' model if it's not present or incomplete. It checks file size and handles partial downloads.

```python
import urllib.request
MODEL_URL = "https://huggingface.co/hacksider/deep-live-cam/resolve/main/inswapper_128.onnx"
MODEL_PATH = WORK_DIR / "models" / "inswapper_128.onnx"
MODEL_PATH.parent.mkdir(parents=True, exist_ok=True)

if MODEL_PATH.exists() and MODEL_PATH.stat().st_size > 1024 * 1024:
    print(f"✓ Model already present: {MODEL_PATH.name} ({MODEL_PATH.stat().st_size / 1048576:.1f} MB)")
else:
    MODEL_PATH.unlink(missing_ok=True)
    temporary_model = MODEL_PATH.with_suffix(".onnx.part")
    temporary_model.unlink(missing_ok=True)
    print("Downloading face swapper model...")
    urllib.request.urlretrieve(MODEL_URL, temporary_model)
    if temporary_model.stat().st_size < 1024 * 1024:
        temporary_model.unlink(missing_ok=True)
        raise RuntimeError("Downloaded inswapper_128.onnx is incomplete")
    temporary_model.replace(MODEL_PATH)
    print(f"✓ Model downloaded: {MODEL_PATH.name} ({MODEL_PATH.stat().st_size / 1048576:.1f} MB)")
```

--------------------------------

### Convert Jupyter Notebook to Python

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/AGENTS.md

Use this command to convert a Jupyter notebook back to its markerized Python source format. This is crucial for deterministic diffs and version control. Ensure you are in the repository root and specify the correct input and output file paths. The `--eol lf` flag ensures consistent line endings.

```powershell
python scripts/ipynb_to_py.py \
  .\google-colab\Deep_Live_Cam_Remote_Batch.ipynb \
  .\google-colab\Deep_Live_Cam_Remote_Batch.py \
  --eol lf
```

--------------------------------

### Run Pytest Unit Tests

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CONTRIBUTING.md

Command to execute the unit tests located in the 'tests' directory using pytest. The '-q' flag provides a quieter output.

```powershell
python -m pytest .\tests -q
```

--------------------------------

### Convert Python to Jupyter Notebook

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/AGENTS.md

Use this command to convert a markerized Python script into a Jupyter notebook. Ensure you are in the repository root and specify the correct input and output file paths. The `--eol lf` flag ensures consistent line endings.

```powershell
python scripts/py_to_ipynb.py \
  .\google-colab\Deep_Live_Cam_Remote_Batch.py \
  .\google-colab\Deep_Live_Cam_Remote_Batch.ipynb \
  --eol lf
```

--------------------------------

### Rebuild Colab Notebook from Python Source

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CONTRIBUTING.md

Command to convert a Python script into a Jupyter notebook using the provided utility script. Ensure you are in the repo root.

```powershell
python scripts/py_to_ipynb.py \
  .\google-colab\Deep_Live_Cam_Remote_Batch.py \
  .\google-colab\Deep_Live_Cam_Remote_Batch.ipynb \
  --eol auto
```

--------------------------------

### Convert Colab Notebook back to Python Source

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CONTRIBUTING.md

Command to convert a Jupyter notebook back into a Python script using the provided utility script. Useful if edits were made directly in Colab.

```powershell
python scripts/ipynb_to_py.py \
  .\google-colab\Deep_Live_Cam_Remote_Batch.ipynb \
  .\google-colab\Deep_Live_Cam_Remote_Batch.py \
  --eol auto
```

--------------------------------

### Run Photo Batch Processor

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

This cell executes the photo batch processing functionality. It requires pre-defined variables like PHOTO_INPUT_DIR, PHOTO_OUTPUT_DIR, SOURCE_FACE, etc. Optional flags like --many-faces, --poisson-blend, and --color-correction can be included.

```python
# @title Run photo batch processor
from colab_batch import main
photo_args = ["photos", "--input-dir", PHOTO_INPUT_DIR, "--output-dir", PHOTO_OUTPUT_DIR, "--source-face", SOURCE_FACE, "--opacity", str(OPACITY), "--sharpness", str(SHARPNESS), "--mouth-mask-size", str(MOUTH_MASK_SIZE), "--interpolation-weight", str(INTERPOLATION_WEIGHT), "--enhancer", ENHANCER]
if MANY_FACES: photo_args += ["--many-faces"]
if POISSON_BLEND: photo_args += ["--poisson-blend"]
if COLOR_CORRECTION: photo_args += ["--color-correction"]
exit_code = main(photo_args)
print("Photo batch exit code:", exit_code)

```

--------------------------------

### Run Python Syntax Check and Tests

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Before committing, perform a syntax check on Python files and run pytest for validation. Ensure necessary files are present.

```powershell
# Syntax check
python -m py_compile .\colab_batch.py .\colab_api.py .\windows_app\app.py

# Run tests (if intentionally needed)
python -m pytest .\tests -q

# Manual validation notes required in PR for:
# - UI changes (screenshots)
# - Colab changes (GPU, Drive, Tailscale behavior varies)
# - Batch processing (manifest, resume logic)
```

--------------------------------

### Syntax Check Command

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Performs a syntax check on key Python files in the project. Run this after editing relevant files.

```powershell
# Syntax check (run after editing colab_batch.py, colab_api.py, or windows_app/app.py)
python -m py_compile .\colab_batch.py .\colab_api.py
```

--------------------------------

### Launch Windows Remote App Directly

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/devdocs/plans/2026-06-24-windows-remote-app.md

Alternatively, launch the Windows Remote App directly using the Python executable from the virtual environment.

```powershell
# Or directly
.\.venv\Scripts\python.exe run_windows_remote_app.py
```

--------------------------------

### Colab Notebook Cloning

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/AGENTS.md

The Colab notebook clones the main branch of the Deep-Live-Cam-Remote repository from GitHub.

```git
https://github.com/djebaz/Deep-Live-Cam-Remote.git
```

--------------------------------

### Rebuild Colab Notebook from Python Source

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/CLAUDE.md

Rebuilds the Colab notebook from its corresponding Python source file, ensuring correct line endings.

```powershell
# After editing google-colab/Deep_Live_Cam_Remote_Batch.py, rebuild the notebook
python scripts/py_to_ipynb.py \
  .\google-colab\Deep_Live_Cam_Remote_Batch.py \
  .\google-colab\Deep_Live_Cam_Remote_Batch.ipynb \
  --eol lf
```

--------------------------------

### Verify Critical Files

Source: https://github.com/djebaz/deep-live-cam-remote/blob/main/google-colab/Deep_Live_Cam_Remote_Batch.ipynb

Checks for the existence of essential files required for the Deep Live Cam functionality. Raises an error if any critical files are missing.

```python
# Verify critical files exist
critical_files = ["colab_api.py", "colab_batch.py", "modules/__init__.py"]
missing_files = [f for f in critical_files if not (WORK_DIR / f).exists()]
if missing_files:
    print(f"ERROR: Missing critical files: {missing_files}")
    print(f"Directory contents: {list(WORK_DIR.glob('*'))}")
    raise RuntimeError(f"Repository clone incomplete. Missing: {missing_files}")
```