🎥 VirtualCam Studio — Turn Any Video, Image or GIF into a Live Virtual Webcam

A free, open-source Windows desktop app that streams images, videos, and GIFs to any video-call app as a live, effect-processed virtual webcam — 100% local processing, no cloud, no subscription, no data leaving your machine.

Features · Why This Project · Quick Start · Installation · Usage · Use Cases · Roadmap · FAQ

The actual app running: playlist, live preview (LIVE badge, 30 FPS), and the real-time effects panel.

---

📌 Repository Audit Summary

Verified directly against the source in this repository — nothing below is assumed or extrapolated.

• What it is: a Windows desktop GUI application (Python + CustomTkinter) that plays a media playlist, runs every frame through a real-time OpenCV effects pipeline, and streams the result to the OBS Virtual Camera device via pyvirtualcam.
• What it is not: it has no web server, no REST/GraphQL API, no database, no CLI flags, no cloud component, and no AI/ML models in the active code path (a mediapipe dependency exists but is commented out and unused).
• Dependencies present but unused in code today: moviepy, ffmpeg-python, mediapipe (listed in requirements.txt, not imported anywhere in core/, gui/, effects/, or media/).
• No secrets, API keys, tokens, or credentials were found anywhere in the codebase, configuration, or logs.
• No LICENSE file currently exists in the repository.
• No .gitignore, CONTRIBUTING.md, SECURITY.md, issue templates, PR template, or GitHub Actions workflows currently exist.
• This directory is not yet a Git repository (git status returns "not a git repository") and is not yet connected to GitHub — every discoverability/growth recommendation below assumes these setup steps happen first.
• One real screenshot was found and is now used as the hero image: docs/screenshots/main-window.png.

---

💡 The Problem & The Value Proposition

Showing anything other than your raw camera feed on a video call — a looping product demo, a branded holding slide, a promo clip — normally means building an OBS scene with sources, transforms, and filters just to loop one file.

VirtualCam Studio removes that friction: load your media, dial in the look with real-time effects, click Start Webcam, and any app that can select a camera device — Zoom, Google Meet, Microsoft Teams, Discord, browser-based calls, or OBS itself — sees your processed output as a normal webcam.

✨ Key Features

(Every item below is directly traceable to a function, class, or UI control in the current codebase.)

🎞️ Playlist & Media

Feature	Details
Multi-format playlist	Images (.jpg .jpeg .png .webp .bmp), Videos (.mp4 .mov .avi .mkv .wmv .flv .ts), GIFs (.gif)
Auto-generated thumbnails	Every playlist item gets a thumbnail (video thumbnails sampled at 10% of duration)
Loop & Shuffle	One-click toggles for looped and shuffled playback
Configurable image hold time	1–30 seconds per static image before auto-advancing
Seamless video looping	Videos rewind automatically at end-of-file
Playlist management	Add, remove, and clear items from the sidebar

🔄 Transform Effects

Zoom (0.1×–5×, centered) · Rotation (±180°) · Position D-pad with fine-tune sliders and selectable step size (1/5/10/50 px) · Horizontal/vertical flip · Side-by-side mirror mode · Independent edge cropping (left/right/top/bottom)

🎨 Color & Tone

Brightness · Contrast · Saturation · Sharpness · Gaussian blur · Opacity blending · Independent Red/Green/Blue channel gains

✨ Style Filters

Grayscale and Sepia (mutually exclusive, applied after color grading)

💬 Overlay

On-screen text watermark/caption with a drop shadow, positionable in any of the four corners

🖥️ Output & Performance

Selectable output resolution (HD / FHD / QHD / 4K) and frame rate (24 / 30 / 60 fps) · Live FPS, CPU, and RAM readout · Letterboxed resizing that always preserves aspect ratio

💾 Presets

Save and load the entire effects configuration as a JSON preset — instantly recall your "look" for the next stream

📷 Virtual Camera Output

