AvatarStream

This project implements a virtual avatar controlled by MediaPipe Holistic tracking. The Python script tracks body pose and sends the data to Godot, which renders the avatar. The rendered view is then sent back to a virtual camera device, allowing you to use the avatar in meetings (Zoom, Teams, etc.).

• Python 3.8+
• Godot Engine 4.x (Ensure godot is in your PATH, or specify the path when running)

Install the required packages:

pip install -r game/AvatarStream/scripts/python/requirements.txt

1. Install OBS Studio.
2. OBS Studio comes with a Virtual Camera built-in. However, pyvirtualcam usually works with the Unity Capture driver or similar DirectShow filters.
   • Recommended: Install OBS-VirtualCam if the built-in one isn't detected, or better yet, simply use pyvirtualcam which often defaults to OBS Virtual Camera if available.
   • Alternatively, pyvirtualcam on Windows often uses the unity-capture driver.

1. Install v4l2loopback:

   sudo apt install v4l2loopback-dkms

2. Create a virtual device:

   sudo modprobe v4l2loopback devices=1 video_nr=20 card_label="AvatarStream" exclusive_caps=1

   (You might want to add this to /etc/modules or a startup script).

• pyvirtualcam usually relies on OBS Virtual Camera on macOS as well. Ensure OBS is installed and the Virtual Camera is set up.

Use the unified launcher script run.py at the root of the repository:

python run.py

This script will:

1. Check if dependencies are installed.
2. Start the Python tracking script in the background.
3. Launch the Godot project.
4. Clean up processes when you close Godot or press Ctrl+C.

Options:

• --godot-path <path>: Specify the path to your Godot executable if it's not in your PATH.

  python run.py --godot-path /path/to/Godot_v4.x

• Python Scripts: Located in game/AvatarStream/scripts/python/.
• Godot Project: Located in game/AvatarStream/.
• Communication:
  • Python -> Godot: UDP Port 5005 (Pose Data, JSON)
  • Godot -> Python: UDP Port 5006 (Video Frames, MJPEG)

If you export this project to Android or iOS, the Virtual Camera streaming feature is automatically disabled, and it functions as a standalone "Magic Mirror" application.

If you find this repository helpful and would like to support its development, consider making a donation:

Your support helps maintain and improve this collection of development tools and templates. Thank you for contributing to open source!

This project is licensed under the MIT License. See the LICENSE file for details.