Virtual Camera Usage

Quick Start

1. Start the Service

python app.py --transport virtualcam --model wav2lip --avatar_id wav2lip256_avatar1

OBS Studio: Add Video Capture Device → OBS Virtual Camera

You need to download and launch OBS Studio first.

2. Open the Control Page

Visit in your browser: http://localhost:8010/virtualcam.html

3. Control the Digital Human

• Enter text and click “Send Text” to make the avatar speak
• Click “Interrupt Playback” to stop speaking
• Or use keyboard shortcuts: Ctrl+Enter to send, Escape to interrupt

4. Use in Other Applications

• Zoom/Teams: Select camera “OBS Virtual Camera”
• To use the newly created virtual camera in Tencent Meeting, follow the steps below:

Feature Overview

Key Features

✅ Background rendering – independent of browser tabs ✅ Automatic audio device – auto-detects the system default speaker ✅ Color correction – automatically converts BGR to RGB ✅ Web console – full HTTP API and page-based control ✅ Real-time monitoring – live display of speaking status and device information

Operating Modes

Usage Guide

Installing and Configuring OBS Studio

Relationship Between OBS and pyvirtualcam

• OBS Studio: Provides the virtual camera device driver
• pyvirtualcam: Python library that pushes video streams to the virtual camera
• Zoom/Teams/Tencent Meeting: Receives video from the virtual camera

Workflow: OBS creates the device → pyvirtualcam pushes video → third-party applications receive the feed

Installation Steps

1. Download and install OBS Studio

   • Official website: https://obsproject.com/

2. Launch OBS Studio once on first use

   • Open OBS Studio for the first time
   • This activates the virtual camera device
   • Close OBS afterwards (the device remains registered in the system)

3. Verify the virtual camera is registered

import pyvirtualcam

try:
    cam = pyvirtualcam.Camera(width=640, height=480, fps=30)
    print(f"Success: {cam.device}")  # Expected output: OBS Virtual Camera
    cam.close()
except Exception as e:
    print(f"Failed: {e}")

Important Notes:

• ✅ OBS only needs to be opened once for initial activation
• ✅ No need to keep OBS open afterward; the device stays available
• ✅ The device persists after system reboot

Prerequisites

# Install Python dependencies after installing OBS Studio
pip install pyvirtualcam pyaudio

Basic Usage

Automatic Audio Device (Recommended)

python app.py --transport virtualcam --model wav2lip --avatar_id wav2lip256_avatar1

Manually Specify the Audio Device

# 1. List available audio devices
python list_audio_devices.py

# 2. Launch with the selected device index
python app.py --transport virtualcam --audio_output_device 25

Using YAML Configuration

# config.yaml
transport: virtualcam
model: wav2lip
avatar_id: wav2lip256_avatar1
audio_output_device: 25  # Optional

python app.py  # Automatically loads config.yaml

Control Page Functions

Visit: http://localhost:8010/virtualcam.html

Modules

Keyboard Shortcuts

HTTP API

# Send text
curl -X POST http://localhost:8010/human \
  -H "Content-Type: application/json" \
  -d '{"sessionid":"0","type":"echo","text":"Hello"}'

# Stop speaking
curl -X POST http://localhost:8010/interrupt_talk \
  -H "Content-Type: application/json" \
  -d '{"sessionid":"0"}'

# Check speaking status
curl -X POST http://localhost:8010/is_speaking \
  -H "Content-Type: application/json" \
  -d '{"sessionid":"0"}'

# Fetch full configuration
curl http://localhost:8010/api/virtualcam/status

Audio Device Configuration

List Devices

python list_audio_devices.py

Sample output:

[Output Devices]:

Device Index: 5
  Name: Speakers (2- Realtek(R) Audio)
  Output Channels: 2

Device Index: 25
  Name: Speakers (2- Realtek(R) Audio)
  Host API: Windows WASAPI

Device Selection Tips

1. Prefer WASAPI devices (usually index 22–27) – low latency
2. DirectSound devices (usually index 15–21) – better compatibility
3. Leave blank to use the system default – automatic selection with minimal setup

Troubleshooting

Q1: No audio output

Troubleshooting Steps:

1. Check startup logs:

[VirtualCam Audio] Using default output device: Speakers (index 25)

2. Confirm the selected index belongs to an output device:

python list_audio_devices.py

3. Manually assign the audio device:

python app.py --transport virtualcam --audio_output_device 25

4. Verify TTS works normally (look for doubao tts Time to first chunk in logs)

Q2: Video tinted blue

Fixed: The code automatically converts color space from BGR to RGB.

Q3: RuntimeError: virtual camera output could not be started

Cause: The virtual camera device is not registered or activated.

Solutions:

1. Confirm OBS Studio is installed: https://obsproject.com/
2. Launch OBS once for initialization
   • Open OBS Studio
   • Close it afterward (device is activated)
3. Verify registration with this script:

import pyvirtualcam
cam = pyvirtualcam.Camera(width=640, height=480, fps=30)
print(cam.device)  # Expected output: OBS Virtual Camera

4. OBS does not need to stay open afterward.

Q4: ModuleNotFoundError: No module named ‘pyaudio’

pip install pyaudio
# or
pip install pipwin && pipwin install pyaudio

Q5: ModuleNotFoundError: No module named ‘pyvirtualcam’

pip install pyvirtualcam

Q6: How to verify the virtual camera works properly?

1. Check startup logs:

VirtualCam output started: OBS Virtual Camera with resolution 1280x720

2. Test inside OBS:
   • Add a “Video Capture Device”
   • Select “OBS Virtual Camera”
   • You should see the digital human video
3. Send a test request:

curl -X POST http://localhost:8010/human -H "Content-Type: application/json" -d '{"sessionid":"0","type":"echo","text":"Test message"}'

Q7: High audio latency

Optimizations:

1. Use WASAPI audio devices for low latency
2. Close other audio-consuming applications
3. Monitor and reduce CPU usage

Technical Architecture

Rendering Pipeline

app.py
  └─> Create Session 0
      └─> render() Thread
          └─> inference() Generates video frames
              └─> process_frames() Pushes frames
                  └─> virtualcam.py
                      ├─> Video: BGR→RGB → pyvirtualcam
                      └─> Audio: PyAudio → Speakers

API Endpoints

Core Files

Summary

The virtual camera feature is fully implemented with the following capabilities:

✅ Core Features – automatic audio detection, color conversion, background rendering ✅ Ease of Use – web dashboard, HTTP API, interactive operation ✅ Stability – independent worker threads, exception handling, resource cleanup

You can now stream your digital human directly into Zoom, Teams, OBS and other video applications!