Streams the fully-processed frame to the OBS Virtual Camera driver via pyvirtualcam. If the driver isn't installed, the app degrades gracefully to preview-only mode instead of crashing.

🖼️ Live Preview

In-app real-time preview panel plus a dedicated fullscreen preview window (F11, Esc to exit).

📋 Full effects parameter reference

Parameter	Range	Default	Description
zoom	0.1 – 5.0	1.0	Centered zoom level
rotation	−180° – 180°	0	Rotation angle
pos_x	−800 – 800 px	0	Horizontal pan
pos_y	−600 – 600 px	0	Vertical pan
flip_h / flip_v	bool	false	Horizontal / vertical flip
mirror_mode	bool	false	Side-by-side mirror (overrides flip)
brightness	−100 – 100	0	Brightness offset
contrast	0.5 – 3.0	1.0	Contrast multiplier
saturation	0.0 – 3.0	1.0	HSV saturation scale
sharpness	0 – 10	0	Unsharp-mask strength
blur	0 – 20	0	Gaussian blur kernel radius
opacity	0.0 – 1.0	1.0	Blend with black canvas
red_gain / green_gain / blue_gain	0.0 – 3.0	1.0	Per-channel color gain
grayscale / sepia	bool	false	Style filter (sepia takes priority)
crop_left/right/top/bottom	0 – 400 px	0	Edge crop, applied first
watermark_text	string	""	Overlay caption text
watermark_enabled	bool	false	Toggle the overlay
watermark_position	top-left/top-right/bottom-left/bottom-right	bottom-right	Overlay corner

---

🏆 Why Choose VirtualCam Studio?

Reasons grounded in what the code actually does, not marketing claims:

• Purpose-built, not a side feature. Unlike general broadcasting suites where "loop a file as my webcam" is one buried feature among hundreds, this app's entire UI is built around that one workflow — playlist → effects → webcam, in three clicks.
• A real, ordered effects pipeline, not a filter list. effects/pipeline.py applies crop → flip/mirror → zoom → pan → rotation → color/tone → style filter → blur/sharpen → opacity → watermark in a fixed, predictable order on every single frame.
• Fails safe, not silently. If the OBS Virtual Camera driver isn't installed, WebcamEngine automatically falls back to preview-only mode (core/webcam_engine.py) instead of crashing — you still see your effects working.
• Genuinely local. A full read of every source file found zero network calls anywhere in the codebase. Nothing you load or configure leaves your machine.
• Ships with its own build pipeline. build.py auto-detects local packages and data folders and generates a working PyInstaller spec — including two extra hardening options (Nuitka native compilation, PyArmor AES-256 source encryption) for anyone distributing the compiled app.

---

🧭 How It Works

flowchart LR
    A["🎞️ Playlist\nImages · Videos · GIFs"] --> B["MediaManager\nframe reader"]
    B --> C["Renderer"]
    C --> D["EffectsPipeline\ncrop · zoom · color · filters · watermark"]
    D --> E["WebcamEngine\nrender loop thread"]
    D --> P["🖥️ Live Preview Panel"]
    E --> F["pyvirtualcam"]
    F --> G["OBS Virtual Camera driver"]
    G --> H["Zoom · Meet · Teams · Discord · OBS · any camera app"]

Loading

Every frame passes through a fixed, ordered pipeline before reaching the virtual camera or the preview panel:

flowchart TD
    S["Raw Frame"] --> P1["1 · Crop"]
    P1 --> P2["2 · Flip / Mirror"]
    P2 --> P3["3 · Zoom"]
    P3 --> P4["4 · Position / Pan"]
    P4 --> P5["5 · Rotation"]
    P5 --> P6["6 · Brightness · Contrast · Saturation · RGB Gains"]
    P6 --> P7["7 · Grayscale / Sepia"]
    P7 --> P8["8 · Blur / Sharpen"]
    P8 --> P9["9 · Opacity"]
    P9 --> P10["10 · Watermark"]
    P10 --> O["Resize → Output Frame"]

