random-vc-bg

Generate custom background images for video conferencing platforms (Microsoft Teams, Zoom, etc.) by randomly selecting from your image collection, with optional logo and text overlays.

Features

• Random Selection: Cryptographically secure random selection from your background image collection
• Logo Overlay: Add your logo to backgrounds with automatic dark/light variant selection
• Text Overlay: Display location and date information from image EXIF metadata
• Multi-Platform Support: Output to Microsoft Teams, Zoom, or custom directories
• Image Processing: Automatic resize and aspect ratio preservation
• EXIF Support: Auto-rotation correction and metadata extraction

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

Steps

1. Clone the repository

   git clone https://github.com/yourusername/random-vc-bg.git
   cd random-vc-bg

2. Create a virtual environment

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure the application

   Edit config/random_vc_bg.cfg with your settings:

   [random_vc_bg]
   # Directory containing your background images
   src_dir=/path/to/your/backgrounds
   
   # Directory for processed output images
   output_dir=/path/to/output
   
   # Output platform: teams, zoom, or none
   output_platform=teams
   
   # Platform-specific directories
   teams_dir=~/Library/Application Support/Microsoft/Teams/Backgrounds/Uploads
   zoom_dir=~/Library/Application Support/zoom.us/data/VirtualBkgnd_Custom
   
   # Logo overlay settings
   overlay_logo=True
   logo_file=/path/to/your/logo.png
   logo_file_light=/path/to/your/logo_light.png
   
   # Image dimensions (16:9 recommended)
   fixed_width=1920
   fixed_height=1080
   
   # Logo placement (0.0 to 1.0)
   logo_offset_x=0.1
   logo_offset_y=0.1
   
   # Text overlay from EXIF metadata
   add_text_overlay=False
   text_offset_x=0.95
   text_offset_y=0.05

Usage

Basic Usage

Generate a random background for Teams (using config file defaults):

python -m random_vc_bg.main
# Or if installed via pip:
random-vc-bg

Generate for Zoom instead:

python -m random_vc_bg.main --output zoom

Process a specific image:

python -m random_vc_bg.main --file ~/Pictures/vacation.jpg

Just create output file without copying (useful for testing):

python -m random_vc_bg.main --output none

Use a custom config file:

python -m random_vc_bg.main --cfg config/my_custom.cfg

Command Line Options

python -m random_vc_bg.main --help

Available options:

• --cfg CONFIG_FILE - Path to configuration file (default: config/random_vc_bg.cfg)
• --file IMAGE_FILE - Process a specific image instead of random selection
• --output {teams,zoom,none} - Output platform (overrides config file)

How It Works

The script follows these steps:

1. Setup: Load configuration and parse command line arguments
2. Select Input: Choose a random image from src_dir (or use --file argument)
3. Analyze: Extract EXIF metadata (GPS coordinates, date, orientation)
4. Process: Create output image with:
   • EXIF orientation correction
   • Resize to specified dimensions
   • Logo overlay (if enabled)
   • Text overlay with location and date (if enabled)
5. Output: Save processed image with timestamp filename
6. Copy: Copy to Teams or Zoom directory (based on output_platform setting)

Configuration Reference

All configuration options in config/random_vc_bg.cfg:

Option	Description	Example
src_dir	Source directory for background images	/home/user/Pictures/Backgrounds
output_dir	Directory for processed images	/home/user/tmp
output_platform	Platform to copy to: teams, zoom, or none	teams
teams_dir	Microsoft Teams backgrounds folder	See platform-specific paths below
zoom_dir	Zoom virtual backgrounds folder	See platform-specific paths below
overlay_logo	Enable logo overlay	True or False
logo_file	Logo for light backgrounds (PNG with transparency)	/home/user/logos/logo.png
logo_file_light	Logo for dark backgrounds	/home/user/logos/logo_light.png
fixed_width	Output image width	1920
fixed_height	Output image height	1080
logo_offset_x	Logo horizontal position (0.0-1.0)	0.1
logo_offset_y	Logo vertical position (0.0-1.0)	0.1
add_text_overlay	Add location/date text from EXIF	True or False
text_offset_x	Text horizontal position (0.0-1.0)	0.95
text_offset_y	Text vertical position (0.0-1.0)	0.05

Platform-Specific Directories

macOS:

• Teams: ~/Library/Application Support/Microsoft/Teams/Backgrounds/Uploads
• Zoom: ~/Library/Application Support/zoom.us/data/VirtualBkgnd_Custom

Windows:

• Teams: %APPDATA%\Microsoft\Teams\Backgrounds\Uploads
• Zoom: %APPDATA%\Zoom\data\VirtualBkgnd_Custom

Linux:

• Teams: ~/.config/Microsoft/Microsoft Teams/Backgrounds/Uploads
• Zoom: ~/.zoom/data/VirtualBkgnd_Custom

Automated Scheduling

Run the script automatically every day to get a fresh background.

macOS (launchd)

1. Edit the plist file at config/vc_bg.plist with your paths:

   <key>ProgramArguments</key>
   <array>
       <string>/path/to/random-vc-bg/.venv/bin/python</string>
       <string>-m</string>
       <string>random_vc_bg.main</string>
       <string>--cfg</string>
       <string>/path/to/random-vc-bg/config/random_vc_bg.cfg</string>
   </array>

2. Set the time (default is 7:35 AM):

   <key>Hour</key>
   <integer>07</integer>
   <key>Minute</key>
   <integer>35</integer>

3. Load the agent:

   cp config/vc_bg.plist ~/Library/LaunchAgents/
   launchctl load ~/Library/LaunchAgents/vc_bg.plist

Linux (systemd timer)

1. Create systemd service at ~/.config/systemd/user/random-vc-bg.service:

   [Unit]
   Description=Random Video Conference Background Generator
   
   [Service]
   Type=oneshot
   ExecStart=/path/to/random-vc-bg/.venv/bin/python -m random_vc_bg.main
   WorkingDirectory=/path/to/random-vc-bg

2. Create systemd timer at ~/.config/systemd/user/random-vc-bg.timer:

   [Unit]
   Description=Run Random VC Background daily
   
   [Timer]
   OnCalendar=daily
   Persistent=true
   
   [Install]
   WantedBy=timers.target

3. Enable and start:

   systemctl --user enable --now random-vc-bg.timer

Windows (Task Scheduler)

1. Open Task Scheduler and create a new task
2. Set trigger to run daily at your preferred time
3. Set action to run:

   Program: C:\path\to\random-vc-bg\.venv\Scripts\python.exe
   Arguments: -m random_vc_bg.main
   

Development

Running Tests

Run the test suite from the project root:

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run all tests
python -m unittest discover test

# Run with verbose output
python -m unittest discover test -v

All 19 tests should pass:

.....................
----------------------------------------------------------------------
Ran 19 tests in 0.5s

OK

LICENSE

MIT License