Loading

The render loop runs on a dedicated background thread so the GUI stays responsive; FPS/CPU/RAM are sampled once per second and shown live in the preview bar.

---

⚡ Quick Start

The fastest path from clone to a live virtual webcam:

git clone https://github.com/<your-username>/virtualcam-studio.git
cd virtualcam-studio
pip install -r requirements.txt
python main.py

Then, inside the app: 🖼 Images / 🎬 Videos → ▶ Play → 📷 Start Webcam. Select OBS Virtual Camera as the camera in any call app.

First time? You need the OBS Virtual Camera driver registered once — see Installation & Setup below.

---

✅ Prerequisites

Requirement	Notes
Windows 10/11	Primary, tested target — runtime data is written to %APPDATA%\VirtualWebcam and the app ships as a .exe
Python 3.10+	Only required if running from source
OBS Studio (free)	Needed once, to register the OBS Virtual Camera driver used by pyvirtualcam

---

🚀 Installation & Setup

1. Run from source

git clone https://github.com/<your-username>/virtualcam-studio.git
cd virtualcam-studio
pip install -r requirements.txt
python main.py

The app checks for required packages on startup and prints a pip install hint if anything's missing, instead of crashing silently.

2. Register the virtual camera driver (one-time)

1. Install OBS Studio from obsproject.com
2. Open OBS → Tools → Start Virtual Camera (once)
3. Close OBS — the driver stays registered on your system
4. Launch VirtualCam Studio and click "📷 Start Webcam"

If the driver isn't detected, VirtualCam Studio automatically falls back to preview-only mode and shows setup instructions instead of failing silently.

📦 Building a standalone .exe

VirtualCam Studio ships with an interactive build script that auto-detects local packages, data folders, and hidden imports:

python build.py

Option	Toolchain	Output size	Notes
1	PyInstaller	~45 MB	Stable, fastest build
2	Nuitka	~50 MB	Compiles to native C — harder to reverse-engineer
3	PyArmor + PyInstaller	~45 MB	AES-256 source encryption before packaging

Output is written to dist/.

---

⚙️ Configuration & Environment Variables

VirtualCam Studio requires no environment variables, API keys, or secrets — it is a fully local, offline desktop application. The only persisted configuration is:

• Effect presets — plain JSON files you save/load via the 💾 Presets panel, stored under presets/
• Logs — logs/app.log
• Compiled-app data — when running as a built .exe, writable data (logs, cache, presets) is redirected to %APPDATA%\VirtualWebcam automatically

Example preset (matches the exact fields written by the app):

{
  "zoom": 1.2,
  "rotation": 0,
  "brightness": 10,
  "contrast": 1.1,
  "saturation": 1.0,
  "sharpness": 0.0,
  "blur": 0,
  "opacity": 1.0,
  "flip_h": false,
  "flip_v": false,
  "grayscale": false,
  "sepia": false,
  "mirror_mode": false,
  "red_gain": 1.0,
  "green_gain": 1.0,
  "blue_gain": 1.0,
  "crop_left": 0,
  "crop_right": 0,
  "crop_top": 0,
  "crop_bottom": 0,
  "watermark_text": "LIVE",
  "watermark_enabled": true
}

Output settings

Resolution	Pixels	Frame rates
HD	1280 × 720	24 / 30 / 60 fps
FHD	1920 × 1080	24 / 30 / 60 fps
QHD	2560 × 1440	24 / 30 / 60 fps
4K	3840 × 2160	24 / 30 / 60 fps

---

🖥️ Usage Guide

1. Launch the app (python main.py or the built .exe)
2. Click 🖼 Images or 🎬 Videos to add files to the playlist (multi-select supported)
3. Press ▶ Play — the live preview panel starts rendering immediately
4. Fine-tune the look in the Effects & Position panel — zoom, pan with the D-pad, color grade, apply filters, add a watermark
5. Click 📷 Start Webcam — your processed feed is now available as OBS Virtual Camera to any app
6. In Zoom / Meet / Teams / Discord → camera settings → select OBS Virtual Camera
7. Save the configuration as a preset (💾 Save) to reload it instantly next time

⌨️ Keyboard shortcuts

Key	Action
Space	Play / Pause
→	Next media item
←	Previous media item
Delete	Remove selected playlist item
F11	Toggle fullscreen preview
Esc	Exit fullscreen preview

API / CLI / SDK / Webhooks

VirtualCam Studio is currently a GUI-only desktop application. It does not expose a command-line interface, REST API, SDK, or webhook integrations — main.py takes no arguments and there is no server component in this codebase. If you need programmatic control, that would be a new feature (see Roadmap).

---

🎯 Use Cases & Who It's For

Grounded in what the app actually supports (looping media + real-time effects + a virtual camera device) rather than assumed scenarios:

Who	What they'd use it for
Streamers & content creators	Loop a "Be Right Back" graphic or branded intro without leaving OBS scene management to chance
Webinar & virtual event hosts	Show a branded holding slide or looping sponsor video before the live segment starts
Sales & demo teams	Play a looping product video as their "camera" during a call instead of screen-sharing
Educators & trainers	Loop instructional GIFs or diagrams as webcam input for remote lessons
Developers testing overlays	Preview watermark/branding placement and color grading before going live in OBS

---

📁 Project Structure

virtualcam-studio/
├── main.py                  # Entry point — works from source or as a compiled .exe
├── build.py                 # Interactive EXE builder (PyInstaller / Nuitka / PyArmor)
├── requirements.txt
├── core/
│   ├── app_state.py         # Central thread-safe application state
│   ├── media_manager.py     # Playlist + frame-reader lifecycle
│   ├── renderer.py          # Effects → resize render step
│   └── webcam_engine.py     # Render loop thread + pyvirtualcam output
├── effects/
│   └── pipeline.py          # Every frame effect + the fixed pipeline order
├── media/
│   └── loader.py            # Image / Video / GIF readers
├── gui/
│   ├── main_window.py       # App shell, layout, hotkeys
│   ├── sidebar.py           # Playlist panel with thumbnails
│   ├── preview.py           # Live preview canvas + stats bar
│   ├── controls.py          # Transport bar (play/stop/webcam/fullscreen)
│   └── effects_panel.py     # Effects sliders, D-pad, presets
├── utils/
│   └── helpers.py           # Frame resize/convert utilities
├── presets/                 # Saved effect presets (JSON)
├── assets/icons/            # App icon, picked up automatically by build.py (currently empty)
├── docs/screenshots/        # README screenshots
└── logs/                    # Runtime log file (app.log)

---

🧱 Tech Stack

Layer	Technology
GUI	CustomTkinter (Tkinter)
Image & video processing	OpenCV, NumPy
Image I/O & thumbnails	Pillow
Virtual camera output	pyvirtualcam (OBS Virtual Camera driver)
System stats	psutil
Packaging	PyInstaller / Nuitka / PyArmor, orchestrated by build.py
Language	Python 3.10+

moviepy and ffmpeg-python are included in requirements.txt for future video-export tooling but aren't wired into the current render pipeline yet — see Roadmap.

---

📦 Deployment

VirtualCam Studio is a desktop application, not a hosted service — there is nothing here to deploy to a server. "Deployment" means producing a distributable Windows executable via python build.py (see Installation & Setup) and sharing the resulting dist/*.exe with your users. No Docker, CI/CD, or cloud infrastructure currently exists in this repository.

---

📸 Screenshots & Demo

A short GIF/video demo of the playlist → effects → webcam workflow would be a strong addition here — see Roadmap.

---

🗺️ Roadmap

Ideas that are not implemented yet — tracked openly so contributors know where to start:

• macOS / Linux packaging (pyvirtualcam already supports both platforms; current build tooling targets Windows only)
• Video export/trimming using the already-bundled moviepy / ffmpeg-python dependencies
• Face detection / auto-framing (a mediapipe dependency is scaffolded but currently disabled)
• Drag-to-reorder playlist items
• Bundled default app icon (assets/icons/ is currently empty)
• One-click virtual-camera driver installer to replace the manual OBS Studio step
• A short animated GIF/video demo for the README
• Optional CLI for scripted/headless playback

Have another idea? Open an issue — contributions and discussion are welcome.

---

❓ FAQ

What is a "virtual webcam" and why would I need one?

A virtual webcam is a system camera device that any app can select, but whose video comes from software instead of a physical camera. VirtualCam Studio uses this to let you present a video, image, or GIF as your webcam feed in any call or streaming app.

Which apps can I use this with?

Any application that lets you pick a camera source — Zoom, Google Meet, Microsoft Teams, Discord, browser-based video calls, and OBS Studio itself — since OBS Virtual Camera registers as a standard system camera device.

Do I need to keep OBS Studio open while using VirtualCam Studio?

No. Open OBS once and click Start Virtual Camera to register the driver on your system, then close OBS entirely — VirtualCam Studio talks to the driver directly afterward.

My virtual camera doesn't show up in my video-call app.

The OBS Virtual Camera driver likely isn't registered yet. Reinstall OBS Studio, open it, and run Tools → Start Virtual Camera once. Until the driver is detected, VirtualCam Studio automatically runs in preview-only mode instead of failing.

Does this work on macOS or Linux?

The core Python/OpenCV codebase and pyvirtualcam both support other platforms, but the current packaging (build.py, %APPDATA% paths) targets Windows specifically. Cross-platform packaging is on the roadmap.

Is any of my data uploaded anywhere?

No. There is no network code anywhere in the project — media files, effect presets, and logs are all read from and written to your local disk only.

Can I protect my source code when I share a built app?

Yes — build.py includes a PyArmor + PyInstaller option that AES-256 encrypts your source before bundling it into the final executable.

Does it have a CLI or API?

Not currently. It's a GUI-only application with no command-line arguments, REST API, or SDK. See Roadmap.

---

🔒 Security

• 100% local processing — a full source read found no network requests anywhere in the codebase; nothing is uploaded or tracked.
• Media, presets, and logs stay on your machine (logs/app.log, presets/*.json).
• Optional AES-256 source encryption when building distributable binaries via the PyArmor build option.
• No SECURITY.md currently exists. Until one is added, please report security issues by opening a GitHub issue marked clearly as a security concern, or via a private GitHub Security Advisory if enabled on the repository — avoid posting exploit details in public issues.

---

🤝 Contributing

Contributions are welcome — this project benefits from real-world testing across different Windows setups and OBS versions.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-improvement
3. Make your changes and test them by actually running python main.py
4. Commit with a clear message and open a pull request describing the why, not just the what

No CONTRIBUTING.md exists yet — the steps above are the de facto process until one is added (see recommendations below).

---

📄 License

This project is intended to be released under the MIT License — a permissive license well suited to an open-source desktop tool. No LICENSE file currently exists in the repository — add one at the root to make this legally effective (see choosealicense.com/licenses/mit).

---

💬 Support & Community

• 🐛 Found a bug or have a feature request? Open an issue.
• ⭐ Star this repo if VirtualCam Studio saves you from fumbling with OBS scenes every stream — it helps other people find it too.
• 🍴 Fork it and adapt it for your own workflow.
• 🔔 Watch releases to hear about new features first.
• 📣 Share it with anyone who streams, presents, or hosts calls for a living.

(No Discord/forum currently exists for this project — GitHub Issues and Discussions are the primary channels once enabled.)

---

Ready to turn any video into a live webcam feed?
git clone it, pip install -r requirements.txt, and hit Start Webcam.